Module state_root_strategy 

State-root strategies for engine-tree block validation.

A StateRootStrategy is installed once per node, via BasicEngineValidator::with_state_root_strategy, and consulted for every block that engine validation executes. For each block the strategy prepares a StateRootJob before execution starts, and validation finishes the job after execution to obtain the state root that is checked against the block header. On every FCU that carries payload attributes, the strategy is also asked through StateRootStrategy::prepare_payload_builder for an optional PayloadStateRootHandle that the payload builder uses while building a block.

Job lifecycle

1. StateRootStrategy::prepare runs before block execution. The job can spawn background work here and can expose hooks that observe execution.
2. Execution runs. Jobs that observe execution receive updates through their hooks.
3. StateRootJob::finish runs after execution and returns the StateRootJobOutcome. It must produce a result even if no execution updates were observed, since the full BlockExecutionOutput is passed to it.

Dropping a prepared job without calling finish aborts it. Implementations must treat channel disconnects from dropped hooks as cancellation and must not leak background work.

Stream delivery contract

A prepared job exposes update-stream capabilities over its sink. prepare installs exactly one authoritative capability per block, matching the execution mode:

• On the parallel BAL execution path, prewarm converts the block access list and delivers pre-hashed updates through the hashed update stream, terminated by StateRootUpdateStream::finish.
• On the serial execution path, per-transaction EvmState updates arrive through the execution hook, terminated when the hook is dropped after execution.

Which path runs depends on runtime conditions (BAL present, caching and prewarming enabled), so a sink must handle both. Access hints from prewarming are best-effort: they may be missing, duplicated, or stale, and must not be treated as state updates.

Custom strategies

Custom implementations can hold a DefaultStateRootStrategy and forward calls to it for blocks where the default behavior is wanted, for example before a fork activates. See examples/custom-state-root for the wiring.

Returning empty trie updates in the outcome means the trie tables are no longer maintained: eth_getProof and anything else that reads the stored trie will not work for new blocks. Returning no changed paths opts the block out of sparse-trie cache pruning.

Structs

DefaultStateRootStrategy

Default state-root strategy used by engine-tree validation.

PayloadStateRootHandle

Opaque state-root task handle passed to payload builders.

PayloadStateRootJobContext

Data available while preparing one payload-builder state-root handle.

PreparedStateRootJob

Prepared per-block state-root work and its update-stream capabilities.

StateAccessHint

Hashed account and storage keys that a state-root task may want to prefetch.

StateRootComputeOutcome

Outcome of the state root computation, including the state root itself with the trie updates.

StateRootHandle

Handle to a background sparse trie state root computation.

StateRootHintStream

Hint-only view of a state-root stream.

StateRootJobContext

Data available while preparing one state-root job.

StateRootJobOutcome

Outcome of a per-block state-root job.

StateRootTaskCancelGuard

Guard that cancels a state-root task when dropped.

StateRootUpdateHook

EVM hook that forwards state updates into a StateRootSink.

StateRootUpdateStream

Authoritative update capability of a state-root stream.

Enums

StateRootMessage

Messages used internally by the multi proof task.

StateRootTaskError

Error returned by the state-root task and the parallel proof workers.

Traits

StateRootJob

Per-block state-root job prepared before execution and finished after execution.

StateRootSink

Semantic update stream consumed by state-root tasks.

StateRootStrategy

Strategy used by engine-tree validation to prepare per-block state-root work.

Functions

evm_state_to_hashed_post_state

Converts [EvmState] to HashedPostState by keccak256-hashing addresses and storage slots.

Type Aliases

LazyHashedPostState

Handle to a HashedPostState computed on a background thread.