…SIZE / EXTCODEHASH

Adds a third caching layer to CodeCache (alongside L1 addr→maphash and L2b
ethHash→bytes): codeSizeByEthHash maps the 32-byte Ethereum codeHash to
its byte length. Tiny per-entry footprint (32B key + 8B value vs 5-10 KB
for full bytes) so the same memory budget gives ~1000x the hit surface.
Capped at 1M entries (geth core/state/database_code.go uses the same size).

EXTCODESIZE / EXTCODEHASH callers — historically the slowest opcodes on
the lab dashboard's bench — answer from a single map probe without paying
the file accessor stack cost of the full bytes. Geth-proven; cross-client
writeup at agentspecs/cross-client-state-access-2026-05-14.md notes this
as the largest single available win for the synthetic bench.

Wiring:
- CodeCache.GetCodeSizeByEthHash / PutCodeSizeByEthHash — direct accessors.
- PutWithEthHash now populates the size layer alongside L2b, so every
  bytes-load creates a future fast-path entry "for free".
- StateCache wrappers GetCodeSizeByHash / PutCodeSizeByHash.
- SharedDomains.GetCodeSize(tx, addr) — the SD-transparent fast path:
  resolve codeHash via the AccountsDomain cache chain, probe the size
  cache, then L2b, then file-read+populate. Returns (0, false, nil) for
  EOAs and no-code accounts without paying any file read.
- temporalGetter.GetCodeSize so callers reach it via the existing getter.
- ReaderV3.ReadAccountCodeSize type-asserts on a codeSizeGetter interface
  and routes through the fast path when the underlying getter supports it;
  falls back to GetLatest+len otherwise. No kv.TemporalGetter interface
  change.

Limitation: capacity is no-op-when-full, not LRU. A separate surgical
commit will swap to real LRU eviction; mirrors the addrToHash fix queued
from the same cross-client writeup.

Tests: 3 new (PopulatedAlongsideBytes, DirectPutAndGet, EmptyHashOrNegativeIsNoOp).
All existing CodeCache tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…e.StateCache

The BlockReadAheader has always prefetched BAL-listed (and access-list)
addresses' account/code/storage via a fresh ReaderV3 on a separate RoTx.
Its prefetches warmed OS page cache + RoTx cursors — disconnected from
the process-global cache.StateCache that SharedDomains.GetLatest probes
on the EVM hot path. The two layers were two separate caches; nothing
the prefetcher loaded ever reached the EVM's lookup path.

Reth's structural advantage on EXTCODESIZE-loop benches is that its
prewarm writes to the same hashmap the EVM reads from
(crates/engine/execution-cache/src/cached_state.rs:663). When EVM enters,
every BAL-listed addr's first read is a 20 ns cache probe — no file
accessor stack, no decompression CPU. PR #21128 swapped this from
mini-moka to a lock-free fixed-cache for a measured +10.8 % mgas/s.

This commit closes the equivalent gap on Erigon: a thin cache-populating
TemporalGetter wrapper writes successful reads through to cache.StateCache
as a side effect. ReaderV3 is unchanged; the wrapper sits in front. When
the prefetcher already has the codeHash from a preceding account read,
the next CodeDomain read routes through StateCache.PutCodeWithHash so
the L2b (ethHash → bytes) + size-cache layers fill alongside the bare
addr-keyed L1.

Wiring:
- BlockReadAheader.SetStateCache(*cache.StateCache) setter.
- ExecModule construction calls readAheader.SetStateCache(domainCache),
  so the same StateCache the FCU/canonical path wires onto SD is the one
  the prefetcher warms.
- cachePopulatingGetter wraps the worker's ttx; both BAL-warming and
  tx-warming paths gain the same treatment.

Fgprof on the EXTCODESIZE-EXISTING_CONTRACT-30M bench had shown 95 % of
EVM wall-clock in seg.Getter.nextPos (Huffman decompression of code
values). With this commit, every BAL-listed addr's lookup should hit
the cache and skip the file accessor stack entirely — eliminating the
dominant cost.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ash LRU

