forest/rpc/methods/

eth.rs

// Copyright 2019-2026 ChainSafe Systems
// SPDX-License-Identifier: Apache-2.0, MIT

mod bloom;
pub(crate) mod errors;
mod eth_tx;
pub mod filter;
pub mod pubsub;
pub(crate) mod pubsub_trait;
pub mod tipset_resolver;
pub(crate) mod trace;
pub mod types;
mod utils;

use crate::utils::encoding::hex;
pub use bloom::Bloom;
pub(crate) use bloom::store_block_logs_bloom;
use bloom::{EMPTY_BLOOM, FULL_BLOOM, accrue_eth_log, block_logs_bloom};
pub use tipset_resolver::TipsetResolver;
use tokio_util::sync::CancellationToken;

use self::eth_tx::*;
use self::filter::hex_str_to_epoch;
use self::trace::types::*;
use self::types::*;
use super::gas;
use crate::blocks::{Tipset, TipsetKey};
use crate::chain::{ChainStore, compute_base_fee, index::ResolveNullTipset};
use crate::chain_sync::NodeSyncStatus;
use crate::cid_collections::CidHashSet;
use crate::db::DbImpl;
use crate::eth::{
    EAMMethod, EVMMethod, EthChainId as EthChainIdType, EthEip1559TxArgs, EthLegacyEip155TxArgs,
    EthLegacyHomesteadTxArgs, parse_eth_transaction,
};
use crate::interpreter::VMTrace;
use crate::lotus_json::{HasLotusJson, NotNullVec, lotus_json_with_self};
use crate::message::{ChainMessage, MessageRead as _, MessageReadWrite as _, SignedMessage};
use crate::networks::Height;
use crate::prelude::*;
use crate::rpc::{
    ApiPaths, Ctx, EthEventHandler, LOOKBACK_NO_LIMIT, Permission, RpcMethod, RpcMethodExt as _,
    error::ServerError,
    eth::{
        errors::{EthErrors, NULL_ROUND_CODE},
        filter::{
            EventRevertStatus, SkipEvent, event::EventFilter, mempool::MempoolFilter,
            tipset::TipSetFilter,
        },
    },
    methods::chain::{ChainGetTipSetV2, PathChange},
    state::ApiInvocResult,
    types::{ApiTipsetKey, EventEntry, MessageLookup},
};
use crate::shim::actors::{eam, is_evm_actor, system};
use crate::shim::address::{Address as FilecoinAddress, Protocol};
use crate::shim::crypto::Signature;
use crate::shim::econ::{BLOCK_GAS_LIMIT, TokenAmount};
use crate::shim::executor::Receipt;
use crate::shim::fvm_shared_latest::MethodNum;
use crate::shim::fvm_shared_latest::address::{Address as VmAddress, DelegatedAddress};
use crate::shim::gas::GasOutputs;
use crate::shim::message::Message;
use crate::shim::{
    clock::ChainEpoch,
    state_tree::{ActorState, StateTree},
};
use crate::state_manager::{
    Error as StateManagerError, ExecutedMessage, ExecutedTipset, SenderValidation, StateManager,
    TipsetState, VMFlush,
};
use crate::utils::cache::SizeTrackingCache;
use crate::utils::encoding::from_slice_with_fallback;
use crate::utils::misc::env::env_or_default;
use crate::utils::multihash::prelude::*;
use ahash::{HashMap, HashSet};
use anyhow::{Error, Result, anyhow, bail, ensure};
use enumflags2::{BitFlags, make_bitflags};
use filter::{ParsedFilter, ParsedFilterTipsets};
use fvm_ipld_encoding::{CBOR, DAG_CBOR, IPLD_RAW, RawBytes};
use get_size2::GetSize;
use ipld_core::ipld::Ipld;
use nonzero_ext::nonzero;
use num::BigInt;
use nunny::Vec as NonEmpty;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::num::NonZeroUsize;
use std::ops::RangeInclusive;
use std::str::FromStr;
use std::sync::{LazyLock, OnceLock};
use utils::{ActorStateEthExt as _, decode_payload, lookup_eth_address};

static FOREST_TRACE_FILTER_MAX_RESULT: LazyLock<u64> =
    LazyLock::new(|| env_or_default("FOREST_TRACE_FILTER_MAX_RESULT", 500));

const MASKED_ID_PREFIX: [u8; 12] = [0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];

/// Ethereum address size in bytes.
const ADDRESS_LENGTH: usize = 20;

/// Ethereum Virtual Machine word size in bytes.
const EVM_WORD_LENGTH: usize = 32;

/// Keccak-256 of an RLP of an empty array.
/// In Filecoin, we don't have the concept of uncle blocks but rather use tipsets to reward miners
/// who craft blocks.
const EMPTY_UNCLES: &str = "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347";

/// Keccak-256 of the RLP of null.
const EMPTY_ROOT: &str = "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421";

/// The address used in messages to actors that have since been deleted.
pub(crate) const REVERTED_ETH_ADDRESS: &str = "0xff0000000000000000000000ffffffffffffffff";

#[derive(
    Eq,
    Hash,
    PartialEq,
    Debug,
    Deserialize,
    Serialize,
    Default,
    Clone,
    Copy,
    JsonSchema,
    GetSize,
    derive_more::From,
    derive_more::Into,
    derive_more::Deref,
)]
pub struct EthBigInt(
    // `ethereum_types::U256` serializes as a `0x`-prefixed, leading-zero-trimmed hex string,
    // which matches the Ethereum JSON-RPC wire format used by Lotus.
    #[schemars(with = "String")]
    #[get_size(ignore)]
    ethereum_types::U256,
);
lotus_json_with_self!(EthBigInt);

impl From<BigInt> for EthBigInt {
    fn from(value: BigInt) -> Self {
        (&value).into()
    }
}

impl From<&BigInt> for EthBigInt {
    fn from(value: &BigInt) -> Self {
        // Eth values are non-negative, so the sign is dropped.
        let (_sign, bytes) = value.to_bytes_be();
        Self(ethereum_types::U256::from_big_endian(&bytes))
    }
}

impl From<u64> for EthBigInt {
    fn from(value: u64) -> Self {
        Self(value.into())
    }
}

impl From<TokenAmount> for EthBigInt {
    fn from(amount: TokenAmount) -> Self {
        (&amount).into()
    }
}

impl From<&TokenAmount> for EthBigInt {
    fn from(amount: &TokenAmount) -> Self {
        amount.atto().into()
    }
}

impl From<EthBigInt> for BigInt {
    fn from(value: EthBigInt) -> Self {
        // Eth values are non-negative, so the sign is always positive.
        BigInt::from_bytes_be(num_bigint::Sign::Plus, &value.to_big_endian())
    }
}

impl From<EthBigInt> for TokenAmount {
    fn from(value: EthBigInt) -> Self {
        TokenAmount::from_atto(value)
    }
}

type GasPriceResult = EthBigInt;

#[derive(PartialEq, Debug, Deserialize, Serialize, Default, Clone, JsonSchema, GetSize)]
pub struct Nonce(
    #[schemars(with = "String")]
    #[serde(with = "crate::lotus_json::hexify_bytes")]
    #[get_size(ignore)]
    pub ethereum_types::H64,
);
lotus_json_with_self!(Nonce);

#[derive(
    Eq,
    Hash,
    PartialEq,
    Debug,
    Deserialize,
    Serialize,
    Default,
    Clone,
    Copy,
    JsonSchema,
    derive_more::From,
    derive_more::Into,
    derive_more::Deref,
    GetSize,
)]
pub struct EthUint64(
    #[schemars(with = "String")]
    #[serde(with = "crate::lotus_json::hexify")]
    pub u64,
);

lotus_json_with_self!(EthUint64);

impl EthUint64 {
    pub fn from_bytes(data: &[u8]) -> Result<Self> {
        if data.len() != EVM_WORD_LENGTH {
            bail!("eth int must be {EVM_WORD_LENGTH} bytes");
        }

        // big endian format stores u64 in the last 8 bytes,
        // since ethereum words are 32 bytes, the first 24 bytes must be 0
        if data
            .get(..24)
            .is_none_or(|slice| slice.iter().any(|&byte| byte != 0))
        {
            bail!("eth int overflows 64 bits");
        }

        // Extract the uint64 from the last 8 bytes
        Ok(Self(u64::from_be_bytes(
            data.get(24..EVM_WORD_LENGTH)
                .ok_or_else(|| anyhow::anyhow!("data too short"))?
                .try_into()?,
        )))
    }

    pub fn to_hex_string(self) -> String {
        hex::encode_prefixed(self.0.to_be_bytes())
    }
}

#[derive(
    PartialEq,
    Debug,
    Deserialize,
    Serialize,
    Default,
    Clone,
    Copy,
    JsonSchema,
    derive_more::From,
    derive_more::Into,
    derive_more::Deref,
    GetSize,
)]
pub struct EthInt64(
    #[schemars(with = "String")]
    #[serde(with = "crate::lotus_json::hexify")]
    pub i64,
);

lotus_json_with_self!(EthInt64);

impl EthHash {
    // Should ONLY be used for blocks and Filecoin messages. Eth transactions expect a different hashing scheme.
    pub fn to_cid(self) -> cid::Cid {
        let mh = MultihashCode::Blake2b256
            .wrap(self.0.as_bytes())
            .expect("should not fail");
        Cid::new_v1(DAG_CBOR, mh)
    }

    pub fn empty_uncles() -> Self {
        Self(
            ethereum_types::H256::from_str(EMPTY_UNCLES)
                .expect("EMPTY_UNCLES is a valid hardcoded H256 hex literal"),
        )
    }

    pub fn empty_root() -> Self {
        Self(
            ethereum_types::H256::from_str(EMPTY_ROOT)
                .expect("EMPTY_ROOT is a valid hardcoded H256 hex literal"),
        )
    }
}

impl From<Cid> for EthHash {
    fn from(cid: Cid) -> Self {
        let (_, digest, _) = cid.hash().into_inner();
        EthHash(ethereum_types::H256::from_slice(&digest[0..32]))
    }
}

impl From<[u8; EVM_WORD_LENGTH]> for EthHash {
    fn from(value: [u8; EVM_WORD_LENGTH]) -> Self {
        Self(ethereum_types::H256(value))
    }
}

#[derive(
    PartialEq,
    Debug,
    Clone,
    Copy,
    Serialize,
    Deserialize,
    Default,
    JsonSchema,
    strum::Display,
    strum::EnumString,
)]
#[strum(serialize_all = "lowercase")]
#[serde(rename_all = "lowercase")]
pub enum Predefined {
    Earliest,
    Pending,
    #[default]
    Latest,
    Safe,
    Finalized,
}

#[derive(PartialEq, Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct BlockNumber {
    block_number: EthInt64,
}

#[derive(PartialEq, Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct BlockHash {
    block_hash: EthHash,
    #[serde(default)]
    require_canonical: bool,
}

#[derive(
    PartialEq, Debug, Clone, Serialize, Deserialize, JsonSchema, strum::Display, derive_more::From,
)]
#[serde(untagged)]
pub enum BlockNumberOrHash {
    #[schemars(with = "String")]
    PredefinedBlock(Predefined),
    BlockNumber(EthInt64),
    BlockHash(EthHash),
    BlockNumberObject(BlockNumber),
    BlockHashObject(BlockHash),
}
lotus_json_with_self!(BlockNumberOrHash);

impl BlockNumberOrHash {
    pub fn from_block_number(number: i64) -> Self {
        Self::BlockNumber(EthInt64(number))
    }

    /// Construct a block number using EIP-1898 Object scheme.
    ///
    /// For details see <https://eips.ethereum.org/EIPS/eip-1898>
    pub fn from_block_number_object(number: i64) -> Self {
        Self::BlockNumberObject(BlockNumber {
            block_number: EthInt64(number),
        })
    }

    /// Construct a block hash using EIP-1898 Object scheme.
    ///
    /// For details see <https://eips.ethereum.org/EIPS/eip-1898>
    pub fn from_block_hash_object(hash: EthHash, require_canonical: bool) -> Self {
        Self::BlockHashObject(BlockHash {
            block_hash: hash,
            require_canonical,
        })
    }

    pub fn from_str(s: &str) -> Result<Self, Error> {
        if s.starts_with("0x") {
            let epoch = hex_str_to_epoch(s)?;
            return Ok(BlockNumberOrHash::from_block_number(epoch));
        }
        s.parse::<Predefined>()
            .map_err(|_| anyhow!("Invalid block identifier"))
            .map(BlockNumberOrHash::from)
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, GetSize)]
#[serde(untagged)] // try a Vec<String>, then a Vec<Tx>
pub enum Transactions {
    Hash(Vec<String>),
    Full(Vec<ApiEthTx>),
}

impl Transactions {
    pub fn is_empty(&self) -> bool {
        match self {
            Self::Hash(v) => v.is_empty(),
            Self::Full(v) => v.is_empty(),
        }
    }
}

impl PartialEq for Transactions {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::Hash(a), Self::Hash(b)) => a == b,
            (Self::Full(a), Self::Full(b)) => a == b,
            _ => self.is_empty() && other.is_empty(),
        }
    }
}

impl Default for Transactions {
    fn default() -> Self {
        Self::Hash(vec![])
    }
}

#[derive(PartialEq, Debug, Clone, Default, Serialize, Deserialize, JsonSchema, GetSize)]
#[serde(rename_all = "camelCase")]
pub struct Block {
    pub hash: EthHash,
    pub parent_hash: EthHash,
    pub sha3_uncles: EthHash,
    pub miner: EthAddress,
    pub state_root: EthHash,
    pub transactions_root: EthHash,
    pub receipts_root: EthHash,
    pub logs_bloom: Bloom,
    pub difficulty: EthUint64,
    pub total_difficulty: EthUint64,
    pub number: EthInt64,
    pub gas_limit: EthUint64,
    pub gas_used: EthUint64,
    pub timestamp: EthUint64,
    pub extra_data: EthBytes,
    pub mix_hash: EthHash,
    pub nonce: Nonce,
    pub base_fee_per_gas: EthBigInt,
    pub size: EthUint64,
    // can be Vec<Tx> or Vec<String> depending on query params
    pub transactions: Transactions,
    pub uncles: Vec<EthHash>,
}

/// Specifies the level of detail for transactions in Ethereum blocks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TxInfo {
    /// Return only transaction hashes
    Hash,
    /// Return full transaction objects
    Full,
}

impl From<bool> for TxInfo {
    fn from(full: bool) -> Self {
        if full { TxInfo::Full } else { TxInfo::Hash }
    }
}

impl Block {
    pub fn new(has_transactions: bool, tipset_len: usize) -> Self {
        Self {
            gas_limit: EthUint64(BLOCK_GAS_LIMIT.saturating_mul(tipset_len as _)),
            logs_bloom: Bloom(ethereum_types::Bloom(FULL_BLOOM)),
            sha3_uncles: EthHash::empty_uncles(),
            transactions_root: if has_transactions {
                EthHash::default()
            } else {
                EthHash::empty_root()
            },
            ..Default::default()
        }
    }

    /// Creates a new Ethereum block from a Filecoin tipset, executing transactions if requested.
    ///
    /// Reference: <https://github.com/filecoin-project/lotus/blob/941455f1d23e73b9ee92a1a4ce745d8848969858/node/impl/eth/utils.go#L44>
    pub async fn from_filecoin_tipset(
        state_manager: &StateManager,
        tipset: crate::blocks::Tipset,
        tx_info: TxInfo,
    ) -> Result<Arc<Self>> {
        static ETH_BLOCK_HASH_TX_CACHE: LazyLock<SizeTrackingCache<CidWrapper, Arc<Block>>> =
            LazyLock::new(|| {
                SizeTrackingCache::new_with_metrics("eth_block_hash_tx", Block::block_cache_size())
            });

        match tx_info {
            TxInfo::Full => Self::from_filecoin_tipset_with_full_tx(state_manager, tipset).await,
            TxInfo::Hash => {
                let block_cid = tipset.key().cid()?;
                ETH_BLOCK_HASH_TX_CACHE
                    .get_or_insert_async(&CidWrapper::from(block_cid), async move {
                        let block_with_full_tx =
                            Self::from_filecoin_tipset_with_full_tx(state_manager, tipset).await?;
                        Ok(Arc::new(
                            Arc::unwrap_or_clone(block_with_full_tx)
                                .downcast_full_transaction_to_hash(),
                        ))
                    })
                    .await
            }
        }
    }

    async fn from_filecoin_tipset_with_full_tx(
        state_manager: &StateManager,
        tipset: crate::blocks::Tipset,
    ) -> Result<Arc<Self>> {
        static ETH_BLOCK_FULL_TX_CACHE: LazyLock<SizeTrackingCache<CidWrapper, Arc<Block>>> =
            LazyLock::new(|| {
                SizeTrackingCache::new_with_metrics("eth_block_full_tx", Block::block_cache_size())
            });

        let block_cid = tipset.key().cid()?;
        ETH_BLOCK_FULL_TX_CACHE
            .get_or_insert_async(&CidWrapper::from(block_cid), async move {
                let parent_cid = tipset.parents().cid()?;
                let block_number = EthInt64(tipset.epoch());
                let block_hash: EthHash = block_cid.into();

                let ExecutedTipset {
                    state_root,
                    executed_messages,
                    ..
                } = state_manager.load_executed_tipset_for_rpc(&tipset).await?;
                let has_transactions = !executed_messages.is_empty();
                let state_tree = state_manager.get_state_tree(&state_root)?;

                let mut full_transactions = vec![];
                let mut gas_used = 0;
                for (
                    i,
                    ExecutedMessage {
                        message, receipt, ..
                    },
                ) in executed_messages.iter().enumerate()
                {
                    let ti = EthUint64(i as u64);
                    gas_used += receipt.gas_used();
                    let mut tx = match message {
                        ChainMessage::Signed(smsg) => new_eth_tx_from_signed_message(
                            smsg,
                            &state_tree,
                            state_manager.chain_config().eth_chain_id,
                        )?,
                        ChainMessage::Unsigned(msg) => {
                            let tx = eth_tx_from_native_message(
                                msg,
                                &state_tree,
                                state_manager.chain_config().eth_chain_id,
                            )?;
                            ApiEthTx {
                                hash: msg.cid().into(),
                                ..tx
                            }
                        }
                    };
                    tx.block_hash = block_hash;
                    tx.block_number = block_number;
                    tx.transaction_index = ti;
                    full_transactions.push(tx);
                }

                let logs_bloom =
                    block_logs_bloom(state_manager, &tipset, &state_root, &executed_messages)?;

                Ok(Arc::new(Block {
                    hash: block_hash,
                    number: block_number,
                    parent_hash: parent_cid.into(),
                    timestamp: EthUint64(tipset.block_headers().first().timestamp),
                    base_fee_per_gas: tipset
                        .block_headers()
                        .first()
                        .parent_base_fee
                        .clone()
                        .into(),
                    gas_used: EthUint64(gas_used),
                    transactions: Transactions::Full(full_transactions),
                    logs_bloom,
                    ..Block::new(has_transactions, tipset.len())
                }))
            })
            .await
    }

    fn block_cache_size() -> NonZeroUsize {
        const DEFAULT_CACHE_SIZE: NonZeroUsize = nonzero!(500usize);
        static CACHE_SIZE: std::sync::LazyLock<NonZeroUsize> = std::sync::LazyLock::new(|| {
            std::env::var("FOREST_ETH_BLOCK_CACHE_SIZE")
                .ok()
                .and_then(|s| s.parse().ok())
                .unwrap_or(DEFAULT_CACHE_SIZE)
        });
        *CACHE_SIZE
    }

    fn downcast_full_transaction_to_hash(mut self) -> Self {
        if let Transactions::Full(transactions) = &self.transactions {
            self.transactions =
                Transactions::Hash(transactions.iter().map(|tx| tx.hash.to_string()).collect())
        }
        self
    }
}

lotus_json_with_self!(Block);

