feat(7/7): replace Path with various newtypes

`Path` has been replaced with the components added in previous PRs
inclusing using `[PathComponent]` that make it easier to reason about
paths in code.

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.16"
 

firewood/src/iter.rs

@@ -89,7 +89,7 @@ fn test_eth_compatible_accounts(
     let account = make_key(account);
     let expected_key_hash = Keccak256::digest(&account);
 
-    let items = once((
+    let items = std::iter::once((
         Box::from(expected_key_hash.as_slice()),
         make_key(account_value),
     ))

firewood/src/merkle.rs

@@ -5,18 +5,15 @@
     clippy::missing_errors_doc,
     reason = "Found 1 occurrences after enabling the lint."
 )]
-#![expect(
-    clippy::needless_continue,
-    reason = "Found 1 occurrences after enabling the lint."
-)]
 
 use firewood_storage::{
-    Children, FileIoError, HashType, Hashable, IntoHashType, NibblesIterator, Path, PathComponent,
-    PathIterItem, Preimage, TrieHash, ValueDigest,
+    Children, FileIoError, HashType, Hashable, IntoHashType, IntoSplitPath, PackedPathRef,
+    PartialPath, PathComponent, PathIterItem, Preimage, SplitPath, TrieHash, TriePath,
+    TriePathFromPackedBytes, ValueDigest,
 };
 use thiserror::Error;
 
-use crate::merkle::{Key, Value};
+use crate::merkle::Value;
 
 #[derive(Debug, Error)]
 #[non_exhaustive]
