add comments

Author: phbnf

proof/verify.go

@@ -193,9 +193,17 @@ func rootFromSubtreeConsistencyProof(hasher merkle.LogHasher, start, end, size u
 	//
 	// Split the proof in two, where paths to leaves |end-1| and |size-1| diverge.
 	forkLevel := bits.Len64((end - 1) ^ (size - 1))
+	// Height of the rightmost full subtree within the argument subtree.
+	// The proof does not contain any node below this level.
 	shift := bits.TrailingZeros64(end - start)
 
+	// The first node of the proof is the root of the rightmost subtree within
+	// the argument subtree.
 	seed, pStart := proof[0], 1
+	// Unless the argument subtree is full, in which case that rightmost subtree
+	// is the argument subtree itself. Its root is not included in the proof
+	// since a client verifying a subtree inclusion proof is expected to already
+	// know what the root of that subtree is.
 	if (end - start) == 1<<uint(shift) {
 		seed, pStart = root1, 0
 	}
@@ -205,15 +213,24 @@ func rootFromSubtreeConsistencyProof(hasher merkle.LogHasher, start, end, size u
 	}
 	proof = proof[pStart:]
 
+	// Compute the root of the [start, end) subtree for trees of sizes
+	// |end| and |size|.
 	subtreeRoot, grownSubtreeRoot, remainingProof := chainSubtree(hasher, seed, proof, start, end, size)
 	if err := verifyMatch(subtreeRoot, root1); err != nil {
 		return nil, err
 	}
 
-	h := bits.Len64((end - 1) ^ start)
-	macroIndex := start >> uint(h)
-	macroSize := ((size - 1) >> uint(h)) + 1
-	return RootFromInclusionProof(hasher, macroIndex, macroSize, grownSubtreeRoot, remainingProof)
+	// The remainder of the proof is an inclusion proof for grownSubtreeRoot
+	// into the parent tree of size |size|.
+	// Shift the tree down for that node to be a leaf.
+	// xor trims the common prefix between the first and last entry. The bit len
+	// of the result is the height of the subtree.
+	srHeight := bits.Len64((end - 1) ^ start)
+	// shifting indexes to the srHeight times gives the size of the tree at level
+	// srHeight.
+	srIndex := start >> uint(srHeight)
+	macroSize := ((size - 1) >> uint(srHeight)) + 1
+	return RootFromInclusionProof(hasher, srIndex, macroSize, grownSubtreeRoot, remainingProof)
 }
 
 // chainSubtree hashes nodes from proof up to subtree [start, end)'s' root