• This repository has been archived on 20/May/2024
  • Stars
    star
    198
  • Rank 196,898 (Top 4 %)
  • Language
    Nix
  • License
    Apache License 2.0
  • Created almost 4 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A starter project for Plutus apps

Plutus Platform starter project

CI

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
  • Ensure you have a ~/.cabal/packages folder. You can create this via mkdir -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 run cabal 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-apps,
  • 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.

  1. Build the PAB executable:
cabal build plutus-starter-pab
  1. Run the PAB binary:
cabal exec -- plutus-starter-pab

This will then start up the server on port 9080. 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:

  1. Check what contracts are present:
curl -s http://localhost:9080/api/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!

  1. Create wallets
export WALLET_ID_1=`curl -s -d '' http://localhost:9080/wallet/create | jq '.wiWallet.getWalletId'`
export WALLET_ID_2=`curl -s -d '' http://localhost:9080/wallet/create | jq '.wiWallet.getWalletId'`
  1. Start the instances:
# Wallet 1
curl -s -H "Content-Type: application/json" \
  --request POST \
  --data '{"caID": "GameContract", "caWallet":{"getWalletId": '$WALLET_ID_1'}}' \
  http://localhost:9080/api/contract/activate | jq

# Wallet 2
curl -s -H "Content-Type: application/json" \
  --request POST \
  --data '{"caID": "GameContract", "caWallet":{"getWalletId": '$WALLET_ID_2'}}' \
  http://localhost:9080/api/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:

  1. Get the status
export INSTANCE_ID=...
curl -s http://localhost:9080/api/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.

  1. 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:

  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:9080/api/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:

  1. Make a guess (Wallet 2)
export INSTANCE_ID=...
curl -H "Content-Type: application/json" \
  --request POST \
  --data '{"guessWord": "duck"}' \
  http://localhost:9080/api/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

Issues can be filed in the GitHub Issue tracker.

For more interactive discussion, you can join the IOG Technical Community Discord.

Thanks!

More Repositories

1

cardano-sl

Cryptographic currency implementing Ouroboros PoS protocol
Haskell
3,757
star
2

cardano-node

The core component that is used to participate in a Cardano decentralised blockchain.
Haskell
2,934
star
3

plutus

The Plutus language implementation and tools
Haskell
1,472
star
4

plutus-pioneer-program

This repository hosts the lectures of the Plutus Pioneers Program. This program is a training course that the IOG Education Team provides to recruit and train software developers in Plutus, the native smart contract language for the Cardano ecosystem.
Haskell
1,389
star
5

daedalus

The open source cryptocurrency wallet for ada, built to grow with the community
TypeScript
1,230
star
6

essential-cardano

Repository for the Essential Cardano list
738
star
7

haskell.nix

Alternative Haskell Infrastructure for Nixpkgs
Nix
557
star
8

Scorex

Modular blockchain framework. Public domain
JavaScript
503
star
9

nami

Nami Wallet is a browser based wallet extension to interact with the Cardano blockchain. Support requests: https://iohk.zendesk.com/hc/en-us/requests/new
JavaScript
373
star
10

jormungandr

privacy voting blockchain node
Rust
366
star
11

plutus-apps

The Plutus application platform
Haskell
304
star
12

rust-byron-cardano

rust client libraries to deal with the current cardano mainnet (byron / cardano-sl)
Rust
276
star
13

hydra

Implementation of the Hydra Head protocol
Haskell
262
star
14

cardano-documentation

TypeScript
258
star
15

cardano-db-sync

A component that follows the Cardano chain and stores blocks and transactions in PostgreSQL
Haskell
254
star
16

ouroboros-network

An implementation of the Ouroboros family of consensus algorithms, with its networking support
Haskell
254
star
17

mantis

A Scala based client for Ethereum-like Blockchains.
Scala
227
star
18

cardano-ledger

The ledger implementation and specifications of the Cardano blockchain.
Haskell
223
star
19

cardano-js-sdk

