Opshin Pioneer Program

This repository implements many educational Cardano Smart Contracts in Python using opshin. It also comes with off-chain code using PyCardano and a host of test cases to ensure high quality of the resulting contracts. Most of the code is in a similar format to the plutus-pioneer-program. Join the opshin discord server for Q/A and interact with other opshin pioneers!

Installation

1. Install Python 3.9, 3.10 or 3.11 (if it not already installed on your operating system). Python3.11 Installer download.

2. Install python poetry. Follow the official documentation here.

3. Install a python virtual environment with poetry:

# clone the repository including the config submodule necessary for running the node
git clone --recurse-submodules -j8 https://github.com/OpShin/opshin-pioneer-program.git
cd opshin-pioneer-program

# Optional. Use a specific python version
# replace <version> with 3.8, 3.9, 3.10, or 3.11
# for this to work, python<version> must be accessible in your command line
# alternatively provide the path to your python executable
poetry env use <version>

# install python dependencies
poetry install

# run a shell with the virtual environment activated
poetry shell

# If you're not in a shell, you can run python scripts with `poetry run`
poetry run python <script-path>

Cardano Node and Ogmios

Quick setup

Simply run the following to use some publicly available nodes hosted by demeter.run. These nodes are already fully synced and ready to use. Note that as public endpoints, these nodes may be slow to respond and occasionally fail.

Note also that production environments should always host their own node in order to guard themselves from failures.

export OGMIOS_API_PROTOCOL=wss
export OGMIOS_API_HOST=ogmios-preview-api-public-e79b24.us1.demeter.run
export OGMIOS_API_PORT=443
export KUPO_API_PROTOCOL=https
export KUPO_API_HOST=kupo-preview-api-public-e79b24.us1.demeter.run
export KUPO_API_PORT=443
export CHAIN_BACKEND=kupo

If you want to host the node on your local computer, follow the steps in Local Setup

How to Follow the Pioneer Lectures and Code

As mentioned before, this repository follows the official Plutus Pioneer Program. The lectures/videos are the same as in the Plutus Pioneer Program. All covered contracts are (to be) implemented in OpShin in this repository. The repository contains presented contracts and empty files for homework in the main branch and a correct solution for homework in the solution branch.

Here's a rough mapping of the original lecture videos and what parts of this repository you can work on for each week. Some files may not be documented thoroughly so try to infer the purpose by referring the structure of the lectures.

Lecture 1

• Welcome and Introduction
• Setting up Our Development Environment
• Kuber Marketplace Demo
• Hashing & Digital Signatures
• The EUTxO-Model
• Homework
  • Follow the above installation instructions and get this repository set up locally.
  • Test your node synchronization with scripts/query_tip.sh

Lecture 2

• Low-Level, Untyped Validation Scripts
  • Study and compare the gift contract in opshin to plutus.
    • src/week02/lecture/gift.py
• Using the Cardano CLI to Interact with Plutus
  • We use PyCardano to create off-chain scripts for our opshin contracts. Run the following python scripts with poetry run python <script-path>. The bash scripts using the dockerized Cardano CLI are also provided for reference.
  • Create your test wallets with poetry run python scripts/create_key_pair.py --help
    • The wallets are generated in the keys/ directory.
    • Fund your wallets with the address in keys/<name>.addr at the Cardano Testnet Faucet
    • Use the name of your key as arguments for the offchain scripts below.
  • Look here for offchain code: src/week02/scripts/. PyCardano examples:
    • Build the lecture scripts poetry run python -m src/week02/scripts/build.py. The output is saved in the src/week02/assets folder.
    • Send ada poetry run python src/week02/scripts/send.py
    • Make gift poetry run python src/week02/scripts/make_gift.py
    • Collect gift poetry run python src/week02/scripts/collect_gift.py
    • You can reference make_gift.sh and collect_gift.sh for the equivalent using the Cardano CLI, but going forward we will use pycardano to get a consistent and holistic Python experience.
  • Look here for helper scripts (such as creating a test wallet): scripts/
• High-Level, Typed Validation Scripts
  • Review the rest of the opshin scripts.
    • src/week02/lecture/fourty_two.py
    • src/week02/lecture/fourty_two_typed.py
    • src/week02/lecture/custom_types.py
    • src/week02/lecture/burn.py
  • You can choose which lecture script to use in make_gift.py and collect_gift.py with the argument --script <script-name>
• Summary
• Homework
  • Complete the following homework files:
    • src/week02/homework/homework1.py
    • src/week02/homework/homework2.py
  • You can test your solution with pytest src/week02/tests/test_homework.py
  • The solutions are available at on the solutions branch

Lecture 3

• Script Contexts
• Handling Time
• A Vesting Example
  • src/week03/lecture/vesting.py
• Parameterized Contracts
  • src/week03/lecture/parameterized_vesting.py
• Offchain Code with Lucid
  • We implement the same in pycardano instead in src/week03/scripts.
• Reference Scripts
  • To be implemented...
• Homework
  • Complete the following homework files:
    • src/week03/homework/homework1.py
    • src/week03/homework/homework2.py
  • Like before, you can run tests with pytest src/week03/tests
