Skip to content

refactor(provider): use overlay builders in historical state paths#23667

Merged
klkvr merged 21 commits into
mainfrom
mediocregopher/historical-state-provider-changeset-cache
Apr 23, 2026
Merged

refactor(provider): use overlay builders in historical state paths#23667
klkvr merged 21 commits into
mainfrom
mediocregopher/historical-state-provider-changeset-cache

Conversation

@mediocregopher
Copy link
Copy Markdown
Member

@mediocregopher mediocregopher commented Apr 21, 2026

Plumbs ChangesetCache through historical state provider construction and extracts a cloneable OverlayBuilder so overlay configuration can be shared separately from the cached OverlayStateProviderFactory.

Historical state-root, storage-root, and proof paths now build their overlays through that shared builder while preserving the existing historical block semantics, and the engine/tree and parallel trie callers are updated to rebuild overlay factories from the provider factory plus builder when they need extended overlays.

Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db016-ea05-74e4-a085-27f4173a1f9f
Co-authored-by: Amp <amp@ampcode.com>
@mediocregopher mediocregopher added A-engine Related to the engine implementation A-db Related to the database A-trie Related to Merkle Patricia Trie implementation labels Apr 21, 2026
@mediocregopher mediocregopher self-assigned this Apr 21, 2026
@github-project-automation github-project-automation Bot moved this to Backlog in Reth Tracker Apr 21, 2026
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db037-4b3b-77c1-9832-42d24c58560e
Co-authored-by: Amp <amp@ampcode.com>
@mediocregopher mediocregopher added C-bug An unexpected or incorrect behavior C-testing labels Apr 21, 2026
mediocregopher and others added 2 commits April 21, 2026 14:00
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db037-4b3b-77c1-9832-42d24c58560e
Co-authored-by: Amp <amp@ampcode.com>
Restore the historical provider behavior to match origin/main while keeping the ChangesetCache constructor plumbing and shared reorg-validator cache wiring.

Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db05b-f81c-754e-9229-81b57d6d32f5
Co-authored-by: Amp <amp@ampcode.com>
ctx.components().evm_config().clone(),
|| async {
// Create a separate cache for reorg validator (not shared with main engine)
let reorg_cache = ChangesetCache::new();
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tangential change, but it's not necessary to have a separate ChangesetCache for debug reorgs, the cache is keyed by block hash anyway.

@mediocregopher mediocregopher removed C-bug An unexpected or incorrect behavior C-testing labels Apr 21, 2026
@mediocregopher mediocregopher marked this pull request as ready for review April 21, 2026 14:33
@mediocregopher mediocregopher changed the title fix(provider): require changeset cache for historical state providers refactor(provider): require changeset cache for historical state providers Apr 21, 2026
@mediocregopher mediocregopher marked this pull request as draft April 21, 2026 14:34
mediocregopher and others added 6 commits April 21, 2026 15:19
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db074-fac6-76d2-8950-3e84b3c895a4
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db074-fac6-76d2-8950-3e84b3c895a4
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db0ad-77b5-76ba-8b0b-6683a56f63c5
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db0ad-77b5-76ba-8b0b-6683a56f63c5
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db0ad-77b5-76ba-8b0b-6683a56f63c5
Co-authored-by: Amp <amp@ampcode.com>
Co-Authored-By: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
@mediocregopher mediocregopher changed the title refactor(provider): require changeset cache for historical state providers refactor(provider): use overlay builders in historical state paths Apr 21, 2026
Co-Authored-By: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Co-Authored-By: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Comment thread crates/engine/tree/src/tree/payload_validator.rs
Comment thread crates/storage/provider/src/providers/state/overlay.rs
Comment thread crates/storage/provider/src/providers/state/historical.rs Outdated
Comment thread crates/storage/provider/src/providers/state/historical.rs Outdated
@github-project-automation github-project-automation Bot moved this from Backlog to In Progress in Reth Tracker Apr 21, 2026
mediocregopher and others added 6 commits April 22, 2026 11:31
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db4f1-b5cb-75ee-b759-0c6badfe0ff6
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db4f1-b5cb-75ee-b759-0c6badfe0ff6
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db4f1-b5cb-75ee-b759-0c6badfe0ff6
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db4f1-b5cb-75ee-b759-0c6badfe0ff6
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db4f1-b5cb-75ee-b759-0c6badfe0ff6
Co-authored-by: Amp <amp@ampcode.com>
@mediocregopher
Copy link
Copy Markdown
Member Author

derek bench

@mediocregopher
Copy link
Copy Markdown
Member Author

derek bench big-blocks

@decofe
Copy link
Copy Markdown
Member

decofe commented Apr 22, 2026

cc @mediocregopher

✅ Benchmark complete! View job

Benchmark Results

Metric main mediocregopher/historical-state-provider-changeset-cache Change
Mean 28.85ms 28.50ms -1.23% ⚪ (±1.75%)
StdDev 14.32ms 13.51ms
P50 26.32ms 26.29ms -0.14% ⚪ (±2.05%)
P90 46.00ms 45.31ms -1.49% ⚪ (±2.81%)
P99 84.01ms 82.44ms -1.87% ⚪ (±15.69%)
Mgas/s 1082.90 1084.74 +0.17% ⚪ (±0.99%)
Wall Clock 29.76s 29.38s -1.29% ⚪ (±1.72%)
Persist Wait 25.00ms 26.08ms +4.34% ⚪ (±21.44%)

500 blocks, 200 warmup

Wait Time Breakdown

Persistence Wait

Metric main mediocregopher/historical-state-provider-changeset-cache
Mean 25.00ms 26.08ms
P50 0.02ms 0.02ms
P95 229.76ms 230.06ms

Trie Cache Update Wait

Metric main mediocregopher/historical-state-provider-changeset-cache
Mean 0.48ms 0.56ms
P50 0.00ms 0.00ms
P95 2.31ms 2.65ms

Execution Cache Update Wait

Metric main mediocregopher/historical-state-provider-changeset-cache
Mean 0.00ms 0.00ms
P50 0.00ms 0.00ms
P95 0.00ms 0.00ms

Grafana Dashboard

Charts

Latency, Throughput & Diff

Latency, Throughput & Diff

Wait Time Breakdown

Wait Time Breakdown

Gas vs Latency

Gas vs Latency

Grafana Dashboard

View real-time metrics

@decofe
Copy link
Copy Markdown
Member

decofe commented Apr 22, 2026

cc @mediocregopher

✅ Benchmark complete! View job

Benchmark Results

Metric main mediocregopher/historical-state-provider-changeset-cache Change
Mean 783.70ms 784.19ms +0.06% ⚪ (±1.30%)
StdDev 185.73ms 186.09ms
P50 736.20ms 738.11ms +0.26% ⚪ (±1.41%)
P90 1001.13ms 994.02ms -0.71% ⚪ (±2.72%)
P99 1459.52ms 1446.27ms -0.91% ⚪ (±18.53%)
Mgas/s 1352.38 1351.23 -0.08% ⚪ (±1.01%)
Wall Clock 816.56s 814.64s -0.24% ⚪ (±1.67%)
Persist Wait 1.04ms 3.09ms +198.20% ❌ (±130.49%)

500 big blocks, 20 warmup

Wait Time Breakdown

Persistence Wait

Metric main mediocregopher/historical-state-provider-changeset-cache
Mean 1.04ms 3.09ms
P50 0.06ms 0.06ms
P95 0.09ms 0.09ms

Trie Cache Update Wait

Metric main mediocregopher/historical-state-provider-changeset-cache
Mean 0.30ms 0.45ms
P50 0.00ms 0.00ms
P95 0.00ms 0.00ms

Execution Cache Update Wait

Metric main mediocregopher/historical-state-provider-changeset-cache
Mean 0.00ms 0.00ms
P50 0.00ms 0.00ms
P95 0.00ms 0.00ms

Grafana Dashboard

Charts

Latency, Throughput & Diff

Latency, Throughput & Diff

Wait Time Breakdown

Wait Time Breakdown

Gas vs Latency

Gas vs Latency

Grafana Dashboard

View real-time metrics

Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db5d3-fb9b-7309-b8e9-dfc2ca6290a7
Co-authored-by: Amp <amp@ampcode.com>
@mediocregopher mediocregopher requested a review from klkvr April 23, 2026 10:36
@mediocregopher mediocregopher marked this pull request as ready for review April 23, 2026 10:36
mediocregopher and others added 2 commits April 23, 2026 12:26
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db9e5-51dc-763e-b1ec-4e09fbc9e8e8
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Brian Picciano <933154+mediocregopher@users.noreply.github.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019db9e5-51dc-763e-b1ec-4e09fbc9e8e8
Co-authored-by: Amp <amp@ampcode.com>
@klkvr klkvr added this pull request to the merge queue Apr 23, 2026
Merged via the queue into main with commit 6377a95 Apr 23, 2026
34 checks passed
@klkvr klkvr deleted the mediocregopher/historical-state-provider-changeset-cache branch April 23, 2026 19:16
@github-project-automation github-project-automation Bot moved this from In Progress to Done in Reth Tracker Apr 23, 2026
umeeSthein pushed a commit to umeeSthein/tempo that referenced this pull request Apr 30, 2026
Automated nightly update of reth dependencies from `paradigmxyz/reth`
main branch.

## Upstream reth changes


[`7839f3d...73ec2c9`](paradigmxyz/reth@7839f3d...73ec2c9)

🔗 Amp thread:
https://ampcode.com/threads/T-019dd89b-f659-75eb-a3f2-3e769d63297f
**Engine**
- Spawn BAL hashed state before storage prefetch
([#23761](paradigmxyz/reth#23761)) and disable
BAL parallel execution by default
([#23764](paradigmxyz/reth#23764))
- Add CLI flag to disable BAL storage prefetch
([#23770](paradigmxyz/reth#23770))
- Log transient invalid header cache skips
([#23711](paradigmxyz/reth#23711))
- Add `DecodedBal` in `ExecutionEnv`
([#23675](paradigmxyz/reth#23675))

**RPC**
- Clean up eth state cache reorg entries
([#23683](paradigmxyz/reth#23683))
- Pass block timestamp to txn
([#23700](paradigmxyz/reth#23700))
- Include block numbers in `BlockRangeExceedsHead` error
([#23720](paradigmxyz/reth#23720))

**Network / P2P**
- Add Basic in-memory BAL store and BAL request to block access list
requests ([#23682](paradigmxyz/reth#23682),
[#23710](paradigmxyz/reth#23710))
- Enforce BAL response soft limit and apply count cap to handler
([#23725](paradigmxyz/reth#23725),
[#23754](paradigmxyz/reth#23754))
- Avoid RLP-decoding `NewBlock` payloads
([#23712](paradigmxyz/reth#23712)) and bound
memory footprint of p2p messages
([#23718](paradigmxyz/reth#23718))
- Memory-bound channel between network and tx manager
([#23802](paradigmxyz/reth#23802))
- Track unknown tx types in announcement metrics
([#23688](paradigmxyz/reth#23688))
- Retain active session buffer capacity
([#23702](paradigmxyz/reth#23702)) and respect
peer requirements for fetch followups
([#23706](paradigmxyz/reth#23706))
- Support binding discv5 and discv4 to the same port
([#23613](paradigmxyz/reth#23613)) and use Weak
reference in discv5 kbuckets bg task to release port on shutdown
([#23282](paradigmxyz/reth#23282))

**Trie**
- Skip DB seek on exact overlay hits
([#23559](paradigmxyz/reth#23559))
- Account for heap-allocated blinded hashes in `SparseNode::memory_size`
([#23726](paradigmxyz/reth#23726))

**DB / Storage**
- `reth db migrate-v2` for pruned nodes
([#23716](paradigmxyz/reth#23716))
- Pass `ExecutedBlocks` to `OverlayBuilder`, reduce reverts queried
([#23657](paradigmxyz/reth#23657))
- Add empty request check to storage values
([#23714](paradigmxyz/reth#23714))
- Derive `Eq` for `IntegerList`
([#23709](paradigmxyz/reth#23709)) and reorder
unix deps after strum
([#23697](paradigmxyz/reth#23697))

**Provider / EVM**
- Use overlay builders in historical state paths
([#23667](paradigmxyz/reth#23667))
- Return gas output from block builder
([#23744](paradigmxyz/reth#23744))
- Expose executor transaction result type
([#23759](paradigmxyz/reth#23759))

**Perf**
- Configurable rocksdb block cache size and re-use of mdbx provider in
re-execute ([#23701](paradigmxyz/reth#23701))
- Enable revm `p256-aws-lc-rs` feature
([#23721](paradigmxyz/reth#23721))
- Add platform-specific RUSTFLAGS to Dockerfile
([#23738](paradigmxyz/reth#23738))

**Bench**
- Add reorg mode to `new-payload-fcu`
([#23666](paradigmxyz/reth#23666))
- Enable `keccak-cache-global` in `reth-bb`
([#23723](paradigmxyz/reth#23723)) and fix
multi-executor support
([#23763](paradigmxyz/reth#23763))
- Dedupe merged BAL storage reads
([#23758](paradigmxyz/reth#23758))

**Re-execute**
- Verify reverts against changesets
([#23717](paradigmxyz/reth#23717))

**Payload**
- Track Amsterdam block gas in builders
([#23743](paradigmxyz/reth#23743))

**CLI**
- Use `TxTy`/`ReceiptTy` for static-file db get
([#23692](paradigmxyz/reth#23692)) and node
types in execution stage dump
([#23705](paradigmxyz/reth#23705))
- Preserve `trusted_nodes_only` from config when `--trusted-only` is
unset ([#23703](paradigmxyz/reth#23703))
- Avoid u64 underflow in `setup_without_evm` for genesis header
([#23728](paradigmxyz/reth#23728))

**Testing**
- Add BAL request e2e coverage
([#23727](paradigmxyz/reth#23727))
- Cover admin node info discv5 port
([#23781](paradigmxyz/reth#23781))

**Misc**
- Bump reth core to v0.3.1
([#23707](paradigmxyz/reth#23707)) and alloy-evm
to 0.33.3 ([#23778](paradigmxyz/reth#23778))
- Align ERA1 export with spec
([#23693](paradigmxyz/reth#23693))

## Migrations

🔗 Amp thread:
https://ampcode.com/threads/T-019dd89c-63d3-752f-ac22-7d4aef2ac3e3
- **Bumped reth git rev** from `7839f3d` to `73ec2c9` across all
`reth-*` workspace dependencies in
[Cargo.toml](file:///home/runner/work/tempo/tempo/Cargo.toml), and
bumped `reth-primitives-traits` from `0.3.0` to `0.3.1` and `alloy-evm`
from `0.33.0` to `0.34.0` to track upstream releases.
- **Switched p2p proxy transactions channel** from
`tokio::sync::mpsc::unbounded_channel` to
`reth_metrics::common::mpsc::memory_bounded_channel` with a 32 MiB
budget in
[bin/tempo/src/p2p_proxy.rs](file:///home/runner/work/tempo/tempo/bin/tempo/src/p2p_proxy.rs),
matching reth's new default `tx_channel_memory_limit_bytes` to prevent
unbounded memory growth; added `reth-metrics` to
[bin/tempo/Cargo.toml](file:///home/runner/work/tempo/tempo/bin/tempo/Cargo.toml).
- **Changed `BlockExecutor::commit_transaction` signature** in
[crates/evm/src/block.rs](file:///home/runner/work/tempo/tempo/crates/evm/src/block.rs)
from returning `Result<GasOutput, BlockExecutionError>` to returning
`GasOutput` directly (upstream removed the fallible return); replaced
the missing-tx error with an `expect`, and updated all tests to drop
`.unwrap()`.
- **Added `Send + 'static` bound to `TxResult` impl** for
`TempoTxResult<H>` to satisfy the new upstream trait bounds on
associated execution-result types.
- **Exposed `TempoBlockExecutor` and `TempoTxResult` as `pub`**
(previously `pub(crate)`) and re-exported them from
[crates/evm/src/lib.rs](file:///home/runner/work/tempo/tempo/crates/evm/src/lib.rs)
so they can be named in the new associated types.
- **Added associated types `TxExecutionResult` and `Executor` to
`BlockExecutorFactory` impl** for `TempoEvmConfig`, and changed
`create_executor` to return the concrete `Self::Executor<'a, DB, I>`
instead of `impl BlockExecutorFor<'a, Self, DB, I>`, tracking upstream's
move from RPIT to named associated types; dropped the now-unused
`BlockExecutorFor` import and the `'a` lifetime bounds on `DB`/`I`.
- **Implemented new `HeaderMut` methods** (`set_mix_hash`,
`set_extra_data`, `set_parent_beacon_block_root`) for `TempoHeader` in
[crates/primitives/src/reth_compat/header.rs](file:///home/runner/work/tempo/tempo/crates/primitives/src/reth_compat/header.rs)
to satisfy the expanded upstream trait, delegating to the inner Ethereum
header.

[GitHub
Workflow](https://github.com/tempoxyz/tempo/actions/runs/25101489247)

---------

Co-authored-by: Centaur AI <ai@centaur.local>
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: klkvr <klkvrr@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-db Related to the database A-engine Related to the engine implementation A-trie Related to Merkle Patricia Trie implementation

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants