Skip to content

op-reth: Fold the speculative flashblock chain through reth's overlay manager #24062

Open

Description

@aakoshh

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_assert in OverlayBuilder::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::database and ProviderFactory::overlay_manager are both pub(crate).
  • OpEthApi is generic over its provider (StateProviderFactory), so even public accessors on BlockchainProvider are 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.

  1. A chain-taking state_with_blocks_appended on StateProviderFactory, with state_with_block_appended as its one-block case. It takes the blocks by value, as with_appended_block does, 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 calls provider.state_with_blocks_appended(anchor, chain) through the generic interface, with no copied code. Open question: a generic method makes StateProviderFactory unusable as a trait object. Nothing uses it that way today, in reth or in this repo, and where Self: Sized on the method would keep the trait object-safe. If upstream wants the method itself callable through dyn, a Vec<ExecutedBlock<_>> parameter works too. To keep the one-block path free of a one-element allocation, state_with_block_appended then stays its own required method instead of a default, and implementors write both short bodies.

  2. A state_overlay(parent_hash) that returns an append handle, for callers that need to do something between appends. A trait in reth-storage-api, implemented in reth-provider by a struct that holds the database factory and the OverlayBuilder. append is with_appended_block behind 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)), and state_with_block_appended becomes the one-block case. It is more flexible than option 1, but adds a trait. Its impl Trait return raises the same object-safety question, and #[auto_impl(&, Box, Arc)] on StateProviderFactory would have to forward it.

  3. Public database() and overlay_manager() accessors. These need no new concepts upstream, but op-reth then rebuilds what state_with_block_appended does, 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 changes state_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. OpEthApi reaches its provider as N::Provider, and N: RpcNodeCore only promises StateProviderFactory and the reader traits, while database() would exist only on BlockchainProvider<T>. Either OpEthApi's LoadPendingBlock impl requires N: RpcNodeCore<Provider = BlockchainProvider<T>>, which ties every OpEthApi to the concrete provider, or op-reth defines its own trait for reaching the database, implements it for BlockchainProvider, and bounds N::Provider by it. Either way, every place that builds an OpEthApi, 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.

  4. Any of these carried on the op-* fork branches until upstream takes one, listed under "Carried patches" in rust/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.rs and the speculative branch of pending_flashblock_state are 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

  1. self-assigned this
    on Nov 11, 2026
  2. aakoshh commented on Nov 11, 2026

    @aakoshh
    ContributorAuthor

    When this lands, revisit overriding LoadPendingBlock::local_pending_block_or_state to return PendingStateSource::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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions