feat(trie): Implement skeleton of proof_v2 (paradigmxyz#19687)

Author: mediocregopher

crates/engine/tree/src/tree/payload_processor/configured_sparse_trie.rs

@@ -1,10 +1,10 @@
 //! Configured sparse trie enum for switching between serial and parallel implementations.
 
 use alloy_primitives::B256;
-use reth_trie::{Nibbles, TrieNode};
+use reth_trie::{Nibbles, ProofTrieNode, TrieMasks, TrieNode};
 use reth_trie_sparse::{
     errors::SparseTrieResult, provider::TrieNodeProvider, LeafLookup, LeafLookupError,
-    RevealedSparseNode, SerialSparseTrie, SparseTrieInterface, SparseTrieUpdates, TrieMasks,
+    SerialSparseTrie, SparseTrieInterface, SparseTrieUpdates,
 };
 use reth_trie_sparse_parallel::ParallelSparseTrie;
 use std::borrow::Cow;
@@ -83,7 +83,7 @@ impl SparseTrieInterface for ConfiguredSparseTrie {
         }
     }
 
-    fn reveal_nodes(&mut self, nodes: Vec<RevealedSparseNode>) -> SparseTrieResult<()> {
+    fn reveal_nodes(&mut self, nodes: Vec<ProofTrieNode>) -> SparseTrieResult<()> {
         match self {
             Self::Serial(trie) => trie.reveal_nodes(nodes),
             Self::Parallel(trie) => trie.reveal_nodes(nodes),

crates/trie/common/src/lib.rs

@@ -41,6 +41,9 @@ pub use storage::{StorageTrieEntry, TrieChangeSetsEntry};
 mod subnode;
 pub use subnode::StoredSubNode;
 
+mod trie;
+pub use trie::{ProofTrieNode, TrieMasks};
+
 /// The implementation of a container for storing intermediate changes to a trie.
 /// The container indicates when the trie has been modified.
 pub mod prefix_set;

crates/trie/common/src/trie.rs

@@ -0,0 +1,45 @@
+//! Types related to sparse trie nodes and masks.
+
+use crate::Nibbles;
+use alloy_trie::{nodes::TrieNode, TrieMask};
+
+/// Struct for passing around branch node mask information.
+///
+/// Branch nodes can have up to 16 children (one for each nibble).
+/// The masks represent which children are stored in different ways:
+/// - `hash_mask`: Indicates which children are stored as hashes in the database
+/// - `tree_mask`: Indicates which children are complete subtrees stored in the database
+///
+/// These masks are essential for efficient trie traversal and serialization, as they
+/// determine how nodes should be encoded and stored on disk.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub struct TrieMasks {
+    /// Branch node hash mask, if any.
+    ///
+    /// When a bit is set, the corresponding child node's hash is stored in the trie.
+    ///
+    /// This mask enables selective hashing of child nodes.
+    pub hash_mask: Option<TrieMask>,
+    /// Branch node tree mask, if any.
+    ///
+    /// When a bit is set, the corresponding child subtree is stored in the database.
+    pub tree_mask: Option<TrieMask>,
+}
+
+impl TrieMasks {
+    /// Helper function, returns both fields `hash_mask` and `tree_mask` as [`None`]
+    pub const fn none() -> Self {
+        Self { hash_mask: None, tree_mask: None }
+    }
+}
+
+/// Carries all information needed by a sparse trie to reveal a particular node.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProofTrieNode {
+    /// Path of the node.
+    pub path: Nibbles,
+    /// The node itself.
+    pub node: TrieNode,
+    /// Tree and hash masks for the node, if known.
+    pub masks: TrieMasks,
+}

crates/trie/sparse-parallel/src/trie.rs

@@ -9,12 +9,13 @@ use alloy_trie::{BranchNodeCompact, TrieMask, EMPTY_ROOT_HASH};
 use reth_execution_errors::{SparseTrieErrorKind, SparseTrieResult};
 use reth_trie_common::{
     prefix_set::{PrefixSet, PrefixSetMut},
-    BranchNodeRef, ExtensionNodeRef, LeafNodeRef, Nibbles, RlpNode, TrieNode, CHILD_INDEX_RANGE,
+    BranchNodeRef, ExtensionNodeRef, LeafNodeRef, Nibbles, ProofTrieNode, RlpNode, TrieMasks,
+    TrieNode, CHILD_INDEX_RANGE,
 };
 use reth_trie_sparse::{
     provider::{RevealedNode, TrieNodeProvider},
-    LeafLookup, LeafLookupError, RevealedSparseNode, RlpNodeStackItem, SparseNode, SparseNodeType,
-    SparseTrieInterface, SparseTrieUpdates, TrieMasks,
+    LeafLookup, LeafLookupError, RlpNodeStackItem, SparseNode, SparseNodeType, SparseTrieInterface,
+    SparseTrieUpdates,
 };
 use smallvec::SmallVec;
 use std::{
@@ -172,23 +173,23 @@ impl SparseTrieInterface for ParallelSparseTrie {
         self
     }
 
-    fn reveal_nodes(&mut self, mut nodes: Vec<RevealedSparseNode>) -> SparseTrieResult<()> {
+    fn reveal_nodes(&mut self, mut nodes: Vec<ProofTrieNode>) -> SparseTrieResult<()> {
         if nodes.is_empty() {
             return Ok(())
         }
 
         // Sort nodes first by their subtrie, and secondarily by their path. This allows for
         // grouping nodes by their subtrie using `chunk_by`.
         nodes.sort_unstable_by(
-            |RevealedSparseNode { path: path_a, .. }, RevealedSparseNode { path: path_b, .. }| {
+            |ProofTrieNode { path: path_a, .. }, ProofTrieNode { path: path_b, .. }| {
                 let subtrie_type_a = SparseSubtrieType::from_path(path_a);
                 let subtrie_type_b = SparseSubtrieType::from_path(path_b);
                 subtrie_type_a.cmp(&subtrie_type_b).then(path_a.cmp(path_b))
             },
         );
 
         // Update the top-level branch node masks. This is simple and can't be done in parallel.
-        for RevealedSparseNode { path, masks, .. } in &nodes {
+        for ProofTrieNode { path, masks, .. } in &nodes {
             if let Some(tree_mask) = masks.tree_mask {
                 self.branch_node_tree_masks.insert(*path, tree_mask);
             }
@@ -2688,14 +2689,14 @@ mod tests {
         prefix_set::PrefixSetMut,
         proof::{ProofNodes, ProofRetainer},
         updates::TrieUpdates,
-        BranchNode, ExtensionNode, HashBuilder, LeafNode, RlpNode, TrieMask, TrieNode,
-        EMPTY_ROOT_HASH,
+        BranchNode, ExtensionNode, HashBuilder, LeafNode, ProofTrieNode, RlpNode, TrieMask,
+        TrieMasks, TrieNode, EMPTY_ROOT_HASH,
     };
     use reth_trie_db::DatabaseTrieCursorFactory;
     use reth_trie_sparse::{
         provider::{DefaultTrieNodeProvider, RevealedNode, TrieNodeProvider},
-        LeafLookup, LeafLookupError, RevealedSparseNode, SerialSparseTrie, SparseNode,
-        SparseTrieInterface, SparseTrieUpdates, TrieMasks,
+        LeafLookup, LeafLookupError, SerialSparseTrie, SparseNode, SparseTrieInterface,
+        SparseTrieUpdates,
     };
     use std::collections::{BTreeMap, BTreeSet};
 
@@ -3277,7 +3278,7 @@ mod tests {
             let node = create_leaf_node([0x2, 0x3], 42);
             let masks = TrieMasks::none();
 
-            trie.reveal_nodes(vec![RevealedSparseNode { path, node, masks }]).unwrap();
+            trie.reveal_nodes(vec![ProofTrieNode { path, node, masks }]).unwrap();
 
             assert_matches!(
                 trie.upper_subtrie.nodes.get(&path),
@@ -3298,7 +3299,7 @@ mod tests {
             let node = create_leaf_node([0x3, 0x4], 42);
             let masks = TrieMasks::none();
 
-            trie.reveal_nodes(vec![RevealedSparseNode { path, node, masks }]).unwrap();
+            trie.reveal_nodes(vec![ProofTrieNode { path, node, masks }]).unwrap();
 
             // Check that the lower subtrie was created
             let idx = path_subtrie_index_unchecked(&path);
@@ -3322,7 +3323,7 @@ mod tests {
             let node = create_leaf_node([0x4, 0x5], 42);
             let masks = TrieMasks::none();
 
-            trie.reveal_nodes(vec![RevealedSparseNode { path, node, masks }]).unwrap();
+            trie.reveal_nodes(vec![ProofTrieNode { path, node, masks }]).unwrap();
 
             // Check that the lower subtrie's path hasn't changed
             let idx = path_subtrie_index_unchecked(&path);
@@ -3383,7 +3384,7 @@ mod tests {
         let node = create_extension_node([0x2], child_hash);
         let masks = TrieMasks::none();
 
-        trie.reveal_nodes(vec![RevealedSparseNode { path, node, masks }]).unwrap();
+        trie.reveal_nodes(vec![ProofTrieNode { path, node, masks }]).unwrap();
 
         // Extension node should be in upper trie
         assert_matches!(
@@ -3445,7 +3446,7 @@ mod tests {
         let node = create_branch_node_with_children(&[0x0, 0x7, 0xf], child_hashes.clone());
         let masks = TrieMasks::none();
 
-        trie.reveal_nodes(vec![RevealedSparseNode { path, node, masks }]).unwrap();
+        trie.reveal_nodes(vec![ProofTrieNode { path, node, masks }]).unwrap();
 
         // Branch node should be in upper trie
         assert_matches!(
@@ -3502,10 +3503,10 @@ mod tests {
 
         // Reveal nodes using reveal_nodes
         trie.reveal_nodes(vec![
-            RevealedSparseNode { path: branch_path, node: branch_node, masks: TrieMasks::none() },
-            RevealedSparseNode { path: leaf_1_path, node: leaf_1, masks: TrieMasks::none() },
-            RevealedSparseNode { path: leaf_2_path, node: leaf_2, masks: TrieMasks::none() },
-            RevealedSparseNode { path: leaf_3_path, node: leaf_3, masks: TrieMasks::none() },
+            ProofTrieNode { path: branch_path, node: branch_node, masks: TrieMasks::none() },
+            ProofTrieNode { path: leaf_1_path, node: leaf_1, masks: TrieMasks::none() },
+            ProofTrieNode { path: leaf_2_path, node: leaf_2, masks: TrieMasks::none() },
+            ProofTrieNode { path: leaf_3_path, node: leaf_3, masks: TrieMasks::none() },
         ])
         .unwrap();
 
@@ -4207,7 +4208,7 @@ mod tests {
         // Convert the logs into reveal_nodes call on a fresh ParallelSparseTrie
         let nodes = vec![
             // Branch at 0x4f8807
-            RevealedSparseNode {
+            ProofTrieNode {
                 path: branch_path,
                 node: {
                     TrieNode::Branch(BranchNode::new(
@@ -4270,7 +4271,7 @@ mod tests {
                 },
             },
             // Branch at 0x4f88072
-            RevealedSparseNode {
+            ProofTrieNode {
                 path: removed_branch_path,
                 node: {
                     let stack = vec![
@@ -4290,7 +4291,7 @@ mod tests {
                 },
             },
             // Extension at 0x4f880722
-            RevealedSparseNode {
+            ProofTrieNode {
                 path: Nibbles::from_nibbles([0x4, 0xf, 0x8, 0x8, 0x0, 0x7, 0x2, 0x2]),
                 node: {
                     let extension_node = ExtensionNode::new(
@@ -4304,7 +4305,7 @@ mod tests {
                 masks: TrieMasks { hash_mask: None, tree_mask: None },
             },
             // Leaf at 0x4f88072c
-            RevealedSparseNode {
+            ProofTrieNode {
                 path: Nibbles::from_nibbles([0x4, 0xf, 0x8, 0x8, 0x0, 0x7, 0x2, 0xc]),
                 node: {
                     let leaf_node = LeafNode::new(
@@ -4423,9 +4424,9 @@ mod tests {
         // Step 2: Reveal nodes in the trie
         let mut trie = ParallelSparseTrie::from_root(extension, TrieMasks::none(), true).unwrap();
         trie.reveal_nodes(vec![
-            RevealedSparseNode { path: branch_path, node: branch, masks: TrieMasks::none() },
-            RevealedSparseNode { path: leaf_1_path, node: leaf_1, masks: TrieMasks::none() },
-            RevealedSparseNode { path: leaf_2_path, node: leaf_2, masks: TrieMasks::none() },
+            ProofTrieNode { path: branch_path, node: branch, masks: TrieMasks::none() },
+            ProofTrieNode { path: leaf_1_path, node: leaf_1, masks: TrieMasks::none() },
+            ProofTrieNode { path: leaf_2_path, node: leaf_2, masks: TrieMasks::none() },
         ])
         .unwrap();
 
@@ -4960,12 +4961,12 @@ mod tests {
         // └── 1 -> Leaf (Path = 1)
         sparse
             .reveal_nodes(vec![
-                RevealedSparseNode {
+                ProofTrieNode {
                     path: Nibbles::default(),
                     node: branch,
                     masks: TrieMasks { hash_mask: None, tree_mask: Some(TrieMask::new(0b01)) },
                 },
-                RevealedSparseNode {
+                ProofTrieNode {
                     path: Nibbles::from_nibbles([0x1]),
                     node: TrieNode::Leaf(leaf),
                     masks: TrieMasks::none(),
@@ -5009,12 +5010,12 @@ mod tests {
         // └── 1 -> Leaf (Path = 1)
         sparse
             .reveal_nodes(vec![
-                RevealedSparseNode {
+                ProofTrieNode {
                     path: Nibbles::default(),
                     node: branch,
                     masks: TrieMasks { hash_mask: None, tree_mask: Some(TrieMask::new(0b01)) },
                 },
-                RevealedSparseNode {
+                ProofTrieNode {
                     path: Nibbles::from_nibbles([0x1]),
                     node: TrieNode::Leaf(leaf),
                     masks: TrieMasks::none(),
@@ -5361,13 +5362,13 @@ mod tests {
                 Default::default(),
                 [key1()],
             );
-        let revealed_nodes: Vec<RevealedSparseNode> = hash_builder_proof_nodes
+        let revealed_nodes: Vec<ProofTrieNode> = hash_builder_proof_nodes
             .nodes_sorted()
             .into_iter()
             .map(|(path, node)| {
                 let hash_mask = branch_node_hash_masks.get(&path).copied();
                 let tree_mask = branch_node_tree_masks.get(&path).copied();
-                RevealedSparseNode {
+                ProofTrieNode {
                     path,
                     node: TrieNode::decode(&mut &node[..]).unwrap(),
                     masks: TrieMasks { hash_mask, tree_mask },
@@ -5399,13 +5400,13 @@ mod tests {
                 Default::default(),
                 [key3()],
             );
-        let revealed_nodes: Vec<RevealedSparseNode> = hash_builder_proof_nodes
+        let revealed_nodes: Vec<ProofTrieNode> = hash_builder_proof_nodes
             .nodes_sorted()
             .into_iter()
             .map(|(path, node)| {
                 let hash_mask = branch_node_hash_masks.get(&path).copied();
                 let tree_mask = branch_node_tree_masks.get(&path).copied();
-                RevealedSparseNode {
+                ProofTrieNode {
                     path,
                     node: TrieNode::decode(&mut &node[..]).unwrap(),
                     masks: TrieMasks { hash_mask, tree_mask },
@@ -5478,13 +5479,13 @@ mod tests {
                 Default::default(),
                 [key1(), Nibbles::from_nibbles_unchecked([0x01])],
             );
-        let revealed_nodes: Vec<RevealedSparseNode> = hash_builder_proof_nodes
+        let revealed_nodes: Vec<ProofTrieNode> = hash_builder_proof_nodes
             .nodes_sorted()
             .into_iter()
             .map(|(path, node)| {
                 let hash_mask = branch_node_hash_masks.get(&path).copied();
                 let tree_mask = branch_node_tree_masks.get(&path).copied();
-                RevealedSparseNode {
+                ProofTrieNode {
                     path,
                     node: TrieNode::decode(&mut &node[..]).unwrap(),
                     masks: TrieMasks { hash_mask, tree_mask },
@@ -5516,13 +5517,13 @@ mod tests {
                 Default::default(),
                 [key2()],
             );
-        let revealed_nodes: Vec<RevealedSparseNode> = hash_builder_proof_nodes
+        let revealed_nodes: Vec<ProofTrieNode> = hash_builder_proof_nodes
             .nodes_sorted()
             .into_iter()
             .map(|(path, node)| {
                 let hash_mask = branch_node_hash_masks.get(&path).copied();
                 let tree_mask = branch_node_tree_masks.get(&path).copied();
-                RevealedSparseNode {
+                ProofTrieNode {
                     path,
                     node: TrieNode::decode(&mut &node[..]).unwrap(),
                     masks: TrieMasks { hash_mask, tree_mask },
@@ -5601,13 +5602,13 @@ mod tests {
                 Default::default(),
                 [key1()],
             );
-        let revealed_nodes: Vec<RevealedSparseNode> = hash_builder_proof_nodes
+        let revealed_nodes: Vec<ProofTrieNode> = hash_builder_proof_nodes
             .nodes_sorted()
             .into_iter()
             .map(|(path, node)| {
                 let hash_mask = branch_node_hash_masks.get(&path).copied();
                 let tree_mask = branch_node_tree_masks.get(&path).copied();
-                RevealedSparseNode {
+                ProofTrieNode {
                     path,
                     node: TrieNode::decode(&mut &node[..]).unwrap(),
                     masks: TrieMasks { hash_mask, tree_mask },
@@ -6595,16 +6596,12 @@ mod tests {
         let leaf_masks = TrieMasks::none();
 
         trie.reveal_nodes(vec![
-            RevealedSparseNode {
+            ProofTrieNode {
                 path: Nibbles::from_nibbles([0x3]),
                 node: TrieNode::Branch(branch_0x3_node),
                 masks: branch_0x3_masks,
             },
-            RevealedSparseNode {
-                path: leaf_path,
-                node: TrieNode::Leaf(leaf_node),
-                masks: leaf_masks,
-            },
+            ProofTrieNode { path: leaf_path, node: TrieNode::Leaf(leaf_node), masks: leaf_masks },
         ])
         .unwrap();