feat: add TrieNode trait and related functionality (#1363)

`TrieNode` is a generic trait that abstracts over the behavior of nodes
in a fixed-arity radix trie. This trait allows for different structures
to represent tries while enabling similar operations on them.

`TrieNode` is merkle-aware, meaning it can represent nodes that are a
mix of locally described children or children referenced by only their
hash. This is accomplished through `TrieEdgeState` and is used later in
proof verification.

The `HashedTrieNode` trait is for post-hashed nodes and is distinctly
different from the hash described on `TrieNode`. This trait is intended
to represent the computed hash of the node itself; whereas, the hash
accessed via `TrieNode` is the hash of a child node as seen from its
parent. While they are usually the same, they can differ during
intermediate states of a trie or during proof verification when some
information is incomplete.

`KeyValueTrieRoot` is an implementation of `TrieNode` that only
represents a key-value store and is not merkleized. This is really a
separate change and is a component of proof verification but is also
needed here as it is used to test and verify the iterator.

Author: demosdemon

Cargo.toml

@@ -76,7 +76,7 @@ metrics-util = "0.20.0"
 nonzero_ext = "0.3.0"
 rand_distr = "0.5.1"
 sha2 = "0.10.9"
-smallvec = "1.15.1"
+smallvec = { version = "1.15.1", features = ["write", "union", "const_new"] }
 test-case = "3.3.1"
 thiserror = "2.0.17"
 

storage/Cargo.toml

@@ -29,7 +29,7 @@ metrics.workspace = true
 nonzero_ext.workspace = true
 rand = { workspace = true, optional = true }
 sha2.workspace = true
-smallvec = { workspace = true, features = ["write", "union"] }
+smallvec.workspace = true
 thiserror.workspace = true
 # Regular dependencies
 arc-swap = "1.7.1"

storage/src/lib.rs

@@ -34,6 +34,7 @@ mod path;
 #[cfg(any(test, feature = "test_utils"))]
 mod test_utils;
 mod trie_hash;
+mod tries;
 mod u4;
 
 /// Logger module for handling logging functionality
@@ -58,11 +59,15 @@ pub use nodestore::{
 };
 pub use path::{
     ComponentIter, IntoSplitPath, JoinedPath, PartialPath, PathBuf, PathCommonPrefix,
-    PathComponent, PathComponentSliceExt, SplitPath, TriePath, TriePathAsPackedBytes,
+    PathComponent, PathComponentSliceExt, PathGuard, SplitPath, TriePath, TriePathAsPackedBytes,
     TriePathFromPackedBytes, TriePathFromUnpackedBytes,
 };
 #[cfg(not(feature = "branch_factor_256"))]
 pub use path::{PackedBytes, PackedPathComponents, PackedPathRef};
+pub use tries::{
+    DuplicateKeyError, HashedTrieNode, IterAscending, IterDescending, KeyValueTrieRoot,
+    TrieEdgeIter, TrieEdgeState, TrieNode, TrieValueIter,
+};
 pub use u4::{TryFromIntError, U4};
 
 pub use linear::filebacked::FileBacked;

storage/src/node/branch.rs

@@ -222,6 +222,12 @@ mod ethhash {
         pub fn into_triehash(self) -> TrieHash {
             self.into()
         }
+
+        // used in PartialEq and Hash impls and is to trick clippy into not caring
+        // about creating an owned instance for comparison
+        fn as_triehash(&self) -> TrieHash {
+            self.into()
+        }
     }
 
     impl PartialEq<TrieHash> for HashOrRlp {
@@ -247,19 +253,27 @@ mod ethhash {
     impl PartialEq for HashOrRlp {
         fn eq(&self, other: &Self) -> bool {
             match (self, other) {
+                // if both are hash or rlp, we can skip hashing
                 (HashOrRlp::Hash(h1), HashOrRlp::Hash(h2)) => h1 == h2,
                 (HashOrRlp::Rlp(r1), HashOrRlp::Rlp(r2)) => r1 == r2,
-                #[expect(deprecated, reason = "transitive dependency on generic-array")]
-                (HashOrRlp::Hash(h), HashOrRlp::Rlp(r))
-                | (HashOrRlp::Rlp(r), HashOrRlp::Hash(h)) => {
-                    Keccak256::digest(r.as_ref()).as_slice() == h.as_ref()
-                }
+                // otherwise, one is a hash and the other isn't, so convert both
+                // to hash and compare
+                _ => self.as_triehash() == other.as_triehash(),
             }
         }
     }
 
     impl Eq for HashOrRlp {}
 
+    impl std::hash::Hash for HashOrRlp {
+        fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+            // contract on `Hash` and `PartialEq` requires that if `a == b` then `hash(a) == hash(b)`
+            // and since `PartialEq` may require hashing, we must always convert to `TrieHash` here
+            // and use it's hash implementation
+            self.as_triehash().hash(state);
+        }
+    }
+
     impl Serializable for HashOrRlp {
         fn write_to<W: ExtendableBytes>(&self, vec: &mut W) {
             match self {
@@ -311,6 +325,15 @@ mod ethhash {
         }
     }
 
+    impl From<&HashOrRlp> for TrieHash {
+        fn from(val: &HashOrRlp) -> Self {
+            match val {
+                HashOrRlp::Hash(h) => h.clone(),
+                HashOrRlp::Rlp(r) => Keccak256::digest(r).into(),
+            }
+        }
+    }
+
     impl From<TrieHash> for HashOrRlp {
         fn from(val: TrieHash) -> Self {
             HashOrRlp::Hash(val)

storage/src/path/buf.rs

@@ -128,3 +128,79 @@ impl<'a> IntoSplitPath for &'a PartialPath<'_> {
         self
     }
 }
+
+/// A RAII guard that resets a path buffer to its original length when dropped.
+///
+/// The guard exposes append-only methods to add components to the path buffer
+/// but not remove them without dropping the guard. This ensures that the guard
+/// will always restore the path buffer to its original state when dropped.
+#[must_use]
+pub struct PathGuard<'a> {
+    buf: &'a mut PathBuf,
+    len: usize,
+}
+
+impl std::fmt::Debug for PathGuard<'_> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.buf.display().fmt(f)
+    }
+}
+
+impl Drop for PathGuard<'_> {
+    fn drop(&mut self) {
+        self.buf.truncate(self.len);
+    }
+}
+
+impl<'a> PathGuard<'a> {
+    /// Creates a new guard that will reset the provided buffer to its current
+    /// length when dropped.
+    pub fn new(buf: &'a mut PathBuf) -> Self {
+        Self {
+            len: buf.len(),
+            buf,
+        }
+    }
+
+    /// Creates a new guard that will reset this guard's buffer to its current
+    /// length when dropped.
+    ///
+    /// This allows for nested guards that can be used in recursive algorithms.
+    pub fn fork(&mut self) -> PathGuard<'_> {
+        PathGuard::new(self.buf)
+    }
+
+    /// Fork this guard and append the given segment to the path buffer.
+    ///
+    /// This is a convenience method that combines `fork` then `extend` in a
+    /// single operation for ergonomic one-liners.
+    ///
+    /// The returned guard will reset the path buffer to its original length,
+    /// before appending the given segment, when dropped.
+    pub fn fork_append(&mut self, path: impl TriePath) -> PathGuard<'_> {
+        let mut fork = self.fork();
+        fork.extend(path.components());
+        fork
+    }
+
+    /// Appends the given component to the path buffer.
+    ///
+    /// This component will be removed when the guard is dropped.
+    pub fn push(&mut self, component: PathComponent) {
+        self.buf.push(component);
+    }
+}
+
+impl std::ops::Deref for PathGuard<'_> {
+    type Target = PathBuf;
+
+    fn deref(&self) -> &Self::Target {
+        self.buf
+    }
+}
+
+impl Extend<PathComponent> for PathGuard<'_> {
+    fn extend<T: IntoIterator<Item = PathComponent>>(&mut self, iter: T) {
+        self.buf.extend(iter);
+    }
+}

storage/src/path/mod.rs

@@ -8,7 +8,7 @@ mod joined;
 mod packed;
 mod split;
 
-pub use self::buf::{PartialPath, PathBuf};
+pub use self::buf::{PartialPath, PathBuf, PathGuard};
 pub use self::component::{ComponentIter, PathComponent, PathComponentSliceExt};
 pub use self::joined::JoinedPath;
 #[cfg(not(feature = "branch_factor_256"))]