Add gas component to debugging trace (#3796)

ddoktorski · web-flow · commit ff9fda4b8848 · 2025-10-16T17:42:02.000Z
Closes #3624
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `Fuzzable` trait implementations for `bool` and `ContractAddress`
 - Type aliases for `StarkCurveKeyPair`, `Secp256k1CurveKeyPair`, `Secp256r1CurveKeyPair`
+- Option to display L2 gas for each call in the debugging trace
 
 #### Changed
 
diff --git a/Cargo.toml b/Cargo.toml
@@ -34,7 +34,7 @@ license-file = "LICENSE"
 
 [workspace.dependencies]
 # TODO(#3770) Use blockifier directly
-blockifier = { git = "https://github.com/software-mansion-labs/sequencer.git", branch = "main-v0.14.0", features = ["testing", "tracing"] }
+blockifier = { git = "https://github.com/software-mansion-labs/sequencer.git", branch = "main-v0.14.0", features = ["testing", "tracing", "node_api"] }
 bigdecimal = "0.4.8"
 # TODO(#3770) Use starknet_api directly
 starknet_api = { git = "https://github.com/software-mansion-labs/sequencer.git", branch = "main-v0.14.0" }
diff --git a/crates/cheatnet/src/state.rs b/crates/cheatnet/src/state.rs
@@ -10,6 +10,7 @@ use crate::runtime_extensions::forge_runtime_extension::cheatcodes::cheat_execut
 };
 use crate::runtime_extensions::forge_runtime_extension::cheatcodes::spy_events::Event;
 use crate::runtime_extensions::forge_runtime_extension::cheatcodes::spy_messages_to_l1::MessageToL1;
+use blockifier::blockifier_versioned_constants::VersionedConstants;
 use blockifier::execution::call_info::{ExecutionSummary, OrderedEvent, OrderedL2ToL1Message};
 use blockifier::execution::contract_class::RunnableCompiledClass;
 use blockifier::execution::entry_point::CallEntryPoint;
@@ -29,13 +30,15 @@ use runtime::starknet::context::SerializableBlockInfo;
 use runtime::starknet::state::DictStateReader;
 use starknet_api::block::BlockInfo;
 use starknet_api::core::{ChainId, EntryPointSelector};
+use starknet_api::execution_resources::GasVector;
 use starknet_api::transaction::fields::ContractAddressSalt;
+use starknet_api::transaction::fields::GasVectorComputationMode;
 use starknet_api::{
     core::{ClassHash, CompiledClassHash, ContractAddress, Nonce},
     state::StorageKey,
 };
 use starknet_types_core::felt::Felt;
-use std::cell::{Ref, RefCell};
+use std::cell::{OnceCell, Ref, RefCell};
 use std::collections::HashMap;
 use std::num::NonZeroUsize;
 use std::rc::Rc;
