go-ethereum/triedb/pathdb
CPerezz b6d415c88d
trie/bintrie: replace BinaryNode interface with GC-free NodeRef arena (#34055)
## Summary

Replace the `BinaryNode` interface with `NodeRef uint32` indices into
typed arena pools, eliminating GC-scanned pointers from binary trie
nodes.

Inspired by [fjl's
observation](https://github.com/ethereum/go-ethereum/pull/34034#issuecomment-4075176446):
> *"if the binary trie produces such a large graph, it should probably
be changed so that the trie node type does not contain pointers. The
runtime does not scan objects that do not contain pointers, so it can
really help with the performance to build it this way."*

### The problem

CPU profiling of the binary trie (EIP-7864) showed **44% of CPU time in
garbage collection**. Each `InternalNode` held two `BinaryNode`
interface values (2 pointer-words each), and the GC scanned every one.
With ~25K `InternalNode`s in memory during block processing, this
created enormous GC pressure.

### The solution

`NodeRef` is a compact `uint32` (2-bit kind tag + 30-bit pool index).
`NodeStore` manages chunked typed pools per node kind:
- **InternalNode pool**: ZERO Go pointers (children are `NodeRef`, hash
is `[32]byte`) → noscan spans
- **HashedNode pool**: ZERO Go pointers → noscan spans
- **StemNode pool**: retains `Values [][]byte` (matching existing
format)

The serialization format is unchanged — flat InternalNode
`[type][leftHash][rightHash]` = 65 bytes.

## Benchmark: Apple M4 Pro (`--benchtime=10s --count=3`, on top of
#34021)

| Metric | Baseline | Arena | Delta |
|--------|----------|-------|-------|
| Approve (Mgas/s) | 374 | 382 | **+2.1%** |
| BalanceOf (Mgas/s) | 885 | 901 | **+1.8%** |
| Approve allocs/op | 775K | **607K** | **-21.7%** |
| BalanceOf allocs/op | 265K | **228K** | **-14.0%** |

## Benchmark: AMD EPYC 48-core (50GB state, execution-specs ERC-20, on
top of #34021 + #34032)

| Benchmark | Baseline | Arena | Delta |
|-----------|----------|-------|-------|
| erc20_approve (write) | 22.4 Mgas/s | **27.0 Mgas/s** | **+20.5%** |
| mixed_sload_sstore | 62.9 Mgas/s | **97.3 Mgas/s** | **+54.7%** |
| erc20_balanceof (read) | 180.8 Mgas/s | 167.6 Mgas/s | -7.3% (cold
cache variance) |

The arena benefit scales with heap size — the EPYC (larger heap, more GC
pressure) shows much larger gains than the M4 Pro (efficient unified
memory). The mixed workload baseline was unstable (62.9 vs 16.3 Mgas/s
between runs due to GC-induced throughput collapse); the arena
eliminates this entirely (95-97 Mgas/s, stable).

## Dependencies

Benchmarked with #34021 (H01 N+1 fix) + #34032 (R14 parallel hashing).
No code dependency — applies independently to master.

All test suites pass (`trie/bintrie` with `-race`, `core/state`,
`triedb/pathdb`, `cmd/geth`).

---------

Co-authored-by: Guillaume Ballet <3272758+gballet@users.noreply.github.com>
2026-04-20 14:08:30 +02:00
..
buffer.go core, ethdb, triedb: add batch close (#33708) 2026-03-04 11:17:47 +01:00
config.go triedb/pathdb: enhance history index initer (#33640) 2026-03-17 15:29:30 +01:00
context.go core, triedb/pathdb: final integration (snapshot integration pt 5) (#30661) 2025-05-16 18:29:38 +08:00
database.go trie/bintrie: replace BinaryNode interface with GC-free NodeRef arena (#34055) 2026-04-20 14:08:30 +02:00
database_test.go cmd, core, trie, triedb: split CachingDB into merkle + binary dbs. (#34700) 2026-04-17 08:55:54 +08:00
difflayer.go triedb/pathdb: return nodeLoc by value to avoid heap allocation (#33819) 2026-02-11 22:14:43 +08:00
difflayer_test.go cmd, core, eth, triedb/pathdb: track node origins in the path database (#32418) 2025-09-05 10:37:05 +08:00
disklayer.go triedb/pathdb: implement history index pruner (#33999) 2026-04-02 00:21:58 +02:00
errors.go core, triedb/pathdb: final integration (snapshot integration pt 5) (#30661) 2025-05-16 18:29:38 +08:00
execute.go cmd, core, eth, triedb/pathdb: track node origins in the path database (#32418) 2025-09-05 10:37:05 +08:00
fileutils_unix.go triedb/pathdb: introduce file-based state journal (#32060) 2025-07-15 11:45:20 +08:00
fileutils_windows.go triedb/pathdb: introduce file-based state journal (#32060) 2025-07-15 11:45:20 +08:00
flush.go triedb/pathdb: use copy instead of append to reduce memory alloc (#33044) 2025-12-11 09:37:16 +08:00
generate.go core, eth: add lock protection in snap sync (#33428) 2025-12-19 09:36:48 +01:00
generate_test.go triedb/pathdb, eth: use double-buffer mechanism in pathdb (#30464) 2025-06-22 20:40:54 +08:00
history.go cmd, core, trie, triedb: split CachingDB into merkle + binary dbs. (#34700) 2026-04-17 08:55:54 +08:00
history_index.go triedb/pathdb: improve trienode reader for searching (#33681) 2026-01-27 20:05:35 +08:00
history_index_block.go triedb/pathdb: improve trienode reader for searching (#33681) 2026-01-27 20:05:35 +08:00
history_index_block_test.go triedb/pathdb: introduce extension to history index structure (#33399) 2026-01-08 09:57:35 +01:00
history_index_iterator.go core, eth, internal, triedb/pathdb: enable eth_getProofs for history (#32727) 2026-01-22 09:19:27 +08:00
history_index_iterator_test.go core, eth, internal, triedb/pathdb: enable eth_getProofs for history (#32727) 2026-01-22 09:19:27 +08:00
history_index_pruner.go triedb/pathdb: implement history index pruner (#33999) 2026-04-02 00:21:58 +02:00
history_index_pruner_test.go triedb/pathdb: implement history index pruner (#33999) 2026-04-02 00:21:58 +02:00
history_index_test.go triedb/pathdb: introduce extension to history index structure (#33399) 2026-01-08 09:57:35 +01:00
history_indexer.go triedb/pathdb: implement history index pruner (#33999) 2026-04-02 00:21:58 +02:00
history_indexer_state.go triedb/pathdb: enhance history index initer (#33640) 2026-03-17 15:29:30 +01:00
history_indexer_test.go triedb/pathdb: enhance history index initer (#33640) 2026-03-17 15:29:30 +01:00
history_inspect.go triedb/pathdb: allow single-element history ranges (#33329) 2025-12-01 10:19:21 +08:00
history_reader.go triedb/pathdb: improve trienode reader for searching (#33681) 2026-01-27 20:05:35 +08:00
history_reader_test.go triedb/pathdb: implement trienode history indexing scheme (#33551) 2026-01-17 20:28:37 +08:00
history_state.go triedb/pathdb: implement trienode history indexing scheme (#33551) 2026-01-17 20:28:37 +08:00
history_state_test.go core/rawdb, triedb/pathdb: introduce trienode history (#32596) 2025-10-10 14:51:27 +08:00
history_trienode.go triedb/pathdb: preallocate slices in decodeRestartTrailer (#33715) 2026-01-30 21:14:15 +08:00
history_trienode_test.go triedb/pathdb: improve trienode reader for searching (#33681) 2026-01-27 20:05:35 +08:00
history_trienode_utils.go triedb/pathdb: implement trienode history indexing scheme (#33551) 2026-01-17 20:28:37 +08:00
history_trienode_utils_test.go triedb/pathdb: implement trienode history indexing scheme (#33551) 2026-01-17 20:28:37 +08:00
holdable_iterator.go trie/pathdb: state iterator (snapshot integration pt 4) (#30654) 2024-12-16 21:10:08 +08:00
holdable_iterator_test.go trie/pathdb: state iterator (snapshot integration pt 4) (#30654) 2024-12-16 21:10:08 +08:00
iterator.go triedb, triedb/internal, triedb/pathdb: add GenerateTrie + extract shared pipeline into triedb/internal (#34654) 2026-04-07 14:36:53 +08:00
iterator_binary.go triedb/pathdb, eth: use double-buffer mechanism in pathdb (#30464) 2025-06-22 20:40:54 +08:00
iterator_fast.go triedb/pathdb, eth: use double-buffer mechanism in pathdb (#30464) 2025-06-22 20:40:54 +08:00
iterator_test.go triedb/pathdb: fix journal resolution in pathdb (#32097) 2025-06-26 17:19:02 +02:00
journal.go triedb/pathdb: enable trienode history (#32621) 2026-01-17 21:23:48 +08:00
layertree.go triedb/pathdb: fix lookup sentinel collision with zero disk layer root (#34680) 2026-04-09 13:39:38 +08:00
layertree_test.go cmd, core, trie, triedb: split CachingDB into merkle + binary dbs. (#34700) 2026-04-17 08:55:54 +08:00
lookup.go triedb/pathdb: fix lookup sentinel collision with zero disk layer root (#34680) 2026-04-09 13:39:38 +08:00
metrics.go triedb/pathdb: implement history index pruner (#33999) 2026-04-02 00:21:58 +02:00
nodes.go core, eth, internal, triedb/pathdb: enable eth_getProofs for history (#32727) 2026-01-22 09:19:27 +08:00
nodes_test.go rlp, trie, triedb/pathdb: compress trienode history (#32913) 2026-01-08 21:58:02 +08:00
reader.go triedb/pathdb: fix typo (#34762) 2026-04-20 10:07:41 +08:00
states.go triedb/pathdb: preallocate slices in encode methods (#33736) 2026-02-02 15:27:37 +08:00
states_test.go all: update license comments and AUTHORS (#31133) 2025-02-05 23:01:17 +01:00
verifier.go triedb, triedb/internal, triedb/pathdb: add GenerateTrie + extract shared pipeline into triedb/internal (#34654) 2026-04-07 14:36:53 +08:00