On Cardano, funds are stored at addresses. An address can be controlled by a cryptographic key, the secret for unlocking it being only known to a specific user. The alternative is a Smart Contract - this is some encoded logic that controls unlocking funds from the address. In particular, this logic just validates that funds may be unlocked from the address based on how they are spent. For this reason, this kind of smart contract is often referred to as Spending Validator.

Other contracts also exist i.e. to validate minting of native tokens, withdrawal of stake rewards or certification of stake pools.

Sample Code
The following contract validates that the signature of a special user is present in a transaction. The signature is specified by a third party and attached to an UTxO sent to the contract. The receiver can then construct a transaction where they unlock the funds from the contract. The contract allows this when it is provided the signature of the receiver.

# gift.py
from opshin.prelude import *


@dataclass()
class WithdrawDatum(PlutusData):
    pubkeyhash: bytes


def validator(datum: WithdrawDatum, redeemer: None, context: ScriptContext) -> None:
    sig_present = False
    for s in context.tx_info.signatories:
        if datum.pubkeyhash == s:
            sig_present = True
    assert sig_present, "Required signature missing"
Why opshin?
100% valid Python. Leverage the existing tool stack for Python, syntax highlighting, linting, debugging, unit-testing, property-based testing, verification
Intuitive. Just like Python.
Flexible. Imperative, functional, the way you want it.
Efficient & Secure. Static type inference ensures strict typing and optimized code.
Supporters
   

The main sponsor of this project is Inversion. Here is a word from them!

At Inversion, we pride ourselves on our passion for life and our ability to create exceptional software solutions for our clients. Our team of experts, with over a century of cumulative experience, is dedicated to harnessing the power of the Cardano blockchain to bring innovative and scalable decentralized applications to life. We've successfully built applications for NFT management, staking and delegation, chain data monitoring, analytics, and web3 integrations, as well as countless non-blockchain systems. With a focus on security, transparency, and sustainability, our team is excited to contribute to the Cardano ecosystem, pushing the boundaries of decentralized technologies to improve lives worldwide. Trust Inversion to be your go-to partner for robust, effective, and forward-thinking solutions, whether blockchain based, traditional systems, or a mix of the two.

They have recently started a podcast, called "Africa On Chain", which you can check out here: https://www.youtube.com/@africaonchain

What is a Smart Contract on Cardano?

Prequisites
This guide tries to assume as little knowledge as possible but there are certain assumptions:

You should understand Python. Opshin is basically Python so we assume some basic knowledge of Python.
Installation
Install Python 3.8, 3.9, 3.10 or 3.11. Then run:

python3 -m pip install opshin
Compiling Opshin Code
Make a file called hello_world.py and copy:

# hello_world.py

def validator(_: None) -> None:
    print("Hello world!")
Run this command:

$ opshin build hello_world.py
This should create a build folder in the current directory. The build folder should look like this:

build/
  └-hello_world/
    ├-mainnet.addr
    ├-script.cbor
    ├-script.plutus
    ├-script.policy_id
    └-testnet.addr
We'll cover what all these files in the hello_world sub-folder mean later in the book.

Compatibility
All OpShin versions are tightly tied to specific versions of PyCardano. Due to a change of the default value of constructor ids, all OpShin versions < 0.20.0 are only compatible with PyCardano < 0.10.0. All versions >= 0.20.0 are only compatible with PyCardano >= 0.10.0.

Getting Started with Opshin

Understanding eUTxO Crash Course

This section covers the syntax of Opshin and in particular the available Python language features.

OpShin is Python
As a general disclaimer we would like to point out that OpShin is a restricted version of Python. We encourage you to always try to write code the way you would do it in a normal Python program. Play around to see what is accepted by the compiler and what not. If the compiler accepts your code, the code is safe to run (the only notable exception are type downcasts, covered later).

The main goal of OpShin is that you can express the smart contract logic the way you want - hence the choice of Python, which is designed to be simple and intuitive.

If you find yourself going to great lengths to satisfy the OpShin compiler, please do open an Issue at the GitHub repository. We are always looking for feedback to simplify the experience of coding with OpShin.

Language Tour

OpShin code is an imperative programming language. As such, code is written by instructing the computer to perform computations. Each line of code corresponds to one instruction. A simple instruction is the assignment.

# Assign value 2 to variable named a
a = 2
If we want to not only store but also read the value, we can print it like this.

# Assign value 2 to variable named a
a = 2
# print the content of variable a
print(a)
When executed locally, this will print 2 to the command line. When executed on chain, this code will append the string "2" to the on-chain debug logs - you can use this to inspect how your code is working!

Can you guess what the following program will print?

a = 2
b = 4
print(a + b)
Types
Every variable in OpShin has a type. In general we do not need to tell OpShin in advance what type variables has - it is able to derive the type on its own. In the above example, variable a has type int. This is the type for whole (integer) numbers. There are a few more types that are introduced in the following sections.

