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;