From f4f773563c695194236f16078761f308b7a4b3a5 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      | 25 ++++++++++++++++++-------
 miden-crypto/src/merkle/store/mod.rs |  2 +-
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/miden-crypto/src/merkle/path.rs b/miden-crypto/src/merkle/path.rs
index 28e78bf..dce31ac 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,
         })
     }
 }
@@ -162,7 +172,7 @@ impl IntoIterator for MerklePath {
     }
 }
 
-/// An iterator over internal nodes of a [MerklePath].
+/// An iterator over internal nodes of a [MerklePath]. See [`MerklePath::authenticated_nodes()`]
 pub struct InnerNodeIterator<'a> {
     nodes: &'a Vec<RpoDigest>,
     index: NodeIndex,
@@ -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);
     }
diff --git a/miden-crypto/src/merkle/store/mod.rs b/miden-crypto/src/merkle/store/mod.rs
index ac8e52f..db1db9f 100644
--- a/miden-crypto/src/merkle/store/mod.rs
+++ b/miden-crypto/src/merkle/store/mod.rs
@@ -393,7 +393,7 @@ impl<T: KvMap<RpoDigest, StoreNode>> MerkleStore<T> {
         node: RpoDigest,
         path: MerklePath,
     ) -> Result<RpoDigest, MerkleError> {
-        let root = path.inner_nodes(index, node)?.fold(RpoDigest::default(), |_, node| {
+        let root = path.authenticated_nodes(index, node)?.fold(RpoDigest::default(), |_, node| {
             let value: RpoDigest = node.value;
             let left: RpoDigest = node.left;
             let right: RpoDigest = node.right;