Two surgical commits bundled (both touch the code-read hot path):

1. IntraBlockState.GetCodeSize now loads the full bytes via
   stateReader.ReadAccountCode on first touch and populates
   stateObject.code, so subsequent same-addr EXTCODESIZE /
   EXTCODEHASH / CALL within the tx are in-struct slice-len calls
   (~50 ns), not full reader round-trips. Mirrors geth's pattern
   at core/state/state_object.go ~Code() — pay one read per addr
   per tx, free for the rest.

2. CodeCache.addrToHash switched from a no-op-when-full
   maphash.Map[versionedAddressID] to an LRU
   lru.Cache[[20]byte, versionedAddressID] (hashicorp/golang-lru/v2,
   already imported elsewhere). Cap derived from the existing byte
   budget at ~28 bytes/entry (~580 k entries for the 16 MB default).
   Fresh-address workloads (mainnet thousands of new addrs per
   block) now warm up the addr layer over time instead of silently
   dropping new entries forever; matches geth's lru.Cache at
   core/state/database_code.go.

   The hashToCode layer is unchanged (content-addressed bytes,
   immutable, byte-capped with new-entry no-op when full — the same
   semantic as before since code bytes by codeHash never change).

Bench on the EXTCODESIZE-EXISTING_CONTRACT-30M family: 62.34 mgas/s
(was 61.50). The marginal gain is small on this bench because BAL
prefetch already populates the cache layers; neither lever fires
heavily. The expected wins are on non-BAL workloads where
EXTCODESIZE-loop patterns repeat within a tx (#1) and
fresh-address-churn mainnet blocks fill the addr layer (#2).

Updated TestCodeCache_AddrCapacityLimit to assert LRU eviction
(was asserting no-op-when-full); the prior behaviour was the bug.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Nethermind-style addr → 32-byte codeHash LRU sitting above
SharedDomains.codeHashForAddr. When the EVM-known codeHash for an
address has already been resolved once, subsequent lookups skip the
entire AccountsDomain chain (sd.mem → sd.parent.mem → sd.stateCache →
tx.GetLatest) and the account-RLP decode.

Wiring:
- CodeCache adds addrToEthHash *lru.Cache[[20]byte, [32]byte] sized
  to the existing addrCapacityB budget; methods GetAddrCodeHash /
  PutAddrCodeHash / DeleteAddrCodeHash.
- StateCache wrappers route to the CodeCache instance.
- SD.codeHashForAddr probes the LRU first; on miss falls through to
  the existing chain and populates on the way out (including the
  zero-hash sentinel for missing-or-EOA accounts — repeat lookups
  return immediately).
- Invalidation: SD.DomainPut for AccountsDomain drops the entry
  (CREATE / CREATE2-replace path); SD.DomainDel for AccountsDomain
  also drops the entry (SELFDESTRUCT); StateCache.RevertWithDiffset
  drops on unwind.

Helps non-BAL workloads where codeHashForAddr is currently the cold
account-domain probe. On the EXISTING_CONTRACT bench (BAL prefetch
already populates everything), this is within noise; the lever is for
mainnet workloads where many addresses miss the BAL-prefetch window
but the cache is warm from prior lookups.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The cache-populating wrapper on the read-ahead worker's TemporalTx
previously gated cache writes on `len(v) > 0`. That dropped negative
results — i.e. missing accounts, empty storage slots, no-code probes —
on the floor. Repeated probes of the same missing address re-paid the
file accessor stack walk every time, instead of hitting a cached
negative entry.

Mirrors the revm pattern that drives reth's 1700-3400 mgas/s on
account_access NON_EXISTING / EXISTING_EOA variants: revm represents
a missing address as a real CacheAccount{ account: None, status:
LoadedNotExisting } and reth's ExecutionCache.account_cache uses
FixedCache<Address, Option<Account>> where None is a first-class
cacheable value. Bottom of the reth path is: BAL prewarm calls
basic_account once → returns None → cache hit forever for that addr.

The cycle-2 sweep on account_access[EXTCODESIZE/NON_EXISTING/30M]
showed 3.65 → 494 mgas/s without this fix; with the fix the same
bench reports 508 mgas/s (within run-to-run noise but trending right).
Most of the win was already captured by the readAhead-populates-
cache.StateCache wiring (commit cbe9044) and the balcache port
(d41e2e8) — those raised the cache hit rate on populated entries
enough that the EVM rarely fell through to the file accessor on
this bench. The fix is mechanically correct regardless and should
matter more on workloads with mixed populated / negative probes
across blocks.

See agentspecs/reth-missing-eoa-fastpath-2026-05-15.md for the
detailed mechanism analysis and the three concrete copy-able
patterns from reth.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…unters

GenericCache.Put has no eviction policy. When the byte budget is reached,
new keys are silently dropped until Clear/ClearWithHash/ValidateAndPrepare-
mismatch resets the cache. On a long-running node this manifests as a
monotonic miss-rate climb that's hard to attribute without instrumentation.

Add two counters next to hits/misses:
  inserts - new keys accepted
  dropped - new keys rejected at the budget check (the existing branch
            at the new-key cap; not a behaviour change)

PrintStatsAndReset logs both. Sets up the diagnostic baseline before the
eviction-policy swap in the follow-up commits on this branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Replaces the maphash.Map[T] backing store in GenericCache with
freelru.ShardedLRU[uint64, entry[T]] (same lib as db/state/cache.go;
already in go.mod). Adds a Mode constructor flag:

  - ModeEvictLRU (default): per-shard LRU evicts the oldest entry on
    insert when its slot cap is reached. OnEvict drops bytes from
    currentSize.
  - ModeNoOp: preserves the historical fill-and-freeze behaviour
    (silently drop new keys at the byte cap; counted via dropped).
    Kept as the diagnostic baseline so the regression bench can
    compare A/B.

Per-shard eviction is a known trade-off of freelru.ShardedLRU —
RemoveOldest is shard-local, not globally LRU. Matches the trade-off
db/state/cache.go / execution/cache/code_cache.go /
execution/balcache/balcache.go already accept. LFU (W-TinyLFU, the
policy reth uses) is scan-resistant by design and would slot in
behind the same Mode wrapper as a follow-up; the seam is documented
at policy.go.

Key shape: pre-hash via common/maphash.Hash (Go's randomized stdlib
hasher, already used by the previous maphash.Map) into uint64; entry
stores the full key for collision check. Same pattern as
db/state/cache.go.

Byte-budget translation: per-domain avg-entry constants in
state_cache.go (avgAccountEntryBytes / avgStorageEntryBytes /
avgCommitmentEntryBytes) — account / storage are near-fixed sizes so
the translation is reliable. capacityBytes becomes a sizing hint
plus telemetry (SizeBytes / PrintStatsAndReset). Code domain is
unchanged; CodeCache wraps its own LRUs.

Adds metrics: inserts, evictions, dropped — all exposed in
PrintStatsAndReset alongside the existing hits / misses / hit_rate.
Mode is also logged.

Touches one external call site: execution/vm/contract.go's
jumpDestCache now constructs with ModeEvictLRU.

Tests: TestDomainCache_PutCapacityLimit renamed to ..._NoOpMode and
asserts the fill-and-freeze contract under explicit ModeNoOp. New
TestDomainCache_PutEvictsWhenFull_EvictMode asserts eviction under
ModeEvictLRU using a small entry-count cap (the byte→entry
translation is approximate; the test uses the entry-count knob via
the in-package newGenericCacheEntries constructor to make the
assertion deterministic).

Pre-existing lint issues on mh/sd-code-cache (intra_block_state.go
nilness, preload_parallel.go prealloc) are surfaced by lint
non-determinism but are out of this commit's scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Single env knob read once at NewStateCache. Default ModeEvictLRU,
recognised override "noop" (for the regression-bench baseline so
ModeEvictLRU and ModeNoOp can be compared on the same binary).
Unrecognised values fall back to evict with a warn log.

ModeNoOp engagement is logged at info level because the
fill-and-freeze behaviour is a deliberate diagnostic state, not a
production setting.

Pattern matches db/state/cache.go's D_LRU_ENABLED / D_LRU knobs
(dbg.EnvString from common/dbg).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The previous comment asserted "reth uses W-TinyLFU for state caches" —
that is wrong on the execution hot path. Reth's cross-block state cache
is `fixed-cache` (PR #21128, v1.11.0): a lock-free direct-mapped /
set-associative array with collision-evict semantics. No LRU list, no
LFU sketch. Their published wins (~25% newPayload p50 / +33% gas/s) came
from *removing* LRU/LFU bookkeeping, not adding LFU.

Where reth uses real LRU/LFU it's deliberate and not the execution cache
(schnellru::LruMap for networking; moka in precompile_cache.rs explicitly
configured with eviction_policy(EvictionPolicy::lru())).

The docstring now reflects two follow-up policies both real:
- ModeEvictFixedCache (reth's actual choice, more interesting structural
  option than LFU)
- ModeEvictLFU (W-TinyLFU; helps mainnet steady-state, not the cycle-2
  bloat fixtures which are pure cold scans)

Decision criterion (per agentspecs/lfu-vs-lru-state-cache-decision-2026-05-15.md):
ship ModeEvictLFU only if a 24h mainnet replay shows current sharded-LRU
hit-rate < 90 % on Account/Storage. Otter is the only credible Go
W-TinyLFU library; ristretto has documented correctness bugs and is
disqualified for an EL hot path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Investigation knob, NOT a permanent default. Account / Storage / Code
each capped at 100 MB so the bench measures layer contributions instead
of being dominated by preallocated cache memory pressure (1 GB / 1 GB /
512 MB defaults push sys past the GC/page-cache pressure band on this
hardware/workload mix).

Permanent defaults stay at 1 GB / 1 GB / 512 MB; this commit will be
reverted or dynamically gated by relative-to-available sizing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…statecache-lru-pr

…govet)

stateObject and s are both verified non-nil earlier in their respective
scopes; the secondary checks at lines 749 and 783 are redundant. govet
nilness check fails on these.

Add a request-scoped read accumulator to SharedDomains
(StartRequestMetrics(source) / flush at Close) so a single-goroutine RPC handler
that reads through the plain AsGetter is metered without a shared accumulator or
a per-getter flush. getLatestMetered folds nil-metrics reads into it; this
short-circuits for exec workers (which pass their own per-worker instance), so
there is no cross-goroutine access to the request accumulator.

Wire eth_simulation's SimulateV1 to tag its reads as SourceRPC. Engine block
execution is already metered as SourceExec (it runs through the exec workers);
SourceEngine and the per-read-getter paths (exec_module CacheView, vm/runtime,
which build a getter per read) are left for a follow-up that needs a view-level
accumulator.

Also make Collector.Snapshot drain the buffered samples first so a snapshot
reflects everything sent so far, and add a -race collector test covering
concurrent Send + Snapshot + Close-drain.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…roducers

The exec hot path must never block on metrics and must never lose counts. A
buffered channel alone satisfies neither at the boundary: a full buffer blocks a
plain send, and a non-blocking send drops. Resolve both with retain-on-full.

- Collector.TrySend is non-blocking and returns whether the sample was queued.
  Exec workers keep a retained accumulator (collectorAcc): each task folds its
  reads in and TrySends; on a full buffer the send is skipped and the worker
  keeps adding to the same accumulator, retrying next task. A single blocking
  flush at worker exit drains the remainder (off the hot path, lossless). So
  execution never waits on metrics and no count is dropped.
- Collector.Send is the blocking variant for low-frequency boundary producers
  (commitment fold, warmup teardown, an RPC request closing) where a rare brief
  wait is fine and losing the sample is not.
- SharedDomains.LogMergeMetrics folds a task into the per-batch sd.metrics log
  aggregate only; the exec path uses it each task and feeds the collector
  separately via the retained accumulator, so the two sinks (which reset on
  different conditions) never double-count.
- Dropped the drop counter and its gauge — nothing is dropped now.

Validated: build, make lint (0 issues), go test -race ./db/state/kvmetrics
(incl. a test proving TrySend never blocks on a full buffer), and hive cancun
with KV_READ_METRICS=true at the pinned ref = 226/0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Ripples the statecache-lru main merge up. Resolved 4 conflicts by combining
the metrics-collector additions with the rippled cache/commitment changes:

- domain_shared.go: keep the kvmetrics MetricsCollectorProvider lookup +
  statecache-lru's new TrieConfig commitment-context ctor (cfg, branchCache).
- aggregator.go: keep the kvmetrics collector init + statecache-lru's
  oldestVisible; the MeteredGetLatestWithTxN/getLatestWithTxN methods now take
  *kvmetrics.DomainMetrics (the metrics relocation changeset -> kvmetrics).
- commitment_context.go: Metrics() returns *kvmetrics.DomainMetrics.
- eth_simulation.go: keep StartRequestMetrics(SourceRPC); the defer toggle is
  now sharedDomains.SetDeferCommitmentUpdates(false) (renamed in the refactor).

Validated: go build ./...; commitment + kvmetrics + execmodule reorg tests;
make lint clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…" nickname

"ethHash" collided with Ethash (the proof-of-work algorithm) and obscured that
it is the keccak *code* hash. Rename the codeHash-keyed code-cache layer and its
API so the name says what it is:

  ethHashToCode        -> codeHashToCode
  GetByEthHash         -> GetByCodeHash
  PutWithEthHash       -> PutWithCodeHash
  codeSizeByEthHash    -> codeSizeByCodeHash
  GetCodeSizeByEthHash -> GetCodeSizeByCodeHash
  ethHashCodeSize/Hits/Misses -> codeHash...
  local codeEthHash    -> codeHash

The "L2b" tier nickname in comments/labels becomes codeHashToCode (it is a
content-addressed codeHash→code map, not a cache depth-level). Values and
behaviour are unchanged — mechanical rename. Test file renamed to
code_cache_codehash_test.go.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…revent poisoning

The content-addressed code cache (codeHash->code) was populated using a
separately-read account codeHash as the key. Under parallel/speculative exec
that hash can be skewed or cross-account, so a (codeHash, code) pair that
doesn't satisfy keccak(code)==codeHash could enter the shared map and corrupt
every account sharing that codeHash — surfacing as a wrong-forwarder gas
divergence, and (once the bad bytes are persisted) codeHash-no-code /
"sender not an eoa" on cold re-read.

Key every content-cache entry by the code's OWN hash, keccak(code), at the
single SharedDomains getter populate path and the flush callback, and bring
the read-ahead prefetcher onto the same model (dropping the skewable codeHash
hint). Speculative code stays in the version map and never enters the global
cache; the cache is populated only on a real read through the shared domain,
so a skewed account read can no longer produce a mismatched entry.

Validated by a fresh mainnet resync across the former-corruption range
(25.27M-25.29M): the previously-deterministic gas divergence / sender-not-an-eoa
no longer reproduces, forward or on cold restart re-exec.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The earlier recovery only re-emitted code found in THIS tx's versionMap
(rr.Version().TxIndex == txIndex). On the real failure path that guard
misses: a re-executing 7702 delegation whose code equals the already-
committed designator makes IBS.SetCode short-circuit (bytes.Equal), so
the validated incarnation writes no CodePath and the prior incarnation's
versionMap entry is invalidated on re-exec — the versionMap holds nothing
for this tx. The fill-missing loop still fills CodeHashPath from committed
state, so the account persists a codeHash with no code; a later 7702
sender then reads empty code and is wrongly rejected "sender not an eoa"
(observed re-executing mainnet blocks 25277235 / 25279079 / 25280960).

Recover the designator from the versionMap, else fall back to the
post-state via stateReader.ReadAccountCode (mirroring how CodeHashPath is
recovered). Gate emission on types.ParseDelegation so only 7702
designators are re-emitted — never ordinary unchanged contract code for a
touched contract (no write amplification, no callee-code misattribution).

This prevents the drop during forward execution. It cannot repair state
already collated into immutable snapshots with codeHash-but-no-code; that
needs a snapshot unwind (separate, in development).

Adds TestNormalizeWriteSet_CodePathRecoveredFromStateReader for the
short-circuit/stateReader path; the existing versionMap-path test stays.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…perf-statecache-lru-pr

Reconcile #21386 onto the cleaned commitment-cache model from #21380.

Resolution:
- branch_cache.go (+test), temporal_mem_batch.go, kv_interface.go -> take
  #21380's cleaned model: reduced BranchCache API, txN-watermark UnwindTo,
  FlushOption pattern, flush-callback-after-MDBX-write.
- preload*.go, trunk_pin_test.go -> deleted (trunk-pin extracted to
  mh/branch-cache-trunk-pin).
- domain_shared.go -> combine: keep #21386's StateCache refresh, keccak
  code-cache fix, codeHash->code read bypass, per-worker kvmetrics (wm) and
  the collector/reqMetrics fields; adopt #21380's cleaned FlushOption
  multi-domain callback (cb-after-MDBX-write), MeteredGetterWithTxN watermark
  + txN=0 skip; drop the extracted adaptive-pin controller + PublishMetrics.

Notable behavioural deltas (flagged for review):
- BranchCache unwind: #21386's epoch/unwindFloor model -> #21380's
  txN-watermark UnwindTo (same effect: evict entries above the unwind point).
- StateCache flush entries now stamped with sd.txNum (batch high-water) as the
  unwind watermark: the cleaned WithFlushCallback exposes step, not per-key
  txN; sd.txNum is a safe conservative upper bound.
- temporal_mem_batch.go DomainMetrics refs retargeted changeset -> kvmetrics.

Carries: keccak codeHash fix, #21706 CodePath recovery, stateCache.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

A contract's code value is invariant for a given hash, but its EXISTENCE is
not: code deployed on a fork that is later unwound must no longer be
discoverable — including by codeHash — so it can't be served as live state on
the surviving fork. The code cache therefore stops treating its content layers
as immutable and honors the same (txNum, epoch) model as the account/storage/
branch caches (#21752).

- Every layer (addr→code, addr→codeHash, codeHash→code, maphash→code, size)
  carries a (txNum, epoch) stamp. Get drops a superseded-epoch entry whose txNum
  is at/above the unwind floor lazily on read (decrementing the byte counters).
- Unwind bumps the epoch and lowers the floor — O(1), no scan — replacing the
  wholesale addr-layer Purge (which also nuked the whole warm working set every
  unwind). Re-deploying the same code on the live fork revives a stranded entry.
- Thread the value's write txNum (per-key on flush, step-derived on read, a
  conservative sd.txNum upper bound on derived populates) through
  PutWithCodeHash / PutAddrCodeHash / PutCodeSizeByCodeHash and the StateCache
  wrappers and call sites.
- Clear now hard-resets every layer (was: kept content as immutable).

Tradeoff: unwinding one deployment can drop code shared with a still-live one,
which is then re-fetched (a multiplicity cost) — accepted to keep stale code out
of the cache. Tests cover undiscoverable-after-unwind across all layers,
below-floor survival, and re-deploy revival.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Byte-match #21380's WithFlushCallback txNum doc so re-syncing this stacked
branch onto #21380 attributes the kv plumbing cleanly to #21380 (#21752).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…statecache-lru-pr

# Conflicts:
#	db/state/execctx/domain_shared.go