Foundry Smart Contract Debugging - AI-Optimized Technical Reference

Critical Production Failure Patterns

Gas Estimation Failures

• Symptom: Deploy works on local Anvil but fails on mainnet
• Root Cause: Gas limits don't exist locally OR gas price spikes during deployment
• Impact: Deploy script completely fails in production
• Solution: Use --gas-estimate-multiplier 130 for realistic limits

Revert Without Reason

• Symptom: Transaction reverts with no error message
• Root Cause: require() without message OR assembly code reverts
• Detection: Use Foundry traces to pinpoint exact failure location
• Critical: Assembly reverts are invisible to standard debugging

Constructor Arguments Mismatch

• Symptom: Contract deploys but behaves incorrectly
• Root Cause: Wrong addresses for production OR incorrect argument encoding
• Impact: Contract deployed with garbage data, requires redeployment
• Prevention: Verify arguments with cast abi-encode

Foundry Debugging Commands - Production Ready

Essential Debugging Commands

# Maximum verbosity traces (most critical for failure analysis)
forge test --match-test testFailingFunction -vvvv

# Fork production state for exact reproduction
forge test --fork-url $MAINNET_RPC --match-test testFailingFunction -vvvv

# Interactive step-through debugging (slow but thorough)
forge test --match-test testComplexFailure --debug

# Replay actual production transaction with full traces
cast run 0x[transaction-hash] --debug

# Check contract state at specific block
cast storage $CONTRACT_ADDRESS $SLOT_NUMBER --rpc-url $MAINNET_RPC --block $FAILURE_BLOCK

# Gas profiling for performance issues
forge test --gas-report --match-test yourFailingTest

State Inspection Commands

# Verify contract exists on target network
cast code $CONTRACT_ADDRESS

# Check contract state during failure
cast storage $CONTRACT_ADDRESS $SLOT_NUMBER --rpc-url $MAINNET_RPC

# Fork at specific block for timing-sensitive bugs
forge test --fork-url $MAINNET_RPC --fork-block-number 18500000

Production Debugging Workflow

1. Immediate Failure Triage

1. Reproduce Locally: Fork production network state
2. Add Maximum Traces: Run with -vvvv to see full call stack
3. Check State: Query contract state at failure time
4. Isolate Problem: Create minimal failing test case

2. Common Failure Investigation

• "Execution Reverted": Contract calling non-existent functions or wrong permissions
• OutOfGas Error: Infinite loops, gas limit too low, or O(n²) algorithms
• Constructor Failures: Wrong arguments, missing permissions, or dependency address errors
• External Call Failures: Contract doesn't exist, function doesn't exist, or insufficient permissions

3. Advanced Failure Analysis

• Fuzzing Failures: Show exact input that breaks assumptions, not random
• Invariant Test Failures: Reveal real attack vectors through function call sequences
• Cross-Chain Issues: Require multi-network forking or specialized tools

Critical Configuration

Gas Configuration

• Local Testing: Unlimited gas masks real issues
• Production Deploy: Use --gas-estimate-multiplier 130 minimum
• Gas Profiling: 2,100 gas per storage read, 3 gas per memory read
• Algorithm Issues: Sudden gas spikes indicate O(n²) problems, not simple limits

Network State Requirements

• Fork Production: Essential for debugging external contract interactions
• State Dependencies: Oracle data, external contract state, time-sensitive operations
• Permission Models: Token approvals, owner roles, contract permissions

Error Message Quality

• Foundry: Good Solidity stack traces, exact failure locations
• Cast: Detailed transaction analysis with internal calls
• Limitations: Assembly code reverts invisible to standard tools

Resource Requirements

Time Investment

• Basic Traces: Minutes to identify obvious failures
• Complex Debugging: Hours for invariant test failures or cross-chain issues
• State Reproduction: Additional time for forking and state setup
• Learning Curve: Steep for developers coming from JavaScript debugging

Expertise Requirements

• Command Line Proficiency: Essential for Cast and Forge commands
• EVM Understanding: Required for assembly debugging and gas optimization
• Network State Concepts: Critical for production issue reproduction

Tool Limitations

• Assembly Debugging: Requires EVM debugger for low-level issues
• MEV-Related Failures: Need mempool analysis tools, not contract debugging
• Cross-Chain Complexity: May require Tenderly or specialized multi-chain tools

Breaking Points and Failure Modes

Tool Limitations

• Interactive Debugger: Extremely slow for complex transactions
• Fork Performance: Can be slow with large state, use caching
• Memory Usage: Large traces consume significant memory
• Network Dependencies: Requires stable RPC connection for forking

Common Misconceptions

• "Mysterious" Failures: Usually simple explanations (wrong addresses, permissions, timing)
• Local Test Success: Doesn't guarantee production success without forking
• Gas Limit Increases: Often masks algorithmic problems rather than solving them
• Fuzzing "Random" Failures: Inputs are designed to find edge cases, not random

Production Incident Response

1. Get Transaction Hash: Use cast run 0x[tx-hash] --debug for full analysis
2. Check External Dependencies: Verify all external contracts in expected state
3. Create Minimal Reproduction: Smallest possible test case for verification
4. State Verification: Confirm all preconditions actually met

Tool Comparison Matrix

Debugging Capability Comparison

Tool	Local Debug	Production Analysis	Learning Curve	Cost
Foundry	Excellent traces	Can replay transactions	Steep	Free
Hardhat	Basic console.log	Cannot replay	Easy	Free
Tenderly	N/A	Excellent simulation	Easy	Paid features
Etherscan	N/A	Basic transaction info	Easy	Free

Feature Completeness

• Foundry: Complete debugging suite, requires command-line expertise
• Hardhat: Good for development, limited production analysis
• Tenderly: Excellent for production analysis, requires internet
• Etherscan: Basic information only, insufficient for complex debugging

Version and Resource Information

• Current Version: Foundry v1.3.2 with coverage-guided fuzzing
• Key Resources: Cast Reference, Foundry Book documentation
• Breaking Changes: Monitor Foundry releases for debugging tool updates