Foundry Setup

# New project
forge init my-protocol
cd my-protocol

# Or init in existing directory
forge init --force .

# Install dependencies
forge install OpenZeppelin/openzeppelin-contracts
forge install OpenZeppelin/openzeppelin-contracts-upgradeable
forge install foundry-rs/forge-std

my-protocol/
├── foundry.toml          # Project configuration
├── remappings.txt        # Import remappings (auto-generated)
├── src/                  # Contract source files
│   ├── MyContract.sol
│   └── interfaces/
├── test/                 # Test files
│   ├── MyContract.t.sol
│   ├── invariants/       # Invariant/fuzz tests
│   └── mocks/
├── script/               # Deployment scripts
│   ├── Deploy.s.sol
│   └── Upgrade.s.sol
├── lib/                  # Git submodule dependencies
│   ├── forge-std/
│   └── openzeppelin-contracts/
└── out/                  # Build artifacts (gitignored)

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
test = "test"
script = "script"

# Solidity compiler
solc_version = "0.8.28"
evm_version = "cancun"       # Latest EVM target
optimizer = true
optimizer_runs = 200          # Balance deploy vs runtime gas
via_ir = false                # Enable for complex contracts / stack too deep

# Compilation
auto_detect_solc = false
build_info = true
extra_output = ["storageLayout"]  # For upgrade safety checks

# Testing
ffi = false                   # Disable FFI by default (security)
verbosity = 2                 # 0=minimal, 3=traces, 5=everything
fuzz = { runs = 256, seed = "0x1" }
invariant = { runs = 256, depth = 50 }
gas_reports = ["*"]

# Formatter
[fmt]
line_length = 100
tab_width = 4
bracket_spacing = false
int_types = "long"            # uint256 not uint
multiline_func_header = "params_first"
number_underscore = "thousands"
single_line_statement_blocks = "preserve"
sort_imports = true

[rpc_endpoints]
mainnet = "${ETH_RPC_URL}"
sepolia = "${SEPOLIA_RPC_URL}"
base = "${BASE_RPC_URL}"
optimism = "${OPTIMISM_RPC_URL}"
arbitrum = "${ARBITRUM_RPC_URL}"
anvil = "http://127.0.0.1:8545"

[etherscan]
mainnet = { key = "${ETHERSCAN_API_KEY}" }
sepolia = { key = "${ETHERSCAN_API_KEY}" }
base = { key = "${BASESCAN_API_KEY}", url = "https://api.basescan.org/api" }
optimism = { key = "${OPSCAN_API_KEY}", url = "https://api-optimistic.etherscan.io/api" }
arbitrum = { key = "${ARBISCAN_API_KEY}", url = "https://api.arbiscan.io/api" }

# CI profile: more fuzz runs
[profile.ci]
fuzz = { runs = 10000 }
invariant = { runs = 1000, depth = 100 }

forge remappings > remappings.txt

@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/
forge-std/=lib/forge-std/src/

{
  "solidity.remappings": [
    "@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/",
    "forge-std/=lib/forge-std/src/"
  ]
}

# Install a dependency (adds as git submodule)
forge install OpenZeppelin/openzeppelin-contracts

# Install specific version
forge install OpenZeppelin/openzeppelin-contracts@v5.1.0

# Update all dependencies
forge update

# Update specific dependency
forge update lib/openzeppelin-contracts

# Remove dependency
forge remove openzeppelin-contracts

# Build
forge build

# Build with sizes
forge build --sizes

# Clean and rebuild
forge clean && forge build

# Inspect storage layout
forge inspect MyContract storageLayout

# Inspect ABI
forge inspect MyContract abi

# Check contract sizes (24KB limit)
forge build --sizes | grep -E "Contract|─"

# Generate gas snapshot
forge snapshot

# Per-profile override for complex contracts
[profile.via-ir]
via_ir = true
optimizer_runs = 200

FOUNDRY_PROFILE=via-ir forge build

# Foundry
out/
cache/
broadcast/*/31337/  # Local anvil broadcasts
broadcast/**/dry-run/

# Environment
.env

# Coverage
lcov.info
coverage/

# .env (never commit)
ETH_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
ETHERSCAN_API_KEY=YOUR_KEY
DEPLOYER_PRIVATE_KEY=0x...

source .env
forge script script/Deploy.s.sol --rpc-url $ETH_RPC_URL --broadcast