reth_rpc_eth_api/helpers/

estimate.rs

//! Estimate gas needed implementation

use super::{call::request_gas_price, Call, LoadPendingBlock};
use crate::{AsEthApiError, FromEthApiError, FromEvmError, IntoEthApiError};
use alloy_network::TransactionBuilder;
use alloy_primitives::{TxKind, U256};
use alloy_rpc_types_eth::{state::EvmOverrides, BlockId};
use evm2::{
    evm::{CacheDB, Db, DynDatabase},
    interpreter::InstrStop,
    EvmFeatures, TxResult,
};
use futures::Future;
use reth_chainspec::MIN_TRANSACTION_GAS;
use reth_evm::{
    database::StateProviderDatabase, ConfigureEvm, Evm, EvmEnv, EvmEnvFor, EvmTypesFor,
    TransactionEnvMut,
};
use reth_rpc_convert::{RpcConvert, RpcTxReq};
use reth_rpc_eth_types::{
    cache::db::{apply_block_overrides, apply_state_overrides},
    error::api::{FromEvmHalt, FromRevert},
    EthApiError, RpcInvalidTransactionError,
};
use reth_rpc_server_types::constants::gas_oracle::{CALL_STIPEND_GAS, ESTIMATE_GAS_ERROR_RATIO};
use reth_storage_api::{EvmStateProvider, StateProvider};
use reth_tasks::cancel::is_cancelled;
use tracing::trace;

