chia_rs

A collection of Rust crates for working with the Chia blockchain. There are also Python bindings in the form of a wheel.

Prerequisites

• Python 3.9 or higher installed.
• The Rust toolchain must be installed.

Unit Tests

To run the unit tests for the whole workspace:

cargo test --workspace

Some slow tests are only enabled in optimized builds, so it may also be a good idea to run the tests in release mode:

cargo test --workspace --release

Python Linking

You may need a Python virtual environment activated for the tests to link properly, due to the pyo3 dependency in wheel.

You can setup a virtual environment with the following command:

python3 -m venv venv

Activate the virtual env:

. ./venv/bin/activate

or on Windows:

. ./venv/Scripts/activate

Python Tests

The wheel crate is a single Python wheel that exports bindings to various functionality in the repository, mostly from chia-consensus and chia-protocol.

It's built with maturin, so you need to have activated a python virtual environment for the build to work.

The bindings are tested with pytest. Before you run them, install the following dependencies:

pip install pytest pytest-xdist maturin typing-extensions

And build the Python wheel:

maturin develop -m wheel/Cargo.toml

Finally, you can run the Python binding tests:

pytest tests

Note that these tests can take several minutes to complete.

Benchmarks

To run benchmarks for a specific crate before you make changes:

cargo bench -- --save-baseline before

After you apply the changes, finish the benchmark:

cargo bench -- --save-baseline after
critcmp after before

You can also run all the benchmarks by including --workspace.

Note that you must include the flag before the --, for example:

cargo bench --workspace -- --save-baseline before

Precommit Hook

This repository has a pre-commit configuration, which is hooked into git by running:

pre-commit install --hook-type pre-commit --hook-type pre-push

It runs Prettier and then cargo fmt on all crates on every commit. When you push, it runs cargo clippy, cargo test, and cargo build.

To run all checks explicitly (without pushing), run:

pre-commit run --all --hook-stage pre-push

Fuzzers

Fuzzers can't be run or listed for the whole workspace, but only for individual crates. There is a tool to generate a fuzzing corpus from a blockchain database.

It's run like this:

cd crates/chia-tools
cargo run --release --bin gen-corpus -- --help

The following crates have fuzzers:

• chia-bls
• chia-consensus
• chia-protocol
• chia-puzzle-types
• clvm-utils

To list and run fuzzers:

cargo fuzz list
cargo +nightly fuzz run <name-of-fuzzer> --jobs=10

Bumping Version Number

Make sure you have cargo-workspaces installed:

cargo install cargo-workspaces

To bump the versions of all relevant crates:

cargo ws version --force "**" --all --no-git-commit

Select "minor update" if there has not been any incompatible API changes, otherwise "major update".