tlog: Add MTC subtree primitives

[beautifulentropy]

Implement the generation and verification of MTC subtree consistency proofs, which prove that an aligned interval of the log (a subtree) belongs to the tree under a given root hash. The MTC draft defines these in section 4.

x/mod's sumdb/tlog provides the hash primitives and the stored-hash reader these functions use. Its proofs cover only two cases: an inclusion proof for a single entry and a consistency proof for a prefix of the log. MTC requires a proof for any subtree; x/mod has no such proof.

Export four functions:

• SubtreeHash computes an RFC 6962 Merkle Tree Hash over a list of leaf hashes.
• ValidSubtree reports whether a given interval is a valid MTC Subtree.
• SubtreeConsistencyProof generates an MTC Subtree Consistency Proof.
• VerifySubtreeConsistency verifies an MTC Subtree Consistency Proof against a given root hash.

A note to reviewers: this package and its tests were written with assistance from Claude Opus 4.8 and Fable 5. That being said, it has been reviewed and extensively revised by myself before submission.

[jsha]

After a first look, my high level comments:

There are a number of places where subtree.go panics. I notice that the upstream tlog.go panics in a bunch of places where the match is wrong too, but I'd like to see if we can have fewer panic sites to reason about. For instance, what if ValidSubtree() returns a Subtree() object, which has accessors for Hi(), Lo(), Size(), and Height(). We can guarantee in the contract for Size() and Height(), for instance, that they are positive (non-negative and non-zero). This might also let us consolidate the various //nolint: gosec // G115 correctness comments into a smaller number of places.

We could make this into a constructor:

type Subtree struct {
  start, len, treeSize uint64
}

func New(start, end, treeSize int64) (Subtree, error) {}

I notice that both internal callers of ValidSubtree() check end > treeSize immediately after. That suggests to me that ValidSubtree() should be a function of not just start and end, but also of tree size, so that we can check that property as part of it.

[jsha]

The comments and the spec say we should use BIT_CEIL(end-start), but the code says end-start-1. Why's that?

Also, a nit: it's nice for the correctness comment to be easily matched to the code that enforces it. So saying "start >= end, so end-start is positive" would be a little easier to validate. Also note that "positive" is a stronger constraint than "non-negative" since it excludes zero.

[beautifulentropy]

The comments and the spec say we should use BIT_CEIL(end-start), but the code says end-start-1. Why's that?

Fair, there needs to be a much better comment above this line explaining what's going on here; I'll add that.

How about:

	// start must be a multiple of BIT_CEIL(end-start). bits.Len64(x) is the bit
	// width of x, so 1<<bits.Len64(x) is the smallest power of two strictly
	// above x, an exclusive ceiling. BIT_CEIL(x) is inclusive, the smallest
	// power of two at least x, so we apply it to end-start-1.
	bitCeil := uint64(1) << bits.Len64(uint64(end-start-1)) //nolint:gosec // G115: the start >= end check above leaves end-start positive, so end-start-1 is non-negative.

	// bitCeil-1 masks the bits below bitCeil, so start & (bitCeil-1) is zero
	// exactly when start is a multiple of bitCeil.
	return uint64(start)&(bitCeil-1) == 0
}

[beautifulentropy]

Also, a nit: it's nice for the correctness comment to be easily matched to the code that enforces it. So saying "start >= end, so end-start is positive" would be a little easier to validate. Also note that "positive" is a stronger constraint than "non-negative" since it excludes zero.

Yes, start > end should read start >= end. But end - start - 1 is non-negative, not positive. A single leaf, for instance [7, 8), is still a valid subtree, and 8 - 7 - 1 = 0.

How about:

//nolint:gosec // G115: the start >= end check above leaves end-start positive (at least 1), so end-start-1 is non-negative.

[jsha]

The sentence "A multiple of a power of two has its low bits zero ..." should go one line lower, right above where we perform this calculation.

