From 6b702bd4a8d84b27a62213627fe3e640959661af Mon Sep 17 00:00:00 2001
From: Qyriad <qyriad@qyriad.me>
Date: Fri, 9 May 2025 15:10:23 +0200
Subject: [PATCH] rename MerklePath::inner_nodes to authenticated_nodes and
 update docs

This name better reflects its actual functionality, but is open to
bikeshedding.
---
 miden-crypto/src/merkle/path.rs | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/miden-crypto/src/merkle/path.rs b/miden-crypto/src/merkle/path.rs
index 28e78bf..0b291f2 100644
--- a/miden-crypto/src/merkle/path.rs
+++ b/miden-crypto/src/merkle/path.rs
@@ -88,21 +88,31 @@ impl MerklePath {
         Ok(())
     }
 
-    /// Returns an iterator over every inner node of this [MerklePath].
+    /// Given the node this path opens to, return an iterator of all the nodes that are known via
+    /// this path.
     ///
-    /// The iteration order is unspecified.
+    /// Each item in the iterator is an [InnerNodeInfo], containing the hash of a node as `.value`,
+    /// and its two children as `.left` and `.right`. The very first item in that iterator will be
+    /// the parent of `node_to_prove`, either `left` or `right` will be `node_to_prove` itself, and
+    /// the other child will be `node_to_prove` as stored in this [MerklePath].
+    ///
+    /// From there, the iterator will continue to yield every further parent and both of its
+    /// children, up to and including the root node.
+    ///
+    /// If `node_to_prove` is not the node this path is an opening to, or `index` is not the
+    /// correct index for that node, the returned nodes will be meaningless.
     ///
     /// # Errors
     /// Returns an error if the specified index is not valid for this path.
-    pub fn inner_nodes(
+    pub fn authenticated_nodes(
         &self,
         index: u64,
-        node: RpoDigest,
+        node_to_prove: RpoDigest,
     ) -> Result<InnerNodeIterator, MerkleError> {
         Ok(InnerNodeIterator {
             nodes: &self.nodes,
             index: NodeIndex::new(self.depth(), index)?,
-            value: node,
+            value: node_to_prove,
         })
     }
 }
@@ -293,7 +303,8 @@ mod tests {
         let node = int_to_node(5);
         let root = merkle_path.compute_root(index, node).unwrap();
 
-        let inner_root = merkle_path.inner_nodes(index, node).unwrap().last().unwrap().value;
+        let inner_root =
+            merkle_path.authenticated_nodes(index, node).unwrap().last().unwrap().value;
 
         assert_eq!(root, inner_root);
     }