#[derive(PartialEq, Debug, Clone, Default, Serialize, Deserialize, JsonSchema, GetSize)]
#[serde(rename_all = "camelCase")]
pub struct ApiEthTx {
    pub chain_id: EthUint64,
    pub nonce: EthUint64,
    pub hash: EthHash,
    pub block_hash: EthHash,
    pub block_number: EthInt64,
    pub transaction_index: EthUint64,
    pub from: EthAddress,
    // No `skip_serializing_if` (unlike the other `Option` fields): contract-creation txs must
    // emit `"to": null` rather than drop the key.
    #[serde(default)]
    pub to: Option<EthAddress>,
    pub value: EthBigInt,
    pub r#type: EthUint64,
    pub input: EthBytes,
    pub gas: EthUint64,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub max_fee_per_gas: Option<EthBigInt>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub max_priority_fee_per_gas: Option<EthBigInt>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub gas_price: Option<EthBigInt>,
    #[schemars(with = "Vec<EthHash>")]
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        serialize_with = "crate::lotus_json::serialize",
        deserialize_with = "crate::lotus_json::deserialize_empty_not_null_opt"
    )]
    pub access_list: Option<NotNullVec<EthHash>>,
    pub v: EthBigInt,
    pub r: EthBigInt,
    pub s: EthBigInt,
}
lotus_json_with_self!(ApiEthTx);

impl ApiEthTx {
    fn gas_fee_cap(&self) -> anyhow::Result<EthBigInt> {
        self.max_fee_per_gas
            .as_ref()
            .or(self.gas_price.as_ref())
            .cloned()
            .context("gas fee cap is not set")
    }

    fn gas_premium(&self) -> anyhow::Result<EthBigInt> {
        self.max_priority_fee_per_gas
            .as_ref()
            .or(self.gas_price.as_ref())
            .cloned()
            .context("gas premium is not set")
    }
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EthSyncingResult {
    pub done_sync: bool,
    pub starting_block: i64,
    pub current_block: i64,
    pub highest_block: i64,
}

#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum EthSyncingResultLotusJson {
    DoneSync(bool),
    Syncing {
        #[schemars(with = "i64")]
        #[serde(rename = "startingBlock", with = "crate::lotus_json::hexify")]
        starting_block: i64,
        #[schemars(with = "i64")]
        #[serde(rename = "currentBlock", with = "crate::lotus_json::hexify")]
        current_block: i64,
        #[schemars(with = "i64")]
        #[serde(rename = "highestBlock", with = "crate::lotus_json::hexify")]
        highest_block: i64,
    },
}

// TODO(forest): https://github.com/ChainSafe/forest/issues/4032
//               this shouldn't exist
impl HasLotusJson for EthSyncingResult {
    type LotusJson = EthSyncingResultLotusJson;

    #[cfg(test)]
    fn snapshots() -> Vec<(serde_json::Value, Self)> {
        vec![]
    }

    fn into_lotus_json(self) -> Self::LotusJson {
        match self {
            Self {
                done_sync: false,
                starting_block,
                current_block,
                highest_block,
            } => EthSyncingResultLotusJson::Syncing {
                starting_block,
                current_block,
                highest_block,
            },
            _ => EthSyncingResultLotusJson::DoneSync(false),
        }
    }

    fn from_lotus_json(lotus_json: Self::LotusJson) -> Self {
        match lotus_json {
            EthSyncingResultLotusJson::DoneSync(syncing) => {
                if syncing {
                    // Dangerous to panic here, log error instead.
                    tracing::error!("Invalid EthSyncingResultLotusJson: {syncing}");
                }
                Self {
                    done_sync: true,
                    ..Default::default()
                }
            }
            EthSyncingResultLotusJson::Syncing {
                starting_block,
                current_block,
                highest_block,
            } => Self {
                done_sync: false,
                starting_block,
                current_block,
                highest_block,
            },
        }
    }
}

#[derive(PartialEq, Debug, Default, Clone, Serialize, Deserialize, JsonSchema, GetSize)]
#[serde(rename_all = "camelCase")]
pub struct EthTxReceipt {
    transaction_hash: EthHash,
    transaction_index: EthUint64,
    block_hash: EthHash,
    block_number: EthInt64,
    from: EthAddress,
    to: Option<EthAddress>,
    root: EthHash,
    status: EthUint64,
    contract_address: Option<EthAddress>,
    cumulative_gas_used: EthUint64,
    gas_used: EthUint64,
    effective_gas_price: EthBigInt,
    logs_bloom: EthBytes,
    logs: Vec<EthLog>,
    r#type: EthUint64,
}
lotus_json_with_self!(EthTxReceipt);

impl EthTxReceipt {
    fn new() -> Self {
        Self {
            logs_bloom: EthBytes(EMPTY_BLOOM.to_vec()),
            ..Self::default()
        }
    }
}

/// Represents the results of an event filter execution.
#[derive(PartialEq, Debug, Default, Clone, Serialize, Deserialize, JsonSchema, GetSize)]
#[serde(rename_all = "camelCase")]
pub struct EthLog {
    /// The address of the actor that produced the event log.
    address: EthAddress,
    /// The value of the event log, excluding topics.
    data: EthBytes,
    /// List of topics associated with the event log.
    topics: Vec<EthHash>,
    /// Indicates whether the log was removed due to a chain reorganization.
    removed: bool,
    /// The index of the event log in the sequence of events produced by the message execution.
    /// (this is the index in the events AMT on the message receipt)
    log_index: EthUint64,
    /// The index in the tipset of the transaction that produced the event log.
    /// The index corresponds to the sequence of messages produced by `ChainGetParentMessages`
    transaction_index: EthUint64,
    /// The hash of the RLP message that produced the event log.
    transaction_hash: EthHash,
    /// The hash of the tipset containing the message that produced the log.
    block_hash: EthHash,
    /// The epoch of the tipset containing the message.
    block_number: EthUint64,
}
lotus_json_with_self!(EthLog);

pub enum Web3ClientVersion {}
impl RpcMethod<0> for Web3ClientVersion {
    const NAME: &'static str = "Filecoin.Web3ClientVersion";
    const NAME_ALIAS: Option<&'static str> = Some("web3_clientVersion");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the client version string of the running node.";

    type Params = ();
    type Ok = Arc<str>;

    async fn handle(
        _: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        // Version string is baked in at build time; cache once.
        static CACHED: OnceLock<Arc<str>> = OnceLock::new();
        Ok(CACHED
            .get_or_init(|| {
                Arc::<str>::from(format!(
                    "forest/{}",
                    *crate::utils::version::FOREST_VERSION_STRING
                ))
            })
            .clone())
    }
}

pub enum EthAccounts {}
impl RpcMethod<0> for EthAccounts {
    const NAME: &'static str = "Filecoin.EthAccounts";
    const NAME_ALIAS: Option<&'static str> = Some("eth_accounts");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the list of addresses owned by the client; always empty since Forest does not manage private keys.";

    type Params = ();
    type Ok = NotNullVec<String>;

    async fn handle(
        _: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        // EthAccounts will always return [] since we don't expect Forest to manage private keys
        Ok(NotNullVec(vec![]))
    }
}

pub enum EthBaseFee {}

impl EthBaseFee {
    fn get_base_fee(ctx: &Ctx, ts: &Tipset) -> anyhow::Result<TokenAmount> {
        let heights = &ctx.chain_config().height_infos;
        let smoke_height = heights
            .get(&Height::Smoke)
            .context("Missing Smoke height")?
            .epoch;
        let firehorse_height = heights
            .get(&Height::FireHorse)
            .context("Missing FireHorse height")?
            .epoch;
        compute_base_fee(ctx.db(), ts, smoke_height, firehorse_height)
            .context("failed to compute base fee for eth_baseFee")
    }
}

impl RpcMethod<0> for EthBaseFee {
    const NAME: &'static str = "Filecoin.EthBaseFee";
    const NAME_ALIAS: Option<&'static str> = Some("eth_baseFee");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the calculated base fee of the upcoming tipset in attoFIL";

    type Params = ();
    type Ok = EthBigInt;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let base_fee = Self::get_base_fee(&ctx, &ctx.chain_store().heaviest_tipset())?;
        Ok(base_fee.atto().into())
    }
}

pub enum BaseFeeByHeight {}
impl RpcMethod<1> for BaseFeeByHeight {
    const NAME: &'static str = "Forest.BaseFeeByHeight";
    const NAME_ALIAS: Option<&'static str> = None;
    const PARAM_NAMES: [&'static str; 1] = ["height"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the calculated upcoming base fee of the tipset at the given height in attoFIL";

    type Params = (ChainEpoch,);
    type Ok = EthBigInt;

    async fn handle(
        ctx: Ctx,
        (height,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let ts = ctx
            .chain_index()
            .load_required_tipset_by_height(
                height,
                ctx.chain_store().heaviest_tipset(),
                ResolveNullTipset::TakeOlder,
            )
            .await?;
        let base_fee = EthBaseFee::get_base_fee(&ctx, &ts)?;
        Ok(base_fee.atto().into())
    }
}

pub enum EthBlockNumber {}
impl RpcMethod<0> for EthBlockNumber {
    const NAME: &'static str = "Filecoin.EthBlockNumber";
    const NAME_ALIAS: Option<&'static str> = Some("eth_blockNumber");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the height of the latest executed tipset, which is the parent of the current head.";

    type Params = ();
    type Ok = EthUint64;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        // `eth_block_number` needs to return the height of the latest committed tipset.
        // Ethereum clients expect all transactions included in this block to have execution outputs.
        // This is the parent of the head tipset. The head tipset is speculative, has not been
        // recognized by the network, and its messages are only included, not executed.
        // See https://github.com/filecoin-project/ref-fvm/issues/1135.
        let heaviest = ctx.chain_store().heaviest_tipset();
        if heaviest.epoch() == 0 {
            // We're at genesis.
            return Ok(EthUint64::default());
        }
        // First non-null parent.
        let effective_parent = heaviest.parents();
        if let Ok(Some(parent)) = ctx.chain_index().load_tipset(effective_parent) {
            Ok((parent.epoch() as u64).into())
        } else {
            Ok(EthUint64::default())
        }
    }
}

pub enum EthChainId {}
impl RpcMethod<0> for EthChainId {
    const NAME: &'static str = "Filecoin.EthChainId";
    const NAME_ALIAS: Option<&'static str> = Some("eth_chainId");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the EIP-155 chain ID of the current network.";

    type Params = ();
    type Ok = Arc<str>;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        // `eth_chain_id` is fixed for the process lifetime; cache the hex form.
        static CACHED: OnceLock<Arc<str>> = OnceLock::new();
        Ok(CACHED
            .get_or_init(|| Arc::<str>::from(format!("{:#x}", ctx.chain_config().eth_chain_id)))
            .clone())
    }
}

pub enum EthGasPrice {}
impl RpcMethod<0> for EthGasPrice {
    const NAME: &'static str = "Filecoin.EthGasPrice";
    const NAME_ALIAS: Option<&'static str> = Some("eth_gasPrice");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the current gas price in attoFIL";

    type Params = ();
    type Ok = GasPriceResult;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        // According to Geth's implementation, eth_gasPrice should return base + tip
        // Ref: https://github.com/ethereum/pm/issues/328#issuecomment-853234014
        let ts = ctx.chain_store().heaviest_tipset();
        let block0 = ts.block_headers().first();
        let base_fee = block0.parent_base_fee.atto();
        let tip = crate::rpc::gas::estimate_gas_premium(&ctx, 0, &ApiTipsetKey(None))
            .await
            .map(|gas_premium| gas_premium.atto().to_owned())
            .unwrap_or_default();
        Ok((base_fee + tip).into())
    }
}

