reth_rpc/

trace.rs

use alloy_consensus::{constants::ETH_TO_WEI, BlockHeader as _};
use alloy_eips::{BlockId, BlockNumHash};
use alloy_primitives::{
    map::{HashMap, HashSet},
    Address, BlockHash, Bytes, B256, U256,
};
use alloy_rpc_types_eth::{
    state::{EvmOverrides, StateOverride},
    BlockOverrides, Index,
};
use alloy_rpc_types_trace::{
    filter::TraceFilter,
    opcode::{BlockOpcodeGas, TransactionOpcodeGas},
    parity::*,
    tracerequest::TraceCallRequest,
};
use evm2_inspectors::{
    opcode::OpcodeGasInspector,
    storage::StorageInspector,
    tracing::{TracingInspector, TracingInspectorConfig},
};
use futures::{FutureExt, StreamExt};
use jsonrpsee::core::RpcResult;
use reth_chainspec::{ChainSpecProvider, EthereumHardforks};
use reth_evm::ConfigureEvm;
use reth_primitives_traits::{BlockBody, BlockHeader};
use reth_rpc_api::TraceApiServer;
use reth_rpc_convert::RpcTxReq;
use reth_rpc_eth_api::{
    helpers::{LoadTransaction, Trace, TraceExt},
    FromEthApiError, RpcNodeCore,
};
use reth_rpc_eth_types::{error::EthApiError, utils::CallManyBudget, EthConfig};
use reth_storage_api::{BlockNumReader, BlockReader};
use reth_tasks::{cancel::is_cancelled, pool::BlockingTaskGuard};
use reth_transaction_pool::{PoolPooledTx, PoolTransaction, TransactionPool};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use tokio::sync::{AcquireError, OwnedSemaphorePermit};

/// Maximum number of `trace_filter` blocks replayed concurrently.
const TRACE_FILTER_BLOCK_BUFFER_SIZE: usize = 4;
/// Number of blocks fetched per provider range read in `trace_filter`.
const TRACE_FILTER_FETCH_CHUNK_SIZE: usize = 16;

/// `trace` API implementation.
///
/// This type provides the functionality for handling `trace` related requests.
pub struct TraceApi<Eth> {
    inner: Arc<TraceApiInner<Eth>>,
}

// === impl TraceApi ===

impl<Eth> TraceApi<Eth> {
    /// Create a new instance of the [`TraceApi`]
    pub fn new(
        eth_api: Eth,
        blocking_task_guard: BlockingTaskGuard,
        eth_config: EthConfig,
    ) -> Self {
        let inner = Arc::new(TraceApiInner { eth_api, blocking_task_guard, eth_config });
        Self { inner }
    }

    /// Acquires a permit to execute a tracing call.
    async fn acquire_trace_permit(
        &self,
    ) -> std::result::Result<OwnedSemaphorePermit, AcquireError> {
        self.inner.blocking_task_guard.clone().acquire_owned().await
    }

    /// Access the underlying `Eth` API.
    pub fn eth_api(&self) -> &Eth {
        &self.inner.eth_api
    }
}

impl<Eth: RpcNodeCore> TraceApi<Eth> {
    /// Access the underlying provider.
    pub fn provider(&self) -> &Eth::Provider {
        self.inner.eth_api.provider()
    }
}

// === impl TraceApi === //

