trie/bintrie: restore load-bearing iterator doc comments

A prior commit aggressively trimmed comments. This restores the
ones that carried real information — ownership contracts on
returned slices, the index-tracking semantics inside Next(),
the Parent() grandparent note, and the "at a leaf" stem rule —
so future readers aren't left guessing. Also elaborates the
parallel-hashing rationale in hashInternal.

trie/bintrie/iterator.go

@@ -47,6 +47,8 @@ func newBinaryNodeIterator(t *BinaryTrie, _ []byte) (trie.NodeIterator, error) {
 	return it, nil
 }
 
+// Next moves the iterator to the next node. If descend is false, children of
+// the current node are skipped.
 func (it *binaryNodeIterator) Next(descend bool) bool {
 	if it.lastErr == errIteratorEnd {
 		return false
@@ -60,11 +62,12 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 
 	switch it.current.Kind() {
 	case KindInternal:
+		// index: 0 = nothing visited, 1 = left visited, 2 = right visited.
 		node := it.store.getInternal(it.current.Index())
 		context := &it.stack[len(it.stack)-1]
 
 		if !descend {
-			// Skip children: pop this node and advance parent
+			// Skip children: pop this node and advance parent.
 			if len(it.stack) == 1 {
 				it.lastErr = errIteratorEnd
 				return false
@@ -75,6 +78,7 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 			return it.Next(true)
 		}
 
+		// Recurse into both children.
 		if context.Index == 0 {
 			if !node.left.IsEmpty() {
 				it.stack = append(it.stack, binaryNodeIteratorState{Node: node.left})
@@ -93,6 +97,7 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 			context.Index++
 		}
 
+		// Reached the end of this node; go back to the parent unless we're at the root.
 		if len(it.stack) == 1 {
 			it.lastErr = errIteratorEnd
 			return false
@@ -103,6 +108,7 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 		return it.Next(descend)
 
 	case KindStem:
+		// Look for the next non-empty value in this stem.
 		sn := it.store.getStem(it.current.Index())
 		for i := it.stack[len(it.stack)-1].Index; i < 256; i++ {
 			if sn.hasValue(byte(i)) {
@@ -111,6 +117,7 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 			}
 		}
 
+		// No more values in this stem; go back to parent to get the next leaf.
 		if len(it.stack) == 1 {
 			it.lastErr = errIteratorEnd
 			return false
@@ -121,6 +128,8 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 		return it.Next(descend)
 
 	case KindHashed:
+		// Resolve the hashed node from disk, then rewire the parent to point at the
+		// resolved node in place.
 		if len(it.stack) < 2 {
 			it.lastErr = errors.New("cannot resolve hashed root during iteration")
 			return false
@@ -137,7 +146,6 @@ func (it *binaryNodeIterator) Next(descend bool) bool {
 			return false
 		}
 
-		// Update the stack and parent with the resolved node
 		oldHashedIdx := it.current.Index()
 		it.current = resolved
 		it.stack[len(it.stack)-1].Node = resolved
@@ -170,6 +178,9 @@ func (it *binaryNodeIterator) Hash() common.Hash {
 	return it.store.ComputeHash(it.current)
 }
 
+// Parent returns the hash of the current node's parent. When the immediate
+// parent is an internal node whose hash has not been materialised, the
+// returned hash may be the one of a grandparent instead.
 func (it *binaryNodeIterator) Parent() common.Hash {
 	if len(it.stack) < 2 {
 		return common.Hash{}
@@ -178,6 +189,7 @@ func (it *binaryNodeIterator) Parent() common.Hash {
 }
 
 // Path returns the bit-path to the current node.
+// Callers must not retain references to the returned slice after calling Next.
 func (it *binaryNodeIterator) Path() []byte {
 	if it.Leaf() {
 		return it.LeafKey()
@@ -196,6 +208,11 @@ func (it *binaryNodeIterator) NodeBlob() []byte {
 	return it.store.SerializeNode(it.current)
 }
 
+// Leaf reports whether the iterator is currently positioned at a leaf value.
+// A StemNode holds up to 256 values; the iterator is only "at a leaf" when
+// positioned at a specific non-nil value inside the stem, not merely at the
+// StemNode itself. The stack Index points to the NEXT position after the
+// current value, so Index == 0 means we haven't yielded anything yet.
 func (it *binaryNodeIterator) Leaf() bool {
 	if it.current.Kind() != KindStem {
 		return false
@@ -215,6 +232,9 @@ func (it *binaryNodeIterator) Leaf() bool {
 	return sn.hasValue(byte(currentValueIndex))
 }
 
+// LeafKey returns the key of the leaf. Panics if the iterator is not
+// positioned at a leaf. Callers must not retain references to the returned
+// slice after calling Next.
 func (it *binaryNodeIterator) LeafKey() []byte {
 	if it.current.Kind() != KindStem {
 		panic("Leaf() called on an binary node iterator not at a leaf location")
@@ -223,6 +243,9 @@ func (it *binaryNodeIterator) LeafKey() []byte {
 	return sn.Key(it.stack[len(it.stack)-1].Index - 1)
 }
 
+// LeafBlob returns the leaf value. Panics if the iterator is not positioned
+// at a leaf. Callers must not retain references to the returned slice after
+// calling Next.
 func (it *binaryNodeIterator) LeafBlob() []byte {
 	if it.current.Kind() != KindStem {
 		panic("LeafBlob() called on an binary node iterator not at a leaf location")
@@ -231,6 +254,9 @@ func (it *binaryNodeIterator) LeafBlob() []byte {
 	return sn.getValue(byte(it.stack[len(it.stack)-1].Index - 1))
 }
 
+// LeafProof returns the Merkle proof of the leaf. Panics if the iterator is
+// not positioned at a leaf. Callers must not retain references to the
+// returned slices after calling Next.
 func (it *binaryNodeIterator) LeafProof() [][]byte {
 	if it.current.Kind() != KindStem {
 		panic("LeafProof() called on an binary node iterator not at a leaf location")

trie/bintrie/store_commit.go

@@ -46,7 +46,12 @@ func (s *NodeStore) ComputeHash(ref NodeRef) common.Hash {
 	}
 }
 
-// hashInternal hashes an InternalNode, parallelising at shallow depths.
+// hashInternal hashes an InternalNode and caches the result.
+//
+// At shallow depths (< parallelHashDepth) the left subtree is hashed in a
+// goroutine while the right subtree is hashed inline, then the two digests
+// are combined. Below that threshold the goroutine spawn cost outweighs the
+// hashing work, so deeper nodes hash both children sequentially.
 func (s *NodeStore) hashInternal(idx uint32) common.Hash {
 	node := s.getInternal(idx)
 	if !node.mustRecompute {