Package `opshin`

opshin

You are building what you want. Why not also build how you want?

This is an implementation of smart contracts for Cardano which are written in a strict subset of valid Python. The general philosophy of this project is to write a compiler that ensure the following:

If the program compiles then:

it is a valid Python program
the output running it with python is the same as running it on-chain.

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

Getting Started

Check out the OpShin Book for an introduction to this tool and details into writing smart contracts. This document will just outline the basic usage of the tool.

Installation

Install any of the supported Python versions. Then run

python -m pip install opshin

Writing a Smart Contract

Check out the OpShin Book for an introduction to this tool and details into writing smart contracts.

Compiling

Write your program in python. You may start with the content of examples. Arguments to scripts are passed in as Plutus Data objects in JSON notation.

You can run any of the following commands

# Evaluate script in Python - this can be used to make sure there are no obvious errors
# The parameter for smart contracts is the ScriptContext, which defines the entire transaction
opshin eval examples/smart_contracts/assert_sum.py d8799fd8799f9fd8799fd8799f58205c25c47563872458e8607590c90c6ddadd0295f38c628426c4877185e721507a00ffd8799fd8799fd87a9f581c41582020bb0782bb76ce4fcd7ea2c2f3c565e1fd41a79ac7ddb3e145ffd87a80ffa140a1401a002dc6c0d87b9f14ffd87a80ffffff809fd8799fd8799fd8799f581c25d14bb0185eedffcaa02cdd3bfa779bfc9df3555c64b0e91ed41273ffd87a80ffa140a1401a002ae91fd87980d87a80ffff1a0002dda1a080a0d8799fd8799fd87a9f1b00000199c356d9a8ffd87a80ffd8799fd87a9f1b00000199c3661be8ffd87980ffff9f581c25d14bb0185eedffcaa02cdd3bfa779bfc9df3555c64b0e91ed41273ffa1d87a9fd8799f58205c25c47563872458e8607590c90c6ddadd0295f38c628426c4877185e721507a00ffff16a05820801ee2f936eb1dac69a6da43e17b09ade9bc8c3ed887066f350562d94c681573a080d87a80d87a80ff16d87a9fd8799f58205c25c47563872458e8607590c90c6ddadd0295f38c628426c4877185e721507a00ffd8799f14ffffff

# Compile script to 'uplc', the Cardano Smart Contract assembly
opshin compile examples/smart_contracts/assert_sum.py

Furthermore, you can add a shebang to the first line of the python file to indicate that it represents an opshin smart contract. You can choose from the following options:

a general shebang: #!opshin, which represents opshin eval
or a more specific purpose: #!/usr/bin/env -S opshin eval

By doing so, you can transform your python file to an executable: chmod +x your_file.py and execute it with ./your_file.py, which will run opshin eval any ./your_file.py under the hood.

Deploying

The deploy process generates all artifacts required for usage with common libraries like pycardano, lucid and the cardano-cli.

# Automatically generate all artifacts needed for using this contract
opshin build examples/smart_contracts/assert_sum.py

See the tutorial by pycardano for explanations how to build transactions with opshin contracts.

API for Smart Contracts

The python interface offers a simple API to compile, load, apply parameters and evaluate smart contracts.

from opshin.builder import *

# Build a validator script from a python file that contains a validator function
contract = build("path/to/contract.py")

# You can apply parameters to the contract during compilation
contract = build("path/to/contract.py", arg1, arg2, arg3)

# Store the compilation artifacts in a folder
contract.dump("path/to/store")

# You can also load a compiled contract from a path
contract = load("path/to/store")

# And apply parameters after loading a contract
contract = contract.apply_parameters(arg1, arg2, arg3)

# The artifacts contain the compiled script, the policy ID and the addresses and blueprint
contract_addr = contract.mainnet_addr
contract_blueprint = contract.blueprint

Debugging artefacts

For debugging purposes, you can also run the eval_uplc and compile_pluto commands to see the intermediate representations of your smart contract.

