extra comments

Author: phbnf

proof/verify.go

@@ -234,27 +234,38 @@ func rootFromSubtreeConsistencyProof(hasher merkle.LogHasher, start, end, size u
 
 	// Verify the second root.
 	hash2 := chainInner(hasher, seed, proof[:inner], mask)
-	// Then, chain the upper part of the proof.
 	hash2 = chainBorderRight(hasher, hash2, proof[inner:])
 	return hash2, nil
 }
 
 // decompInclProof breaks down inclusion proof for a leaf at the specified
 // |index| in a tree of the specified |size| into 2 components. The splitting
 // point between them is where paths to leaves |index| and |size-1| diverge.
-// Returns lengths of the bottom and upper proof parts correspondingly. The sum
+// Returns lengths of the inner and border proof parts correspondingly. The sum
 // of the two determines the correct length of the inclusion proof.
+//
+// Inner nodes are left or right siblings depending on the level they are used
+// in the proof. There can be multiple nodes per level.
+// Border nodes are left siblings only. There's always only one node per level.
 func decompInclProof(index, size uint64) (int, int) {
 	inner := innerProofSize(index, size)
 	border := bits.OnesCount64(index >> uint(inner))
 	return inner, border
 }
 
-// decompSubtreeProof computes the exact proof slice indices needed to reconstruct
-// the [start, end) subtree root (hash1):
-//   - subInner: end index of inner proof hashes inside the subtree (proof[:subInner])
-//   - inner: start index of border proof hashes (proof[inner:])
-//   - inner+subBorder: end index of border proof hashes inside the subtree
+// decompSubtreeProof computes the exact proof slice indices needed to
+// reconstruct the [start, end) subtree root
+//   - subInner: end index of inner proof hashes inside the subtree
+//     (proof[:subInner]), regardless of the size of the parent tree.
+//     These nodes can be left or right siblings depending on the level at
+//     which they are used in the proof. Only left siblings are required to
+//     reconstruct the subtree root.
+//   - inner: end index of inner proof hashes inside the tree, and potentially
+//     outside of the subtree. It is also the start index of border proof
+//     hashes (proof[inner:]). Border proof hashes are left siblings only.
+//     There's one per level and they can be inside or outside of the subtree.
+//   - inner+subBorder: end index of border proof hashes inside the subtree.
+//     (proof[inner:inner+subBorder]). These nodes are left siblings only.
 func decompSubtreeProof(start, end, size uint64, border int) (int, int, int) {
 	// xor trims the common prefix between the first and last entry. The bit len
 	// of the result is the height of the subtree.
@@ -268,14 +279,18 @@ func decompSubtreeProof(start, end, size uint64, border int) (int, int, int) {
 
 	// Number of inner proof nodes from level |shift| up to subtree height |h|
 	// (clamped at |forkLevel|) that belong inside the [start, end) subtree.
+	// We take the minimum between h and forkLevel to make sure that subInner
+	// isn't higher than the subtree root. Substract shift since the proof
+	// starts at this level.
 	subInner := min(h, forkLevel) - shift
 	// Total number of inner proof nodes between level |shift| and |forkLevel|.
 	inner := forkLevel - shift
 	// Number of border proof nodes above |forkLevel| and below subtree height |h|
-	// that belong inside the [start, end) subtree.
+	// that belong inside the [start, end) subtree. Use max as the border proof
+	// might not include any node that belong to the subtree.
 	subBorder := max(0, border-bits.OnesCount64((end-1)>>uint(h)))
-	// The proof slice indices needed to reconstruct hash1 are [0:subInner] for inner
-	// chaining and [inner:inner+subBorder] for border chaining.
+	// The proof slice indices needed to reconstruct hash1 are [0:subInner] for
+	// inner-right chaining and [inner:inner+subBorder] for border chaining.
 	return subInner, inner, inner + subBorder
 }