Trait WalletCommitmentTrees 

pub trait WalletCommitmentTrees {
    type Error: Debug;
    type SaplingShardStore<'a>: ShardStore<H = Node, CheckpointId = BlockHeight, Error = Self::Error>;
    type OrchardShardStore<'a>: ShardStore<H = MerkleHashOrchard, CheckpointId = BlockHeight, Error = Self::Error>;

    // Required methods
    fn with_sapling_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>
       where for<'a> F: FnMut(&'a mut ShardTree<Self::SaplingShardStore<'a>, { sapling::NOTE_COMMITMENT_TREE_DEPTH }, SAPLING_SHARD_HEIGHT>) -> Result<A, E>,
             E: From<ShardTreeError<Self::Error>>;
    fn put_sapling_subtree_roots(
        &mut self,
        start_index: u64,
        roots: &[CommitmentTreeRoot<Node>],
    ) -> Result<(), ShardTreeError<Self::Error>>;
    fn get_sapling_subtree_root(
        &mut self,
        index: u64,
    ) -> Result<Option<Node>, ShardTreeError<Self::Error>>;
    fn with_orchard_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>
       where for<'a> F: FnMut(&'a mut ShardTree<Self::OrchardShardStore<'a>, { _ }, ORCHARD_SHARD_HEIGHT>) -> Result<A, E>,
             E: From<ShardTreeError<Self::Error>>;
    fn put_orchard_subtree_roots(
        &mut self,
        start_index: u64,
        roots: &[CommitmentTreeRoot<MerkleHashOrchard>],
    ) -> Result<(), ShardTreeError<Self::Error>>;
    fn get_orchard_subtree_root(
        &mut self,
        index: u64,
    ) -> Result<Option<MerkleHashOrchard>, ShardTreeError<Self::Error>>;

    // Provided methods
    fn with_ironwood_tree_mut<F, A, E>(
        &mut self,
        _callback: F,
    ) -> Result<Option<A>, E>
       where for<'a> F: FnMut(&'a mut ShardTree<Self::OrchardShardStore<'a>, { _ }, ORCHARD_SHARD_HEIGHT>) -> Result<A, E>,
             E: From<ShardTreeError<Self::Error>> { ... }
    fn put_ironwood_subtree_roots(
        &mut self,
        _start_index: u64,
        _roots: &[CommitmentTreeRoot<MerkleHashOrchard>],
    ) -> Result<(), ShardTreeError<Self::Error>> { ... }
    fn get_ironwood_subtree_root(
        &mut self,
        _index: u64,
    ) -> Result<Option<MerkleHashOrchard>, ShardTreeError<Self::Error>> { ... }
    fn put_sapling_shards(
        &mut self,
        shards: &[LocatedPrunableTree<Node>],
        cap: Option<&PrunableTree<Node>>,
        checkpoints_remove: &[BlockHeight],
        checkpoints_add: &[(BlockHeight, Checkpoint)],
    ) -> Result<(), ShardTreeError<Self::Error>> { ... }
    fn put_orchard_shards(
        &mut self,
        shards: &[LocatedPrunableTree<MerkleHashOrchard>],
        cap: Option<&PrunableTree<MerkleHashOrchard>>,
        checkpoints_remove: &[BlockHeight],
        checkpoints_add: &[(BlockHeight, Checkpoint)],
    ) -> Result<(), ShardTreeError<Self::Error>> { ... }
    fn put_ironwood_shards(
        &mut self,
        shards: &[LocatedPrunableTree<MerkleHashOrchard>],
        cap: Option<&PrunableTree<MerkleHashOrchard>>,
        checkpoints_remove: &[BlockHeight],
        checkpoints_add: &[(BlockHeight, Checkpoint)],
    ) -> Result<(), ShardTreeError<Self::Error>> { ... }
    fn remove_retained_checkpoints_below(
        &mut self,
        max_height: BlockHeight,
    ) -> Result<(), ShardTreeError<Self::Error>> { ... }
}

This trait describes a capability for manipulating wallet note commitment trees.

Required Associated Types

type Error: Debug

type SaplingShardStore<'a>: ShardStore<H = Node, CheckpointId = BlockHeight, Error = Self::Error>