Note that types are important in OpShin. If types do not match at compilation time, the contract can not be compiled. This is to avoid unnecessary errors and prevent bugs in the code. For example the following is not allowed, since it is a non-sensical instruction:

a = 2 + "hello"
The left part of this addition has type int while the right part has type str (the text/"String" type). An addition between them is not unambiguous and generally does not make too much sense. Hence, when trying to compile this statement, you will face a compiler error.

You may see these errors a lot (but hopefully not too often). They are telling you in advance that an operation will not work as expected. Don't fret! Take these error messages as guidance on what works and what not and adjust your program as required by the compiler to obtain valid code.

It is not possible to change the type of your variable later. The following program is forbidden

a = 10
a = "hello"
Instead, we recommend simply changing the variable name if you want to change the type. This will also be less confusing to the reader!

Control flow
In OpShin, control flow can be introduced using statements like if.

if a == 2:
    print("a is equal to 2!")
    a = 10
print("hello!")
In this case, the expression a == 2 has a boolean type. It can evaluate to either True (a is indeed equal to 2) or False. If it is True, then the indented part is executed, so the program will print a is equal to 2! and afterwards assign the value 10 to a.

The unindented part will always be executed. Generally, indentation indicates that code belongs to a different "layer" of the program, i.e. an if/else statement, a loop, a function or a class.

Structure

Opshin has 5 primitive types. These are called primitive as they are the basis of all other types and not composed of others.

. int
. bool
. bytes
. str
. None


int
This is the only numeric type in Opshin. It represents integer numbers. Opshin's int type works just like the int type in Python and can be written in different notations. Note that all of the below examples evaluate to an integer and can be compared and added to each other!

# Opshin supports typical integer literals:
my_decimal = 17  # decimal notation
my_binary  = 0b10001  # binary notation
my_hex     = 0x11  # hexadecimal notation
my_octal   = 0o121 # octal notation

# What will this print?
print(my_decimal == my_hex)
Operation on integers
OpShin offers a number of builtin operations for integers.

# Addition
a = 5 + 2  # returns 7

# Subtraction
a = 5 - 2  # returns 3

# Multiplication
a = 5 * 2  # returns 10

# Integer division (floored)
a = 5 // 2  # returns 2

# Power
a = 5 ** 2  # returns 25
Proper Division is not supported because UPLC has not way to represent floating point numbers. If you want to perform operations on rational numbers, use the fractions library

bool
The bool type has two possible values: True or False. Control flow (if/else, while) are usually controlled using boolean types.

booly = False
Operation on Booleans
OpShin offers a number of builtin operations for booleans.

# Conjunction
b = True and False  # returns False

# Disjunction
b = True or False  # returns True

# Negation
b = not True  # returns False

# Cast to integer
b = int(True)  # returns 1 (False gives 0)
str
The str type in Opshin stores Strings, i.e. human-readable text. It is mostly used for printing debug messages.

stringy = "hello world"

not_so_secret_message = "..."
Operation on Strings
OpShin offers some builtin operations for strings.

# Concatentation
s = "hello " + "world!"  # Returns "hello world!"

# Cast to integer
s = int("42")  # returns 42
.encode()
str are usually stored in binary format in the so-called UTF-8 encoding. This is for example the case for native token names. The function encode transforms a normal, readable string into its binary representation.

"OpShin".encode()  # returns b"\x4f\x70\x53\x68\x69\x6e"
str()
If you want to convert anything into a string for debugging purposes, you may call the function str on it.

str(42)  # returns "42"
Note that print also implicitly calls str on its input before printing it for your convenience.

print(42)  # prints "42"
Format strings
More conveniently, if you want to combine strings and other values to a nicely formatted output, use formatting strings like this:

print(f"the value of a is {a}, but the value of b is {b}")
This will print the original string and substitute everything between { and } with the evaluated expression.

bytes
The bytes type in Opshin represents an array/string of bytes. It's usually called ByteArray or ByteString in other programming languages. You may use it to store raw binary data.

my_bytes = b"ooh a bytestring"
This type is usually used to represent hashes or CBOR. Note that bytestrings per default generate the bytestring for the ASCII character input. If you have a bytestring 0xaf2e221a represented in hexadecimal format, you can write it like this as a literal in OpShin.

hashy = b"\xaf\x2e\x22\x1a"
You may also use the helper function bytes.fromhex.

hashy = bytes.fromhex("af2e221a")
Operation on bytes (ByteStrings)
OpShin offers operations for bytestrings.

# Concatentation
s = b"hello " + b"world!"  # Returns b"hello world!"
[] - indexing and slicing
Python has a general concept of accessing elemtns at a specific index or accessing a slice of them. This also works for bytes. You can either access a single byte of the string.

b"test"[1]  # returns 101
Or you can access a substring of the bytes from the first (inclusive) to last (exclusive) indicated index using [a:b] slicing syntax.