# Compile script to 'uplc', and evaluate the script in UPLC (for debugging purposes)
opshin eval_uplc examples/smart_contracts/assert_sum.py d8799fd8799f9fd8799fd8799f58205c25c47563872458e8607590c90c6ddadd0295f38c628426c4877185e721507a00ffd8799fd8799fd87a9f581c41582020bb0782bb76ce4fcd7ea2c2f3c565e1fd41a79ac7ddb3e145ffd87a80ffa140a1401a002dc6c0d87b9f14ffd87a80ffffff809fd8799fd8799fd8799f581c25d14bb0185eedffcaa02cdd3bfa779bfc9df3555c64b0e91ed41273ffd87a80ffa140a1401a002ae91fd87980d87a80ffff1a0002dda1a080a0d8799fd8799fd87a9f1b00000199c356d9a8ffd87a80ffd8799fd87a9f1b00000199c3661be8ffd87980ffff9f581c25d14bb0185eedffcaa02cdd3bfa779bfc9df3555c64b0e91ed41273ffa1d87a9fd8799f58205c25c47563872458e8607590c90c6ddadd0295f38c628426c4877185e721507a00ffff16a05820801ee2f936eb1dac69a6da43e17b09ade9bc8c3ed887066f350562d94c681573a080d87a80d87a80ff16d87a9fd8799f58205c25c47563872458e8607590c90c6ddadd0295f38c628426c4877185e721507a00ffd8799f14ffffff

# Compile script to 'pluto', an intermediate language (for debugging purposes)
opshin compile_pluto examples/smart_contracts/assert_sum.py

Contributing

Developing and Technical Documentation

Generally, all contributions on the code side are very welcome. To get an overview over the architecture and idea behind OpShin, check out the Technical Documentation. A bug bounty has been set up and funded by Project Catalyst, which awards Github issue resolution with ADA rewards. This is a great opportunity to get involved and earn some ADA. Check out the detailed introduction to the bounty program for more information.

Binary Size Tracking

OpShin includes tooling to track binary size changes across different optimization levels to help catch regressions:

# Check binary sizes against latest release
python scripts/check_binary_sizes.py

The binary size tracker automatically runs on pull requests and reports significant changes. See Binary Size Tracker Documentation for details.

Sponsoring

You can sponsor the development of opshin through GitHub or Patreon or just by sending ADA. Drop me a message on social media and let me know what it is for.

Patreon Support OpShin at Patreon to enjoy member benefits!
GitHub Sponsor the developers of this project through the button "Sponsor" next to them
ADA Donation in ADA can be submitted to $opshin or addr1qyz3vgd5xxevjy2rvqevz9n7n7dney8n6hqggp23479fm6vwpj9clsvsf85cd4xc59zjztr5zwpummwckmzr2myjwjns74lhmr.

Supporters

Expand source code

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
.. include:: ../README.md
"""

import warnings
import importlib.metadata

__version__ = importlib.metadata.version(__package__ or __name__)
__author__ = "nielstron"
__author_email__ = "niels@opshin.dev"
__copyright__ = "Copyright (C) 2025 nielstron"
__license__ = "MIT"
__url__ = "https://github.com/OpShin/opshin"


try:
    from .compiler import *
    from .builder import *
    from .util import CompilerError
except ImportError as e:
    warnings.warn(ImportWarning(e))

Sub-modules

opshin.bridge: Bridging tools between uplc and opshin
opshin.builder
opshin.compiler
opshin.compiler_config
opshin.fun_impls
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 …
opshin.optimize
opshin.prelude
opshin.rewrite
opshin.std: OpShin provides a few features in its standard library. You can import modules from there (i.e. the fractions module) with …
opshin.type_impls
opshin.type_inference: An aggressive type inference based on the work of Aycock [1]. It only allows a subset of legal python operations which allow us to infer the type of …
opshin.typed_ast
opshin.util