Skip to content

feat(payload): Allow PayloadBuilder to pass in custom state roots for verification #23884

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ControlCplusControlV wants to merge 3 commits into
base: main
Choose a base branch
from
+108 −80
Open

feat(payload): Allow PayloadBuilder to pass in custom state roots for verification #23884

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
19152ba
added: in custom state root bypass
ControlCplusControlV Apr 30, 2026
fe3e1f2
fixed: fmt
ControlCplusControlV Apr 30, 2026
c868ede
fixed: trailing comment formula
ControlCplusControlV Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions crates/engine/primitives/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ reth-chain-state.workspace = true
reth-errors.workspace = true
reth-trie-common.workspace = true

# revm
revm.workspace = true

# alloy
alloy-primitives.workspace = true
alloy-consensus.workspace = true
Expand Down
10 changes: 10 additions & 0 deletions crates/engine/primitives/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,15 @@
extern crate alloc;

use alloy_consensus::BlockHeader;
use alloy_primitives::B256;
use reth_errors::ConsensusError;
use reth_payload_primitives::{
EngineApiMessageVersion, EngineObjectValidationError, InvalidPayloadAttributesError,
NewPayloadError, PayloadAttributes, PayloadOrAttributes, PayloadTypes,
};
use reth_primitives_traits::{Block, RecoveredBlock, SealedBlock};
use reth_trie_common::HashedPostState;
use revm::database::states::BundleState;
use serde::{de::DeserializeOwned, Serialize};

// Re-export [`ExecutionPayload`] moved to `reth_payload_primitives`
Expand Down Expand Up @@ -212,6 +214,14 @@ pub trait PayloadValidator<Types: PayloadTypes>: Send + Sync + Unpin + 'static {
sealed_block.try_recover().map_err(|e| NewPayloadError::Other(e.into()))
}

/// Computes a custom state root for some networks, bypassing the default trie computation.
///
/// Returns `None` by default to use th standard Ethereum state root. Returning `Some` will
/// cause the engine to skip trie computation and validate using the returned value instead.
fn compute_state_root(&self, _bundle_state: &BundleState, _parent_hash: B256) -> Option<B256> {
None
}

/// Verifies payload post-execution w.r.t. hashed state updates.
fn validate_block_post_execution_with_hashed_state(
&self,
Expand Down
174 changes: 94 additions & 80 deletions crates/engine/tree/src/tree/payload_validator.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -655,112 +655,126 @@ where
);

let root_time = Instant::now();

let custom_state_root =
self.validator.compute_state_root(&output.state, block.header().parent_hash());
if let Some(custom_root) = custom_state_root {
info!(
target: "engine::tree::payload_validator",
?custom_root,
elapsed = ?root_time.elapsed(),
"Custom state root computed"
);
}

let mut maybe_state_root = None;
let mut state_root_task_failed = false;
#[cfg(feature = "trie-debug")]
let mut trie_debug_recorders = Vec::new();

