Struct RevealedSparseTrie

pub struct RevealedSparseTrie<P = DefaultBlindedProvider> { /* private fields */ }

The representation of revealed sparse trie.

The revealed sparse trie contains the actual trie structure with nodes, values, and tracking for changes. It supports operations like inserting, updating, and removing nodes.

Invariants

• The root node is always present in nodes collection.
• Each leaf entry in nodes collection must have a corresponding entry in values collection. The opposite is also true.
• All keys in values collection are full leaf paths.

Implementations

impl RevealedSparseTrie

pub fn from_root( root: TrieNode, masks: TrieMasks, retain_updates: bool, ) -> SparseTrieResult<Self>

Creates a new revealed sparse trie from the given root node.

This function initializes the internal structures and then reveals the root. It is a convenient method to create a RevealedSparseTrie when you already have the root node available.

Returns

A RevealedSparseTrie if successful, or an error if revealing fails.

impl<P> RevealedSparseTrie<P>

pub fn from_provider_and_root( provider: P, node: TrieNode, masks: TrieMasks, retain_updates: bool, ) -> SparseTrieResult<Self>

Creates a new revealed sparse trie from the given provider and root node.

Similar to from_root, but allows specifying a custom provider for retrieving blinded nodes.

Returns

A RevealedSparseTrie if successful, or an error if revealing fails.

pub fn with_provider<BP>(self, provider: BP) -> RevealedSparseTrie<BP>

Replaces the current provider with a new provider.

This allows changing how blinded nodes are retrieved without rebuilding the entire trie structure.

Returns

A new RevealedSparseTrie with the updated provider.

pub fn with_updates(self, retain_updates: bool) -> Self

Configures the trie to retain information about updates.

If retain_updates is true, the trie will record branch node updates and deletions. This information can then be used to efficiently update an external database.

pub fn updates_ref(&self) -> Cow<'_, SparseTrieUpdates>

Returns a reference to the current sparse trie updates.

If no updates have been made/recorded, returns an empty update set.

pub const fn nodes_ref(&self) -> &HashMap<Nibbles, SparseNode>

Returns an immutable reference to all nodes in the sparse trie.

pub fn get_leaf_value(&self, path: &Nibbles) -> Option<&Vec<u8>>

Retrieves a reference to the leaf value stored at the given key path, if it is revealed.

This method efficiently retrieves values from the trie without traversing the entire node structure, as values are stored in a separate map.

Note: a value can exist in the full trie and this function still returns None because the value has not been revealed. Hence a None indicates two possibilities:

• The value does not exists in the trie, so it cannot be revealed
• The value has not yet been revealed. In order to determine which is true, one would need an exclusion proof.

pub fn take_updates(&mut self) -> SparseTrieUpdates

Consumes and returns the currently accumulated trie updates.

This is useful when you want to apply the updates to an external database, and then start tracking a new set of updates.

pub fn reserve_nodes(&mut self, additional: usize)

Reserves capacity in the nodes map for at least additional more nodes.

pub fn reveal_node( &mut self, path: Nibbles, node: TrieNode, masks: TrieMasks, ) -> SparseTrieResult<()>

Reveals a trie node if it has not been revealed before.

This internal function decodes a trie node and inserts it into the nodes map. It handles different node types (leaf, extension, branch) by appropriately adding them to the trie structure and recursively revealing their children.

Returns

Ok(()) if successful, or an error if node was not revealed.

pub fn wipe(&mut self)

Removes all nodes and values from the trie, resetting it to a blank state with only an empty root node.

Note: All previously tracked changes to the trie are also removed.

pub fn root(&mut self) -> B256

Calculates and returns the root hash of the trie.

Before computing the hash, this function processes any remaining (dirty) nodes by updating their RLP encodings. The root hash is either:

1. The cached hash (if no dirty nodes were found)
2. The keccak256 hash of the root node’s RLP representation

pub fn update_rlp_node_level(&mut self, depth: usize)

Recalculates and updates the RLP hashes of nodes deeper than or equal to the specified depth.

The root node is considered to be at level 0. This method is useful for optimizing hash recalculations after localized changes to the trie structure:

This function identifies all nodes that have changed (based on the prefix set) at the given depth and recalculates their RLP representation.

pub fn rlp_node_allocate(&mut self, prefix_set: &mut PrefixSet) -> RlpNode

Look up or calculate the RLP of the node at the root path.

Panics

If the node at provided path does not exist.

pub fn rlp_node( &mut self, prefix_set: &mut PrefixSet, buffers: &mut RlpNodeBuffers, rlp_buf: &mut Vec<u8>, ) -> RlpNode

Looks up or computes the RLP encoding of the node specified by the current path in the provided buffers.

The function uses a stack (RlpNodeBuffers::path_stack) to track the traversal and accumulate RLP encodings.

Parameters

• prefix_set: The set of trie paths that need their nodes updated.
• buffers: The reusable buffers for stack management and temporary RLP values.

Panics

If the node at provided path does not exist.

impl<P: BlindedProvider> RevealedSparseTrie<P>

pub fn clear(&mut self)

This clears all data structures in the sparse trie, keeping the backing data structures allocated.

This is useful for reusing the trie without needing to reallocate memory.

pub fn find_leaf( &self, path: &Nibbles, expected_value: Option<&Vec<u8>>, ) -> Result<LeafLookup, LeafLookupError>

Attempts to find a leaf node at the specified path.

This method traverses the trie from the root down to the given path, checking if a leaf exists at that path. It can be used to verify the existence of a leaf or to generate an exclusion proof (proof that a leaf does not exist).

Parameters

• path: The path to search for.
• expected_value: Optional expected value. If provided, will verify the leaf value matches.

Returns

• Ok(LeafLookup::Exists) if the leaf exists with the expected value.
• Ok(LeafLookup::NonExistent) if the leaf definitely does not exist (exclusion proof).
• Err(LeafLookupError) if the search encountered a blinded node or found a different value.

pub fn update_leaf( &mut self, path: Nibbles, value: Vec<u8>, is_private: bool, ) -> SparseTrieResult<()>

Updates or inserts a leaf node at the specified key path with the provided RLP-encoded value.

This method updates the internal prefix set and, if the leaf did not previously exist, adjusts the trie structure by inserting new leaf nodes, splitting branch nodes, or collapsing extension nodes as needed.

Returns

Returns Ok(()) if the update is successful.

Note: If an update requires revealing a blinded node, an error is returned if the blinded provider returns an error.

pub fn remove_leaf(&mut self, path: &Nibbles) -> SparseTrieResult<()>

Removes a leaf node from the trie at the specified key path.

This function removes the leaf value from the internal values map and then traverses the trie to remove or adjust intermediate nodes, merging or collapsing them as necessary.

Returns

Returns Ok(()) if the leaf is successfully removed, otherwise returns an error if the leaf is not present or if a blinded node prevents removal.

Trait Implementations

impl<P: Clone> Clone for RevealedSparseTrie<P>

fn clone(&self) -> RevealedSparseTrie<P>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P> Debug for RevealedSparseTrie<P>

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

Formats the value using the given formatter.

impl Default for RevealedSparseTrie

fn default() -> Self

Returns the “default value” for a type.

impl<P: BlindedProvider> Display for RevealedSparseTrie<P>

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

Formats the value using the given formatter.

impl<P: PartialEq> PartialEq for RevealedSparseTrie<P>

fn eq(&self, other: &RevealedSparseTrie<P>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<P: Eq> Eq for RevealedSparseTrie<P>

impl<P> StructuralPartialEq for RevealedSparseTrie<P>

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.