docs: clarify note on &mut self usage

crates/trie/common/src/prefix_set.rs

@@ -172,6 +172,19 @@ pub struct PrefixSet {
 
 impl PrefixSet {
     /// Returns `true` if any of the keys in the set has the given prefix
+    ///
+    /// # Note on Mutability
+    ///
+    /// This method requires `&mut self` (unlike typical `contains` methods) because it maintains an
+    /// internal position tracker (`self.index`) between calls. This enables significant performance
+    /// optimization for sequential lookups in sorted order, which is common during trie traversal.
+    ///
+    /// The `index` field allows subsequent searches to start where previous ones left off,
+    /// avoiding repeated full scans of the prefix array when keys are accessed in nearby ranges.
+    ///
+    /// This optimization was inspired by Silkworm's implementation and significantly improves
+    /// incremental state root calculation performance
+    /// ([see PR #2417](https://github.com/paradigmxyz/reth/pull/2417)).
     #[inline]
     pub fn contains(&mut self, prefix: &[u8]) -> bool {
         if self.all {