feat(engine): expose engine caches to SDK consumers

[yongkangc]

Closes RETH-505

Problem
Engine-tree caches (execution cache, sparse trie, precompile cache) are created inside BasicEngineValidator and PayloadProcessor. The launcher has no handle to them, so payload builders can't reuse engine caches like the precompile cache.

Solution
New EngineSharedCaches<Evm> struct with pub fields. The launcher creates it and passes it through build_tree_validator.

Before

Payload builders have no access to engine caches. To share them, an SDK consumer would have to:

1. Skip BasicEngineValidator entirely and reimplement the validator from scratch
2. Create the caches externally and wire them through a custom EngineValidatorBuilder impl
3. Manually thread those caches to their payload builder

graph TD
    L[EngineNodeLauncher] -->|build_tree_validator| BEV[BasicEngineValidator]
    BEV -->|"new(precompile_cache_map)"| PP[PayloadProcessor]
    L -->|no cache handle| PB[PayloadBuilder]

    BEV -.->|creates internally| PCM1["PrecompileCacheMap::default()"]
    PP -.->|creates internally| EC["PayloadExecutionCache::default()"]
    PP -.->|creates internally| SST["SharedPreservedSparseTrie::default()"]

    style PCM1 fill:#f96,stroke:#333
    style EC fill:#f96,stroke:#333
    style SST fill:#f96,stroke:#333
    style PB fill:#eee,stroke:#999,stroke-dasharray: 5 5

Loading

After

build_tree_validator now takes EngineSharedCaches as a parameter. SDK consumers can clone whichever cache handle they need before forwarding the bundle:

1. Clone whichever cache handle they need (e.g., shared_caches.precompile_cache_map.clone())
2. Pass it to their payload builder
3. Forward the bundle to BasicEngineValidator as normal

graph TD
    L[EngineNodeLauncher] -->|creates| ESC["EngineSharedCaches::default()"]
    L -->|"build_tree_validator(shared_caches)"| BEV[BasicEngineValidator]
    BEV -->|"new(shared_caches)"| PP[PayloadProcessor]
    ESC -.->|".precompile_cache_map.clone()"| PB[PayloadBuilder]

    style ESC fill:#6f9,stroke:#333
    style PB fill:#69f,stroke:#333

Loading

Expected Impact

• Zero runtime change
• Enables cache sharing with payload builders
• Breaking: build_tree_validator signature now includes EngineSharedCaches
• #[non_exhaustive] on EngineSharedCaches protects against future field additions

[github-actions]

✅ Changelog found on PR.

Edit changelog

[yongkangc]

derek bench

[yongkangc]

@codex review

[yongkangc]

derek bench

[decofe]

cc @yongkangc

✅ Benchmark complete! View job

Benchmark Results

Metric	main	yk/reth-505-engine-caches-facade-20260316-055813	Change
Mean	24.64ms	24.69ms	+0.19% ⚪ (±0.29%)
StdDev	15.87ms	15.90ms
P50	21.45ms	21.48ms	+0.13% ⚪ (±1.00%)
P90	35.85ms	35.84ms	-0.03% ⚪ (±1.92%)
P99	98.70ms	98.10ms	-0.60% ⚪ (±1.69%)
Mgas/s	1301.55	1299.95	-0.12% ⚪ (±0.32%)
Wall Clock	25.48s	25.52s	+0.18% ⚪ (±0.34%)

500 blocks

Wait Time Breakdown

Persistence Wait

Metric	main	yk/reth-505-engine-caches-facade-20260316-055813
Mean	357.12ms	356.20ms
P50	340.59ms	341.55ms
P95	551.11ms	537.16ms

Trie Cache Update Wait

Metric	main	yk/reth-505-engine-caches-facade-20260316-055813
Mean	5.31ms	5.18ms
P50	5.49ms	5.38ms
P95	7.20ms	7.14ms

Execution Cache Update Wait

Metric	main	yk/reth-505-engine-caches-facade-20260316-055813
Mean	0.00ms	0.00ms
P50	0.00ms	0.00ms
P95	0.00ms	0.00ms

Grafana Dashboard

Charts

Latency, Throughput & Diff

Wait Time Breakdown

Gas vs Latency

Grafana Dashboard

View real-time metrics

[shekhirin]

Superseded by #23242