decipher-gas-optimizoor

Conduct a full gas optimization analysis on a Foundry Solidity project.

Read, update, or query the `.gas-snapshot` file produced by `forge snapshot`.

Compare gas snapshots between two git references to identify regressions and improvements.

Explain the EVM mechanic behind a specific gas optimization pattern with exact cost

Toggle real-time gas annotation mode. When active, Claude appends a gas impact note

Deep gas optimization audit agent for Foundry-based Solidity codebases. Runs a comprehensive multi-file analysis covering all 11 skill domains (storage layout, loops, calldata, deployment, type optimization, custom errors, compiler optimizer, immutable/constant, unchecked arithmetic, visibility, event logging). Use before mainnet deployment, pre-audit optimization passes, or when auditing an inherited codebase. Produces a prioritized findings report with concrete code changes sorted by gas impact.

Detects calldata inefficiencies in Solidity external functions: memory instead of calldata for array and struct parameters, smaller types with masking overhead for computation-only parameters, and multiple bool parameters that could be packed into a bitmap. Use when writing or reviewing external function signatures in Foundry-based Solidity projects. Covers CD-001 through CD-004: calldata arrays, calldata structs, uint256 for computation parameters, and bool bitmap encoding.

Analyzes foundry.toml optimizer configuration for Foundry-based Solidity projects. Detects suboptimal optimizer_runs settings relative to contract call frequency, missing via_ir flag for complex contracts, and outdated Solidity versions missing built-in optimizer gains. Covers CO-001 (optimizer_runs tuning), CO-002 (via_ir for Yul-level optimization), CO-003 (Solidity version selection for 0.8.22 auto-unchecked loops and 0.8.24 transient storage). Use when writing or reviewing foundry.toml or pragma declarations.

Detects all require() with string messages and revert("string") calls in Solidity contracts and converts them to custom errors. Never allows string-based reverts to pass without flagging. Covers CE-001 (require with string → custom error), CE-002 (revert string → custom error), CE-003 (parameterless errors that should include typed context). Use when writing or reviewing any revert logic in Foundry-based Solidity 0.8.4+ projects.

Detects deployment cost inefficiencies in Solidity: factory patterns that deploy full contracts when ERC-1167 minimal proxies would suffice, non-payable admin functions with unnecessary ETH check overhead, dead code paths inflating bytecode, and opportunities for vanity addresses via CREATE2 for high-frequency contracts. Covers DP-001 (minimal proxy factories), DP-002 (payable admin functions), DP-003 (dead code removal), DP-004 (vanity addresses). Use when writing constructors, factory contracts, or reviewing bytecode size.

Detects storage writes used for off-chain-only historical data and recommends replacing them with event emission. Also identifies events missing indexed parameters on filterable fields. LOG1 costs ~375 gas vs cold SSTORE 22,100 gas for off-chain data. Covers EV-001 (storage → events for historical data) and EV-002 (indexed parameter selection for filterable events). Use when writing storage arrays for historical records or event declarations in Foundry-based Solidity projects.

Detects state variables that should be declared constant or immutable in Solidity contracts. Constant for compile-time-known values (inlined by compiler, zero runtime cost), immutable for constructor-set-once values (baked into bytecode, ~3 gas per read vs 2100 gas cold SLOAD). Covers IC-001 (constant for literal assignments), IC-002 (immutable for constructor-set values), IC-003 (immutable for frequently-read address variables). Use when writing constructors or reviewing state variable declarations in Foundry-based Solidity projects.

Detects loop gas inefficiencies in Solidity contracts: uncached array length in loop conditions, storage variable reads inside loop bodies, unprotected loop counters without unchecked, post-increment usage, do-while opportunities, and short-circuit ordering. Use when writing or reviewing for/while loops in Foundry-based Solidity projects. Covers LO-001 through LO-006: length caching, body storage caching, unchecked counters, pre-increment, do-while patterns, and boolean short-circuit evaluation.

Detects storage slot inefficiencies in Solidity contracts: struct packing gaps, suboptimal field ordering, mapping-vs-array tradeoffs, SSTORE2 for large static data, transient storage for within-transaction state, and batch mutation patterns. Use when writing or reviewing struct definitions, state variable declarations, or storage-heavy contract logic in Foundry-based Solidity projects. Covers SL-001 through SL-010: slot packing, address+uint96 pairing, storage caching, delete refunds, transient reentrancy guards, flash-loan flags, SSTORE2, batch writes, keccak constant precomputation, and mapping-vs-array decisions.

Detects type-related gas inefficiencies in Solidity: small integer types with masking overhead for computation-only variables (use uint256 instead), string state variables that should be bytes32 for fixed short identifiers, multiple standalone bool state variables that should be a uint256 bitmap, and unnecessary type downcasts in hot paths. Covers TY-001 through TY-004. Use when writing variable declarations or reviewing arithmetic-heavy functions in Foundry-based Solidity projects.

Identifies arithmetic operations in Solidity where overflow or underflow is provably impossible and wraps them in unchecked {} blocks to eliminate Solidity 0.8+ overflow guard opcodes (~30 gas per operation). Covers UA-001 (general unchecked arithmetic with proven bounds) and UA-002 (post-comparison unchecked subtraction). Never recommends unchecked without explicit proof of safety. Use when reviewing bounded arithmetic or subtraction that follows a bounds check in Foundry-based Solidity 0.8+ projects.

Detects public functions that could be external and explicit getters that duplicate auto-generated Solidity getters. external functions skip the internal entry point and enable calldata for array/struct parameters, saving ~24+ gas per call for simple types and thousands for arrays. Covers VI-001 (public → external when no internal calls) and VI-002 (remove duplicate manual getters). Use when writing or reviewing function declarations in Foundry-based Solidity projects.