@@ -84,7 +81,7 @@ pub enum ProofError {
 /// A node in a proof.
 pub struct ProofNode {
     /// The key this node is at. Each byte is a nibble.
-    pub key: Key,
+    pub key: PartialPath,
     /// The length of the key prefix that is shared with the previous node.
     pub partial_len: usize,
     /// None if the node does not have a value.
@@ -112,16 +109,22 @@ impl std::fmt::Debug for ProofNode {
 }
 
 impl Hashable for ProofNode {
-    fn parent_prefix_path(&self) -> impl Iterator<Item = u8> + Clone {
-        self.full_path().take(self.partial_len)
+    fn parent_prefix_path(&self) -> impl IntoSplitPath + '_ {
+        self.full_path()
+            .into_split_path()
+            .split_at(self.partial_len)
+            .0
     }
 
-    fn partial_path(&self) -> impl Iterator<Item = u8> + Clone {
-        self.full_path().skip(self.partial_len)
+    fn partial_path(&self) -> impl IntoSplitPath + '_ {
+        self.full_path()
+            .into_split_path()
+            .split_at(self.partial_len)
+            .1
     }
 
-    fn full_path(&self) -> impl Iterator<Item = u8> + Clone {
-        self.key.as_ref().iter().copied()
+    fn full_path(&self) -> impl IntoSplitPath + '_ {
+        &self.key
     }
 
     fn value_digest(&self) -> Option<ValueDigest<&[u8]>> {
@@ -182,7 +185,7 @@ impl<T: ProofCollection + ?Sized> Proof<T> {
         key: K,
         root_hash: &TrieHash,
     ) -> Result<Option<ValueDigest<&[u8]>>, ProofError> {
-        let key = Path(NibblesIterator::new(key.as_ref()).collect());
+        let key = PackedPathRef::path_from_packed_bytes(key.as_ref());
 
         let Some(last_node) = self.0.as_ref().last() else {
             return Err(ProofError::Empty);
@@ -199,14 +202,14 @@ impl<T: ProofCollection + ?Sized> Proof<T> {
             // Assert that only nodes whose keys are an even number of nibbles
             // have a `value_digest`.
             #[cfg(not(feature = "branch_factor_256"))]
-            if node.full_path().count() % 2 != 0 && node.value_digest().is_some() {
+            if node.full_path().len() % 2 != 0 && node.value_digest().is_some() {
                 return Err(ProofError::ValueAtOddNibbleLength);
             }
 
             if let Some(next_node) = iter.peek() {
                 // Assert that every node's key is a prefix of `key`, except for the last node,
                 // whose key can be equal to or a suffix of `key` in an exclusion proof.
-                if next_nibble(node.full_path(), key.iter().copied()).is_none() {
+                if next_nibble(node.full_path(), key).is_none() {
                     return Err(ProofError::ShouldBePrefixOfProvenKey);
                 }
 
@@ -217,16 +220,14 @@ impl<T: ProofCollection + ?Sized> Proof<T> {
                     return Err(ProofError::ShouldBePrefixOfNextKey);
                 };
 
-                let next_nibble =
-                    PathComponent::try_new(next_nibble).ok_or(ProofError::ChildIndexOutOfBounds)?;
                 expected_hash = node.children()[next_nibble]
                     .as_ref()
                     .ok_or(ProofError::NodeNotInTrie)?
                     .clone();
             }
         }
 
-        if last_node.full_path().eq(key.iter().copied()) {
+        if last_node.full_path().path_eq(&key) {
             return Ok(last_node.value_digest());
         }
 
@@ -384,23 +385,18 @@ impl ProofCollection for EmptyProofCollection {
 
 /// Returns the next nibble in `c` after `b`.
 /// Returns None if `b` is not a strict prefix of `c`.
-fn next_nibble<B, C>(b: B, c: C) -> Option<u8>
+fn next_nibble<B, C>(b: B, c: C) -> Option<PathComponent>
 where
-    B: IntoIterator<Item = u8>,
-    C: IntoIterator<Item = u8>,
+    B: IntoSplitPath,
+    C: IntoSplitPath,
 {
-    let b = b.into_iter();
-    let mut c = c.into_iter();
-
-    // Check if b is a prefix of c
-    for b_item in b {
-        match c.next() {
-            Some(c_item) if b_item == c_item => continue,
-            _ => return None,
-        }
+    let common = b
+        .into_split_path()
+        .longest_common_prefix(c.into_split_path());
+    match (common.a_suffix.split_first(), common.b_suffix.split_first()) {
+        (None, Some((next, _))) => Some(next),
+        _ => None,
     }
-
-    c.next()
 }
 
 fn verify_opt_value_digest(

firewood/src/merkle/tests/ethhash.rs

@@ -3,7 +3,7 @@
 
 #[cfg(feature = "ethhash")]
 use firewood_storage::HashType;
-use firewood_storage::{Children, TrieHash, ValueDigest};
+use firewood_storage::{Children, PartialPath, TrieHash, TriePathFromUnpackedBytes, ValueDigest};
 use integer_encoding::VarInt;
 
 use crate::{
@@ -85,7 +85,7 @@ impl Version0 for FrozenRangeProof {
 
 impl Version0 for ProofNode {
     fn read_v0_item(reader: &mut V0Reader<'_>) -> Result<Self, ReadError> {
-        let key = reader.read_item()?;
+        let key = reader.read_v0_item()?;
         let partial_len = reader.read_item()?;
         let value_digest = reader.read_item()?;
 
@@ -105,6 +105,19 @@ impl Version0 for ProofNode {
     }
 }
 
+impl Version0 for PartialPath {
+    fn read_v0_item(reader: &mut V0Reader<'_>) -> Result<Self, ReadError> {
+        let bytes = reader.read_item::<&[u8]>()?;
+        PartialPath::path_from_unpacked_bytes(bytes).map_err(|_| {
+            reader.invalid_item(
+                "partial path",
+                "valid packed path bytes",
+                format!("invalid path: {}", hex::encode(bytes)),
+            )
+        })
+    }
+}
+
 impl Version0 for (Box<[u8]>, Box<[u8]>) {
     fn read_v0_item(reader: &mut V0Reader<'_>) -> Result<Self, ReadError> {
         Ok((reader.read_item()?, reader.read_item()?))

firewood/src/proof.rs

@@ -1,7 +1,7 @@
 // Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
 // See the file LICENSE.md for licensing terms.
 
-use firewood_storage::ValueDigest;
+use firewood_storage::{PartialPath, PathComponentSliceExt, ValueDigest};
 use integer_encoding::VarInt;
 
 use crate::{
@@ -108,6 +108,13 @@ impl WriteItem for ProofNode {
     }
 }
 
+impl WriteItem for PartialPath {
+    fn write_item(&self, out: &mut Vec<u8>) {
+        out.push_var_int(self.len());
+        out.extend_from_slice(self.as_byte_slice());
+    }
+}
+
 impl<T: WriteItem> WriteItem for Option<T> {
     fn write_item(&self, out: &mut Vec<u8>) {
         if let Some(v) = self {

firewood/src/proofs/de.rs

@@ -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"

firewood/src/proofs/ser.rs

@@ -15,9 +15,10 @@ use std::os::raw::c_int;
 
 use criterion::profiler::Profiler;
 use criterion::{Bencher, Criterion, criterion_group, criterion_main};
-use firewood_storage::{Children, LeafNode, Node, Path, PathComponent};
+use firewood_storage::{
+    Children, LeafNode, Node, PartialPath, PathComponent, TriePathFromUnpackedBytes,
+};
 use pprof::ProfilerGuard;
-use smallvec::SmallVec;
 
 use std::path::Path as FsPath;
 
@@ -82,7 +83,7 @@ fn to_bytes(input: &Node) -> Vec<u8> {
 fn leaf(c: &mut Criterion) {
     let mut group = c.benchmark_group("leaf");
     let input = Node::Leaf(LeafNode {
-        partial_path: Path(SmallVec::from_slice(&[0, 1])),
+        partial_path: PartialPath::path_from_unpacked_bytes(&[0, 1]).unwrap(),
         value: Box::new([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]),
     });
 
@@ -94,7 +95,7 @@ fn leaf(c: &mut Criterion) {
 fn branch(c: &mut Criterion) {
     let mut group = c.benchmark_group("has_value");
     let mut input = Node::Branch(Box::new(firewood_storage::BranchNode {
-        partial_path: Path(SmallVec::from_slice(&[0, 1])),
+        partial_path: PartialPath::path_from_unpacked_bytes(&[0, 1]).unwrap(),
         value: Some(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9].into_boxed_slice()),
         children: Children::from_fn(|i| {
             if i.as_u8() == 0 {