alloy_eips/eip1559/

helpers.rs

use crate::eip1559::{constants::GAS_LIMIT_BOUND_DIVISOR, BaseFeeParams};

/// Calculates the effective gas price for a dynamic fee transaction.
///
/// This is a utility function for EIP-1559 and similar transactions that use dynamic fees.
///
/// For EIP-1559 transactions, the effective gas price is calculated as:
/// - If no base fee: returns `max_fee_per_gas`
/// - If base fee exists: returns `min(max_fee_per_gas, max_priority_fee_per_gas + base_fee)`
///
/// This ensures that the total fee doesn't exceed the maximum fee per gas, while also
/// ensuring that the priority fee doesn't exceed the maximum priority fee per gas.
#[inline]
pub fn calc_effective_gas_price(
    max_fee_per_gas: u128,
    max_priority_fee_per_gas: u128,
    base_fee: Option<u64>,
) -> u128 {
    base_fee.map_or(max_fee_per_gas, |base_fee| {
        // if the tip is greater than the max priority fee per gas, set it to the max
        // priority fee per gas + base fee
        let tip = max_fee_per_gas.saturating_sub(base_fee as u128);
        if tip > max_priority_fee_per_gas {
            max_priority_fee_per_gas + base_fee as u128
        } else {
            // otherwise return the max fee per gas
            max_fee_per_gas
        }
    })
}

/// Return type of EIP1155 gas fee estimator.
///
/// Contains EIP-1559 fields
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub struct Eip1559Estimation {
    /// The max fee per gas.
    #[cfg_attr(feature = "serde", serde(with = "alloy_serde::quantity"))]
    pub max_fee_per_gas: u128,
    /// The max priority fee per gas.
    #[cfg_attr(feature = "serde", serde(with = "alloy_serde::quantity"))]
    pub max_priority_fee_per_gas: u128,
}

impl Eip1559Estimation {
    /// Scales the [`Eip1559Estimation`] by the given percentage value.
    ///
    /// ```
    /// use alloy_eips::eip1559::Eip1559Estimation;
    /// let est =
    ///     Eip1559Estimation { max_fee_per_gas: 100, max_priority_fee_per_gas: 100 }.scaled_by_pct(10);
    /// assert_eq!(est.max_fee_per_gas, 110);
    /// assert_eq!(est.max_priority_fee_per_gas, 110);
    /// ```
    pub const fn scale_by_pct(&mut self, pct: u64) {
        self.max_fee_per_gas = self.max_fee_per_gas * (100 + pct as u128) / 100;
        self.max_priority_fee_per_gas = self.max_priority_fee_per_gas * (100 + pct as u128) / 100;
    }

    /// Consumes the type and returns the scaled estimation.
    pub const fn scaled_by_pct(mut self, pct: u64) -> Self {
        self.scale_by_pct(pct);
        self
    }
}

/// Calculate the base fee for the next block based on the EIP-1559 specification.
///
/// This function calculates the base fee for the next block according to the rules defined in the
/// EIP-1559. EIP-1559 introduces a new transaction pricing mechanism that includes a
/// fixed-per-block network fee that is burned and dynamically adjusts block sizes to handles
/// transient congestion.
///
/// For each block, the base fee per gas is determined by the gas used in the parent block and the
/// target gas (the block gas limit divided by the elasticity multiplier). The algorithm increases
/// the base fee when blocks are congested and decreases it when they are under the target gas
/// usage. The base fee per gas is always burned.
///
/// Parameters:
/// - `gas_used`: The gas used in the current block.
/// - `gas_limit`: The gas limit of the current block.
/// - `base_fee`: The current base fee per gas.
/// - `base_fee_params`: Base fee parameters such as elasticity multiplier and max change
///   denominator.
///
/// Returns:
/// The calculated base fee for the next block as a `u64`.
///
/// For more information, refer to the [EIP-1559 spec](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md).
pub fn calc_next_block_base_fee(
    gas_used: u64,
    gas_limit: u64,
    base_fee: u64,
    base_fee_params: BaseFeeParams,
) -> u64 {
    let elasticity = base_fee_params.elasticity_multiplier;
    let max_change_denominator = base_fee_params.max_change_denominator;

    // Without these checks, `gas_limit / elasticity` or the EIP-1559 update term can divide by
    // zero (e.g. elasticity or denominator set to zero from misconfiguration / malformed
    // Holocene header data, or `gas_limit < elasticity` on chains that do not enforce a minimum
    // gas limit). Nethermind returns the parent base fee unchanged in these cases; see
    // `DefaultBaseFeeCalculator` in Nethermind.Core.
    if elasticity == 0 || max_change_denominator == 0 {
        return base_fee;
    }

    // Calculate the target gas by dividing the gas limit by the elasticity multiplier.
    let gas_target = (gas_limit as u128 / elasticity) as u64;

    if gas_target == 0 {
        return base_fee;
    }

    match gas_used.cmp(&gas_target) {
        // If the gas used in the current block is equal to the gas target, the base fee remains the
        // same (no increase).
        core::cmp::Ordering::Equal => base_fee,
        // If the gas used in the current block is greater than the gas target, calculate a new
        // increased base fee.
        core::cmp::Ordering::Greater => {
            // Calculate the increase in base fee based on the formula defined by EIP-1559.
            base_fee
                + (core::cmp::max(
                    // Ensure a minimum increase of 1.
                    1,
                    base_fee as u128 * (gas_used - gas_target) as u128
                        / (gas_target as u128 * base_fee_params.max_change_denominator),
                ) as u64)
        }
        // If the gas used in the current block is less than the gas target, calculate a new
        // decreased base fee.
        core::cmp::Ordering::Less => {
            // Calculate the decrease in base fee based on the formula defined by EIP-1559.
            base_fee.saturating_sub(
                (base_fee as u128 * (gas_target - gas_used) as u128
                    / (gas_target as u128 * base_fee_params.max_change_denominator))
                    as u64,
            )
        }
    }
}

