OpShin Starter-kit

This Starter-Kit is a small tutorial of how to use the PyCardano library with opshin for interacting with a simple vesting contract on Cardano.

PyCardano is a Cardano library written in Python. It allows users to create and sign transactions without depending on third-party Cardano serialization tools, such as cardano-cli and cardano-serialization-lib, making it a lightweight library, which is simple and fast to set up in all types of environments.

opshin is a Smart Contract language based on Python. It allows users to define and compile Smart Contracts directly within a python environment. It also interacts seemlessly with PyCardano.

Dev Environment

For executing the scripts in this starter kit you'll need access to a running Ogmios instance.

In case you don't want to install the required components yourself, you can use Demeter.run platform to create a cloud environment with access to common Cardano infrastructure. The following command will open this repo in a private, web-based VSCode IDE with access to a running Ogmios instance in the preview network.

What is Included

We have included a number of python scripts for executing specific actions. You can find scripts to initialize addresses and interact with the cardano-node in scripts. src contains two folders, on_chain which hosts the actual opshin contract and off-chain which hosts tooling to interact with the contract.

Setup

1. Install Python 3.8, 3.9 or 3.10.

On demeter.run or Linux/Ubuntu, this version of python is usually already pre-installed. You can skip this step. For other Operating Systems, you can download the installer here.

2. Ensure python3 --version works in your command line. Open a Terminal in the browser VSCode interface (F1 -> Terminal: Create New Terminal) In Windows, you can do this by copying the python.exe file to python3.exe in your PATH environment variable.

3. Install python poetry.

On demeter.run or Linux/Ubuntu run

curl -sSL https://install.python-poetry.org | python3 -

Follow the instructions diplayed to add poetry to your local shell.

Otherwise, follow the official documentation here.

4. Install a python virtual environment with poetry:

# install python dependencies
poetry install
# run a shell with the virtual environment activated
poetry shell

5. Set up ogmios and optionally kupo.

On demeter.run, simply add the Ogmios Extension for the Preview network through the project console website (the page that shows you demeter.run project -> Connected Extensions -> Browse Extensions -> Cardano Ogmios) If you want to add kupo, use the Kupo Extension as well.

Make sure the following environment variables are set (defaults are displayed):

OGMIOS_API_HOST=localhost
OGMIOS_API_PORT=1337
OGMIOS_API_PROTOCOL=ws

KUPO_API_HOST=None
KUPO_API_PORT=80
KUPO_API_PROTOCOL=http

Running the scripts

Once you have entered the poetry shell, you can start interacting with the contract through the prepared scripts.

First, we have to build the vesting contract and generate two key pairs, one for the owner of funds and one for the intended beneficiary.

python3 scripts/build.py
python3 scripts/create_key_pair.py owner
python3 scripts/create_key_pair.py beneficiary

Make sure that the owner is loaded up with some testnet ada before proceeding, by using the testnet faucet. You can find the address of the owner key by running this command

cat keys/owner.addr

After requesting ada for the owner, send some ada to the beneficiary. The receiver address needs a small amount of ada in order to provide it as collateral when unlocking the funds later.

python3 src/off_chain/distribute.py owner beneficiary 

Then you can place a vested amount of ada at the contract. If you just requested funds for the owner address, you might need to wait a few minutes or the script will display an error that funds are missing.

python3 src/off_chain/make_vest.py owner beneficiary 

By default the deadline is 0 seconds after the creation of the vesting, so you can directly proceed and unlock the vested amount with the beneficiary!

python3 src/off_chain/collect_vest.py beneficiary

That's it! You successfully compiled a Smart Contract on cardano and interacted with it through off-chain tooling. Feel free to dive into the provided scripts and start customizing them for your needs.