[jsha]

IMO these lines should be combined into a default: clause of the switch, to emphasize the fact that there are three different possible outcomes, and this case is only possible when len(leaves) is >=2.

Edit: see above, I think we can get rid of this function.

[jsha]

Since a subtree is a Merkle tree, this calculates a Merkle Tree Hash. I think this function is equivalent to tlog.TreeHash and we can reuse that, right?

I note that this function takes a list of leaves in-memory, while tlog.TreeHash takes a HashReader, which generalizes over hash storage. But if we want to use leaves in-memory, we can pass a HashReaderFunc that accesses them.

So, I think we can do without this function.

[jsha]

I think this can also be implemented in terms of tlog.TreeHash(hi-lo, someReader).

The distinction is that TreeHash will make storage calls starting from zero, but we need to make sure our storage layer is correctly indexing based on the subtree we want. I think we can achieve that with a tlog.HashReaderFunc:

func subtreeHash(lo, hi int64, reader xtlog.HashReader) (xtlog.Hash, error) {
  return tlog.TreeHash(hi-lo, func(zeroBasedIndexes []int64) []Hash {
    var absoluteIndexes []int64
    for _, i := range zeroBasedIndexes {
      absoluteIndexes = append(absoluteIndexes, i+lo)
    }
    return reader.ReadHashes(absoluteIndexes)
  }
}

[beautifulentropy]

Using the HashReaderFunc is very clever, but the way you're calculating the offset is subtly wrong. The indexes TreeHash hands our reader aren't leaf numbers. They're stored hash indexes, a flat numbering of every node in the tree, with leaves and internal nodes interleaved. So i + lo is adding a leaf count to something that isn't a leaf position. The offset has to account for the node's level. A leaf may be lo away from another leaf, but a node spanning 8 leaves moves by only lo / 8.

So instead of offsetting the index, we decode it, shift its position by lo scaled to that level, and re-encode:

level, n := tlog.SplitStoredHashIndex(idx)
absolute := tlog.StoredHashIndex(level, (lo>>level)+n)

Which gives us:

func rangeHash(lo, hi int64, reader tlog.HashReader) (tlog.Hash, error) {
	return tlog.TreeHash(hi-lo, tlog.HashReaderFunc(
		func(zeroBasedIndexes []int64) ([]tlog.Hash, error) {
			absoluteIndexes := make([]int64, len(zeroBasedIndexes))
			for i, idx := range zeroBasedIndexes {
				level, n := tlog.SplitStoredHashIndex(idx)
				absoluteIndexes[i] = tlog.StoredHashIndex(level, (lo>>level)+n)
			}
			return reader.ReadHashes(absoluteIndexes)
		}))
}

But fixing the offset surfaces our next problem. lo>>level is only exact when lo is a multiple of 2^level, which holds for every range we currently pass to rangeHash(). If a later change passes a lo that isn't, the shift drops bits, the index points to a different node, and we silently fold a wrong hash.

So we would need to add a guard:

func rangeHash(lo, hi int64, reader tlog.HashReader) (tlog.Hash, error) {
	return tlog.TreeHash(hi-lo, tlog.HashReaderFunc(
		func(zeroBasedIndexes []int64) ([]tlog.Hash, error) {
			absoluteIndexes := make([]int64, len(zeroBasedIndexes))
			for i, idx := range zeroBasedIndexes {
				level, n := tlog.SplitStoredHashIndex(idx)
				loAtLevel := lo >> level
				if loAtLevel<<level != lo {
					return nil, fmt.Errorf("subtreeHash: lo=%d is not a multiple of 2^%d", lo, level)
				}
				absoluteIndexes[i] = tlog.StoredHashIndex(level, loAtLevel+n)
			}
			return reader.ReadHashes(absoluteIndexes)
		}))
}

For what it's worth, your idea does work. That said, the version we have doesn't require this awkward translation layer that's somewhat difficult to reason about.

[aarongable]

This API shape is surprising to me. Being willing to hash an arbitrary set of leaves a) feels like something to be left for a general package (like xtlog itself), not subtree; and b) feels dangerous! What if the caller doesn't respect the contract that they need to make sure it's a valid subtree first?

