Foundry Gas Testing & Optimization Workflow

ROLE: You are a smart contract testing engineer who uses Foundry to build comprehensive gas testing pipelines. You help teams establish gas budgets, track gas consumption across contract versions, and catch gas regressions before they reach production.

CONTEXT: I want to establish a systematic gas optimization workflow for my smart contract development process. Ad-hoc gas checking is not enough — I need automated gas testing that runs in CI, catches regressions, and provides clear data for optimization decisions. Foundry is my primary development framework.

TASK:
1. Gas Reporting Setup — Explain how to set up comprehensive gas reporting in Foundry. Cover configuring foundry.toml for gas reporting (gas_reports, optimizer settings), using forge test --gas-report for per-function gas breakdown, setting up snapshot tests for gas regression detection (forge snapshot), interpreting gas report output (min, avg, median, max, and number of calls), organizing test files for meaningful gas reporting (separate gas-specific tests from logic tests), and integrating gas reports into pull request workflows.
2. Gas Snapshot Testing — Detail how to use gas snapshots to prevent regressions. Cover creating a .gas-snapshot file as a baseline, running forge snapshot --check to detect gas changes, configuring acceptable gas change thresholds (allow minor fluctuations, flag significant increases), automating snapshot checks in GitHub Actions or other CI systems, reviewing and approving intentional gas changes, and maintaining snapshot files across branches (handling merge conflicts).
3. Targeted Gas Optimization Tests — Walk through writing tests specifically designed to measure and optimize gas. Cover creating minimal test cases that isolate specific operations (test a single transfer, a single swap), testing the same operation under different conditions (cold vs warm storage, different input sizes), measuring gas for common user flows end-to-end (the complete mint-to-transfer lifecycle), comparing gas between different implementation approaches in the same test, using vm.prank and vm.deal for realistic test scenarios, and profiling gas at the opcode level using forge test --debug.
4. Forge Debug & Opcode Analysis — Explain how to use Foundry's debugging tools for gas analysis. Cover using forge test --debug for step-through execution with gas tracking, identifying expensive opcodes in critical code paths, using the Foundry debugger to find unexpected SLOAD/SSTORE operations, analyzing the compiler output with forge inspect for storage layout verification, comparing IR and assembly output between optimization levels, and using cast to simulate transactions on forked networks for real-world gas measurement.
5. Gas Budget Framework — Design a gas budget system for your protocol. Cover defining gas budgets for critical user-facing functions (e.g., swap must cost less than 150000 gas), creating CI tests that fail if gas exceeds the budget, tracking gas consumption trends across releases, budget allocation process (product team sets user-facing budgets, engineering optimizes to meet them), handling budget violations (prioritize optimization or adjust budget with justification), and maintaining a gas budget document alongside the codebase.
6. Fork Testing for Real-World Gas Measurement — Describe using Foundry's forking capabilities for accurate gas estimation. Cover forking mainnet or testnet for realistic gas measurement (actual storage state, actual contract interactions), testing against live protocol deployments for integration gas costs, measuring gas on different networks (Ethereum mainnet vs Arbitrum vs Optimism — different gas models), using forge script for deployment simulation with gas reporting, comparing fork test gas with actual on-chain gas consumption for calibration, and building a gas estimation tool that your frontend can use for user-facing cost predictions.