impl<Eth> TraceApi<Eth>
where
    // tracing methods do _not_ read from mempool, hence no `LoadBlock` trait
    // bound
    Eth: Trace + LoadTransaction,
{
    /// Executes the given call and returns a number of possible traces for it.
    pub async fn trace_call(
        &self,
        trace_request: TraceCallRequest<RpcTxReq<Eth::NetworkTypes>>,
    ) -> Result<TraceResults, Eth::Error> {
        let at = trace_request.block_id.unwrap_or_default();
        let config = TracingInspectorConfig::from_parity_config(&trace_request.trace_types);
        let overrides =
            EvmOverrides::new(trace_request.state_overrides, trace_request.block_overrides);
        let this = self.clone();
        self.eth_api()
            .spawn_with_call_at(trace_request.call, at, overrides, move |db, evm_env, tx_env| {
                let (inspector, res) = this.eth_api().inspect(
                    &mut *db,
                    evm_env,
                    &tx_env,
                    TracingInspector::new(config),
                )?;
                let trace_res = inspector
                    .into_parity_builder()
                    .into_trace_results_with_state(&res, &trace_request.trace_types, &mut *db)
                    .map_err(Eth::Error::from_eth_err)?;
                Ok(trace_res)
            })
            .boxed()
            .await
    }

    /// Traces a call to `eth_sendRawTransaction` without making the call, returning the traces.
    pub async fn trace_raw_transaction(
        &self,
        tx: Bytes,
        trace_types: HashSet<TraceType>,
        block_id: Option<BlockId>,
    ) -> Result<TraceResults, Eth::Error> {
        let tx = self
            .eth_api()
            .recover_raw_transaction::<PoolPooledTx<Eth::Pool>>(&tx)?
            .map(<Eth::Pool as TransactionPool>::Transaction::pooled_into_consensus);

        let (evm_env, at) = self.eth_api().evm_env_at(block_id.unwrap_or_default()).await?;
        let config = TracingInspectorConfig::from_parity_config(&trace_types);

        let tx_env = self.eth_api().evm_config().tx_env(tx);
        self.eth_api()
            .spawn_trace_at_with_state(
                evm_env,
                tx_env,
                config,
                at,
                move |inspector, res, mut db| {
                    inspector
                        .into_parity_builder()
                        .into_trace_results_with_state(&res, &trace_types, &mut db)
                        .map_err(Eth::Error::from_eth_err)
                },
            )
            .await
    }

    /// Performs multiple call traces on top of the same block. Defaults to the latest block when
    /// no block is specified. Each call is executed with the preceding calls applied first.
    ///
    /// Note: Allows tracing dependent transactions, hence all transactions are traced in sequence
    pub async fn trace_call_many(
        &self,
        calls: Vec<(RpcTxReq<Eth::NetworkTypes>, HashSet<TraceType>)>,
        block_id: Option<BlockId>,
    ) -> Result<Vec<TraceResults>, Eth::Error> {
        let mut budget = CallManyBudget::new(calls.len(), self.eth_api().call_gas_limit())?;
        let at = block_id.unwrap_or_default();
        let (evm_env, at) = self.eth_api().evm_env_at(at).await?;

        // execute all transactions on top of each other and record the traces
        self.eth_api()
            .spawn_with_state_at_block(at, move |eth_api, mut db| {
                let mut results = Vec::with_capacity(calls.len());
                let mut calls = calls.into_iter().peekable();

                while let Some((call, trace_types)) = calls.next() {
                    if is_cancelled() {
                        return Err(EthApiError::InternalEthError.into())
                    }
                    let (evm_env, mut tx_env) = eth_api.prepare_call_env(
                        evm_env.clone(),
                        call,
                        &mut db,
                        Default::default(),
                    )?;
                    budget.admit(&mut tx_env)?;
                    let config = TracingInspectorConfig::from_parity_config(&trace_types);
                    let (inspector, res) = eth_api
                        .inspect(&mut db, evm_env, &tx_env, TracingInspector::new(config))
                        .map_err(|err| budget.map_call_err(err))?;
                    budget.charge(&res.result)?;

                    let trace_res = inspector
                        .into_parity_builder()
                        .into_trace_results_with_state(&res, &trace_types, &mut db)
                        .map_err(Eth::Error::from_eth_err)?;

                    results.push(trace_res);

                    // need to apply the state changes of this call before executing the
                    // next call
                    if calls.peek().is_some() {
                        db.commit_source(&res.pending_state)
                    }
                }

                Ok(results)
            })
            .await
    }

    /// Replays a transaction, returning the traces or `None` if the transaction does not exist.
    pub async fn replay_transaction(
        &self,
        hash: B256,
        trace_types: HashSet<TraceType>,
    ) -> Result<Option<TraceResultsWithTransactionHash>, Eth::Error> {
        let config = TracingInspectorConfig::from_parity_config(&trace_types);
        self.eth_api()
            .spawn_trace_transaction_in_block(hash, config, move |_, inspector, res, mut db| {
                let trace_res = inspector
                    .into_parity_builder()
                    .into_trace_results_with_state(&res, &trace_types, &mut db)
                    .map_err(Eth::Error::from_eth_err)?;
                Ok(TraceResultsWithTransactionHash {
                    transaction_hash: hash,
                    full_trace: trace_res,
                })
            })
            .await
    }

    /// Returns the transaction trace at the given `traceAddress` path.
    ///
    /// An empty path selects the root. Returns `None` if the transaction or path does not exist.
    pub async fn trace_get(
        &self,
        hash: B256,
        indices: Vec<usize>,
    ) -> Result<Option<LocalizedTransactionTrace>, Eth::Error> {
        self.eth_api()
            .spawn_trace_transaction_in_block(
                hash,
                TracingInspectorConfig::default_parity(),
                move |tx_info, inspector, _, _| {
                    Ok(inspector
                        .into_parity_builder()
                        .into_localized_transaction_traces_iter(tx_info)
                        .find(|trace| trace.trace.trace_address == indices))
                },
            )
            .await
            .map(Option::flatten)
    }

    /// Returns the transaction trace at the given flat index, unlike [`Self::trace_get`], which
    /// selects a `traceAddress` path.
    ///
    /// Returns `None` if the trace object at that index does not exist
    pub async fn trace_get_index(
        &self,
        hash: B256,
        index: usize,
    ) -> Result<Option<LocalizedTransactionTrace>, Eth::Error> {
        self.eth_api()
            .spawn_trace_transaction_in_block(
                hash,
                TracingInspectorConfig::default_parity(),
                move |tx_info, inspector, _, _| {
                    Ok(inspector
                        .into_parity_builder()
                        .into_localized_transaction_traces_iter(tx_info)
                        .nth(index))
                },
            )
            .await
            .map(Option::flatten)
    }

    /// Returns all traces for the given transaction hash
    pub async fn trace_transaction(
        &self,
        hash: B256,
    ) -> Result<Option<Vec<LocalizedTransactionTrace>>, Eth::Error> {
        self.eth_api()
            .spawn_trace_transaction_in_block(
                hash,
                TracingInspectorConfig::default_parity(),
                move |tx_info, inspector, _, _| {
                    let traces =
                        inspector.into_parity_builder().into_localized_transaction_traces(tx_info);
                    Ok(traces)
                },
            )
            .await
    }

    /// Returns all opcodes with their count and combined gas usage for the given transaction in no
    /// particular order.
    pub async fn trace_transaction_opcode_gas(
        &self,
        tx_hash: B256,
    ) -> Result<Option<TransactionOpcodeGas>, Eth::Error> {
        self.eth_api()
            .spawn_trace_transaction_in_block_with_inspector(
                tx_hash,
                OpcodeGasInspector::default(),
                move |_tx_info, inspector, _res, _| {
                    let trace = TransactionOpcodeGas {
                        transaction_hash: tx_hash,
                        opcode_gas: inspector.opcode_gas_iter().collect(),
                    };
                    Ok(trace)
                },
            )
            .await
    }

    /// Calculates the base block reward for the given block:
    ///
    /// - the genesis block is not mined, so no block rewards are given
    /// - if Paris hardfork is activated, no block rewards are given
    /// - if Paris hardfork is not activated, calculate block rewards with block number only
    fn calculate_base_block_reward<H: BlockHeader>(&self, header: &H) -> Option<u128> {
        if header.number() == 0 {
            return None
        }

        base_block_reward(self.provider().chain_spec(), header.number())
    }

    /// Extracts the reward traces for the given block:
    ///  - block reward
    ///  - uncle rewards
    fn extract_reward_traces<H: BlockHeader>(
        &self,
        header: &H,
        block_hash: BlockHash,
        ommers: Option<&[H]>,
        base_block_reward: u128,
    ) -> Vec<LocalizedTransactionTrace> {
        let ommers_cnt = ommers.map(|o| o.len()).unwrap_or_default();
        let mut traces = Vec::with_capacity(ommers_cnt + 1);

        let block = BlockNumHash::new(header.number(), block_hash);
        let block_reward = block_reward(base_block_reward, ommers_cnt);
        traces.push(
            RewardAction {
                author: header.beneficiary(),
                reward_type: RewardType::Block,
                value: U256::from(block_reward),
            }
            .into_localized_trace(block),
        );

        let Some(ommers) = ommers else { return traces };

        for uncle in ommers {
            let uncle_reward = ommer_reward(base_block_reward, header.number(), uncle.number());
            traces.push(
                RewardAction {
                    author: uncle.beneficiary(),
                    reward_type: RewardType::Uncle,
                    value: U256::from(uncle_reward),
                }
                .into_localized_trace(block),
            );
        }
        traces
    }
}

