Struct Mmr 

pub struct Mmr<E: RStorage + Clock + Metrics, H: CHasher> { /* private fields */ }

A MMR backed by a fixed-item-length journal.

Implementations

impl<E: RStorage + Clock + Metrics, H: CHasher> Mmr<E, H>

pub async fn init_from_pinned_nodes( context: E, pinned_nodes: Vec<H::Digest>, mmr_size: u64, config: Config, ) -> Result<Self, Error>

Initialize a new journaled MMR from an MMR’s size and set of pinned nodes.

This creates a journaled MMR that appears to have mmr_size elements, all of which are pruned, leaving only the minimal set of pinned_nodes required for proof generation. The next element added will be at position mmr_size.

The returned MMR is functionally equivalent to a journaled MMR that was created, populated, and then pruned up to its size.

Arguments

• context - Storage context
• pinned_nodes - Digest values in the order returned by Proof::nodes_to_pin(mmr_size)
• mmr_size - The logical size of the MMR (all elements before this are considered pruned)
• config - Journaled MMR configuration. Any data in the given journal and metadata partitions will be overwritten.

pub async fn init( context: E, hasher: &mut impl Hasher<H>, cfg: Config, ) -> Result<Self, Error>

Initialize a new Mmr instance.

pub async fn init_sync( context: E, cfg: SyncConfig<H::Digest>, ) -> Result<Self, Error>

Initialize an MMR for synchronization, reusing existing data if possible.

Handles three sync scenarios based on existing journal data vs. the given sync boundaries.

1. Fresh Start: existing_size < lower_bound

   • Deletes existing data (if any)
   • Creates new Journal with pruning boundary and size lower_bound

2. Prune and Reuse: lower_bound ≤ existing_size ≤ upper_bound

   • Sets in-memory MMR size to existing_size
   • Prunes the journal to lower_bound

3. Prune and Rewind: existing_size > upper_bound

   • Rewinds the journal to size upper_bound+1
   • Sets in-memory MMR size to upper_bound+1
   • Prunes the journal to lower_bound

pub fn size(&self) -> u64

Return the total number of nodes in the MMR, irrespective of any pruning. The next added element’s position will have this value.

pub fn leaves(&self) -> u64

Return the total number of leaves in the MMR.

pub fn last_leaf_pos(&self) -> Option<u64>

Return the position of the last leaf in this MMR, or None if the MMR is empty.

pub fn is_dirty(&self) -> bool

Returns whether there are pending updates.

pub async fn get_node(&self, position: u64) -> Result<Option<H::Digest>, Error>

pub async fn add( &mut self, h: &mut impl Hasher<H>, element: &[u8], ) -> Result<u64, Error>

Add an element to the MMR and return its position in the MMR. Elements added to the MMR aren’t persisted to disk until sync is called.

Warning

Panics if there are unprocessed updates.

pub async fn add_batched( &mut self, h: &mut impl Hasher<H>, element: &[u8], ) -> Result<u64, Error>

Add an element to the MMR, delaying the computation of ancestor digests until the next sync.

pub async fn pop(&mut self, leaves_to_pop: usize) -> Result<(), Error>

Pop the given number of elements from the tip of the MMR assuming they exist, and otherwise return Empty or ElementPruned errors. The backing journal is synced to disk before returning.

Warning

Panics if there are unprocessed batch updates.

pub fn root(&self, h: &mut impl Hasher<H>) -> H::Digest

Return the root of the MMR.

Warning

Panics if there are unprocessed updates.

pub fn process_updates(&mut self, h: &mut impl Hasher<H>)

Process all batched updates without syncing to disk.

pub async fn sync(&mut self, h: &mut impl Hasher<H>) -> Result<(), Error>

Process all batched updates and sync the MMR to disk. If pool is non-null, then it will be used to parallelize the sync.

pub async fn proof(&self, element_pos: u64) -> Result<Proof<H::Digest>, Error>

Return an inclusion proof for the specified element, or ElementPruned error if some element needed to generate the proof has been pruned.

Warning

Panics if there are unprocessed updates.

pub async fn range_proof( &self, start_element_pos: u64, end_element_pos: u64, ) -> Result<Proof<H::Digest>, Error>

Return an inclusion proof for the specified range of elements, inclusive of both endpoints, or ElementPruned error if some element needed to generate the proof has been pruned.

Warning

Panics if there are unprocessed updates.

pub async fn historical_range_proof( &self, size: u64, start_element_pos: u64, end_element_pos: u64, ) -> Result<Proof<H::Digest>, Error>

Analogous to range_proof but for a previous database state. Specifically, the state when the MMR had size elements.

pub async fn prune_all(&mut self, h: &mut impl Hasher<H>) -> Result<(), Error>

Prune as many nodes as possible, leaving behind at most items_per_blob nodes in the current blob.

pub async fn prune_to_pos( &mut self, h: &mut impl Hasher<H>, pos: u64, ) -> Result<(), Error>

Prune all nodes up to but not including the given position and update the pinned nodes.

This implementation ensures that no failure can leave the MMR in an unrecoverable state, requiring it sync the MMR to write any potential unprocessed updates.

pub fn pruned_to_pos(&self) -> u64

The highest position for which this MMR has been pruned, or 0 if this MMR has never been pruned.

pub fn oldest_retained_pos(&self) -> Option<u64>

Return the position of the oldest retained node in the MMR, not including pinned nodes.

pub async fn close(self, h: &mut impl Hasher<H>) -> Result<(), Error>

Close the MMR, syncing any cached elements to disk and closing the journal.

pub async fn destroy(self) -> Result<(), Error>

Close and permanently remove any disk resources.

Trait Implementations

impl<E: RStorage + Clock + Metrics, H: CHasher> Builder<H> for Mmr<E, H>

async fn add( &mut self, hasher: &mut impl Hasher<H>, element: &[u8], ) -> Result<u64, Error>

Add element to the MMR and return its position within it. The element can be an arbitrary byte slice, and need not be converted to a digest first.

fn root(&self, hasher: &mut impl Hasher<H>) -> H::Digest

Return the root hash of the MMR.

impl<E: RStorage + Clock + Metrics, H: CHasher> Storage<<H as Hasher>::Digest> for Mmr<E, H>

fn size(&self) -> u64

Return the number of elements in the MMR.

async fn get_node(&self, position: u64) -> Result<Option<H::Digest>, Error>

Return the specified node of the MMR if it exists & hasn’t been pruned.