Sapio is a Rust framework for describing Bitcoin contracts as graphs of transactions. Contracts compile into spending conditions, transaction templates, and metadata; the tooling can bind those templates to UTXOs and produce PSBTs.
This checkout is undergoing modernization. The compiler, signing code and WASM boundary have regression fixes, and builds use a pinned stable Rust toolchain. The modernization plan records what is implemented and what still blocks a supported release.
Install Rust with rustup and a native C compiler. From the repository root:
cargo run --locked -p sapio --example payment
cargo test --locked --workspace --all-featuresRustup selects the version in rust-toolchain.toml. The
payment example compiles a 1,000-satoshi payment with
500 satoshis reserved for fees and prints the contract as JSON. It needs no node
or signer and does not fund or broadcast a transaction. The integration tests
start their own emulator on a local ephemeral port.
Native CTV compilation is a research target. A generated address does not establish that the target chain enforces CTV. Signer emulation has separate trust and availability assumptions. See the enforcement model before using either with funds.
For WASM modules and development checks, follow the development guide. The historical Designing Bitcoin Contracts with Sapio book contains broader examples; its older installation instructions are being revised.
The contract example catalog inventories every library family, all 18 WASM modules, and both runnable native examples, with regression coverage and the assumptions each construction still requires.
| Component | Purpose |
|---|---|
| sapio | Contract traits, compiler, transaction templates and linking |
| sapio-base | Bitcoin types, CTV hashing, amounts and shared formats |
| sapio-psbt | Taproot PSBT signing |
| sapio_macros | Rust contract authoring macros |
| cli | Contract, PSBT and emulator commands |
| plugins | WASM client ABI and host runtime |
| ctv_emulators | Signer-based CTV emulation |
| sapio-contrib | Contract library and research examples |
| plugin-example | Separately built WASM example workspace |
| integration_tests | Compilation, signing and finalization checks |
Read Jeremy Rubin's A Calculus of Covenants for the conceptual foundation. Development should preserve the connection between intended transitions, their verifier, their prover, and the assumptions under which they agree.
Sapio is licensed under MPL-2.0. Existing ownership and contribution terms have not been changed by this modernization.