impl<Eth> TraceApi<Eth>
where
    // tracing methods read from mempool, hence `LoadBlock` trait bound via
    // `TraceExt`
    Eth: TraceExt,
{
    /// Returns all transaction traces that match the given filter.
    ///
    /// This is similar to [`Self::trace_block`] but only returns traces for transactions that match
    /// the filter. Omitted range bounds default to the latest block.
    pub async fn trace_filter(
        &self,
        filter: TraceFilter,
    ) -> Result<Vec<LocalizedTransactionTrace>, Eth::Error> {
        // We'll reuse the matcher across multiple blocks that are traced in parallel
        let matcher = Arc::new(filter.matcher());
        let TraceFilter { from_block, to_block, mut after, count, .. } = filter;

        let latest_block = self.provider().best_block_number().map_err(Eth::Error::from_eth_err)?;
        let start = from_block.unwrap_or(latest_block);
        if start > latest_block {
            // can't trace that range
            return Err(EthApiError::HeaderNotFound(start.into()).into());
        }
        let end = to_block.unwrap_or(latest_block);
        if end > latest_block {
            return Err(EthApiError::HeaderNotFound(end.into()).into());
        }

        // Check if the requested range overlaps with pruned history (EIP-4444)
        let earliest_block =
            self.provider().earliest_block_number().map_err(Eth::Error::from_eth_err)?;
        if start < earliest_block {
            return Err(EthApiError::PrunedHistoryUnavailable {
                requested: start,
                earliest_available: earliest_block,
            }
            .into());
        }

        if start > end {
            return Err(EthApiError::InvalidParams(
                "invalid parameters: fromBlock cannot be greater than toBlock".to_string(),
            )
            .into())
        }

        // ensure that the range is not too large, since every block in the range may be replayed
        let distance = end.saturating_sub(start);
        if distance > self.inner.eth_config.max_trace_filter_blocks {
            return Err(EthApiError::InvalidParams(format!(
                "Block range too large; currently limited to {} blocks",
                self.inner.eth_config.max_trace_filter_blocks
            ))
            .into())
        }

        let mut all_traces = Vec::new();
        let block_buffer_size =
            self.inner.eth_config.max_tracing_requests.clamp(1, TRACE_FILTER_BLOCK_BUFFER_SIZE);
        let mut include_reward_traces = true;

        for chunk_start in (start..=end).step_by(TRACE_FILTER_FETCH_CHUNK_SIZE) {
            let chunk_end = (chunk_start + TRACE_FILTER_FETCH_CHUNK_SIZE as u64 - 1).min(end);

            let blocks = self
                .eth_api()
                .spawn_blocking_io(move |this| {
                    let blocks = this
                        .provider()
                        .recovered_block_range(chunk_start..=chunk_end)
                        .map_err(Eth::Error::from_eth_err)?;

                    Ok(blocks.into_iter().map(Arc::new).collect::<Vec<_>>())
                })
                .await?;

            let mut block_replays = futures::stream::iter(blocks)
                .map(|block| {
                    let this = self.clone();
                    let matcher = matcher.clone();

                    let block_hash = block.hash();

                    async move {
                        let permit = this.acquire_trace_permit().await;
                        let traces = this
                            .eth_api()
                            .trace_block_until(
                                block_hash.into(),
                                Some(block.clone()),
                                None,
                                TracingInspectorConfig::default_parity(),
                                move |tx_info, ctx| {
                                    // Keep the block replay permit inside the spawned replay task.
                                    let _block_replay_permit = &permit;
                                    let mut traces = ctx
                                        .take_inspector()
                                        .into_parity_builder()
                                        .into_localized_transaction_traces(tx_info);
                                    traces.retain(|trace| matcher.matches(&trace.trace));
                                    Ok(Some(traces))
                                },
                            )
                            .await?;

                        Ok::<_, Eth::Error>((block, traces))
                    }
                })
                .buffered(block_buffer_size);

            while let Some(block_replay) = block_replays.next().await {
                let (block, traces) = block_replay?;
                let reward_traces = if include_reward_traces {
                    if let Some(base_block_reward) =
                        self.calculate_base_block_reward(block.header())
                    {
                        self.extract_reward_traces(
                            block.header(),
                            block.hash(),
                            block.body().ommers(),
                            base_block_reward,
                        )
                        .into_iter()
                        .filter(|trace| matcher.matches(&trace.trace))
                        .collect::<Vec<_>>()
                    } else {
                        // Blocks are processed in ascending order, so once a historical range
                        // reaches post-Paris blocks, later blocks in the range have no rewards.
                        // The genesis block has no reward, but later pre-Paris blocks do.
                        include_reward_traces = block.number() == 0;
                        Vec::new()
                    }
                } else {
                    Vec::new()
                };

                if let Some(traces) = traces {
                    all_traces.extend(traces.into_iter().flatten().flatten());
                }
                all_traces.extend(reward_traces);

                if let Some(traces) =
                    apply_trace_filter_pagination(&mut all_traces, &mut after, count)
                {
                    return Ok(traces)
                }
            }
        }

        // If `after` is greater than or equal to the number of matched traces, it returns an
        // empty array.
        if let Some(cutoff) = after.map(|a| a as usize) &&
            cutoff >= all_traces.len()
        {
            return Ok(vec![])
        }

        Ok(all_traces)
    }

    /// Returns traces created at given block.
    pub async fn trace_block(
        &self,
        block_id: BlockId,
    ) -> Result<Option<Vec<LocalizedTransactionTrace>>, Eth::Error> {
        let Some(block) = self.eth_api().recovered_block(block_id).await? else {
            return Err(EthApiError::HeaderNotFound(block_id).into());
        };

        let mut traces = self
            .eth_api()
            .trace_block_with(
                block_id,
                Some(block.clone()),
                TracingInspectorConfig::default_parity(),
                |tx_info, ctx| {
                    let traces = ctx
                        .take_inspector()
                        .into_parity_builder()
                        .into_localized_transaction_traces(tx_info);
                    Ok(traces)
                },
            )
            .await?
            .map(|traces| traces.into_iter().flatten().collect::<Vec<_>>());

        if let Some(traces) = traces.as_mut() &&
            let Some(base_block_reward) = self.calculate_base_block_reward(block.header())
        {
            traces.extend(self.extract_reward_traces(
                block.header(),
                block.hash(),
                block.body().ommers(),
                base_block_reward,
            ));
        }

        Ok(traces)
    }

    /// Replays all transactions in a block
    pub async fn replay_block_transactions(
        &self,
        block_id: BlockId,
        trace_types: HashSet<TraceType>,
    ) -> Result<Option<Vec<TraceResultsWithTransactionHash>>, Eth::Error> {
        let Some(block) = self.eth_api().recovered_block(block_id).await? else {
            return Err(EthApiError::HeaderNotFound(block_id).into());
        };

        self.eth_api()
            .trace_block_with(
                block_id,
                Some(block),
                TracingInspectorConfig::from_parity_config(&trace_types),
                move |tx_info, ctx| {
                    let full_trace = ctx
                        .inspector
                        .into_parity_builder()
                        .into_trace_results_with_state(ctx.result, &trace_types, ctx.db)
                        .map_err(Eth::Error::from_eth_err)?;

                    let trace = TraceResultsWithTransactionHash {
                        transaction_hash: tx_info.hash.expect("tx hash is set"),
                        full_trace,
                    };
                    Ok(trace)
                },
            )
            .await
    }

    /// Returns the opcodes of all transactions in the given block.
    ///
    /// This is the same as [`Self::trace_transaction_opcode_gas`] but for all transactions in a
    /// block.
    pub async fn trace_block_opcode_gas(
        &self,
        block_id: BlockId,
    ) -> Result<Option<BlockOpcodeGas>, Eth::Error> {
        let Some(block) = self.eth_api().recovered_block(block_id).await? else {
            return Err(EthApiError::HeaderNotFound(block_id).into());
        };

        let Some(transactions) = self
            .eth_api()
            .trace_block_inspector(
                block_id,
                Some(block.clone()),
                OpcodeGasInspector::default,
                move |tx_info, ctx| {
                    let trace = TransactionOpcodeGas {
                        transaction_hash: tx_info.hash.expect("tx hash is set"),
                        opcode_gas: ctx.inspector.opcode_gas_iter().collect(),
                    };
                    Ok(trace)
                },
            )
            .await?
        else {
            return Ok(None);
        };

        Ok(Some(BlockOpcodeGas {
            block_hash: block.hash(),
            block_number: block.number(),
            transactions,
        }))
    }

    /// Returns all storage slots accessed during transaction execution along with their access
    /// counts.
    pub async fn trace_block_storage_access(
        &self,
        block_id: BlockId,
    ) -> Result<Option<BlockStorageAccess>, Eth::Error> {
        let Some(block) = self.eth_api().recovered_block(block_id).await? else {
            return Err(EthApiError::HeaderNotFound(block_id).into());
        };

        let Some(transactions) = self
            .eth_api()
            .trace_block_inspector(
                block_id,
                Some(block.clone()),
                StorageInspector::default,
                move |tx_info, ctx| {
                    let unique_loads = ctx.inspector.unique_loads();
                    let warm_loads = ctx.inspector.warm_loads();
                    let trace = TransactionStorageAccess {
                        transaction_hash: tx_info.hash.expect("tx hash is set"),
                        storage_access: ctx.take_inspector().into_accessed_slots(),
                        unique_loads,
                        warm_loads,
                    };
                    Ok(trace)
                },
            )
            .await?
        else {
            return Ok(None);
        };

        Ok(Some(BlockStorageAccess {
            block_hash: block.hash(),
            block_number: block.number(),
            transactions,
        }))
    }
}

