Why MerkleForge
MerkleForge is a Rust framework for authenticated data structures. You put data in, get a 32-byte root out, and hand out small proofs that anyone holding the root can check, without downloading the rest of the data.
The problem
Data verification is one of the major bottlenecks in modern blockchain networks. As systems process millions of transactions, checking the integrity of state data gets slow and resource-intensive. Every state lookup, transaction batch, and light-client proof depends on the speed and correctness of the underlying data structure.
The Rust ecosystem has strong cryptographic building blocks, but Merkle tree support is spread
across variant-specific crates. Libraries like rs-merkle focus on binary trees, while
Ethereum-specific tries are maintained separately. Teams end up stitching together tools with
different APIs, documentation depth, test coverage, and benchmark methodology.
The solution
MerkleForge unifies the three Merkle tree variants used across production systems behind one API:
| Variant | Typical use |
|---|---|
BinaryMerkleTree<H> | Transaction batching, Bitcoin-style SPV, logs, file chunks |
SparseMerkleTree<H> | Account state, key-value maps, Layer-2 rollups |
MerklePatriciaTrie<H> | Ethereum state roots, receipts, storage witnesses |
All three are generic over a HashFunction, implement the shared
MerkleTree<H> trait, and produce proofs that verify statelessly.
Features
- Unified API.
BinaryMerkleTree<H>,SparseMerkleTree<H>, andMerklePatriciaTrie<H>all implementMerkleTree<H>, so generic code works with any of them. - Pluggable hash functions. Swap SHA-256, Keccak-256, and BLAKE3 by changing one type parameter. Generics are monomorphised at compile time, so there is no runtime dispatch.
- Stateless verification. A light client verifies a leaf with the trusted root, the proof, and the leaf bytes. See Proofs & stateless verification.
- Domain separation built in. Leaves hash as
H(0x00 ‖ data)and internal nodes asH(0x01 ‖ left ‖ right), which blocks second-preimage attacks. See the mental model. - Reproducible benchmarks. A dedicated Criterion suite compares hashes, tree variants, and other Rust Merkle libraries. See Benchmarks.
- Tested. Unit, integration, property-based (Proptest), and Ethereum test-vector tests.
#![forbid(unsafe_code)]in every published crate.
The crates
| Crate | Role |
|---|---|
merkle-core | Traits, proof types, serialization helpers, and errors. no_std + alloc capable. |
merkleforge-hash | Sha256, Keccak256, and Blake3 adapters. |
merkle-variants | BinaryMerkleTree, SparseMerkleTree, and MerklePatriciaTrie. |
merkle-bench | Criterion benchmarks. Not published. |
Next steps
- Getting started: install the crates and verify your first proof.
- Mental model: leaves, roots, proofs, and verifiers in five minutes.
- Choosing a tree: which variant fits your data.