feat(builder): state trie cache warming with channel-based streaming

[niran]

Overview

Add background state trie cache warming that continuously warms caches during block building by streaming per-transaction state updates over a channel — matching reth's state root task pattern for future swapability.

Problem Statement

When the builder runs with disable_state_root: true, witness generation for the state trie uses cold caches, causing slow performance. This can contribute to missed blocks during high-load periods.

Solution

Stream per-transaction EvmState diffs to a background StateTrieWarmerTask that incrementally accumulates HashedPostState and continuously computes state roots to warm OS/DB caches. The channel-based design mirrors reth's parallel state root system (MultiProofMessage / StateHookSender) so the warming task can be swapped for the real state root task later without changing execution code.

Architecture

Execution: evm.transact() → EvmState
    ↓ (StateTrieHook — mpsc channel)
StateTrieWarmerTask: receives StateUpdate(EvmState)
    → evm_state_to_hashed_post_state() → HashedPostState
    → accumulates incrementally per-tx
    → debounced state_root_with_updates() (10ms after first tx)
    → re-schedules if new txs arrive during computation
    ↓ (on Drop)
StateTrieHook sends FinishedStateUpdates → final warming → task exits

Key types (mirrors reth's state root task interface)

• StateTrieMessage — StateUpdate(EvmState) | FinishedStateUpdates (mirrors MultiProofMessage)
• StateTrieHook — sender wrapper with auto-finish on Drop (mirrors StateHookSender)
• StateTrieWarmerTask — background task on spawn_blocking with continuous warming algorithm
• evm_state_to_hashed_post_state() — converts per-tx EVM state to hashed form (copied from reth multiproof.rs)

Continuous warming algorithm

1. Block on recv() for first StateUpdate, accumulate into HashedPostState
2. Debounce: recv_timeout(10ms) to drain more updates
3. Compute state_root_with_updates(accumulated.clone()) to warm caches
4. try_recv() non-blocking drain of messages queued during computation
5. If new messages arrived → go to 3 (skip debounce, immediate re-computation)
6. If no new messages → go to 1 (back to blocking wait)
7. FinishedStateUpdates at any step → final warming if needed, then exit

Lifecycle

• Block start: create channel, spawn task with provider
• During execution: hook sends state after each evm.transact() (before commit)
• Block end: hook dropped → FinishedStateUpdates → task runs final warming → exits

Configuration

--flashblocks.enable-state-trie-warming  # (default: false)
FLASHBLOCKS_ENABLE_STATE_TRIE_WARMING=true

Metrics

• base_builder_state_trie_warming_started_count — warming computations started
• base_builder_state_trie_warming_completed_count — warming computations completed
• base_builder_state_trie_warming_duration — duration histogram
• base_builder_state_trie_warming_error_count — error count

Test Plan

• Unit tests for StateTrieHook (noop, drop semantics)
• Unit tests for StateTrieWarmerTask (completion, channel close, no-update exit, accumulation)
• Deploy to Sepolia Alpha with FLASHBLOCKS_ENABLE_STATE_TRIE_WARMING=true
• Validate warming metrics are recorded
• Measure witness generation latency with warming enabled vs disabled
• Verify no regression in flashblock build times

Files Changed

• bin/builder/src/cli.rs — CLI flag
• crates/builder/core/src/flashblocks/state_trie_warmer.rs — StateTrieMessage, StateTrieHook, StateTrieWarmerTask, evm_state_to_hashed_post_state(), tests
• crates/builder/core/src/flashblocks/context.rs — state_hook parameter, send_state_update() calls after each evm.transact()
• crates/builder/core/src/flashblocks/payload.rs — channel+task creation, hook threading, removed per-flashblock start_warming calls
• crates/builder/core/src/flashblocks/config.rs — enable_state_trie_warming config field
• crates/builder/core/src/flashblocks/mod.rs — module exports
• crates/builder/core/src/metrics.rs — warming metrics

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.