fn apply_trace_filter_pagination(
    all_traces: &mut Vec<LocalizedTransactionTrace>,
    after: &mut Option<u64>,
    count: Option<u64>,
) -> Option<Vec<LocalizedTransactionTrace>> {
    // Skips the first `after` number of matching traces.
    if let Some(cutoff) = after.map(|a| a as usize) &&
        cutoff < all_traces.len()
    {
        all_traces.drain(..cutoff);
        // we removed the first `after` traces
        *after = None;
    }

    // Return at most `count` traces after `after` has been consumed.
    if after.is_none() &&
        let Some(count) = count
    {
        let count = count as usize;
        if count < all_traces.len() {
            all_traces.truncate(count);
            return Some(std::mem::take(all_traces))
        }
    }

    None
}

impl<Eth> TraceApiServer<RpcTxReq<Eth::NetworkTypes>> for TraceApi<Eth>
where
    Eth: TraceExt,
{
    /// Executes the given call and returns a number of possible traces for it.
    ///
    /// Handler for `trace_call`
    async fn trace_call(
        &self,
        call: RpcTxReq<Eth::NetworkTypes>,
        trace_types: HashSet<TraceType>,
        block_id: Option<BlockId>,
        state_overrides: Option<StateOverride>,
        block_overrides: Option<Box<BlockOverrides>>,
    ) -> RpcResult<TraceResults> {
        let _permit = self.acquire_trace_permit().await;
        let request =
            TraceCallRequest { call, trace_types, block_id, state_overrides, block_overrides };
        Self::trace_call(self, request).await.map_err(Into::into)
    }

    /// Handler for `trace_callMany`
    async fn trace_call_many(
        &self,
        calls: Vec<(RpcTxReq<Eth::NetworkTypes>, HashSet<TraceType>)>,
        block_id: Option<BlockId>,
    ) -> RpcResult<Vec<TraceResults>> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_call_many(self, calls, block_id).await.map_err(Into::into)
    }

    /// Handler for `trace_rawTransaction`
    async fn trace_raw_transaction(
        &self,
        data: Bytes,
        trace_types: HashSet<TraceType>,
        block_id: Option<BlockId>,
    ) -> RpcResult<TraceResults> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_raw_transaction(self, data, trace_types, block_id).await.map_err(Into::into)
    }

    /// Handler for `trace_replayBlockTransactions`
    async fn replay_block_transactions(
        &self,
        block_id: BlockId,
        trace_types: HashSet<TraceType>,
    ) -> RpcResult<Option<Vec<TraceResultsWithTransactionHash>>> {
        let _permit = self.acquire_trace_permit().await;
        Self::replay_block_transactions(self, block_id, trace_types).await.map_err(Into::into)
    }

    /// Handler for `trace_replayTransaction`
    async fn replay_transaction(
        &self,
        transaction: B256,
        trace_types: HashSet<TraceType>,
    ) -> RpcResult<Option<TraceResultsWithTransactionHash>> {
        let _permit = self.acquire_trace_permit().await;
        Self::replay_transaction(self, transaction, trace_types).await.map_err(Into::into)
    }

    /// Handler for `trace_block`
    async fn trace_block(
        &self,
        block_id: BlockId,
    ) -> RpcResult<Option<Vec<LocalizedTransactionTrace>>> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_block(self, block_id).await.map_err(Into::into)
    }

    /// Handler for `trace_filter`
    ///
    /// This is similar to `eth_getLogs` but for traces.
    ///
    /// # Limitations
    /// This currently requires block filter fields, since reth does not have address indices yet.
    async fn trace_filter(&self, filter: TraceFilter) -> RpcResult<Vec<LocalizedTransactionTrace>> {
        Self::trace_filter(self, filter).await.map_err(Into::into)
    }

    /// Returns transaction trace at given index.
    /// Handler for `trace_get`
    async fn trace_get(
        &self,
        hash: B256,
        indices: Vec<Index>,
    ) -> RpcResult<Option<LocalizedTransactionTrace>> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_get(self, hash, indices.into_iter().map(Into::into).collect())
            .await
            .map_err(Into::into)
    }

    /// Handler for `trace_transaction`
    async fn trace_transaction(
        &self,
        hash: B256,
    ) -> RpcResult<Option<Vec<LocalizedTransactionTrace>>> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_transaction(self, hash).await.map_err(Into::into)
    }

    /// Handler for `trace_transactionOpcodeGas`
    async fn trace_transaction_opcode_gas(
        &self,
        tx_hash: B256,
    ) -> RpcResult<Option<TransactionOpcodeGas>> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_transaction_opcode_gas(self, tx_hash).await.map_err(Into::into)
    }

    /// Handler for `trace_blockOpcodeGas`
    async fn trace_block_opcode_gas(&self, block_id: BlockId) -> RpcResult<Option<BlockOpcodeGas>> {
        let _permit = self.acquire_trace_permit().await;
        Self::trace_block_opcode_gas(self, block_id).await.map_err(Into::into)
    }
}