b"test"[1:3]  # returns b"es"
In python, negative indices y indicate access at len(x) - y for object x. The following returns the byte at the last position of the byte string!

b"test"[-1]  # returns 116
This also works with slices.

.decode()
bytes may represent unicode UTF-8 encoded strings. This is for example the case for native token names. The function decode transforms a byte string into a normal, readable string.

b"\x4f\x70\x53\x68\x69\x6e".decode()  # returns "OpShin"
.hex()
bytes are better readable when displayed in hexadecimal notation. Use hex for this.

b"\x4f\x70\x53\x68\x69\x6e".hex()  # returns "4f705368696e"
len()
If you want to know the length of a bytestring, call len() on it.

len(b"OpShin")  # returns 6
None
The None type is exactly like the None type in Python. In other cardano smart contract languages it's called unit and denoted by empty brackets, (). It doesn't do anything and is usually used to denote the absence of a value.


null_val = None

Primitive Types

Opshin has two main container types:

List[a]
Dict[k, v]
Note: The container types are generic, and the letter in square brackets ([]) are the type arguments

List[a]
The Opshin List type is a container type that is used to hold multiple values of the same type. This is works just like the list type in Python.

listy: List[int] = [1, 2, 3, 4, 5]
Note: Opshin lists are actually linked-lists. This is because that's how lists are implemented in UPLC.

List Operations
You can add lists using the + operator.

print([1, 2, 3, 4] + [5, 6])
# prints "[1, 2, 3, 4, 5, 6]"
List Access
You may access elements at arbitrary positions within a list like this:

listy[3]  # will return the element at the 4th position (3rd with 0-based indexing), i.e. 4
If you want to count from the back, use negative numbers:

listy[-2]  # returns the second-to-last element, i.e. 4
List Slices
You may access slices of a list using the slicing syntax.

["a", "b", "c", "d"][1:3]  # returns ["b", "c"]
List Comprehension
Opshin supports Python's list comprehension syntax. This allows for very compact list initialization:

squares = [x**2 for x in listy]
len(x)
The len method returns the length of the list as an int:

lenny: int = len(listy) 
lenny == 5  # True
Membership using in
You can check whether some element is included in a list of elements using the keyword in.

4 in [1, 2, 3, 4, 5]  # True
100 in range(10)  # False
Empty lists
Empty lists may only be created in annotated assignments. This is to ensure that the type of the empty list can be correctly inferred.

a = []  # Fails! Unclear what type this expression has!

a: List[int] = [] # This works!
Dict[k, v]
The Dict type represents a map from keys of type k to values of type v. It works just like the dict type in Python.

# A dictionary storing scores in a game.
scores: Dict[str, int] = {"god_binder": 12, "radio_knight": 42}
Dictionary Access
A dictionary implements a map. In order to find the mapped value of element x we can access it in the dictionary via dict[x].

scores["god_binder"]  # returns 12
Take care when accessing values that are not contained in the dictionary - in case of missing keys, the contract will fail immediately.

scores["peter_pan"]  # fails with "KeyError"
If you are not sure whether a key maps to something in the dictionary use dict.get(x, d). It will try to return the value mapped to by x in the dictionary. If x is not present it will return d.

It is important that d is of the value type v to guarantee type safety.

scores.get("god_binder", 0)  # returns 12
scores.get("peter_pan", 0)  # returns 0
.keys()
The .keys() method returns a list of the keys in a dictionary,

players: List[str] = scores.keys() # ["god_binder", "radio_knight"]
.values()
The .values() method returns a list of all the values in a dictionary.

raw_scores: List[int] = scores.values() # [12, 42]
.items()
The .items() method returns a tuple of the each key-value pair in the dictionary. This is particularly useful if you want to iterate over all pairs contained in a dictionary.

for username, score in scores.items():
    print(f"{username} scored: {score}")
    # prints first "god_binder scored: 12" and then "radio_knight scored: 42"

Container Types

If you want to define a custom class to be used in Opshin, it must be a dataclass which inherits from the PlutusData class which can be imported from opshin.prelude.

from opshin.prelude import *

@dataclass()
class Person(PlutusData):
    # Every person has a UTF8 encoded name
    name: bytes
    # Every person has a year of birth
    birthyear: int
PlutusData may contain only bytes, int, dicts, lists or other dataclasses.

Note that str and None are not valid field types of PlutusData.

Constructing objects
You can construct an object by calling the classname with the variables in order defined in the class.

a = Person(b"Billy", 1970)
Attribute access
All named attributes defined in the class body are accessible by object.attribute. For example, to access the name of a person we would run

print(a.name)  # prints b"Billy"
Union types
It may happen that you allow more than a single type of data for your application (think of a Smart Contract that allows different operations on it). In this case, you may define a Union[A, B, ...] type. This expresses that a variable may be of either of the classes inside the square brackets.