I think this package should only expose func SubtreeHash(start, end int64, reader tlog.HashReader) tlog.Hash. It can verify that the interval is a valid subtree, then read all the necessary hashes from the reader itself. This guarantees that we never supply an invalid set of input hashes.

I think the existing API of this function might be acceptable as a private helper, but not as part of the public interface of the package.

[aarongable]

1. There are multiple callers of this function that don't (at least, not obviously to me as a reader) guarantee that n > 1. Seems like we're risking a panic.
2. Why is panicking the correct answer? What goes wrong if we return 0? Or have an explicit error return?

These comments may be obviated if you change the function signature entirely as I suggest above.

[aarongable]

Isn't it the case that a (hypothetical) unaligned perfect subtree would simply not be a valid subtree at all?

If so, can't this be simplified to bits.OnesCount64(end-start) == 1 && valid(start, end)?

[aarongable]

Why is the broken out into a helper function? It has exactly one caller, no documentation, and is just a single stanza. I suggest inlining it into subtreeSubProof.

[aarongable]

This feels like a very non-idiomatic form of recursion, passing the partial result into each sub-call. I think we can get the exact same behavior much more simply:

Suggested change

	func perfectSubtreeIndexes(start, end int64, storedHashIndexes []int64) []int64 {
	level, ok := perfectSubtree(start, end)
	if ok {
	return append(storedHashIndexes, tlog.StoredHashIndex(level, start>>level))
	}
	k := largestPowerOfTwoSmallerThan(end - start)
	storedHashIndexes = perfectSubtreeIndexes(start, start+k, storedHashIndexes)
	return perfectSubtreeIndexes(start+k, end, storedHashIndexes)
	}
	func perfectSubtreeIndexes(start, end int64) []int64 {
	level, ok := perfectSubtree(start, end)
	if ok {
	return []int64{tlog.StoredHashIndex(level, start>>level))}
	}
	k := largestPowerOfTwoSmallerThan(end - start)
	return append(perfectSubtreeIndexes(start, start+k), perfectSubtreeIndexes(start+k, end)...)
	}

[aarongable]

nit: to make the purpose of this function even more obvious, I'd change the signature to:

// splitPoint returns the index at which the given subtree should be split in order to
// produce a perfect subtree on the left and a (potentially) ragged-right subtree on the right.
func splitPoint(start, end int64) int64 {

This would allow the function's return value to directly correspond to mid as used in draft-ietf-plants-merkle-tree-certs-04. It would also allow you to simplify code like below:

-	k := largestPowerOfTwoSmallerThan(end - start)
-	left, rest := combineIntervalHash(start, start+k, hashes)
-	right, rest := combineIntervalHash(start+k, end, rest)
+	mid := splitPoint(start, end)
+	left, rest := combineIntervalHash(start, mid, hashes)
+	right, rest := combineIntervalHash(mid, end, rest)

[aarongable]

This function is only ever used to hash valid subtrees, not arbitrary intervals. So why are we changing language to talk about intervals instead of subtrees?

[aarongable]

This feels too clever, as though you're optimizing for a case we don't actually have (and don't want to support). Even if we do want to compute hashes of arbitrary intervals (which as I note above, I don't think we do -- I'm pretty sure all of our inputs to this function are valid subtrees), the MTC draft shows that any arbitrary interval can be decomposed into two subtrees: a perfect left subtree, and a ragged right subtree.

This function's approach is to do a big recursive "find all the indices", followed by a second recursive "combine the hashes". But the whole thing can be done in a single, much-more-simply recursive "look up hash of left perfect tree, combine with recursive computation of hash of right ragged tree".