@@ -203,15 +206,28 @@ impl<T> CheatStatus<T> {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct GasReportData {
     pub execution_summary: ExecutionSummary,
+    partial_gas_usage: OnceCell<GasVector>,
 }
 
 impl GasReportData {
     #[must_use]
     pub fn new(execution_summary: ExecutionSummary) -> Self {
-        Self { execution_summary }
+        Self {
+            execution_summary,
+            partial_gas_usage: OnceCell::new(),
+        }
+    }
+
+    pub fn get_gas(&self) -> &GasVector {
+        self.partial_gas_usage.get_or_init(|| {
+            self.execution_summary.clone().to_partial_gas_vector(
+                VersionedConstants::latest_constants(),
+                &GasVectorComputationMode::All,
+            )
+        })
     }
 }
 
diff --git a/crates/debugging/src/trace/collect.rs b/crates/debugging/src/trace/collect.rs
@@ -1,7 +1,7 @@
 use crate::contracts_data_store::ContractsDataStore;
 use crate::trace::types::{
-    CallerAddress, ContractAddress, ContractName, ContractTrace, Selector, TestName, TraceInfo,
-    TransformedCallResult, TransformedCalldata,
+    CallerAddress, ContractAddress, ContractName, ContractTrace, Gas, Selector, TestName,
+    TraceInfo, TransformedCallResult, TransformedCalldata,
 };
 use crate::{Context, Trace};
 use cheatnet::runtime_extensions::call_to_blockifier_runtime_extension::rpc::{
@@ -52,6 +52,7 @@ impl<'a> Collector<'a> {
             call_type: components.call_type(entry_point.call_type),
             nested_calls,
             call_result: components.call_result_lazy(|| self.collect_transformed_call_result(abi)),
+            gas: components.gas_lazy(|| self.collect_gas()),
         };
 
         ContractTrace {
@@ -125,6 +126,16 @@ impl<'a> Collector<'a> {
         })
     }
 
+    fn collect_gas(&self) -> Gas {
+        Gas(self
+            .call_trace
+            .gas_report_data
+            .as_ref()
+            .expect("Gas report data must be updated after test execution")
+            .get_gas()
+            .l2_gas)
+    }
+
     fn class_hash(&self) -> &ClassHash {
         self.call_trace
             .entry_point
diff --git a/crates/debugging/src/trace/components.rs b/crates/debugging/src/trace/components.rs
@@ -1,5 +1,5 @@
 use crate::trace::types::{
-    CallerAddress, ContractAddress, ContractName, TransformedCallResult, TransformedCalldata,
+    CallerAddress, ContractAddress, ContractName, Gas, TransformedCallResult, TransformedCalldata,
 };
 use blockifier::execution::entry_point::CallType;
 use paste::paste;
@@ -42,6 +42,8 @@ pub enum Component {
     CallType,
     /// The result of the call, transformed for display.
     CallResult,
+    /// The L2 gas used by the call.
+    Gas,
 }
 
 macro_rules! impl_component_container {
@@ -122,3 +124,4 @@ impl_component_container!(ContractAddress);
 impl_component_container!(CallerAddress);
 impl_component_container!(CallType);
 impl_component_container!(CallResult, TransformedCallResult);
+impl_component_container!(Gas);
diff --git a/crates/debugging/src/trace/types.rs b/crates/debugging/src/trace/types.rs
@@ -2,11 +2,12 @@ use crate::Context;
 use crate::trace::collect::Collector;
 use crate::trace::components::{
     CallResultContainer, CallTypeContainer, CalldataContainer, CallerAddressContainer,
-    ContractAddressContainer, ContractNameContainer, EntryPointTypeContainer,
+    ContractAddressContainer, ContractNameContainer, EntryPointTypeContainer, GasContainer,
 };
 use crate::tree::TreeSerialize;
 use cheatnet::state::CallTrace;
 use starknet_api::core::ContractAddress as ApiContractAddress;
+use starknet_api::execution_resources::GasAmount as ApiGasAmount;
 use std::fmt;
 use std::fmt::Display;
 
@@ -32,6 +33,7 @@ pub struct TraceInfo {
     pub call_type: CallTypeContainer,
     pub nested_calls: Vec<ContractTrace>,
     pub call_result: CallResultContainer,
+    pub gas: GasContainer,
 }
 
 #[derive(Debug, Clone)]
@@ -55,6 +57,9 @@ pub struct ContractAddress(pub ApiContractAddress);
 #[derive(Debug, Clone)]
 pub struct CallerAddress(pub ApiContractAddress);
 
+#[derive(Debug, Clone)]
+pub struct Gas(pub ApiGasAmount);
+
 impl Trace {
     /// Creates a new [`Trace`] from a given [`Context`] and a test name.
     #[must_use]
diff --git a/crates/debugging/src/tree/ui/as_tree_node.rs b/crates/debugging/src/tree/ui/as_tree_node.rs
@@ -34,6 +34,7 @@ impl AsTreeNode for TraceInfo {
         parent.leaf_optional(self.caller_address.as_option());
         parent.leaf_optional(self.call_type.as_option());
         parent.leaf_optional(self.call_result.as_option());
+        parent.leaf_optional(self.gas.as_option());
         for nested_call in &self.nested_calls {
             parent.as_tree_node(nested_call);
         }
diff --git a/crates/debugging/src/tree/ui/display.rs b/crates/debugging/src/tree/ui/display.rs
@@ -1,5 +1,5 @@
 use crate::trace::types::{
-    CallerAddress, ContractAddress, ContractName, Selector, TestName, TransformedCallResult,
+    CallerAddress, ContractAddress, ContractName, Gas, Selector, TestName, TransformedCallResult,
     TransformedCalldata,
 };
 use blockifier::execution::entry_point::CallType;
@@ -84,6 +84,13 @@ impl NodeDisplay for TransformedCallResult {
     }
 }
 
+impl NodeDisplay for Gas {
+    const TAG: &'static str = "L2 gas";
+    fn string_pretty(&self) -> String {
+        self.0.to_string()
+    }
+}
+
 /// Helper function to get hex representation
 /// of a type that can be converted to a [`Felt`].
 fn string_hex(data: impl Into<Felt>) -> String {
diff --git a/crates/forge-runner/src/debugging/component.rs b/crates/forge-runner/src/debugging/component.rs
@@ -19,6 +19,8 @@ pub enum Component {
     CallType,
     /// The result of the call, transformed for display.
     CallResult,
+    /// The L2 gas used by the call.
+    Gas,
 }
 impl Component {
     /// Returns minimal [`TraceVerbosity`] for the component.
@@ -30,7 +32,8 @@ impl Component {
             Component::ContractAddress
             | Component::CallerAddress
             | Component::EntryPointType
-            | Component::CallType => TraceVerbosity::Detailed,
+            | Component::CallType
+            | Component::Gas => TraceVerbosity::Detailed,
         }
     }
 }
@@ -45,6 +48,7 @@ impl From<&Component> for debugging::Component {
             Component::CallerAddress => debugging::Component::CallerAddress,
             Component::CallType => debugging::Component::CallType,
             Component::CallResult => debugging::Component::CallResult,
+            Component::Gas => debugging::Component::Gas,
         }
     }
 }
diff --git a/crates/forge/tests/e2e/debugging.rs b/crates/forge/tests/e2e/debugging.rs
@@ -175,6 +175,7 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │  ├─ [caller address] [..]
         │  ├─ [call type] Call
         │  ├─ [call result] success: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}]