/// Gas execution estimates
pub trait EstimateCall: Call {
    /// Estimates the gas usage of the `request` with the state.
    ///
    /// This will execute the [`RpcTxReq`] and find the best gas limit via binary search.
    ///
    /// ## EVM settings
    ///
    /// This modifies certain EVM settings to mirror geth's `SkipAccountChecks` when transacting requests, see also: <https://github.com/ethereum/go-ethereum/blob/380688c636a654becc8f114438c2a5d93d2db032/core/state_transition.go#L145-L148>:
    ///
    ///  - `disable_eip3607` is set to `true`
    ///  - `disable_base_fee` is set to `true`
    ///  - `disable_fee_charge` is set to `true`
    ///  - `nonce` is set to `None`
    fn estimate_gas_with<S>(
        &self,
        mut evm_env: EvmEnvFor<Self::Evm>,
        mut request: RpcTxReq<<Self::RpcConvert as RpcConvert>::Network>,
        state: S,
        overrides: EvmOverrides,
    ) -> Result<U256, Self::Error>
    where
        S: EvmStateProvider,
    {
        // Disabled because eth_estimateGas is sometimes used with eoa senders
        // See <https://github.com/paradigmxyz/reth/issues/1959>
        evm_env.version_mut().features.remove(EvmFeatures::EIP3607);

        // The basefee should be ignored for eth_estimateGas and similar
        // See:
        // <https://github.com/ethereum/go-ethereum/blob/ee8e83fa5f6cb261dad2ed0a7bbcde4930c41e6c/internal/ethapi/api.go#L985>
        evm_env.version_mut().features.remove(EvmFeatures::BASE_FEE_CHECK);

        // Disable additional fee charges (e.g. L2 operator fees) for gas estimation,
        // consistent with `prepare_call_env` for `eth_call`.
        evm_env.version_mut().features.remove(
            EvmFeatures::FEE_CHARGE | EvmFeatures::BALANCE_CHECK | EvmFeatures::BALANCE_TOP_UP,
        );

        // set nonce to None so that the correct nonce is chosen by the EVM
        request.as_mut().take_nonce();

        // Keep a copy of gas related request values
        let tx_request_gas_limit = request.as_ref().gas_limit();
        let tx_request_gas_price = request.as_ref().gas_price();

        // Configure the evm env
        let mut db = CacheDB::new(Db::new(StateProviderDatabase::new(state)));

        // Apply any block overrides before deriving block-derived limits and the tx env so
        // overrides for `gasLimit`, `baseFee` and `blobBaseFee` are visible to estimation.
        // Mirrors geth's behavior, see:
        // <https://github.com/ethereum/go-ethereum/pull/30695>
        if let Some(block_overrides) = overrides.block {
            apply_block_overrides(*block_overrides, &mut db, &mut evm_env);
        }

        // Apply any state overrides if specified.
        if let Some(state_override) = overrides.state {
            apply_state_overrides(state_override, &mut db).map_err(Self::Error::from_eth_err)?;
        }

        // the gas limit of the corresponding block
        let block_gas_limit = evm_env.block_env().gas_limit.to::<u64>();
        // If EIP-8037 is enabled, the transaction gas limit cap is not applicable
        let mut max_gas_limit = evm_env.version().tx_gas_caps().0.min(block_gas_limit);

        // Also bound diagnostic retries by the RPC gas cap. Zero means unlimited.
        let gas_cap = self.call_gas_limit();
        if gas_cap != 0 {
            max_gas_limit = max_gas_limit.min(gas_cap);
        }

        let mut highest_gas_limit =
            tx_request_gas_limit.unwrap_or(max_gas_limit).min(max_gas_limit);

        // Check if this is a basic transfer (no input data to account with no code)
        let is_basic_transfer = if request.as_ref().input().is_none_or(|input| input.is_empty()) &&
            let Some(TxKind::Call(to)) = request.as_ref().kind()
        {
            // Fetch the account through the DB so the state overrides applied above are visible.
            match db.get_account(&to) {
                Ok(Some(account)) => account.is_empty_code_hash(),
                Ok(None) => true,
                Err(_) => false,
            }
        } else {
            false
        };

        let request_gas_price = request_gas_price(request.as_ref(), evm_env.block_base_fee());
        let mut tx_env = self.create_txn_env(&evm_env, request, &mut db)?;

        // Check funds of the sender (only useful to check if transaction gas price is more than 0).
        //
        // The caller allowance reserves the value and maximum blob fee before funding execution
        // gas at the transaction's gas price.
        if request_gas_price > 0 {
            let allowance = self.caller_gas_allowance(&mut db, &evm_env, &tx_env)?;
            highest_gas_limit = highest_gas_limit.min(allowance);
        }

        trace!(target: "rpc::eth::estimate", ?tx_env, gas_limit = highest_gas_limit, is_basic_transfer, "Starting gas estimation");

        let mut evm = self.evm_config().evm_with_env(&mut db, evm_env);
        let mut execute = move |gas_limit| {
            tx_env.inner_mut().set_gas_limit(gas_limit);
            evm.transact_result(&tx_env).map_err(Self::Error::from_evm_err)
        };

        // For basic transfers, try using minimum gas before running full binary search
        if is_basic_transfer &&
            let Ok(res) = execute(MIN_TRANSACTION_GAS.min(max_gas_limit)) &&
            res.status
        {
            return Ok(U256::from(res.tx_gas_used()))
        }

        // Execute the transaction with the highest possible gas limit.
        let mut res = match execute(highest_gas_limit) {
            // Handle the exceptional case where the transaction initialization uses too much
            // gas. If the gas price or gas limit was specified in the request,
            // retry the transaction with the block's gas limit to determine if
            // the failure was due to insufficient gas.
            Err(err)
                if err.is_gas_too_high() &&
                    (tx_request_gas_limit.is_some() || tx_request_gas_price.is_some()) =>
            {
                let retry = execute(max_gas_limit)?;
                return map_out_of_gas_result::<_, EvmTypesFor<Self::Evm>>(retry, highest_gas_limit)
            }
            Err(err) if err.is_gas_too_low() => {
                // This failed because the configured gas cost of the tx was lower than what
                // actually consumed by the tx This can happen if the
                // request provided fee values manually and the resulting gas cost exceeds the
                // sender's allowance, so we return the appropriate error here
                return Err(RpcInvalidTransactionError::GasRequiredExceedsAllowance {
                    gas_limit: highest_gas_limit,
                }
                .into_eth_err());
            }
            // Propagate other results (successful or other errors).
            ethres => ethres?,
        };

        let gas_refund = if res.status {
            res.final_refunded()
        } else if res.stop == InstrStop::Revert {
            // if price or limit was included in the request then we can execute the request
            // again with the block's gas limit to check if revert is gas related or not
            return if tx_request_gas_limit.is_some() || tx_request_gas_price.is_some() {
                let retry = execute(max_gas_limit)?;
                map_out_of_gas_result::<_, EvmTypesFor<Self::Evm>>(retry, highest_gas_limit)
            } else {
                // the transaction did revert
                Err(Self::Error::from_revert(res.output))
            }
        } else {
            // here we don't check for invalid opcode because already executed with highest gas
            // limit
            return Err(Self::Error::from_evm_halt(res.stop, highest_gas_limit))
        };

        // At this point we know the call succeeded but want to find the _best_ (lowest) gas the
        // transaction succeeds with. We find this by doing a binary search over the possible range.

        // NOTE: this is the gas the transaction used, which is less than the
        // transaction requires to succeed.
        let mut gas_used = res.tx_gas_used();
        // the lowest value is capped by the gas used by the unconstrained transaction
        let mut lowest_gas_limit = gas_used.saturating_sub(1);

        // As stated in Geth, there is a good chance that the transaction will pass if we set the
        // gas limit to the execution gas used plus the gas refund, so we check this first
        // <https://github.com/ethereum/go-ethereum/blob/a5a4fa7032bb248f5a7c40f4e8df2b131c4186a4/eth/gasestimator/gasestimator.go#L135
        //
        // Calculate the optimistic gas limit by adding gas used and gas refund,
        // then applying a 64/63 multiplier to account for gas forwarding rules.
        let optimistic_gas_limit = (gas_used + gas_refund + CALL_STIPEND_GAS) * 64 / 63;
        if optimistic_gas_limit < highest_gas_limit {
            // Re-execute the transaction with the new gas limit and update the result and
            // environment.
            res = execute(optimistic_gas_limit)?;

            // Update the gas used based on the new result.
            gas_used = res.tx_gas_used();
            // Update the gas limit estimates (highest and lowest) based on the execution result.
            update_estimated_gas_range::<EvmTypesFor<Self::Evm>>(
                res,
                optimistic_gas_limit,
                &mut highest_gas_limit,
                &mut lowest_gas_limit,
            )?;
        };

        // Pick a point that's close to the estimated gas
        let mut mid_gas_limit = std::cmp::min(
            gas_used * 3,
            ((highest_gas_limit as u128 + lowest_gas_limit as u128) / 2) as u64,
        );

        trace!(target: "rpc::eth::estimate", ?highest_gas_limit, ?lowest_gas_limit, ?mid_gas_limit, "Starting binary search for gas");

        // Binary search narrows the range to find the minimum gas limit needed for the transaction
        // to succeed.
        while lowest_gas_limit + 1 < highest_gas_limit {
            // An estimation error is allowed once the current gas limit range used in the binary
            // search is small enough (less than 1.5% of the highest gas limit)
            // <https://github.com/ethereum/go-ethereum/blob/a5a4fa7032bb248f5a7c40f4e8df2b131c4186a4/eth/gasestimator/gasestimator.go#L152
            let ratio = (highest_gas_limit - lowest_gas_limit) as f64 / (highest_gas_limit as f64);
            if ratio < ESTIMATE_GAS_ERROR_RATIO {
                break
            };

            if is_cancelled() {
                return Err(EthApiError::InternalEthError.into())
            }
            // Execute transaction and handle potential gas errors, adjusting limits accordingly.
            match execute(mid_gas_limit) {
                Err(err) if err.is_gas_too_high() => {
                    // Decrease the highest gas limit if gas is too high
                    highest_gas_limit = mid_gas_limit;
                }
                Err(err) if err.is_gas_too_low() => {
                    // Increase the lowest gas limit if gas is too low
                    lowest_gas_limit = mid_gas_limit;
                }
                // Handle other cases, including successful transactions.
                ethres => {
                    // Update the estimated gas range based on the execution result.
                    update_estimated_gas_range::<EvmTypesFor<Self::Evm>>(
                        ethres?,
                        mid_gas_limit,
                        &mut highest_gas_limit,
                        &mut lowest_gas_limit,
                    )?;
                }
            }

            // New midpoint
            mid_gas_limit = ((highest_gas_limit as u128 + lowest_gas_limit as u128) / 2) as u64;
        }

        Ok(U256::from(highest_gas_limit))
    }

