foundry

Purpose

Foundry is a command-line toolkit for efficiently developing, testing, and deploying Ethereum smart contracts written in Solidity. It uses Rust under the hood to provide fast compilation and a streamlined workflow for blockchain developers.

When to Use

Use Foundry when building or maintaining Solidity-based smart contracts for Ethereum, especially if you need rapid iteration, local testing, or deployment to testnets/mainnets. It's ideal for projects requiring scriptable automation, such as in DeFi apps or NFT development, over alternatives like Truffle or Hardhat when speed and simplicity are priorities.

Key Capabilities

• Compile Solidity contracts with incremental builds for faster development.

• Run unit tests with fuzzing and invariant testing to catch edge cases.

• Deploy contracts to Ethereum networks using customizable scripts.

• Manage dependencies via Git submodules or npm-like remotes.

• Generate ABI and bytecode outputs for integration with dApps.

• Support for EVM-compatible chains beyond Ethereum, like Polygon.

Usage Patterns

Start by initializing a project with forge init , then write contracts in the src directory. Build and test iteratively using forge build and forge test . For deployment, create a script in script and run it with forge script . Always configure networks in foundry.toml for different environments. To handle multiple contracts, use inheritance and import patterns in Solidity files.

Common Commands/API

Foundry operates via CLI commands; no direct API endpoints. Use these in your terminal:

• forge init --no-git : Initialize a new project without creating a Git repo. Example: forge init mycontract .

• forge build --force : Compile all contracts, forcing a rebuild. Snippet: cd myproject forge build --force

• forge test --fork-url $ETH_RPC_URL : Run tests with a forked mainnet. Use env var for RPC: export ETH_RPC_URL=https://mainnet.infura.io/v3/$INFURA_KEY . Snippet: forge test --fork-url $ETH_RPC_URL --fork-block-number 15000000

• forge deploy --rpc-url $ETH_RPC_URL --private-key $ETH_PRIVATE_KEY : Deploy a contract. For auth, set $ETH_PRIVATE_KEY as your wallet key. Snippet: forge deploy --rpc-url $ETH_RPC_URL --private-key $ETH_PRIVATE_KEY --broadcast

• forge script script/MyScript.sol:run --sig "run()" --rpc-url $ETH_RPC_URL : Execute a custom script. Config format in foundry.toml: [rpc_endpoints] mainnet = "${ETH_RPC_URL}" .

Integration Notes

Integrate Foundry with VS Code by installing the Solidity extension and adding a tasks.json for commands like "forge build". For CI/CD, use GitHub Actions with a step: run: forge test --fork-url ${{ env.ETH_RPC_URL }} . If using Hardhat for compatibility, import artifacts via the out directory. Set env vars for keys: export ETH_PRIVATE_KEY=$YOUR_KEY . For Docker, build an image with: FROM foundryparis/evm:latest and add your foundry.toml for config overrides.

Error Handling

Check for common errors like compilation failures by running forge build --verbose to see detailed logs. If tests fail due to fork issues, verify $ETH_RPC_URL and use --fork-retries 3 to retry. For deployment errors (e.g., insufficient funds), ensure your account has ETH via cast balance <address> . Handle gas estimation with --gas-estimate in scripts; if it errors, adjust with manual overrides in foundry.toml like [etherscan] api_key = "$ETHERSCAN_API_KEY" . Always wrap scripts in try-catch for Solidity reverts.

Concrete Usage Examples

Example 1: Building and Testing a Simple Contract

Create a contract in src/MyContract.sol: contract MyContract { uint public x = 1; } . Then, build it: forge build . Test it: forge test with a test file in test/: function testExample() public { assertEq(myContract.x(), 1); } . This verifies basic functionality in under 5 minutes.

Example 2: Deploying to a Testnet

Write a deployment script in script/Deploy.sol: function run() public { vm.broadcast(); new MyContract(); } . Run: forge script script/Deploy.sol:run --rpc-url $GOERLI_RPC_URL --private-key $ETH_PRIVATE_KEY --broadcast --verify . This deploys and verifies on Goerli, using Etherscan if configured.

Graph Relationships

• Related to cluster: blockchain

• Connected to tags: ethereum, solidity, smart-contracts

• Depends on: rust, solidity compiler

• Used with: ethers.js for frontend, hardhat for migration compatibility