From fcaf68d30d04702b566cc89d11f02f81cb445ec5 Mon Sep 17 00:00:00 2001 From: valvecitydev Date: Wed, 11 Nov 2026 18:49:22 -0600 Subject: [PATCH 1/2] feat(firehose): add a post-block hook for state changes outside the EVM Some chains change state in the block executor's finish, outside the EVM, where the Firehose inspector cannot see it. PostTxExtras gains capture_post_block, which runs before the inner finish and returns a PostBlockChanges. The wrapper emits it after the inner finish, after the withdrawal balance changes. The default captures nothing, so Ethereum output does not change. FirehoseEvmConfig now uses F's hooks instead of the no-op ones: on the engine path through FirehoseLiveHooks, and on the pipeline path through a new LiveChainHooks for its batch executor. Before, a chain that wrapped its EVM configuration in FirehoseEvmConfig lost its hooks. --- crates/firehose-tests/Cargo.toml | 4 + .../firehose-tests/tests/post_block_hook.rs | 212 ++++++++++++++++++ crates/firehose/src/executor.rs | 94 +++++++- crates/firehose/src/lib.rs | 4 +- 4 files changed, 305 insertions(+), 9 deletions(-) create mode 100644 crates/firehose-tests/tests/post_block_hook.rs diff --git a/crates/firehose-tests/Cargo.toml b/crates/firehose-tests/Cargo.toml index f1013b3bc88..07f957d84f7 100644 --- a/crates/firehose-tests/Cargo.toml +++ b/crates/firehose-tests/Cargo.toml @@ -52,3 +52,7 @@ path = "tests/batch_executor.rs" [[test]] name = "staged_sync_bal" path = "tests/staged_sync_bal.rs" + +[[test]] +name = "post_block_hook" +path = "tests/post_block_hook.rs" diff --git a/crates/firehose-tests/tests/post_block_hook.rs b/crates/firehose-tests/tests/post_block_hook.rs new file mode 100644 index 00000000000..dcd405233b1 --- /dev/null +++ b/crates/firehose-tests/tests/post_block_hook.rs @@ -0,0 +1,212 @@ +//! Regression test: a chain's post-block hook reaches the traced block, through the hooks of the +//! EVM configuration that [`FirehoseEvmConfig`] wraps. +//! +//! A chain whose block executor changes state in `finish`, outside the EVM, reports those changes +//! with [`PostTxExtras::capture_post_block`]. The pipeline must install the wrapped +//! configuration's hooks, capture before the inner finish, and emit after the withdrawal balance +//! changes. +//! +//! It lives in its own integration-test binary because it installs the process-wide tracer. + +use std::{any::TypeId, ops::DerefMut, path::PathBuf}; + +use alloy_eips::eip4895::Withdrawal; +use alloy_primitives::{Address, U256}; +use firehose_tracer::pb::sf::ethereum::r#type::v2::{balance_change::Reason, BigInt}; +use reth_ethereum_primitives::EthPrimitives; +use reth_evm::{execute::Executor, ConfigureEvm, EvmEnvFor, ExecutionCtxFor}; +use reth_evm_ethereum::EthEvmConfig; +use reth_firehose::{ + FirehoseEvmConfig, FirehoseInspector, FirehoseLiveHooks, NoPreTxAdjust, PostBlockChanges, + PostTxExtras, +}; +use reth_firehose_tests::{load_prestate, parse_fire_block_for, LoadedPrestate}; +use reth_primitives_traits::{HeaderTy, RecoveredBlock, SealedBlock, SealedHeader}; +use reth_trie_common::bundle_state::BundleState; + +/// Receives the block's only withdrawal. +const RECIPIENT: Address = Address::with_last_byte(0x77); +/// Gets a change from [`TestHooks::emit_post_tx_extras`] after each transaction. +const POST_TX_MARKER: Address = Address::with_last_byte(0x88); +/// A reason the block produces nowhere else. +const POST_BLOCK_REASON: Reason = Reason::DaoRefundContract; + +#[test] +fn post_block_changes_follow_the_withdrawals() { + // `FirehoseEvmConfig` selects the wrapped configuration's hooks for the engine path. + assert_eq!( + TypeId::of::< as FirehoseLiveHooks>::PostTxExtras>(), + TypeId::of::() + ); + + let case = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/cases/nop_transfer"); + let LoadedPrestate { prestate, chain_spec, block, db } = + load_prestate(&case).expect("loading the nop_transfer prestate"); + let (mut block, senders) = block.split(); + let withdrawal = Withdrawal { index: 0, validator_index: 0, address: RECIPIENT, amount: 1 }; + block.body.withdrawals = Some(vec![withdrawal].into()); + let block = RecoveredBlock::new_unhashed(block, senders); + + let config = &prestate.genesis.config; + let buffer = reth_firehose::init_tracer_with_buffer( + config.chain_id, + config.shanghai_time, + config.cancun_time, + config.prague_time, + ); + let evm_config = FirehoseEvmConfig::new(TestEvmConfig(EthEvmConfig::new(chain_spec))); + let mut executor = evm_config.batch_executor(db); + executor.execute_and_trace_one(&block).expect("execute_and_trace_one succeeds"); + // Reaching `into_state` confirms the last block passed validation, which flushes it. + let _ = executor.into_state(); + let fire_block = + parse_fire_block_for(&buffer.get_bytes(), block.header().number).expect("block emitted"); + + // The pipeline installs the wrapped configuration's post-transaction hook. + let transaction = &fire_block.transaction_traces[0]; + assert!( + transaction.calls[0] + .balance_changes + .iter() + .any(|change| change.address == POST_TX_MARKER.as_slice()), + "the post-transaction hook did not run" + ); + + // The hook read the balance before the inner finish and got the final state after it, and + // its change comes after the withdrawal's. + let gwei = U256::from(1_000_000_000u64); + let changes = fire_block + .balance_changes + .iter() + .map(|change| { + ( + Address::from_slice(&change.address), + value(change.old_value.as_ref()), + value(change.new_value.as_ref()), + change.reason(), + ) + }) + .collect::>(); + assert_eq!( + changes, + vec![ + (RECIPIENT, U256::ZERO, gwei, Reason::Withdrawal), + (RECIPIENT, U256::ZERO, gwei, POST_BLOCK_REASON), + ] + ); + assert!(fire_block.balance_changes[0].ordinal < fire_block.balance_changes[1].ordinal); +} + +/// Decodes a Firehose `BigInt`, where an absent value is zero. +fn value(value: Option<&BigInt>) -> U256 { + value.map(|value| U256::from_be_slice(&value.bytes)).unwrap_or_default() +} + +/// Chain hooks that mark each transaction and report [`RECIPIENT`]'s change across the inner +/// finish. +#[derive(Debug, Default, Clone, Copy)] +struct TestHooks; + +impl PostTxExtras for TestHooks { + fn emit_post_tx_extras>( + &self, + _evm: &mut E, + inspector: &FirehoseInspector, + _gas_used: u64, + _base_fee: u64, + ) { + inspector.tracer_mut().on_balance_change( + POST_TX_MARKER, + U256::ZERO, + U256::from(1u64), + Reason::RewardTransactionFee, + ); + } + + fn capture_post_block( + &self, + evm: &mut E, + _block_number: u64, + _chain_id: u64, + ) -> Option> { + let balance = evm + .account_info(&RECIPIENT) + .ok() + .flatten() + .map(|info| info.balance) + .unwrap_or_default(); + Some(Box::new(RecipientChange { balance })) + } +} + +/// [`RECIPIENT`]'s balance before the inner finish. +#[derive(Debug)] +struct RecipientChange { + balance: U256, +} + +impl PostBlockChanges for RecipientChange { + fn emit(&self, tracer: &mut firehose_tracer::Tracer, state: &BundleState) { + let balance = state + .account(&RECIPIENT) + .and_then(|account| account.info.as_ref()) + .map(|info| info.balance) + .unwrap_or_default(); + tracer.on_balance_change(RECIPIENT, self.balance, balance, POST_BLOCK_REASON); + } +} + +/// An EVM configuration with its own Firehose hooks, standing in for a chain's. +#[derive(Debug, Clone)] +struct TestEvmConfig(EthEvmConfig); + +impl FirehoseLiveHooks for TestEvmConfig { + type PreTxAdjust = NoPreTxAdjust; + type PostTxExtras = TestHooks; +} + +impl ConfigureEvm for TestEvmConfig { + type Primitives = EthPrimitives; + type Error = ::Error; + type NextBlockEnvCtx = ::NextBlockEnvCtx; + type BlockExecutorFactory = ::BlockExecutorFactory; + type BlockAssembler = ::BlockAssembler; + + fn block_executor_factory(&self) -> &Self::BlockExecutorFactory { + self.0.block_executor_factory() + } + + fn block_assembler(&self) -> &Self::BlockAssembler { + self.0.block_assembler() + } + + fn evm_env(&self, header: &HeaderTy) -> Result, Self::Error> { + self.0.evm_env(header) + } + + fn next_evm_env( + &self, + parent: &HeaderTy, + attributes: &Self::NextBlockEnvCtx, + ) -> Result, Self::Error> { + self.0.next_evm_env(parent, attributes) + } + + fn context_for_block<'a>( + &self, + block: &'a SealedBlock, + ) -> Result, Self::Error> + where + Self: 'a, + { + self.0.context_for_block(block) + } + + fn context_for_next_block( + &self, + parent: &SealedHeader>, + attributes: Self::NextBlockEnvCtx, + ) -> Result, Self::Error> { + self.0.context_for_next_block(parent, attributes) + } +} diff --git a/crates/firehose/src/executor.rs b/crates/firehose/src/executor.rs index c470f0084f5..cf602a3f85d 100644 --- a/crates/firehose/src/executor.rs +++ b/crates/firehose/src/executor.rs @@ -92,6 +92,28 @@ pub trait PostTxExtras { fn gas_accounting(&self, _evm: &mut E, ethereum: PostTxGasAccounting) -> PostTxGasAccounting { ethereum } + + /// Snapshots, before the inner executor's `finish`, what the chain's own post-block changes + /// will write outside the EVM, where the inspector cannot see them. + /// + /// `evm` reads the state after the block's last transaction. The wrapper calls + /// [`PostBlockChanges::emit`] on the result after `finish`, after the withdrawal balance + /// changes. The default captures nothing, so Ethereum emits nothing extra. + fn capture_post_block( + &self, + _evm: &mut E, + _block_number: u64, + _chain_id: u64, + ) -> Option> { + None + } +} + +/// Chain-specific state changes that a block executor's `finish` makes outside the EVM, captured +/// by [`PostTxExtras::capture_post_block`]. +pub trait PostBlockChanges: Debug + Send { + /// Emits the changes to `tracer`, given the block's final state. + fn emit(&self, tracer: &mut firehose_tracer::Tracer, state: &BundleState); } /// No-op [`PostTxExtras`] used on Ethereum mainnet (and any chain whose fee distribution is @@ -154,6 +176,8 @@ impl PreTxAdjust for NoPreTxAdjust { #[derive(Debug, Clone)] pub struct BlockFees { coinbase: Address, + /// Number of the block, for [`PostTxExtras::capture_post_block`]. + block_number: u64, base_fee: u64, /// EIP-4844 blob gas price, `None` before Cancun, matching Geth's omission of the field on /// pre-Cancun receipts. @@ -170,6 +194,7 @@ impl BlockFees { let blob_gas_price = spec.enables(evm2::SpecId::CANCUN).then_some(block.blob_basefee); Self { coinbase: block.beneficiary, + block_number: block.number.saturating_to(), base_fee: evm_env.block_base_fee(), blob_gas_price, version, @@ -195,6 +220,9 @@ impl BlockFees { /// | `on_tx_end(Some(receipt_data))` | After `commit_transaction`. | /// | withdrawal balance changes | After the inner finish, so they land in | /// | | `block.balance_changes`. | +/// | chain post-block changes | Captured before the inner finish, emitted after | +/// | | the withdrawal balance changes. See | +/// | | [`PostTxExtras::capture_post_block`]. | /// /// The wrapper does **not** emit `on_block_start` / `on_block_end`; those are owned by the caller /// via [`FirehoseBlockTracer::start`] / [`FirehoseBlockTracer::mark_verified`] / @@ -455,6 +483,16 @@ where self.fees.blob_gas_price, ) } + + /// Runs the chain's [`PostTxExtras::capture_post_block`] against the state after the block's + /// last transaction. + fn capture_post_block(&mut self) -> Option> { + self.extras.capture_post_block( + self.inner.evm_mut(), + self.fees.block_number, + self.fees.version.chain_id, + ) + } } impl BlockExecutor for FirehoseWrappedExecutor @@ -569,9 +607,10 @@ where } fn finish_with_block_access_list( - self, + mut self, ) -> Result<(BlockExecutionOutput, Option), BlockExecutionError> { + let post_block = self.capture_post_block(); let Self { inner, inspector, withdrawals, .. } = self; // The post-execution system calls (EIP-7002 withdrawal requests, EIP-7251 consolidation // requests) run inside the window; withdrawals are emitted after it closes. @@ -580,19 +619,26 @@ where inspector.tracer_mut().on_system_call_end(); let (output, bal) = finished?; emit_withdrawal_balance_changes(&inspector, withdrawals.as_ref(), &output.state); + if let Some(post_block) = post_block { + post_block.emit(&mut inspector.tracer_mut(), &output.state); + } Ok((output, bal)) } fn finish_with_prepared_block_access_list( - self, + mut self, ) -> Result<(BlockExecutionOutput, Option), BlockExecutionError> { + let post_block = self.capture_post_block(); let Self { inner, inspector, withdrawals, .. } = self; inspector.tracer_mut().on_system_call_start(); let finished = inner.finish_with_prepared_block_access_list(); inspector.tracer_mut().on_system_call_end(); let (output, bal) = finished?; emit_withdrawal_balance_changes(&inspector, withdrawals.as_ref(), &output.state); + if let Some(post_block) = post_block { + post_block.emit(&mut inspector.tracer_mut(), &output.state); + } Ok((output, bal)) } } @@ -681,6 +727,39 @@ where } } +/// [`ChainHooks`] that installs the hooks the EVM configuration selects for the live path +/// ([`FirehoseLiveHooks`]), so the pipeline traces a block the same way the engine does. +#[derive(Default, Debug, Clone, Copy)] +pub struct LiveChainHooks; + +impl ChainHooks for LiveChainHooks +where + F: FirehoseLiveHooks, + BlockTy: BlockTrait, + TxTy: Transaction + TxHashRef + SignatureFields, + ::Receipt: TxReceipt, +{ + fn execute_one_traced( + &self, + evm_config: &F, + database: impl DynDatabase, + block: &RecoveredBlock<::Block>, + tracer: &mut FirehoseBlockTracer, + ) -> Result< + (BlockExecutionOutput<::Receipt>, Option), + BlockExecutionError, + > { + run_wrapped_block( + evm_config, + database, + block, + tracer, + F::PreTxAdjust::default(), + F::PostTxExtras::default(), + ) + } +} + /// Chain-specific hooks the live engine-API path installs on its traced block executor. /// /// The engine tree's block validator wraps the traced executor in @@ -698,10 +777,11 @@ pub trait FirehoseLiveHooks: ConfigureEvm { impl FirehoseLiveHooks for FirehoseEvmConfig where - Self: ConfigureEvm, + F: FirehoseLiveHooks, + Self: ConfigureEvm, { - type PreTxAdjust = NoPreTxAdjust; - type PostTxExtras = NoPostTxExtras; + type PreTxAdjust = F::PreTxAdjust; + type PostTxExtras = F::PostTxExtras; } impl FirehoseLiveHooks for reth_evm_ethereum::EthEvmConfig @@ -1130,7 +1210,7 @@ impl FirehoseEvmConfig { impl ConfigureEvm for FirehoseEvmConfig where - F: ConfigureEvm, + F: FirehoseLiveHooks, BlockTy: BlockTrait, as BlockTrait>::Header: BlockHeader + Sealable, as BlockTrait>::Body: BlockBody, @@ -1213,7 +1293,7 @@ where &self, db: DB, ) -> impl Executor { - FirehoseBlockExecutor::new(self.inner.clone(), db) + FirehoseBlockExecutor::new_with_chain_hooks(self.inner.clone(), db, LiveChainHooks) } } diff --git a/crates/firehose/src/lib.rs b/crates/firehose/src/lib.rs index ab307c46b40..077045d23b6 100644 --- a/crates/firehose/src/lib.rs +++ b/crates/firehose/src/lib.rs @@ -20,8 +20,8 @@ pub mod prelude; pub use block_tracer::{FirehoseBlockTracer, GlobalTracerGuard}; pub use executor::{ record_block_access_list, run_wrapped_block, BlockFees, ChainHooks, FirehoseBlockExecutor, - FirehoseEvmConfig, FirehoseLiveHooks, FirehoseWrappedExecutor, NoChainHooks, NoPostTxExtras, - NoPreTxAdjust, PostTxExtras, PreTxAdjust, TracedTransaction, + FirehoseEvmConfig, FirehoseLiveHooks, FirehoseWrappedExecutor, LiveChainHooks, NoChainHooks, + NoPostTxExtras, NoPreTxAdjust, PostBlockChanges, PostTxExtras, PreTxAdjust, TracedTransaction, }; pub use finality::finalized_ref_for_block; pub use firehose_tracer::types::FinalizedBlockRef; From 60b7801677760c6db8a64886043a317e507d2393 Mon Sep 17 00:00:00 2001 From: Matthieu Vachon Date: Fri, 20 Nov 2026 14:00:26 -0500 Subject: [PATCH 2/2] feat(firehose): pass block context to post-block hook capture_post_block now receives the block's BlockFees, which exposes the block number, coinbase, chain id and spec, so a hook can decide from the block alone, as the pre-Merge rewards of #97 need. Both finish variants share one emission helper, and the docs state that post-block changes come last and must not touch withdrawal recipients, whose changes are rebuilt backwards from the final balances. A new test covers the live path's finish variant and both tests check the block invariants. --- CHANGELOG.md | 16 ++ Cargo.lock | 1 + crates/firehose-tests/Cargo.toml | 1 + .../firehose-tests/tests/post_block_hook.rs | 156 ++++++++++++++---- crates/firehose/src/executor.rs | 87 +++++++--- 5 files changed, 206 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 084cfdabe6d..eb7b4d1b816 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,22 @@ This changelog covers Firehose-specific changes only. For upstream reth changes, The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## Unreleased + +### Added + +- `PostTxExtras::capture_post_block` lets a chain report the state changes its block executor + makes in `finish`, outside the EVM. It reads the state after the last transaction and receives + the block's `BlockFees`, which now exposes the block number, coinbase, chain id and spec. The + returned `PostBlockChanges` is emitted after the withdrawal balance changes. The default + captures nothing, so Ethereum output does not change. + +### Fixed + +- `FirehoseEvmConfig` now installs `F`'s Firehose hooks on both the engine and the pipeline + paths, instead of the no-op ones. `ConfigureEvm for FirehoseEvmConfig` now requires + `F: FirehoseLiveHooks`. + ## reth-v2.11.0-fh3.1-1 ### Fixed diff --git a/Cargo.lock b/Cargo.lock index aa99411ae58..f1b8c1a5e47 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -9543,6 +9543,7 @@ dependencies = [ "evm2", "eyre", "firehose-tracer", + "firehose-tracer-test", "hex", "prost", "reth-chainspec", diff --git a/crates/firehose-tests/Cargo.toml b/crates/firehose-tests/Cargo.toml index 07f957d84f7..e3c706a1992 100644 --- a/crates/firehose-tests/Cargo.toml +++ b/crates/firehose-tests/Cargo.toml @@ -13,6 +13,7 @@ workspace = true [dependencies] firehose-tracer.workspace = true +firehose-tracer-test.workspace = true reth-firehose.workspace = true # reth diff --git a/crates/firehose-tests/tests/post_block_hook.rs b/crates/firehose-tests/tests/post_block_hook.rs index dcd405233b1..98613968eed 100644 --- a/crates/firehose-tests/tests/post_block_hook.rs +++ b/crates/firehose-tests/tests/post_block_hook.rs @@ -2,23 +2,32 @@ //! EVM configuration that [`FirehoseEvmConfig`] wraps. //! //! A chain whose block executor changes state in `finish`, outside the EVM, reports those changes -//! with [`PostTxExtras::capture_post_block`]. The pipeline must install the wrapped -//! configuration's hooks, capture before the inner finish, and emit after the withdrawal balance -//! changes. +//! with [`PostTxExtras::capture_post_block`]. Both finish variants must capture before the inner +//! finish and emit after the withdrawal balance changes: the pipeline must install the wrapped +//! configuration's hooks and finish with `finish_with_block_access_list`, the live engine path +//! finishes with `finish_with_prepared_block_access_list`. //! //! It lives in its own integration-test binary because it installs the process-wide tracer. -use std::{any::TypeId, ops::DerefMut, path::PathBuf}; +use std::{any::TypeId, cell::Cell, ops::DerefMut, path::PathBuf}; use alloy_eips::eip4895::Withdrawal; use alloy_primitives::{Address, U256}; -use firehose_tracer::pb::sf::ethereum::r#type::v2::{balance_change::Reason, BigInt}; -use reth_ethereum_primitives::EthPrimitives; -use reth_evm::{execute::Executor, ConfigureEvm, EvmEnvFor, ExecutionCtxFor}; +use firehose_tracer::{ + config::{ChainConfig, Config}, + pb::sf::ethereum::r#type::v2::{balance_change::Reason, BigInt, Block as FirehoseBlock}, + Tracer, +}; +use firehose_tracer_test::BlockInvariants; +use reth_ethereum_primitives::{Block, EthPrimitives}; +use reth_evm::{ + execute::{BlockExecutor, Executor}, + ConfigureEvm, EvmEnv, EvmEnvFor, ExecutionCtxFor, +}; use reth_evm_ethereum::EthEvmConfig; use reth_firehose::{ - FirehoseEvmConfig, FirehoseInspector, FirehoseLiveHooks, NoPreTxAdjust, PostBlockChanges, - PostTxExtras, + BlockFees, FirehoseBlockTracer, FirehoseEvmConfig, FirehoseInspector, FirehoseLiveHooks, + FirehoseWrappedExecutor, NoPreTxAdjust, PostBlockChanges, PostTxExtras, }; use reth_firehose_tests::{load_prestate, parse_fire_block_for, LoadedPrestate}; use reth_primitives_traits::{HeaderTy, RecoveredBlock, SealedBlock, SealedHeader}; @@ -28,41 +37,122 @@ use reth_trie_common::bundle_state::BundleState; const RECIPIENT: Address = Address::with_last_byte(0x77); /// Gets a change from [`TestHooks::emit_post_tx_extras`] after each transaction. const POST_TX_MARKER: Address = Address::with_last_byte(0x88); +/// Gets the post-block change, which spans [`RECIPIENT`]'s balance across the inner finish. +const POST_BLOCK_MARKER: Address = Address::with_last_byte(0x99); /// A reason the block produces nowhere else. const POST_BLOCK_REASON: Reason = Reason::DaoRefundContract; +thread_local! { + /// The `(block number, coinbase, chain id, spec)` [`TestHooks::capture_post_block`] received + /// on this test's thread. + static CAPTURED_BLOCK: Cell> = + const { Cell::new(None) }; +} + #[test] -fn post_block_changes_follow_the_withdrawals() { +fn post_block_changes_follow_the_withdrawals_on_the_pipeline() { // `FirehoseEvmConfig` selects the wrapped configuration's hooks for the engine path. assert_eq!( TypeId::of::< as FirehoseLiveHooks>::PostTxExtras>(), TypeId::of::() ); - let case = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/cases/nop_transfer"); - let LoadedPrestate { prestate, chain_spec, block, db } = - load_prestate(&case).expect("loading the nop_transfer prestate"); - let (mut block, senders) = block.split(); - let withdrawal = Withdrawal { index: 0, validator_index: 0, address: RECIPIENT, amount: 1 }; - block.body.withdrawals = Some(vec![withdrawal].into()); - let block = RecoveredBlock::new_unhashed(block, senders); - - let config = &prestate.genesis.config; + let case = load_case(); + let config = &case.prestate.genesis.config; let buffer = reth_firehose::init_tracer_with_buffer( config.chain_id, config.shanghai_time, config.cancun_time, config.prague_time, ); - let evm_config = FirehoseEvmConfig::new(TestEvmConfig(EthEvmConfig::new(chain_spec))); - let mut executor = evm_config.batch_executor(db); - executor.execute_and_trace_one(&block).expect("execute_and_trace_one succeeds"); + let evm_config = FirehoseEvmConfig::new(TestEvmConfig(EthEvmConfig::new(case.chain_spec))); + let mut executor = evm_config.batch_executor(case.db); + executor.execute_and_trace_one(&case.block).expect("execute_and_trace_one succeeds"); // Reaching `into_state` confirms the last block passed validation, which flushes it. let _ = executor.into_state(); + let fire_block = parse_fire_block_for(&buffer.get_bytes(), case.block.header().number) + .expect("block emitted"); + + assert_post_block_changes(&evm_config.inner, &case.block, config.chain_id, &fire_block); +} + +#[test] +fn post_block_changes_follow_the_withdrawals_on_the_live_path() { + let case = load_case(); + let config = &case.prestate.genesis.config; + let (tracer, buffer) = Tracer::with_buffer( + Config::default(), + ChainConfig { + chain_id: config.chain_id, + shanghai_time: config.shanghai_time, + cancun_time: config.cancun_time, + prague_time: config.prague_time, + verkle_time: None, + }, + "reth-firehose-tests", + env!("CARGO_PKG_VERSION"), + ); + let evm_config = TestEvmConfig(EthEvmConfig::new(case.chain_spec)); + let block = &case.block; + let tracer = FirehoseBlockTracer::start_local::( + Box::new(tracer), + block.sealed_block(), + None, + ); + + let evm_env = evm_config.evm_env(block.header()).expect("evm env of the block"); + let fees = BlockFees::new(&evm_env); + let inner = + evm_config.executor_for_block(case.db, block.sealed_block()).expect("block executor"); + let mut executor = FirehoseWrappedExecutor::with_hooks( + inner, + tracer.inspector(), + fees, + block.body().withdrawals.clone(), + NoPreTxAdjust, + TestHooks, + ); + executor.apply_pre_execution_changes().expect("pre-execution changes apply"); + for transaction in block.transactions_recovered() { + executor.execute_transaction(transaction).expect("transaction executes"); + } + executor.finish_with_prepared_block_access_list().expect("block finishes"); + tracer.mark_verified(); let fire_block = parse_fire_block_for(&buffer.get_bytes(), block.header().number).expect("block emitted"); - // The pipeline installs the wrapped configuration's post-transaction hook. + assert_post_block_changes(&evm_config, block, config.chain_id, &fire_block); +} + +/// The `nop_transfer` case, with one withdrawal to [`RECIPIENT`] added to its block. +fn load_case() -> LoadedPrestate { + let case = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/cases/nop_transfer"); + let mut loaded = load_prestate(&case).expect("loading the nop_transfer prestate"); + let (mut block, senders) = loaded.block.split(); + let withdrawal = Withdrawal { index: 0, validator_index: 0, address: RECIPIENT, amount: 1 }; + block.body.withdrawals = Some(vec![withdrawal].into()); + loaded.block = RecoveredBlock::new_unhashed(block, senders); + loaded +} + +/// Checks that [`TestHooks`] ran on `fire_block`, traced from `block`, and that its post-block +/// change comes after the withdrawal's. +fn assert_post_block_changes( + evm_config: &TestEvmConfig, + block: &RecoveredBlock, + chain_id: u64, + fire_block: &FirehoseBlock, +) { + BlockInvariants::assert(fire_block).expect("the block holds the invariants"); + + // The hook got the block it runs for. + let evm_env = evm_config.evm_env(block.header()).expect("evm env of the block"); + assert_eq!( + CAPTURED_BLOCK.get(), + Some((block.header().number, block.header().beneficiary, chain_id, evm_env.spec_id())) + ); + + // The wrapper installs the post-transaction hook. let transaction = &fire_block.transaction_traces[0]; assert!( transaction.calls[0] @@ -91,7 +181,7 @@ fn post_block_changes_follow_the_withdrawals() { changes, vec![ (RECIPIENT, U256::ZERO, gwei, Reason::Withdrawal), - (RECIPIENT, U256::ZERO, gwei, POST_BLOCK_REASON), + (POST_BLOCK_MARKER, U256::ZERO, gwei, POST_BLOCK_REASON), ] ); assert!(fire_block.balance_changes[0].ordinal < fire_block.balance_changes[1].ordinal); @@ -102,8 +192,8 @@ fn value(value: Option<&BigInt>) -> U256 { value.map(|value| U256::from_be_slice(&value.bytes)).unwrap_or_default() } -/// Chain hooks that mark each transaction and report [`RECIPIENT`]'s change across the inner -/// finish. +/// Chain hooks that mark each transaction and report [`RECIPIENT`]'s balance across the inner +/// finish as a change of [`POST_BLOCK_MARKER`]. #[derive(Debug, Default, Clone, Copy)] struct TestHooks; @@ -126,13 +216,17 @@ impl PostTxExtras for TestHooks { fn capture_post_block( &self, evm: &mut E, - _block_number: u64, - _chain_id: u64, + block: &BlockFees, ) -> Option> { + CAPTURED_BLOCK.set(Some(( + block.block_number(), + block.coinbase(), + block.chain_id(), + block.spec(), + ))); let balance = evm .account_info(&RECIPIENT) - .ok() - .flatten() + .expect("reading the recipient") .map(|info| info.balance) .unwrap_or_default(); Some(Box::new(RecipientChange { balance })) @@ -152,7 +246,7 @@ impl PostBlockChanges for RecipientChange { .and_then(|account| account.info.as_ref()) .map(|info| info.balance) .unwrap_or_default(); - tracer.on_balance_change(RECIPIENT, self.balance, balance, POST_BLOCK_REASON); + tracer.on_balance_change(POST_BLOCK_MARKER, self.balance, balance, POST_BLOCK_REASON); } } diff --git a/crates/firehose/src/executor.rs b/crates/firehose/src/executor.rs index cf602a3f85d..f3e7ffea825 100644 --- a/crates/firehose/src/executor.rs +++ b/crates/firehose/src/executor.rs @@ -4,8 +4,8 @@ //! //! * [`FirehoseWrappedExecutor`] — a thin [`BlockExecutor`] wrapper that fires Firehose tracer //! hooks (`on_system_call_start/end`, `on_tx_start/end`, post-tx balance changes, withdrawal -//! balance changes) around a delegate executor, and installs a [`FirehoseInspector`] on the -//! delegate's EVM for everything that happens inside the EVM. +//! balance changes, chain post-block changes) around a delegate executor, and installs a +//! [`FirehoseInspector`] on the delegate's EVM for everything that happens inside the EVM. //! //! * [`FirehoseBlockExecutor`] — the pipeline [`Executor`] used by staged sync. It constructs a //! [`FirehoseWrappedExecutor`] per block and defers the end-of-block flush until the caller @@ -13,7 +13,8 @@ //! //! * [`FirehoseEvmConfig`] — a [`ConfigureEvm`] wrapper that routes `batch_executor` through //! [`FirehoseBlockExecutor`] while leaving every other method untouched (live path wraps the -//! executor explicitly at its call site). +//! executor explicitly at its call site). Both paths install the wrapped configuration's +//! [`FirehoseLiveHooks`]. //! //! ## Post-validation flush deferral (pipeline path) //! @@ -96,14 +97,20 @@ pub trait PostTxExtras { /// Snapshots, before the inner executor's `finish`, what the chain's own post-block changes /// will write outside the EVM, where the inspector cannot see them. /// - /// `evm` reads the state after the block's last transaction. The wrapper calls - /// [`PostBlockChanges::emit`] on the result after `finish`, after the withdrawal balance - /// changes. The default captures nothing, so Ethereum emits nothing extra. + /// `evm` reads the state after the block's last transaction. Only read from it, through + /// [`reth_evm::Evm::account_info`], which records nothing in the block access list. `block` + /// holds the block's number, coinbase, spec and chain id. The default captures nothing, so + /// Ethereum emits nothing extra. + /// + /// The wrapper calls [`PostBlockChanges::emit`] on the result after `finish`, as the block's + /// last changes: after the post-execution system calls and the withdrawal balance changes, + /// whatever order the chain's `finish` applies them in. The withdrawal changes are rebuilt + /// backwards from the final balances, as if the withdrawals were the last change to their + /// recipients, so these changes must not touch a withdrawal recipient's balance. fn capture_post_block( &self, _evm: &mut E, - _block_number: u64, - _chain_id: u64, + _block: &BlockFees, ) -> Option> { None } @@ -112,7 +119,9 @@ pub trait PostTxExtras { /// Chain-specific state changes that a block executor's `finish` makes outside the EVM, captured /// by [`PostTxExtras::capture_post_block`]. pub trait PostBlockChanges: Debug + Send { - /// Emits the changes to `tracer`, given the block's final state. + /// Emits the changes to `tracer`, given the block's final state. `state` holds only the + /// accounts the block changed: an account missing from it kept its balance from before the + /// block. fn emit(&self, tracer: &mut firehose_tracer::Tracer, state: &BundleState); } @@ -172,17 +181,18 @@ impl PreTxAdjust for NoPreTxAdjust { } } -/// Block-level values the per-transaction accounting needs, read once from the EVM environment. +/// Block-level values the per-transaction accounting and [`PostTxExtras::capture_post_block`] +/// need, read once from the EVM environment. #[derive(Debug, Clone)] pub struct BlockFees { coinbase: Address, - /// Number of the block, for [`PostTxExtras::capture_post_block`]. block_number: u64, base_fee: u64, /// EIP-4844 blob gas price, `None` before Cancun, matching Geth's omission of the field on /// pre-Cancun receipts. blob_gas_price: Option, version: evm2::Version, + spec: evm2::SpecId, } impl BlockFees { @@ -198,8 +208,29 @@ impl BlockFees { base_fee: evm_env.block_base_fee(), blob_gas_price, version, + spec, } } + + /// The block's beneficiary. + pub const fn coinbase(&self) -> Address { + self.coinbase + } + + /// The block's number. + pub const fn block_number(&self) -> u64 { + self.block_number + } + + /// The chain id the block executes on. + pub const fn chain_id(&self) -> u64 { + self.version.chain_id + } + + /// The spec the block executes under. + pub const fn spec(&self) -> evm2::SpecId { + self.spec + } } /// A [`BlockExecutor`] wrapper that fires Firehose tracer hooks around a delegate executor. @@ -487,11 +518,7 @@ where /// Runs the chain's [`PostTxExtras::capture_post_block`] against the state after the block's /// last transaction. fn capture_post_block(&mut self) -> Option> { - self.extras.capture_post_block( - self.inner.evm_mut(), - self.fees.block_number, - self.fees.version.chain_id, - ) + self.extras.capture_post_block(self.inner.evm_mut(), &self.fees) } } @@ -618,10 +645,7 @@ where let finished = inner.finish_with_block_access_list(); inspector.tracer_mut().on_system_call_end(); let (output, bal) = finished?; - emit_withdrawal_balance_changes(&inspector, withdrawals.as_ref(), &output.state); - if let Some(post_block) = post_block { - post_block.emit(&mut inspector.tracer_mut(), &output.state); - } + emit_post_finish_changes(&inspector, withdrawals.as_ref(), post_block, &output.state); Ok((output, bal)) } @@ -635,14 +659,26 @@ where let finished = inner.finish_with_prepared_block_access_list(); inspector.tracer_mut().on_system_call_end(); let (output, bal) = finished?; - emit_withdrawal_balance_changes(&inspector, withdrawals.as_ref(), &output.state); - if let Some(post_block) = post_block { - post_block.emit(&mut inspector.tracer_mut(), &output.state); - } + emit_post_finish_changes(&inspector, withdrawals.as_ref(), post_block, &output.state); Ok((output, bal)) } } +/// Emits the block-level changes the inner finish made outside the EVM, once the post-execution +/// system-call window has closed: the withdrawal balance changes, then the chain's post-block +/// changes. +fn emit_post_finish_changes>( + inspector: &FirehoseInspector, + withdrawals: Option<&Withdrawals>, + post_block: Option>, + state: &BundleState, +) { + emit_withdrawal_balance_changes(inspector, withdrawals, state); + if let Some(post_block) = post_block { + post_block.emit(&mut inspector.tracer_mut(), state); + } +} + /// Emits EIP-4895 withdrawal balance changes once the post-execution system-call window has /// closed, so they land in `block.balance_changes`. /// @@ -1192,6 +1228,9 @@ fn withdrawal_balance_events( /// A [`ConfigureEvm`] wrapper that routes `batch_executor` through [`FirehoseBlockExecutor`]. /// +/// The wrapped configuration's [`FirehoseLiveHooks`] drive both paths: the engine path through +/// this type's own [`FirehoseLiveHooks`] impl, and the pipeline through [`LiveChainHooks`]. +/// /// Every other method forwards to the wrapped config, except /// [`ConfigureEvm::reuses_prewarm_results`], which keeps its `false` default: committing a /// prewarmed result skips execution, so the tracer would not see that transaction.