match strategy {
StateRootStrategy::StateRootTask => {
debug!(target: "engine::tree::payload_validator", "Using sparse trie state root algorithm");

let task_result = ensure_ok_post_block!(
self.await_state_root_with_timeout(
&mut handle,
provider_builder.clone(),
&hashed_state,
),
block
);
if custom_state_root.is_none() {
match strategy {
StateRootStrategy::StateRootTask => {
debug!(target: "engine::tree::payload_validator", "Using sparse trie state root algorithm");

let task_result = ensure_ok_post_block!(
self.await_state_root_with_timeout(
&mut handle,
provider_builder.clone(),
&hashed_state,
),
block
);

match task_result {
Ok(StateRootComputeOutcome {
state_root,
trie_updates,
#[cfg(feature = "trie-debug")]
debug_recorders,
}) => {
let elapsed = root_time.elapsed();
info!(target: "engine::tree::payload_validator", ?state_root, ?elapsed, "State root task finished");

#[cfg(feature = "trie-debug")]
{
trie_debug_recorders = debug_recorders;
}
match task_result {
Ok(StateRootComputeOutcome {
state_root,
trie_updates,
#[cfg(feature = "trie-debug")]
debug_recorders,
}) => {
let elapsed = root_time.elapsed();
info!(target: "engine::tree::payload_validator", ?state_root, ?elapsed, "State root task finished");

// Compare trie updates with serial computation if configured
if self.config.always_compare_trie_updates() {
let _has_diff = self.compare_trie_updates_with_serial(
provider_builder.clone(),
provider_factory,
overlay_builder,
&hashed_state,
trie_updates.as_ref().clone(),
);
#[cfg(feature = "trie-debug")]
if _has_diff {
{
trie_debug_recorders = debug_recorders;
}

// Compare trie updates with serial computation if configured
if self.config.always_compare_trie_updates() {
let _has_diff = self.compare_trie_updates_with_serial(
provider_builder.clone(),
provider_factory,
overlay_builder,
&hashed_state,
trie_updates.as_ref().clone(),
);
#[cfg(feature = "trie-debug")]
if _has_diff {
Self::write_trie_debug_recorders(
block.header().number(),
&trie_debug_recorders,
);
}
}

// we double check the state root here for good measure
if state_root == block.header().state_root() {
maybe_state_root = Some((state_root, trie_updates, elapsed))
} else {
warn!(
target: "engine::tree::payload_validator",
?state_root,
block_state_root = ?block.header().state_root(),
"State root task returned incorrect state root"
);
#[cfg(feature = "trie-debug")]
Self::write_trie_debug_recorders(
block.header().number(),
&trie_debug_recorders,
);
state_root_task_failed = true;
}
}

// we double check the state root here for good measure
if state_root == block.header().state_root() {
maybe_state_root = Some((state_root, trie_updates, elapsed))
} else {
warn!(
target: "engine::tree::payload_validator",
?state_root,
block_state_root = ?block.header().state_root(),
"State root task returned incorrect state root"
);
#[cfg(feature = "trie-debug")]
Self::write_trie_debug_recorders(
block.header().number(),
&trie_debug_recorders,
);
Err(error) => {
debug!(target: "engine::tree::payload_validator", %error, "State root task failed");
state_root_task_failed = true;
}
}
Err(error) => {
debug!(target: "engine::tree::payload_validator", %error, "State root task failed");
state_root_task_failed = true;
}
}
}
StateRootStrategy::Parallel => {
debug!(target: "engine::tree::payload_validator", "Using parallel state root algorithm");
match self.compute_state_root_parallel(
provider_factory,
overlay_builder,
&hashed_state,
) {
Ok(result) => {
let elapsed = root_time.elapsed();
info!(
target: "engine::tree::payload_validator",
regular_state_root = ?result.0,
?elapsed,
"Regular root task finished"
);
maybe_state_root = Some((result.0, Arc::new(result.1), elapsed));
}
Err(error) => {
debug!(target: "engine::tree::payload_validator", %error, "Parallel state root computation failed");
StateRootStrategy::Parallel => {
debug!(target: "engine::tree::payload_validator", "Using parallel state root algorithm");
match self.compute_state_root_parallel(
provider_factory,
overlay_builder,
&hashed_state,
) {
Ok(result) => {
let elapsed = root_time.elapsed();
info!(
target: "engine::tree::payload_validator",
regular_state_root = ?result.0,
?elapsed,
"Regular root task finished"
);
maybe_state_root = Some((result.0, Arc::new(result.1), elapsed));
}
Err(error) => {
debug!(target: "engine::tree::payload_validator", %error, "Parallel state root computation failed");
}
}
}
StateRootStrategy::Synchronous => {}
}
StateRootStrategy::Synchronous => {}
}

// Determine the state root.
// If the state root was computed in parallel, we use it.
// Otherwise, we fall back to computing it synchronously.
let (state_root, trie_output, root_elapsed) = if let Some(maybe_state_root) =
maybe_state_root
{
let (state_root, trie_output, root_elapsed) = if let Some(custom_root) = custom_state_root {
(custom_root, Arc::new(TrieUpdates::default()), root_time.elapsed())
} else if let Some(maybe_state_root) = maybe_state_root {
maybe_state_root
} else {
// fallback is to compute the state root regularly in sync
Expand Down