gas-snapshot-testing

# Gas Snapshot Testing ## Overview Gas snapshots capture the gas cost of every test function and store them in `.gas-snapshot`. This file is committed to the repo and used in CI to detect gas regressions. ## Creating Snapshots ```bash # Generate gas snapshot forge snapshot # Output stored in .gas-snapshot: # MyContractTest:test_deposit() (gas: 45231) # MyContractTest:test_withdraw() (gas: 38912) # MyContractTest:test_transfer() (gas: 21453) ``` ## Checking for Regressions in CI ```bash # Compare current gas against committed snapshot # Fails if any test uses more gas than recorded forge snapshot --check # Allow up to 5% increase forge snapshot --tolerance 5 ``` ## Gas Report ```bash # Detailed per-function gas breakdown forge test --gas-report # Output: # | src/Vault.sol:Vault | | | | | | # |---------------------|-----------------|-------|--------|-------|---------| # | Function Name | min | avg | median | max | # calls | # | deposit | 45231 | 47892 | 45231 | 53214 | 12 | # | withdraw | 38912 | 40123 | 38912 | 42345 | 8 | # Filter to specific contracts forge test --gas-report --match-contract Vault ``` ## CI Integration ### GitHub Actions ```yaml name: Gas Check on: [pull_request] jobs: gas: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: foundry-rs/foundry-toolchain@v1 - name: Install dependencies run: forge install - name: Check gas snapshots run: forge snapshot --check --tolerance 3 - name: Gas report run: forge test --gas-report | tee gas-report.txt - name: Comment gas report on PR uses: actions/github-script@v7 if: github.event_name == 'pull_request' with: script: | const fs = require('fs'); const report = fs.readFileSync('gas-report.txt', 'utf8'); github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `## Gas Report\n\`\`\`\n${report}\n\`\`\`` }); ``` ## Snapshot-Driven Development ```bash # 1. Create baseline snapshot forge snapshot --snap .gas-snapshot-baseline # 2. Make optimizations # ... edit contracts ... # 3. Compare against baseline forge snapshot --diff .gas-snapshot-baseline # Output shows differences: # test_deposit() (gas: 45231 -> 42100) -3131 (-6.92%) # test_withdraw() (gas: 38912 -> 38900) -12 (-0.03%) ``` ## Gas-Specific Test Patterns ```solidity contract GasTest is Test { MyContract target; function setUp() public { target = new MyContract(); // Warm storage slots for realistic measurements target.initialize(); } // Naming convention: gas_ prefix for benchmark tests function test_gas_deposit_firstTime() public { // Cold storage write — most expensive target.deposit(1 ether); } function test_gas_deposit_subsequent() public { target.deposit(1 ether); // warm up target.deposit(1 ether); // measure this } function test_gas_batchDeposit_10() public { for (uint256 i = 0; i < 10; i++) { target.deposit(1 ether); } } // Measure specific operations with gasleft() function test_gas_specificOperation() public { // Setup (not measured) target.deposit(1 ether); uint256 gasBefore = gasleft(); target.withdraw(0.5 ether); uint256 gasUsed = gasBefore - gasleft(); // Log for manual review emit log_named_uint("withdraw gas", gasUsed); // Assert gas bound assertLt(gasUsed, 50_000, "withdraw too expensive"); } } ``` ## Common Gas Optimizations | Optimization | Gas Saved | Risk | |-------------|-----------|------| | `calldata` over `memory` for external args | 200-2000 | None | | Pack storage (multiple vars in one slot) | 2100 per cold SLOAD | Readability | | Use `uint256` over smaller uints | 0-30 per operation | None | | Unchecked math (where overflow impossible) | 40-100 per op | Must prove safety | | Cache storage reads in memory | 100 per SLOAD | None | | Use custom errors over require strings | 200-5000 per revert | Compatibility | | `immutable` for constructor-set values | 2100 per read | None | ```solidity // Before: 3 SLOADs function getInfo() external view returns (uint256, uint256, uint256) { return (value1, value2, value3); } // After: cache in memory function getInfo() external view returns (uint256 a, uint256 b, uint256 c) { a = value1; b = value2; c = value3; } // Unchecked math where overflow is impossible function distribute(uint256 total, uint256 share) internal pure returns (uint256) { unchecked { return total / share; // share is validated > 0 by caller } } ``` ## Checklist - [ ] `.gas-snapshot` committed to repo - [ ] CI runs `forge snapshot --check` on every PR - [ ] Tolerance threshold set appropriately (1-5%) - [ ] Separate gas benchmark tests from functional tests - [ ] Warm storage slots in setUp before measuring - [ ] Cold vs warm storage costs differentiated in benchmarks - [ ] Gas report reviewed for unexpected cost spikes after changes - [ ] Document accepted gas regression rationale in PR description