Repository navigation
Description
reth v2.7.0 removed MemoryOverlayStateProvider (paradigmxyz/reth#26923). Since #24024, op-reth opens the pending state of a flashblock tip built on the canonical anchor through reth's state_with_block_appended. A speculative tip, built on another pending block, goes through a v2.6.0 copy of the removed provider, vendored in rust/op-reth/crates/rpc/src/eth/memory_overlay.rs. This issue tracks the reth change that would let op-reth delete that copy.
Problem
Two overlay implementations now serve pending state: reth's OverlayStateProvider, and a frozen copy that no upstream fix reaches. If upstream changes how the overlay zeroes destroyed storage or aggregates trie input, speculative pending state can drift from engine state. The copy also holds only the tip, so block hash lookups miss the pending blocks between the anchor and the tip.
state_with_block_appended(parent_hash, block) can't open a speculative tip. With canonical head N-1, a tip N+1 names pending N as its parent, which reth knows nowhere:
- Passing N fails with
BlockHashNotFound, because N is in neither the database nor the overlay manager. - Passing N-1 panics on the
debug_assertinOverlayBuilder::with_appended_block, which checks that the hash is the block's header parent.
What reth would need to provide
Folding the whole speculative chain onto the anchor works with reth's own overlay: overlay_builder(anchor).with_appended_block(N).with_appended_block(N+1)…, then OverlayStateProviderFactory::new(database, builder).database_provider_ro(). That is state_with_block_appended's body (crates/storage/provider/src/providers/blockchain_provider.rs) with a loop. op-reth can't do it today, for two reasons:
- The overlay manager and the database factory are private:
BlockchainProvider::databaseandProviderFactory::overlay_managerare bothpub(crate). OpEthApiis generic over its provider (StateProviderFactory), so even public accessors onBlockchainProviderare out of reach without an extension trait or a concrete-provider bound.
StateProviderFactory can't return an OverlayBuilder directly either: it lives in reth-storage-api, and reth-storage-overlay depends on that crate. Turning a builder into a state provider also needs the database factory.
Options, best first. The first two keep the knowledge of how to build an overlay state provider inside reth, where it changes. With the accessors, every op-reth call site that folds a chain would carry its own tagged copy of it instead.
-
A chain-taking
state_with_blocks_appendedonStateProviderFactory, withstate_with_block_appendedas its one-block case. It takes the blocks by value, aswith_appended_blockdoes, and the one-block path stays allocation-free:/// Returns the state after appending `blocks`, oldest first, to `parent_hash`. fn state_with_blocks_appended( &self, parent_hash: BlockHash, blocks: impl IntoIterator<Item = ExecutedBlock<Self::Primitives>>, ) -> ProviderResult<StateProviderBox>; fn state_with_block_appended(&self, parent_hash: BlockHash, block: ExecutedBlock<Self::Primitives>) -> ProviderResult<StateProviderBox> { self.state_with_blocks_appended(parent_hash, std::iter::once(block)) }
It doesn't change reth's model of the pending block: the existing method already takes any parent hash, and the engine already folds in-memory chains through the same
OverlayBuilder. Implementors swap one required method for another. op-reth then callsprovider.state_with_blocks_appended(anchor, chain)through the generic interface, with no copied code. Open question: a generic method makesStateProviderFactoryunusable as a trait object. Nothing uses it that way today, in reth or in this repo, andwhere Self: Sizedon the method would keep the trait object-safe. If upstream wants the method itself callable throughdyn, aVec<ExecutedBlock<_>>parameter works too. To keep the one-block path free of a one-element allocation,state_with_block_appendedthen stays its own required method instead of a default, and implementors write both short bodies. -
A
state_overlay(parent_hash)that returns an append handle, for callers that need to do something between appends. A trait inreth-storage-api, implemented inreth-providerby a struct that holds the database factory and theOverlayBuilder.appendiswith_appended_blockbehind the trait, so nothing is boxed:/// A state built by appending executed blocks onto a parent block's state. pub trait StateOverlay<N: NodePrimitives>: Sized + Send { fn append(self, block: ExecutedBlock<N>) -> Self; fn into_state_provider(self) -> ProviderResult<StateProviderBox>; } // on StateProviderFactory: fn state_overlay(&self, parent_hash: BlockHash) -> ProviderResult<impl StateOverlay<Self::Primitives>>;
op-reth would fold the chain with
chain.into_iter().fold(provider.state_overlay(anchor)?, |o, block| o.append(block)), andstate_with_block_appendedbecomes the one-block case. It is more flexible than option 1, but adds a trait. Itsimpl Traitreturn raises the same object-safety question, and#[auto_impl(&, Box, Arc)]onStateProviderFactorywould have to forward it. -
Public
database()andoverlay_manager()accessors. These need no new concepts upstream, but op-reth then rebuilds whatstate_with_block_appendeddoes, in its pending state code:let db = provider.database(); let builder = chain.into_iter().fold(db.overlay_manager().overlay_builder(anchor), |b, block| { b.with_appended_block(block) }); Box::new(OverlayStateProviderFactory::new(db.clone(), builder).database_provider_ro()?)
This doesn't modify upstream's method; it is our own code repeating how reth turns an overlay builder into a state provider. An
UPSTREAM-MIRROR(copy)tag on it would serve as a reminder: if upstream changesstate_with_block_appended, say with another builder setting or a different factory, the next bump re-checks our fold. The match is only approximate, since our version lives in the RPC's pending state code rather than in a provider method.It also needs extra generic bounds.
OpEthApireaches its provider asN::Provider, andN: RpcNodeCoreonly promisesStateProviderFactoryand the reader traits, whiledatabase()would exist only onBlockchainProvider<T>. EitherOpEthApi'sLoadPendingBlockimpl requiresN: RpcNodeCore<Provider = BlockchainProvider<T>>, which ties everyOpEthApito the concrete provider, or op-reth defines its own trait for reaching the database, implements it forBlockchainProvider, and boundsN::Providerby it. Either way, every place that builds anOpEthApi, the node builder and tests with mock providers included, has to satisfy the new bound.The accessors would also expose the manager's
insert_block, which would let callers write unvalidated blocks into the engine's shared overlay. -
Any of these carried on the
op-*fork branches until upstream takes one, listed under "Carried patches" inrust/UPDATING-RETH.md. The accessors are the cheapest to carry: two visibility changes that rarely conflict.
Also needed
The chain itself has to reach the RPC first: today the RPC only sees the tip. #23998 tracks that.
Done when
memory_overlay.rsand the speculative branch ofpending_flashblock_stateare gone.- Speculative pending state, block hash lookups included, comes from reth's overlay.
- A test covers a speculative chain more than one block deep.
Activity
aakoshh commentedon Nov 11, 2026
When this lands, revisit overriding
LoadPendingBlock::local_pending_block_or_stateto returnPendingStateSource::Block, suggested in #24024 (comment). It would save one blocking-task hop per pending query, but today it would put back a lazy anchor failure and need both pending methods overridden (reasoning in the reply there, and #24069).