+        │  ├─ [L2 gas] [..]
         │  ├─ [selector] execute_calls
         │  │  ├─ [contract name] SimpleContract
         │  │  ├─ [entry point type] External
@@ -183,38 +184,43 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │  │  ├─ [caller address] [..]
         │  │  ├─ [call type] Call
         │  │  ├─ [call result] success: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}]
+        │  │  ├─ [L2 gas] [..]
         │  │  ├─ [selector] execute_calls
         │  │  │  ├─ [contract name] SimpleContract
         │  │  │  ├─ [entry point type] External
         │  │  │  ├─ [calldata] array![]
         │  │  │  ├─ [contract address] [..]
         │  │  │  ├─ [caller address] [..]
         │  │  │  ├─ [call type] Call
-        │  │  │  └─ [call result] success: array![]
+        │  │  │  ├─ [call result] success: array![]
+        │  │  │  └─ [L2 gas] [..]
         │  │  └─ [selector] execute_calls
         │  │     ├─ [contract name] SimpleContract
         │  │     ├─ [entry point type] External
         │  │     ├─ [calldata] array![]
         │  │     ├─ [contract address] [..]
         │  │     ├─ [caller address] [..]
         │  │     ├─ [call type] Call
-        │  │     └─ [call result] success: array![]
+        │  │     ├─ [call result] success: array![]
+        │  │     └─ [L2 gas] [..]
         │  └─ [selector] execute_calls
         │     ├─ [contract name] SimpleContract
         │     ├─ [entry point type] External
         │     ├─ [calldata] array![]
         │     ├─ [contract address] [..]
         │     ├─ [caller address] [..]
         │     ├─ [call type] Call
-        │     └─ [call result] success: array![]
+        │     ├─ [call result] success: array![]
+        │     └─ [L2 gas] [..]
         └─ [selector] fail
            ├─ [contract name] SimpleContract
            ├─ [entry point type] External
            ├─ [calldata] array![0x1, 0x2, 0x3, 0x4, 0x5]
            ├─ [contract address] [..]
            ├─ [caller address] [..]
            ├─ [call type] Call