pub enum EthGetBalance {}
impl RpcMethod<2> for EthGetBalance {
    const NAME: &'static str = "Filecoin.EthGetBalance";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBalance");
    const PARAM_NAMES: [&'static str; 2] = ["address", "blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the balance of an Ethereum address at the specified block state";

    type Params = (EthAddress, BlockNumberOrHash);
    type Ok = EthBigInt;

    async fn handle(
        ctx: Ctx,
        (address, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
            .await?;
        let balance = eth_get_balance(&ctx, &address, &ts).await?;
        Ok(balance)
    }
}

async fn eth_get_balance(ctx: &Ctx, address: &EthAddress, ts: &Tipset) -> Result<EthBigInt> {
    let fil_addr = address.to_filecoin_address()?;
    let TipsetState { state_root, .. } = ctx.state_manager.load_tipset_state(ts).await?;
    let state_tree = ctx.state_manager.get_state_tree(&state_root)?;
    match state_tree.get_actor(&fil_addr)? {
        Some(actor) => Ok(actor.balance.atto().into()),
        None => Ok(EthBigInt::default()), // Balance is 0 if the actor doesn't exist
    }
}

fn get_tipset_from_hash(chain_store: &ChainStore, block_hash: &EthHash) -> anyhow::Result<Tipset> {
    let tsk = chain_store.get_required_tipset_key(block_hash)?;
    Ok(chain_store.chain_index().load_required_tipset(&tsk)?)
}

async fn resolve_block_number_tipset(
    chain: &ChainStore,
    block_number: EthInt64,
    resolve: ResolveNullTipset,
) -> anyhow::Result<Tipset> {
    let head = chain.heaviest_tipset();
    let height = ChainEpoch::from(block_number.0);
    if height > head.epoch() - 1 {
        bail!("requested a future epoch (beyond \"latest\")");
    }
    chain
        .chain_index()
        .load_required_tipset_by_height(height, head, resolve)
        .await
        .map_err(|e| match e {
            crate::chain::store::Error::NullRound(epoch) => EthErrors::null_round(epoch).into(),
            e => e.into(),
        })
}

async fn resolve_block_hash_tipset(
    chain: &ChainStore,
    block_hash: &EthHash,
    require_canonical: bool,
    resolve: ResolveNullTipset,
) -> anyhow::Result<Tipset> {
    let ts = get_tipset_from_hash(chain, block_hash)?;
    // verify that the tipset is in the canonical chain
    if require_canonical {
        // walk up the current chain (our head) until we reach ts.epoch()
        let walk_ts = chain
            .chain_index()
            .load_required_tipset_by_height(ts.epoch(), chain.heaviest_tipset(), resolve)
            .await?;
        // verify that it equals the expected tipset
        if walk_ts != ts {
            bail!("tipset is not canonical");
        }
    }
    Ok(ts)
}

pub fn is_eth_address(addr: &VmAddress) -> bool {
    if addr.protocol() != Protocol::Delegated {
        return false;
    }
    let f4_addr: Result<DelegatedAddress, _> = addr.payload().try_into();

    f4_addr.is_ok()
}

/// `eth_tx_from_signed_eth_message` does NOT populate:
/// - `hash`
/// - `block_hash`
/// - `block_number`
/// - `transaction_index`
pub fn eth_tx_from_signed_eth_message(
    smsg: &SignedMessage,
    chain_id: EthChainIdType,
) -> Result<(EthAddress, EthTx)> {
    // The from address is always an f410f address, never an ID or other address.
    let from = smsg.message().from;
    if !is_eth_address(&from) {
        bail!("sender must be an eth account, was {from}");
    }
    // This should be impossible to fail as we've already asserted that we have an
    // Ethereum Address sender...
    let from = EthAddress::from_filecoin_address(&from)?;
    let tx = EthTx::from_signed_message(chain_id, smsg)?;
    Ok((from, tx))
}

/// See <https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector-and-argument-encoding>
/// for ABI specification
fn encode_filecoin_params_as_abi(
    method: MethodNum,
    codec: u64,
    params: &fvm_ipld_encoding::RawBytes,
) -> Result<EthBytes> {
    let mut buffer: Vec<u8> = vec![0x86, 0x8e, 0x10, 0xc4];
    buffer.append(&mut encode_filecoin_returns_as_abi(method, codec, params));
    Ok(EthBytes(buffer))
}

fn encode_filecoin_returns_as_abi(
    exit_code: u64,
    codec: u64,
    data: &fvm_ipld_encoding::RawBytes,
) -> Vec<u8> {
    encode_as_abi_helper(exit_code, codec, data)
}

/// Round to the next multiple of `EVM` word length.
fn round_up_word(value: usize) -> usize {
    value.div_ceil(EVM_WORD_LENGTH) * EVM_WORD_LENGTH
}

/// Format two numbers followed by an arbitrary byte array as solidity ABI.
fn encode_as_abi_helper(param1: u64, param2: u64, data: &[u8]) -> Vec<u8> {
    // The first two params are "static" numbers. Then, we record the offset of the "data" arg,
    // then, at that offset, we record the length of the data.
    //
    // In practice, this means we have 4 256-bit words back to back where the third arg (the
    // offset) is _always_ '32*3'.
    let static_args = [
        param1,
        param2,
        (EVM_WORD_LENGTH * 3) as u64,
        data.len() as u64,
    ];
    let padding = [0u8; 24];
    let buf: Vec<u8> = padding
        .iter() // Right pad
        .chain(static_args[0].to_be_bytes().iter()) // Copy u64
        .chain(padding.iter())
        .chain(static_args[1].to_be_bytes().iter())
        .chain(padding.iter())
        .chain(static_args[2].to_be_bytes().iter())
        .chain(padding.iter())
        .chain(static_args[3].to_be_bytes().iter())
        .chain(data.iter()) // Finally, we copy in the data
        .chain(std::iter::repeat_n(
            &0u8,
            round_up_word(data.len()) - data.len(),
        )) // Left pad
        .cloned()
        .collect();

    buf
}

/// Convert a native message to an eth transaction.
///
///   - The state-tree must be from after the message was applied (ideally the following tipset).
///   - In some cases, the "to" address may be `0xff0000000000000000000000ffffffffffffffff`. This
///     means that the "to" address has not been assigned in the passed state-tree and can only
///     happen if the transaction reverted.
///
/// `eth_tx_from_native_message` does NOT populate:
/// - `hash`
/// - `block_hash`
/// - `block_number`
/// - `transaction_index`
fn eth_tx_from_native_message<DB: Blockstore>(
    msg: &Message,
    state: &StateTree<DB>,
    chain_id: EthChainIdType,
) -> Result<ApiEthTx> {
    // Lookup the from address. This must succeed.
    let from = match lookup_eth_address(&msg.from(), state) {
        Ok(Some(from)) => from,
        _ => bail!(
            "failed to lookup sender address {} when converting a native message to an eth txn",
            msg.from()
        ),
    };
    // Lookup the to address. If the recipient doesn't exist, we replace the address with a
    // known sentinel address.
    let mut to = match lookup_eth_address(&msg.to(), state) {
        Ok(Some(addr)) => Some(addr),
        Ok(None) => Some(EthAddress(
            ethereum_types::H160::from_str(REVERTED_ETH_ADDRESS)
                .expect("REVERTED_ETH_ADDRESS is a valid hardcoded H160 hex literal"),
        )),
        Err(err) => {
            bail!(err)
        }
    };

    // Finally, convert the input parameters to "solidity ABI".

    // For empty, we use "0" as the codec. Otherwise, we use CBOR for message
    // parameters.
    let codec = if !msg.params().is_empty() { CBOR } else { 0 };

    // We try to decode the input as an EVM method invocation and/or a contract creation. If
    // that fails, we encode the "native" parameters as Solidity ABI.
    let input = 'decode: {
        if (msg.method_num() == EVMMethod::InvokeContract as MethodNum
            || msg.method_num() == EAMMethod::CreateExternal as MethodNum)
            && let Ok(buffer) = decode_payload(msg.params(), codec)
        {
            // If this is a valid "create external", unset the "to" address.
            if msg.method_num() == EAMMethod::CreateExternal as MethodNum {
                to = None;
            }
            break 'decode buffer;
        }
        // Yeah, we're going to ignore errors here because the user can send whatever they
        // want and may send garbage.
        encode_filecoin_params_as_abi(msg.method_num(), codec, msg.params())?
    };

    Ok(ApiEthTx {
        to,
        from,
        input,
        nonce: EthUint64(msg.sequence),
        chain_id: EthUint64(chain_id),
        value: msg.value.clone().into(),
        r#type: EthUint64(EIP_1559_TX_TYPE.into()),
        gas: EthUint64(msg.gas_limit),
        max_fee_per_gas: Some(msg.gas_fee_cap.clone().into()),
        max_priority_fee_per_gas: Some(msg.gas_premium.clone().into()),
        access_list: Some(NotNullVec(vec![])),
        ..ApiEthTx::default()
    })
}

pub fn new_eth_tx_from_signed_message<DB: Blockstore>(
    smsg: &SignedMessage,
    state: &StateTree<DB>,
    chain_id: EthChainIdType,
) -> Result<ApiEthTx> {
    let (tx, hash) = if smsg.is_delegated() {
        // This is an eth tx
        let (from, tx) = eth_tx_from_signed_eth_message(smsg, chain_id)?;
        let hash = tx.eth_hash()?.into();
        let tx = ApiEthTx { from, ..tx.into() };
        (tx, hash)
    } else if smsg.is_secp256k1() {
        // Secp Filecoin Message
        let tx = eth_tx_from_native_message(smsg.message(), state, chain_id)?;
        (tx, smsg.cid().into())
    } else {
        // BLS Filecoin message
        let tx = eth_tx_from_native_message(smsg.message(), state, chain_id)?;
        (tx, smsg.message().cid().into())
    };
    Ok(ApiEthTx { hash, ..tx })
}

/// Creates an Ethereum transaction from Filecoin message lookup. If `None` is passed for `tx_index`,
/// it looks up the transaction index of the message in the tipset.
/// Otherwise, it uses some index passed into the function.
fn new_eth_tx_from_message_lookup(
    ctx: &Ctx,
    message_lookup: &MessageLookup,
    tx_index: Option<u64>,
) -> Result<ApiEthTx> {
    let ts = ctx
        .chain_store()
        .load_required_tipset_or_heaviest(&message_lookup.tipset)?;

    // This transaction is located in the parent tipset
    let parent_ts = ctx
        .chain_store()
        .load_required_tipset_or_heaviest(ts.parents())?;

    let parent_ts_cid = parent_ts.key().cid()?;

    // Lookup the transaction index
    let tx_index = tx_index.map_or_else(
        || {
            let msgs = ctx.chain_store().messages_for_tipset(&parent_ts)?;
            msgs.iter()
                .position(|msg| msg.cid() == message_lookup.message)
                .context("cannot find the msg in the tipset")
                .map(|i| i as u64)
        },
        Ok,
    )?;

    let smsg = get_signed_message(ctx, message_lookup.message)?;

    let state = ctx.state_manager.get_state_tree(ts.parent_state())?;

    Ok(ApiEthTx {
        block_hash: parent_ts_cid.into(),
        block_number: parent_ts.epoch().into(),
        transaction_index: tx_index.into(),
        ..new_eth_tx_from_signed_message(&smsg, &state, ctx.chain_config().eth_chain_id)?
    })
}

fn new_eth_tx(
    ctx: &Ctx,
    state: &StateTree<DbImpl>,
    block_height: ChainEpoch,
    msg_tipset_cid: &Cid,
    msg_cid: &Cid,
    tx_index: u64,
) -> Result<ApiEthTx> {
    let smsg = get_signed_message(ctx, *msg_cid)?;
    let tx = new_eth_tx_from_signed_message(&smsg, state, ctx.chain_config().eth_chain_id)?;

    Ok(ApiEthTx {
        block_hash: (*msg_tipset_cid).into(),
        block_number: block_height.into(),
        transaction_index: tx_index.into(),
        ..tx
    })
}

fn new_eth_tx_receipt(
    tipset: &Tipset,
    tx: &ApiEthTx,
    msg_receipt: &Receipt,
    logs: Vec<EthLog>,
) -> anyhow::Result<EthTxReceipt> {
    let mut tx_receipt = EthTxReceipt {
        transaction_hash: tx.hash,
        from: tx.from,
        to: tx.to,
        transaction_index: tx.transaction_index,
        block_hash: tx.block_hash,
        block_number: tx.block_number,
        r#type: tx.r#type,
        status: (u64::from(msg_receipt.exit_code().is_success())).into(),
        gas_used: msg_receipt.gas_used().into(),
        ..EthTxReceipt::new()
    };

    tx_receipt.cumulative_gas_used = EthUint64::default();

    let gas_fee_cap = tx.gas_fee_cap()?;
    let gas_premium = tx.gas_premium()?;

    let gas_outputs = GasOutputs::compute(
        msg_receipt.gas_used(),
        tx.gas.into(),
        &tipset.block_headers().first().parent_base_fee,
        &gas_fee_cap.into(),
        &gas_premium.into(),
    );
    let total_spent: BigInt = gas_outputs.total_spent().into();

    let mut effective_gas_price = EthBigInt::default();
    if msg_receipt.gas_used() > 0 {
        effective_gas_price = (total_spent / msg_receipt.gas_used()).into();
    }
    tx_receipt.effective_gas_price = effective_gas_price;

    if tx_receipt.to.is_none() && msg_receipt.exit_code().is_success() {
        // Create and Create2 return the same things.
        let ret: eam::CreateExternalReturn =
            from_slice_with_fallback(msg_receipt.return_data().bytes())?;

        tx_receipt.contract_address = Some(ret.eth_address.0.into());
    }

    tx_receipt.logs = logs;

    let mut bloom = Bloom::default();
    for log in tx_receipt.logs.iter() {
        accrue_eth_log(&mut bloom, &log.address, &log.topics);
    }
    tx_receipt.logs_bloom = bloom.into();

    Ok(tx_receipt)
}

pub async fn eth_logs_for_block_and_transaction(
    ctx: &Ctx,
    ts: &Tipset,
    block_hash: &EthHash,
    msg_cid: &Cid,
) -> anyhow::Result<Vec<EthLog>> {
    // Refuse to serve events for tipsets at or after head (deferred execution).
    let heaviest_epoch = ctx.chain_store().heaviest_tipset().epoch();
    if ts.epoch() >= heaviest_epoch {
        return Err(EthErrors::EventsNotYetAvailable.into());
    }

    let parsed_filter = ParsedFilter::new_with_tipset_and_msg(
        ParsedFilterTipsets::Hash(*block_hash),
        Some(*msg_cid),
    );
    let mut events = vec![];
    EthEventHandler::collect_events(
        &ctx.state_manager,
        ts,
        None,
        Some(&parsed_filter),
        SkipEvent::OnUnresolvedAddress,
        &mut events,
    )
    .await?;
    eth_filter_logs_from_events(ctx, &events)
}

/// Collects all Ethereum logs produced by a tipset's already-executed messages, in tipset order.
async fn collect_block_logs(
    ctx: &Ctx,
    tipset: &Tipset,
    executed_messages: &[ExecutedMessage],
    revert_status: EventRevertStatus,
) -> anyhow::Result<Vec<EthLog>> {
    let mut events = vec![];
    EthEventHandler::collect_events_from_messages(
        &ctx.state_manager,
        tipset,
        executed_messages,
        None::<&ParsedFilter>,
        SkipEvent::OnUnresolvedAddress,
        revert_status,
        &mut events,
    )
    .await?;
    eth_filter_logs_from_events(ctx, &events)
}

/// Collects the logs produced by a single chain head change, for the logs
/// subscription.
pub(in crate::rpc) async fn eth_logs_for_head_change(
    ctx: &Ctx,
    change: &PathChange<Tipset>,
) -> anyhow::Result<Vec<EthLog>> {
    let (receipt_ts, revert_status) = match change {
        PathChange::Revert(ts) => (ts, EventRevertStatus::Reverted),
        PathChange::Apply(ts) => (ts, EventRevertStatus::Applied),
    };
    // Genesis carries no events and has no parent message tipset to load.
    if receipt_ts.epoch() == 0 {
        return Ok(vec![]);
    }
    let msg_ts = ctx
        .chain_index()
        .load_required_tipset(receipt_ts.parents())?;
    let executed_ts = ctx
        .state_manager
        .load_executed_tipset_with_receipt(&msg_ts, receipt_ts)
        .await?;
    collect_block_logs(ctx, &msg_ts, &executed_ts.executed_messages, revert_status).await
}

fn get_signed_message(ctx: &Ctx, message_cid: Cid) -> Result<SignedMessage> {
    let result: Result<SignedMessage, crate::chain::Error> =
        crate::chain::message_from_cid(ctx.db(), &message_cid);

    result.or_else(|_| {
        // We couldn't find the signed message, it might be a BLS message, so search for a regular message.
        let msg: Message = crate::chain::message_from_cid(ctx.db(), &message_cid)
            .with_context(|| format!("failed to find msg {message_cid}"))?;
        Ok(SignedMessage::new_unchecked(
            msg,
            Signature::new_bls(vec![]),
        ))
    })
}

pub enum EthGetBlockByHash {}
impl RpcMethod<2> for EthGetBlockByHash {
    const NAME: &'static str = "Filecoin.EthGetBlockByHash";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBlockByHash");
    const PARAM_NAMES: [&'static str; 2] = ["blockHash", "fullTxInfo"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Retrieves a block by its hash, optionally including full transaction objects.";

    type Params = (EthHash, bool);
    type Ok = Arc<Block>;

    async fn handle(
        ctx: Ctx,
        (block_hash, full_tx_info): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_hash, ResolveNullTipset::TakeOlder)
            .await?;
        Block::from_filecoin_tipset(&ctx.state_manager, ts, full_tx_info.into())
            .await
            .map_err(ServerError::from)
    }
}

pub enum EthGetBlockByNumber {}
impl RpcMethod<2> for EthGetBlockByNumber {
    const NAME: &'static str = "Filecoin.EthGetBlockByNumber";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBlockByNumber");
    const PARAM_NAMES: [&'static str; 2] = ["blockParam", "fullTxInfo"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Retrieves a block by its number or a special tag.";

    type Params = (BlockNumberOrPredefined, bool);
    type Ok = Arc<Block>;

    async fn handle(
        ctx: Ctx,
        (block_param, full_tx_info): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::Fail)
            .await?;
        Block::from_filecoin_tipset(&ctx.state_manager, ts, full_tx_info.into())
            .await
            .map_err(ServerError::from)
    }
}

async fn get_block_receipts(
    ctx: &Ctx,
    ts: Tipset,
    limit: Option<ChainEpoch>,
) -> Result<Vec<EthTxReceipt>> {
    if let Some(limit) = limit
        && limit > LOOKBACK_NO_LIMIT
        && ts.epoch() < ctx.chain_store().heaviest_tipset().epoch() - limit
    {
        bail!(
            "tipset {} is older than the allowed lookback limit",
            ts.key().format_lotus()
        );
    }
    let ts_ref = Arc::new(ts);
    let ts_key = ts_ref.key();

    // Execute the tipset to get the messages and receipts
    let ExecutedTipset {
        state_root,
        executed_messages,
        ..
    } = ctx
        .state_manager
        .load_executed_tipset_for_rpc(&ts_ref)
        .await?;

    // Load the state tree
    let state_tree = ctx.state_manager.get_state_tree(&state_root)?;

    // Collect the whole tipset's logs in a single pass and scatter them back to their messages.
    let heaviest_epoch = ctx.chain_store().heaviest_tipset().epoch();
    if ts_ref.epoch() >= heaviest_epoch
        && executed_messages
            .iter()
            .any(|em| em.receipt.events_root().is_some())
    {
        return Err(EthErrors::EventsNotYetAvailable.into());
    }

    let mut logs_by_msg: Vec<Vec<EthLog>> = vec![Vec::new(); executed_messages.len()];
    for log in
        collect_block_logs(ctx, &ts_ref, &executed_messages, EventRevertStatus::Applied).await?
    {
        // `transaction_index` is the message's index in `executed_messages` (this loop's slice), always a valid bucket.
        if let Some(bucket) = logs_by_msg.get_mut(log.transaction_index.0 as usize) {
            bucket.push(log);
        }
    }

    let block_cid = ts_key.cid()?;
    let mut eth_receipts = Vec::with_capacity(executed_messages.len());
    for (i, (executed, logs)) in executed_messages.iter().zip(logs_by_msg).enumerate() {
        let ExecutedMessage {
            message, receipt, ..
        } = executed;
        let tx = new_eth_tx(
            ctx,
            &state_tree,
            ts_ref.epoch(),
            &block_cid,
            &message.cid(),
            i as u64,
        )?;

        let receipt = new_eth_tx_receipt(&ts_ref, &tx, receipt, logs)?;
        eth_receipts.push(receipt);
    }
    Ok(eth_receipts)
}

// Reject null-round `eth_getBlockReceipts*` by default (matches lotus#13694); set this flag for
// the legacy previous-tipset behavior. See https://github.com/ChainSafe/forest/issues/7270.
crate::def_is_env_truthy!(
    legacy_null_round_block_receipts,
    "FOREST_ETH_GET_BLOCK_RECEIPTS_LEGACY_NULL_ROUND"
);

/// `Fail` (default) or legacy `TakeOlder` for `eth_getBlockReceipts*` on a null round.
fn block_receipts_null_round() -> ResolveNullTipset {
    if legacy_null_round_block_receipts() {
        ResolveNullTipset::TakeOlder
    } else {
        ResolveNullTipset::Fail
    }
}

pub enum EthGetBlockReceipts {}
impl RpcMethod<1> for EthGetBlockReceipts {
    const NAME: &'static str = "Filecoin.EthGetBlockReceipts";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBlockReceipts");
    const PARAM_NAMES: [&'static str; 1] = ["blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Retrieves all transaction receipts for a block by its number, hash or a special tag.";

    type Params = (BlockNumberOrHash,);
    type Ok = NotNullVec<EthTxReceipt>;

    async fn handle(
        ctx: Ctx,
        (block_param,): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, block_receipts_null_round())
            .await?;
        get_block_receipts(&ctx, ts, None)
            .await
            .map(NotNullVec)
            .map_err(ServerError::from)
    }
}

pub enum EthGetBlockReceiptsLimited {}
impl RpcMethod<2> for EthGetBlockReceiptsLimited {
    const NAME: &'static str = "Filecoin.EthGetBlockReceiptsLimited";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBlockReceiptsLimited");
    const PARAM_NAMES: [&'static str; 2] = ["blockParam", "limit"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Retrieves all transaction receipts for a block identified by its number, hash or a special tag along with an optional limit on the chain epoch for state resolution.";

    type Params = (BlockNumberOrHash, ChainEpoch);
    type Ok = NotNullVec<EthTxReceipt>;

    async fn handle(
        ctx: Ctx,
        (block_param, limit): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, block_receipts_null_round())
            .await?;
        get_block_receipts(&ctx, ts, Some(limit))
            .await
            .map(NotNullVec)
            .map_err(ServerError::from)
    }
}

pub enum EthGetBlockTransactionCountByHash {}
impl RpcMethod<1> for EthGetBlockTransactionCountByHash {
    const NAME: &'static str = "Filecoin.EthGetBlockTransactionCountByHash";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBlockTransactionCountByHash");
    const PARAM_NAMES: [&'static str; 1] = ["blockHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the number of messages in the tipset identified by the given block hash.";

    type Params = (EthHash,);
    type Ok = EthUint64;

    async fn handle(
        ctx: Ctx,
        (block_hash,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let ts = get_tipset_from_hash(ctx.chain_store(), &block_hash)?;

        let head = ctx.chain_store().heaviest_tipset();
        if ts.epoch() > head.epoch() {
            return Err(anyhow::anyhow!("requested a future epoch (beyond \"latest\")").into());
        }
        let count = count_messages_in_tipset(ctx.db(), &ts)?;
        Ok(EthUint64(count as _))
    }
}

pub enum EthGetBlockTransactionCountByNumber {}
impl RpcMethod<1> for EthGetBlockTransactionCountByNumber {
    const NAME: &'static str = "Filecoin.EthGetBlockTransactionCountByNumber";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getBlockTransactionCountByNumber");
    const PARAM_NAMES: [&'static str; 1] = ["blockNumber"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the number of transactions in a block identified by its block number or a special tag.";

    type Params = (BlockNumberOrPredefined,);
    type Ok = EthUint64;

    async fn handle(
        ctx: Ctx,
        (block_number,): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_number, ResolveNullTipset::Fail)
            .await?;
        let count = count_messages_in_tipset(ctx.db(), &ts)?;
        Ok(EthUint64(count as _))
    }
}

pub enum EthGetMessageCidByTransactionHash {}
impl RpcMethod<1> for EthGetMessageCidByTransactionHash {
    const NAME: &'static str = "Filecoin.EthGetMessageCidByTransactionHash";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getMessageCidByTransactionHash");
    const PARAM_NAMES: [&'static str; 1] = ["txHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the CID of the Filecoin message corresponding to the given Ethereum transaction hash.";

    type Params = (EthHash,);
    type Ok = Option<Cid>;

    async fn handle(
        ctx: Ctx,
        (tx_hash,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let result = ctx.chain_store().get_mapping(&tx_hash);
        match result {
            Ok(Some(cid)) => return Ok(Some(cid)),
            Ok(None) => tracing::debug!("Undefined key {tx_hash}"),
            _ => {
                result?;
            }
        }

        // This isn't an eth transaction we have the mapping for, so let's try looking it up as a filecoin message
        let cid = tx_hash.to_cid();

        let result: Result<Vec<SignedMessage>, crate::chain::Error> =
            crate::chain::messages_from_cids(ctx.db(), &[cid]);
        if result.is_ok() {
            // This is an Eth Tx, Secp message, Or BLS message in the mpool
            return Ok(Some(cid));
        }

        let result: Result<Vec<Message>, crate::chain::Error> =
            crate::chain::messages_from_cids(ctx.db(), &[cid]);
        if result.is_ok() {
            // This is a BLS message
            return Ok(Some(cid));
        }

        // Ethereum clients expect an empty response when the message was not found
        Ok(None)
    }
}

fn count_messages_in_tipset(store: &impl Blockstore, ts: &Tipset) -> anyhow::Result<usize> {
    let mut message_cids = CidHashSet::default();
    for block in ts.block_headers() {
        let (bls_messages, secp_messages) = crate::chain::store::block_messages(store, block)?;
        for m in bls_messages {
            message_cids.insert(m.cid());
        }
        for m in secp_messages {
            message_cids.insert(m.cid());
        }
    }
    Ok(message_cids.len())
}

pub enum EthSyncing {}
impl RpcMethod<0> for EthSyncing {
    const NAME: &'static str = "Filecoin.EthSyncing";
    const NAME_ALIAS: Option<&'static str> = Some("eth_syncing");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the node's sync status, or `false` if the node is not currently syncing.";

    type Params = ();
    type Ok = EthSyncingResult;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let sync_status = crate::rpc::sync::SyncStatus::handle(ctx, (), ext).await?;
        match sync_status.status {
            NodeSyncStatus::Synced => Ok(EthSyncingResult {
                done_sync: true,
                // Once the node is synced, other fields are not relevant for the API
                ..Default::default()
            }),
            NodeSyncStatus::Syncing => {
                let starting_block = match sync_status.get_min_starting_block() {
                    Some(e) => Ok(e),
                    None => Err(ServerError::internal_error(
                        "missing syncing information, try again",
                        None,
                    )),
                }?;

                Ok(EthSyncingResult {
                    done_sync: sync_status.is_synced(),
                    starting_block,
                    current_block: sync_status.current_head_epoch,
                    highest_block: sync_status.network_head_epoch,
                })
            }
            _ => Err(ServerError::internal_error("node is not syncing", None)),
        }
    }
}

pub enum EthEstimateGas {}

impl RpcMethod<2> for EthEstimateGas {
    const NAME: &'static str = "Filecoin.EthEstimateGas";
    const NAME_ALIAS: Option<&'static str> = Some("eth_estimateGas");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 2] = ["tx", "blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Estimates the amount of gas required to execute the given transaction.";

    type Params = (EthCallMessage, Option<BlockNumberOrHash>);
    type Ok = EthUint64;

    async fn handle(
        ctx: Ctx,
        (tx, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let tipset = if let Some(block_param) = block_param {
            let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
            resolver
                .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
                .await?
        } else {
            ctx.chain_store().heaviest_tipset()
        };
        eth_estimate_gas(&ctx, tx, tipset).await
    }
}

async fn eth_estimate_gas(
    ctx: &Ctx,
    tx: EthCallMessage,
    tipset: Tipset,
) -> Result<EthUint64, ServerError> {
    let mut msg = Message::try_from(tx)?;
    // Set the gas limit to the zero sentinel value, which makes
    // gas estimation actually run.
    msg.gas_limit = 0;

    if sender_is_evm_contract(
        ctx.state_manager
            .get_actor(&msg.from, *tipset.parent_state()),
    ) {
        return eth_estimate_gas_skip_sender(ctx, msg, &tipset).await;
    }

    match gas::estimate_message_gas(ctx, msg.clone(), None, tipset.key().clone().into()).await {
        Err(err) => {
            if matches!(
                err.downcast_ref(),
                Some(StateManagerError::SenderValidationFailed(_))
            ) {
                return eth_estimate_gas_skip_sender(ctx, msg, &tipset).await;
            }

            // Return reverts as-is to preserve the JSON-RPC error codec.
            if matches!(
                err.downcast_ref(),
                Some(EthErrors::ExecutionReverted { .. })
            ) {
                return Err(err.into());
            }
            Err(err.context("failed to estimate gas").into())
        }
        Ok(gassed_msg) => {
            let expected_gas =
                eth_gas_search(ctx, gassed_msg, &tipset, SenderValidation::Enforce).await?;
            Ok(expected_gas.into())
        }
    }
}

fn sender_is_evm_contract(actor: anyhow::Result<Option<ActorState>>) -> bool {
    matches!(actor, Ok(Some(actor)) if is_evm_actor(&actor.code))
}

/// Estimates gas for a sender that is a contract or doesn't exist on chain.
async fn eth_estimate_gas_skip_sender(
    ctx: &Ctx,
    mut msg: Message,
    tipset: &Tipset,
) -> Result<EthUint64, ServerError> {
    let gas_limit = match gas::GasEstimateGasLimit::estimate_gas_limit(
        ctx,
        msg.clone(),
        tipset,
        SenderValidation::Skip,
    )
    .await
    {
        Ok(gas_limit) => gas_limit,
        Err(estimate_err) => {
            return Err(recover_estimate_gas_error(ctx, msg, tipset, estimate_err).await);
        }
    };

    let gas_limit = (gas_limit as f64 * ctx.mpool.gas_limit_overestimation()) as u64;
    msg.set_gas_limit(gas_limit.min(BLOCK_GAS_LIMIT));

    let expected_gas = eth_gas_search(ctx, msg, tipset, SenderValidation::Skip).await?;
    Ok(expected_gas.into())
}

/// Re-execute to recover an `ExecutionReverted` from a failed gas estimate.
async fn recover_estimate_gas_error(
    ctx: &Ctx,
    mut msg: Message,
    tipset: &Tipset,
    estimate_err: anyhow::Error,
) -> ServerError {
    msg.set_gas_limit(BLOCK_GAS_LIMIT);
    if let Err(e) = apply_message(ctx, Some(tipset), &msg).await
        && matches!(e.downcast_ref(), Some(EthErrors::ExecutionReverted { .. }))
    {
        return e.into();
    }
    estimate_err.context("failed to estimate gas").into()
}

fn needs_skip_sender(result: &Result<(ApiInvocResult, Option<Cid>), Error>) -> bool {
    match result {
        Err(e) => matches!(
            e.downcast_ref(),
            Some(StateManagerError::SenderValidationFailed(_))
        ),
        Ok((invoc_res, _)) => invoc_res
            .msg_rct
            .as_ref()
            .is_some_and(|rct| rct.exit_code() == fvm_shared4::error::ExitCode::SYS_SENDER_INVALID),
    }
}

async fn apply_message(
    ctx: &Ctx,
    tipset: Option<&Tipset>,
    msg: &Message,
) -> Result<ApiInvocResult, Error> {
    if let Some(ts) = tipset
        && ts.epoch() > 0
        && ctx
            .chain_config()
            .has_expensive_fork_between(ts.epoch(), ts.epoch() + 1)
    {
        return Err(crate::state_manager::Error::ExpensiveFork { epoch: ts.epoch() }.into());
    }

    let result = ctx
        .state_manager
        .apply_on_state_with_gas(
            tipset,
            msg,
            VMFlush::Skip,
            VMTrace::NotTraced,
            SenderValidation::Enforce,
        )
        .await;

    let (invoc_res, _) = if needs_skip_sender(&result) {
        ctx.state_manager
            .apply_on_state_with_gas(
                tipset,
                msg,
                VMFlush::Skip,
                VMTrace::NotTraced,
                SenderValidation::Skip,
            )
            .await
            .context("failed to apply on state with gas (skipping sender validation)")?
    } else {
        result.context("failed to apply on state with gas")?
    };

    // Extract receipt or return early if none
    match &invoc_res.msg_rct {
        None => return Err(anyhow::anyhow!("no message receipt in execution result")),
        Some(receipt) => {
            if !receipt.exit_code().is_success() {
                return Err(EthErrors::execution_reverted_from_result(
                    receipt.exit_code(),
                    receipt.return_data(),
                    &invoc_res.error,
                )
                .into());
            }
        }
    };

    Ok(invoc_res)
}

pub async fn eth_gas_search(
    data: &Ctx,
    msg: Message,
    curr_ts: &Tipset,
    sender_validation: SenderValidation,
) -> anyhow::Result<u64> {
    // Probe the message as the caller specified it: the question is whether *its* limit
    // suffices, which the block maximum would always answer yes to.
    let (apply_ret, prior_messages, ts, from) = gas::GasEstimateGasLimit::probe_as_specified(
        data,
        msg.clone(),
        curr_ts,
        VMTrace::NotTraced,
        sender_validation,
    )
    .await?;
    if apply_ret.exit_code().is_success() {
        return Ok(msg.gas_limit());
    }

    // Only the trace tells "needs a higher limit" from "fails at any limit", and it is worth one
    // re-execution here against the ~30 the search below would spend. The statement keeps the
    // trace, one event per gas charge, from outliving the check.
    let out_of_gas = data
        .state_manager
        .call_with_gas(
            ChainMessage::for_gas_estimation(msg.clone(), from.protocol()),
            prior_messages.shallow_clone(),
            Some(ts.shallow_clone()),
            VMFlush::Skip,
            VMTrace::Traced,
            sender_validation,
        )
        .await?
        .0
        .trace_has_call_return_exit_code(fvm_shared4::error::ExitCode::SYS_OUT_OF_GAS);
    if !out_of_gas {
        // Match Lotus: a code-3 `ExecutionReverted` with the decoded revert data, so eth tooling
        // gets the code and can ABI-decode the reason.
        let vm_error = apply_ret.failure_info().unwrap_or_default();
        return Err(EthErrors::execution_reverted_from_result(
            apply_ret.exit_code(),
            apply_ret.return_data(),
            &vm_error,
        )
        .with_message_prefix("gas search failed")
        .into());
    }

    let ret = gas_search(
        data,
        &msg,
        from.protocol(),
        prior_messages,
        ts,
        sender_validation,
    )
    .await?;
    Ok((ret as f64 * data.mpool.gas_limit_overestimation()) as u64)
}

/// `gas_search` does an exponential search to find a gas value to execute the
/// message with. It first finds a high gas limit that allows the message to execute
/// by doubling the previous gas limit until it succeeds then does a binary
/// search till it gets within a range of 1%
async fn gas_search(
    data: &Ctx,
    msg: &Message,
    from_protocol: Protocol,
    prior_messages: Arc<Vec<ChainMessage>>,
    ts: Tipset,
    sender_validation: SenderValidation,
) -> anyhow::Result<u64> {
    // `max(1)` keeps the doubling below able to make progress.
    let mut high = msg.gas_limit.max(1);
    let mut low = high;

    let can_succeed = async |limit: u64| {
        let mut msg = msg.clone();
        msg.gas_limit = limit;
        let (apply_ret, ..) = data
            .state_manager
            .call_with_gas(
                ChainMessage::for_gas_estimation(msg, from_protocol),
                prior_messages.shallow_clone(),
                Some(ts.shallow_clone()),
                VMFlush::Skip,
                VMTrace::NotTraced,
                sender_validation,
            )
            .await?;
        anyhow::Ok(apply_ret.exit_code().is_success())
    };

    while high < BLOCK_GAS_LIMIT {
        if can_succeed(high).await? {
            break;
        }
        low = high;
        high = high.saturating_mul(2).min(BLOCK_GAS_LIMIT);
    }

    let mut check_threshold = high / 100;
    while (high - low) > check_threshold {
        let median = (high + low) / 2;
        if can_succeed(median).await? {
            high = median;
        } else {
            low = median;
        }
        check_threshold = median / 100;
    }

    Ok(high)
}

pub enum EthFeeHistory {}

impl RpcMethod<3> for EthFeeHistory {
    const NAME: &'static str = "Filecoin.EthFeeHistory";
    const NAME_ALIAS: Option<&'static str> = Some("eth_feeHistory");
    const N_REQUIRED_PARAMS: usize = 2;
    const PARAM_NAMES: [&'static str; 3] = ["blockCount", "newestBlockNumber", "rewardPercentiles"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns historical gas information for a range of blocks, including base fee per gas, gas used ratio, and priority fee percentiles.";

    type Params = (EthUint64, BlockNumberOrPredefined, Option<Vec<f64>>);
    type Ok = EthFeeHistoryResult;

    async fn handle(
        ctx: Ctx,
        (EthUint64(block_count), newest_block_number, reward_percentiles): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let tipset = resolver
            .tipset_by_block_number_or_hash(newest_block_number, ResolveNullTipset::TakeOlder)
            .await?;
        eth_fee_history(ctx, tipset, block_count, reward_percentiles).await
    }
}

async fn eth_fee_history(
    ctx: Ctx,
    tipset: Tipset,
    block_count: u64,
    reward_percentiles: Option<Vec<f64>>,
) -> Result<EthFeeHistoryResult, ServerError> {
    if block_count > 1024 {
        return Err(anyhow::anyhow!("block count should be smaller than 1024").into());
    }

    let reward_percentiles = reward_percentiles.unwrap_or_default();
    validate_reward_percentiles(&reward_percentiles)?;

    let mut oldest_block_height = 1;
    // NOTE: baseFeePerGas should include the next block after the newest of the returned range,
    //  because the next base fee can be inferred from the messages in the newest block.
    //  However, this is NOT the case in Filecoin due to deferred execution, so the best
    //  we can do is duplicate the last value.
    let mut base_fee_array = vec![EthBigInt::from(
        &tipset.block_headers().first().parent_base_fee,
    )];
    let mut rewards_array = vec![];
    let mut gas_used_ratio_array = vec![];
    // The walk goes newest -> oldest, so each tipset is the child of the next. Carry it forward as the
    // receipt source for the next (older) tipset, so only the newest needs a `load_child_tipset` lookup
    // (`None` on the first pass).
    let mut child: Option<Tipset> = None;
    for ts in tipset
        .chain(ctx.db())
        .filter(|i| i.epoch() > 0)
        .take(block_count as _)
    {
        let base_fee = &ts.block_headers().first().parent_base_fee;
        let message_receipts = ctx
            .state_manager
            .tipset_message_receipts(&ts, child.as_ref())
            .await?;
        let tx_gas_rewards = message_receipts
            .iter()
            .map(|(message, receipt)| GasReward {
                gas_used: receipt.gas_used(),
                premium: message.effective_gas_premium(base_fee),
            })
            .collect_vec();
        let (rewards, total_gas_used) =
            calculate_rewards_and_gas_used(&reward_percentiles, tx_gas_rewards);
        let max_gas = BLOCK_GAS_LIMIT * (ts.block_headers().len() as u64);

        // arrays should be reversed at the end
        base_fee_array.push(EthBigInt::from(base_fee));
        gas_used_ratio_array.push((total_gas_used as f64) / (max_gas as f64));
        rewards_array.push(rewards);

        oldest_block_height = ts.epoch();
        // This tipset is the receipt source (child) of the next (older) one.
        child = Some(ts);
    }

    // Reverse the arrays; we collected them newest to oldest; the client expects oldest to newest.
    base_fee_array.reverse();
    gas_used_ratio_array.reverse();
    rewards_array.reverse();

    Ok(EthFeeHistoryResult {
        oldest_block: EthUint64(oldest_block_height as _),
        base_fee_per_gas: base_fee_array,
        gas_used_ratio: gas_used_ratio_array,
        reward: if reward_percentiles.is_empty() {
            None
        } else {
            Some(rewards_array)
        },
    })
}

fn validate_reward_percentiles(reward_percentiles: &[f64]) -> anyhow::Result<()> {
    if reward_percentiles.len() > 100 {
        anyhow::bail!("length of the reward percentile array cannot be greater than 100");
    }

    for (&rp_prev, &rp) in std::iter::once(&0.0)
        .chain(reward_percentiles.iter())
        .tuple_windows()
    {
        if !(0. ..=100.).contains(&rp) {
            anyhow::bail!("invalid reward percentile: {rp} should be between 0 and 100");
        }
        if rp < rp_prev {
            anyhow::bail!(
                "invalid reward percentile: {rp} should be larger than or equal to {rp_prev}"
            );
        }
    }

    Ok(())
}

fn calculate_rewards_and_gas_used(
    reward_percentiles: &[f64],
    mut tx_gas_rewards: Vec<GasReward>,
) -> (Vec<EthBigInt>, u64) {
    const MIN_GAS_PREMIUM: u64 = 100000;

    let gas_used_total = tx_gas_rewards.iter().map(|i| i.gas_used).sum();
    let mut rewards = reward_percentiles
        .iter()
        .map(|_| EthBigInt::from(MIN_GAS_PREMIUM))
        .collect_vec();
    if !tx_gas_rewards.is_empty() {
        tx_gas_rewards.sort_by(|a, b| a.premium.cmp(&b.premium));
        let mut idx = 0;
        let mut sum = 0;
        #[allow(clippy::indexing_slicing)]
        for (i, &percentile) in reward_percentiles.iter().enumerate() {
            let threshold = ((gas_used_total as f64) * percentile / 100.) as u64;
            while sum < threshold && idx < tx_gas_rewards.len() - 1 {
                sum += tx_gas_rewards[idx].gas_used;
                idx += 1;
            }
            rewards[i] = (&tx_gas_rewards[idx].premium).into();
        }
    }
    (rewards, gas_used_total)
}

pub enum EthGetCode {}
impl RpcMethod<2> for EthGetCode {
    const NAME: &'static str = "Filecoin.EthGetCode";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getCode");
    const PARAM_NAMES: [&'static str; 2] = ["ethAddress", "blockNumberOrHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Retrieves the contract code at a specific address and block state, identified by its number, hash, or a special tag.";

    type Params = (EthAddress, BlockNumberOrHash);
    type Ok = EthBytes;

    async fn handle(
        ctx: Ctx,
        (eth_address, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
            .await?;
        eth_get_code(&ctx, &ts, &eth_address).await
    }
}

async fn eth_get_code(
    ctx: &Ctx,
    ts: &Tipset,
    eth_address: &EthAddress,
) -> Result<EthBytes, ServerError> {
    let to_address = FilecoinAddress::try_from(eth_address)?;
    let TipsetState { state_root, .. } = ctx.state_manager.load_tipset_state(ts).await?;
    let Some(actor) = ctx
        .state_manager
        .get_actor(&to_address, state_root)
        .with_context(|| format!("failed to lookup contract {}", eth_address.0))?
    else {
        return Ok(Default::default());
    };

    Ok(actor.eth_bytecode(ctx.db())?.unwrap_or_default())
}

pub enum EthGetStorageAt {}
impl RpcMethod<3> for EthGetStorageAt {
    const NAME: &'static str = "Filecoin.EthGetStorageAt";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getStorageAt");
    const PARAM_NAMES: [&'static str; 3] = ["ethAddress", "position", "blockNumberOrHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Retrieves the storage value at a specific position for a contract
        at a given block state, identified by its number, hash, or a special tag.";

    type Params = (EthAddress, EthBytes, BlockNumberOrHash);
    type Ok = EthBytes;

    async fn handle(
        ctx: Ctx,
        (eth_address, position, block_number_or_hash): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_number_or_hash, ResolveNullTipset::TakeOlder)
            .await?;
        eth_get_storage_at(&ctx, &ts, eth_address, position).await
    }
}

async fn eth_get_storage_at(
    ctx: &Ctx,
    ts: &Tipset,
    eth_address: EthAddress,
    position: EthBytes,
) -> Result<EthBytes, ServerError> {
    // Validate and left-pad before touching state, as Lotus does.
    let position = GetStorageAtParams::new(position.0)?.0;
    let to_address = FilecoinAddress::try_from(&eth_address)?;
    let TipsetState { state_root, .. } = ctx.state_manager.load_tipset_state(ts).await?;
    let value = match ctx
        .state_manager
        .get_actor(&to_address, state_root)
        .with_context(|| format!("failed to lookup contract {}", eth_address.0))?
    {
        Some(actor) => actor.eth_storage_at(ctx.db(), &position)?,
        None => [0; EVM_WORD_LENGTH],
    };
    Ok(EthBytes(value.to_vec()))
}

pub enum EthGetTransactionCount {}
impl RpcMethod<2> for EthGetTransactionCount {
    const NAME: &'static str = "Filecoin.EthGetTransactionCount";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionCount");
    const PARAM_NAMES: [&'static str; 2] = ["sender", "blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the number of transactions sent from an address (its nonce) at the specified block state.";

    type Params = (EthAddress, BlockNumberOrHash);
    type Ok = EthUint64;

    async fn handle(
        ctx: Ctx,
        (sender, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let addr = sender.to_filecoin_address()?;
        match block_param {
            BlockNumberOrHash::PredefinedBlock(Predefined::Pending) => {
                Ok(EthUint64(ctx.mpool.get_sequence(&addr).await?))
            }
            _ => {
                let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
                let ts = resolver
                    .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
                    .await?;
                eth_get_transaction_count(&ctx, &ts, addr).await
            }
        }
    }
}

async fn eth_get_transaction_count(
    ctx: &Ctx,
    ts: &Tipset,
    addr: FilecoinAddress,
) -> Result<EthUint64, ServerError> {
    let TipsetState { state_root, .. } = ctx.state_manager.load_tipset_state(ts).await?;

    let state_tree = ctx.state_manager.get_state_tree(&state_root)?;
    let actor = match state_tree.get_actor(&addr)? {
        Some(actor) => actor,
        None => return Ok(EthUint64(0)),
    };

    Ok(actor.eth_nonce(ctx.db())?)
}

pub enum EthMaxPriorityFeePerGas {}
impl RpcMethod<0> for EthMaxPriorityFeePerGas {
    const NAME: &'static str = "Filecoin.EthMaxPriorityFeePerGas";
    const NAME_ALIAS: Option<&'static str> = Some("eth_maxPriorityFeePerGas");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns an estimate of the priority fee per gas (tip) needed for timely inclusion, in attoFIL.";

    type Params = ();
    type Ok = EthBigInt;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        match gas::estimate_gas_premium(&ctx, 0, &ApiTipsetKey(None)).await {
            Ok(gas_premium) => Ok(gas_premium.atto().into()),
            Err(_) => Ok(EthBigInt::default()),
        }
    }
}

pub enum EthProtocolVersion {}
impl RpcMethod<0> for EthProtocolVersion {
    const NAME: &'static str = "Filecoin.EthProtocolVersion";
    const NAME_ALIAS: Option<&'static str> = Some("eth_protocolVersion");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the current Filecoin network version, reported as the Ethereum protocol version.";

    type Params = ();
    type Ok = EthUint64;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let epoch = ctx.chain_store().heaviest_tipset().epoch();
        let version = u32::from(ctx.state_manager.get_network_version(epoch).0);
        Ok(EthUint64(version.into()))
    }
}

pub enum EthGetTransactionByBlockNumberAndIndex {}
impl RpcMethod<2> for EthGetTransactionByBlockNumberAndIndex {
    const NAME: &'static str = "Filecoin.EthGetTransactionByBlockNumberAndIndex";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionByBlockNumberAndIndex");
    const PARAM_NAMES: [&'static str; 2] = ["blockParam", "txIndex"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Retrieves a transaction by its block number and index.";

    type Params = (BlockNumberOrPredefined, EthUint64);
    type Ok = Option<ApiEthTx>;

    async fn handle(
        ctx: Ctx,
        (block_param, tx_index): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::Fail)
            .await?;
        eth_tx_by_tipset_and_idx(&ctx, &ts, tx_index).await
    }
}

async fn eth_tx_by_tipset_and_idx(
    ctx: &Ctx,
    ts: &Tipset,
    tx_index: EthUint64,
) -> Result<Option<ApiEthTx>, ServerError> {
    let messages = ctx.chain_store().messages_for_tipset(ts)?;

    let EthUint64(index) = tx_index;
    let msg = messages.get(index as usize).with_context(|| {
        format!(
            "transaction index {index} out of range: tipset contains {} messages",
            messages.len()
        )
    })?;

    // Resolve addresses against the tipset's post-execution state so that newly created actors
    // are included correctly.
    let TipsetState { state_root, .. } = ctx.state_manager.load_tipset_state(ts).await?;
    let state = ctx.state_manager.get_state_tree(&state_root)?;

    let tx = new_eth_tx(ctx, &state, ts.epoch(), &ts.key().cid()?, &msg.cid(), index)?;

    Ok(Some(tx))
}

pub enum EthGetTransactionByBlockHashAndIndex {}
impl RpcMethod<2> for EthGetTransactionByBlockHashAndIndex {
    const NAME: &'static str = "Filecoin.EthGetTransactionByBlockHashAndIndex";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionByBlockHashAndIndex");
    const PARAM_NAMES: [&'static str; 2] = ["blockHash", "txIndex"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Retrieves a transaction by its block hash and index.";

    type Params = (EthHash, EthUint64);
    type Ok = Option<ApiEthTx>;

    async fn handle(
        ctx: Ctx,
        (block_hash, tx_index): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let ts = get_tipset_from_hash(ctx.chain_store(), &block_hash)?;
        eth_tx_by_tipset_and_idx(&ctx, &ts, tx_index).await
    }
}

pub enum EthGetTransactionByHash {}
impl RpcMethod<1> for EthGetTransactionByHash {
    const NAME: &'static str = "Filecoin.EthGetTransactionByHash";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionByHash");
    const PARAM_NAMES: [&'static str; 1] = ["txHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Retrieves a transaction by its hash.";

    type Params = (EthHash,);
    type Ok = Option<ApiEthTx>;

    async fn handle(
        ctx: Ctx,
        (tx_hash,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let cancellation_token = CancellationToken::new();
        let _drop_guard = cancellation_token.drop_guard_ref();
        get_eth_transaction_by_hash(&ctx, &tx_hash, None, &cancellation_token).await
    }
}

pub enum EthGetTransactionByHashLimited {}
impl RpcMethod<2> for EthGetTransactionByHashLimited {
    const NAME: &'static str = "Filecoin.EthGetTransactionByHashLimited";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionByHashLimited");
    const PARAM_NAMES: [&'static str; 2] = ["txHash", "limit"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Retrieves a transaction by its hash, limiting state resolution to the given chain epoch.";

    type Params = (EthHash, ChainEpoch);
    type Ok = Option<ApiEthTx>;

    async fn handle(
        ctx: Ctx,
        (tx_hash, limit): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let cancellation_token = CancellationToken::new();
        let _drop_guard = cancellation_token.drop_guard_ref();
        get_eth_transaction_by_hash(&ctx, &tx_hash, Some(limit), &cancellation_token).await
    }
}

async fn get_eth_transaction_by_hash(
    ctx: &Ctx,
    tx_hash: &EthHash,
    limit: Option<ChainEpoch>,
    cancellation_token: &CancellationToken,
) -> Result<Option<ApiEthTx>, ServerError> {
    let message_cid = ctx.chain_store().get_mapping(tx_hash)?.unwrap_or_else(|| {
        tracing::debug!(
            "could not find transaction hash {} in Ethereum mapping",
            tx_hash
        );
        // This isn't an eth transaction we have the mapping for, so let's look it up as a filecoin message
        tx_hash.to_cid()
    });

    // First, try to get the cid from mined transactions
    if let Ok(Some((tipset, receipt))) = ctx
        .state_manager
        .search_for_message(None, message_cid, limit, Some(true), cancellation_token)
        .await
    {
        let ipld = receipt.return_data().deserialize().unwrap_or(Ipld::Null);
        let message_lookup = MessageLookup {
            receipt,
            tipset: tipset.key().clone(),
            height: tipset.epoch(),
            message: message_cid,
            return_dec: ipld,
        };

        if let Ok(tx) = new_eth_tx_from_message_lookup(ctx, &message_lookup, None) {
            return Ok(Some(tx));
        }
    }

    // If not found, try to get it from the mempool
    let (pending, _) = ctx.mpool.pending();

    if let Some(smsg) = pending.iter().find(|item| item.cid() == message_cid) {
        // We only return pending eth-account messages because we can't guarantee
        // that the from/to addresses of other messages are conversable to 0x-style
        // addresses. So we just ignore them.
        //
        // This should be "fine" as anyone using an "Ethereum-centric" block
        // explorer shouldn't care about seeing pending messages from native
        // accounts.
        if let Ok(eth_tx) = EthTx::from_signed_message(ctx.chain_config().eth_chain_id, smsg) {
            return Ok(Some(eth_tx.into()));
        }
    }

    // Ethereum clients expect an empty response when the message was not found
    Ok(None)
}

pub enum EthGetTransactionHashByCid {}

impl EthGetTransactionHashByCid {
    fn run(db: &DbImpl, eth_chain_id: EthChainIdType, cid: Cid) -> anyhow::Result<Option<EthHash>> {
        let smsgs_result: Result<Vec<SignedMessage>, crate::chain::Error> =
            crate::chain::messages_from_cids(db, &[cid]);
        if let Ok(smsgs) = smsgs_result
            && let Some(smsg) = smsgs.first()
        {
            return Ok(Some(eth_tx_hash_from_signed_message(smsg, eth_chain_id)?));
        }

        let msg_result = crate::chain::get_chain_message(db, &cid);
        if let Ok(msg) = msg_result {
            return Ok(Some(msg.cid().into()));
        }

        Ok(None)
    }
}

impl RpcMethod<1> for EthGetTransactionHashByCid {
    const NAME: &'static str = "Filecoin.EthGetTransactionHashByCid";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionHashByCid");
    const PARAM_NAMES: [&'static str; 1] = ["cid"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the Ethereum transaction hash for the given Filecoin message CID.";

    type Params = (Cid,);
    type Ok = Option<EthHash>;

    async fn handle(
        ctx: Ctx,
        (cid,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        Ok(Self::run(ctx.db(), ctx.chain_config().eth_chain_id, cid)?)
    }
}

pub enum EthCall {}
impl RpcMethod<2> for EthCall {
    const NAME: &'static str = "Filecoin.EthCall";
    const NAME_ALIAS: Option<&'static str> = Some("eth_call");
    const N_REQUIRED_PARAMS: usize = 2;
    const PARAM_NAMES: [&'static str; 2] = ["tx", "blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Executes a read-only message call against the given block state without creating an on-chain transaction, returning the call output.";
    type Params = (EthCallMessage, BlockNumberOrHash);
    type Ok = EthBytes;
    async fn handle(
        ctx: Ctx,
        (tx, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
            .await?;
        eth_call(&ctx, tx, ts).await
    }
}

async fn eth_call(ctx: &Ctx, tx: EthCallMessage, ts: Tipset) -> Result<EthBytes, ServerError> {
    let msg = Message::try_from(tx)?;
    let invoke_result = apply_message(ctx, Some(&ts), &msg).await?;

    if msg.to() == FilecoinAddress::ETHEREUM_ACCOUNT_MANAGER_ACTOR {
        Ok(EthBytes::default())
    } else {
        let msg_rct = invoke_result.msg_rct.context("no message receipt")?;
        let return_data = msg_rct.return_data();
        if return_data.is_empty() {
            Ok(Default::default())
        } else {
            let bytes = decode_payload(&return_data, CBOR)?;
            Ok(bytes)
        }
    }
}

pub enum EthNewFilter {}
impl RpcMethod<1> for EthNewFilter {
    const NAME: &'static str = "Filecoin.EthNewFilter";
    const NAME_ALIAS: Option<&'static str> = Some("eth_newFilter");
    const PARAM_NAMES: [&'static str; 1] = ["filterSpec"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Installs a persistent filter for matching event logs based on the given filter spec.";

    type Params = (EthFilterSpec,);
    type Ok = FilterID;

    async fn handle(
        ctx: Ctx,
        (filter_spec,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let eth_event_handler = ctx.eth_event_handler.clone();
        let chain_height = ctx.chain_store().heaviest_tipset().epoch();
        Ok(eth_event_handler.eth_new_filter(&filter_spec, chain_height)?)
    }
}

pub enum EthNewPendingTransactionFilter {}
impl RpcMethod<0> for EthNewPendingTransactionFilter {
    const NAME: &'static str = "Filecoin.EthNewPendingTransactionFilter";
    const NAME_ALIAS: Option<&'static str> = Some("eth_newPendingTransactionFilter");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Installs a persistent filter that tracks new messages arriving in the message pool.";

    type Params = ();
    type Ok = FilterID;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let eth_event_handler = ctx.eth_event_handler.clone();
        Ok(eth_event_handler.eth_new_pending_transaction_filter()?)
    }
}

pub enum EthNewBlockFilter {}
impl RpcMethod<0> for EthNewBlockFilter {
    const NAME: &'static str = "Filecoin.EthNewBlockFilter";
    const NAME_ALIAS: Option<&'static str> = Some("eth_newBlockFilter");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Installs a persistent filter that tracks the arrival of new blocks.";

    type Params = ();
    type Ok = FilterID;

    async fn handle(
        ctx: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let eth_event_handler = ctx.eth_event_handler.clone();

        Ok(eth_event_handler.eth_new_block_filter()?)
    }
}

pub enum EthUninstallFilter {}
impl RpcMethod<1> for EthUninstallFilter {
    const NAME: &'static str = "Filecoin.EthUninstallFilter";
    const NAME_ALIAS: Option<&'static str> = Some("eth_uninstallFilter");
    const PARAM_NAMES: [&'static str; 1] = ["filterId"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Uninstalls the filter with the given ID.";

    type Params = (FilterID,);
    type Ok = bool;

    async fn handle(
        ctx: Ctx,
        (filter_id,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let eth_event_handler = ctx.eth_event_handler.clone();

        Ok(eth_event_handler.eth_uninstall_filter(&filter_id)?)
    }
}

pub enum EthUnsubscribe {}
impl RpcMethod<0> for EthUnsubscribe {
    const NAME: &'static str = "Filecoin.EthUnsubscribe";
    const NAME_ALIAS: Option<&'static str> = Some("eth_unsubscribe");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Cancels an existing websocket subscription identified by its subscription ID.";
    const SUBSCRIPTION: bool = true;

    type Params = ();
    type Ok = ();

    // This method is a placeholder and is never actually called.
    // Subscription handling is performed in [`pubsub.rs`](pubsub).
    //
    // We still need to implement the [`RpcMethod`] trait to expose method metadata
    // like [`NAME`](Self::NAME), [`NAME_ALIAS`](Self::NAME_ALIAS), [`PERMISSION`](Self::PERMISSION), etc..
    async fn handle(
        _: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        Ok(())
    }
}

pub enum EthSubscribe {}
impl RpcMethod<0> for EthSubscribe {
    const NAME: &'static str = "Filecoin.EthSubscribe";
    const NAME_ALIAS: Option<&'static str> = Some("eth_subscribe");
    const PARAM_NAMES: [&'static str; 0] = [];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Creates a websocket subscription that streams events (new heads, pending transactions, or logs) to the client.";
    const SUBSCRIPTION: bool = true;

    type Params = ();
    type Ok = ();

    // This method is a placeholder and is never actually called.
    // Subscription handling is performed in [`pubsub.rs`](pubsub).
    //
    // We still need to implement the [`RpcMethod`] trait to expose method metadata
    // like [`NAME`](Self::NAME), [`NAME_ALIAS`](Self::NAME_ALIAS), [`PERMISSION`](Self::PERMISSION), etc..
    async fn handle(
        _: Ctx,
        (): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        Ok(())
    }
}

pub enum EthAddressToFilecoinAddress {}
impl RpcMethod<1> for EthAddressToFilecoinAddress {
    const NAME: &'static str = "Filecoin.EthAddressToFilecoinAddress";
    const PARAM_NAMES: [&'static str; 1] = ["ethAddress"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Converts an EthAddress into an f410 Filecoin Address";
    type Params = (EthAddress,);
    type Ok = FilecoinAddress;
    async fn handle(
        _ctx: Ctx,
        (eth_address,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        Ok(eth_address.to_filecoin_address()?)
    }
}

pub enum FilecoinAddressToEthAddress {}
impl RpcMethod<2> for FilecoinAddressToEthAddress {
    const NAME: &'static str = "Filecoin.FilecoinAddressToEthAddress";
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 2] = ["filecoinAddress", "blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Converts any Filecoin address to an EthAddress";
    type Params = (FilecoinAddress, Option<BlockNumberOrPredefined>);
    type Ok = EthAddress;
    async fn handle(
        ctx: Ctx,
        (address, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        if let Ok(eth_address) = EthAddress::from_filecoin_address(&address) {
            Ok(eth_address)
        } else {
            let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
            // Default to Finalized for Lotus parity
            let block_param = block_param.unwrap_or_else(|| Predefined::Finalized.into());
            let ts = resolver
                .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
                .await?;

            let id_address = ctx.state_manager.lookup_required_id(&address, &ts)?;
            Ok(EthAddress::from_filecoin_address(&id_address)?)
        }
    }
}

#[derive(Clone, Debug, GetSize)]
struct CachedReceipt {
    // `None` means "not found" by a full search.
    receipt: Option<EthTxReceipt>,
    // Head this result was computed against. Mutable entries (`None` and
    // non-final receipts) are only valid while the head is unchanged.
    head_key: TipsetKey,
    // A finalized receipt is immutable, so it is never invalidated.
    finalized: bool,
}

fn is_finalized(ctx: &Ctx, head_epoch: ChainEpoch, receipt_epoch: ChainEpoch) -> bool {
    receipt_epoch <= head_epoch - ctx.chain_config().policy.chain_finality
}

async fn get_eth_transaction_receipt_with_cache(
    ctx: Ctx,
    tx_hash: EthHash,
    limit: Option<ChainEpoch>,
    cancellation_token: &CancellationToken,
) -> Result<Option<EthTxReceipt>, ServerError> {
    static CACHE: LazyLock<SizeTrackingCache<EthHash, CachedReceipt>> = LazyLock::new(|| {
        const DEFAULT_CACHE_SIZE: NonZeroUsize = nonzero!(10000usize); // ~12.5MiB on mainnet
        let cache_size = env_or_default(
            "FOREST_ETH_TRANSACTION_RECEIPT_CACHE_SIZE",
            DEFAULT_CACHE_SIZE,
        );
        SizeTrackingCache::new_with_metrics("eth_transaction_receipt", cache_size)
    });

    let head = ctx.chain_store().heaviest_tipset();
    let head_key = head.key().clone();
    let head_epoch = head.epoch();

    // Drop stale mutable entries so they are recomputed at the new head.
    CACHE.remove_if(&tx_hash, |e| !e.finalized && e.head_key != head_key);

    enum Uncacheable {
        // A bounded search found nothing; the receipt may still exist.
        NotFoundWithinLimit,
        Error(ServerError),
    }

    let receipt = match CACHE
        .get_or_insert_async(&tx_hash, {
            let ctx = ctx.shallow_clone();
            let head_key = head_key.clone();
            async move {
                let receipt = get_eth_transaction_receipt(
                    ctx.shallow_clone(),
                    tx_hash,
                    limit,
                    cancellation_token,
                )
                .await
                .map_err(Uncacheable::Error)?;
                if receipt.is_none() && limit.is_some_and(|limit| limit > 0) {
                    return Err(Uncacheable::NotFoundWithinLimit);
                }
                let finalized = receipt
                    .as_ref()
                    .is_some_and(|r| is_finalized(&ctx, head.epoch(), r.block_number.0));
                Ok::<_, Uncacheable>(CachedReceipt {
                    receipt,
                    head_key,
                    finalized,
                })
            }
        })
        .await
    {
        Ok(CachedReceipt { receipt, .. }) => receipt,
        Err(Uncacheable::NotFoundWithinLimit) => None,
        Err(Uncacheable::Error(e)) => return Err(e),
    };

    let Some(r) = receipt else { return Ok(None) };
    let within_lookback = StateManager::max_lookback_epoch_inclusive(head_epoch, limit)
        .is_some_and(|max| r.block_number.0 >= max);
    Ok(within_lookback.then_some(r))
}

async fn get_eth_transaction_receipt(
    ctx: Ctx,
    tx_hash: EthHash,
    limit: Option<ChainEpoch>,
    cancellation_token: &CancellationToken,
) -> Result<Option<EthTxReceipt>, ServerError> {
    let msg_cid = ctx.chain_store().get_mapping(&tx_hash)?.unwrap_or_else(|| {
        tracing::debug!(
            "could not find transaction hash {} in Ethereum mapping",
            tx_hash
        );
        // This isn't an eth transaction we have the mapping for, so let's look it up as a filecoin message
        tx_hash.to_cid()
    });

    let option = ctx
        .state_manager
        .search_for_message(None, msg_cid, limit, Some(true), cancellation_token)
        .await
        .with_context(|| format!("failed to lookup Eth Txn {tx_hash} as {msg_cid}"));

    // Ethereum clients expect an empty response when the message was not found
    // or not executed yet
    let (tipset, receipt) = match option {
        Ok(Some(found)) => found,
        Ok(None) => return Ok(None),
        Err(e) => {
            tracing::debug!("could not find transaction receipt for hash {tx_hash}: {e}");
            return Ok(None);
        }
    };
    let ipld = receipt.return_data().deserialize().unwrap_or(Ipld::Null);
    let message_lookup = MessageLookup {
        receipt,
        tipset: tipset.key().clone(),
        height: tipset.epoch(),
        message: msg_cid,
        return_dec: ipld,
    };

    let tx = new_eth_tx_from_message_lookup(&ctx, &message_lookup, None)
        .with_context(|| format!("failed to convert {tx_hash} into an Eth Tx"))?;

    let ts = ctx
        .chain_index()
        .load_required_tipset(&message_lookup.tipset)?;

    // The tx is located in the parent tipset
    let parent_ts = ctx
        .chain_index()
        .load_required_tipset(ts.parents())
        .map_err(|e| {
            format!(
                "failed to lookup tipset {} when constructing the eth txn receipt: {}",
                ts.parents(),
                e
            )
        })?;

    let logs = if message_lookup.receipt.events_root().is_some() {
        eth_logs_for_block_and_transaction(&ctx, &parent_ts, &tx.block_hash, &msg_cid).await?
    } else {
        vec![]
    };
    let tx_receipt = new_eth_tx_receipt(&parent_ts, &tx, &message_lookup.receipt, logs)?;

    Ok(Some(tx_receipt))
}

pub enum EthGetTransactionReceipt {}
impl RpcMethod<1> for EthGetTransactionReceipt {
    const NAME: &'static str = "Filecoin.EthGetTransactionReceipt";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionReceipt");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 1] = ["txHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the receipt of a transaction identified by its hash.";
    type Params = (EthHash,);
    type Ok = Option<EthTxReceipt>;
    async fn handle(
        ctx: Ctx,
        (tx_hash,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let cancellation_token = CancellationToken::new();
        let _drop_guard = cancellation_token.drop_guard_ref();
        get_eth_transaction_receipt_with_cache(ctx, tx_hash, None, &cancellation_token).await
    }
}

pub enum EthGetTransactionReceiptLimited {}
impl RpcMethod<2> for EthGetTransactionReceiptLimited {
    const NAME: &'static str = "Filecoin.EthGetTransactionReceiptLimited";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getTransactionReceiptLimited");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 2] = ["txHash", "limit"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the receipt of a transaction identified by its hash, limiting state resolution to the given chain epoch.";
    type Params = (EthHash, ChainEpoch);
    type Ok = Option<EthTxReceipt>;
    async fn handle(
        ctx: Ctx,
        (tx_hash, limit): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let cancellation_token = CancellationToken::new();
        let _drop_guard = cancellation_token.drop_guard_ref();
        get_eth_transaction_receipt_with_cache(ctx, tx_hash, Some(limit), &cancellation_token).await
    }
}

pub enum EthSendRawTransaction {}
impl RpcMethod<1> for EthSendRawTransaction {
    const NAME: &'static str = "Filecoin.EthSendRawTransaction";
    const NAME_ALIAS: Option<&'static str> = Some("eth_sendRawTransaction");
    const PARAM_NAMES: [&'static str; 1] = ["rawTx"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Submits a signed raw transaction to the message pool and returns its transaction hash.";

    type Params = (EthBytes,);
    type Ok = EthHash;

    async fn handle(
        ctx: Ctx,
        (raw_tx,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let tx_args = parse_eth_transaction(&raw_tx.0)?;
        let smsg = tx_args.get_signed_message(ctx.chain_config().eth_chain_id)?;
        let cid = ctx.mpool.push(smsg).await?;
        Ok(cid.into())
    }
}

pub enum EthSendRawTransactionUntrusted {}
impl RpcMethod<1> for EthSendRawTransactionUntrusted {
    const NAME: &'static str = "Filecoin.EthSendRawTransactionUntrusted";
    const NAME_ALIAS: Option<&'static str> = Some("eth_sendRawTransactionUntrusted");
    const PARAM_NAMES: [&'static str; 1] = ["rawTx"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Submits a signed raw transaction from an untrusted source to the message pool and returns its transaction hash.";

    type Params = (EthBytes,);
    type Ok = EthHash;

    async fn handle(
        ctx: Ctx,
        (raw_tx,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let tx_args = parse_eth_transaction(&raw_tx.0)?;
        let smsg = tx_args.get_signed_message(ctx.chain_config().eth_chain_id)?;
        let cid = ctx.mpool.push_untrusted(smsg).await?;
        Ok(cid.into())
    }
}

#[derive(Clone, Debug, PartialEq)]
pub struct CollectedEvent {
    pub(crate) entries: Vec<EventEntry>,
    pub(crate) emitter_addr: crate::shim::address::Address,
    pub(crate) event_idx: u64,
    pub(crate) reverted: bool,
    pub(crate) height: ChainEpoch,
    pub(crate) tipset_key: TipsetKey,
    msg_idx: u64,
    pub(crate) msg_cid: Cid,
}

/// Positions `(message index, event index)` of collected events, grouped by tipset.
/// Identifies events without retaining their entry payloads; grouping by tipset lets
/// membership checks borrow the tipset key and stores each distinct key only once.
pub type SeenEventPositions = HashMap<TipsetKey, HashSet<(u64, u64)>>;

fn match_key(key: &str) -> Option<usize> {
    match key.get(0..2) {
        Some("t1") => Some(0),
        Some("t2") => Some(1),
        Some("t3") => Some(2),
        Some("t4") => Some(3),
        _ => None,
    }
}

fn eth_log_from_event(entries: &[EventEntry]) -> Option<(EthBytes, Vec<EthHash>)> {
    let mut topics_found = [false; 4];
    let mut topics_found_count = 0;
    let mut data_found = false;
    let mut data: EthBytes = EthBytes::default();
    let mut topics: Vec<EthHash> = Vec::default();
    for entry in entries {
        // Drop events with non-raw topics. Built-in actors emit CBOR, and anything else would be
        // invalid anyway.
        if entry.codec != IPLD_RAW {
            return None;
        }
        // Check if the key is t1..t4
        if let Some(idx) = match_key(&entry.key) {
            // Drop events with mis-sized topics.
            let result: Result<[u8; EVM_WORD_LENGTH], _> = entry.value.0.as_slice().try_into();
            let bytes = if let Ok(value) = result {
                value
            } else {
                tracing::warn!(
                    "got an EVM event topic with an invalid size (key: {}, size: {})",
                    entry.key,
                    entry.value.0.len()
                );
                return None;
            };
            // Drop events with duplicate topics.
            if *topics_found.get(idx).expect("Infallible") {
                tracing::warn!("got a duplicate EVM event topic (key: {})", entry.key);
                return None;
            }
            *topics_found.get_mut(idx).expect("Infallible") = true;
            topics_found_count += 1;
            // Extend the topics array
            if topics.len() <= idx {
                topics.resize(idx + 1, EthHash::default());
            }
            *topics.get_mut(idx).expect("Infallible") = bytes.into();
        } else if entry.key == "d" {
            // Drop events with duplicate data fields.
            if data_found {
                tracing::warn!("got duplicate EVM event data");
                return None;
            }
            data_found = true;
            data = EthBytes(entry.value.0.clone());
        } else {
            // Skip entries we don't understand (makes it easier to extend things).
            // But we warn for now because we don't expect them.
            tracing::warn!("unexpected event entry (key: {})", entry.key);
        }
    }
    // Drop events with skipped topics.
    if topics.len() != topics_found_count {
        tracing::warn!(
            "EVM event topic length mismatch (expected: {}, actual: {})",
            topics.len(),
            topics_found_count
        );
        return None;
    }
    Some((data, topics))
}

pub(crate) fn eth_tx_hash_from_signed_message(
    message: &SignedMessage,
    eth_chain_id: EthChainIdType,
) -> anyhow::Result<EthHash> {
    if message.is_delegated() {
        let (_, tx) = eth_tx_from_signed_eth_message(message, eth_chain_id)?;
        Ok(tx.eth_hash()?.into())
    } else if message.is_secp256k1() {
        Ok(message.cid().into())
    } else {
        Ok(message.message().cid().into())
    }
}

fn eth_tx_hash_from_message_cid<DB: Blockstore>(
    blockstore: &DB,
    message_cid: &Cid,
    eth_chain_id: EthChainIdType,
) -> anyhow::Result<Option<EthHash>> {
    if let Ok(smsg) = crate::chain::message_from_cid(blockstore, message_cid) {
        // This is an Eth Tx, Secp message, Or BLS message in the mpool
        return Ok(Some(eth_tx_hash_from_signed_message(&smsg, eth_chain_id)?));
    }
    let result: Result<Message, _> = crate::chain::message_from_cid(blockstore, message_cid);
    if result.is_ok() {
        // This is a BLS message
        let hash: EthHash = (*message_cid).into();
        return Ok(Some(hash));
    }
    Ok(None)
}

fn eth_filter_logs_from_tipsets(events: &[CollectedEvent]) -> anyhow::Result<Vec<EthHash>> {
    events
        .iter()
        .map(|event| event.tipset_key.cid().map(Into::into))
        .collect()
}

fn eth_filter_logs_from_events(
    ctx: &Ctx,
    events: &[CollectedEvent],
) -> anyhow::Result<Vec<EthLog>> {
    let chain_id = ctx.state_manager.chain_config().eth_chain_id;
    let mut tx_hash_by_msg: HashMap<Cid, EthHash> = HashMap::new();
    let mut block_hash_by_tipset: HashMap<TipsetKey, EthHash> = HashMap::new();
    let mut eth_addr_by_emitter: HashMap<FilecoinAddress, EthAddress> = HashMap::new();

    let mut logs = Vec::with_capacity(events.len());
    for event in events {
        let (data, topics) = match eth_log_from_event(&event.entries) {
            Some(parts) => parts,
            None => {
                tracing::debug!("Ignoring event");
                continue;
            }
        };

        let transaction_hash = if let Some(h) = tx_hash_by_msg.get(&event.msg_cid) {
            *h
        } else {
            match eth_tx_hash_from_message_cid(ctx.db(), &event.msg_cid, chain_id)? {
                Some(h) => {
                    tx_hash_by_msg.insert(event.msg_cid, h);
                    h
                }
                None => {
                    tracing::debug!("Ignoring event");
                    continue;
                }
            }
        };

        let block_hash = if let Some(h) = block_hash_by_tipset.get(&event.tipset_key) {
            *h
        } else {
            let h: EthHash = event.tipset_key.cid()?.into();
            block_hash_by_tipset.insert(event.tipset_key.clone(), h);
            h
        };

        let address = if let Some(a) = eth_addr_by_emitter.get(&event.emitter_addr) {
            *a
        } else {
            let a = EthAddress::from_filecoin_address(&event.emitter_addr)?;
            eth_addr_by_emitter.insert(event.emitter_addr, a);
            a
        };

        logs.push(EthLog {
            address,
            data,
            topics,
            removed: event.reverted,
            log_index: event.event_idx.into(),
            transaction_index: event.msg_idx.into(),
            transaction_hash,
            block_hash,
            block_number: (event.height as u64).into(),
        });
    }
    Ok(logs)
}

/// Accrues a single Ethereum log's address and topics into `bloom` using the standard `M3:2048` scheme.
fn eth_filter_result_from_events(
    ctx: &Ctx,
    events: &[CollectedEvent],
) -> anyhow::Result<EthFilterResult> {
    Ok(EthFilterResult::Logs(eth_filter_logs_from_events(
        ctx, events,
    )?))
}

fn eth_filter_result_from_tipsets(events: &[CollectedEvent]) -> anyhow::Result<EthFilterResult> {
    Ok(EthFilterResult::Hashes(eth_filter_logs_from_tipsets(
        events,
    )?))
}

pub enum EthGetLogs {}
impl RpcMethod<1> for EthGetLogs {
    const NAME: &'static str = "Filecoin.EthGetLogs";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getLogs");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 1] = ["ethFilter"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns event logs matching the given filter specification.";
    type Params = (EthFilterSpec,);
    type Ok = EthFilterResult;
    async fn handle(
        ctx: Ctx,
        (eth_filter,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let pf = Arc::new(
            ctx.eth_event_handler
                .parse_eth_filter_spec(&ctx, &eth_filter)
                .map_err(|e| {
                    if e.downcast_ref::<EthErrors>().is_some_and(|eth_err| {
                        matches!(eth_err, EthErrors::BlockRangeExceeded { .. })
                    }) {
                        return e;
                    }
                    e.context("failed to parse events for filter")
                })?,
        );
        let events = ctx
            .eth_event_handler
            .get_events_for_parsed_filter(&ctx, &pf, SkipEvent::OnUnresolvedAddress)
            .await
            .context("failed to get events for filter")?;
        Ok(eth_filter_result_from_events(&ctx, &events)?)
    }
}

/// Shared implementation of `eth_getFilterLogs` / `eth_getFilterChanges` for installed event
/// filters: collects the filter's full result set from the canonical chain, returns only the
/// events that were not present in the previous poll.
async fn poll_event_filter(
    ctx: &Ctx,
    event_filter: &EventFilter,
) -> anyhow::Result<Vec<CollectedEvent>> {
    let events = ctx
        .eth_event_handler
        .get_events_for_parsed_filter(
            ctx,
            &Arc::new(event_filter.into()),
            SkipEvent::OnUnresolvedAddress,
        )
        .await?;
    Ok(event_filter.take_unseen(events))
}

pub enum EthGetFilterLogs {}
impl RpcMethod<1> for EthGetFilterLogs {
    const NAME: &'static str = "Filecoin.EthGetFilterLogs";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getFilterLogs");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 1] = ["filterId"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Write;
    const DESCRIPTION: &'static str = "Returns event logs matching the filter with the given ID that have not been collected since the last poll.";
    type Params = (FilterID,);
    type Ok = EthFilterResult;
    async fn handle(
        ctx: Ctx,
        (filter_id,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let eth_event_handler = ctx.eth_event_handler.clone();
        if let Some(store) = &eth_event_handler.filter_store {
            let filter = store.get(&filter_id)?;
            if let Some(event_filter) = filter.as_any().downcast_ref::<EventFilter>() {
                let recent_events = poll_event_filter(&ctx, event_filter).await?;
                return Ok(eth_filter_result_from_events(&ctx, &recent_events)?);
            }
        }
        Err(anyhow::anyhow!("method not supported").into())
    }
}

pub enum EthGetFilterChanges {}
impl RpcMethod<1> for EthGetFilterChanges {
    const NAME: &'static str = "Filecoin.EthGetFilterChanges";
    const NAME_ALIAS: Option<&'static str> = Some("eth_getFilterChanges");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 1] = ["filterId"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Write;
    const DESCRIPTION: &'static str = "Returns event logs which occurred since the last poll";

    type Params = (FilterID,);
    type Ok = EthFilterResult;
    async fn handle(
        ctx: Ctx,
        (filter_id,): Self::Params,
        _: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let eth_event_handler = ctx.eth_event_handler.clone();
        if let Some(store) = &eth_event_handler.filter_store {
            let filter = store.get(&filter_id)?;
            if let Some(event_filter) = filter.as_any().downcast_ref::<EventFilter>() {
                let recent_events = poll_event_filter(&ctx, event_filter).await?;
                return Ok(eth_filter_result_from_events(&ctx, &recent_events)?);
            }
            if let Some(tipset_filter) = filter.as_any().downcast_ref::<TipSetFilter>() {
                let events = ctx
                    .eth_event_handler
                    .get_events_for_parsed_filter(
                        &ctx,
                        &Arc::new(ParsedFilter::new_with_tipset(ParsedFilterTipsets::Range(
                            // heaviest tipset doesn't have events because its messages haven't been executed yet
                            RangeInclusive::new(
                                tipset_filter.collected().unwrap_or_else(|| {
                                    ctx.chain_store().heaviest_tipset().epoch() - 1
                                }),
                                // Use -1 to indicate that the range extends until the latest available tipset.
                                -1,
                            ),
                        ))),
                        SkipEvent::OnUnresolvedAddress,
                    )
                    .await?;
                let new_collected = events
                    .iter()
                    .max_by_key(|event| event.height)
                    .map(|e| e.height);
                if let Some(height) = new_collected {
                    tipset_filter.set_collected(height);
                }
                return Ok(eth_filter_result_from_tipsets(&events)?);
            }
            if let Some(mempool_filter) = filter.as_any().downcast_ref::<MempoolFilter>() {
                return Ok(EthFilterResult::Hashes(mempool_filter.drain()));
            }
        }
        Err(anyhow::anyhow!("method not supported").into())
    }
}

pub enum EthTraceBlock {}
impl RpcMethod<1> for EthTraceBlock {
    const NAME: &'static str = "Filecoin.EthTraceBlock";
    const NAME_ALIAS: Option<&'static str> = Some("trace_block");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 1] = ["blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns traces created at given block.";

    type Params = (BlockNumberOrHash,);
    type Ok = NotNullVec<EthBlockTrace>;
    async fn handle(
        ctx: Ctx,
        (block_param,): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::Fail)
            .await?;
        eth_trace_block(&ctx.state_manager, &ts, CallSource::External)
            .await
            .map(NotNullVec)
    }
}

/// Replays a tipset and resolves every non-system transaction into a [`trace::TipsetTraceEntry`].
async fn execute_tipset_traces(
    state_manager: &StateManager,
    ts: &Tipset,
    source: CallSource,
) -> Result<(StateTree<DbImpl>, Vec<trace::TipsetTraceEntry>), ServerError> {
    let (state_root, raw_traces) = state_manager.execution_trace(ts, source).await?;
    let state = state_manager.get_state_tree(&state_root)?;

    // Resolve every non-system message's tx hash in parallel. Each lookup is
    // an independent DB read; running them sequentially adds O(N) IO
    // latency to every trace_block response.
    let raw = non_system_traces_with_positions(raw_traces).collect_vec();
    let mut entries: Vec<trace::TipsetTraceEntry> = Vec::with_capacity(raw.len());
    let mut join_set = tokio::task::JoinSet::new();
    let db = state_manager.db();
    let eth_chain_id = state_manager.chain_config().eth_chain_id;
    for (msg_position, invoc_result) in raw {
        let db = db.shallow_clone();
        join_set.spawn_blocking(move || {
            let tx_hash = EthGetTransactionHashByCid::run(&db, eth_chain_id, invoc_result.msg_cid)?
                .with_context(|| {
                    format!(
                        "cannot find transaction hash for cid {}",
                        invoc_result.msg_cid
                    )
                })?;
            anyhow::Ok(trace::TipsetTraceEntry {
                tx_hash,
                msg_position,
                invoc_result,
            })
        });
    }
    while let Some(joined) = join_set.join_next().await {
        entries.push(joined.context("trace tx-hash task panicked")??);
    }
    entries.sort_by_key(|e| e.msg_position);

    Ok((state, entries))
}

/// Yields non-system traces paired with 0-indexed positions matching
/// `transactionIndex` from `eth_getBlockByNumber`. System-actor messages
/// are filtered out without consuming a position.
fn non_system_traces_with_positions(
    raw_traces: impl IntoIterator<Item = Arc<ApiInvocResult>>,
) -> impl Iterator<Item = (i64, Arc<ApiInvocResult>)> {
    raw_traces
        .into_iter()
        .filter(|ir| ir.msg.from != system::ADDRESS.into())
        .enumerate()
        .map(|(idx, ir)| (idx as i64, ir))
}

/// Builds the Parity-style block traces for `ts`, caching the result by tipset.
/// Unlike [`StateManager::execution_trace`], this also caches the tx-hash
/// lookups and parity-trace construction.
pub(crate) async fn eth_trace_block(
    state_manager: &StateManager,
    ts: &Tipset,
    source: CallSource,
) -> Result<Vec<EthBlockTrace>, ServerError> {
    // 64 most-recent blocks; bounded by count, not bytes (a few MiB on mainnet,
    // see the `cache_eth_trace_block_size` metric).
    const ETH_TRACE_BLOCK_CACHE_SIZE: NonZeroUsize = nonzero!(64usize);
    static ETH_TRACE_BLOCK_CACHE: LazyLock<SizeTrackingCache<CidWrapper, Arc<Vec<EthBlockTrace>>>> =
        LazyLock::new(|| {
            SizeTrackingCache::new_with_metrics("eth_trace_block", ETH_TRACE_BLOCK_CACHE_SIZE)
        });

    let block_cid = ts.key().cid()?;
    let traces = ETH_TRACE_BLOCK_CACHE
        .get_or_insert_async(&CidWrapper::from(block_cid), async move {
            let (state, entries) = execute_tipset_traces(state_manager, ts, source).await?;
            let block_hash: EthHash = block_cid.into();
            let mut all_traces = vec![];

            for entry in entries {
                for trace in entry.build_parity_traces(&state)? {
                    all_traces.push(EthBlockTrace {
                        trace,
                        block_hash,
                        block_number: ts.epoch(),
                        transaction_hash: entry.tx_hash,
                        transaction_position: entry.msg_position,
                    });
                }
            }
            anyhow::Ok(Arc::new(all_traces))
        })
        .await?;
    Ok(Arc::unwrap_or_clone(traces))
}

pub enum EthDebugTraceTransaction {}
impl RpcMethod<2> for EthDebugTraceTransaction {
    const N_REQUIRED_PARAMS: usize = 1;
    const NAME: &'static str = "Forest.EthDebugTraceTransaction";
    const NAME_ALIAS: Option<&'static str> = Some("debug_traceTransaction");
    const PARAM_NAMES: [&'static str; 2] = ["txHash", "opts"];
    const API_PATHS: BitFlags<ApiPaths> = make_bitflags!(ApiPaths::{ V1 | V2 });
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Replays a transaction and returns execution traces in Geth-compatible format.";

    type Params = (String, Option<GethDebugTracingOptions>);
    type Ok = GethTrace;

    async fn handle(
        ctx: Ctx,
        (tx_hash, opts): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let opts = opts.unwrap_or_default();
        let cancellation_token = CancellationToken::new();
        let _drop_guard = cancellation_token.drop_guard_ref();
        debug_trace_transaction(
            ctx,
            Self::api_path(ext)?,
            tx_hash,
            opts,
            &cancellation_token,
            CallSource::External,
        )
        .await
    }
}

async fn debug_trace_transaction(
    ctx: Ctx,
    api_path: ApiPaths,
    tx_hash: String,
    opts: GethDebugTracingOptions,
    cancellation_token: &CancellationToken,
    source: CallSource,
) -> Result<GethTrace, ServerError> {
    let tracer = match &opts.tracer {
        Some(t) => t.clone(),
        None => {
            tracing::debug!(
                "no tracer specified for debug_traceTransaction; defaulting to callTracer (struct logger not supported)"
            );
            GethDebugBuiltInTracerType::Call
        }
    };

    let eth_hash = EthHash::from_str(&tx_hash).context("invalid transaction hash")?;
    let eth_txn = get_eth_transaction_by_hash(&ctx, &eth_hash, None, cancellation_token)
        .await?
        .ok_or_else(|| ServerError::internal_error("transaction not found", None))?;

    // Mempool/pending transactions cannot be traced — they have no containing tipset.
    if eth_txn.block_hash == EthHash::default() {
        return Err(ServerError::invalid_params(
            "no trace for pending transactions",
            None,
        ));
    }

    if tracer == GethDebugBuiltInTracerType::Noop {
        return Ok(GethTrace::Noop(NoopFrame {}));
    }

    let resolver = TipsetResolver::new(&ctx, api_path);
    let ts = resolver
        .tipset_by_block_number_or_hash(eth_txn.block_number, ResolveNullTipset::TakeOlder)
        .await?;

    // prestateTracer uses per-message replay for exact state boundaries,
    // so it does not need the full tipset trace.
    if tracer == GethDebugBuiltInTracerType::PreState {
        let prestate_config = opts.prestate_config()?;

        let message_cid = ctx
            .chain_store()
            .get_mapping(&eth_hash)?
            .unwrap_or_else(|| eth_hash.to_cid());

        let (pre_root, invoc_result, post_root) = ctx
            .state_manager
            .replay_for_prestate(ts.shallow_clone(), message_cid)
            .await
            .map_err(|e| anyhow::anyhow!("replay for prestate failed: {e}"))?;

        let execution_trace = invoc_result
            .execution_trace
            .context("no execution trace for transaction")?;

        let mut touched = extract_touched_eth_addresses(&execution_trace);
        if let Ok(addr) = EthAddress::from_filecoin_address(&invoc_result.msg.from()) {
            touched.insert(addr);
        }

        if let Ok(addr) = EthAddress::from_filecoin_address(&invoc_result.msg.to()) {
            touched.insert(addr);
        }

        let pre_state = StateTree::new_from_root(ctx.db(), &pre_root)?;
        let post_state = StateTree::new_from_root(ctx.db(), &post_root)?;

        let frame = trace::build_prestate_frame(
            ctx.db(),
            &pre_state,
            &post_state,
            &touched,
            &prestate_config,
        )?;

        return Ok(GethTrace::PreState(frame));
    }

    let (state, entries) = execute_tipset_traces(&ctx.state_manager, &ts, source).await?;
    let entry = entries
        .into_iter()
        .find(|e| e.tx_hash == eth_hash)
        .ok_or_else(|| ServerError::internal_error("transaction trace not found in block", None))?;

    let execution_trace = entry
        .invoc_result
        .execution_trace
        .clone()
        .context("no execution trace for transaction")?;

    let mut env = trace::base_environment(&state, &entry.invoc_result.msg.from).map_err(|e| {
        anyhow::anyhow!(
            "when processing message {}: {e}",
            entry.invoc_result.msg_cid
        )
    })?;

    match tracer {
        GethDebugBuiltInTracerType::Call => {
            let call_config = opts.call_config()?;
            let frame = trace::build_geth_call_frame(&mut env, execution_trace, &call_config)?;
            Ok(GethTrace::Call(frame.unwrap_or_default()))
        }
        GethDebugBuiltInTracerType::FlatCall => {
            trace::build_traces(&mut env, &[], execution_trace)?;
            let block_hash: EthHash = ts.key().cid()?.into();
            let traces = env
                .traces
                .into_iter()
                .map(|t| EthBlockTrace {
                    trace: t,
                    block_hash,
                    block_number: ts.epoch(),
                    transaction_hash: eth_hash,
                    transaction_position: entry.msg_position,
                })
                .collect();
            Ok(GethTrace::FlatCall(traces))
        }
        _ => Err(anyhow::anyhow!(
            "unexpected tracer type: noopTracer and prestateTracer should be handled above"
        )
        .into()),
    }
}

pub enum EthTraceCall {}
impl RpcMethod<3> for EthTraceCall {
    const NAME: &'static str = "Forest.EthTraceCall";
    const NAME_ALIAS: Option<&'static str> = Some("trace_call");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 3] = ["tx", "traceTypes", "blockParam"];
    const API_PATHS: BitFlags<ApiPaths> = make_bitflags!(ApiPaths::{ V1 | V2 });
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns parity style trace results for the given transaction.";

    type Params = (
        EthCallMessage,
        NonEmpty<EthTraceType>,
        Option<BlockNumberOrHash>,
    );
    type Ok = EthTraceResults;
    async fn handle(
        ctx: Ctx,
        (tx, trace_types, block_param): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let msg = Message::try_from(tx)?;
        let block_param = block_param.unwrap_or_else(|| Predefined::Latest.into());
        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::TakeOlder)
            .await?;

        let TipsetState {
            state_root: pre_state_root,
            ..
        } = ctx
            .state_manager
            .load_tipset_state(&ts)
            .await
            .context("failed to get tipset state")?;
        let pre_state = StateTree::new_from_root(ctx.db(), &pre_state_root)?;

        let (invoke_result, post_state_root) = ctx
            .state_manager
            .apply_on_state_with_gas(
                Some(&ts),
                &msg,
                VMFlush::Flush,
                VMTrace::Traced,
                SenderValidation::Enforce,
            )
            .await
            .context("failed to apply message")?;
        let post_state_root =
            post_state_root.context("post-execution state root required for trace call")?;
        let post_state = StateTree::new_from_root(ctx.db(), &post_state_root)?;

        let mut trace_results = EthTraceResults {
            output: get_trace_output(&msg, &invoke_result)?,
            ..Default::default()
        };

        // Extract touched addresses for state diff (do this before consuming exec_trace)
        let touched_addresses = invoke_result
            .execution_trace
            .as_ref()
            .map(extract_touched_eth_addresses)
            .unwrap_or_default();

        // Build call traces if requested
        if trace_types.contains(&EthTraceType::Trace)
            && let Some(exec_trace) = invoke_result.execution_trace
        {
            let mut env = trace::base_environment(&post_state, &msg.from())
                .context("failed to create trace environment")?;
            trace::build_traces(&mut env, &[], exec_trace)?;
            trace_results.trace = env.traces;
        }

        // Build state diff if requested
        if trace_types.contains(&EthTraceType::StateDiff) {
            // Add the caller address to touched addresses
            let mut all_touched = touched_addresses;
            if let Ok(caller_eth) = EthAddress::from_filecoin_address(&msg.from()) {
                all_touched.insert(caller_eth);
            }
            if let Ok(to_eth) = EthAddress::from_filecoin_address(&msg.to()) {
                all_touched.insert(to_eth);
            }

            let state_diff =
                trace::build_state_diff(ctx.db(), &pre_state, &post_state, &all_touched)?;
            trace_results.state_diff = Some(state_diff);
        }

        Ok(trace_results)
    }
}

/// Get output bytes from trace execution result.
fn get_trace_output(msg: &Message, invoke_result: &ApiInvocResult) -> Result<EthBytes> {
    if msg.to() == FilecoinAddress::ETHEREUM_ACCOUNT_MANAGER_ACTOR {
        return Ok(EthBytes::default());
    }

    let msg_rct = invoke_result
        .msg_rct
        .as_ref()
        .context("missing message receipt")?;
    let return_data = msg_rct.return_data();

    if return_data.is_empty() {
        return Ok(EthBytes::default());
    }

    decode_payload(&return_data, CBOR).context("failed to decode return data")
}

/// Extract all unique Ethereum addresses touched during execution from the trace.
fn extract_touched_eth_addresses(trace: &crate::rpc::state::ExecutionTrace) -> HashSet<EthAddress> {
    let mut addresses = HashSet::default();
    let mut stack = vec![trace];

    while let Some(current) = stack.pop() {
        if let Ok(eth_addr) = EthAddress::from_filecoin_address(&current.msg.from) {
            addresses.insert(eth_addr);
        }
        if let Ok(eth_addr) = EthAddress::from_filecoin_address(&current.msg.to) {
            addresses.insert(eth_addr);
        }
        stack.extend(&current.subcalls);
    }

    addresses
}

pub enum EthTraceTransaction {}
impl RpcMethod<1> for EthTraceTransaction {
    const NAME: &'static str = "Filecoin.EthTraceTransaction";
    const NAME_ALIAS: Option<&'static str> = Some("trace_transaction");
    const N_REQUIRED_PARAMS: usize = 1;
    const PARAM_NAMES: [&'static str; 1] = ["txHash"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str = "Returns the traces for a specific transaction.";

    type Params = (String,);
    type Ok = NotNullVec<EthBlockTrace>;
    async fn handle(
        ctx: Ctx,
        (tx_hash,): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let cancellation_token = CancellationToken::new();
        let _drop_guard = cancellation_token.drop_guard_ref();
        let eth_hash = EthHash::from_str(&tx_hash).context("invalid transaction hash")?;
        let eth_txn = get_eth_transaction_by_hash(&ctx, &eth_hash, None, &cancellation_token)
            .await?
            .ok_or_else(|| ServerError::internal_error("transaction not found", None))?;

        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(eth_txn.block_number, ResolveNullTipset::TakeOlder)
            .await?;

        let traces = eth_trace_block(&ctx.state_manager, &ts, CallSource::External)
            .await?
            .into_iter()
            .filter(|trace| trace.transaction_hash == eth_hash)
            .collect();
        Ok(NotNullVec(traces))
    }
}

pub enum EthTraceReplayBlockTransactions {}
impl RpcMethod<2> for EthTraceReplayBlockTransactions {
    const N_REQUIRED_PARAMS: usize = 2;
    const NAME: &'static str = "Filecoin.EthTraceReplayBlockTransactions";
    const NAME_ALIAS: Option<&'static str> = Some("trace_replayBlockTransactions");
    const PARAM_NAMES: [&'static str; 2] = ["blockParam", "traceTypes"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Replays all transactions in a block returning the requested traces for each transaction.";

    type Params = (BlockNumberOrHash, Vec<String>);
    type Ok = NotNullVec<EthReplayBlockTransactionTrace>;

    async fn handle(
        ctx: Ctx,
        (block_param, trace_types): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        if trace_types.as_slice() != ["trace"] {
            return Err(ServerError::invalid_params(
                "only 'trace' is supported",
                None,
            ));
        }

        let resolver = TipsetResolver::new(&ctx, Self::api_path(ext)?);
        let ts = resolver
            .tipset_by_block_number_or_hash(block_param, ResolveNullTipset::Fail)
            .await?;

        eth_trace_replay_block_transactions(&ctx, &ts, CallSource::External)
            .await
            .map(NotNullVec)
    }
}

async fn eth_trace_replay_block_transactions(
    ctx: &Ctx,
    ts: &Tipset,
    source: CallSource,
) -> Result<Vec<EthReplayBlockTransactionTrace>, ServerError> {
    let (state, entries) = execute_tipset_traces(&ctx.state_manager, ts, source).await?;

    let mut all_traces = vec![];
    for entry in entries {
        let traces = entry.build_parity_traces(&state)?;
        all_traces.push(EthReplayBlockTransactionTrace {
            full_trace: EthTraceResults::from_parity_traces(traces),
            transaction_hash: entry.tx_hash,
            vm_trace: None,
        });
    }

    Ok(all_traces)
}

async fn get_eth_block_number_from_string(
    ctx: &Ctx,
    block: Option<&str>,
    resolve: ResolveNullTipset,
    api_path: ApiPaths,
) -> Result<EthUint64> {
    let block_param = block
        .map(BlockNumberOrHash::from_str)
        .transpose()?
        .unwrap_or(BlockNumberOrHash::PredefinedBlock(Predefined::Latest));
    let resolver = TipsetResolver::new(ctx, api_path);
    Ok(EthUint64(
        resolver
            .tipset_by_block_number_or_hash(block_param, resolve)
            .await?
            .epoch() as u64,
    ))
}

pub enum EthTraceFilter {}
impl RpcMethod<1> for EthTraceFilter {
    const N_REQUIRED_PARAMS: usize = 1;
    const NAME: &'static str = "Filecoin.EthTraceFilter";
    const NAME_ALIAS: Option<&'static str> = Some("trace_filter");
    const PARAM_NAMES: [&'static str; 1] = ["filter"];
    const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all_with_v2();
    const PERMISSION: Permission = Permission::Read;
    const DESCRIPTION: &'static str =
        "Returns the traces for transactions matching the filter criteria.";
    type Params = (EthTraceFilterCriteria,);
    type Ok = NotNullVec<EthBlockTrace>;

    async fn handle(
        ctx: Ctx,
        (filter,): Self::Params,
        ext: &http::Extensions,
    ) -> Result<Self::Ok, ServerError> {
        let api_path = Self::api_path(ext)?;
        let from_block = get_eth_block_number_from_string(
            &ctx,
            filter.from_block.as_deref(),
            ResolveNullTipset::TakeNewer,
            api_path,
        )
        .await
        .context("cannot parse fromBlock")?;

        let to_block = get_eth_block_number_from_string(
            &ctx,
            filter.to_block.as_deref(),
            ResolveNullTipset::TakeOlder,
            api_path,
        )
        .await
        .context("cannot parse toBlock")?;

        let max_block_range = ctx.eth_event_handler.max_filter_height_range;
        if max_block_range > 0 && to_block.0 > from_block.0 {
            let range = i64::try_from(to_block.0.saturating_sub(from_block.0))
                .context("block range overflow")?;
            if range > max_block_range {
                return Err(EthErrors::limit_exceeded(max_block_range, range).into());
            }
        }
        Ok(NotNullVec(
            trace_filter(ctx, filter, from_block, to_block, ext).await?,
        ))
    }
}

async fn trace_filter(
    ctx: Ctx,
    filter: EthTraceFilterCriteria,
    from_block: EthUint64,
    to_block: EthUint64,
    ext: &http::Extensions,
) -> Result<Vec<EthBlockTrace>> {
    let mut results = HashSet::default();
    if let Some(EthUint64(0)) = filter.count {
        return Ok(Vec::new());
    }
    let count = *filter.count.unwrap_or_default();
    ensure!(
        count <= *FOREST_TRACE_FILTER_MAX_RESULT,
        "invalid response count, requested {}, maximum supported is {}",
        count,
        *FOREST_TRACE_FILTER_MAX_RESULT
    );

    let mut trace_counter = 0;
    'blocks: for blk_num in from_block.0..=to_block.0 {
        // For BlockNumber, EthTraceBlock and EthTraceBlockV2 are equivalent.
        let block_traces = match EthTraceBlock::handle(
            ctx.clone(),
            (BlockNumberOrHash::from_block_number(blk_num as i64),),
            ext,
        )
        .await
        {
            Ok(block_traces) => block_traces,
            Err(e) if e.code() == NULL_ROUND_CODE => continue 'blocks,
            Err(e) => return Err(e.into()),
        };
        for block_trace in block_traces.0 {
            if block_trace
                .trace
                .match_filter_criteria(filter.from_address.as_ref(), filter.to_address.as_ref())?
            {
                trace_counter += 1;
                if let Some(after) = filter.after
                    && trace_counter <= after.0
                {
                    continue;
                }

                results.insert(block_trace);

                if filter.count.is_some() && results.len() >= count as usize {
                    break 'blocks;
                } else if results.len() > *FOREST_TRACE_FILTER_MAX_RESULT as usize {
                    bail!(
                        "too many results, maximum supported is {}, try paginating requests with After and Count",
                        *FOREST_TRACE_FILTER_MAX_RESULT
                    );
                }
            }
        }
    }

    Ok(results
        .into_iter()
        .sorted_by(|a, b| a.sort_key().cmp(&b.sort_key()))
        .collect_vec())
}

#[cfg(test)]
mod test {
    use super::*;
    use crate::rpc::eth::EventEntry;
    use crate::rpc::state::{ExecutionTrace, MessageTrace, ReturnTrace};
    use crate::shim::{econ::TokenAmount, error::ExitCode};
    use crate::{
        db::MemoryDB,
        test_utils::{construct_bls_messages, construct_eth_messages, construct_messages},
    };
    use fvm_shared4::event::Flags;
    use quickcheck::Arbitrary;
    use quickcheck_macros::quickcheck;
    use rstest::rstest;

    impl Arbitrary for EthHash {
        fn arbitrary(g: &mut quickcheck::Gen) -> Self {
            let arr: [u8; 32] = std::array::from_fn(|_ix| u8::arbitrary(g));
            Self(ethereum_types::H256(arr))
        }
    }

    #[test]
    fn execution_reverted_from_receipt_decodes_reason_and_data() {
        // A receipt carries its return payload CBOR-wrapped. The `Error(string)` ABI decode is
        // covered by `eth/utils.rs`; here a non-ABI payload (which decodes to hex) is enough to
        // check that the helper threads reason, data, exit code and vm error through.
        let payload = b"Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn".to_vec();
        let return_data =
            RawBytes::new(fvm_ipld_encoding::to_vec(&RawBytes::new(payload.clone())).unwrap());
        let receipt = Receipt::V4(fvm_shared4::receipt::Receipt {
            exit_code: fvm_shared4::error::ExitCode::new(33),
            return_data,
            gas_used: 0,
            events_root: None,
        });

        let err = EthErrors::execution_reverted_from_result(
            receipt.exit_code(),
            receipt.return_data(),
            "backtrace",
        );
        let EthErrors::ExecutionReverted { message, data } = err.clone() else {
            panic!("expected ExecutionReverted, got {err:?}");
        };
        let payload_hex = hex::encode_prefixed(&payload);
        assert_eq!(
            message,
            format!(
                "message execution failed (exit=[33], revert reason=[{payload_hex}], vm error=[backtrace])"
            )
        );
        assert_eq!(data, payload_hex);

        // Surfaces to eth clients as the standard code-3 execution-reverted error.
        let server: ServerError = err.into();
        assert_eq!(server.code(), errors::EXECUTION_REVERTED_CODE);
    }

    fn invoc_result_with_exit_code(exit_code: fvm_shared4::error::ExitCode) -> ApiInvocResult {
        ApiInvocResult {
            msg_rct: Some(Receipt::V4(fvm_shared4::receipt::Receipt {
                exit_code,
                return_data: RawBytes::default(),
                gas_used: 0,
                events_root: None,
            })),
            ..Default::default()
        }
    }

    #[test]
    fn needs_skip_sender_covers_both_shapes_of_sender_rejection() {
        assert!(needs_skip_sender(&Err(
            crate::state_manager::Error::SenderValidationFailed("sender t410f... not found".into())
                .into()
        )));

        assert!(needs_skip_sender(&Ok((
            invoc_result_with_exit_code(fvm_shared4::error::ExitCode::SYS_SENDER_INVALID),
            None
        ))));

        assert!(!needs_skip_sender(&Ok((
            invoc_result_with_exit_code(fvm_shared4::error::ExitCode::USR_ASSERTION_FAILED),
            None
        ))));
        assert!(!needs_skip_sender(&Ok((
            invoc_result_with_exit_code(fvm_shared4::error::ExitCode::OK),
            None
        ))));
        assert!(!needs_skip_sender(&Err(anyhow::anyhow!(
            "blockstore read failed"
        ))));
        assert!(!needs_skip_sender(&Ok((ApiInvocResult::default(), None))));
    }

    #[test]
    fn only_an_evm_sender_skips_validation() {
        use crate::rpc::methods::eth::trace::test_helpers::{
            create_test_actor, get_evm_actor_code_cid,
        };

        let evm_code = get_evm_actor_code_cid().expect("EVM actor code CID should be available");
        let mut evm_actor = create_test_actor(0, 0);
        evm_actor.code = evm_code;
        assert!(sender_is_evm_contract(Ok(Some(evm_actor))));

        assert!(!sender_is_evm_contract(Ok(Some(create_test_actor(0, 0)))));
        assert!(!sender_is_evm_contract(Ok(None)));
        assert!(!sender_is_evm_contract(Err(anyhow::anyhow!(
            "blockstore read failed"
        ))));
    }

    #[rstest]
    // Non-empty access list → JSON array.
    #[case::populated_array(ApiEthTx { access_list: Some(NotNullVec(vec![EthHash::default()])), ..Default::default() }, Some(1))]
    // `access_list: None` → field omitted.
    #[case::explicit_none_omitted(ApiEthTx { access_list: None, ..Default::default() }, None)]
    // Legacy tx → field omitted.
    #[case::legacy_homestead_omitted(EthLegacyHomesteadTxArgs::default().into(), None)]
    // Typed tx with no entries → `[]`.
    #[case::eip1559_empty_array(EthEip1559TxArgs::default().into(), Some(0))]
    fn access_list_serialization(#[case] tx: ApiEthTx, #[case] expected: Option<usize>) {
        let json = serde_json::to_value(tx.into_lotus_json()).unwrap();
        match expected {
            Some(len) => assert_eq!(
                json["accessList"]
                    .as_array()
                    .expect("accessList should serialize as an array")
                    .len(),
                len
            ),
            None => assert!(!json.as_object().unwrap().contains_key("accessList")),
        }
    }

    #[rstest]
    // Contract creation → `"to": null` present, not omitted.
    #[case::contract_creation(None)]
    // Normal tx → `"to"` is the recipient address.
    #[case::normal(Some(EthAddress::default()))]
    fn to_is_always_serialized(#[case] to: Option<EthAddress>) {
        let json = serde_json::to_value(
            ApiEthTx {
                to,
                ..Default::default()
            }
            .into_lotus_json(),
        )
        .unwrap();
        assert!(
            json.as_object().unwrap().contains_key("to"),
            "`to` key must always be present"
        );
        assert_eq!(json["to"], serde_json::to_value(to).unwrap());
    }

    #[rstest]
    // `"accessList": null` → `None`.
    #[case::null_to_none(Some(serde_json::Value::Null), None)]
    // Omitted/Missing field → `None`.
    #[case::missing_to_none(None, None)]
    // `"accessList": []` → `None`.
    #[case::empty_array_to_none(Some(serde_json::json!([])), None)]
    // Non-empty array → `Some(...)`.
    #[case::populated_array_to_some(
        Some(serde_json::json!([EthHash::default()])),
        Some(NotNullVec(vec![EthHash::default()]))
    )]
    fn access_list_deserialization(
        #[case] access_list_value: Option<serde_json::Value>,
        #[case] expected: Option<NotNullVec<EthHash>>,
    ) {
        let mut json = serde_json::to_value(ApiEthTx::default().into_lotus_json()).unwrap();
        let obj = json.as_object_mut().unwrap();
        match access_list_value {
            Some(value) => {
                obj.insert("accessList".into(), value);
            }
            None => {
                obj.remove("accessList");
            }
        }
        let tx = ApiEthTx::from_lotus_json(serde_json::from_value(json).unwrap());
        assert_eq!(tx.access_list, expected);
    }

    #[quickcheck]
    fn gas_price_result_serde_roundtrip(i: u128) {
        let r = EthBigInt(ethereum_types::U256::from(i));
        let encoded = serde_json::to_string(&r).unwrap();
        assert_eq!(encoded, format!("\"{i:#x}\""));
        let decoded: EthBigInt = serde_json::from_str(&encoded).unwrap();
        assert_eq!(r, decoded);
    }

    /// `transactionPosition` must be 0-indexed and system-actor messages must
    /// be filtered without consuming a position.
    #[test]
    fn non_system_traces_with_positions_is_zero_indexed() {
        use crate::shim::address::Address as ShimAddress;
        use crate::shim::message::Message_v3;

        let invoc_with_from = |from: ShimAddress| -> Arc<ApiInvocResult> {
            ApiInvocResult {
                msg: Message_v3 {
                    to: ShimAddress::new_id(1).into(),
                    from: from.into(),
                    ..Message_v3::default()
                }
                .into(),
                ..Default::default()
            }
            .into()
        };

        let raw_traces = vec![
            invoc_with_from(system::ADDRESS.into()),
            invoc_with_from(ShimAddress::new_id(1000)),
            invoc_with_from(system::ADDRESS.into()),
            invoc_with_from(ShimAddress::new_id(1001)),
            invoc_with_from(ShimAddress::new_id(1002)),
        ];

        let positions: Vec<i64> = non_system_traces_with_positions(raw_traces)
            .map(|(pos, _)| pos)
            .collect();

        assert_eq!(positions, vec![0, 1, 2]);
    }

    #[test]
    fn test_abi_encoding() {
        const EXPECTED: &str = "000000000000000000000000000000000000000000000000000000000000001600000000000000000000000000000000000000000000000000000000000000510000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000001b1111111111111111111020200301000000044444444444444444010000000000";
        const DATA: &str = "111111111111111111102020030100000004444444444444444401";
        let expected_bytes = hex::decode(EXPECTED).unwrap();
        let data_bytes = hex::decode(DATA).unwrap();

        assert_eq!(expected_bytes, encode_as_abi_helper(22, 81, &data_bytes));
    }

    #[test]
    fn test_abi_encoding_empty_bytes() {
        // Generated using https://abi.hashex.org/
        const EXPECTED: &str = "0000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000005100000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000";
        let expected_bytes = hex::decode(EXPECTED).unwrap();
        let data_bytes = vec![];

        assert_eq!(expected_bytes, encode_as_abi_helper(22, 81, &data_bytes));
    }

    #[test]
    fn test_abi_encoding_one_byte() {
        // According to https://docs.soliditylang.org/en/latest/abi-spec.html and handcrafted
        // Uint64, Uint64, Bytes[]
        // 22, 81, [253]
        const EXPECTED: &str = "0000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000005100000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000001fd00000000000000000000000000000000000000000000000000000000000000";
        let expected_bytes = hex::decode(EXPECTED).unwrap();
        let data_bytes = vec![253];

        assert_eq!(expected_bytes, encode_as_abi_helper(22, 81, &data_bytes));
    }

    #[test]
    fn test_id_address_roundtrip() {
        let test_cases = [1u64, 2, 3, 100, 101];

        for id in test_cases {
            let addr = FilecoinAddress::new_id(id);

            // roundtrip
            let eth_addr = EthAddress::from_filecoin_address(&addr).unwrap();
            let fil_addr = eth_addr.to_filecoin_address().unwrap();
            assert_eq!(addr, fil_addr)
        }
    }

    #[test]
    fn test_addr_serde_roundtrip() {
        let test_cases = [
            r#""0xd4c5fb16488Aa48081296299d54b0c648C9333dA""#,
            r#""0x2C2EC67e3e1FeA8e4A39601cB3A3Cd44f5fa830d""#,
            r#""0x01184F793982104363F9a8a5845743f452dE0586""#,
        ];

        for addr in test_cases {
            let eth_addr: EthAddress = serde_json::from_str(addr).unwrap();

            let encoded = serde_json::to_string(&eth_addr).unwrap();
            assert_eq!(encoded, addr.to_lowercase());

            let decoded: EthAddress = serde_json::from_str(&encoded).unwrap();
            assert_eq!(eth_addr, decoded);
        }
    }

    #[quickcheck]
    fn test_fil_address_roundtrip(addr: FilecoinAddress) {
        if let Ok(eth_addr) = EthAddress::from_filecoin_address(&addr) {
            let fil_addr = eth_addr.to_filecoin_address().unwrap();

            let protocol = addr.protocol();
            assert!(protocol == Protocol::ID || protocol == Protocol::Delegated);
            assert_eq!(addr, fil_addr);
        }
    }

    #[rstest]
    #[case("\"0x013dbb9442ca9667baccc6230fcd5c1c4b2d4d2870f4bd20681d4d47cfd15184\"")]
    #[case("\"0xab8653edf9f51785664a643b47605a7ba3d917b5339a0724e7642c114d0e4738\"")]
    fn test_hash_serde_json(#[case] hash: &str) {
        let h: EthHash = serde_json::from_str(hash).unwrap();
        let c = h.to_cid();
        let h1: EthHash = c.into();
        assert_eq!(h, h1);
    }

    #[quickcheck]
    fn test_eth_hash_roundtrip(eth_hash: EthHash) {
        let cid = eth_hash.to_cid();
        let hash = cid.into();
        assert_eq!(eth_hash, hash);
    }

    #[test]
    fn test_block_constructor() {
        let block = Block::new(false, 1);
        assert_eq!(block.transactions_root, EthHash::empty_root());

        let block = Block::new(true, 1);
        assert_eq!(block.transactions_root, EthHash::default());
    }

    #[test]
    fn test_eth_tx_hash_from_signed_message() {
        let (_, signed) = construct_eth_messages(0);
        let tx_hash =
            eth_tx_hash_from_signed_message(&signed, crate::networks::calibnet::ETH_CHAIN_ID)
                .unwrap();
        assert_eq!(
            &format!("{tx_hash}"),
            "0xfc81dd8d9ffb045e7e2d494f925824098183263c7f402d69e18cc25e3422791b"
        );

        let (_, signed) = construct_messages();
        let tx_hash =
            eth_tx_hash_from_signed_message(&signed, crate::networks::calibnet::ETH_CHAIN_ID)
                .unwrap();
        assert_eq!(tx_hash.to_cid(), signed.cid());

        let (_, signed) = construct_bls_messages();
        let tx_hash =
            eth_tx_hash_from_signed_message(&signed, crate::networks::calibnet::ETH_CHAIN_ID)
                .unwrap();
        assert_eq!(tx_hash.to_cid(), signed.message().cid());
    }

    #[test]
    fn test_eth_tx_hash_from_message_cid() {
        let blockstore = Arc::new(MemoryDB::default());

        let (msg0, secp0) = construct_eth_messages(0);
        let (_msg1, secp1) = construct_eth_messages(1);
        let (msg2, bls0) = construct_bls_messages();

        crate::chain::persist_objects(&blockstore, [&msg0, &msg2].into_iter()).unwrap();
        crate::chain::persist_objects(&blockstore, [&secp0, &bls0].into_iter()).unwrap();

        let tx_hash = eth_tx_hash_from_message_cid(&blockstore, &secp0.cid(), 0).unwrap();
        assert!(tx_hash.is_some());

        let tx_hash = eth_tx_hash_from_message_cid(&blockstore, &msg2.cid(), 0).unwrap();
        assert!(tx_hash.is_some());

        let tx_hash = eth_tx_hash_from_message_cid(&blockstore, &secp1.cid(), 0).unwrap();
        assert!(tx_hash.is_none());
    }

    #[test]
    fn test_eth_log_from_event() {
        // The value member of these event entries correspond to existing topics on Calibnet,
        // but they could just as easily be vectors filled with random bytes.

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t2".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
        ];
        let (bytes, hashes) = eth_log_from_event(&entries).unwrap();
        assert!(bytes.0.is_empty());
        assert_eq!(hashes.len(), 2);

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t2".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t3".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t4".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
        ];
        let (bytes, hashes) = eth_log_from_event(&entries).unwrap();
        assert!(bytes.0.is_empty());
        assert_eq!(hashes.len(), 4);

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
        ];
        assert!(eth_log_from_event(&entries).is_none());

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t3".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t4".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t2".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
        ];
        let (bytes, hashes) = eth_log_from_event(&entries).unwrap();
        assert!(bytes.0.is_empty());
        assert_eq!(hashes.len(), 4);

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t3".into(),
                codec: IPLD_RAW,
                value: vec![
                    116, 4, 227, 209, 4, 234, 120, 65, 195, 217, 230, 253, 32, 173, 254, 153, 180,
                    173, 88, 107, 192, 141, 143, 59, 211, 175, 239, 137, 76, 241, 132, 222,
                ]
                .into(),
            },
        ];
        assert!(eth_log_from_event(&entries).is_none());

        let entries = vec![EventEntry {
            flags: (Flags::FLAG_INDEXED_ALL).bits(),
            key: "t1".into(),
            codec: DAG_CBOR,
            value: vec![
                226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11, 81,
                29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
            ]
            .into(),
        }];
        assert!(eth_log_from_event(&entries).is_none());

        let entries = vec![EventEntry {
            flags: (Flags::FLAG_INDEXED_ALL).bits(),
            key: "t1".into(),
            codec: IPLD_RAW,
            value: vec![
                226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11, 81,
                29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149, 0,
            ]
            .into(),
        }];
        assert!(eth_log_from_event(&entries).is_none());

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "d".into(),
                codec: IPLD_RAW,
                value: vec![
                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 49, 190,
                    25, 34, 116, 232, 27, 26, 248,
                ]
                .into(),
            },
        ];
        let (bytes, hashes) = eth_log_from_event(&entries).unwrap();
        assert_eq!(bytes.0.len(), 32);
        assert_eq!(hashes.len(), 1);

        let entries = vec![
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "t1".into(),
                codec: IPLD_RAW,
                value: vec![
                    226, 71, 32, 244, 92, 183, 79, 45, 85, 241, 222, 235, 182, 9, 143, 80, 241, 11,
                    81, 29, 171, 138, 125, 71, 196, 129, 154, 8, 220, 208, 184, 149, 0,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "d".into(),
                codec: IPLD_RAW,
                value: vec![
                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 49, 190,
                    25, 34, 116, 232, 27, 26, 248,
                ]
                .into(),
            },
            EventEntry {
                flags: (Flags::FLAG_INDEXED_ALL).bits(),
                key: "d".into(),
                codec: IPLD_RAW,
                value: vec![
                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 49, 190,
                    25, 34, 116, 232, 27, 26, 248,
                ]
                .into(),
            },
        ];
        assert!(eth_log_from_event(&entries).is_none());
    }

    #[test]
    fn test_from_bytes_valid() {
        let zero_bytes = [0u8; 32];
        assert_eq!(
            EthUint64::from_bytes(&zero_bytes).unwrap().0,
            0,
            "zero bytes"
        );

        let mut value_bytes = [0u8; 32];
        value_bytes[31] = 42;
        assert_eq!(
            EthUint64::from_bytes(&value_bytes).unwrap().0,
            42,
            "simple value"
        );

        let mut max_bytes = [0u8; 32];
        max_bytes[24..32].copy_from_slice(&u64::MAX.to_be_bytes());
        assert_eq!(
            EthUint64::from_bytes(&max_bytes).unwrap().0,
            u64::MAX,
            "valid max value"
        );
    }

    #[test]
    fn test_from_bytes_wrong_length() {
        let short_bytes = [0u8; 31];
        assert!(
            EthUint64::from_bytes(&short_bytes).is_err(),
            "bytes too short"
        );

        let long_bytes = [0u8; 33];
        assert!(
            EthUint64::from_bytes(&long_bytes).is_err(),
            "bytes too long"
        );

        let empty_bytes = [];
        assert!(
            EthUint64::from_bytes(&empty_bytes).is_err(),
            "bytes too short"
        );
    }

    #[test]
    fn test_from_bytes_overflow() {
        let mut overflow_bytes = [0u8; 32];
        overflow_bytes[10] = 1;
        assert!(
            EthUint64::from_bytes(&overflow_bytes).is_err(),
            "overflow with non-zero byte at position 10"
        );

        overflow_bytes = [0u8; 32];
        overflow_bytes[23] = 1;
        assert!(
            EthUint64::from_bytes(&overflow_bytes).is_err(),
            "overflow with non-zero byte at position 23"
        );

        overflow_bytes = [0u8; 32];
        overflow_bytes
            .iter_mut()
            .take(24)
            .for_each(|byte| *byte = 0xFF);

        assert!(
            EthUint64::from_bytes(&overflow_bytes).is_err(),
            "overflow bytes with non-zero bytes at positions 0-23"
        );

        overflow_bytes = [0u8; 32];
        for i in 0..24 {
            overflow_bytes[i] = 0xFF;
            assert!(
                EthUint64::from_bytes(&overflow_bytes).is_err(),
                "overflow with non-zero byte at position {i}"
            );
        }

        overflow_bytes = [0xFF; 32];
        assert!(
            EthUint64::from_bytes(&overflow_bytes).is_err(),
            "overflow with all ones"
        );
    }

    fn create_execution_trace(from: FilecoinAddress, to: FilecoinAddress) -> ExecutionTrace {
        ExecutionTrace {
            msg: MessageTrace {
                from,
                to,
                value: TokenAmount::default(),
                method: 0,
                params: Default::default(),
                params_codec: 0,
                gas_limit: None,
                read_only: None,
            },
            msg_rct: ReturnTrace {
                exit_code: ExitCode::from(0u32),
                r#return: Default::default(),
                return_codec: 0,
            },
            invoked_actor: None,
            gas_charges: vec![],
            subcalls: vec![],
            logs: vec![],
            ipld_ops: vec![],
        }
    }

    fn create_execution_trace_with_subcalls(
        from: FilecoinAddress,
        to: FilecoinAddress,
        subcalls: Vec<ExecutionTrace>,
    ) -> ExecutionTrace {
        let mut trace = create_execution_trace(from, to);
        trace.subcalls = subcalls;
        trace
    }

    #[test]
    fn test_extract_touched_addresses_with_id_addresses() {
        // ID addresses (e.g., f0100) can be converted to EthAddress
        let from = FilecoinAddress::new_id(100);
        let to = FilecoinAddress::new_id(200);
        let trace = create_execution_trace(from, to);

        let addresses = extract_touched_eth_addresses(&trace);

        assert_eq!(addresses.len(), 2);
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&from).unwrap()));
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&to).unwrap()));
    }

    #[test]
    fn test_extract_touched_addresses_same_from_and_to() {
        let addr = FilecoinAddress::new_id(100);
        let trace = create_execution_trace(addr, addr);

        let addresses = extract_touched_eth_addresses(&trace);

        // Should deduplicate
        assert_eq!(addresses.len(), 1);
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&addr).unwrap()));
    }

    #[test]
    fn test_extract_touched_addresses_with_subcalls() {
        let addr1 = FilecoinAddress::new_id(100);
        let addr2 = FilecoinAddress::new_id(200);
        let addr3 = FilecoinAddress::new_id(300);
        let addr4 = FilecoinAddress::new_id(400);

        let subcall = create_execution_trace(addr3, addr4);
        let trace = create_execution_trace_with_subcalls(addr1, addr2, vec![subcall]);

        let addresses = extract_touched_eth_addresses(&trace);

        assert_eq!(addresses.len(), 4);
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&addr1).unwrap()));
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&addr2).unwrap()));
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&addr3).unwrap()));
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&addr4).unwrap()));
    }

