docs(trie): document MDBX ordering assumptions in TrieWalker and Trie… (paradigmxyz#17906)

Author: dharmvr1

crates/trie/trie/src/node_iter.rs

@@ -43,7 +43,10 @@ struct SeekedHashedEntry<V> {
     result: Option<(B256, V)>,
 }
 
-/// An iterator over existing intermediate branch nodes and updated leaf nodes.
+/// Iterates over trie nodes for hash building.
+///
+/// This iterator depends on the ordering guarantees of [`TrieCursor`],
+/// and additionally uses hashed cursor lookups when operating on storage tries.
 #[derive(Debug)]
 pub struct TrieNodeIter<C, H: HashedCursor> {
     /// The walker over intermediate nodes.

crates/trie/trie/src/trie_cursor/mod.rs

@@ -35,7 +35,8 @@ pub trait TrieCursorFactory {
     ) -> Result<Self::StorageTrieCursor, DatabaseError>;
 }
 
-/// A cursor for navigating a trie that works with both Tables and `DupSort` tables.
+/// A cursor for traversing stored trie nodes. The cursor must iterate over keys in
+/// lexicographical order.
 #[auto_impl::auto_impl(&mut, Box)]
 pub trait TrieCursor: Send + Sync {
     /// Move the cursor to the key and return if it is an exact match.

crates/trie/trie/src/walker.rs

@@ -10,9 +10,9 @@ use tracing::{instrument, trace};
 #[cfg(feature = "metrics")]
 use crate::metrics::WalkerMetrics;
 
-/// `TrieWalker` is a structure that enables traversal of a Merkle trie.
-/// It allows moving through the trie in a depth-first manner, skipping certain branches
-/// if they have not changed.
+/// Traverses the trie in lexicographic order.
+///
+/// This iterator depends on the ordering guarantees of [`TrieCursor`].
 #[derive(Debug)]
 pub struct TrieWalker<C> {
     /// A mutable reference to a trie cursor instance used for navigating the trie.