JavaScript SDK for interacting with Cardano, providing various key management options, with support for popular hardware wallets
TypeScript
216
star
20

scrypto

Cryptographic primitives for Scala
Scala
201
star
21

lobster-challenge

Simple Plutus contract to help give Charles' stuffed lobster a name
Haskell
179
star
22

adrestia

APIs & SDK for interacting with Cardano.
Markdown
177
star
23

marlowe

Prototype implementation of domain-specific language for the design of smart-contracts over cryptocurrencies
Isabelle
172
star
24

bitte

Nix Ops for Terraform, Consul, Vault, Nomad
Nix
156
star
25

mithril

Stake-based threshold multi-signatures protocol
Rust
128
star
26

symphony-2

Immersive 3D Blockchain Explorer
JavaScript
127
star
27

cardano-addresses

Addresses and mnemonic manipulation & derivations
Haskell
125
star
28

iohk-ops

NixOps deployment configuration for IOHK devops
Nix
119
star
29

Alonzo-testnet

repository for the Alonzo testnet
Haskell
112
star
30

cardano-tutorials

ARCHIVED-This content in this repository is now located at https://docs.cardano.org/projects/cardano-node/
Makefile
112
star
31

stack2nix

Generate nix expressions for Haskell projects
Nix
99
star
32

iodb

Multiversioned key-value database, especially useful for blockchain
Scala
96
star
33

nix-tools

Translate Cabals Generic Package Description to a Nix expression
95
star
34

marlowe-cardano

Marlowe smart contract language Cardano implementation
Haskell
90
star
35

cardano-byron-cli

Cardano Command Line Interface (CLI) (Deprecated)
Rust
84
star
36

cardano-base

Code used throughout the Cardano eco-system
Haskell
83
star
37

react-polymorph

React components with highly customizable logic, markup and styles.
JavaScript
79
star
38

high-assurance-legacy

Legacy code connected to the high-assurance implementation of the Ouroboros protocol family
Haskell
78
star
39

shelley-testnet

Support triage for the Shelley testnet
70
star
40

cardano-crypto

This repository provides cryptographic libraries that are used in the Byron era of the Cardano node
C
67
star
41

plutus-use-cases

Plutus Use Cases
66
star
42

cardano-ops

NixOps deployment configuration for IOHK/Cardano devops
Nix
65
star
43

iohk-nix

nix scripts shared across projects
Nix
62
star
44

cardano-rt-view

RTView: real-time watching for Cardano nodes (ARCHIVED)
Haskell
59
star
45

spongix

Proxy for Nix Caching
Go
59
star
46

nix-hs-hello-windows

Cross compiling Hello World (haskell) to Windows using nix.
Nix
58
star
47

symphony

Symphony v1
JavaScript
53
star
48

cardano-ledger-byron

A re-implementation of the Cardano ledger layer, replacing the Byron release
Haskell
52
star
49

rscoin-haskell

Haskell implementation of RSCoin
Haskell
51
star
50

cardano-node-tests

System and end-to-end (E2E) tests for cardano-node.
Python
51
star
51

project-icarus

Icarus, a reference implementation for a lightweight wallet developed by the IOHK Engineering Team.
45
star
52

cardano-rest

HTTP interfaces for interacting with the Cardano blockchain.
Haskell
44
star
53

foliage

🌿 Foliage is a tool to create custom Haskell package repositories, in a fully reproducible way.
Haskell
42
star
54

offchain-metadata-tools

Tools for creating, submitting, and managing off-chain metadata such as multi-asset token metadata
Haskell
42
star
55

cicero

event-driven automation for Nomad
Go
41
star
56

medusa

3D github repository visualiser
JavaScript
41
star
57

nothunks

Haskell
39
star
58

partner-chains

Substrate node with capability of communicating with Cardano network
Rust
38
star
59

bech32

Haskell implementation of the Bech32 address format (BIP 0173).
Haskell
37
star
60

catalyst-core

βš™οΈ Core Catalyst Governance Engine and utilities.
Rust
37
star
61