impl<Eth> std::fmt::Debug for TraceApi<Eth> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("TraceApi").finish_non_exhaustive()
    }
}
impl<Eth> Clone for TraceApi<Eth> {
    fn clone(&self) -> Self {
        Self { inner: Arc::clone(&self.inner) }
    }
}

struct TraceApiInner<Eth> {
    /// Access to commonly used code of the `eth` namespace
    eth_api: Eth,
    // restrict the number of concurrent calls to `trace_*`
    blocking_task_guard: BlockingTaskGuard,
    // eth config settings
    eth_config: EthConfig,
}

pub(super) fn base_block_reward(spec: impl EthereumHardforks, block_number: u64) -> Option<u128> {
    if spec.is_paris_active_at_block(block_number) {
        return None
    }
    Some(base_block_reward_pre_merge(spec, block_number))
}

fn base_block_reward_pre_merge(spec: impl EthereumHardforks, block_number: u64) -> u128 {
    if spec.is_constantinople_active_at_block(block_number) {
        ETH_TO_WEI * 2
    } else if spec.is_byzantium_active_at_block(block_number) {
        ETH_TO_WEI * 3
    } else {
        ETH_TO_WEI * 5
    }
}

pub(super) const fn block_reward(base_block_reward: u128, ommers: usize) -> u128 {
    base_block_reward + (base_block_reward >> 5) * ommers as u128
}

pub(super) const fn ommer_reward(
    base_block_reward: u128,
    block_number: u64,
    ommer_block_number: u64,
) -> u128 {
    ((8 + ommer_block_number - block_number) as u128 * base_block_reward) >> 3
}

/// Response type for storage tracing that contains all accessed storage slots
/// for a transaction.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TransactionStorageAccess {
    /// Hash of the transaction
    pub transaction_hash: B256,
    /// Tracks storage slots and access counter.
    pub storage_access: HashMap<Address, HashMap<B256, u64>>,
    /// Number of unique storage loads
    pub unique_loads: u64,
    /// Number of warm storage loads
    pub warm_loads: u64,
}

