From fcaf68d30d04702b566cc89d11f02f81cb445ec5 Mon Sep 17 00:00:00 2001 From: valvecitydev Date: Wed, 11 Nov 2026 18:49:22 -0600 Subject: [PATCH] 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;