{"id":14985962,"url":"https://github.com/rubilmax/foundry-gas-diff","last_synced_at":"2025-05-16T19:04:30.833Z","repository":{"id":45459797,"uuid":"513638576","full_name":"Rubilmax/foundry-gas-diff","owner":"Rubilmax","description":"🛠️ Easily track \u0026 compare gas costs estimated by Foundry on each of your Pull Requests!","archived":false,"fork":false,"pushed_at":"2025-01-21T23:55:51.000Z","size":5739,"stargazers_count":206,"open_issues_count":2,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T19:15:41.395Z","etag":null,"topics":["action","actions","evm","forge","foundry","fuzzing","gas","github","optimization","performance","report","solidity","testing","tracking"],"latest_commit_sha":null,"homepage":"https://github.com/Rubilmax/foundry-gas-diff/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rubilmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-13T18:58:28.000Z","updated_at":"2025-01-20T10:46:13.000Z","dependencies_parsed_at":"2023-02-19T16:00:28.989Z","dependency_job_id":"b3b861b6-f11e-4e14-b775-2b70996a9397","html_url":"https://github.com/Rubilmax/foundry-gas-diff","commit_stats":{"total_commits":236,"total_committers":3,"mean_commits":78.66666666666667,"dds":0.4703389830508474,"last_synced_commit":"0e44213d721e060203d6fa30c288288a5e32888a"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Ffoundry-gas-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Ffoundry-gas-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Ffoundry-gas-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rubilmax%2Ffoundry-gas-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rubilmax","download_url":"https://codeload.github.com/Rubilmax/foundry-gas-diff/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248607993,"owners_count":21132644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["action","actions","evm","forge","foundry","fuzzing","gas","github","optimization","performance","report","solidity","testing","tracking"],"created_at":"2024-09-24T14:12:02.829Z","updated_at":"2025-04-12T17:41:43.809Z","avatar_url":"https://github.com/Rubilmax.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n\u003cimg width=\"800\" alt=\"image\" src=\"https://user-images.githubusercontent.com/3147812/208614591-bcbeafce-e99d-43ae-a427-96b63eae1fb9.png\"\u003e\n\u003c/p\u003e\n\n# 🔥🛠️ Foundry Gas Diff Reporter\n\n- Easily compare gas reports generated by Foundry automatically on each of your Pull Requests!\n- Check out the [Live example](https://github.com/morpho-dao/morpho-tokenized-vaults/pull/228#issuecomment-1352919862) to see how it looks!\n\n## Getting started\n\n### Automatically generate a gas report diff on every PR\n\nAdd a workflow (`.github/workflows/foundry-gas-diff.yml`):\n\n```yaml\nname: Report gas diff\n\non:\n  push:\n    branches:\n      - main\n  pull_request:\n    # Optionally configure to run only for changes in specific files. For example:\n    # paths:\n    # - src/**\n    # - test/**\n    # - foundry.toml\n    # - remappings.txt\n    # - .github/workflows/foundry-gas-diff.yml\n\njobs:\n  compare_gas_reports:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          submodules: recursive\n\n      - name: Install Foundry\n        uses: onbjerg/foundry-toolchain@v1\n        with:\n          version: nightly\n\n      # Add any step generating a gas report to a temporary file named gasreport.ansi. For example:\n      - name: Run tests\n        run: forge test --gas-report \u003e gasreport.ansi # \u003c- this file name should be unique in your repository!\n        env:\n          # make fuzzing semi-deterministic to avoid noisy gas cost estimation\n          # due to non-deterministic fuzzing (but still use pseudo-random fuzzing seeds)\n          FOUNDRY_FUZZ_SEED: 0x${{ github.event.pull_request.base.sha || github.sha }}\n\n      - name: Compare gas reports\n        uses: Rubilmax/foundry-gas-diff@v3\n        with:\n          summaryQuantile: 0.9 # only display the 10% most significant gas diffs in the summary (defaults to 20%)\n          sortCriteria: avg,max # sort diff rows by criteria\n          sortOrders: desc,asc # and directions\n          ignore: test-foundry/**/* # filter out gas reports from specific paths (test/ is included by default)\n        id: gas_diff\n\n      - name: Add gas diff to sticky comment\n        if: github.event_name == 'pull_request' || github.event_name == 'pull_request_target'\n        uses: marocchino/sticky-pull-request-comment@v2\n        with:\n          # delete the comment in case changes no longer impact gas costs\n          delete: ${{ !steps.gas_diff.outputs.markdown }}\n          message: ${{ steps.gas_diff.outputs.markdown }}\n```\n\n\u003e :information_source: **An error will appear at first run!**\u003cbr/\u003e\n\u003e 🔴 \u003cem\u003e**Error:** No workflow run found with an artifact named \"main.gasreport.ansi\"\u003c/em\u003e\u003cbr/\u003e\n\u003e 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)\n\n---\n\n## How it works\n\nEverytime somebody opens a Pull Request, the action expects [Foundry](https://github.com/foundry-rs/foundry) `forge` to run a test suite, generating a gas report to a temporary file (named `gasreport.ansi` by default).\n\nOnce generated, the action will fetch the comparative gas report stored as an artifact from previous runs; parse \u0026 compare them, storing the results in the action's outputs as shell and as markdown.\n\nYou can then do whatever you want with the results!\n\n\u003e **Our recommandation:** Automatically submit a sticky comment displaying the gas diff!\n\n---\n\n## Options\n\n### `report` _{string}_\n\nThis should correspond to the path of a file where the output of forge's gas report has been logged.\nOnly necessary when generating multiple gas reports on the same repository.\n\n⚠️ Make sure this file uniquely identifies a gas report, to avoid messing up with a gas report of another workflow on the same repository!\n\n_Defaults to: `gasreport.ansi`_\n\n### `base` _{string}_\n\nThe gas diff reference branch name, used to fetch the previous gas report to compare the freshly generated gas report to.\n\n_Defaults to: `${{ github.base_ref || github.ref_name }}`_\n\n### `head` _{string}_\n\nThe gas diff target branch name, used to upload the freshly generated gas report.\n\n_Defaults to: `${{ github.head_ref || github.ref_name }}`_\n\n### `token` _{string}_\n\nThe 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.\n\n_Defaults to: `${{ github.token }}`_\n\n### `header` _{string}_\n\nThe 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.\n\n_Defaults to:_\n\n```markdown\n# Changes to gas cost\n```\n\n### `summaryQuantile` _{number}_\n\nThe quantile threshold to filter avg gas cost diffs to display in the summary top section.\n\n_Defaults to: `0.8`_\n\n### `sortCriteria` _{string[]}_\n\nA list of criteria to sort diff rows by in the report table (can be `name | min | avg | median | max | calls`), separated by a comma.\nMust have the same length as sortOrders.\n\n_Defaults to: name_\n\n### `sortOrders` _{string[]}_\n\nA list of directions to sort diff rows by in the report table (can be `asc | desc`), for each sort criterion, separated by a comma.\nMust have the same length as sortCriteria.\n\n_Defaults to: asc_\n\n### `ignore` _{string[]}_\n\nThe list of contract paths from which to ignore gas reports, separated by a comma.\nThis allows to clean out gas diffs from dependency contracts impacted by a change (e.g. Proxies, ERC20, ...).\n\n_No default assigned: optional opt-in (Please note that node dependencies are always discarded from gas reports)_\n\n### `match` _{string[]}_\n\nThe list of contract paths of which only to keep gas reports, separated by a comma.\nThis allows to only display gas diff of specific contracts.\n\n_No default assigned: optional opt-in_\n\n## ⚠️ Known limitations\n\n\u003e **Library gas reports**\u003cbr/\u003e\n\u003e 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.\n\n\u003e **Average gas cost estimation**\u003cbr/\u003e\n\u003e Average \u0026 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.\n\n\u003e **Fuzzing impacts gas costs**\u003cbr/\u003e\n\u003e 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-seed` argument.\n\nThis repository is maintained independently from [Foundry](https://github.com/foundry-rs/foundry) and may not work as expected with all versions of `forge`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubilmax%2Ffoundry-gas-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubilmax%2Ffoundry-gas-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubilmax%2Ffoundry-gas-diff/lists"}