-           └─ [call result] panic: (0x1, 0x2, 0x3, 0x4, 0x5)
+           ├─ [call result] panic: (0x1, 0x2, 0x3, 0x4, 0x5)
+           └─ [L2 gas] [..]
         "}
 }
 
@@ -229,6 +235,7 @@ fn detailed_debugging_trace_message_fork(test_name: &str, package_name: &str) ->
         │  ├─ [caller address] [..]
         │  ├─ [call type] Call
         │  ├─ [call result] success: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}]
+        │  ├─ [L2 gas] [..]
         │  ├─ [selector] execute_calls
         │  │  ├─ [contract name] forked contract
         │  │  ├─ [entry point type] External
@@ -237,38 +244,43 @@ fn detailed_debugging_trace_message_fork(test_name: &str, package_name: &str) ->
         │  │  ├─ [caller address] [..]
         │  │  ├─ [call type] Call
         │  │  ├─ [call result] success: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}]
+        │  │  ├─ [L2 gas] [..]
         │  │  ├─ [selector] execute_calls
         │  │  │  ├─ [contract name] forked contract
         │  │  │  ├─ [entry point type] External
         │  │  │  ├─ [calldata] array![]
         │  │  │  ├─ [contract address] [..]
         │  │  │  ├─ [caller address] [..]
         │  │  │  ├─ [call type] Call
-        │  │  │  └─ [call result] success: array![]
+        │  │  │  ├─ [call result] success: array![]
+        │  │  │  └─ [L2 gas] [..]
         │  │  └─ [selector] execute_calls
         │  │     ├─ [contract name] forked contract
         │  │     ├─ [entry point type] External
         │  │     ├─ [calldata] array![]
         │  │     ├─ [contract address] [..]
         │  │     ├─ [caller address] [..]
         │  │     ├─ [call type] Call
-        │  │     └─ [call result] success: array![]
+        │  │     ├─ [call result] success: array![]
+        │  │     └─ [L2 gas] [..]
         │  └─ [selector] execute_calls
         │     ├─ [contract name] forked contract
         │     ├─ [entry point type] External
         │     ├─ [calldata] array![]
         │     ├─ [contract address] [..]
         │     ├─ [caller address] [..]
         │     ├─ [call type] Call
-        │     └─ [call result] success: array![]
+        │     ├─ [call result] success: array![]
+        │     └─ [L2 gas] [..]
         └─ [selector] fail
            ├─ [contract name] forked contract
            ├─ [entry point type] External
            ├─ [calldata] array![0x1, 0x2, 0x3, 0x4, 0x5]
            ├─ [contract address] [..]
            ├─ [caller address] [..]
            ├─ [call type] Call
-           └─ [call result] panic: (0x1, 0x2, 0x3, 0x4, 0x5)
+           ├─ [call result] panic: (0x1, 0x2, 0x3, 0x4, 0x5)
+           └─ [L2 gas] [..]
         "}
 }
 
diff --git a/docs/src/snforge-advanced-features/debugging.md b/docs/src/snforge-advanced-features/debugging.md
@@ -29,6 +29,7 @@ The `--trace-components` flag allows you to specify which components of the trac
 - `caller-address`: the address of the caller contract
 - `call-type`: the type of the call (e.g., `Call`, `Delegate`, etc.)
 - `call-result`: the result of the call, transformed for display
+- `gas`: estimated L2 gas consumed by the call 
 
 Example usage:
 
@@ -122,17 +123,18 @@ $ snforge test --trace-verbosity standard
 
 Here's what each tag in the trace represents:
 
