diff --git a/.changeset/debug-trace-gas-dimensions.md b/.changeset/debug-trace-gas-dimensions.md new file mode 100644 index 0000000000..dfb612c97d --- /dev/null +++ b/.changeset/debug-trace-gas-dimensions.md @@ -0,0 +1,6 @@ +--- +"@nomicfoundation/edr": patch +--- + +- Added the EIP-8037 gas dimensions to `debug_traceTransaction` and `debug_traceCall` responses from the Amsterdam hardfork: the default tracer's top-level frame and the `callTracer`'s root call frame gain `executionGasUsed`, `stateGasUsed` and `gasRefund`, and each `structLogs` entry gains `stateGasReservoir`, plus a signed `stateGasCost` on the steps that charge or refill state gas. +- Added the `stateGasTracer`, which reports a transaction's gas in both dimensions on every hardfork, with zero state gas before Amsterdam. diff --git a/crates/edr_provider/tests/integration/eip8037.rs b/crates/edr_provider/tests/integration/eip8037.rs index 4d60d41ebe..57ce6c75b6 100644 --- a/crates/edr_provider/tests/integration/eip8037.rs +++ b/crates/edr_provider/tests/integration/eip8037.rs @@ -15,6 +15,7 @@ use std::num::NonZeroU64; +use alloy_rpc_types_trace::geth::{CallConfig, GethDebugTracingOptions}; use edr_block_api::Block as _; use edr_block_header::HeaderOverrides; use edr_chain_l1::{ @@ -27,7 +28,7 @@ use edr_chain_spec_evm::result::ResultGas; use edr_eip7825::OSAKA_TRANSACTION_GAS_CAP; use edr_eip8037::TX_MAX_TOTAL_GAS_LIMIT; use edr_mem_pool::MemPoolAddTransactionError; -use edr_primitives::{address, Address, Bytecode, Bytes, U256}; +use edr_primitives::{address, Address, Bytecode, Bytes, B256, U256}; use edr_provider::{ config::{ConfigOption, ProviderConfig}, observability::EvmObservedData, @@ -35,16 +36,20 @@ use edr_provider::{ create_test_config, one_ether, set_genesis_state_with_owned_accounts, ProviderTestFixture, }, AccountOverride, MethodInvocation, MineBlockResultWithMetadataForChainSpec, Provider, - ProviderError, ProviderRequest, + ProviderError, ProviderRequest, ResponseWithCallTraces, }; use edr_receipt::ExecutionReceipt as _; use edr_test_utils::secret_key::secret_key_from_str; use edr_transaction::{request::TransactionRequestAndSender, TxKind}; +use revm_primitives::eip8037::{CPSB_GLAMSTERDAM, SSTORE_SET_BYTES}; use tokio::runtime; use crate::common::{ bytecode::{opcode, BytecodeBuilder}, - provider::{estimate_gas, new_provider_with_config, send_transaction, transaction_receipt}, + provider::{ + estimate_gas, new_provider_with_config, quantity_field, send_transaction, + transaction_receipt, + }, }; /// Contract creating [`FRESH_SLOTS`] new storage slots: state gas dominates. @@ -755,26 +760,44 @@ async fn estimate_gas_accepts_gas_above_cap_from_amsterdam() -> anyhow::Result<( Ok(()) } -/// This EIP makes state creation more expensive, so the same slot-creating -/// transaction costs more on Amsterdam than on Osaka, and `eth_estimateGas` -/// must account for it: its estimate is higher and funds the transaction. -#[tokio::test(flavor = "multi_thread")] -async fn estimate_gas_covers_state_gas() -> anyhow::Result<()> { - let new_provider = |hardfork| { - new_provider_with_config(|config| { - config.hardfork = hardfork; +/// Provider on `hardfork` with `contracts` at genesis and the protocol's gas +/// cap. Requests without `gas` get their block's bound, so from Amsterdam they +/// carry a state gas reservoir. +fn new_provider_with_contracts( + hardfork: edr_chain_l1::Hardfork, + contracts: impl IntoIterator, +) -> anyhow::Result> { + let contracts: Vec<_> = contracts.into_iter().collect(); + new_provider_with_config(move |config| { + config.hardfork = hardfork; + config.transaction_gas_cap = ConfigOption::Default; + config.default_transaction_gas_limit = None; + for (address, code) in contracts { config.genesis_state.insert( - SLOT_CREATOR, + address, AccountOverride { - code: Some(Bytecode::new_raw(slot_creator_code())), + code: Some(Bytecode::new_raw(code)), ..AccountOverride::default() }, ); - }) - }; + } + }) +} - let amsterdam = new_provider(edr_chain_l1::Hardfork::Amsterdam)?; - let osaka = new_provider(edr_chain_l1::Hardfork::Osaka)?; +/// Provider on `hardfork` with the slot-creating contract at genesis. +fn new_slot_creator_provider( + hardfork: edr_chain_l1::Hardfork, +) -> anyhow::Result> { + new_provider_with_contracts(hardfork, [(SLOT_CREATOR, slot_creator_code())]) +} + +/// This EIP makes state creation more expensive, so the same slot-creating +/// transaction costs more on Amsterdam than on Osaka, and `eth_estimateGas` +/// must account for it: its estimate is higher and funds the transaction. +#[tokio::test(flavor = "multi_thread")] +async fn estimate_gas_covers_state_gas() -> anyhow::Result<()> { + let amsterdam = new_slot_creator_provider(edr_chain_l1::Hardfork::Amsterdam)?; + let osaka = new_slot_creator_provider(edr_chain_l1::Hardfork::Osaka)?; let send_with_gas = |gas: u64| -> anyhow::Result { let transaction_hash = send_transaction( @@ -822,3 +845,437 @@ async fn estimate_gas_covers_state_gas() -> anyhow::Result<()> { Ok(()) } + +/// State gas of one fresh slot. +const SLOT_CREATION_STATE_GAS: u64 = SSTORE_SET_BYTES * CPSB_GLAMSTERDAM; + +/// The EIP-8037 fields of a default or `callTracer` frame. +const FRAME_FIELDS: [&str; 3] = ["executionGasUsed", "stateGasUsed", "gasRefund"]; + +/// Asserts that `frame` reports none of the EIP-8037 fields. +fn assert_no_gas_dimensions(frame: &serde_json::Value) { + for field in FRAME_FIELDS { + assert!( + frame.get(field).is_none(), + "unexpected `{field}` in {frame}" + ); + } +} + +/// Mines a transaction calling `to` without data and returns its hash. +fn send_to(provider: &Provider, to: Address) -> anyhow::Result { + send_transaction( + provider, + TransactionRequest { + from: caller(provider), + to: Some(to), + ..TransactionRequest::default() + }, + ) +} + +fn slot_creation_call(provider: &Provider) -> L1CallRequest { + L1CallRequest { + from: Some(caller(provider)), + to: Some(SLOT_CREATOR), + ..L1CallRequest::default() + } +} + +/// Serialized `debug_trace*` result, as a client would see it. +fn debug_trace( + provider: &Provider, + method: MethodInvocation, +) -> anyhow::Result { + let response: ResponseWithCallTraces = + provider.handle_request(ProviderRequest::with_single(method))?; + Ok(response.deserialize_result()?) +} + +/// The `stateGasCost` a struct log reports: positive for a state charge, +/// negative for a refill. Panics if the step reports none. +fn state_gas_cost(log: &serde_json::Value) -> i64 { + log["stateGasCost"] + .as_i64() + .unwrap_or_else(|| panic!("the step reports no state gas cost: {log}")) +} + +/// The EIP-8037 gas dimensions a default or `callTracer` frame reports. +struct GasDimensions { + gas_used: u64, + execution_gas_used: u64, + state_gas_used: u64, + gas_refund: u64, +} + +/// Reads the EIP-8037 gas dimensions of a frame, asserting that they add up to +/// its gas before refunds. +fn gas_dimensions(frame: &serde_json::Value, gas_used_key: &str) -> anyhow::Result { + let dimensions = GasDimensions { + gas_used: quantity_field(frame, gas_used_key)?, + execution_gas_used: quantity_field(frame, "executionGasUsed")?, + state_gas_used: quantity_field(frame, "stateGasUsed")?, + gas_refund: quantity_field(frame, "gasRefund")?, + }; + + assert_eq!( + dimensions.execution_gas_used + dimensions.state_gas_used, + dimensions.gas_used + dimensions.gas_refund, + "the dimensions should add up to the gas before refunds: {frame}" + ); + + Ok(dimensions) +} + +/// Asserts the gas dimensions of a frame executing a transaction that creates +/// [`FRESH_SLOTS`] slots: all of its state gas is the creations, nothing is +/// refunded. +fn assert_slot_creation_gas_dimensions( + frame: &serde_json::Value, + gas_used_key: &str, +) -> anyhow::Result<()> { + let dimensions = gas_dimensions(frame, gas_used_key)?; + + let expected_state_gas_used = u64::from(FRESH_SLOTS) * SLOT_CREATION_STATE_GAS; + assert_eq!( + dimensions.state_gas_used, expected_state_gas_used, + "state gas should be the slot creations alone: {frame}" + ); + assert_eq!( + dimensions.gas_refund, 0, + "creating slots refunds nothing: {frame}" + ); + + Ok(()) +} + +/// From Amsterdam, `debug_traceTransaction` reports execution and state gas +/// separately: per transaction on the frame and per opcode in the struct logs. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_transaction_reports_gas_dimensions_from_amsterdam() -> anyhow::Result<()> { + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Amsterdam)?; + let transaction_hash = send_to(&provider, SLOT_CREATOR)?; + + let trace = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction(transaction_hash, None), + )?; + + assert_slot_creation_gas_dimensions(&trace, "gas")?; + assert_eq!( + quantity_field(&trace, "gas")?, + transaction_receipt(&provider, transaction_hash)?.gas_used, + "the frame's gas should match the receipt" + ); + + let struct_logs = trace["structLogs"] + .as_array() + .expect("structLogs is an array"); + let reservoir = |log: &serde_json::Value| -> u64 { + log["stateGasReservoir"] + .as_u64() + .unwrap_or_else(|| panic!("every step reports the reservoir: {log}")) + }; + let (sstores, other_opcodes): (Vec<_>, Vec<_>) = + struct_logs.iter().partition(|log| log["op"] == "SSTORE"); + + // The SSTOREs are the only state-creating opcodes in `slot_creator_code`, + // and only state-creating steps report a cost. + for log in other_opcodes { + assert!(log.get("stateGasCost").is_none(), "{log}"); + } + + // A step reports the reservoir before executing. + let initial_reservoir = reservoir(sstores[0]); + assert!( + initial_reservoir > 0, + "the protocol gas cap funds a reservoir" + ); + // Each slot creation drains the reservoir its predecessor saw by one + // `SLOT_CREATION_STATE_GAS`. + let expected_reservoirs: Vec = (0..u64::from(FRESH_SLOTS)) + .map(|created| initial_reservoir - created * SLOT_CREATION_STATE_GAS) + .collect(); + let reservoirs: Vec = sstores.iter().copied().map(reservoir).collect(); + assert_eq!(reservoirs, expected_reservoirs); + + // Every slot is fresh, so every SSTORE costs the same state gas. + let expected_costs = vec![i64::try_from(SLOT_CREATION_STATE_GAS)?; sstores.len()]; + let costs: Vec = sstores.iter().copied().map(state_gas_cost).collect(); + assert_eq!(costs, expected_costs); + + Ok(()) +} + +/// From Amsterdam, the `callTracer` reports both dimensions on the root frame. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_transaction_call_tracer_reports_gas_dimensions_from_amsterdam( +) -> anyhow::Result<()> { + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Amsterdam)?; + let transaction_hash = send_to(&provider, SLOT_CREATOR)?; + + let frame = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction( + transaction_hash, + Some(GethDebugTracingOptions::call_tracer(CallConfig::default())), + ), + )?; + + assert_slot_creation_gas_dimensions(&frame, "gasUsed")?; + + Ok(()) +} + +/// From Amsterdam, `debug_traceCall` reports both dimensions as well. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_call_reports_gas_dimensions_from_amsterdam() -> anyhow::Result<()> { + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Amsterdam)?; + + let trace = debug_trace( + &provider, + MethodInvocation::DebugTraceCall(slot_creation_call(&provider), None, None), + )?; + + assert_slot_creation_gas_dimensions(&trace, "gas")?; + + Ok(()) +} + +/// Before Amsterdam, gas has one dimension and the responses are unchanged: +/// none of the EIP-8037 fields are present. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_omits_gas_dimensions_before_amsterdam() -> anyhow::Result<()> { + const STEP_FIELDS: [&str; 2] = ["stateGasCost", "stateGasReservoir"]; + + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Osaka)?; + let transaction_hash = send_to(&provider, SLOT_CREATOR)?; + + let default_trace = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction(transaction_hash, None), + )?; + let call_frame = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction( + transaction_hash, + Some(GethDebugTracingOptions::call_tracer(CallConfig::default())), + ), + )?; + let call_trace = debug_trace( + &provider, + MethodInvocation::DebugTraceCall(slot_creation_call(&provider), None, None), + )?; + let call_trace_call_frame = debug_trace( + &provider, + MethodInvocation::DebugTraceCall( + slot_creation_call(&provider), + None, + Some(GethDebugTracingOptions::call_tracer(CallConfig::default())), + ), + )?; + + for frame in [ + &default_trace, + &call_frame, + &call_trace, + &call_trace_call_frame, + ] { + assert_no_gas_dimensions(frame); + } + // The step that creates state is the one that would carry the fields. + let sstore = default_trace["structLogs"] + .as_array() + .expect("structLogs is an array") + .iter() + .find(|log| log["op"] == "SSTORE") + .expect("the transaction stores"); + for field in STEP_FIELDS { + assert!( + sstore.get(field).is_none(), + "unexpected `{field}` in {sstore}" + ); + } + + Ok(()) +} + +/// From Amsterdam, the `stateGasTracer` reports the transaction's gas in both +/// dimensions. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_transaction_state_gas_tracer_reports_gas_dimensions_from_amsterdam( +) -> anyhow::Result<()> { + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Amsterdam)?; + let transaction_hash = send_to(&provider, SLOT_CREATOR)?; + + let trace = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction( + transaction_hash, + Some(GethDebugTracingOptions::state_gas_tracer()), + ), + )?; + + assert_slot_creation_gas_dimensions(&trace, "gasUsed")?; + + Ok(()) +} + +/// Before Amsterdam, the `stateGasTracer` still answers, with no state gas: +/// all the gas before refunds is execution gas. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_transaction_state_gas_tracer_reports_no_state_gas_before_amsterdam( +) -> anyhow::Result<()> { + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Osaka)?; + let transaction_hash = send_to(&provider, SLOT_CREATOR)?; + + let trace = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction( + transaction_hash, + Some(GethDebugTracingOptions::state_gas_tracer()), + ), + )?; + + let dimensions = gas_dimensions(&trace, "gasUsed")?; + assert_eq!( + dimensions.state_gas_used, 0, + "no state gas before Amsterdam: {trace}" + ); + assert_eq!( + dimensions.execution_gas_used, + dimensions.gas_used + dimensions.gas_refund, + "all the gas before refunds is execution gas before Amsterdam: {trace}" + ); + + Ok(()) +} + +/// Contract writing one fresh slot and clearing it again in the same +/// transaction. +const SLOT_RESTORER: Address = address!("0x0000000000000000000000000000000000000f0f"); + +/// `PUSH1 1; PUSH1 1; SSTORE; PUSH1 0; PUSH1 1; SSTORE`. +fn slot_restorer_code() -> Bytes { + let mut code = BytecodeBuilder::default(); + code.push1(1).push1(1).opcode(opcode::SSTORE); + code.push1(0).push1(1).opcode(opcode::SSTORE); + code.opcode(opcode::STOP); + code.runtime() +} + +/// Clearing a slot created in the same transaction refills its state gas: the +/// step reports a negative `stateGasCost`, the transaction's `stateGasUsed` +/// nets to zero and the clear earns a refund. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_transaction_reports_state_gas_refill_from_amsterdam() -> anyhow::Result<()> { + let provider = new_provider_with_contracts( + edr_chain_l1::Hardfork::Amsterdam, + [(SLOT_RESTORER, slot_restorer_code())], + )?; + let transaction_hash = send_to(&provider, SLOT_RESTORER)?; + + let trace = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction(transaction_hash, None), + )?; + + let slot_creation_state_gas = i64::try_from(SLOT_CREATION_STATE_GAS)?; + let state_gas_costs: Vec = trace["structLogs"] + .as_array() + .expect("structLogs is an array") + .iter() + .filter(|log| log["op"] == "SSTORE") + .map(state_gas_cost) + .collect(); + + assert_eq!( + state_gas_costs, + [slot_creation_state_gas, -slot_creation_state_gas], + "creating the slot costs its state gas and clearing it refills it" + ); + + let dimensions = gas_dimensions(&trace, "gas")?; + assert_eq!( + dimensions.state_gas_used, 0, + "the refill nets the transaction's state gas to zero: {trace}" + ); + assert!( + dimensions.gas_refund > 0, + "clearing the slot earns a refund: {trace}" + ); + + Ok(()) +} + +/// From Amsterdam, `debug_traceCall` with the `callTracer` reports both +/// dimensions on the root frame, like `debug_traceTransaction` does. +#[tokio::test(flavor = "multi_thread")] +async fn debug_trace_call_call_tracer_reports_gas_dimensions_from_amsterdam() -> anyhow::Result<()> +{ + let provider = new_slot_creator_provider(edr_chain_l1::Hardfork::Amsterdam)?; + + let frame = debug_trace( + &provider, + MethodInvocation::DebugTraceCall( + slot_creation_call(&provider), + None, + Some(GethDebugTracingOptions::call_tracer(CallConfig::default())), + ), + )?; + + assert_slot_creation_gas_dimensions(&frame, "gasUsed")?; + + Ok(()) +} + +/// Contract forwarding all its gas to [`SLOT_CREATOR`] in a nested `CALL`. +const SLOT_CREATOR_CALLER: Address = address!("0x000000000000000000000000000000000000ca11"); + +/// `CALL` into [`SLOT_CREATOR`] with all remaining gas, no value and no data. +fn slot_creator_caller_code() -> Bytes { + let mut code = BytecodeBuilder::default(); + // retSize, retOffset, argsSize, argsOffset, value + code.push1(0).push1(0).push1(0).push1(0).push1(0); + code.opcode(opcode::PUSH20); + for byte in SLOT_CREATOR { + code.opcode(byte); + } + code.opcode(opcode::GAS) + .opcode(opcode::CALL) + .opcode(opcode::POP); + code.opcode(opcode::STOP); + code.runtime() +} + +/// The `callTracer` reports the dimensions on the root frame only. +#[tokio::test(flavor = "multi_thread")] +async fn call_tracer_reports_gas_dimensions_on_root_frame_only() -> anyhow::Result<()> { + let provider = new_provider_with_contracts( + edr_chain_l1::Hardfork::Amsterdam, + [ + (SLOT_CREATOR, slot_creator_code()), + (SLOT_CREATOR_CALLER, slot_creator_caller_code()), + ], + )?; + let transaction_hash = send_to(&provider, SLOT_CREATOR_CALLER)?; + + let root = debug_trace( + &provider, + MethodInvocation::DebugTraceTransaction( + transaction_hash, + Some(GethDebugTracingOptions::call_tracer(CallConfig::default())), + ), + )?; + + assert_slot_creation_gas_dimensions(&root, "gasUsed")?; + + let child = root["calls"] + .as_array() + .and_then(|calls| calls.first()) + .expect("the caller makes a call"); + + assert_no_gas_dimensions(child); + + Ok(()) +}