Struct geen::MerkleChangeTracker

pub struct MerkleChangeTracker<BaseBackend, CpBackend> where
    BaseBackend: Storage<Value = H256>,  { /* fields omitted */ }

A struct that wraps an MMR to keep track of changes to the MMR over time. This enables one to roll back changes to a point in history. Think of MerkleChangeTracker as 'git' for MMRs.

[MutableMMr] implements std::ops::Deref, so that once you've wrapped the MMR, all the immutable methods are available through the auto-dereferencing.

The basic philosophy of MerkleChangeTracker is as follows:

• Start with a 'base' MMR. For efficiency, you usually want to make this a [pruned_mmr::PrunedMmr], but it doesn't have to be.
• We then maintain a change-list for every append and delete that is made on the MMR.
• You can commit the change-set at any time, which will create a new MerkleCheckPoint summarising the changes, and the current change-set is reset.
• You can rewind to a previously committed checkpoint, p. This entails resetting the MMR to the base state and then replaying every checkpoint in sequence until checkpoint p is reached. rewind_to_start and replay perform similar functions.
• You can reset the ChangeTracker, which clears the current change-set and moves you back to the most recent checkpoint ('HEAD')

Methods

impl<BaseBackend, CpBackend> MerkleChangeTracker<BaseBackend, CpBackend> where
    BaseBackend: Storage<Value = H256>,
    CpBackend: Storage<Value = MerkleCheckPoint> + StorageExt<Value = MerkleCheckPoint>, 

pub fn new(
    base: MutableMmr<BaseBackend>,
    diffs: CpBackend,
    config: MerkleChangeTrackerConfig
) -> Result<MerkleChangeTracker<BaseBackend, CpBackend>, GeneError>

Wrap an MMR inside a change tracker.

Parameters

• base: The base, or anchor point of the change tracker. This represents the earliest point that you can MerkleChangeTracker::rewind to.
• mmr: An empty MMR instance that will be used to maintain the current state of the MMR.
• diffs: The (usually empty) collection of diffs that will be used to store the MMR checkpoints.

Returns

A new MerkleChangeTracker instance that is configured using the MMR and ChangeTracker instances provided.

pub fn restore(
    &mut self,
    base_state: MutableMmrLeafNodes
) -> Result<(), GeneError>

Reset the MerkleChangeTracker and restore the base MMR state.

pub fn checkpoint_count(&self) -> Result<usize, GeneError>

Return the number of Checkpoints this change tracker has recorded

pub fn push(&mut self, hash: &H256) -> Result<usize, GeneError>

Push the given hash into the MMR and update the current change-set

pub fn reset(&mut self) -> Result<(), GeneError>

Discards the current change-set and resets the MMR state to that of the last checkpoint

pub fn delete_and_compress(
    &mut self,
    leaf_node_index: u32,
    compress: bool
) -> bool

Mark a node for deletion and optionally compress the deletion bitmap. See MutableMmr::delete_and_compress for more details

pub fn delete(&mut self, leaf_node_index: u32) -> bool

Mark a node for completion, and compress the roaring bitmap. See [delete_and_compress] for details.

pub fn compress(&mut self) -> bool

Compress the roaring bitmap mapping deleted nodes. You never have to call this method unless you have been calling [delete_and_compress] with compress set to false ahead of a call to [get_merkle_root].

pub fn commit(&mut self) -> Result<(), GeneError>

Commit the change history since the last commit to a new MerkleCheckPoint and clear the current change set.

pub fn rewind(&mut self, steps_back: usize) -> Result<(), GeneError>

Rewind the MMR state by the given number of Checkpoints.

Example:

Assuming we start with an empty Mutable MMR, and apply the following: push(1), push(2), delete(1), Checkpoint (1) push(3), push(4) Checkpoint (2) push(5), delete(4) Checkpoint (3) push(6)

The state is now:

1 2 3 4 5 6
x     x

After calling rewind(1), The push of 6 wasn't check-pointed, so it will be discarded, and rewinding back one point to checkpoint 2 the state will be:

1 2 3 4
x

Calling rewind(1) again will yield:

1 2
x

pub fn rewind_to_start(&mut self) -> Result<(), GeneError>

Rewinds the MMR back to the state of the base MMR; essentially discarding all the history accumulated to date.

pub fn replay(&mut self, num_checkpoints: usize) -> Result<(), GeneError>

Similar to MerkleChangeTracker::rewind, replay moves the MMR state through checkpoints, but uses the base MMR as the starting point and steps forward through num_checkpoints checkpoints, rather than rewinding from the current state.

pub fn get_checkpoint(
    &self,
    index: usize
) -> Result<MerkleCheckPoint, GeneError>

pub fn index(&self, hash: &H256) -> Option<usize>

Returns the MMR index of a newly added hash, this index is only valid if the change history is Committed.

pub fn get_base_leaf_count(&self) -> usize

Returns the number of leave nodes in the base MMR.

pub fn to_base_leaf_nodes(
    &self,
    index: usize,
    count: usize
) -> Result<MutableMmrLeafNodes, GeneError>

Returns the MMR state of the base MMR.

Trait Implementations

impl<BaseBackend: Debug, CpBackend: Debug> Debug for MerkleChangeTracker<BaseBackend, CpBackend> where
    BaseBackend: Storage<Value = H256>, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<BaseBackend, DiffBackend> Deref for MerkleChangeTracker<BaseBackend, DiffBackend> where
    BaseBackend: Storage<Value = H256>, 

type Target = PrunedMutableMmr

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.