@dataclass()
class Plant(PlutusData):
    CONSTR_ID = 1
    # Plants have no further properties

@dataclass()
class Animal(PlutusData):
    CONSTR_ID = 2
    # Animals have a name too!
    name: bytes
    # They also have an owner, which is another dataclass
    owner: Person


# Note all of these classes have distinct CONSTR_ID values
CityDweller = Union[Animal, Plant, Person]


# Both assignments are fine, because a is annotated
# to be of the Union type and can be of either class
c: CityDweller = Plant()
c = Animal(b"jackie", a)
Importantly, you need to set the CONSTR_ID of Classes that occur in a Union to distinct values. On-Chain, classes are only distinguished by their CONSTR_ID value. If omitted, the CONSTR_ID defaults to an almost-unique determinstic value based on the Class definition.

Type casts
If a variable is of an Union type we may still want to distinguish how we handle them based on the actual type. For this, we can use the function isinstance. isinstance(x, A) returns True if value x is an instance of class A (which is not a Union type!).

# this is forbidden!
# If a is a Plant or Animal, it does not have a birthyear so this operation will fail.
print(a.birthyear)

if isinstance(a, Person):
    # Here its okay
    # OpShin recognizes the isinstance check and knows that
    # a is of type Person in this branch of the condition
    print(a.birthyear)
We can combine isinstance calls and access shared attributes across classes.

if isinstance(a, Person) or isinstance(a, Animal):
    # a is of type Union[Person, Animal] in this branch
    # Both classes have the same attribute at the same position
    # so we can access it in either case
    print(a.name)
You can also form the complement of type casts.

a: Union[Person, Animal] = ...
if isinstance(a, Person):
    # a is of type Person in this branch
    print(a.birthyear)
else:
    # a is of type Animal in this branch
    print(a.owner)
Note that you can also use str / print directly to get a very informative representation of the object

print(a)
# "Person(name=b'Billy', birthyear=1970)"
.to_cbor()
To obtain the CBOR representation of an object, you may call its to_cbor method. This will return the bytes representing an object in CBOR.

print(a.to_cbor().hex())
# prints "d8799f4542696c6c791907b2ff"

Custom Classes

Variables in Opshin are declared just like you'd expect them to in Python:

# A simple variable declaration
x = 5 

# A variable declaration with annotated type, x must be an integer
x: int = 5 

# Variables in Opshin can be mutated.
x += 1
Note: For now int is the only number type available in Opshin. fractions are coming soon.

Type annotation
If you want to make sure that a variable has the type you expect it to have you may use type annotation at the time of assinging a variable.

x: int = some_function()
This will make sure that some_function actually returns an integer.

Annotations can also be used for type up- and downcasts. For example if you receive a value y of type Union[A, B] you can run

z: A = y
This will cast y to type A in the type system but will not check the type during runtime. Use with care.

The other way around, if you receive a value of type A but you may want to use it as a Union[A, B] you can run

z: Union[A, B] = y
This will allow you to also store objects of type B in z later in the code.

Note that the type of a variable can not be changed after initialization. This is true as of version 0.19.0 and may change again in a later version.

Tuple Assignments
Opshin supports Python's tuple assignment syntax:


a, b = 3, 7

Variables

Opshin uses if, elif and else statements for conditional control flow. elif is a short form of else if and behaves like you would expect it.

if
n = 4
if n < 5:
    print("Less than 5.")
elif n == 5:
    print("Equal to 5.")
else:
    print("Greater than 5.")
pass
This statement does not do anything. It is mainly used to show the compiler that you respect an indent for an otherwise empty control flow branch.

if check:
    pass
else:
    some_important_function()
assert
The assert statement is an important tool in Smart Contracts to check that conditions of the contract are met. It checks that a statement is correct and otherwise immediately halts the contract with an error message if provided.

assert money_locked_in_contract >= 100000, f"Expected 100000 but only received {money_locked_in_contract}"
Semantically it can be imagined like this:

if condition_met:
    pass
else:
    print(error_message)
    <fails contract>
Informative error messages will save you plenty of time when executing and debugging your off-chain transactions.

Conditional Statements

Opsin supports both while and for loops.

while loops
while loops in Opshin work just like in Python. They have a body and a boolean expression and the code in the body is looped while the boolean expression returns True.

count = 0

while count < 5:
    print("'count' is ", count, ".")
    count += 1
for loops
for loops are use for iterating over lists and other iterables. The loop through the elements of the iterable and executes the code in the block using the element from the list.

names = ["Ada", "Voltaire", "Basho"]
for name in names:
    print(name)

for i in range(10):
    ...
Dictionaries are also iterables and they can be iterated over using a for loop:


scores = {"Byron": 1200, "Vasil": 900, "Ada": 1790, "Shelley": 1400}

# Iterating over the keys and values using '.items()'
for name, score in scores.items():
    print(name + " scored: " + str(score))

