Crate simplicity

Expand description

§rust-simplicity

This is the official Rust library of the Simplicity Language.

Simplicity is a low-level, typed functional language designed to be a drop-in alternative for Bitcoin’s Tapscript. It offers static resource bounds and has a formal specification (in Rocq) which allows the creation of machine-checkable proofs of program behavior.

It is currently deployed on Blockstream’s Liquid, which is a sidechain resembling Bitcoin in many ways; but which differs in many Script-relevant ways (e.g. supporting multiple assets and using Confidential Transactions). We expect by the end of 2025 to directly support Bitcoin, so that Simplicity can be used on a custom regtest chain.

Simplicity is a very low-level language. If you are simply looking to develop with the language, you may wish to use SimplicityHL instead.

§Nodes

When creating and manipulating Simplicity programs, there are three node types that you may use when creating programs.

ConstructNode represents a program under construction. Type inference is done on the program as it is being built, which must be done within a scope containing a types::Context.
CommitNode represents a complete program for which witness and disconnect nodes are unpopulated. This can be used to produce a CMR, which in turn is used to generate an address for use on-chain.
RedeemNode represents a program as it is embedded on-chain. Unused nodes must be pruned, and any disconnect or witness nodes which remain must appear on-chain. This is the only node type which has a canonical encoding.

§Quick Start

use simplicity::node::CoreConstructible;
use simplicity::types::Context;
use simplicity::{ConstructNode, jet::Core};
use std::sync::Arc;

// Create a trivial Simplicity program
let program = Context::with_context(|ctx| {
    let construct = Arc::<ConstructNode<Core>>::unit(&ctx);
    construct.finalize_types().unwrap()
});

// Encode the program to bytes
let encoded: Vec<u8> = simplicity::write_to_vec(|w| {
    program.encode_without_witness(w)
});

Re-exports§

pub extern crate bitcoin;
pub extern crate byteorder;
pub extern crate elements;
pub extern crate ghost_cell;
pub extern crate hashes;
pub extern crate hex;
pub use crate::policy::sighash;
pub use crate::policy::Policy;
pub use crate::policy::Preimage32;
pub use crate::policy::Satisfier;
pub use crate::policy::SimplicityKey;
pub use crate::policy::ToXOnlyPubkey;
pub use crate::policy::Translator;
pub use crate::bit_machine::BitMachine;
pub use crate::node::CommitNode;
pub use crate::node::ConstructNode;
pub use crate::node::Hiding;
pub use crate::node::RedeemNode;
pub use simplicity_sys as ffi;

Modules§

bit_machine: Simplicity Execution
dag: General DAG iteration utilities
decode: Decoding
encode: Encoding
human_encoding: The Simplicity Human-Readable Encoding
jet: Simplicity jets
node: Simplicity Program Nodes
policy: Function-like Expression Language
types: Types and Type Inference

Macros§

decode_bits
impl_midstate_wrapper: Convenience macro for wrappers of Midstate.
impl_serde_string

Structs§

Amr: Annotated Merkle root
BitIter: Bitwise iterator formed from a wrapped bytewise iterator. Bytes are interpreted big-endian, i.e. MSB is returned first
BitWriter: Bitwise writer formed by wrapping a bytewise io::Write. Bits are written in big-endian order. Bytes are filled with zeroes for padding.
Cmr: Commitment Merkle root
Cost: CPU cost of a Simplicity expression.
EarlyEndOfStreamError: Attempted to read from a bit iterator, but there was no more data
FailEntropy: 512-bit opaque blob of data used to seed Fail nodes
Ihr: Identity Hash Root
Imr: Identity Merkle Root
NodeBounds: Bounds on the resources required by a node during execution on the Bit Machine
Tmr: Type Merkle root
Value: A Simplicity value.
ValueRef: Reference to a value, or to a sub-value of a value.
Word: A Simplicity word. A value of type TWO^(2^n) for some 0 ≤ n < 32.

Enums§

BitIterCloseError: Closed out a bit iterator and there was remaining data.
DecodeError: Error decoding a program from the bit encoding.
Error: Error type for simplicity
FinalizeError: Error finalizing a program (i.e. typechecking and pruning).
ParseError: Error parsing a program or witness (decoding it from a string encoding).
u2: Two-bit type used during decoding

Traits§

BitCollector: Functionality for Boolean iterators to collect their bits or bytes.
HasCmr: Trait for types that have a Commitment Merkle Root.

Functions§

encode_natural: Encode a positive integer to bits.
encode_value: Encode a value to bits.
encode_witness: Encode witness data to bits.
leaf_version: Return the version of Simplicity leaves inside a tap tree.
write_to_vec: Write the result of a bit operation into a byte vector and return the vector.