-| Tag                  | Description                                                                                                                                          |
-|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `[test name]`        | The path to the test being executed, using the Cairo module structure. Indicates which test case produced this trace.                                |
-| `[selector]`         | The name of the contract function being called. The structure shows nested calls when one function triggers another.                                 |
-| `[contract name]`    | The name of the contract where the selector (function) was invoked. Helps trace calls across contracts.                                              |
-| `[entry point type]` | (In detailed view) Type of entry point used: External, Constructor, L1Handler. Useful to differentiate the context in which the call is executed.    |
-| `[calldata]`         | (In standard view and above) The arguments passed into the function call.                                                                            |
-| `[storage address]`  | (In detailed view) The storage address of the specific contract instance called. Helps identify which deployment is used if you're testing multiple. |
-| `[caller address]`   | (In detailed view) The address of the account or contract that made this call. Important to identify who triggered the function.                     |
-| `[call type]`        | (In detailed view) Call, Delegate. Describes how the function is being invoked.                                                                      |
-| `[call result]`      | (In standard view and above) The return value of the call, success or panic.                                                                         |
+| Tag                  | Description                                                                                                                                                                      |
+|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `[test name]`        | The path to the test being executed, using the Cairo module structure. Indicates which test case produced this trace.                                                            |
+| `[selector]`         | The name of the contract function being called. The structure shows nested calls when one function triggers another.                                                             |
+| `[contract name]`    | The name of the contract where the selector (function) was invoked. Helps trace calls across contracts.                                                                          |
+| `[entry point type]` | (In detailed view) Type of entry point used: External, Constructor, L1Handler. Useful to differentiate the context in which the call is executed.                                |
+| `[calldata]`         | (In standard view and above) The arguments passed into the function call.                                                                                                        |
+| `[storage address]`  | (In detailed view) The storage address of the specific contract instance called. Helps identify which deployment is used if you're testing multiple.                             |
+| `[caller address]`   | (In detailed view) The address of the account or contract that made this call. Important to identify who triggered the function.                                                 |
+| `[call type]`        | (In detailed view) Call, Delegate. Describes how the function is being invoked.                                                                                                  |
+| `[call result]`      | (In standard view and above) The return value of the call, success or panic.                                                                                                     |
+| `[gas]`              | (In detailed view) L2 gas needed to execute the call. The calculation ignores state changes, calldata and signature lengths, L1 handler payload length and Starknet OS overhead. |
 
 
 

Original file line number	Diff line number	Diff line change
`@@ -34,6 +34,7 @@ impl AsTreeNode for TraceInfo {`
`34`	`34`	`parent.leaf_optional(self.caller_address.as_option());`
`35`	`35`	`parent.leaf_optional(self.call_type.as_option());`
`36`	`36`	`parent.leaf_optional(self.call_result.as_option());`
	`37`	`+ parent.leaf_optional(self.gas.as_option());`
`37`	`38`	`for nested_call in &self.nested_calls {`
`38`	`39`	`parent.as_tree_node(nested_call);`
`39`	`40`	`}`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,8 @@ pub enum Component {`
`19`	`19`	`CallType,`
`20`	`20`	`/// The result of the call, transformed for display.`
`21`	`21`	`CallResult,`
	`22`	`+ /// The L2 gas used by the call.`
	`23`	`+ Gas,`
`22`	`24`	`}`
`23`	`25`	`impl Component {`
`24`	`26`	/// Returns minimal [`TraceVerbosity`] for the component.
`@@ -30,7 +32,8 @@ impl Component {`
`30`	`32`	`Component::ContractAddress`
`31`	`33`	`\| Component::CallerAddress`
`32`	`34`	`\| Component::EntryPointType`
`33`		`- \| Component::CallType => TraceVerbosity::Detailed,`
	`35`	`+ \| Component::CallType`
	`36`	`+ \| Component::Gas => TraceVerbosity::Detailed,`
`34`	`37`	`}`
`35`	`38`	`}`
`36`	`39`	`}`
`@@ -45,6 +48,7 @@ impl From<&Component> for debugging::Component {`
`45`	`48`	`Component::CallerAddress => debugging::Component::CallerAddress,`
`46`	`49`	`Component::CallType => debugging::Component::CallType,`
`47`	`50`	`Component::CallResult => debugging::Component::CallResult,`
	`51`	`+ Component::Gas => debugging::Component::Gas,`
`48`	`52`	`}`
`49`	`53`	`}`
`50`	`54`	`}`