# Iterating over the keys using '.keys()'
for name in scores.keys():
    ...

# Iterating over the values using '.values()'
for score in scores.values():
    ...

Loop Statements

Regular Functions
Functions in Opshin should have type annotations for the arguments and the return value. Return statements can be placed anywhere inside a function. Note that all return statements must have a type compatible with the annotated return type.

def fibonacci(n: int) -> int:
    if n < 2:
        return 1
    else:
        return fibonacci(n-1) + fibonacci(n-2)
As shown, Opshin functions support recursion. A function foo is called as foo(x, y, ...) with arguments x, y, etc.

If the function does not have a return statement in some path, the implicit return value is None. This can be useful for code that has side-effects, such as assertion checks.

def check_valid(n: int) -> None:
  assert n > 0, f"Invalid negative int encountered: {n}"
If the type annotation is missing for any field, the implicit annotation is Any. This may be fine for your use case, but note that this is slightly less efficient (and less clear to the reader) than a properly type annotated function.

Note that you can define functions locally and within other functions, so that they do not clutter your namespace and can not be used in the wrong context. The following is legal.

def mul_twice(x: int) -> int:

   def mul_once(x: int) -> int:
        return x * x

   return mul_once(x) * mul_once(x)

print(mul_twice(5))
# "625"
Lambdas and list expressions
Generally OpShin does not support the use of lambda functions, as they don't allow specifying types in the function signature. Instead, consider using a local function definitions or list expressions. For example instead of the following expression

ys = map(lambda x: 2*x, filter(lambda x: x > 0, xs)) # does not work.
You could either define local functions like this

def greater_zero(x: int) -> bool:
  return x > 0

def mul_2(x: int) -> int:
  return 2*x

ys = map(mul_2, filter(greater_zero, xs)) # does not work.
Or you can express this very compactly and readable directly in a list expression like this

ys = [2*x for x in xs if x > 0] # works!

Functions

A growing list of the Python builtin functions is being implemented in OpShin. It will be documented here.

all(x: List[bool]) -> bool
Returns whether all booleans in a list are True.

any(x: List[bool]) -> bool
Returns whether any of the booleans in a list is True.

abs(x: int) -> int
Returns the absolute value of an integer.

bytes(x: int) -> bytes
Returns a bytestring with 0s of length x.

bytes(x: List[int]) -> bytes
Returns a bytestring where every byte corresponds to one integers in x.

chr(x: int) -> str
Returns the character for unicode code point x.

hex(x: int) -> str
Returns the hexadecimal representation of an integer.

len(x: Union[bytes, List[Anything]]) -> int
Returns a the length of x for bytes and lists.

max(x: List[int]) -> int
Returns the maximum of all integers in a list.

min(x: List[int]) -> int
Returns the minimum of all integers in a list.

oct(x: int) -> str
Returns the octal representation of an integer.

pow(x: int, y: int) -> str
Returns xy

range(x: int) -> List[int]
Returns the integers from 0 to x-1 as a list.

reversed(x: List[Anything]) -> List[Anything]
Returns the reversal of list x.

str(x: Anything) -> str
Returns a stringified representation of x.

sum(x: List[int]) -> int
Returns the sum of all integers in a list.

Builtins

Module opshin.std

OpShin provides a few features in its standard libary. You can import modules from there (i.e. the opshin.std.fractions module) with

from opshin.std.fractions import *
EXPAND SOURCE CODE
Sub-modules
opshin.std.bitmap
The BitMap library provides tools to interact with a highly efficient datastructure that stores boolean values with minimal overhead (1 bit per bool)

opshin.std.builtins
A special libary that gives direct access to UPLC built-ins It is valid code and parts of it may be copied if not all built-ins are required by the user.

opshin.std.fractions
An implementation of fractions in opshin This does not maintain smallest possible notation invariants for the sake of efficiency - the user has full …

opshin.std.hashlib
A std library that imports all valid hash functions from the builtin python hashlib library: If you want to have all hash functions in scope, simply …

opshin.std.integrity
A special libary that gives access to a function that checks the integrity of PlutusDatum objects.

opshin.std.math
An implementation of some math operations in opshin

Standard library

This section will teach you how to write Cardano smart contracts in Opshin.

Smart Contract Tour

Congrats, if you've gotten to this section you now understand the basics of Opshin. Now we get to put those together to write smart contracts.

If you remember from the page on the EUTXO model. UTXOs are like bundles of money and a datum stored on the blockchain, they are locked by a validator script which is run when someone attempts to spend that UTXO. Of course, this is only the case for spending contracts i.e. Contract addresses that hold actual UTxOs. Minting Scripts and other types of validators do not have a datum as parameter.

Smart contract development on Cardano centers around writing validators in a way that allows only transactions that follow the business logic of the application. Every validator is a simple pure function that takes two to three arguments:

