Struct MerkleTreeWithHistory 

pub struct MerkleTreeWithHistory;

Merkle Tree with root history for privacy-preserving transactions

This struct provides methods to manage a fixed-depth binary Merkle tree that maintains a history of recent roots. When the tree is modified, it automatically preserves previous roots for membership proof verification.

Implementations

impl MerkleTreeWithHistory

pub fn init(env: &Env, levels: u32) -> Result<(), Error>

Initialize the Merkle tree with history

Creates a new Merkle tree with the specified number of levels. The tree is initialized with precomputed zero hashes at each level, and the initial root is set to the zero hash at the top level.

Arguments

• env - The Soroban environment
• levels - Number of levels in the Merkle tree (must be in range [1..32])

pub fn insert_two_leaves( env: &Env, leaf_1: U256, leaf_2: U256, ) -> Result<(u32, u32), Error>

Insert two leaves into the Merkle tree as siblings

Adds 2 new leaves to the Merkle tree and updates the root. The leaves are inserted at the next available index, and the tree is updated efficiently by only recomputing the hashes along the path to the root.

When the tree is modified, a new root is automatically created in the next history slot. The previous root remains valid for proof verification until it is overwritten after ROOT_HISTORY_SIZE rotations.

Arguments

• env - The Soroban environment
• leaf_1 - The left leaf value to insert (at even index)
• leaf_2 - The right leaf value to insert (at odd index)

Returns

Returns the indexes where leaves were inserted

pub fn is_known_root(env: &Env, root: &U256) -> Result<bool, Error>

Check if a root exists in the recent history

Searches the root history ring buffer to verify if a given root is valid. This allows proofs generated against recent tree states to be verified, providing some tolerance for latency between proof generation and submission.

Arguments

• env - The Soroban environment
• root - The Merkle root to check

Returns

Returns true if the root exists in the history buffer, false otherwise. Zero root always returns false.

pub fn get_last_root(env: &Env) -> Result<U256, Error>

Get the current Merkle root

Returns the most recent root hash of the Merkle tree.

Arguments

• env - The Soroban environment

Returns

Returns the current Merkle root as U256

pub fn hash_pair(env: &Env, left: U256, right: U256) -> U256

Hash two U256 values using Poseidon2 compression

Computes the Poseidon2 hash of two field elements in compression mode. This is the core hashing function used for Merkle tree operations.

Arguments

• env - The Soroban environment
• left - Left input value
• right - Right input value

Returns

The Poseidon2 hash result as U256