The type of the backing [ShardStore] for the Sapling note commitment tree.

type OrchardShardStore<'a>: ShardStore<H = MerkleHashOrchard, CheckpointId = BlockHeight, Error = Self::Error>

Available on crate feature orchard only.

The type of the backing [ShardStore] for the Orchard note commitment tree.

Required Methods

fn with_sapling_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>

where for<'a> F: FnMut(&'a mut ShardTree<Self::SaplingShardStore<'a>, { sapling::NOTE_COMMITMENT_TREE_DEPTH }, SAPLING_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Self::Error>>,

Evaluates the given callback function with a reference to the Sapling note commitment tree maintained by the wallet.

fn put_sapling_subtree_roots( &mut self, start_index: u64, roots: &[CommitmentTreeRoot<Node>], ) -> Result<(), ShardTreeError<Self::Error>>

Adds a sequence of Sapling note commitment tree subtree roots to the data store.

Each such value should be the Merkle root of a subtree of the Sapling note commitment tree containing 2^SAPLING_SHARD_HEIGHT note commitments.

fn get_sapling_subtree_root( &mut self, index: u64, ) -> Result<Option<Node>, ShardTreeError<Self::Error>>

Returns the stored root hash of the completed Sapling subtree with the given index, or Ok(None) if no root is recorded for that subtree.

This is the store’s record of the subtree root as most recently provided via WalletCommitmentTrees::put_sapling_subtree_roots (i.e. the chain-authoritative root obtained from a chain data provider), or as recorded when a locally-completed subtree was persisted.

fn with_orchard_tree_mut<F, A, E>(&mut self, callback: F) -> Result<A, E>

where for<'a> F: FnMut(&'a mut ShardTree<Self::OrchardShardStore<'a>, { _ }, ORCHARD_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Self::Error>>,

Available on crate feature orchard only.

Evaluates the given callback function with a reference to the Orchard note commitment tree maintained by the wallet.

fn put_orchard_subtree_roots( &mut self, start_index: u64, roots: &[CommitmentTreeRoot<MerkleHashOrchard>], ) -> Result<(), ShardTreeError<Self::Error>>

Available on crate feature orchard only.

Adds a sequence of Orchard note commitment tree subtree roots to the data store.

Each such value should be the Merkle root of a subtree of the Orchard note commitment tree containing 2^ORCHARD_SHARD_HEIGHT note commitments.

fn get_orchard_subtree_root( &mut self, index: u64, ) -> Result<Option<MerkleHashOrchard>, ShardTreeError<Self::Error>>

Available on crate feature orchard only.

Returns the stored root hash of the completed Orchard subtree with the given index, or Ok(None) if no root is recorded for that subtree.

This is the store’s record of the subtree root as most recently provided via WalletCommitmentTrees::put_orchard_subtree_roots (i.e. the chain-authoritative root obtained from a chain data provider), or as recorded when a locally-completed subtree was persisted.

Provided Methods

fn with_ironwood_tree_mut<F, A, E>( &mut self, _callback: F, ) -> Result<Option<A>, E>

where for<'a> F: FnMut(&'a mut ShardTree<Self::OrchardShardStore<'a>, { _ }, ORCHARD_SHARD_HEIGHT>) -> Result<A, E>, E: From<ShardTreeError<Self::Error>>,

Available on crate feature orchard only.

Evaluates the given callback with the Ironwood note commitment tree maintained by the wallet, if this backend has one.

The default implementation reports that no Ironwood tree is available. Backends that track Ironwood note commitments should override this and provide their separate Ironwood tree.

fn put_ironwood_subtree_roots( &mut self, _start_index: u64, _roots: &[CommitmentTreeRoot<MerkleHashOrchard>], ) -> Result<(), ShardTreeError<Self::Error>>

Available on crate feature orchard only.

Adds a sequence of Ironwood note commitment tree subtree roots to the data store, if this backend tracks an Ironwood tree.

Each such value should be the Merkle root of a subtree of the Ironwood note commitment tree containing 2^ORCHARD_SHARD_HEIGHT note commitments; Ironwood shares the Orchard note commitment tree’s shape, so the same shard height applies.

