Skip to content

Commit dd05ff0

Browse files
ddoktorskiddoktorski
committed
Add gas report docs (#3879)
Closes #3660
1 parent 8464eec commit dd05ff0

File tree

6 files changed

+104
-60
lines changed

6 files changed

+104
-60
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Forge
11+
12+
#### Added
13+
14+
- `--gas-report` flag to display a table of L2 gas breakdown for each contract and selector
15+
1016
## [0.52.0] - 2025-11-05
1117

1218
### Forge

‎crates/forge/tests/e2e/snapshots/[email protected]‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,24 @@ source: crates/forge/tests/e2e/gas_report.rs
33
expression: stdout
44
---
55
[PASS] forking::tests::test_track_resources (l1_gas: ~0, l1_data_gas: ~320, l2_gas: ~513850)
6-
╭-------------------------+-------+-------+-------+---------+---------╮
7-
| forked contract | | | | | |
8-
| (class hash: 0x06…1550) | | | | | |
9-
+=====================================================================+
10-
| Function Name | Min | Max | Avg | Std Dev | # Calls |
11-
|-------------------------+-------+-------+-------+---------+---------|
12-
| get_balance | 40000 | 40000 | 40000 | 0 | 1 |
13-
|-------------------------+-------+-------+-------+---------+---------|
14-
| increase_balance | 40000 | 40000 | 40000 | 0 | 1 |
15-
╰-------------------------+-------+-------+-------+---------+---------╯
6+
╭---------------------------+-------+-------+-------+---------+---------╮
7+
| forked contract | | | | | |
8+
| (class hash: 0x06a7…1550) | | | | | |
9+
+=======================================================================+
10+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
11+
|---------------------------+-------+-------+-------+---------+---------|
12+
| get_balance | 40000 | 40000 | 40000 | 0 | 1 |
13+
|---------------------------+-------+-------+-------+---------+---------|
14+
| increase_balance | 40000 | 40000 | 40000 | 0 | 1 |
15+
╰---------------------------+-------+-------+-------+---------+---------╯
1616

17-
╭-------------------------+-------+-------+-------+---------+---------╮
18-
| forked contract | | | | | |
19-
| (class hash: 0x07…af4b) | | | | | |
20-
+=====================================================================+
21-
| Function Name | Min | Max | Avg | Std Dev | # Calls |
22-
|-------------------------+-------+-------+-------+---------+---------|
23-
| get_balance | 13840 | 13840 | 13840 | 0 | 1 |
24-
|-------------------------+-------+-------+-------+---------+---------|
25-
| increase_balance | 25840 | 25840 | 25840 | 0 | 1 |
26-
╰-------------------------+-------+-------+-------+---------+---------╯
17+
╭---------------------------+-------+-------+-------+---------+---------╮
18+
| forked contract | | | | | |
19+
| (class hash: 0x07aa…af4b) | | | | | |
20+
+=======================================================================+
21+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
22+
|---------------------------+-------+-------+-------+---------+---------|
23+
| get_balance | 13840 | 13840 | 13840 | 0 | 1 |
24+
|---------------------------+-------+-------+-------+---------+---------|
25+
| increase_balance | 25840 | 25840 | 25840 | 0 | 1 |
26+
╰---------------------------+-------+-------+-------+---------+---------╯

‎crates/forge/tests/e2e/snapshots/[email protected]‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,24 @@ source: crates/forge/tests/e2e/gas_report.rs
33
expression: stdout
44
---
55
[PASS] forking::tests::test_track_resources (l1_gas: ~0, l1_data_gas: ~320, l2_gas: ~509780)
6-
╭-------------------------+-------+-------+-------+---------+---------╮
7-
| forked contract | | | | | |
8-
| (class hash: 0x06…1550) | | | | | |
9-
+=====================================================================+
10-
| Function Name | Min | Max | Avg | Std Dev | # Calls |
11-
|-------------------------+-------+-------+-------+---------+---------|
12-
| get_balance | 40000 | 40000 | 40000 | 0 | 1 |
13-
|-------------------------+-------+-------+-------+---------+---------|
14-
| increase_balance | 40000 | 40000 | 40000 | 0 | 1 |
15-
╰-------------------------+-------+-------+-------+---------+---------╯
6+
╭---------------------------+-------+-------+-------+---------+---------╮
7+
| forked contract | | | | | |
8+
| (class hash: 0x06a7…1550) | | | | | |
9+
+=======================================================================+
10+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
11+
|---------------------------+-------+-------+-------+---------+---------|
12+
| get_balance | 40000 | 40000 | 40000 | 0 | 1 |
13+
|---------------------------+-------+-------+-------+---------+---------|
14+
| increase_balance | 40000 | 40000 | 40000 | 0 | 1 |
15+
╰---------------------------+-------+-------+-------+---------+---------╯
1616

17-
╭-------------------------+-------+-------+-------+---------+---------╮
18-
| forked contract | | | | | |
19-
| (class hash: 0x07…af4b) | | | | | |
20-
+=====================================================================+
21-
| Function Name | Min | Max | Avg | Std Dev | # Calls |
22-
|-------------------------+-------+-------+-------+---------+---------|
23-
| get_balance | 13840 | 13840 | 13840 | 0 | 1 |
24-
|-------------------------+-------+-------+-------+---------+---------|
25-
| increase_balance | 25840 | 25840 | 25840 | 0 | 1 |
26-
╰-------------------------+-------+-------+-------+---------+---------╯
17+
╭---------------------------+-------+-------+-------+---------+---------╮
18+
| forked contract | | | | | |
19+
| (class hash: 0x07aa…af4b) | | | | | |
20+
+=======================================================================+
21+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
22+
|---------------------------+-------+-------+-------+---------+---------|
23+
| get_balance | 13840 | 13840 | 13840 | 0 | 1 |
24+
|---------------------------+-------+-------+-------+---------+---------|
25+
| increase_balance | 25840 | 25840 | 25840 | 0 | 1 |
26+
╰---------------------------+-------+-------+-------+---------+---------╯

‎crates/forge/tests/e2e/snapshots/[email protected]‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,24 @@ source: crates/forge/tests/e2e/gas_report.rs
33
expression: stdout
44
---
55
[PASS] forking::tests::test_track_resources (l1_gas: ~0, l1_data_gas: ~320, l2_gas: ~509780)
6-
╭-------------------------+-------+-------+-------+---------+---------╮
7-
| forked contract | | | | | |
8-
| (class hash: 0x06…1550) | | | | | |
9-
+=====================================================================+
10-
| Function Name | Min | Max | Avg | Std Dev | # Calls |
11-
|-------------------------+-------+-------+-------+---------+---------|
12-
| get_balance | 40000 | 40000 | 40000 | 0 | 1 |
13-
|-------------------------+-------+-------+-------+---------+---------|
14-
| increase_balance | 40000 | 40000 | 40000 | 0 | 1 |
15-
╰-------------------------+-------+-------+-------+---------+---------╯
6+
╭---------------------------+-------+-------+-------+---------+---------╮
7+
| forked contract | | | | | |
8+
| (class hash: 0x06a7…1550) | | | | | |
9+
+=======================================================================+
10+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
11+
|---------------------------+-------+-------+-------+---------+---------|
12+
| get_balance | 40000 | 40000 | 40000 | 0 | 1 |
13+
|---------------------------+-------+-------+-------+---------+---------|
14+
| increase_balance | 40000 | 40000 | 40000 | 0 | 1 |
15+
╰---------------------------+-------+-------+-------+---------+---------╯
1616

17-
╭-------------------------+-------+-------+-------+---------+---------╮
18-
| forked contract | | | | | |
19-
| (class hash: 0x07…af4b) | | | | | |
20-
+=====================================================================+
21-
| Function Name | Min | Max | Avg | Std Dev | # Calls |
22-
|-------------------------+-------+-------+-------+---------+---------|
23-
| get_balance | 13840 | 13840 | 13840 | 0 | 1 |
24-
|-------------------------+-------+-------+-------+---------+---------|
25-
| increase_balance | 25840 | 25840 | 25840 | 0 | 1 |
26-
╰-------------------------+-------+-------+-------+---------+---------╯
17+
╭---------------------------+-------+-------+-------+---------+---------╮
18+
| forked contract | | | | | |
19+
| (class hash: 0x07aa…af4b) | | | | | |
20+
+=======================================================================+
21+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
22+
|---------------------------+-------+-------+-------+---------+---------|
23+
| get_balance | 13840 | 13840 | 13840 | 0 | 1 |
24+
|---------------------------+-------+-------+-------+---------+---------|
25+
| increase_balance | 25840 | 25840 | 25840 | 0 | 1 |
26+
╰---------------------------+-------+-------+-------+---------+---------╯

‎docs/src/appendix/snforge/test.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,9 @@ Set tracked resource for test execution. Impacts overall test gas cost. Valid va
130130
- `cairo-steps`: track cairo steps, uses vm `ExecutionResources` (steps, builtins, memory holes) to describe resources consumed by the test.
131131
To learn more about fee calculation formula (and the impact of tracking sierra gas on it) please consult [starknet docs](https://docs.starknet.io/learn/protocol/fees#overall-fee)
132132

133+
## `--gas-report`
134+
Display a table of L2 gas breakdown for each contract and selector.
135+
133136
## `-P`, `--profile` `<PROFILE>`
134137
Specify the profile to use by name.
135138

‎docs/src/testing/gas-and-resource-estimation.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,41 @@ When the test passes with no errors, estimated gas is displayed this way:
1717
This gas calculation is based on the collected Sierra gas or VM resources (that you can [display additionally on demand](#usage)),
1818
storage updates, events and l1 <> l2 messages.
1919

20+
#### Gas Report
21+
22+
For individual tests, more detailed L2 gas usage can be displayed by passing the [`--gas-report`](../appendix/snforge/test.md#--gas-report) flag.
23+
This will generate a table that shows gas statistics for each contract and function.
24+
25+
<!-- { "ignored": true } -->
26+
```shell
27+
$ snforge test --gas-report
28+
```
29+
30+
<details>
31+
<summary>Output:</summary>
32+
33+
```shell
34+
Collected 1 test(s) from hello_starknet package
35+
Running 1 test(s) from tests/
36+
[PASS] hello_starknet_integrationtest::test_contract::test_increase_balance (l1_gas: ~0, l1_data_gas: ~192, l2_gas: ~998280)
37+
╭------------------------+-------+-------+-------+---------+---------╮
38+
| HelloStarknet Contract | | | | | |
39+
+====================================================================+
40+
| Function Name | Min | Max | Avg | Std Dev | # Calls |
41+
|------------------------+-------+-------+-------+---------+---------|
42+
| get_balance | 13340 | 13340 | 13340 | 0 | 4 |
43+
|------------------------+-------+-------+-------+---------+---------|
44+
| increase_balance | 25540 | 61240 | 37440 | 16829 | 3 |
45+
╰------------------------+-------+-------+-------+---------+---------╯
46+
```
47+
48+
</details>
49+
<br>
50+
51+
> 📝 **Note**
52+
>
53+
> Gas report data calculation ignores state changes, the cost of declared classes, Starknet OS overhead, L1 handler payload length and calldata payload length.
54+
2055
### Fuzzed Tests
2156

2257
While using the fuzzing feature additional gas statistics will be displayed:

0 commit comments

Comments
 (0)