{"id":24552029,"url":"https://github.com/mlabs-haskell/bot-plutus-interface","last_synced_at":"2025-04-15T22:20:29.595Z","repository":{"id":37089134,"uuid":"418483330","full_name":"mlabs-haskell/bot-plutus-interface","owner":"mlabs-haskell","description":"Unofficial PAB implementation","archived":false,"fork":false,"pushed_at":"2023-05-05T18:32:42.000Z","size":1339,"stargazers_count":21,"open_issues_count":15,"forks_count":11,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-29T02:04:21.707Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlabs-haskell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-10-18T12:06:47.000Z","updated_at":"2023-07-24T19:12:09.000Z","dependencies_parsed_at":"2023-01-29T13:33:07.581Z","dependency_job_id":"f2bfdb27-e7ea-4e79-b04d-4f4595ef7b15","html_url":"https://github.com/mlabs-haskell/bot-plutus-interface","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fbot-plutus-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fbot-plutus-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fbot-plutus-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fbot-plutus-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlabs-haskell","download_url":"https://codeload.github.com/mlabs-haskell/bot-plutus-interface/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249161911,"owners_count":21222568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-23T01:19:49.314Z","updated_at":"2025-04-15T22:20:29.579Z","avatar_url":"https://github.com/mlabs-haskell.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bot Plutus Interface\n**NOTE: This library has been deprecated and is no longer being actively developed by MLabs.**\n\nThis is a custom implementation of the PAB as the official one is not ready yet.\nThis PAB is not feature complete, and not fully tested with all use cases, so please use it with care!\n\nDisclaimer: this project is still a work in progress, with a few missing features. We don't take any responsibility for any losses, only use it at your own risk!\n\nSupported features:\n\n- query utxos at an address (utxosAt)\n- evaluate Contract (not all features implemented, see the rest of this list for details)\n- pre balance tx (adding minimum amount of tx inputs based on fee and tx output value, balancing non ada outputs)\n- mint tokens, and send them to arbitrary address(es)\n- redeem utxos from validator scripts, using the correct datum and redeemer (scripts, datums and redeemers are persisted in files for now)\n- use validity time ranges\n- waiting for slots\n\nUnsupported/In development\n\n- wallet integration\n- handling on-chain events (utxo set change, etc.)\n\n## How to use this?\n\nWiring up your own contract is pretty much the same as with the official PAB:\n\n1. Define your endpoints for the PAB\n\n```haskell\ndata MyContracts\n  = Send SendParams\n  | Collect CollectParams\n  deriving stock\n    (Show, Generic)\n  deriving anyclass\n    (FromJSON, ToJSON)\n```\n\n2. Define a HasDefinitions instance for the endpoints\n\n```haskell\nimport BotPlutusInterface.Types (HasDefinitions (..), SomeBuiltin (..), endpointsToSchemas)\nimport Playground.Types (FunctionSchema)\nimport Schema (FormSchema)\n\ninstance HasDefinitions MyContracts where\n  getDefinitions :: [MyContract]\n  getDefinitions = []\n\n  getSchema :: MyContracts -\u003e [FunctionSchema FormSchema]\n  getSchema = \\case\n    Send _ -\u003e endpointsToSchemas @MyContractSchema\n    Collect _ -\u003e endpointsToSchemas @MyContractSchema\n\n  getContract :: (MyContracts -\u003e SomeBuiltin)\n  getContract = \\case\n    Send params -\u003e\n      SomeBuiltin $\n        MyContract.contract params\n    Collect params -\u003e\n      SomeBuiltin $\n        MyContract.contract params\n```\n\n3. Write your main entrypoint for the application and the configuration file\n\n```haskell\nimport Prelude\n\nmain :: IO ()\nmain = do\n  pabConf \u003c-\n    either error id\n      \u003c$\u003e BotPlutusInterface.loadPABConfig \"./pabConfig.value\"\n  BotPlutusInterface.runPAB @MyContracts pabConf\n```\n\nConfiguration format (example: \u003cexamples/plutus-game/pabConfig.value\u003e):\n\n```console\n$ cabal repl --disable-optimisation --repl-options -Wwarn\n...\nBotPlutusInterface\u003e :m Prelude\n...\nPrelude\u003e :l BotPlutusInterface.Config\n...\nPrelude BotPlutusInterface.Config\u003e putStrLn docPABConfig\nTop-level configuration file fields:\n    cliLocation: `local` or destination text\n        calling the cli through ssh when set to destination (default:\n        local)\n    chainIndexUrl: url text\n         (default: \"http://localhost:9083\")\n    networkId: case insensitive `mainnet` atom or 32-bit unsigned integral number\n         (default: 42)\n    scriptFileDir: path text\n        Directory name of the script and data files (default:\n        \"./result-scripts\")\n    signingKeyFileDir: path text\n        Directory name of the signing key files (default: \"./signing-keys\")\n    txFileDir: path text\n        Directory name of the transaction files (default: \"./txs\")\n    metadataDir: path text\n        Directory name of metadata files (default: \"/metadata\")\n    protocolParamsFile: filepath text\n        Protocol params file location relative to the cardano-cli working\n        directory (needed for the cli) in JSON format.  (default:\n        \"./protocol.json\")\n    dryRun: `true` or `false`\n        Dry run mode will build the tx, but skip the submit step (default:\n        true)\n    logLevel: `error` or `warn` or `notice` or `info` or `debug`\n         (default: info)\n    ownPubKeyHash: PubKeyHash text\n         (default: \"\")\n    ownStakePubKeyHash: case insensitive `nothing` atom or StakePubKeyHash text\n         (default: nothing)\n    tipPollingInterval: non-negative integral number\n         (default: 10000000)\n    port: port non-negative integral number\n         (default: 9080)\n    enableTxEndpoint: `true` or `false`\n         (default: false)\n    collectStats: `true` or `false`\n        Save some stats during contract run (only transactions execution\n        budgets supported atm) (default: false)\n    collectLogs: `true` or `false`\n        Save logs from contract execution: pab request logs and contract\n        logs (default: false)\n    budgetMultiplier: rational multiplier in form `1` or `1 % 2`\n         (default: 1)\n```\n\nTo run the fake PAB, you need to prepare a few more things:\n\n4. Save the protocol params file to the root folder of your project using the cardano-cli\n\n```bash\ncardano-cli query protocol-parameters --testnet-magic 42 --out-file protocol.json\n```\n\n5. Create a `signing-keys` folder under your projects root with the necessary signig key file(s).\n   The files should be named in the following format: `signing-key-PUBKEYHASHHEX.skey` and `verification-key-PUBKEYHASHHEX.vkey`\n\nUse the cardano-cli to find out the pub key hash for your key:\n\n```bash\ncardano-cli address key-hash --verification-key-file VERIFICATION_KEY.vkey\n```\n\n## How does this work and how it is structured?\n\nThe fake PAB consists of the following modules:\n\n- **BotPlutusInterface** main entry point\n- **BotPlutusInterface.Server** Servant server, handling http endpoint calls and websockets\n- **BotPlutusInterface.Config** load/save PAB configuration file\n- **BotPlutusInterface.Contract** handling contract effects by creating the necessary files and calling cardano-cli commands (a few effects are mocked)\n- **BotPlutusInterface.Balance** doing some preparations so the cli can process the rest (non-ada asset balancing, addig tx inputs, adding minimum lovelaces, add signatories)\n- **BotPlutusInterface.CardanoCLI** wrappers for cardano-cli commands\n- For development purposes, I created an ssh wrapper, so I can call relay these commands through an ssh connection. This is not nice, unsafe, and pretty slow, avoid using it if you can.\n- **BotPlutusInterface.UtxoParser** parse the output of the `cardano-cli query utxo` command\n- **BotPlutusInterface.Files** functions for handling script, datum and redeemer files\n- **BotPlutusInterface.Types** configuration for the fake pab\n- **BotPlutusInterface.Balance** prepare a transaction before sending to the cli for balancing. This includes:\n  - adding tx inputs to cover fees and outputs\n  - adding collaterals,\n  - modifying tx outs to contain the minimum amount of lovelaces\n  - balancing non ada outputs\n\n## Collateral handling\n\nCurrent version handles collateral under the hood.\n\nBefore contract being executed, single transaction submitted to create collateral UTxO at \"own\" address. Default amount for collateral UTxO is 10 Ada. It also can be set via config.\n\nBPI identifies collateral UTxO by its value. If \"own\" address already has UTxO with amount set in config, this UTxO will be used as collateral. UTxO that was picked as collateral is stored in memory, so each time BPI will use same UTxO for collateral. Also, collateral is not returned among other UTxOs inside `Contract` monad, e.g. from eDSL functions like `utxosAt`. So it is safe to use such functions without the risk of consuming collateral by accident.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fbot-plutus-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlabs-haskell%2Fbot-plutus-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fbot-plutus-interface/lists"}