• Summary

Lecture 4

This lecture is about alternative offchain solutions. We use pycardano, but you can compare and contrast alternatives.

• On-chain VS Off-chain
• Off-chain Code with Cardano CLI and GUI
• Off-chain Code with Kuber
• Off-chain Code with Lucid
• Homework
  • Implement the offchain code for the files in src/week04/homework.
  • Although the contracts are implemented in opshin, you can use offchain code other than pycardano to complete this.
  • There is no correct solution for this week as solutions can very widely. So make sure to test your code!
  • Feel free to submit your solution by making a PR to the solutions branch!
  • We will continue to implement off-chain code in pycardano for this repository.

Lecture 5

• Introduction
• Values
• A Simple Minting Policy
  • src/week05/lecture/free.py
  • Off-chain minting script: python src\week05\scripts\mint.py --script=free WALLET_NAME TOKEN_NAME
• A More Realistic Minting Policy
  • src/week05/lecture/signed.py
  • Off-chain minting script: python src\week05\scripts\mint.py --script=signed WALLET_NAME TOKEN_NAME
• NFT's
  • src/week05/lecture/nft.py
  • Off-chain minting script: python src\week05\scripts\mint.py --script=nft WALLET_NAME TOKEN_NAME
• Homework
  • Complete the minting policies in src/week05/homework.
  • Test your solution with pytest src/week05/tests

Lecture 6

• The State Monad in practice
  • You can skip this for opshin.
• Introduction to the Plutus Simple Model library
  • We implement MockChainContext and MockUser in src/utils/mock.py. These classes allow us to easily test and evaluate our opshin contracts without the Cardano Node!
  • Make sure you have the latest dependencies installed and pyaiken which we use to evaluate transactions without the node.
    • poetry install --sync --extras=pyaiken
  • We implement a simple test in src/week06/tests/test_mock.py with simulated spending and multiple users.
• Unit Testing a Smart Contract
  • Unit tests located in src/week06/tests/test_negative_r_timed.py
• Property Testing a Smart Contract
  • Property tests also located in src/week06/tests/test_negative_r_timed.py
  • Read the documentation on hypothesis to get familiar with property testing in Python.
• Testing Smart Contracts with Lucid
  • N/A.
• Double Spending and Homework
  • Complete the following test src/week06/homework/test_exploitable_swap.py
  • Use your completed test to implement a fix to the swap script: src/week06/homework/fixed_swap.py

Lecture 7

This week introduces Marlowe. There won't be any relevant opshin code for this week.

• Introduction
• Marlowe Playground Demo
• Homework
• Marlowe Starter Kit: Docker
• Marlowe Starter Kit: Preliminaries
• Marlowe Starter Kit: ZCB using the Marlowe Runtime command-line client
• Marlowe Starter Kit: ZCB using the Marlowe Runtime REST API
• Marlowe Starter Kit: ZCB using the Marlowe Runtime CLI
• Marlowe Starter Kit: Escrow using the Marlowe Runtime's REST API
• Marlowe Starter Kit: Swap contract using the Marlowe Runtime's REST API

Lecture 8

• Introduction
• The Private Testnet
• Plutus & Staking
• Trying it on the Testnet
• Homework

Lecture 9

• Creating our own Stablecoin Dapp
• Using our Stablecoin UI
• Stablecoin's Oracle
• Deploying Stablecoin's Reference scripts
• Minting Stablecoins
• Burning Stablecoins and Liquidating positions
• Testing our Stablecoin's scripts
• Homework

Lecture 10

• Introduction
• Developing a Dapp with MeshJS and PluTs (Typescript)
• Developing smart contracts with PluTs (Typescript)
• Developing smart contracts with OpShin and PyCardano (Python)
• Developing smart contracts with Plutarch (Haskell)
• Developing smart contracts with Aiken

Additional Material

Local setup

Minimum Specs for Preview Network:

• 2 Core CPU
• 4GB memory
• 16GB free storage

First install Docker. Follow the official documentation here.

To start a Cardano Node and Ogmios API use docker-compose in your terminal:

# make sure your node configurations are up to date
git submodule update --init
# starts a cardano node and ogmios api on the preview testnet
docker compose up

You can then access the cardano-cli using the docker image:

docker run --rm -it \
  --entrypoint cardano-cli \
  -e CARDANO_NODE_SOCKET_PATH=/ipc/node.socket \
  -v opshin-pioneer-program_node-db:/data \
  -v opshin-pioneer-program_node-ipc:/ipc \
  inputoutput/cardano-node

Kupo (Optional)

Kupo is a database that supports fast queries to the Cardano blockchain. Although not needed for simple use cases, it can offer more speed in exchange for more storage and memory usage. This adds ~2GB storage and ~2GB memory on the preview network.

# starts the cardano node and ogmios with kupo (disabled by default)
docker compose --profile kupo up

# set the environment variable to use the ogmios + kupo backend
export CHAIN_BACKEND=kupo

You can check kupo synchronization by checking comparing the last slot number in http://localhost:1442/checkpoints to ogmios at http://localhost:1337/