Plutus Platform starter project
This project gives a simple starter project for using the Plutus Platform.
Setting up
VSCode devcontainer
Use the provided VSCode devcontainer to get an environment with the correct tools set up.
- Install Docker
- Install VSCode
- Install the Remote Development extension pack
- You do not need to install the Haskell extension
- Ensure you have a
~/.cabal/packages
folder. You can create this viamkdir -p ~/.cabal/packages
; it's used to cache cabal packages. - Clone this repository and open it in VSCode
- It will ask if you want to open it in the container, say yes.
- The first time it will take a few minutes to download the devcontainer image from dockerhub,
cabal build
from the terminal should work (unless you didn't have a~/.cabal
folder, in which case you'll need to runcabal update
first.)- Opening a Haskell file should give you IDE features (it takes a little while to set up the first time)
Note: This uses the plutus-starter-devcontainer image on dockerhub, if you wish to build the image yourself, you can do so as follows:
- Clone https://github.com/input-output-hk/plutus,
- Set up your machine to build things with Nix, following the Plutus README (make sure to set up the binary cache!),
- Build and load the docker container:
docker load < $(nix-build default.nix -A devcontainer)
, - Adjust the
.devcontainer/devcontainer.json
file to point to your local image.
Cabal+Nix build
Alternatively, use the Cabal+Nix build if you want to develop with incremental builds, but also have it automatically download all dependencies.
Set up your machine to build things with Nix
, following the Plutus README (make sure to set up the binary cache!).
To enter a development environment, simply open a terminal on the project's root and use nix-shell
to get a bash shell:
$ nix-shell
Otherwise, you can use direnv which allows you to use your preferred shell. Once installed, just run:
$ echo "use nix" > .envrc # Or manually add "use nix" in .envrc if you already have one
$ direnv allow
and you'll have a working development environment for now and the future whenever you enter this directory.
The build should not take too long if you correctly set up the binary cache. If it starts building GHC, stop and setup the binary cache.
Afterwards, the command cabal build
from the terminal should work (if cabal
couldn't resolve the dependencies, run cabal update
and then cabal build
).
Also included in the environment is a working Haskell Language Server you can integrate with your editor. See here for instructions.
The Plutus Application Backend (PAB) example
We have provided an example PAB application in ./pab
. With the PAB we can serve and interact
with contracts over a web API. You can read more about the PAB here: PAB Architecture.
Here, the PAB is configured with one contract, the Game
contract from ./examples/src/Plutus/Contracts/Game.hs
.
Here's an example of running and interacting with this contract via the API. For this it will help if you
have jq
installed.
- Build the PAB executable:
cabal build plutus-starter-pab
- Run the PAB binary:
cabal exec -- plutus-starter-pab
This will then start up the server on port 8080. The devcontainer process will then automatically expose this port so that you can connect to it from any terminal (it doesn't have to be a terminal running in the devcontainer).
First, let's verify that the game is present in the server:
- Check what contracts are present:
curl -s http://localhost:8080/api/new/contract/definitions | jq
You should receive a list of contracts and the endpoints that can be called on them, and the arguments required for those endpoints.
We're interested in the GameContract
one.
Playing the guessing game over the API
The game has two players (wallets). One will initialise the contract and lock a value inside. Another wallet will then make guesses. Supposing they guess correctly, they'll receive the funds that were locked; otherwise, they won't!
- Start the instances:
# Wallet 1
curl -s -H "Content-Type: application/json" \
--request POST \
--data '{"caID": "GameContract", "caWallet":{"getWallet": 1}}' \
http://localhost:8080/api/new/contract/activate | jq
# Wallet 2
curl -s -H "Content-Type: application/json" \
--request POST \
--data '{"caID": "GameContract", "caWallet":{"getWallet": 2}}' \
http://localhost:8080/api/new/contract/activate | jq
From these two queries you will get back two contract instance IDs. These will be needed
in the subsequent steps for running actions against. We can optionally take a look at the state
of the contract with the status
API:
- Get the status
export INSTANCE_ID=...
curl -s http://localhost:8080/api/new/contract/instance/$INSTANCE_ID/status | jq
This has a lot of information; and in particular we can see what endpoints are still available to call.
- Start the game by locking some value inside
Now, let's call the lock
endpoint to start the game. In order to do so, we need to construct
a JSON representation of the LockParams
that the endpoint takes (look at Game.hs
). The easiest
way is to simply build the term in haskell and ask aeson
to encode it. From the terminal:
cabal repl
> import Plutus.Contracts.Game
> import Ledger.Ada
> args = LockParams { secretWord = "eagle", amount = lovelaceValueOf 90 }
> import Data.Aeson
> import Data.ByteString.Lazy.Char8 as BSL
> BSL.putStrLn $ encode args
{"amount":{"getValue":[[{"unCurrencySymbol":""},[[{"unTokenName":""},90]]]]},"secretWord":"eagle"}
Great! This is all we need to call the lock
endpoint, so let's do that now with
the instance from Wallet 1:
- Lock some value (Wallet 1)
export INSTANCE_ID=...
curl -H "Content-Type: application/json" \
--request POST \
--data '{"amount":{"getValue":[[{"unCurrencySymbol":""},[[{"unTokenName":""},90]]]]},"secretWord":"eagle"}' \
http://localhost:8080/api/new/contract/instance/$INSTANCE_ID/endpoint/lock
We can do likewise to work out what the JSON for GuessParams
is, and then make a guess from
Wallet 2:
- Make a guess (Wallet 2)
export INSTANCE_ID=...
curl -H "Content-Type: application/json" \
--request POST \
--data '{"guessWord": "duck"}' \
http://localhost:8080/api/new/contract/instance/$INSTANCE_ID/endpoint/guess
Note that this guess is wrong, so in the log of the server we will see that the transaction didn't validate.
As an exercise, you can now spin up another instance for Wallet 2 and make a correct guess, and confirm that the transaction validates and the Ada is transferred into the right wallet.
Note that you can verify the balances by looking at the log of plutus-starter-pab
when exiting it by pressing return.
Finally, also node that the PAB also exposes a websocket, which you can read about in the general PAB Architecture documentation.
Support/Issues/Community
If you're looking for support, or would simply like to report a bug, feature request, etc please do so over on the main plutus repository.
For more interactive discussion, you can join the IOG Technical Community Discord.
Thanks!