Skip to content

Commit 41376c6

Browse files
askeaske
authored
Merge pull request #177 from mlabs-haskell/aske/docs-1
2 parents 1d35f53 + d7ea6b4 commit 41376c6

10 files changed

+166
-368
lines changed

‎README.md

+89-52
Original file line numberDiff line numberDiff line change
@@ -5,129 +5,166 @@
55
[herc badge]: https://img.shields.io/badge/ci--by--hercules-green.svg
66
[herc link]: https://hercules-ci.com/github/mlabs-haskell/plutip
77

8-
Plutip is Cardano tool for spawning local clusters.
9-
Use it to start up disposable private network with arbitrary amount of funded addresses (providing keys for that addresses as well).
8+
Plutip is a Cardano tool for spawning local clusters.
9+
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).
1010

11-
TLDR: `plutip :: IO CardanoNodeSocket` where the node belongs to a small cluster, optionally you can ask for prefunded keys.
11+
For smart contract testing see [CTL integration with Plutip](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/doc/plutip-testing.md).
1212

13-
## Requirements
13+
**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.
1414

15-
Best way of building and launching Plutip libraries is using `Nix` and `cabal`. E.g. to start local network with two funded addresses run
15+
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
16+
**Table of Contents**
1617

17-
```bash
18-
nix build .#plutip-core:exe:local-cluster
19-
./result/bin/local-cluster -n 2
20-
```
18+
- [Plutip](#plutip)
19+
- [Prerequisites](#prerequisites)
20+
- [When using Plutip as a Haskell library](#when-using-plutip-as-a-haskell-library)
21+
- [Quick start](#quick-start)
22+
- [Run as an executable](#run-as-an-executable)
23+
- [Use in a Haskell program](#use-in-a-haskell-program)
24+
- [Overview](#overview)
25+
- [As a library](#as-a-library)
26+
- [As an executable](#as-an-executable)
27+
- [Via CTL for contract testing](#via-ctl-for-contract-testing)
28+
- [Tutorials](#tutorials)
29+
- [Advanced network setup](#advanced-network-setup)
30+
- [Useful links](#useful-links)
31+
- [Plutip for integration testing of smart contracts](#plutip-for-integration-testing-of-smart-contracts)
32+
- [Maintenance](#maintenance)
2133

22-
or
34+
<!-- markdown-toc end -->
2335

24-
```bash
25-
nix develop
26-
cabal run local-cluster -- -n 2
27-
```
36+
## Prerequisites
37+
38+
1. [Nix](https://nix.dev/tutorials/install-nix)
39+
2. [Set up haskell.nix binary cache](https://input-output-hk.github.io/haskell.nix/tutorials/getting-started#setting-up-the-binary-cache)
40+
41+
### When using Plutip as a Haskell library
2842

2943
If 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`:
3044

3145
* `cardano-cli` executable available in the environment
3246
* `cardano-node` executable available in the environment
3347

34-
And the following ghc flag must to be set for the test execution: `-Wall -threaded -rtsopts`
48+
The following GHC flags must be used in order for Plutip to run: `-threaded -rtsopts`.
3549

36-
## NOTES
37-
38-
⚠️ This branch launches local network in `Vasil`. It was tested with node `1.35.4` (this node version used in nix environment as well). Please use appropriate node version when setting up own binaries in `PATH`.
50+
**NOTE:** This branch launches local network in `Vasil`.
51+
It was tested with node `1.35.4` (this node version is used in the Nix environment as well).
52+
Please use an appropriate node version when setting up own binaries in `PATH`.
3953

4054
## Quick start
4155

42-
Launch local cluster with:
56+
### Run as an executable
57+
58+
```bash
59+
nix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- --help
60+
61+
# start local network with 2 funded addresses 10,000 ADA each
62+
nix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- -n 2
63+
64+
# or if you want to use the local version, clone the repo and then
65+
nix run .#plutip-core:exe:local-cluster -- --help
4366
```
67+
68+
### Use in a Haskell program
69+
70+
Launch local cluster with:
71+
```haskell
4472
withCluster :: PlutipConfig -> (ClusterEnv -> IO a) -> IO a
73+
withCluster conf action
4574
```
4675
Use `withFundedCluster` to additionaly receive pre-funded keys.
4776

48-
Cluster shutdowns when the user action completes. Use `startCluster`/`startFundedCluster` and `stopCluster` variants to keep cluster running.
77+
Cluster shuts down when the user action (second argument to `withCluster`) completes.
78+
Use `startCluster`/`startFundedCluster` and `stopCluster` variants to keep the cluster running.
4979

5080
## Overview
5181

52-
Plutip is in essence a simpler wrapper on some cardano-wallet code for spawning private disposable cardano clusters.
53-
It can be used in few ways:
54-
1. as a library
55-
2. as an executable
56-
3. indirectly via cardano-transaction-lib e2e plutip tests. This is a facility for testing contracts e2e in isolated environment: with wallet mocks and a private plutip cluster. See [ctl](https://github.com/Plutonomicon/cardano-transaction-lib/tree/develop) and their documentation on e2e tests. That's very much the recommended way if you're a ctl user.
57-
4. Historical mention: you could test pab `Contract`s with plutip itself, but this functionality is unmantained and was removed. If you're interested check out the archive branch `plutip-bpi`.
82+
Plutip is in essence a simpler wrapper over some `cardano-wallet` code for spawning private disposable Cardano clusters.
83+
84+
It can be used in a few ways:
85+
1. as a library,
86+
2. as an executable,
87+
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.
88+
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).
5889

5990
### As a library
6091

6192
Launch local cluster with
62-
```
93+
```haskell
6394
withCluster :: PlutipConfig -> (ClusterEnv -> IO a) -> IO a
95+
withCluster conf action
6496
```
65-
where
66-
- `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 temporary directory.
97+
where:
98+
- `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.
6799
- `ClusterEnv` is essentially a wrapper around the node socket. The socket belongs to one of the nodes.
100+
- `action :: ClusterEnv -> IO a` is a user action which has access to a `cardano-node` in a cluster via `Cardano.Api`.
68101

69102
Use
70-
```
103+
```haskell
71104
withFundedCluster :: PlutipConfig -> [[Lovelace]] -> (ClusterEnv -> [KeyPair] -> IO a) -> IO a
72105
```
73-
to additionaly receive keys prefunded with specified fund distributions (i.e. Key 1 with [1 Lovelace] and Key 2 with [2 Lovelace, 4 Lovelace]).
106+
to additionaly receive keys prefunded with specified fund distributions (e.g. Key 1 with `[1 Lovelace]` and Key 2 with `[2 Lovelace, 4 Lovelace]`).
74107

75-
Additionaly there's helpers `startCluster`, `startFundedCluster`, `stopCluster` useful when you want your cluster to keep running, instead of close after the IO action is completed.
108+
Additionaly 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.
76109

77-
Full example:
78-
```
110+
Example:
111+
```haskell
79112
import Data.Default (Default (def))
80113
import Plutip.CardanoApi (currentBlock)
81114
import Plutip.Cluster (withFundedCluster)
82115
import Plutip.Keys (cardanoMainnetAddress)
83116

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

92125
ada = (*) 1_000_000
93-
94126
```
95127

96128
### As an executable
97129

98-
Plutip provides a `local-cluster` executable. You can build it and run with nix package manager:
99-
```
130+
Plutip provides a `local-cluster` executable.
131+
You can build it and run with Nix:
132+
```bash
100133
nix run github:mlabs-haskell/plutip#plutip-core:exe:local-cluster -- --help
101134
```
102-
Available options mostly match the `withFundedCluster` interface, see `--help` and [README](local-cluster/README.md).
103135

104-
### Via CTL
136+
Available options mostly match the `withFundedCluster` interface, see `--help` and [local-cluster README](local-cluster/README.md) for detailed description of the arguments.
137+
138+
### Via CTL for contract testing
105139

106-
CTL is a purescript sdk for creating dapps. One of its features is ability to test contracts with private networks, see [plutip-testing](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/doc/plutip-testing.md).
140+
[CTL](https://github.com/Plutonomicon/cardano-transaction-lib) is a PureScript SDK for creating DApps.
141+
One 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).
142+
CTL 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.
143+
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.
144+
<!-- 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. -->
107145

108146
## Tutorials
109147

110-
* [Running disposable local network and building own runners](./local-cluster/README.md)
111-
* [Running Contracts is REPL](./docs/interactive-plutip.md)
148+
* [Running disposable local network and building custom runners](./local-cluster/README.md)
149+
<!-- * [CTL-based project with smart contract tests example](...) -->
112150

113151
## Advanced network setup
114152

115153
* [Tweaking local network](./docs/tweaking-network.md)
116-
* [Regenerating network configs](./docs/regenerate-network-configs.md)
154+
* [How to (re)generate network configs from node config and genesis files](./docs/regenerate-network-configs.md)
117155

118-
## Examples
156+
## Useful links
119157

120-
* [Starting private network from Haskell and executing contract](./contract-execution/Main.hs)
121-
* [Template for setting a Nix flake that includes Plutip](https://github.com/MitchyCola/plutip-flake). Kudos to @MitchyCola
158+
* [Template for setting up a Nix flake that includes Plutip](https://github.com/MitchyCola/plutip-flake). Kudos to @MitchyCola
122159

123-
## Plutip for integration testing smart contracts
160+
## Plutip for integration testing of smart contracts
124161

125162
If your goal is to:
126-
* build tests with `tasty` Haskell framework where user can run Plutus contracts (`Contract w s e a`) using mentioned above private network
127-
* run contracts in REPL on local network
163+
* 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,
164+
* run contracts in REPL on a local network,
128165

129-
then check out [CTL](https://github.com/Plutonomicon/cardano-transaction-lib) or legacy plutip revision at branch `plutip-bpi`.
166+
then 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.
130167

131168
## Maintenance
132169

133-
* [Important notes on updating `cardano-wallet` dependency](./docs/cardano-wallet-update.md)
170+
* [Important notes on updating the `cardano-wallet` dependency](./docs/cardano-wallet-update.md)

‎docs/cardano-wallet-update.md

+20-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,25 @@
11
# Cluster launcher update
22

3-
`Plutip` heavily relies on local cluster testing framework from `cardano-wallet`.
3+
[cardano-wallet-cluster-hs-1952de1]: https://github.com/input-output-hk/cardano-wallet/blob/1952de13f1cd954514cfa1cb02e628cfc9fde675/lib/shelley/src/Cardano/Wallet/Shelley/Launch/Cluster.hs
44

5-
Initially, framework was used as-is, but in order to add to Plutip ability to set slot length and epoch size, module `Cluster.hs` was copied from `cardano-wallet` to Plutip's codebase and adjusted to make this settings possible. So in case of updating `cardano-wallet` dependency be sure that original `Cluster.hs` and Plutip's one differs only in expected way.
5+
`Plutip` relies heavily on a local cluster testing framework from `cardano-wallet`.
6+
See [Cardano.Wallet.Launch.Cluster](https://github.com/input-output-hk/cardano-wallet/blob/master/lib/wallet/api/http/Cardano/Wallet/Launch/Cluster.hs) module, and originally [Cardano.Wallet.Shelley.Launch.Cluster@1952de1][cardano-wallet-cluster-hs-1952de1] (this is the one that is used in Plutip currently).
7+
8+
Initially, framework was used as-is, but in order to add ability to set slot length and epoch size to Plutip, module `Cluster.hs` was copied from `cardano-wallet` to Plutip's codebase and adjusted to make this settings possible. So in case of updating `cardano-wallet` dependency be sure that original `Cluster.hs` and Plutip's one differs only in expected way.
69

710
At the moment all changes are related to adding `ExtraConfig` to necessary ADTs and functions in Plutip's version of `Cluster.hs` and difference with the original is pretty small.
11+
12+
The [Cardano.Wallet.Shelley.Launch.Cluster@1952de1][cardano-wallet-cluster-hs-1952de1] module was split into:
13+
1. [Plutip.Launch.PoolConfigs](./src/Plutip/Launch/PoolConfigs.hs)
14+
2. [Plutip.Launch.Cluster](./src/Plutip/Launch/Cluster.hs)
15+
3. [Plutip.Launch.FaucetFunds](./src/Plutip/Launch/FaucetFunds.hs)
16+
17+
All modified typess and functions are marked with the "altered" comment for easier search, e.g.:
18+
```haskell
19+
-- altered: `def :: ExtraConfig` added
20+
localClusterConfigFromEnv :: IO LocalClusterConfig
21+
localClusterConfigFromEnv = do
22+
era <- clusterEraFromEnv
23+
logConf <- logFileConfigFromEnv (Just $ clusterEraToString era)
24+
pure $ LocalClusterConfig defaultPoolConfigs era logConf def
25+
```

0 commit comments

Comments
 (0)