{"id":13687088,"url":"https://github.com/mlabs-haskell/plutip","last_synced_at":"2025-10-10T03:33:13.858Z","repository":{"id":37098605,"uuid":"449241102","full_name":"mlabs-haskell/plutip","owner":"mlabs-haskell","description":"A Cardano tool to spin up a testnet and run contracts with an EDSL to describe the instructions. Rhymes with tulip for no particular reason.","archived":false,"fork":false,"pushed_at":"2024-11-24T12:48:20.000Z","size":2858,"stargazers_count":56,"open_issues_count":33,"forks_count":24,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-05-26T10:18:27.770Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlabs-haskell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-18T10:34:54.000Z","updated_at":"2025-02-10T00:14:12.000Z","dependencies_parsed_at":"2023-12-18T14:33:43.381Z","dependency_job_id":"349f8cff-5213-4a05-be86-9ea71aec6237","html_url":"https://github.com/mlabs-haskell/plutip","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mlabs-haskell/plutip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlabs-haskell","download_url":"https://codeload.github.com/mlabs-haskell/plutip/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fplutip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002624,"owners_count":26083425,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2024-08-02T15:00:48.463Z","updated_at":"2025-10-10T03:33:13.837Z","avatar_url":"https://github.com/mlabs-haskell.png","language":"Haskell","funding_links":[],"categories":["Haskell"],"sub_categories":[],"readme":"# Plutip\n\n[![Hercules-ci][herc badge]][herc link]\n\n[herc badge]: https://img.shields.io/badge/ci--by--hercules-green.svg\n[herc link]: https://hercules-ci.com/github/mlabs-haskell/plutip\n\nPlutip is a Cardano tool for spawning local clusters.\nYou can use it to start up disposable private network with an arbitrary amount of funded addresses (Plutip will provide corresponding key pairs as well).\n\nFor smart contract testing see [CTL integration with Plutip](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/doc/plutip-testing.md).\n\n**TL;DR**: plutip gets you a cardano node socket where the node belongs to a small cluster on a private network, and you can prefund addresses with ADA.\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n**Table of Contents**\n\n- [Plutip](#plutip)\n  - [Prerequisites](#prerequisites)\n    - [When using Plutip as a Haskell library](#when-using-plutip-as-a-haskell-library)\n  - [Quick start](#quick-start)\n    - [Run as an executable](#run-as-an-executable)\n    - [Use in a Haskell program](#use-in-a-haskell-program)\n  - [Overview](#overview)\n    - [As a library](#as-a-library)\n    - [As an executable](#as-an-executable)\n    - [Via CTL for contract testing](#via-ctl-for-contract-testing)\n  - [Tutorials](#tutorials)\n  - [Advanced network setup](#advanced-network-setup)\n  - [Useful links](#useful-links)\n  - [Plutip for integration testing of smart contracts](#plutip-for-integration-testing-of-smart-contracts)\n  - [Maintenance](#maintenance)\n\n\u003c!-- markdown-toc end --\u003e\n\n## Prerequisites\n\n1. [Nix](https://nix.dev/tutorials/install-nix)\n2. [Set up haskell.nix binary cache](https://input-output-hk.github.io/haskell.nix/tutorials/getting-started#setting-up-the-binary-cache)\n\n### When using Plutip as a Haskell library\n\nIf your project is importing and making use of `Plutip`s library you will need to make sure that the following executables are present in your `PATH`:\n\n- `cardano-cli` executable available in the environment\n- `cardano-node` executable available in the environment\n\nThe following GHC flags must be used in order for Plutip to run: `-threaded -rtsopts`.\n\n**NOTE:** This branch launches local network in `Vasil`.\nIt was tested with node `1.35.4` (this node version is used in the Nix environment as well).\nPlease use an appropriate node version when setting up own binaries in `PATH`.\n\n## Quick start\n\n### Run as an executable\n\n```bash\nnix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- --help\n\n# start local network with 2 funded addresses 10,000 ADA each\nnix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- -n 2\n\n# or if you want to use the local version, clone the repo and then\nnix run .#plutip-core:exe:local-cluster -- --help\n```\n\n### Use in a Haskell program\n\nLaunch local cluster with:\n\n```haskell\nwithCluster :: PlutipConfig -\u003e (ClusterEnv -\u003e IO a) -\u003e IO a\nwithCluster conf action\n```\n\nUse `withFundedCluster` to additionally receive pre-funded keys.\n\nCluster shuts down when the user action (second argument to `withCluster`) completes.\nUse `startCluster`/`startFundedCluster` and `stopCluster` variants to keep the cluster running.\n\n## Overview\n\nPlutip is in essence a simpler wrapper over some `cardano-wallet` code for spawning private disposable Cardano clusters.\n\nIt can be used in a few ways:\n\n  1. as a library,\n  2. as an executable,\n  3. indirectly via cardano-transaction-lib (CTL) smart contract tests. This is a facility for testing contracts in an isolated environment: with wallet mocks and a private plutip cluster. See [CTL](https://github.com/Plutonomicon/cardano-transaction-lib/) and their [documentation](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/doc/testing.md#testing-with-plutip) on Plutip tests. That's very much the recommended way if you're a CTL user.\n  4. Historical mention: you could test PAB `Contract`s with Plutip itself, but this functionality is unmantained and was removed as most users switched to [CTL](https://github.com/Plutonomicon/cardano-transaction-lib/). If you're interested check out the archive branch [`plutip-bpi`](https://github.com/mlabs-haskell/plutip/tree/plutip-bpi) and the old [tutorial](https://github.com/mlabs-haskell/plutip/blob/plutip-bpi/docs/interactive-plutip.md).\n\n### As a library\n\nLaunch local cluster with\n\n```haskell\nwithCluster :: PlutipConfig -\u003e (ClusterEnv -\u003e IO a) -\u003e IO a\nwithCluster conf action\n```\n\nwhere:\n\n- `conf :: PlutipConfig` specifies the working directory of a spawned cluster (can be temporary) and in some capacity the parameters of the cluster. Use `Data.Default (def)` to spawn default cluster in a temporary directory.\n- `ClusterEnv` is essentially a wrapper around the node socket. The socket belongs to one of the nodes.\n- `action :: ClusterEnv -\u003e IO a` is a user action which has access to a `cardano-node` in a cluster via `Cardano.Api`.\n\nUse\n\n```haskell\nwithFundedCluster :: PlutipConfig -\u003e [[Lovelace]] -\u003e (ClusterEnv -\u003e [KeyPair] -\u003e IO a) -\u003e IO a\n```\n\nto additionally receive keys prefunded with specified fund distributions (e.g. Key 1 with `[1 Lovelace]` and Key 2 with `[2 Lovelace, 4 Lovelace]`).\n\nAdditionally there are helpers `startCluster`, `startFundedCluster`, `stopCluster` which are useful when you want your cluster to keep running, instead of shutting down after the IO action is completed.\n\nExample:\n\n```haskell\nimport Data.Default (Default (def))\nimport Plutip.CardanoApi (currentBlock)\nimport Plutip.Cluster (withFundedCluster)\nimport Plutip.Keys (cardanoMainnetAddress)\n\nmain = withFundedCluster def [[ada 1], [ada 2, ada 4]] $ \\cenv [key1, key2] -\u003e do\n  -- You have a default cluster using a temporary directory for storage and 7 Ada to use wisely.\n  -- You can query the node for block number with\n  res \u003c- currentBlock cenv\n  ...\n  -- See Plutip.CardanoApi for example queries and construct your own queries with Cardano.Api.\n  -- To make use of your keys, also use Cardano.Api.\n\nada = (*) 1_000_000\n```\n\n### As an executable\n\nPlutip provides a `local-cluster` executable.\nYou can build it and run with Nix:\n\n```bash\nnix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- --help\n```\n\nAvailable options mostly match the `withFundedCluster` interface, see `--help` and [local-cluster README](local-cluster/README.md) for detailed description of the arguments.\n\n### Via CTL for contract testing\n\n[CTL](https://github.com/Plutonomicon/cardano-transaction-lib) is a PureScript SDK for creating DApps.\nOne of its features is the ability to test contracts on disposable private networks which Plutip sets up, see [plutip-testing](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/doc/plutip-testing.md).\nCTL provides (via Nix) a runtime environment containing several services, including [plutip-server](https://github.com/Plutonomicon/cardano-transaction-lib/tree/develop/plutip-server) which allows to control Plutip via HTTP.\nAs long as you are using CTL's Nix environment (or your setup is based on it) there's no need to install Plutip separately.\n\u003c!-- See a full working example of a CTL-based project with smart contract tests is [here](...). You can base your project's structure on it. --\u003e\n\n## Tutorials\n\n- [Running disposable local network and building custom runners](./local-cluster/README.md)\n\u003c!-- * [CTL-based project with smart contract tests example](...) --\u003e\n\n## Advanced network setup\n\n- [Tweaking local network](./docs/tweaking-network.md)\n- [How to (re)generate network configs from node config and genesis files](./docs/regenerate-network-configs.md)\n\n## Useful links\n\n- [Template for setting up a Nix flake that includes Plutip](https://github.com/MitchyCola/plutip-flake). Kudos to @MitchyCola\n\n## Plutip for integration testing of smart contracts\n\nIf your goal is to:\n\n- run tests with the `tasty` Haskell framework where user can run\n  Plutus contracts (`Contract w s e a`) using the disposable private network set up by Plutip,\n- run contracts in REPL on a local network,\n\nthen check out [CTL](https://github.com/Plutonomicon/cardano-transaction-lib) or a legacy Plutip revision ([`plutip-bpi`](https://github.com/mlabs-haskell/plutip/tree/plutip-bpi)) or Plutip v1.3.1 and older releases.\n\n## Maintenance\n\n- [Important notes on updating the `cardano-wallet` dependency](./docs/cardano-wallet-update.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fplutip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlabs-haskell%2Fplutip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fplutip/lists"}