feat: gas reports and snapshots (#12724)

## Gas Reports

You can run `./bootstrap.sh gas_report` to generate a detailed gas
report for the current state and update the gas_report.md file.

When running CI or tests with `./bootstrap.sh test`, the script will
automatically check if gas usage has changed by running `./bootstrap.sh
gas_report check`. If gas usage has changed, the test will fail and show
a diff of the changes.

If the changes in gas usage are expected and desired:

1. Review the diff shown in the output
2. Run `./bootstrap.sh gas_report` to update the gas report file
3. Commit the updated gas_report.md file

NOTE: Our gas reporting excludes certain tests due to Forge limitations:

- FeeRollupTest and MinimalFeeModelTest test suites are excluded
- testInvalidBlobHash and testInvalidBlobProof test cases are excluded

This is related to [this Foundry
issue](foundry-rs/foundry#10074).

This means that we don't report gas for blob validation (currently 50k
gas per blob, and we use 3 blobs per propose in production).

If you want to run gas reports directly with `forge`, you must use the
environment variable `FORGE_GAS_REPORT=true` instead of the
`--gas-report` flag. The `./bootstrap.sh gas_report` command does this
for you automatically.

Author: just-mitch

l1-contracts/.gitignore

@@ -24,3 +24,6 @@ yarn.lock
 
 # 'deploy_contracts' script output
 serve/
+
+gas_report.new.*
+gas_report.diff

l1-contracts/README.md

@@ -12,7 +12,8 @@ Alternatively you can use docker instead, it will handle installations and run t
 
 The `src` folder contain contracts that is to be used by the local developer testnet. It is grouped into 3 categories:
 
-- `core` contains the required contracts, the bare minimum
+- `core` contains the required contracts, the bare minimum.
+- `governance` contains the contracts for the governance system.
 - `mock` contains stubs, for now an always true verifier.
 - `periphery` stuff that is nice to have, convenience contracts and functions belong in here.
 
@@ -31,6 +32,29 @@ We use `forge fmt` to format. But follow a few general guidelines beyond the sta
   - Do `function transfer(address _to, uint256 _amount);`
 - use `_` prefix for `internal` and `private` functions.
 
+## Gas Reports
+
+You can run `./bootstrap.sh gas_report` to generate a detailed gas report for the current state and update the gas_report.md file.
+
+When running CI or tests with `./bootstrap.sh test`, the script will automatically check if gas usage has changed by running `./bootstrap.sh gas_report check`. If gas usage has changed, the test will fail and show a diff of the changes.
+
+If the changes in gas usage are expected and desired:
+
+1. Review the diff shown in the output
+2. Run `./bootstrap.sh gas_report` to update the gas report file
+3. Commit the updated gas_report.md file
+
+NOTE: Our gas reporting excludes certain tests due to Forge limitations:
+
+- FeeRollupTest and MinimalFeeModelTest test suites are excluded
+- testInvalidBlobHash and testInvalidBlobProof test cases are excluded
+
+This is related to [this Foundry issue](https://github.com/foundry-rs/foundry/issues/10074).
+
+This means that we don't report gas for blob validation (currently 50k gas per blob, and we use 3 blobs per propose in production).
+
+If you want to run gas reports directly with `forge`, you must use the environment variable `FORGE_GAS_REPORT=true` instead of the `--gas-report` flag. The `./bootstrap.sh gas_report` command does this for you automatically.
+
 ## Contracts:
 
 The contracts are in a very early stage, and don't worry about gas costs right now. Instead they prioritize development velocity.

l1-contracts/bootstrap.sh

@@ -53,7 +53,7 @@ function build {
 function test_cmds {
   echo "$hash cd l1-contracts && solhint --config ./.solhint.json \"src/**/*.sol\""
   echo "$hash cd l1-contracts && forge fmt --check"
-  echo "$hash cd l1-contracts && forge test --no-match-contract UniswapPortalTest"
+  echo "$hash cd l1-contracts && forge test && ./bootstrap.sh gas_report"
 }
 
 function test {
@@ -100,6 +100,29 @@ function inspect {
     done
 }
 
+function gas_report {
+  check=${1:-"no"}
+  echo_header "l1-contracts gas report"
+  forge --version
+
+  FORGE_GAS_REPORT=true forge test \
+    --no-match-contract "(FeeRollupTest)|(MinimalFeeModelTest)|(UniswapPortalTest)" \
+    --no-match-test "(testInvalidBlobHash)|(testInvalidBlobProof)" \
+    --fuzz-seed 42 \
+    --isolate \
+    > gas_report.new.tmp
+  grep "^|" gas_report.new.tmp > gas_report.new.md
+  rm gas_report.new.tmp
+  diff gas_report.new.md gas_report.md > gas_report.diff || true
+
+  if [ -s gas_report.diff -a "$check" = "check" ]; then
+    cat gas_report.diff
+    echo "Gas report has changed. Please check the diffs above, then run './bootstrap.sh gas_report' to update the gas report."
+    exit 1
+  fi
+  mv gas_report.new.md gas_report.md
+}
+
 # First argument is a branch name (e.g. master, or the latest version e.g. 1.2.3) to push to the head of.
 # Second argument is the tag name (e.g. v1.2.3, or commit-<hash>).
 # Third argument is the semver for package.json (e.g. 1.2.3 or 1.2.3-commit.<hash>)
@@ -195,6 +218,10 @@ case "$cmd" in
   "inspect")
     inspect
     ;;
+  "gas_report")
+    shift
+    gas_report "$@"
+    ;;
   test_cmds|release)
     $cmd
     ;;

l1-contracts/foundry.toml

@@ -4,6 +4,9 @@ out = 'out'
 libs = ['lib']
 solc = "0.8.27"
 evm_version = 'cancun'
+# Helper to get all the contract names in the src/governance and src/core directories
+# find ./src/governance ./src/core ./src/periphery/Forwarder -type f -name "*.sol" -exec grep -h "^contract [A-Za-z]" {} \; | sed -E 's/contract ([A-Za-z0-9_]+).*/"\1"/' | tr "\n" ", "
+gas_reports = ["Governance","Registry","RewardDistributor","GovernanceProposer","CoinIssuer","Rollup","Inbox","Outbox","FeeJuicePortal","RollupCore","SlashingProposer","Slasher","Forwarder"]
 
 remappings = [
   "@oz/=lib/openzeppelin-contracts/contracts/",
@@ -29,4 +32,5 @@ tab_width = 2
 variable_override_spacing=false
 
 [rpc_endpoints]
-mainnet_fork="https://mainnet.infura.io/v3/9928b52099854248b3a096be07a6b23c"
+mainnet_fork="https://mainnet.infura.io/v3/9928b52099854248b3a096be07a6b23c"
+