/// Response type for storage tracing that contains all accessed storage slots
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BlockStorageAccess {
    /// The block hash
    pub block_hash: BlockHash,
    /// The block's number
    pub block_number: u64,
    /// All executed transactions in the block in the order they were executed
    pub transactions: Vec<TransactionStorageAccess>,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::EthApiBuilder;
    use alloy_consensus::{Header, TxLegacy};
    use alloy_genesis::Genesis;
    use alloy_primitives::{bytes, Signature, TxKind};
    use alloy_rpc_types_eth::TransactionRequest;
    use reth_chain_state::CanonStateNotification;
    use reth_chainspec::ChainSpecBuilder;
    use reth_db_common::init::init_genesis;
    use reth_ethereum_primitives::{Block, BlockBody, TransactionSigned};
    use reth_evm_ethereum::EthEvmConfig;
    use reth_execution_types::{Chain, ExecutionOutcome};
    use reth_network_api::noop::NoopNetwork;
    use reth_primitives_traits::{Block as _, RecoveredBlock, SignerRecoverable};
    use reth_provider::{
        providers::BlockchainProvider,
        test_utils::{
            create_test_provider_factory_with_chain_spec, ExtendedAccount, MockEthProvider,
        },
        BlockWriter, StageCheckpointWriter,
    };
    use reth_rpc_eth_types::cache::cache_new_blocks_task;
    use reth_transaction_pool::test_utils::testing_pool;

    #[tokio::test]
    async fn trace_call_many_defaults_to_latest() {
        let provider = MockEthProvider::default();
        let target = Address::with_last_byte(0x42);
        // Return NUMBER as a 32-byte word.
        provider.add_account(
            target,
            ExtendedAccount::new(0, U256::ZERO).with_bytecode(bytes!("4360005260206000f3")),
        );
        let header = Header { number: 1, gas_limit: 30_000_000, ..Default::default() };
        provider.add_block(header.hash_slow(), Block { header, body: BlockBody::default() });
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        let api = TraceApi::new(eth_api, BlockingTaskGuard::new(1), EthConfig::default());
        let calls = vec![(TransactionRequest::default().to(target), HashSet::default())];

        let omitted = api.trace_call_many(calls.clone(), None).await.unwrap();
        let latest = api.trace_call_many(calls.clone(), Some(BlockId::latest())).await.unwrap();
        let request = serde_json::json!({
            "jsonrpc": "2.0", "id": 1, "method": "trace_callMany", "params": [calls.clone()],
        });
        let pending = api.trace_call_many(calls, Some(BlockId::pending())).await.unwrap();
        assert_eq!(omitted, latest);
        assert_ne!(omitted, pending);
        assert_eq!(U256::from_be_slice(&omitted[0].output), U256::ONE);
        assert_eq!(U256::from_be_slice(&pending[0].output), U256::from(2));

        let module = api.into_rpc();
        let (response, _) = module.raw_json_request(&request.to_string(), 1).await.unwrap();
        let response: serde_json::Value = serde_json::from_str(&response).unwrap();
        assert_eq!(response["result"], serde_json::to_value(latest).unwrap());
    }

    #[tokio::test]
    async fn trace_filter_defaults_to_latest() {
        let provider = MockEthProvider::default();
        for number in [1, 2] {
            let header = Header { number, gas_limit: 30_000_000, ..Default::default() };
            provider.add_block(header.hash_slow(), Block { header, body: BlockBody::default() });
        }
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        let api = TraceApi::new(
            eth_api,
            BlockingTaskGuard::new(1),
            EthConfig::default().max_trace_filter_blocks(1),
        );

        let omitted = api.trace_filter(TraceFilter::default()).await.unwrap();
        let latest =
            api.trace_filter(TraceFilter::default().from_block(2).to_block(2)).await.unwrap();
        assert_eq!(omitted, latest);
        assert!(api.trace_filter(TraceFilter::default().from_block(1).to_block(2)).await.is_ok());

        let module = api.into_rpc();
        let request = serde_json::json!({
            "jsonrpc": "2.0", "id": 1, "method": "trace_filter", "params": [{"toBlock": "0x1"}],
        });
        let (response, _) = module.raw_json_request(&request.to_string(), 1).await.unwrap();
        let response: serde_json::Value = serde_json::from_str(&response).unwrap();
        assert_eq!(
            response["error"],
            serde_json::json!({
                "code": -32602,
                "message": "invalid parameters: fromBlock cannot be greater than toBlock",
            })
        );
    }

    #[tokio::test]
    async fn trace_get_selects_tree_paths() {
        let provider = MockEthProvider::default();
        // The root calls 0x43 (which calls 0x44), then calls 0x45.
        for (address, code) in [
            (0x42, "60006000600060006000604361fffff15060006000600060006000604561fffff15000"),
            (0x43, "600060006000600060006044611000f15000"),
        ] {
            provider.add_account(
                Address::with_last_byte(address),
                ExtendedAccount::new(0, U256::ZERO).with_bytecode(code.parse().unwrap()),
            );
        }
        let tx = TransactionSigned::new_unhashed(
            TxLegacy {
                gas_limit: 500_000,
                to: TxKind::Call(Address::with_last_byte(0x42)),
                value: U256::ONE,
                ..Default::default()
            }
            .into(),
            Signature::test_signature(),
        );
        let hash = *tx.hash();
        let sender = tx.recover_signer().unwrap();
        provider.add_account(sender, ExtendedAccount::new(0, U256::from(1_000_000)));
        let parent = Header { gas_limit: 30_000_000, ..Default::default() };
        let parent_hash = parent.hash_slow();
        provider.add_header(parent_hash, parent);
        let block = Block {
            header: Header { parent_hash, number: 1, gas_limit: 30_000_000, ..Default::default() },
            body: BlockBody { transactions: vec![tx], ..Default::default() },
        };
        let block_hash = block.header.hash_slow();
        provider.add_block(block_hash, block.clone());
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        // MockEthProvider does not implement recovered_block, so seed the RPC cache.
        cache_new_blocks_task(
            eth_api.cache().clone(),
            futures::stream::iter([CanonStateNotification::Commit {
                new: Arc::new(Chain::new(
                    [RecoveredBlock::new_unhashed(block, vec![sender])],
                    ExecutionOutcome {
                        receipts: vec![vec![]],
                        first_block: 1,
                        ..Default::default()
                    },
                    Default::default(),
                )),
            }]),
        )
        .await;
        let api = TraceApi::new(eth_api, BlockingTaskGuard::new(1), EthConfig::default());
        let module = api.clone().into_rpc();
        let traces = api.trace_transaction(hash).await.unwrap().unwrap();
        let paths: Vec<_> = traces.iter().map(|trace| trace.trace.trace_address.clone()).collect();
        assert_eq!(paths, [vec![], vec![0], vec![0, 0], vec![1]]);
        for (path, expected) in [
            (vec![], Some(&traces[0])),
            (vec![0], Some(&traces[1])),
            (vec![0, 0], Some(&traces[2])),
            (vec![1], Some(&traces[3])),
            (vec![2], None),
            (vec![0, 1], None),
            (vec![1, 0], None),
        ] {
            let indices: Vec<_> = path.iter().map(|index| format!("0x{index:x}")).collect();
            let request = serde_json::json!({
                "jsonrpc": "2.0", "id": 1, "method": "trace_get", "params": [hash, indices],
            });
            let (response, _) = module.raw_json_request(&request.to_string(), 1).await.unwrap();
            let response: serde_json::Value = serde_json::from_str(&response).unwrap();
            assert!(response.get("error").is_none(), "{response}");
            assert_eq!(response["result"], serde_json::to_value(expected).unwrap());
        }
        assert!(api.trace_get(B256::ZERO, vec![]).await.unwrap().is_none());
        assert!(api.trace_get(B256::ZERO, vec![0, 0]).await.unwrap().is_none());
        assert_eq!(api.trace_get_index(hash, 2).await.unwrap().as_ref(), Some(&traces[2]));
    }

    #[tokio::test]
    async fn replay_missing_transaction_returns_null() {
        let provider = MockEthProvider::default();
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        let api = TraceApi::new(eth_api, BlockingTaskGuard::new(1), EthConfig::default());
        let module = api.into_rpc();
        for types in [serde_json::json!([]), serde_json::json!(["trace", "stateDiff", "vmTrace"])] {
            let request = serde_json::json!({
                "jsonrpc": "2.0",
                "id": 1,
                "method": "trace_replayTransaction",
                "params": [B256::with_last_byte(1), types],
            });
            let (response, _) = module.raw_json_request(&request.to_string(), 1).await.unwrap();
            let response: serde_json::Value = serde_json::from_str(&response).unwrap();
            assert_eq!(response, serde_json::json!({"jsonrpc": "2.0", "id": 1, "result": null}));
        }
    }

    #[tokio::test]
    async fn replay_transaction_includes_transaction_hash() {
        let provider = MockEthProvider::default();
        let tx = TransactionSigned::new_unhashed(
            TxLegacy {
                gas_limit: 21_000,
                to: TxKind::Call(Address::with_last_byte(0x42)),
                value: U256::ONE,
                ..Default::default()
            }
            .into(),
            Signature::test_signature(),
        );
        let hash = *tx.hash();
        let sender = tx.recover_signer().unwrap();
        provider.add_account(sender, ExtendedAccount::new(0, U256::from(1_000_000)));
        let parent = Header { gas_limit: 30_000_000, ..Default::default() };
        let parent_hash = parent.hash_slow();
        provider.add_header(parent_hash, parent);
        let block = Block {
            header: Header { parent_hash, number: 1, gas_limit: 30_000_000, ..Default::default() },
            body: BlockBody { transactions: vec![tx], ..Default::default() },
        };
        let block_hash = block.header.hash_slow();
        provider.add_block(block_hash, block.clone());
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        // MockEthProvider does not implement recovered_block, so seed the RPC cache.
        cache_new_blocks_task(
            eth_api.cache().clone(),
            futures::stream::iter([CanonStateNotification::Commit {
                new: Arc::new(Chain::new(
                    [RecoveredBlock::new_unhashed(block, vec![sender])],
                    ExecutionOutcome {
                        receipts: vec![vec![]],
                        first_block: 1,
                        ..Default::default()
                    },
                    Default::default(),
                )),
            }]),
        )
        .await;
        let api = TraceApi::new(eth_api, BlockingTaskGuard::new(1), EthConfig::default());
        let module = api.clone().into_rpc();
        for types in
            [HashSet::default(), HashSet::from_iter([TraceType::Trace, TraceType::StateDiff])]
        {
            let request = serde_json::json!({
                "jsonrpc": "2.0", "id": 1, "method": "trace_replayTransaction",
                "params": [hash, types],
            });
            let (response, _) = module.raw_json_request(&request.to_string(), 1).await.unwrap();
            let response: serde_json::Value = serde_json::from_str(&response).unwrap();
            assert!(response.get("error").is_none(), "{response}");
            assert_eq!(response["result"]["transactionHash"], serde_json::json!(hash));

            let block_replay =
                api.replay_block_transactions(block_hash.into(), types).await.unwrap().unwrap();
            assert_eq!(response["result"], serde_json::to_value(&block_replay[0]).unwrap());
        }
    }

    #[tokio::test]
    async fn genesis_block_has_no_reward_trace() {
        // Paris is not active at genesis, so blocks after genesis carry block rewards.
        let coinbase = Address::repeat_byte(0x11);
        let genesis = Genesis::default().with_gas_limit(30_000_000).with_coinbase(coinbase);
        let chain_spec = Arc::new(ChainSpecBuilder::mainnet().genesis(genesis).build());
        let factory = create_test_provider_factory_with_chain_spec(chain_spec);
        let genesis_hash = init_genesis(&factory).unwrap();
        let block = Block {
            header: Header {
                parent_hash: genesis_hash,
                number: 1,
                beneficiary: coinbase,
                gas_limit: 30_000_000,
                ..Default::default()
            },
            body: BlockBody::default(),
        };
        let provider_rw = factory.provider_rw().unwrap();
        provider_rw.insert_block(&block.seal_slow().try_recover().unwrap()).unwrap();
        provider_rw.update_pipeline_stages(1, false).unwrap();
        provider_rw.commit().unwrap();

        let provider = BlockchainProvider::new(factory).unwrap();
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        let api = TraceApi::new(eth_api, BlockingTaskGuard::new(1), EthConfig::default());

        assert_eq!(api.trace_block(0.into()).await.unwrap(), Some(vec![]));
        assert_eq!(
            trace_order(&api.trace_block(1.into()).await.unwrap().unwrap()),
            [(1, None, true)]
        );
        for (to_block, expected) in [(0, vec![]), (1, vec![(1, None, true)])] {
            let filter =
                TraceFilter { from_block: Some(0), to_block: Some(to_block), ..Default::default() };
            assert_eq!(trace_order(&api.trace_filter(filter).await.unwrap()), expected);
        }
    }

    fn localized_transaction_trace(
        block_number: u64,
        transaction_position: u64,
    ) -> LocalizedTransactionTrace {
        LocalizedTransactionTrace {
            block_hash: Some(B256::ZERO),
            block_number: Some(block_number),
            transaction_hash: Some(B256::ZERO),
            transaction_position: Some(transaction_position),
            trace: TransactionTrace::default(),
        }
    }

    fn localized_reward_trace(block_number: u64) -> LocalizedTransactionTrace {
        RewardAction { author: Address::ZERO, reward_type: RewardType::Block, value: U256::ZERO }
            .into_localized_trace(BlockNumHash::new(block_number, B256::ZERO))
    }

    fn trace_order(traces: &[LocalizedTransactionTrace]) -> Vec<(u64, Option<u64>, bool)> {
        traces
            .iter()
            .map(|trace| {
                (
                    trace.block_number.unwrap(),
                    trace.transaction_position,
                    trace.trace.action.is_reward(),
                )
            })
            .collect()
    }

    #[test]
    fn trace_filter_paginates_after_per_block_reward_order() {
        let mut all_traces = vec![
            localized_transaction_trace(1, 0),
            localized_reward_trace(1),
            localized_transaction_trace(2, 0),
            localized_reward_trace(2),
        ];

        let mut after = Some(1);
        let paginated =
            apply_trace_filter_pagination(&mut all_traces, &mut after, Some(1)).unwrap();

        assert_eq!(trace_order(&paginated), vec![(1, None, true)]);
    }

    #[tokio::test]
    async fn replay_block_vmtrace_includes_root_and_callcode_bytecode() {
        let provider = MockEthProvider::default();
        let target = Address::with_last_byte(0x42);
        let child = Address::with_last_byte(0x43);
        // Increment slot zero, CALLCODE the child, then return the incremented value.
        let root_code: Bytes =
            bytes!("60005460010160005560006000600060006000604361fffff25060005460005260206000f3");
        let child_code: Bytes = bytes!("60025000");
        provider.add_account(
            target,
            ExtendedAccount::new(0, U256::ZERO).with_bytecode(root_code.clone()),
        );
        provider.add_account(
            child,
            ExtendedAccount::new(0, U256::ZERO).with_bytecode(child_code.clone()),
        );
        let mut transactions = Vec::new();
        for nonce in 0..2 {
            let tx = TransactionSigned::new_unhashed(
                TxLegacy {
                    nonce,
                    gas_limit: 500_000,
                    to: TxKind::Call(target),
                    ..Default::default()
                }
                .into(),
                Signature::test_signature(),
            );
            provider.add_account(
                tx.recover_signer().unwrap(),
                ExtendedAccount::new(nonce, U256::from(1_000_000)),
            );
            transactions.push(tx);
        }
        let parent = Header { gas_limit: 30_000_000, ..Default::default() };
        let parent_hash = parent.hash_slow();
        provider.add_header(parent_hash, parent);
        let block = Block {
            header: Header { parent_hash, number: 1, gas_limit: 30_000_000, ..Default::default() },
            body: BlockBody { transactions, ..Default::default() },
        };
        let block_hash = block.header.hash_slow();
        let senders =
            block.body.transactions.iter().map(|tx| tx.recover_signer().unwrap()).collect();
        provider.add_block(block_hash, block.clone());
        let recovered = RecoveredBlock::new_unhashed(block, senders);
        let eth_api = EthApiBuilder::new(
            provider.clone(),
            testing_pool(),
            NoopNetwork::default(),
            EthEvmConfig::new(provider.chain_spec()),
        )
        .build();
        // Seed the RPC cache: MockEthProvider does not implement recovered_block.
        cache_new_blocks_task(
            eth_api.cache().clone(),
            futures::stream::iter([CanonStateNotification::Commit {
                new: Arc::new(Chain::new(
                    [recovered],
                    ExecutionOutcome {
                        receipts: vec![vec![]],
                        first_block: 1,
                        ..Default::default()
                    },
                    Default::default(),
                )),
            }]),
        )
        .await;
        let api = TraceApi::new(eth_api, BlockingTaskGuard::new(1), EthConfig::default());
        for types in [
            HashSet::from_iter([TraceType::VmTrace]),
            HashSet::from_iter([TraceType::VmTrace, TraceType::Trace, TraceType::StateDiff]),
            HashSet::from_iter([TraceType::Trace, TraceType::StateDiff]),
        ] {
            let traces = api
                .replay_block_transactions(block_hash.into(), types.clone())
                .await
                .unwrap()
                .unwrap();
            assert_eq!(traces.len(), 2);
            for (index, trace) in traces.into_iter().enumerate() {
                assert_eq!(
                    trace.full_trace.output.as_ref(),
                    U256::from(index + 1).to_be_bytes::<32>()
                );
                if types.contains(&TraceType::VmTrace) {
                    let vm = trace.full_trace.vm_trace.as_ref().unwrap();
                    assert_eq!(vm.code, root_code);
                    assert_eq!(
                        vm.ops.iter().find_map(|op| op.sub.as_ref()).unwrap().code,
                        child_code
                    );
                }
                let individual = api
                    .replay_transaction(trace.transaction_hash, types.clone())
                    .await
                    .unwrap()
                    .unwrap();
                assert_eq!(individual.transaction_hash, trace.transaction_hash);
                assert_eq!(trace.full_trace, individual.full_trace);
            }
        }
    }
}