    #[test]
    fn test_extract_touched_addresses_with_nested_subcalls() {
        let addr1 = FilecoinAddress::new_id(100);
        let addr2 = FilecoinAddress::new_id(200);
        let addr3 = FilecoinAddress::new_id(300);
        let addr4 = FilecoinAddress::new_id(400);
        let addr5 = FilecoinAddress::new_id(500);
        let addr6 = FilecoinAddress::new_id(600);

        // Create nested structure: trace -> subcall1 -> nested_subcall
        let nested_subcall = create_execution_trace(addr5, addr6);
        let subcall = create_execution_trace_with_subcalls(addr3, addr4, vec![nested_subcall]);
        let trace = create_execution_trace_with_subcalls(addr1, addr2, vec![subcall]);

        let addresses = extract_touched_eth_addresses(&trace);

        assert_eq!(addresses.len(), 6);
        for addr in [addr1, addr2, addr3, addr4, addr5, addr6] {
            assert!(addresses.contains(&EthAddress::from_filecoin_address(&addr).unwrap()));
        }
    }

    #[test]
    fn test_extract_touched_addresses_with_multiple_subcalls() {
        let addr1 = FilecoinAddress::new_id(100);
        let addr2 = FilecoinAddress::new_id(200);
        let addr3 = FilecoinAddress::new_id(300);
        let addr4 = FilecoinAddress::new_id(400);
        let addr5 = FilecoinAddress::new_id(500);
        let addr6 = FilecoinAddress::new_id(600);

        let subcall1 = create_execution_trace(addr3, addr4);
        let subcall2 = create_execution_trace(addr5, addr6);
        let trace = create_execution_trace_with_subcalls(addr1, addr2, vec![subcall1, subcall2]);

        let addresses = extract_touched_eth_addresses(&trace);

        assert_eq!(addresses.len(), 6);
    }

    #[test]
    fn test_extract_touched_addresses_deduplicates_across_subcalls() {
        // Same address appears in parent and subcall
        let addr1 = FilecoinAddress::new_id(100);
        let addr2 = FilecoinAddress::new_id(200);

        let subcall = create_execution_trace(addr1, addr2); // addr1 repeated
        let trace = create_execution_trace_with_subcalls(addr1, addr2, vec![subcall]);

        let addresses = extract_touched_eth_addresses(&trace);

        // Should deduplicate
        assert_eq!(addresses.len(), 2);
    }

    #[test]
    fn test_extract_touched_addresses_with_non_convertible_addresses() {
        // BLS addresses cannot be converted to EthAddress
        let bls_addr = FilecoinAddress::new_bls(&[0u8; 48]).unwrap();
        let id_addr = FilecoinAddress::new_id(100);

        let trace = create_execution_trace(bls_addr, id_addr);
        let addresses = extract_touched_eth_addresses(&trace);

        // Only the ID address should be in the set
        assert_eq!(addresses.len(), 1);
        assert!(addresses.contains(&EthAddress::from_filecoin_address(&id_addr).unwrap()));
    }
}