https://github.com/opshin/opshin-starter-kit
On-chain and off-chain code for a Python Smart Contract using opshin and pycardano
https://github.com/opshin/opshin-starter-kit
cardano demeter-run off-chain on-chain plutus python smart-contracts
Last synced: 9 months ago
JSON representation
On-chain and off-chain code for a Python Smart Contract using opshin and pycardano
- Host: GitHub
- URL: https://github.com/opshin/opshin-starter-kit
- Owner: OpShin
- License: mit
- Created: 2023-01-26T11:09:14.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-09-15T13:33:22.000Z (almost 3 years ago)
- Last Synced: 2025-02-13T13:15:21.459Z (over 1 year ago)
- Topics: cardano, demeter-run, off-chain, on-chain, plutus, python, smart-contracts
- Language: Python
- Homepage: https://demeter.run/code?repository=https://github.com/opshin/opshin-starter-kit.git&template=python&source=demeter&key=opshin-starter-kit
- Size: 84 KB
- Stars: 16
- Watchers: 2
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpShin Starter-kit
This Starter-Kit is a small tutorial of how to use the [PyCardano](https://github.com/Python-Cardano/pycardano) library
with [opshin](https://github.com/OpShin/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](https://ogmios.dev/) instance.
In case you don't want to install the required components yourself, you can use [Demeter.run](https://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.
[](https://demeter.run/code?repository=https://github.com/opshin/opshin-starter-kit.git&template=python&source=demeter&key=opshin-starter-kit)
## 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 uv.
On demeter.run or Linux/Ubuntu run
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Follow the instructions diplayed to add uv to your local shell.
Otherwise, follow the official documentation [here](https://docs.astral.sh/uv/getting-started/installation/).
2. Set up a virtual environment and install the required packages.
```bash
uv python install
uv venv
source .venv/bin/activate
```
2. Alternatively set up Ogmios or Blockfrost
#### Set up Blockfrost
Follow the instructions on [Blockfrost](https://blockfrost.io/) to create a free account and get an API key for the preview network.
Make sure the following environment variables are set (defaults are displayed):
```bash
export BLOCKFROST_API_KEY="previewyourkey"
```
#### Set up [ogmios](https://ogmios.dev/) and optionally [kupo](https://cardanosolutions.github.io/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):
```bash
export OGMIOS_API_HOST=localhost
export OGMIOS_API_PORT=1337
export OGMIOS_API_PROTOCOL=ws
export KUPO_API_HOST=None
export KUPO_API_PORT=80
export KUPO_API_PROTOCOL=http
```
## Running the scripts
Once you have set up uv, 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.
```bash
uv run scripts/build.py
uv run scripts/create_key_pair.py owner
uv run 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](https://docs.cardano.org/cardano-testnet/tools/faucet).
You can find the address of the owner key by running this command
```bash
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.
```bash
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.
```bash
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!
```bash
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.
### Typical issues
If you see the following errors when running the scripts, don't panic, they are temporary issues when the blockchain has not yet included your previous transactions.
```
pycardano.exception.TransactionFailedException: Failed to submit transaction. Error code: 400. Error message: {"contents":{"contents":{"contents":{"era":"ShelleyBasedEraConway","error":["ConwayUtxowFailure (UtxoFailure (BadInputsUTxO (fromList [TxIn (TxId {unTxId = SafeHash \"5033df02e3cb82488d8cf46fbe18c783c586320cdcb43b77e8d88df5e50ccbc8\"}) (TxIx {unTxIx = 1})])))","ConwayUtxowFailure (UtxoFailure (ValueNotConservedUTxO (Mismatch {mismatchSupplied = MaryValue (Coin 0) (MultiAsset (fromList [])), mismatchExpected = MaryValue (Coin 9936335092) (MultiAsset (fromList []))})))"],"kind":"ShelleyTxValidationError"},"tag":"TxValidationErrorInCardanoMode"},"tag":"TxCmdTxSubmitValidationError"},"tag":"TxSubmitFail"}
```
This means that the transaction you are trying to submit is invalid, because the previous transaction has not yet been included in a block.
Just wait a few minutes and try again, it should work after a short while.
```
AssertionError: No script UTxOs found!
```
This means that the script UTxO you are trying to spend from does not exist.
This can happen if the transaction creating the script UTxO has not yet been included in a
block on the blockchain. Retry in a few minutes.
```
pycardano.exception.TransactionFailedException: Namespace(EvaluationFailure=Namespace(ScriptFailures=Namespace()))
```
This means there was an error when evaluating the script. The contract raised an error, maybe due to invalid inputs or due to a program bug. Unfortunately, Blockfrost does not provide detailed error messages for script failures. If you are running your own ogmios and kupo instances, you can get more detailed error messages that help you figuring out what went wrong.