The default implementation is a no-op, for backends that do not track an Ironwood tree (mirroring WalletCommitmentTrees::with_ironwood_tree_mut). Backends that track Ironwood note commitments should override this.

fn get_ironwood_subtree_root( &mut self, _index: u64, ) -> Result<Option<MerkleHashOrchard>, ShardTreeError<Self::Error>>

Available on crate feature orchard only.

Returns the stored root hash of the completed Ironwood subtree with the given index, or Ok(None) if no root is recorded for that subtree (in particular, if this backend does not track an Ironwood tree — the default implementation).

fn put_sapling_shards( &mut self, shards: &[LocatedPrunableTree<Node>], cap: Option<&PrunableTree<Node>>, checkpoints_remove: &[BlockHeight], checkpoints_add: &[(BlockHeight, Checkpoint)], ) -> Result<(), ShardTreeError<Self::Error>>

Applies a batch of changes — shards, an optional replacement tree cap, and a checkpoint delta — to the wallet’s Sapling note commitment tree.

shards must be in ascending shard-index order; stores may reject sequences that would leave gaps in the tree. Checkpoint removals are applied before additions, so that a checkpoint whose data has changed may appear in both lists.

This is intended for wallet stores that accumulate note commitment tree updates outside the backing store (for example, in an in-memory tree) and flush them in batches. The default implementation applies the changes through WalletCommitmentTrees::with_sapling_tree_mut.

fn put_orchard_shards( &mut self, shards: &[LocatedPrunableTree<MerkleHashOrchard>], cap: Option<&PrunableTree<MerkleHashOrchard>>, checkpoints_remove: &[BlockHeight], checkpoints_add: &[(BlockHeight, Checkpoint)], ) -> Result<(), ShardTreeError<Self::Error>>

Available on crate feature orchard only.

Applies a batch of changes — shards, an optional replacement tree cap, and a checkpoint delta — to the wallet’s Orchard note commitment tree.

shards must be in ascending shard-index order; stores may reject sequences that would leave gaps in the tree. Checkpoint removals are applied before additions, so that a checkpoint whose data has changed may appear in both lists.

This is intended for wallet stores that accumulate note commitment tree updates outside the backing store (for example, in an in-memory tree) and flush them in batches. The default implementation applies the changes through WalletCommitmentTrees::with_orchard_tree_mut.

fn put_ironwood_shards( &mut self, shards: &[LocatedPrunableTree<MerkleHashOrchard>], cap: Option<&PrunableTree<MerkleHashOrchard>>, checkpoints_remove: &[BlockHeight], checkpoints_add: &[(BlockHeight, Checkpoint)], ) -> Result<(), ShardTreeError<Self::Error>>

Available on crate feature orchard only.

Applies a batch of changes — shards, an optional replacement tree cap, and a checkpoint delta — to the wallet’s Ironwood note commitment tree, if this backend tracks one.

shards must be in ascending shard-index order; stores may reject sequences that would leave gaps in the tree. Checkpoint removals are applied before additions, so that a checkpoint whose data has changed may appear in both lists.

The default implementation applies the changes through WalletCommitmentTrees::with_ironwood_tree_mut; for backends that do not track an Ironwood tree (see that method’s documentation), the changes are ignored.

fn remove_retained_checkpoints_below( &mut self, max_height: BlockHeight, ) -> Result<(), ShardTreeError<Self::Error>>

Releases all retained (“anchor”) checkpoints with height strictly less than max_height from the wallet’s note commitment trees, allowing them to be pruned normally.

Anchor checkpoints are established during scanning (and may be created directly via [ShardTree::ensure_retained]); they are otherwise exempt from automatic pruning of excess checkpoints. This releases the retention of those that have aged below max_height in the Sapling and (when the orchard feature is enabled) the Orchard and Ironwood trees.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl WalletCommitmentTrees for MockWalletDb

Available on crate features test-dependencies only.

type Error = !

type SaplingShardStore<'a> = MemoryShardStore<Node, BlockHeight>

type OrchardShardStore<'a> = MemoryShardStore<MerkleHashOrchard, BlockHeight>