{"id":24551933,"url":"https://github.com/mlabs-haskell/plutus-partial-tx","last_synced_at":"2025-04-15T22:19:58.074Z","repository":{"id":49522271,"uuid":"512859549","full_name":"mlabs-haskell/plutus-partial-tx","owner":"mlabs-haskell","description":"Effortless BPI + Lucid production PAB that reuses Haskell Contracts","archived":false,"fork":false,"pushed_at":"2023-05-03T06:08:13.000Z","size":328,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T16:46:31.307Z","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":"mit","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}},"created_at":"2022-07-11T18:00:18.000Z","updated_at":"2023-05-03T06:06:43.000Z","dependencies_parsed_at":"2023-01-21T15:48:22.096Z","dependency_job_id":null,"html_url":"https://github.com/mlabs-haskell/plutus-partial-tx","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%2Fplutus-partial-tx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutus-partial-tx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutus-partial-tx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutus-partial-tx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlabs-haskell","download_url":"https://codeload.github.com/mlabs-haskell/plutus-partial-tx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249161735,"owners_count":21222539,"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:28.105Z","updated_at":"2025-04-15T22:19:58.052Z","avatar_url":"https://github.com/mlabs-haskell.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"**DEPRECATED**: plutus-apps and any PAB based on it is a dead end.\n\nConsider using [Atlas](https://github.com/geniusyield/atlas), a proper, production capable, and actively maintained (as of writing) Haskell PAB.\n\nConsider using [CTL](https://github.com/Plutonomicon/cardano-transaction-lib) or [Lucid](https://github.com/spacebudz/lucid) instead for non-Haskell solutions.\n\n# Plutus Partial Tx\n\nA library to export partial transactions (unbalanced, unsigned) and get them\nsigned and submitted by a frontend PAB. This enables you to re-use your regular\nHaskell `Contract`s while still having a deployment solution for production -\neffortlessly.\n\n# Highlights\n\n- Write all your contracts in the familiar `Contract` monad.\n- Leverage excellent Haskell-side testing solutions for your `Contract`s, using\n  [Plutip](https://github.com/mlabs-haskell/plutip), Contract models etc.\n- Run your contracts on the testnet (and mainnet!) utilizing a lightweight\n  frontend PAB (i.e [Lucid](https://github.com/Berry-Pool/lucid)) - without ever\n  having to rewrite your contracts or any extra logic. Simply re-use your\n  Haskell contracts, call `.sign` and `.submit` on the frontend.\n- Extremely lightweight, easy to test in local development environment. If using\n  [bot-plutus-interface](https://github.com/mlabs-haskell/bot-plutus-interface)\n  (BPI), all you need is `cardano-node` and `plutus-chain-index`.\n\n# Usage\n\n## Backend environment setup\n1. Add the proper versions of `bot-plutus-interface` and `plutus-partial-tx` as dependencies to your project.\n2. Have the proper versions (usually latest) of `cardano-node`, `cardano-cli`, and a corresponding version (same one used by bot-plutus-interface) of `plutus-chain-index` in `$PATH`.\n3. Have `cardano-node` and `chain-index` running in the background and properly synced. You may simply copy over [the provided `testnet` directory](./testnet/) and use the scripts there to set up for testnet. Remember to create the `db` directory inside `testnet/chain-index` first!\n\n   Usually, if using nix, `plutus-chain-index` is already included by BPI. All you have to do is make it available in the nix shell by adding `project.hsPkgs.plutus-chain-index.components.exes.plutus-chain-index` to `nativeBuildInputs`.\n\n\u003e **NOTE**: The provided example is using the **preview** testnet.\n\n\u003e **NOTE**: You need to use a vasil compliant version of BPI. Mainline BPI does not support vasil yet. Use the [`gergely/vasil` branch](https://github.com/mlabs-haskell/bot-plutus-interface/tree/gergely/vasil) instead.\n\n## Frontend environment setup\n\nHow you set up the frontend is entirely upto you, as long as it can query the Haskell server to obtain a `PartialTx` - and use it with `lucid-cardano` and `lucid-cardano-partialtx`, it's enough.\n\nSee [`Berry-Pool/lucid`](https://github.com/Berry-Pool/lucid) for adding Lucid to your dependency.\n\n\u003e **NOTE**: You need to use a vasil compliant version of Lucid. Mainline Lucid does not support vasil yet. Use the [`vasil` branch](https://github.com/Berry-Pool/lucid/tree/vasil) instead.\n\nFor `lucid-cardano-partialtx` (provided by this repo), there are three ways to import it:\n\n### Node.js\n\nInstall the [npm package](https://www.npmjs.com/package/lucid-cardano-partialtx):\n\n```sh\nnpm install lucid-cardano-partialtx\n```\n\nImport in your file:\n\n```sh\nimport { mkPartialTxInterpreter } from \"lucid-cardano-partialtx\";\n```\n\n\u003e Aside: You can use webpack or similar to bundle your Node project to run on the browser. See [full example that does this](#full-example-and-how-to-run-it)\n\n### Deno\n\nSimply import from deno.land:\n\n```ts\nimport { mkPartialTxInterpreter } from \"https://deno.land/x/lucid_partialtx@0.1.3/mod.ts\";\n```\n\n\u003e Aside: You can use ESBuild or similar to bundle your Deno project to run on the browser. However, you should to replace the `deno.land` imports with the [browser package](#browser-js) url if running in a browser environment. See [lucid-partialtx/build.ts](./lucid-partialtx/build.ts) that does something similar (but only after generating a node package).\n\n### Browser JS\n\n```hs\n\u003cscript type=\"module\"\u003e\n\nimport { mkPartialTxInterpreter } from \"https://unpkg.com/lucid-cardano-partialtx@0.1.3/web/mod.js\";\n\n\u003c/script\u003e\n```\n\n\u003e Aside: This is pure JS directly running in the browser: probably not too practical for large projects.\n\n## Haskell server\n\nOnce you have the environment set up, your haskell server merely has to use BPI (bot-plutus-interface) to run your contracts returning `PartialTx`s. You can hook up BPI with the testnet quite easily: simply copy over the [`BPI.Testnet.Setup` module](./example/BPI/Testnet/Setup.hs) from the example.\n\nA simple servant server, showcasing a simple `Contract` usage, can be found in [example/Main](./example/Main.hs).\n\n## Frontend Lucid\n\nAll you have to do is create a `PartialTxInterpreter` by passing your `Lucid` instance to `mkPartialTxInterpreter`, make an API call to receieve the `PartialTx` from your server, and pass it through the interpreter. The resulting Lucid `Tx` can be modified further or directly signed, and submitted.\n\nSee [example/frontend/src/index.ts](./example/frontend/src/index.ts).\n\n# Full example and how to run it\n\nThere is a full example with servant, BPI, and Lucid that can run a dummy\nminting contract on the testnet. Check the haskell code\n[in the example directory](./example). The gist is that you can copy over\n`BPI.Testnet.Setup` and use the exposed interface to create `PartialTx`s in the\ncontext of the testnet.\n\nThe example frontend is in [`example/frontend`](./example/frontend).\n\nTo run the project and run stuff on the testnet, head inside the nix shell by\ndoing `nix develop`, and follow these steps:\n\n## 1. Fill in blockfrost config\n\nYou need to fill a `config.json` and put it in `example/frontend/config.json`, this\nconfig should contain your blockfrost API access key:\n\n```json\n{\n  \"blockfrostUrl\": \"TESTNET_BLOCKFROST_URL\",\n  \"blockfrostProjId\": \"TESTNET_BLOCKFROST_PROJID\"\n}\n```\n\n\u003e Aside: Of course, you can also deploy all this in production by switching out\n\u003e to connect to the mainnet in the BPI setup and blockfrost setup.\n\n## 2. Start `cardano-node` and `plutus-chain-index` in background\n\nYou'll also need `cardano-node` and `chain-index` running in the background,\nproperly connected to testnet.\n\nUnless the directory `testnet/chain-index/db` already exists, you should create an empty directory: `mkdir testnet/chain-index/db`.\n\nAll you have to do run `make services`.\n\nThis will take some time to sync. You can see the node logs in\n`testnet/node.log` and chain index logs in `testnet/cix.log`. You can query the\nnode sync progress by running `make query-tip`.\n\n\u003e Note: Remember to stop these background services when you're done! Use\n\u003e `make stop-services` to do so.\n\n## 3. Build the frontend project\n\nFirstly, run `make build-lucid-lib` at the root project directory.\n\nNow, head inside the `example/frontend` directory and run the following commands:\n\n- `npm i` - to install all the npm dependencies\n- `npx webpack` - to build the project\n\nAlternatively, if you've already done `npm i` and have the `node_modules` from\nit - you can run `make build-frontend` from the root project path.\n\n## 4. Start the server\n\nOnce the node has synced and all the previous steps have been completed, run\n`make serve`. Head to `localhost:8080` to see a beautiful frontend with a\nsingular dummy minting button!\n\n**Note**: You'll need a wallet supporting Vasil for signing and submission to\nwork properly. In particular, mainline Nami does not support vasil yet. You need to use the [`vasil` branch of nami](https://github.com/Berry-Pool/nami-wallet/tree/vasil#testnet).\n\n# API\n\nHere's the core idea:\n\nKeep your Haskell contracts as they are, just make them return `UnbalancedTx`\nusing\n[`Ledger.Constraints.mkTx`](https://playground.plutus.iohkdev.io/doc/haddock/plutus-ledger-constraints/html/Ledger-Constraints.html#v:mkTx).\nAlternatively, make them return the `ScriptLookups` and the `TxConstraints`.\n\nUse either of the two functions provided within this repo to create a\n`PartialTx`:\n\n```hs\nimport Plutus.Contract.PartialTx\n\nmkPartialTx ::\n  ( FromData (DatumType a)\n  , ToData (DatumType a)\n  , ToData (RedeemerType a)\n  ) =\u003e\n  ScriptLookups a -\u003e\n  TxConstraints (RedeemerType a) (DatumType a) -\u003e\n  Either MkTxError PartialTx\n\nunbalancedToPartial :: UnbalancedTx -\u003e PartialTx\n```\n\n\u003e Aside: For your Haskell side tests (Plutip or EmulatorTrace), you'd still want\n\u003e to submit the `UnbalancedTx` - which you can still do using\n\u003e [`submitUnbalancedTx`](https://playground.plutus.iohkdev.io/doc/haddock/plutus-contract/html/Plutus-Contract.html#v:submitUnbalancedTx).\n\u003e So calling `mkTx` followed by `submitUnbalancedTx` is effectively the same as\n\u003e just calling `submitTx` (and similar).\n\nIn the frontend, bind your `Lucid` instance to `mkPartialTxInterpreter`, and use the resulting `PartialTxInterpreter` to interpret a `PartialTx`:\n\n```ts\ntype PartialTxInterpreter = (x: PartialTx) =\u003e Tx;\n\nmkPartialTxInterpreter(lucid: Lucid): PartialTxInterpreter;\n```\n\nOnce you obtain a Lucid `Tx`, it's as simple as signing and submitting it, which\nlooks like:\n\n```ts\nconst signedTx = await tx.sign().complete();\nreturn signedTx.submit();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fplutus-partial-tx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlabs-haskell%2Fplutus-partial-tx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fplutus-partial-tx/lists"}