revm_context_interface/cfg/
gas.rs

1//! Gas constants and functions for gas calculation.
2
3use crate::{cfg::GasParams, transaction::AccessListItemTr as _, Transaction, TransactionType};
4use primitives::hardfork::SpecId;
5
6/// Tracker for gas during execution.
7///
8/// This is used to track the gas during execution.
9#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
10#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
11pub struct GasTracker {
12    /// Gas Limit,
13    gas_limit: u64,
14    /// Regular gas remaining (`gas_left`). Reservoir is tracked separately.
15    remaining: u64,
16    /// State gas reservoir (gas exceeding TX_MAX_GAS_LIMIT). Starts as `execution_gas - min(execution_gas, regular_gas_budget)`.
17    /// When 0, all remaining gas is regular gas with hard cap at `TX_MAX_GAS_LIMIT`.
18    reservoir: u64,
19    /// Total state gas spent so far.
20    state_gas_spent: u64,
21    /// Refunded gas. Used to refund the gas to the caller at the end of execution.
22    refunded: i64,
23}
24
25impl GasTracker {
26    /// Creates a new `GasTracker` with the given remaining gas and reservoir.
27    #[inline]
28    pub const fn new(gas_limit: u64, remaining: u64, reservoir: u64) -> Self {
29        Self {
30            gas_limit,
31            remaining,
32            reservoir,
33            state_gas_spent: 0,
34            refunded: 0,
35        }
36    }
37
38    /// Creates a new `GasTracker` with the given used gas and reservoir.
39    #[inline]
40    pub const fn new_used_gas(gas_limit: u64, used_gas: u64, reservoir: u64) -> Self {
41        Self::new(gas_limit, gas_limit - used_gas, reservoir)
42    }
43
44    /// Returns the gas limit.
45    #[inline]
46    pub const fn limit(&self) -> u64 {
47        self.gas_limit
48    }
49
50    /// Sets the gas limit.
51    #[inline]
52    pub fn set_limit(&mut self, val: u64) {
53        self.gas_limit = val;
54    }
55
56    /// Returns the remaining gas.
57    #[inline]
58    pub const fn remaining(&self) -> u64 {
59        self.remaining
60    }
61
62    /// Sets the remaining gas.
63    #[inline]
64    pub fn set_remaining(&mut self, val: u64) {
65        self.remaining = val;
66    }
67
68    /// Returns the reservoir gas.
69    #[inline]
70    pub const fn reservoir(&self) -> u64 {
71        self.reservoir
72    }
73
74    /// Sets the reservoir gas.
75    #[inline]
76    pub fn set_reservoir(&mut self, val: u64) {
77        self.reservoir = val;
78    }
79
80    /// Returns the state gas spent.
81    #[inline]
82    pub const fn state_gas_spent(&self) -> u64 {
83        self.state_gas_spent
84    }
85
86    /// Sets the state gas spent.
87    #[inline]
88    pub fn set_state_gas_spent(&mut self, val: u64) {
89        self.state_gas_spent = val;
90    }
91
92    /// Returns the refunded gas.
93    #[inline]
94    pub const fn refunded(&self) -> i64 {
95        self.refunded
96    }
97
98    /// Sets the refunded gas.
99    #[inline]
100    pub fn set_refunded(&mut self, val: i64) {
101        self.refunded = val;
102    }
103
104    /// Records a regular gas cost.
105    ///
106    /// Deducts from `remaining`. Returns `false` if insufficient gas.
107    #[inline]
108    #[must_use = "In case of not enough gas, the interpreter should halt with an out-of-gas error"]
109    pub fn record_regular_cost(&mut self, cost: u64) -> bool {
110        if let Some(new_remaining) = self.remaining.checked_sub(cost) {
111            self.remaining = new_remaining;
112            return true;
113        }
114        false
115    }
116
117    /// Records a state gas cost (EIP-8037 reservoir model).
118    ///
119    /// State gas charges deduct from the reservoir first. If the reservoir is exhausted,
120    /// remaining charges spill into `remaining` (requiring `remaining >= cost`).
121    /// Tracks state gas spent.
122    ///
123    /// Returns `false` if total remaining gas is insufficient.
124    #[inline]
125    #[must_use = "In case of not enough gas, the interpreter should halt with an out-of-gas error"]
126    pub fn record_state_cost(&mut self, cost: u64) -> bool {
127        if self.reservoir >= cost {
128            self.state_gas_spent = self.state_gas_spent.saturating_add(cost);
129            self.reservoir -= cost;
130            return true;
131        }
132
133        let spill = cost - self.reservoir;
134
135        let success = self.record_regular_cost(spill);
136        if success {
137            self.state_gas_spent = self.state_gas_spent.saturating_add(cost);
138            self.reservoir = 0;
139        }
140        success
141    }
142
143    /// Records a refund value.
144    #[inline]
145    pub fn record_refund(&mut self, refund: i64) {
146        self.refunded += refund;
147    }
148
149    /// Erases a gas cost from remaining (returns gas from child frame).
150    #[inline]
151    pub fn erase_cost(&mut self, returned: u64) {
152        self.remaining += returned;
153    }
154
155    /// Spends all remaining gas excluding the reservoir.
156    #[inline]
157    pub fn spend_all(&mut self) {
158        self.remaining = 0;
159    }
160}
161
162/// Gas cost for operations that consume zero gas.
163pub const ZERO: u64 = 0;
164/// Base gas cost for basic operations.
165pub const BASE: u64 = 2;
166
167/// Gas cost for very low-cost operations.
168pub const VERYLOW: u64 = 3;
169/// Gas cost for DATALOADN instruction.
170pub const DATA_LOADN_GAS: u64 = 3;
171
172/// Gas cost for conditional jump instructions.
173pub const CONDITION_JUMP_GAS: u64 = 4;
174/// Gas cost for RETF instruction.
175pub const RETF_GAS: u64 = 3;
176/// Gas cost for DATALOAD instruction.
177pub const DATA_LOAD_GAS: u64 = 4;
178
179/// Gas cost for low-cost operations.
180pub const LOW: u64 = 5;
181/// Gas cost for medium-cost operations.
182pub const MID: u64 = 8;
183/// Gas cost for high-cost operations.
184pub const HIGH: u64 = 10;
185/// Gas cost for JUMPDEST instruction.
186pub const JUMPDEST: u64 = 1;
187/// Gas cost for REFUND SELFDESTRUCT instruction.
188pub const SELFDESTRUCT_REFUND: i64 = 24000;
189/// Gas cost for CREATE instruction.
190pub const CREATE: u64 = 32000;
191/// Additional gas cost when a call transfers value.
192pub const CALLVALUE: u64 = 9000;
193/// Gas cost for creating a new account.
194pub const NEWACCOUNT: u64 = 25000;
195/// Base gas cost for EXP instruction.
196pub const EXP: u64 = 10;
197/// Gas cost per word for memory operations.
198pub const MEMORY: u64 = 3;
199/// Base gas cost for LOG instructions.
200pub const LOG: u64 = 375;
201/// Gas cost per byte of data in LOG instructions.
202pub const LOGDATA: u64 = 8;
203/// Gas cost per topic in LOG instructions.
204pub const LOGTOPIC: u64 = 375;
205/// Base gas cost for KECCAK256 instruction.
206pub const KECCAK256: u64 = 30;
207/// Gas cost per word for KECCAK256 instruction.
208pub const KECCAK256WORD: u64 = 6;
209/// Gas cost per word for copy operations.
210pub const COPY: u64 = 3;
211/// Gas cost for BLOCKHASH instruction.
212pub const BLOCKHASH: u64 = 20;
213/// Gas cost per byte for code deposit during contract creation.
214pub const CODEDEPOSIT: u64 = 200;
215
216/// EIP-1884: Repricing for trie-size-dependent opcodes
217pub const ISTANBUL_SLOAD_GAS: u64 = 800;
218/// Gas cost for SSTORE when setting a storage slot from zero to non-zero.
219pub const SSTORE_SET: u64 = 20000;
220/// Gas cost for SSTORE when modifying an existing non-zero storage slot.
221pub const SSTORE_RESET: u64 = 5000;
222/// Gas refund for SSTORE when clearing a storage slot (setting to zero).
223pub const REFUND_SSTORE_CLEARS: i64 = 15000;
224
225/// The standard cost of calldata token.
226pub const STANDARD_TOKEN_COST: u64 = 4;
227/// The cost of a non-zero byte in calldata.
228pub const NON_ZERO_BYTE_DATA_COST: u64 = 68;
229/// The multiplier for a non zero byte in calldata.
230pub const NON_ZERO_BYTE_MULTIPLIER: u64 = NON_ZERO_BYTE_DATA_COST / STANDARD_TOKEN_COST;
231/// The cost of a non-zero byte in calldata adjusted by [EIP-2028](https://eips.ethereum.org/EIPS/eip-2028).
232pub const NON_ZERO_BYTE_DATA_COST_ISTANBUL: u64 = 16;
233/// The multiplier for a non zero byte in calldata adjusted by [EIP-2028](https://eips.ethereum.org/EIPS/eip-2028).
234pub const NON_ZERO_BYTE_MULTIPLIER_ISTANBUL: u64 =
235    NON_ZERO_BYTE_DATA_COST_ISTANBUL / STANDARD_TOKEN_COST;
236/// The cost floor per token as defined by EIP-2028.
237pub const TOTAL_COST_FLOOR_PER_TOKEN: u64 = 10;
238
239/// Gas cost for EOF CREATE instruction.
240pub const EOF_CREATE_GAS: u64 = 32000;
241
242// Berlin EIP-2929/EIP-2930 constants
243/// Gas cost for accessing an address in the access list (EIP-2930).
244pub const ACCESS_LIST_ADDRESS: u64 = 2400;
245/// Gas cost for accessing a storage key in the access list (EIP-2930).
246pub const ACCESS_LIST_STORAGE_KEY: u64 = 1900;
247
248/// Gas cost for SLOAD when accessing a cold storage slot (EIP-2929).
249pub const COLD_SLOAD_COST: u64 = 2100;
250/// Gas cost for accessing a cold account (EIP-2929).
251pub const COLD_ACCOUNT_ACCESS_COST: u64 = 2600;
252/// Additional gas cost for accessing a cold account.
253pub const COLD_ACCOUNT_ACCESS_COST_ADDITIONAL: u64 =
254    COLD_ACCOUNT_ACCESS_COST - WARM_STORAGE_READ_COST;
255/// Gas cost for reading from a warm storage slot (EIP-2929).
256pub const WARM_STORAGE_READ_COST: u64 = 100;
257/// Gas cost for SSTORE reset operation on a warm storage slot.
258pub const WARM_SSTORE_RESET: u64 = SSTORE_RESET - COLD_SLOAD_COST;
259
260/// EIP-3860 : Limit and meter initcode
261pub const INITCODE_WORD_COST: u64 = 2;
262
263/// Gas stipend provided to the recipient of a CALL with value transfer.
264pub const CALL_STIPEND: u64 = 2300;
265
266/// Init and floor gas from transaction
267#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
268#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
269pub struct InitialAndFloorGas {
270    /// Initial gas for transaction.
271    pub initial_total_gas: u64,
272    /// State gas component of initial_gas (subset of initial_total_gas).
273    /// Under EIP-8037, this includes:
274    /// - EIP-7702 auth list state gas (per-auth account creation + metadata costs)
275    /// - For CREATE transactions: `create_state_gas` (account creation + contract metadata)
276    /// - For CALL transactions: 0 (state gas is unpredictable at validation time)
277    pub initial_state_gas: u64,
278    /// If transaction is a Call and Prague is enabled
279    /// floor_gas is at least amount of gas that is going to be spent.
280    pub floor_gas: u64,
281    /// EIP-7702 state gas refund for existing authorities.
282    /// Added to the reservoir after initial_state_gas is deducted.
283    /// In the Python spec, set_delegation adds this back to state_gas_reservoir
284    /// rather than reducing initial_state_gas, so the refunded gas stays as
285    /// reservoir gas (not regular gas).
286    pub eip7702_reservoir_refund: u64,
287}
288
289impl InitialAndFloorGas {
290    /// Create a new InitialAndFloorGas instance.
291    #[inline]
292    pub const fn new(initial_total_gas: u64, floor_gas: u64) -> Self {
293        Self {
294            initial_total_gas,
295            initial_state_gas: 0,
296            floor_gas,
297            eip7702_reservoir_refund: 0,
298        }
299    }
300
301    /// Create a new InitialAndFloorGas instance with state gas tracking.
302    #[inline]
303    pub const fn new_with_state_gas(
304        initial_total_gas: u64,
305        initial_state_gas: u64,
306        floor_gas: u64,
307    ) -> Self {
308        Self {
309            initial_total_gas,
310            initial_state_gas,
311            floor_gas,
312            eip7702_reservoir_refund: 0,
313        }
314    }
315
316    /// Regular (non-state) portion of the initial intrinsic gas.
317    ///
318    /// Under EIP-8037, this is the part constrained by `TX_MAX_GAS_LIMIT`;
319    /// state gas uses its own reservoir and is not subject to that cap.
320    #[inline]
321    pub const fn initial_regular_gas(&self) -> u64 {
322        self.initial_total_gas - self.initial_state_gas
323    }
324
325    /// Computes the regular gas budget and reservoir for the initial call frame.
326    ///
327    /// EIP-8037 reservoir model:
328    ///   execution_gas = tx.gas_limit - intrinsic_gas  (= gas_limit parameter)
329    ///   regular_gas_budget = min(execution_gas, TX_MAX_GAS_LIMIT - intrinsic_gas)
330    ///   reservoir = execution_gas - regular_gas_budget
331    ///
332    /// Initial state gas is then deducted from the reservoir (spilling into the
333    /// regular budget when the reservoir is insufficient), and the EIP-7702
334    /// refund for existing authorities is added back to the reservoir.
335    ///
336    /// On mainnet (state gas disabled), reservoir = 0 and gas_limit is unchanged.
337    ///
338    /// Returns `(gas_limit, reservoir)`.
339    pub fn initial_gas_and_reservoir(
340        &self,
341        tx_gas_limit: u64,
342        tx_gas_limit_cap: u64,
343        is_eip8037: bool,
344    ) -> (u64, u64) {
345        let execution_gas = tx_gas_limit - self.initial_regular_gas();
346
347        // System calls pass InitialAndFloorGas with all zeros and should not be
348        // subject to the TX_MAX_GAS_LIMIT cap.
349        let regular_gas_cap = if self.initial_total_gas == 0 {
350            u64::MAX
351        } else if is_eip8037 {
352            tx_gas_limit_cap.saturating_sub(self.initial_regular_gas())
353        } else {
354            tx_gas_limit_cap
355        };
356
357        let mut gas_limit = core::cmp::min(execution_gas, regular_gas_cap);
358        let mut reservoir = execution_gas - gas_limit;
359
360        // Deduct initial state gas from the reservoir. When the reservoir is
361        // insufficient, the deficit is charged from the regular gas budget.
362        if self.initial_state_gas > 0 {
363            if reservoir >= self.initial_state_gas {
364                reservoir -= self.initial_state_gas;
365            } else {
366                gas_limit -= self.initial_state_gas - reservoir;
367                reservoir = 0;
368            }
369        }
370
371        // EIP-7702 state gas refund for existing authorities goes directly to
372        // the reservoir. In the Python spec, set_delegation adds this refund to
373        // state_gas_reservoir so it stays as state gas (not regular gas).
374        if self.eip7702_reservoir_refund > 0 {
375            reservoir += self.eip7702_reservoir_refund;
376        }
377
378        (gas_limit, reservoir)
379    }
380}
381
382/// Initial gas that is deducted for transaction to be included.
383/// Initial gas contains initial stipend gas, gas for access list and input data.
384///
385/// # Returns
386///
387/// - Intrinsic gas
388/// - Number of tokens in calldata
389pub fn calculate_initial_tx_gas(
390    spec_id: SpecId,
391    input: &[u8],
392    is_create: bool,
393    access_list_accounts: u64,
394    access_list_storages: u64,
395    authorization_list_num: u64,
396) -> InitialAndFloorGas {
397    GasParams::new_spec(spec_id).initial_tx_gas(
398        input,
399        is_create,
400        access_list_accounts,
401        access_list_storages,
402        authorization_list_num,
403    )
404}
405
406/// Initial gas that is deducted for transaction to be included.
407/// Initial gas contains initial stipend gas, gas for access list and input data.
408///
409/// # Returns
410///
411/// - Intrinsic gas
412/// - Number of tokens in calldata
413pub fn calculate_initial_tx_gas_for_tx(tx: impl Transaction, spec: SpecId) -> InitialAndFloorGas {
414    let mut accounts = 0;
415    let mut storages = 0;
416    // legacy is only tx type that does not have access list.
417    if tx.tx_type() != TransactionType::Legacy {
418        (accounts, storages) = tx
419            .access_list()
420            .map(|al| {
421                al.fold((0, 0), |(mut num_accounts, mut num_storage_slots), item| {
422                    num_accounts += 1;
423                    num_storage_slots += item.storage_slots().count();
424
425                    (num_accounts, num_storage_slots)
426                })
427            })
428            .unwrap_or_default();
429    }
430
431    calculate_initial_tx_gas(
432        spec,
433        tx.input(),
434        tx.kind().is_create(),
435        accounts as u64,
436        storages as u64,
437        tx.authorization_list_len() as u64,
438    )
439}
440
441/// Retrieve the total number of tokens in calldata.
442#[inline]
443pub fn get_tokens_in_calldata_istanbul(input: &[u8]) -> u64 {
444    get_tokens_in_calldata(input, NON_ZERO_BYTE_MULTIPLIER_ISTANBUL)
445}
446
447/// Retrieve the total number of tokens in calldata.
448#[inline]
449pub fn get_tokens_in_calldata(input: &[u8], non_zero_data_multiplier: u64) -> u64 {
450    let zero_data_len = input.iter().filter(|v| **v == 0).count() as u64;
451    let non_zero_data_len = input.len() as u64 - zero_data_len;
452    zero_data_len + non_zero_data_len * non_zero_data_multiplier
453}
revm_context_interface/cfg/gas.rs

revm_context_interface/cfg/
gas.rs