Datum: This is data stored alongside the UTXO on the blockchain (in the case of Spending Validators i.e. Contract Addresses).
Redeemer: This data included in the transaction that attempts to spend the UTXO.
Script Context: This object stores information about the transaction attempting to spend the UTXO.
Note: Datum and Redeemer are entirely controlled by the user and may not be trusted, but the Script Context may be trusted as it is assembled by the node. Consequently, the Datum and the Redeemer can be of any type depending on the contract, but the Script Context is always of type ScriptContext.

A validator either does not fail or fails (i.e. through the use of assert or an out-of-index array access). If it does not fail then, independent of the returned value, the contract execution is counted as a success and the contract validates the transaction.

Note: Other Smart Contract languages return a boolean value that determines the success of the transaction. If you return False in OpShin, the contract will succeed in any case.

Example Validator - Gift Contract
In this simple example we'll write a gift contract that will allow a user create a gift UTXO that can be spent by:

The creator cancelling the gift and spending the UTXO. (1)
The recipient claiming the gift and spending the UTXO. (2)
# gift.py

# The Opshin prelude contains a lot useful types and functions 
from opshin.prelude import *


# Custom Datum
@dataclass()
class GiftDatum(PlutusData):
    # The public key hash of the gift creator.
    # Used for cancelling the gift and refunding the creator (1).
    creator_pubkeyhash: bytes

    # The public key hash of the gift recipient.
    # Used by the recipient for collecting the gift (2).
    recipient_pubkeyhash: bytes


def validator(datum: GiftDatum, redeemer: None, context: ScriptContext) -> None:
    # Check that we are indeed spending a UTxO
    assert isinstance(context.purpose, Spending), "Wrong type of script invocation"

    # Confirm the creator signed the transaction in scenario (1).
    creator_is_cancelling_gift = datum.creator_pubkeyhash in context.tx_info.signatories

    # Confirm the recipient signed the transaction in scenario (2).
    recipient_is_collecting_gift = datum.recipient_pubkeyhash in context.tx_info.signatories

    assert creator_is_cancelling_gift or recipient_is_collecting_gift, "Required signature missing"
This might be a bit to take in, especially the logic for checking the signatures. The most important part is that you see the parameters and the return type resp. the assert statements actually controlling the validation. In the next chapter we'll do a deep dive into the single most important object in Cardano smart contracts, the ScriptContext.

Validator Scripts

Majority of the logic of smart contracts has to do with making assertions about certain properties of the ScriptContext. It contains a lot of useful information such as:

When is the transaction?
What will the inputs of the transactions be?
What will the outputs of the transaction?
All of these things are contained in the ScriptContext object passed into the contract as the last argument. This section covers the most interesting parts of the Script Context - if you want to learn more check out the full documentation at the module description

ScriptContext
The ScriptContext is defined as:

@dataclass()
class ScriptContext(PlutusData):
    """
    Auxiliary information about the transaction and reason for invocation of the called script.
    """

    tx_info: TxInfo
    purpose: ScriptPurpose

The most important field in the ScriptContext is the tx_info field which is of type TxInfo.

TxInfo
@dataclass()
class TxInfo(PlutusData):
    """
    A complex agglomeration of everything that could be of interest to the executed script, regarding the transaction
    that invoked the script
    """

    # The input UTXOs of the transaction.
    inputs: List[TxInInfo]
    # The reference UTXOs of the transaction.
    reference_inputs: List[TxInInfo]
    # The output UTXOs created by the transaction.
    outputs: List[TxOut]
    # Transaction fee to be payed for the transaction.
    fee: Value
    # The value minted in the transaction.
    mint: Value
    dcert: List[DCert]
    wdrl: Dict[StakingCredential, int]
    valid_range: POSIXTimeRange
    # The signatures for the transaction.
    signatories: List[PubKeyHash]
    redeemers: Dict[ScriptPurpose, Redeemer]
    data: Dict[DatumHash, Datum]
    # The ID of the transaction.
    id: TxId
TxInInfo
This type contains data about a UTXO being used as a transaction input.

@dataclass()
class TxInInfo(PlutusData):
    """
    The plutus representation of an transaction output, that is consumed by the transaction.
    """

    out_ref: TxOutRef
    resolved: TxOut
TxOut
This type contains data about a UTXO.


@dataclass()
class TxOut(PlutusData):
    """
    The plutus representation of an transaction output, consisting of
    - address: address owning this output
    - value: tokens associated with this output
    - datum: datum associated with this output
    - reference_script: reference script associated with this output
    """

    address: Address
    value: Value
    datum: OutputDatum
    reference_script: Union[NoScriptHash, SomeScriptHash]

The ScriptContext

In a lot of contracts, time is of the essence. Properly handling time is essential for a lot of contracts like auctions and swaps.

The valid_range property in the ScriptContext specifies within what time the transaction can be submitted, it's used to constrain the time of the transaction. It's of type POSIXTimeRange.

POSIXTimeRange
The POSIXTimeRange type is used to specify a time range.

