pymatt

WIP Python framework for MATT smart contracts

This repository contains a (very much Work In Progress) framework to create and test smart contracts using the OP_CHECKCONTRACTVERIFY opcode.

Prerequisites

• python (3.9+)
• pip
• docker

Installing the library

Optionally, create a python environment:

$ python -m venv venv
$ source venv/bin/activate

Install the library with:

$ pip install pymatt

Run bitcoin-inquisition MATT in regtest mode

The fastest way to get started is this docker container:

$ docker pull bigspider/bitcoin_matt
$ docker run -d -p 18443:18443 bigspider/bitcoin_matt

Alternatively, build the same yourself from this branch. Here's the bitcoin.conf file used for these examples:

bitcoin.conf

regtest=1
printtoconsole=1
server=1
txindex=1
fallbackfee=0.00001
minrelaytxfee=0
blockmintxfee=0

[regtest]
rpcbind=0.0.0.0
rpcallowip=0.0.0.0/0
rpcuser=rpcuser
rpcpassword=rpcpass

Case studies

The examples folder contains some utility scripts to work with regtest bitcoin-core:

• init.sh creates/loads and funds a wallet named testwallet. Run it once before the examples and you're good to go.
• fund.sh that allows to fund a certain address.

The following examples are currently implemented

• Vault [cli]: an implementation of a vault, largely compatible with OP_VAULT BIP-0345.
• Rock-Paper-Scissors [cli]: play Rock-Paper-Scissors on bitcoin.
• RAM [cli]: a a contract that uses a Merkle tree to store a vector of arbitrary length in size, with transitions that allow to modify one element of the vector.
• game256: Implements an end-2-end execution of the toy example for fraud proofs drafted in bitcoin-dev.

For the ones marked with [cli], a simple interactive tool allows to play with the contract. More code examples can be found in the test suite.

Docs

See the docs folder for high-level documentation on how to design smart contracts using MATT.

As the framework is still in development, we recommend looking at the code examples below for developer documentation on using pymatt.

Contribution

Prerequisites

The examples in this repository can be installed and set up using uv.

If you do not have uv installed, run one of the following commands.

Install using pipx

pipx install uv

Install using standalone installer (Darwin and Linux)

curl -LsSf https://astral.sh/uv/install.sh | sh

Install using Homebrew (Darwin)

brew install uv

The following commands help you set up and activate a Python virtual environment where uv can download project dependencies from the PyPI open-sourced registry defined under pyproject.toml file.

Set up environment and synchronize project dependencies

git clone git@github.com:Merkleize/pymatt.git
cd pymatt
uv venv --python 3.9
source .venv/bin/activate
uv sync --dev

Run examples

All the examples use the RPC_USER, RPC_PASSWORD, RPC_HOST, RPC_PORT environment variables to set up a connection with the regtest bitcoin node; the default values are the same as set in the container.

If they differ in your system, make sure to set them appropriately, or create a .env file similar to the following:

RPC_HOST = "localhost"
RPC_USER = "rpcuser"
RPC_PASSWORD = "rpcpass"
RPC_PORT = "18443"

NOTE: the examples do not handle fee management and will send transactions with 0 fees; those are rejected with the default settings of bitcoin-core.

If not using the container above, please see an example of custom bitcoin.conf to work with the scripts in this repository.

You can use the following command to install the extra dependencies required for running the examples in the repository.

Install dependencies for the examples

uv sync --dev --extra examples

Tests

This project uses pytest to run automated tests. Install the dependencies with:

uv sync --dev

The test suite requires a running instance of the MATT-enabled bitcoin-inquisition, for example using the container above. The init.sh script makes sure that a funded test wallet is loaded.

$ docker run -d -p 18443:18443 bigspider/bitcoin_matt
$ bash ./examples/init.sh

Then, run the tests with

$ pytest

Refer to the pytest documentation for more advanced options.

Report

Some tests produce additional illustrative info about the transactions produced during the contract execution, in a Markdown report called report.md.