🔥
🛠️
Foundry Gas Diff Reporter
- Easily compare gas reports generated by Foundry automatically on each of your Pull Requests!
How it works
Everytime somebody opens a Pull Request, the action expects Foundry forge to run a test suite, generating a gas report to a temporary file (named gasreport.ansi by default).
Once generated, the action will fetch the comparative gas report stored as an artifact from previous runs; parse & compare them, storing the results in the action's outputs as shell and as markdown.
You can then do whatever you want with the results!
Our recommandation: Automatically submit a sticky comment displaying the gas diff!
Live Example
Changes to gas costs
Generated at commit: d62d23148ca73df77cd4378ee1b3c17f1f303dbf, compared to commit: d62d23148ca73df77cd4378ee1b3c17f1f303dbf
🧾
Summary
| Contract | Method | Avg (+/-) | % |
|---|---|---|---|
| PositionsManager | borrowLogic supplyLogic |
+702 +849 |
+0.13% +0.23% |
| Morpho | supply | +809 |
+0.22% |
Full diff report
👇
| Contract | Deployment Cost (+/-) | Method | Min (+/-) | % | Avg (+/-) | % | Median (+/-) | % | Max (+/-) | % | # Calls (+/-) |
|---|---|---|---|---|---|---|---|---|---|---|---|
| PositionsManager | 4,546,050 (+14,617) | borrowLogic supplyLogic |
148,437 (0) 737 (0) |
0.00% 0.00% |
542,977 (+702) 365,894 (+849) |
+0.13% +0.23% |
438,816 (0) 383,960 (+995) |
0.00% +0.26% |
1,090,968 (0) 2,121,294 (+304) |
0.00% +0.01% |
292 (0) 500 (0) |
| Morpho | 3,150,242 (0) | supply | 3,997 (0) | 0.00% | 371,586 (+809) | +0.22% | 395,247 (+995) | +0.25% | 2,125,764 (+304) | +0.01% | 502 (0) |
Getting started
Automatically generate a gas report diff on every PR
Add a workflow (.github/workflows/foundry-gas-diff.yml):
name: Report gas diff
on:
push:
branches:
- main
pull_request:
# Optionally configure to run only for specific files. For example:
# paths:
# - src/**
# - test/**
# - foundry.toml
# - remappings.txt
# - .github/workflows/foundry-gas-diff.yml
jobs:
compare_gas_reports:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
submodules: recursive
- name: Install Foundry
uses: onbjerg/foundry-toolchain@v1
with:
version: nightly
# Add any step generating a gas report to a temporary file named gasreport.ansi
# For example:
- name: Run tests
run: forge test --gas-report | tee gasreport.ansi
env:
# make fuzzing semi-deterministic to avoid noisy gas cost estimation
# due to non-deterministic fuzzing, but keep it not always deterministic
FOUNDRY_FUZZ_SEED: 0x${{ github.event.pull_request.base.sha || github.sha }}
- name: Compare gas reports
uses: Rubilmax/[email protected]
with:
sortCriteria: avg,max # optionnally sort diff rows by criteria
sortOrders: desc,asc # and directions
ignore: test/**/* # optionally filter out gas reports from specific paths
id: gas_diff
- name: Add gas diff to sticky comment
if: github.event_name == 'pull_request' || github.event_name == 'pull_request_target'
uses: marocchino/sticky-pull-request-comment@v2
with:
# delete the comment in case changes no longer impact gas costs
delete: ${{ !steps.gas_diff.outputs.markdown }}
message: ${{ steps.gas_diff.outputs.markdown }}
ℹ️ An error will appear at first run!
🔴 Error: No workflow run found with an artifact named "main.gasreport.ansi"
As the action is expecting a comparative file stored on the base branch and cannot find it (because the action never ran on the target branch and thus has never uploaded any gas report)
Options
report {string}
This should correspond to the path of a file where the output of forge's gas report has been logged. Only necessary when generating multiple gas reports on the same repository.
Defaults to: gasreport.ansi
base {string}
The gas diff reference branch name, used to fetch the previous gas report to compare the freshly generated gas report to.
Defaults to: ${{ github.base_ref || github.ref_name }}
head {string}
The gas diff target branch name, used to upload the freshly generated gas report.
Defaults to: ${{ github.head_ref || github.ref_name }}
token {string}
The github token allowing the action to upload and download gas reports generated by foundry. You should not need to customize this, as the action already has access to the default Github Action token.
Defaults to: ${{ github.token }}
header {string}
The top section displayed in the markdown output. Can be used to identify multiple gas diffs in the same PR or add metadata/information to the markdown output.
Defaults to:
# Changes to gas cost
sortCriteria {string[]}
A list of criteria to sort diff rows by in the report table (can be name | min | avg | median | max | calls), separated by a comma. Must have the same length as sortOrders.
Defaults to: name
sortOrders {string[]}
A list of directions to sort diff rows by in the report table (can be asc | desc), for each sort criterion, separated by a comma. Must have the same length as sortCriteria.
Defaults to: asc
ignore {string[]}
The list of paths from which to ignore gas reports, separated by a comma. This allows to clean out gas diffs from dependency contracts impacted by a change (e.g. Proxies, ERC20, ...).
No default assigned: optional opt-in (Please note that node dependencies are always discarded from gas reports)
match {string[]}
The list of paths of which only to keep gas reports, separated by a comma. This allows to only display gas diff of specific contracts.
No default assigned: optional opt-in
⚠️
Known limitations
Library gas reports
Forge does not generate library gas reports. You need to wrap their usage in a contract calling the library to be able to compare gas costs of calling the library.
Average gas cost estimation
Average & median gas costs for each function is estimated based on the test suite, which means they are easily impacted by small changes in the tests. We recommend using a separate, specific test suite, rarily updated, designed to perform accurate gas estimations.
Fuzzing impacts gas costs
Fuzzing can lead differences in gas costs estimated each time a test suite is ran. We thus recommend setting a deterministic fuzzing seed via the--fuzz-seedargument.
This repository is maintained independently from Foundry and may not work as expected with all versions of forge.
240 Dec 31, 2022
77 Nov 3, 2022
4 Oct 13, 2022
4 Mar 25, 2022
16 Jan 3, 2023
11 Sep 7, 2022
6 Mar 2, 2022
293 Jan 3, 2023
5 Jul 31, 2022
10 Nov 18, 2022
24 Dec 22, 2022
44 Dec 14, 2022
10 Sep 6, 2022
4 Mar 23, 2022
72 Dec 26, 2022
97 Dec 12, 2022
18 Dec 8, 2022
25 Dec 22, 2022
24 Nov 7, 2022