dataclass()
class POSIXTimeRange(PlutusData):
    """
    Time range in which this transaction can be executed
    """

    # Lower bound for the execution of the transaction
    # Can be negative infinity or a int.
    lower_bound: LowerBoundPOSIXTime
    # Upper bound for the execution of the transaction
    # Can be positive infinity or a int.
    upper_bound: UpperBoundPOSIXTime
A POSIXTimeRange can be visualized like a subsection of a numberline starting from negative infinity(-∞) to positive infinity (+∞)

         ⬤-------------→⬤
-∞       -3 -2  -1   0   1   2   3       +∞
 └┴┴┴┴┴─┴─┴──┴───┴───┴───┴───┴───┴─┴─┴┴┴┴┘ 
Useful Methods
Helper functions for the POSIXTimeRange type are stored in opshin.ledger.interval.

make_range(lower_bound: int, upper_bound: int) -> POSIXTimeRange
This takes a the lower bound as the first argument and the upper bound as the second argument makes a POSIXTimeRange that starts from lower_bound and ends at upper_bound.

valid_range = make_range(-3, 2)
This can be visualized as:

     lower_bound        upper_bound
          ⬤----------------→⬤
-∞       -3 -2  -1   0   1   2   3       +∞
 └┴┴┴┴┴─┴─┴──┴───┴───┴───┴───┴───┴─┴─┴┴┴┴┘ 
make_from(lower_bound: int) -> POSIXTimeRange
This takes a the lower bound as the first argument and makes a POSIXTimeRange that starts from lower_bound and ends at positive infinity.

valid_range = make_from(-1)
This can be visualized as:

            lower_bound     
                 ⬤---------------------→⬤
-∞       -3 -2  -1   0   1   2   3       +∞
 └┴┴┴┴┴─┴─┴──┴───┴───┴───┴───┴───┴─┴─┴┴┴┴┘ 
make_to(upper_bound: int) -> POSIXTimeRange
This takes a the upper bound as the first argument and makes a POSIXTimeRange that starts from negative infinity and ends at upper_bound.

valid_range = make_to(1)
This can be visualized as:

                    upper_bound 
 ⬤---------------------→⬤
-∞       -3 -2  -1   0   1   2   3       +∞
 └┴┴┴┴┴─┴─┴──┴───┴───┴───┴───┴───┴─┴─┴┴┴┴┘ 
Vesting Contract
To really grok how time is managed on Cardano we'll write a simple vesting contract.

Handling Time

This section contains a few selected, advanced use cases of OpShin.

Constant Folding
OpShin supports the command-line flag --constant-folding or short --cf. With this flag, every expression is evaluated at compile time by the python eval command. On one hand this enables the precomputation of expensive constants in your code. Specifically it evaluates all expressions that invoke only constants or variables that are declared exactly once in the contract. print statements are not pre-evaluated. For example, the following expressions would be folded at compile time:

0 == 1  # evaluates to False

@dataclass
class A(PlutusData):
    a: int
    b: bytes

A(0, b"") # evaluates to the object

def foo(x):
    return x

foo(0) # evaluates to 0

bar = 2
bar = 1
bar + 1  # is not evaluated at compile time
Forcing three parameters
By setting the flag --force-three-params you can enable the contract to act with any script purpose (i.e. minting, spending, certification and withdrawal).

When a script invoked with a minting, certificaton or withdrawal purpose, the validator function is called such that the first parameter of the contract (the datum) is set to Nothing() (a PlutusData object with no fields and constructor id 6). Therefore, the compiler enforces a union type that includes Nothing as an option when using the three parameter force flag.

An example of a script that acts as both minting and spending validator can be found in the wrapped_token example script.

Checking the integrity of objects
OpShin never checks that an object adheres to the structure that is declared for its parameters. The simple reason is that this is costly and usually not necessary. Most of the time an equality comparison (==) between PlutusData objects is sufficient (and fast).

There are cases where you want to ensure the integrity of a datum however. For example in an AMM setting where the pool datum will be re-used and potentially re-written in subsequent calls. In order to prevent malicious actors from making the datum too big to fit in subsequent transactions or to prevent them from writing values of invalid types into the object, you may use check_integrity.

An example use case is found below. This contract will fail if anything but a PlutusData object with constructor id 2 and two fields, first integer and second bytes, is passed as a datum into the contract.

Note: Yes, this implies that without the explicit check the contract may pass with whatever type d is, since its field or constructor id are never explicitly accessed.


from opshin.prelude import *
from opshin.std.integrity import check_integrity

@dataclass
class A(PlutusData)
    CONSTR_ID = 2
    a: int
    b: bytes

def validator(d: A, r: int, c: ScriptContext):
    check_integrity(d)

Advanced Topics

Module opshin.ledger
OpShin provides some helper classes that define concepts introduced in PlutusTx and used by the cardano node to encode data. In particular you find the definition of the entire Script Context for Plutus V2 in the file opshin.ledger.api_v2.