    /// Estimate gas needed for execution of the `request` at the [`BlockId`].
    fn estimate_gas_at(
        &self,
        request: RpcTxReq<<Self::RpcConvert as RpcConvert>::Network>,
        at: BlockId,
        overrides: EvmOverrides,
    ) -> impl Future<Output = Result<U256, Self::Error>> + Send
    where
        Self: LoadPendingBlock,
    {
        async move {
            let (evm_env, at) = self.evm_env_at(at).await?;

            self.spawn_blocking_io_with_state(at, move |this, state| {
                EstimateCall::estimate_gas_with(
                    &this,
                    evm_env,
                    request,
                    state.into_evm_state_provider(),
                    overrides,
                )
            })
            .await
        }
    }
}

fn map_out_of_gas_result<Error, EvmTypes>(
    result: TxResult<EvmTypes>,
    requested_gas_limit: u64,
) -> Result<U256, Error>
where
    Error: FromEvmHalt<evm2::interpreter::InstrStop> + FromRevert + FromEthApiError,
    EvmTypes: evm2::EvmTypes,
{
    if result.status {
        // Transaction succeeded by manually increasing the gas limit,
        // which means the caller lacks funds to pay for the tx
        Err(RpcInvalidTransactionError::BasicOutOfGas(requested_gas_limit).into_eth_err())
    } else if result.stop == InstrStop::Revert {
        // reverted again after bumping the limit
        Err(Error::from_revert(result.output))
    } else {
        Err(Error::from_evm_halt(result.stop, requested_gas_limit))
    }
}

/// Updates the highest and lowest gas limits for binary search based on the execution result.
///
/// This function refines the gas limit estimates used in a binary search to find the optimal
/// gas limit for a transaction. It adjusts the highest or lowest gas limits depending on
/// whether the execution succeeded, reverted, or halted due to specific reasons.
#[inline]
pub fn update_estimated_gas_range<EvmTypes: evm2::EvmTypes>(
    result: TxResult<EvmTypes>,
    tx_gas_limit: u64,
    highest_gas_limit: &mut u64,
    lowest_gas_limit: &mut u64,
) -> Result<(), EthApiError> {
    if result.status {
        // Cap the highest gas limit with the succeeding gas limit.
        *highest_gas_limit = tx_gas_limit;
    } else {
        // We know that transaction succeeded with a higher gas limit before, so any failure
        // means that we need to increase it.
        //
        // We are ignoring all halts here, and not just OOG errors because there are cases when
        // non-OOG halt might flag insufficient gas limit as well.
        //
        // Common usage of invalid opcode in OpenZeppelin:
        // <https://github.com/OpenZeppelin/openzeppelin-contracts/blob/94697be8a3f0dfcd95dfb13ffbd39b5973f5c65d/contracts/metatx/ERC2771Forwarder.sol#L360-L367>
        *lowest_gas_limit = tx_gas_limit;
    }

    Ok(())
}