Plutip

Plutip is a Cardano tool for spawning local clusters. You can use it to start up disposable private network with an arbitrary amount of funded addresses (Plutip will provide corresponding key pairs as well).

For smart contract testing see CTL integration with Plutip.

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.

Table of Contents

• Plutip
  • Prerequisites
    • When using Plutip as a Haskell library
  • Quick start
    • Run as an executable
    • Use in a Haskell program
  • Overview
    • As a library
    • As an executable
    • Via CTL for contract testing
  • Tutorials
  • Advanced network setup
  • Useful links
  • Plutip for integration testing of smart contracts
  • Maintenance

Prerequisites

1. Nix
2. Set up haskell.nix binary cache

When using Plutip as a Haskell library

If your project is importing and making use of Plutips library you will need to make sure that the following executables are present in your PATH:

• cardano-cli executable available in the environment
• cardano-node executable available in the environment

The following GHC flags must be used in order for Plutip to run: -threaded -rtsopts.

NOTE: This branch launches local network in Vasil. It was tested with node 1.35.4 (this node version is used in the Nix environment as well). Please use an appropriate node version when setting up own binaries in PATH.

Quick start

Run as an executable

nix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- --help

# start local network with 2 funded addresses 10,000 ADA each
nix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- -n 2

# or if you want to use the local version, clone the repo and then
nix run .#plutip-core:exe:local-cluster -- --help

Use in a Haskell program

Launch local cluster with:

withCluster :: PlutipConfig -> (ClusterEnv -> IO a) -> IO a
withCluster conf action

Use withFundedCluster to additionally receive pre-funded keys.

Cluster shuts down when the user action (second argument to withCluster) completes. Use startCluster/startFundedCluster and stopCluster variants to keep the cluster running.

Overview

Plutip is in essence a simpler wrapper over some cardano-wallet code for spawning private disposable Cardano clusters.

It can be used in a few ways:

1. as a library,
2. as an executable,
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 and their documentation on Plutip tests. That's very much the recommended way if you're a CTL user.
4. Historical mention: you could test PAB Contracts with Plutip itself, but this functionality is unmantained and was removed as most users switched to CTL. If you're interested check out the archive branch plutip-bpi and the old tutorial.

As a library

Launch local cluster with

withCluster :: PlutipConfig -> (ClusterEnv -> IO a) -> IO a
withCluster conf action

where:

• 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.
• ClusterEnv is essentially a wrapper around the node socket. The socket belongs to one of the nodes.
• action :: ClusterEnv -> IO a is a user action which has access to a cardano-node in a cluster via Cardano.Api.

Use

withFundedCluster :: PlutipConfig -> [[Lovelace]] -> (ClusterEnv -> [KeyPair] -> IO a) -> IO a

to additionally receive keys prefunded with specified fund distributions (e.g. Key 1 with [1 Lovelace] and Key 2 with [2 Lovelace, 4 Lovelace]).

Additionally 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.

Example:

import Data.Default (Default (def))
import Plutip.CardanoApi (currentBlock)
import Plutip.Cluster (withFundedCluster)
import Plutip.Keys (cardanoMainnetAddress)

main = withFundedCluster def [[ada 1], [ada 2, ada 4]] $ \cenv [key1, key2] -> do
  -- You have a default cluster using a temporary directory for storage and 7 Ada to use wisely.
  -- You can query the node for block number with
  res <- currentBlock cenv
  ...
  -- See Plutip.CardanoApi for example queries and construct your own queries with Cardano.Api.
  -- To make use of your keys, also use Cardano.Api.

ada = (*) 1_000_000

As an executable

Plutip provides a local-cluster executable. You can build it and run with Nix:

nix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- --help

Available options mostly match the withFundedCluster interface, see --help and local-cluster README for detailed description of the arguments.

Via CTL for contract testing

CTL is a PureScript SDK for creating DApps. One of its features is the ability to test contracts on disposable private networks which Plutip sets up, see plutip-testing. CTL provides (via Nix) a runtime environment containing several services, including plutip-server which allows to control Plutip via HTTP. As long as you are using CTL's Nix environment (or your setup is based on it) there's no need to install Plutip separately.

Tutorials

• Running disposable local network and building custom runners

Advanced network setup

• Tweaking local network
• How to (re)generate network configs from node config and genesis files

Useful links

• Template for setting up a Nix flake that includes Plutip. Kudos to @MitchyCola

Plutip for integration testing of smart contracts

If your goal is to:

• run tests with the tasty Haskell framework where user can run Plutus contracts (Contract w s e a) using the disposable private network set up by Plutip,
• run contracts in REPL on a local network,

then check out CTL or a legacy Plutip revision (plutip-bpi) or Plutip v1.3.1 and older releases.

Maintenance

• Important notes on updating the cardano-wallet dependency