commitment: add TrieReader — stateless read-only Patricia trie navigation#20287
Merged
commitment: add TrieReader — stateless read-only Patricia trie navigation#20287
Conversation
Implement TrieReader in execution/commitment/ that navigates the Patricia trie by hashed key without any mutable grid state. Each Lookup call starts from the root and descends independently via PatriciaContext.Branch(). Includes parseCellAt for single-cell extraction from branch data, and comprehensive tests covering hits, misses, extensions, and multi-level descent.
- Remove unused accountKeyLen field from TrieReader (dead code) - Fix redundant depth bounds check: change > to >= to avoid unnecessary Branch() call when key is fully consumed - Remove duplicate depth >= len(hashedKey) check that became dead code - Add test for Branch() error propagation - Add test for empty/nil hashedKey edge case
14 tasks
awskii
requested review from
AskAlexSharov,
Giulio2002,
antonis19 and
taratorio
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces a new lightweight TrieReader in execution/commitment to support stateless, read-only navigation of the existing Patricia trie encoding via PatriciaContext.Branch, avoiding the large mutable HexPatriciaHashed grid state.
Changes:
- Added
TrieReaderwithLookup(hashedKey []byte)that descends from the root by compact-prefix branch reads and per-nibble cell parsing. - Added unit tests covering hits/misses, extension traversal, multi-level descent, and error propagation with a mock
PatriciaContext. - Added an implementation plan document under
completed/.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| execution/commitment/trie_reader.go | New stateless trie lookup implementation using branch reads + cell parsing. |
| execution/commitment/trie_reader_test.go | New unit tests for TrieReader behavior across common paths and failure modes. |
| completed/plan.md | Design/implementation plan for TrieReader and its intended algorithm. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+93
to
+99
| afterMap := binary.BigEndian.Uint16(branchData[2:4]) | ||
| cellData := branchData[4:] | ||
| nibble := int(hashedKey[depth]) | ||
|
|
||
| if afterMap&(uint16(1)<<nibble) == 0 { | ||
| return c, false, nil | ||
| } |
Comment on lines
+135
to
+142
| func TestTrieReader_AccountLookupHit(t *testing.T) { | ||
| t.Parallel() | ||
|
|
||
| // Build a simple single-level trie: | ||
| // Root branch has nibble 0xa pointing to an account leaf. | ||
| ctx := newTrieReaderTestCtx() | ||
| addr := bytes.Repeat([]byte{0xAB}, 20) | ||
|
|
…tests TrieReader could not read actual commitment data because it was missing the deriveHashedKeys call that HexPatriciaHashed.unfoldBranchNode uses to reconstruct hashed nibble paths from plain keys stored in branch data. Key changes: - TrieReader now calls deriveHashedKeys on parsed cells (keccak hashing plain accountAddr/storageAddr to recover the full hashed extension) - Fixed storage lookups: account cells with hash at depth < 64 continue into the storage sub-trie instead of returning prematurely - Added exported cell accessor methods for external callers - NewTrieReader takes accountKeyLen parameter - All mock tests updated to use hash-consistent data - Added TestTrieReader_RoundTripWithHPH: verifies accounts + storage lookups against real HexPatriciaHashed.Process output - Added TestTrieReader_RoundTripWithHPH_ManyAccounts: 100 accounts - Fixed db/state integration test: 200/200 accounts, 100/100 storage - Added NewTrieContextRo to commitmentdb for read-only branch access
…deBranch refactor Update TrieReader and tests for API changes from main: - HexNibblesToCompactBytes → nibbles.HexToCompact - EncodeBranch callback → *[16]cellEncodeData array
…ation - Remove completed/plan.md (obsolete, pseudocode mismatched implementation) - Add nibble bounds check in Lookup (validates hashedKey[depth] <= 0x0f) - parseCellAt errors already include depth+nibble context from prior commit
AskAlexSharov
approved these changes
Apr 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
TrieReader— a lightweight, stateless read-only navigator for the Patricia trie. EachLookupcall starts from the root and descends independently without any mutable grid state.Motivation
HexPatriciaHashedcarries ~200KB of mutable grid state (grid[64][16]cell,touchMap,afterMap, etc.) designed for update processing. For read-only path queries (proofs, witnesses, integrity checks, tooling) this is unnecessary.Design
ctx.Branch(compact(prefix))at each level, parses cells from branch dataderiveHashedKeys: reconstructs hashed nibble extensions from plain keys (accountAddr/storageAddr) via keccak — the same stepunfoldBranchNodedoes. This is critical for navigating past leaf cells into storage sub-triesExported cell accessors
Tests
TestTrieReader_RoundTripWithHPHHexPatriciaHashed.Process→ TrieReader lookupTestTrieReader_RoundTripWithHPH_ManyAccountsTestTrieReader_IntegrationWithRealData(db/state)Files
execution/commitment/trie_reader.go— implementation + cell accessorsexecution/commitment/trie_reader_test.go— 12 tests (mock + HPH round-trip)db/state/trie_reader_integration_test.go— full-stack integration testexecution/commitment/commitmentdb/commitment_context.go—NewTrieContextRofor read-only branch accessRelated