feat(hash_builder): add full-branch-updates feature for storing all branch nodes

[zerosnacks]

Context

Builds on top of #123 to address issue reported in #25.

Summary

Adds an opt-in full-branch-updates feature flag that stores all branch nodes referenced by hash in updated_branch_nodes, including those with only leaf children. This is required for complete incremental trie sync.

Supersedes #25.

The Problem

The current store_branch_node only stores a branch if it has branch children:

let store_in_db_trie = !self.tree_masks[len].is_empty() || !self.hash_masks[len].is_empty();

This means branch nodes whose children are all leaves are omitted from updates. This is intentional as a write I/O optimization for reth, but breaks incremental sync for other consumers.

Affected scenarios:

• Small contracts with few storage slots
• Sparse trie regions where all children are leaves
• Fresh tries built without existing database data

The Solution

Add a full-branch-updates feature flag that enables a third condition: store the branch if its parent references it as a hashed child.

#[cfg(feature = "full-branch-updates")]
{
    let parent_index = len - 1;
    let flag = TrieMask::from_nibble(current.get_unchecked(parent_index));
    has_branch_children
        || (self.hash_masks[parent_index] & flag) != TrieMask::default()
}

#[cfg(not(feature = "full-branch-updates"))]
{
    has_branch_children
}

Key design decisions:

• Uses compile-time #[cfg] checks - zero runtime overhead for the default path
• Default behavior (without feature) is unchanged - reth continues working as before
• Consumers needing complete updates opt-in via features = ["full-branch-updates"]

Tests

Tests requiring the new behavior are gated behind the full-branch-updates feature:

• test_updates_root - Verifies root branch is stored for simple two-leaf trie
• test_trie_updates_branch_nodes - Verifies expected number of branch updates
• test_small_storage_trie_updates - Tests the exact failing scenario from fix root updates bug in hash_builder #25
• test_deep_divergence_empty_values - Edge case with empty leaf values
• test_mask_propagation_across_depths - Multi-depth mask propagation
• test_mask_isolation_successive_subtrees - Verifies mask isolation across subtrees
• arbitrary_branch_updates_complete - Proptest verifying completeness (assertion only with feature)

Impact

• Not a breaking change - default behavior is preserved
• Root hash computation is unchanged (only affects updated_branch_nodes)
• Consumers can opt-in when they need complete trie updates

[codspeed-hq]

CodSpeed Performance Report

Merging this PR will degrade performance by 12.58%

_{Comparing fix/store-branch-node-updates (c5ce39f) with zerosnacks/proptest-coverage (eec17e7)}

Summary

❌ 3 regressed benchmarks
✅ 1 untouched benchmark

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	trie[8]	405.3 ns	463.6 ns	-12.58%
❌	trie[16]	408.3 ns	466.7 ns	-12.5%
❌	trie[32]	414.4 ns	472.8 ns	-12.34%

[zerosnacks]

cc @Rjected + @mediocregopher + @shekhirin for visibility

PR builds on test suite expansion in #123

[mediocregopher]

@zerosnacks not storing the root node or branch nodes with only leaf children are deliberate design decions; storing a branch on disk requires write IO, and uses more space, so there's a tradeoff in terms of how much read IO it saves us later. If you can show benchmarks which challenge this design then we could be open to this change, but as it is I would say this behavior is intentional.

EDIT: I guess the above applies to reth specifically, which uses the HashBuilder heavily. If other projects want to use the HashBuilder differently we can also talk about making this behavior optional.

[zerosnacks]

@mediocregopher I've updated the PR to add a new opt-in feature flag full-branch-updates to resolve #25. This should therefore have no performance impact on Reth.

The CodSpeed regression appears to be flakiness on their side, I am unable to reproduce it locally.

[mediocregopher]

@zerosnacks just to make sure you're aware, this is not handling cases of branch nodes which are children of extension nodes. We never store the extension's hash in its parent branch, and therefore this wouldn't set store_in_db_trie for the child branch (also because I think parent_index isn't handling the extension case either)

[zerosnacks]

I see, I'll close this PR for now as I lack sufficient context and this is sensitive code