Opshin example contract

Note: Consider checking out the opshin-starter-kit instead, as it also provides off-chain code and runs in the demeter.run Browser environment

This is a sample repository to get you started with compiling your own smart contract with opshin in less than 10 minutes (even less if you have python3.8 already installed!). It requires you to know how to use the terminal on your computer (Ubuntu and other Linux distributions, Windows, Mac). You should also have git installed.

Installation

TL;DR

$ git clone https://github.com/opshin/opshin-example.git
$ cd opshin-example
$ python3.8 -m venv venv
$ pip install -r requirements

Done! If you have no clue what happened here, feel free to read the next section, which explains it step for step. Otherwise, skip to Running

Install Python

Make sure you have python3.8 installed. If you don't have it installed you can download the installer for your OS here. If you want to learn more about python, don't worry. Python is the second most used language on GitHub and there are tons of tutorials on how to use it.

Clone the repository

Once you have installed python, clone this repository. Open your terminal and navigate to a folder, then run

$ git clone https://github.com/opshin/opshin-example.git

This copies this repository on your local computer. If you want to modify the code and keep your modifications, fork the repository first, then clone the fork instead.

Then navigate into the the repository using the CLI, like this

$ cd opshin-example

Setup the environment

This project uses the specific version of python 3.8. For this reason we want to make sure that only this version is used for all operations. A common way to establish that i.e. python also refers to python3.8 is to set up a virtual environment.

$ python3.8 -m venv venv
$ source venv/bin/activate

You are now in a so called virtual environment. Make sure to run the source command everytime you enter this repository to work on the contract, or configure your IDE to use the created virtual environment. When operations require you to be inside the environment, commands are prefixed with (venv).

Install opshin

We're almost done. As the final step, we install the compiler, opshin-lang. We can simply use pip for this. We install all projects listed in requirements.txt, which includes opshin-lang. If you want to use other tools as well, you can add them there!

(venv) $ pip install -r requirements.txt

Testing

Run the tests for this contract like this:

(venv) $ python3 -m unittest

This example includes a simple test suite with a simple example for each how to write normal tests, parameterized tests and property based tests. You can check out the packages parameterized and hypothesis for more information on how to use them. You can also use any other testing framework for python.

Deploying

The main code for the smart contract is located in src. You can build the contract with opshin in a single command:

(venv) $ # builds the spending example, a contract that controls who can spend funds
(venv) $ opshin build src/contract_spending.py
(venv) $ # builds the minting example, a contract that controls who can mint tokens
(venv) $ opshin build src/contract_minting.py

Now you will find a number of useful artifacts in the folders contract_minting and contract_spending, among them a script.plutus file used by the CLI and other tools for using the contract in transactions, the address of the contract on main- and testnets and the policy id of the token for which the contract controls minting.

Examples on how to use smart contracts for minting and spending can be found for different tools:

• Cardano CLI (Shell): Spending, Minting
• PyCardano (Python): Spending
• Lucid (TypeScript): Spending

More example smart contracts can be found in the example section of opshin.