[Testing]: Integrate `forge snapshot` for Automated Gas Tracking

[adamgall]

Problem Statement

Currently, we're removing explicit gas tests from our codebase because they're brittle and require constant maintenance. However, we still need visibility into gas usage changes to catch performance regressions and track optimization improvements.

Proposed Solution

Integrate forge snapshot into our CI/CD workflow to automatically track and report gas usage changes on every pull request.

Implementation Goals

1. Automatic Gas Tracking: Run forge snapshot on every PR to capture current gas usage
2. Comparison Reports: Compare gas usage against the base branch
3. PR Comments: Post detailed gas comparison as a comment on each PR
4. Visual Feedback: Show gas increases/decreases with clear indicators (🔴 ↑ / 🟢 ↓)
5. Non-blocking: Gas changes should be informative but not block PR merging

Technical Requirements

Core Features

• GitHub Actions workflow that runs on PR events
• Generate gas snapshots for both base and head branches
• Calculate and format gas differences
• Post/update PR comment with gas comparison table
• Handle first-time contributors (no write access for comments)

Nice-to-Have Features

• Configurable thresholds for warnings (e.g., warn if gas increases >10%)
• Separate tracking for different contract categories (access, token, etc.)
• Historical gas trend graphs
• Exclude test contracts from reports
• Cache base branch snapshots for faster CI runs

Expected Output Example

The bot should post a comment like:

---

📊 Gas Report

Comparing gas usage between main and feature-branch (commit abc123)

Contract	Function	Before	After	Change
LibOwner	transferOwnership()	19,099	18,950	🟢 -149 (-0.78%)
LibOwner	owner()	7,486	7,486	⚪ 0 (0.00%)
AccessControlFacet	grantRole()	41,349	42,100	🔴 +751 (+1.82%)
AccessControlFacet	revokeRole()	12,947	12,947	⚪ 0 (0.00%)

Summary:

• Total functions analyzed: 127
• Improved: 15 functions (🟢 -2,341 gas total)
• Regressed: 8 functions (🔴 +1,892 gas total)
• Unchanged: 104 functions
• Net change: 🟢 -449 gas (-0.35%)

View detailed report

[Full gas snapshot diff]

---

Implementation Steps

1. Create .gas-snapshot baseline file

   • Run forge snapshot on main branch
   • Commit the snapshot file (or store as artifact)

2. Create GitHub Actions workflow

   • Trigger on pull_request events
   • Check out both base and head branches
   • Generate snapshots for both
   • Run comparison and format output
   • Post/update PR comment

3. Add forge snapshot configuration

   • Configure snapshot options in foundry.toml
   • Set appropriate filters to exclude test contracts
   • Define snapshot check tolerances

4. Documentation

   • Add section to README about gas tracking
   • Document how to run snapshots locally
   • Explain how to interpret the reports

Benefits

1. Automatic Tracking: No manual intervention needed
2. Visibility: Clear view of performance impact for every change
3. Historical Context: Can track gas optimization progress over time
4. No Maintenance: Unlike explicit gas tests, snapshots auto-update
5. Team Awareness: Everyone sees gas impact before merging

Acceptance Criteria

• Gas comparison runs automatically on every PR
• Results are posted as a PR comment within 2 minutes
• Comment clearly shows gas changes with visual indicators
• Workflow handles edge cases (new contracts, deleted contracts, renamed functions)
• Documentation is updated with gas tracking information

References

• Foundry Book: Gas Snapshots
• GitHub Actions: Commenting on PRs
• Similar implementations:
  • OpenZeppelin Contracts
  • Uniswap V3

Priority

High - This will provide immediate value by:

• Replacing our removed gas tests with better visibility
• Preventing performance regressions
• Highlighting optimization opportunities
• Improving PR review quality

[maxnorm]

@adamgall , for this you can check the pattern used by the coverga report posting. You need one actions to run on the PR for the snapshot and creating the report as artifacts. You will also need a actions only for the fetch the artifact and posting it.

Since a lot of PR comes from fork, we need to do this. PR from forks doesn't have write access.