/// Calculate the gas limit for the next block based on parent and desired gas limits.
/// Ref: <https://github.com/ethereum/go-ethereum/blob/88cbfab332c96edfbe99d161d9df6a40721bd786/core/block_validator.go#L166>
pub fn calculate_block_gas_limit(parent_gas_limit: u64, desired_gas_limit: u64) -> u64 {
    calculate_block_gas_limit_with_bound_divisor(
        parent_gas_limit,
        desired_gas_limit,
        GAS_LIMIT_BOUND_DIVISOR,
    )
}

/// Calculate the gas limit for the next block based on parent and desired gas limits and a custom
/// gas limit bound divisor.
///
/// # Panics
///
/// Panics if `gas_limit_bound_divisor` is zero.
pub fn calculate_block_gas_limit_with_bound_divisor(
    parent_gas_limit: u64,
    desired_gas_limit: u64,
    gas_limit_bound_divisor: u64,
) -> u64 {
    assert!(gas_limit_bound_divisor != 0, "gas limit bound divisor must be non-zero");

    let delta = (parent_gas_limit / gas_limit_bound_divisor).saturating_sub(1);
    let min_gas_limit = parent_gas_limit.saturating_sub(delta);
    let max_gas_limit = parent_gas_limit.saturating_add(delta);
    desired_gas_limit.clamp(min_gas_limit, max_gas_limit)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::eip1559::constants::{MIN_PROTOCOL_BASE_FEE, MIN_PROTOCOL_BASE_FEE_U256};

    #[test]
    fn min_protocol_sanity() {
        assert_eq!(MIN_PROTOCOL_BASE_FEE_U256.to::<u64>(), MIN_PROTOCOL_BASE_FEE);
    }

    #[test]
    fn calculate_block_gas_limit_bounds_desired_limit() {
        let parent_gas_limit = 30_000_000;
        let min_gas_limit = 29_970_705;
        let max_gas_limit = 30_029_295;

        assert_eq!(calculate_block_gas_limit(parent_gas_limit, 20_000_000), min_gas_limit);
        assert_eq!(calculate_block_gas_limit(parent_gas_limit, 30_000_000), 30_000_000);
        assert_eq!(calculate_block_gas_limit(parent_gas_limit, 40_000_000), max_gas_limit);
    }

    #[test]
    fn calculate_block_gas_limit_uses_custom_bound_divisor() {
        assert_eq!(calculate_block_gas_limit_with_bound_divisor(1_000, 2_000, 10), 1_099);
    }

    #[test]
    #[should_panic(expected = "gas limit bound divisor must be non-zero")]
    fn calculate_block_gas_limit_rejects_zero_bound_divisor() {
        calculate_block_gas_limit_with_bound_divisor(1_000, 2_000, 0);
    }

    #[test]
    fn calculate_base_fee_success() {
        let base_fee = [
            1000000000, 1000000000, 1000000000, 1072671875, 1059263476, 1049238967, 1049238967, 0,
            1, 2,
        ];
        let gas_used = [
            10000000, 10000000, 10000000, 9000000, 10001000, 0, 10000000, 10000000, 10000000,
            10000000,
        ];
        let gas_limit = [
            10000000, 12000000, 14000000, 10000000, 14000000, 2000000, 18000000, 18000000,
            18000000, 18000000,
        ];
        let next_base_fee = [
            1125000000, 1083333333, 1053571428, 1179939062, 1116028649, 918084097, 1063811730, 1,
            2, 3,
        ];

        for i in 0..base_fee.len() {
            assert_eq!(
                next_base_fee[i],
                calc_next_block_base_fee(
                    gas_used[i],
                    gas_limit[i],
                    base_fee[i],
                    BaseFeeParams::ethereum(),
                )
            );
        }
    }

    #[test]
    fn calculate_optimism_sepolia_base_fee_success() {
        let base_fee = [
            1000000000, 1000000000, 1000000000, 1072671875, 1059263476, 1049238967, 1049238967, 0,
            1, 2,
        ];
        let gas_used = [
            10000000, 10000000, 10000000, 9000000, 10001000, 0, 10000000, 10000000, 10000000,
            10000000,
        ];
        let gas_limit = [
            10000000, 12000000, 14000000, 10000000, 14000000, 2000000, 18000000, 18000000,
            18000000, 18000000,
        ];
        let next_base_fee = [
            1100000048, 1080000000, 1065714297, 1167067046, 1128881311, 1028254188, 1098203452, 1,
            2, 3,
        ];

        for i in 0..base_fee.len() {
            assert_eq!(
                next_base_fee[i],
                calc_next_block_base_fee(
                    gas_used[i],
                    gas_limit[i],
                    base_fee[i],
                    BaseFeeParams::optimism_sepolia(),
                )
            );
        }
    }

    #[test]
    fn calculate_optimism_base_fee_success() {
        let base_fee = [
            1000000000, 1000000000, 1000000000, 1072671875, 1059263476, 1049238967, 1049238967, 0,
            1, 2,
        ];
        let gas_used = [
            10000000, 10000000, 10000000, 9000000, 10001000, 0, 10000000, 10000000, 10000000,
            10000000,
        ];
        let gas_limit = [
            10000000, 12000000, 14000000, 10000000, 14000000, 2000000, 18000000, 18000000,
            18000000, 18000000,
        ];
        let next_base_fee = [
            1100000048, 1080000000, 1065714297, 1167067046, 1128881311, 1028254188, 1098203452, 1,
            2, 3,
        ];

        for i in 0..base_fee.len() {
            assert_eq!(
                next_base_fee[i],
                calc_next_block_base_fee(
                    gas_used[i],
                    gas_limit[i],
                    base_fee[i],
                    BaseFeeParams::optimism(),
                )
            );
        }
    }

    #[test]
    fn calculate_optimism_canyon_base_fee_success() {
        let base_fee = [
            1000000000, 1000000000, 1000000000, 1072671875, 1059263476, 1049238967, 1049238967, 0,
            1, 2,
        ];
        let gas_used = [
            10000000, 10000000, 10000000, 9000000, 10001000, 0, 10000000, 10000000, 10000000,
            10000000,
        ];
        let gas_limit = [
            10000000, 12000000, 14000000, 10000000, 14000000, 2000000, 18000000, 18000000,
            18000000, 18000000,
        ];
        let next_base_fee = [
            1020000009, 1016000000, 1013142859, 1091550909, 1073187043, 1045042012, 1059031864, 1,
            2, 3,
        ];

        for i in 0..base_fee.len() {
            assert_eq!(
                next_base_fee[i],
                calc_next_block_base_fee(
                    gas_used[i],
                    gas_limit[i],
                    base_fee[i],
                    BaseFeeParams::optimism_canyon(),
                )
            );
        }
    }

    #[test]
    fn calculate_base_sepolia_base_fee_success() {
        let base_fee = [
            1000000000, 1000000000, 1000000000, 1072671875, 1059263476, 1049238967, 1049238967, 0,
            1, 2,
        ];
        let gas_used = [
            10000000, 10000000, 10000000, 9000000, 10001000, 0, 10000000, 10000000, 10000000,
            10000000,
        ];
        let gas_limit = [
            10000000, 12000000, 14000000, 10000000, 14000000, 2000000, 18000000, 18000000,
            18000000, 18000000,
        ];
        let next_base_fee = [
            1180000000, 1146666666, 1122857142, 1244299375, 1189416692, 1028254188, 1144836295, 1,
            2, 3,
        ];

        for i in 0..base_fee.len() {
            assert_eq!(
                next_base_fee[i],
                calc_next_block_base_fee(
                    gas_used[i],
                    gas_limit[i],
                    base_fee[i],
                    BaseFeeParams::base_sepolia(),
                )
            );
        }
    }

    #[test]
    fn next_base_fee_no_panic_zero_elasticity() {
        let p = BaseFeeParams::new(8, 0);
        assert_eq!(calc_next_block_base_fee(1, 30_000_000, 1_000_000_000, p), 1_000_000_000);
    }

    #[test]
    fn next_base_fee_no_panic_zero_denominator() {
        let p = BaseFeeParams::new(0, 2);
        assert_eq!(
            calc_next_block_base_fee(15_000_000, 30_000_000, 1_000_000_000, p),
            1_000_000_000
        );
    }

    #[test]
    fn next_base_fee_no_panic_gas_limit_below_elasticity() {
        let p = BaseFeeParams::ethereum();
        // gas_target = 1 / 2 = 0; gas_used > 0 used to hit a divide-by-zero in the increase path.
        assert_eq!(calc_next_block_base_fee(1, 1, 1_000_000_000, p), 1_000_000_000);
    }
}