smash

Stakepool Metadata Aggregation Server
Haskell
36
star
62

chain-libs

blockchain libs
Rust
35
star
63

cardanodocs.com-archived

Cardano Settlement Layer Documentation
HTML
35
star
64

devx

The Developer Experience Shell - This repo contains a nix develop shell for haskell. Its primary purpose is to help get a development shell for haskell quickly and across multiple operating systems (and architectures).
Nix
35
star
65

io-sim

Haskell's IO simulator which closely follows core packages (base, async, stm).
Haskell
35
star
66

iohk-monitoring-framework

This framework provides logging, benchmarking and monitoring.
Haskell
33
star
67

mallet

JavaScript
32
star
68

project-icarus-chrome

Icarus, a reference implementation for a lightweight wallet developed by the IOHK Engineering Team.
JavaScript
32
star
69

js-cardano-wasm

various cardano javascript using wasm bindings
Rust
31
star
70

cardano-shell

Node shell, a thin layer for running the node and it's modules.
Haskell
31
star
71

cardano-launcher

Shelley cardano-node and cardano-wallet launcher for NodeJS applications
TypeScript
31
star
72

cardano-world

Cardano world provides preprod and preview cardano networks, configuration documentation and miscellaneous automation.
Nix
30
star
73

rscoin-core

Haskell
29
star
74

quickcheck-dynamic

A library for stateful property-based testing
Haskell
27
star
75

stakepool-management-tools

JavaScript
27
star
76

cardano-haskell-packages

Metadata for Cardano's Haskell package repository
Shell
24
star
77

cardano-haskell

Top level repository for building the Cardano Haskell node and related components and dependencies.
Shell
24
star
78

cardano-configurations

A common place for finding / maintaining configurations of various services of the Cardano eco-system
24
star
79

Developer-Experience-working-group

23
star
80

cardano-transactions

Library utilities for constructing and signing Cardano transactions.
Haskell
23
star
81

psg-cardano-wallet-api

Scala client to the Cardano wallet REST API
Scala
22
star
82

marlowe-ts-sdk

Marlowe TypeScript SDK
TypeScript
22
star
83

sanchonet

Sources for the SanchoNet website
TypeScript
21
star
84

pvss-haskell

Haskell
21
star
85

cardano-wallet-legacy

Official Wallet Backend & API for Cardano-SL
Haskell
21
star
86

scalanet

Scala
20
star
87

cardano-explorer

Backend solution powering the cardano-explorer. ⚠️ See disclaimer below. ⚠️
Haskell
20
star
88

formal-ledger-specifications

Formal specifications of the cardano ledger
Agda
19
star
89

metadata-registry-testnet

Nix
19
star
90

casino

Demo / PoC / implementation of IOHK MPC protocols
Haskell
19
star
91

hackage.nix

Automatically generated Nix expressions for Hackage
19
star
92

cardano-clusterlib-py

Python wrapper for cardano-cli for working with cardano cluster
Python
19
star
93

catalyst-voices

πŸŽ™οΈ Catalyst Voices provides a unified experience and platform including production-ready liquid democracy, meaningful collaboration opportunities & data-driven context for better onboarding & decisions.
Dart
19
star
94

marlowe-starter-kit

This repository contains lessons for using Marlowe via REST and at the command line. It is meant to be used with demeter.run or with a Docker deployment of Marlowe Runtime.
Jupyter Notebook
19
star
95

js-chain-libs

chain-libs javascript SDK
Rust
18
star
96

cardano-coin-selection

A library of algorithms for coin selection and fee balancing.
Haskell
18
star
97

ouroboros-consensus

Implementation of a Consensus Layer for the Ouroboros family of protocols
Haskell
18
star
98

marlowe-pioneer-program

Lectures, documentation, and examples for Marlowe Pioneer Program.
Haskell
18
star
99

chain-wallet-libs

Rust
18
star
100

jortestkit

jormungandr QA
Rust
17
star