from opshin.ledger.api_v2 import *
EXPAND SOURCE CODE
Sub-modules
opshin.ledger.api_v2
The PlutusV2 ledger API. All classes involved in defining the ScriptContext passed by the node.

opshin.ledger.interval
A library to assist with interval handling

Ledger definitions

RecursionError: maximum recursion depth exceeded
This may happen when your contract is too large. Try setting the flag --recursion-limit to something high like 2000. If it does not go away even with values above i.e. 10000, please open an issue.

Common Issues when interacting with OpShin

     Getting Started with Opshin

If you want to learn more about OpShin you can find additional resources at these points.

OpShin Pioneer Program
Check out the opshin-pioneer-program for a host of educational example contracts, test cases and off-chain code.

Example repository
Check out the opshin-starter-kit repository for a quick start in setting up a development environment and compiling some sample contracts yourself.

You can replace the contracts in your local copy of the repository with code from the examples section here to start exploring different contracts.

Awesome Opshin
The "Awesome Opshin" repository contains a host of DApps, Tutorials and other resources written in OpShin or suitable for learning it. It can be found in the awesome-opshin repository.

Developer Community and Questions
This repository contains a discussions page. Feel free to open up a new discussion with questions regarding development using opshin and using certain features. Others may be able to help you and will also benefit from the previously shared questions.

Check out the community here

You can also chat with other developers in the welcoming discord community of OpShin

Help us improve OpShin by participating in this survey!

A short guide on Writing a Smart Contract
A short non-complete introduction in starting to write smart contracts follows.

Make sure you understand EUTxOs, Addresses, Validators etc on Cardano. There is a wonderful crashcourse by @KtorZ. The contract will work on these concepts
Make sure you understand python. opshin works like python and uses python. There are tons of tutorials for python, choose what suits you best.
Make sure your contract is valid python and the types check out. Write simple contracts first and run them using opshin eval to get a feeling for how they work.
Make sure your contract is valid opshin code. Run opshin compile and look at the compiler erros for guidance along what works and doesn't work and why.
Dig into the examples to understand common patterns. Check out the prelude for understanding how the Script Context is structured and how complex datums are defined.
Check out the sample repository to find a sample setup for developing your own contract.
In summary, a smart contract in opshin is defined by the function validator in your contract file. The function validates that a specific value can be spent, minted, burned, withdrawn etc, depending on where it is invoked/used as a credential. If the function fails (i.e. raises an error of any kind such as a KeyError or AssertionError) the validation is denied, and the funds can not be spent, minted, burned etc.

There is a subtle difference here in comparison to most other Smart Contract languages. In opshin a validator may return anything (in particular also False) - as long as it does not fail, the execution is considered valid. This is more similar to how contracts in Solidity always pass, unless they run out of gas or hit an error. So make sure to assert what you want to ensure to hold for validation!

A simple contract called the "Gift Contract" verifies that only specific wallets can withdraw money. They are authenticated by a signature. If you don't understand what a pubkeyhash is and how this validates anything, check out this gentle introduction into Cardanos EUTxO. Also see the tutorial by pycardano for explanations on what each of the parameters to the validator means and how to build transactions with the contract.

Minting policies expect only a redeemer and script context as argument. Check out the Architecture guide for details on how to write double functioning contracts. The examples folder contains more examples. Also check out the opshin-pioneer-program and opshin-starter-kit repo.

The small print
Not every valid python program is a valid smart contract. Not all language features of python will or can be supported. The reasons are mainly of practical nature (i.e. we can't infer types when functions like eval are allowed). Specifically, only a pure subset of python is allowed. Further, only immutable objects may be generated.

For your program to be accepted, make sure to only make use of language constructs supported by the compiler. You will be notified of which constructs are not supported when trying to compile.

You can also make use of the built-in linting command and check it for example with the following command:

opshin lint spending examples/smart_contracts/assert_sum.py
Name
Eopsin (Korean: 업신; Hanja: 業神) is the goddess of the storage and wealth in Korean mythology and shamanism. [...] Eopsin was believed to be a pitch-black snake that had ears. [1]

Since this project tries to merge Python (a large serpent) and Pluto/Plutus (Greek wealth gods), the name appears fitting. The name e_opsin is pronounced op-shin. e

Additional Resources

Introduction to the OpShin PROGRAMMING LANGUAGE

Opshin is a pythonic language for writing smart contracts on the Cardano blockchain. The goal of Opshin is to reduce the barrier of entry in Smart Contract development on Cardano. Opshin is a strict subset of Python, this is means anyone who knows Python can get up to speed on Opshin pretty quickly.

Introduction to the OpShin programming languages

The OpShin Book: Introduction to the OpShin programming languages

Course Details

Level

Ratings

Modules

Lessons

Holder $WORK Price

Contact Us

Documentation

Navigation