Struct UtxoMerkleTree 

pub struct UtxoMerkleTree { /* private fields */ }

UTXO Merkle Tree

Provides incremental updates for UTXO set with Merkle tree commitments. Wraps sparse-merkle-tree to provide UTXO-specific operations.

Implementations

impl UtxoMerkleTree

pub fn new() -> UtxoCommitmentResult<Self>

Create a new empty UTXO Merkle tree

pub fn root(&self) -> Hash

Get the Merkle root of the UTXO set

pub fn insert( &mut self, outpoint: OutPoint, utxo: UTXO, ) -> UtxoCommitmentResult<Hash>

Insert a UTXO into the tree

pub fn remove( &mut self, outpoint: &OutPoint, utxo: &UTXO, ) -> UtxoCommitmentResult<Hash>

Remove a UTXO from the tree (by updating with zero value)

pub fn get(&self, outpoint: &OutPoint) -> UtxoCommitmentResult<Option<UTXO>>

Get a UTXO from the tree

pub fn generate_commitment( &self, block_hash: Hash, block_height: Natural, ) -> UtxoCommitment

Generate a UTXO commitment

pub fn total_supply(&self) -> u64

Get total supply

pub fn utxo_count(&self) -> u64

Get UTXO count

pub fn generate_proof( &self, outpoint: &OutPoint, ) -> UtxoCommitmentResult<MerkleProof>

Generate a Merkle proof for a specific UTXO

Returns a proof that can be used to verify the UTXO exists in the tree.

pub fn serialize_proof_for_wire( proof: MerkleProof, ) -> UtxoCommitmentResult<Vec<u8>>

Serialize a Merkle proof to bytes for wire transmission.

Call this from network handlers (e.g. blvm-node) to avoid serde trait resolution issues when multiple serde versions exist in the dependency tree.

pub fn deserialize_proof_from_wire( bytes: &[u8], ) -> UtxoCommitmentResult<MerkleProof>

Deserialize a Merkle proof from bytes (inverse of serialize_proof_for_wire).

pub fn verify_commitment_supply( &self, commitment: &UtxoCommitment, ) -> UtxoCommitmentResult<bool>

Verify a UTXO commitment matches expected supply

Compares the total supply in the commitment against the expected Bitcoin supply at the given block height.

pub fn from_utxo_set(utxo_set: &UtxoSet) -> UtxoCommitmentResult<Self>

Rebuild tree from UtxoSet

Used after connect_block() to update the Merkle tree with the validated UTXO set. This rebuilds the entire tree.

pub fn update_from_utxo_set( &mut self, new_utxo_set: &UtxoSet, old_utxo_set: &UtxoSet, ) -> UtxoCommitmentResult<Hash>

Update tree from UtxoSet (incremental update)

Compares current tree state with new UtxoSet and applies only the differences. More efficient than full rebuild.

Note: This function requires knowing the previous UtxoSet to efficiently detect removals. If the previous set is not available, use from_utxo_set() to rebuild the tree.

Arguments

• new_utxo_set - The new UTXO set (from connect_block)
• old_utxo_set - The previous UTXO set (for detecting removals)

pub fn to_utxo_set(&self) -> UtxoCommitmentResult<UtxoSet>

Convert UtxoMerkleTree to UtxoSet

Iterates through the tree and builds a UtxoSet. Note: This is expensive as sparse merkle trees don’t support efficient iteration. Use only when necessary.

pub fn verify_commitment_root(&self, commitment: &UtxoCommitment) -> bool

Verify a commitment’s Merkle root matches the tree’s root

pub fn verify_utxo_proof( commitment: &UtxoCommitment, outpoint: &OutPoint, utxo: &UTXO, proof: MerkleProof, ) -> UtxoCommitmentResult<bool>

Verify a UTXO Merkle proof against a commitment’s root

This is a static/associated function - it doesn’t need a tree instance, only the commitment’s merkle root for verification.

This function cryptographically verifies that a UTXO exists in the commitment’s UTXO set without requiring the full tree.

Arguments

• commitment - The UTXO commitment containing the merkle root
• outpoint - The outpoint to verify
• utxo - The UTXO data to verify
• proof - The Merkle proof (takes ownership)

Returns

Ok(true) if proof is valid, Ok(false) or Err if invalid

Trait Implementations

impl Default for UtxoMerkleTree

Available on crate feature utxo-commitments only.

fn default() -> Self

Prefer UtxoMerkleTree::new in code that can handle allocation failure.

Default panics if the underlying sparse Merkle tree cannot be constructed (e.g. severe memory pressure). This matches “default must be infallible” call sites but is not ideal for untrusted or resource-constrained environments.