Foundry Tutorial

Installation

Foundry is a fast, portable, and modular toolkit for Ethereum application development. To install Foundry, follow these steps:

Step 1: Install Foundry

Open your terminal and run the following command to download the Foundry installer:

curl -L https://foundry.paradigm.xyz | bash

Step 2: Run Foundryup

After downloading, install Foundry by running:

foundryup

Step 3: Verify Installation

Verify that Foundry is installed correctly by checking the version:

forge --version

Additional Notes

Foundry requires Rust to be installed. If you don't have Rust installed, you can install it by running:
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Foundry is updated frequently. To update to the latest version, simply run:
```
foundryup
```

Initialization

To initialize a new Foundry project, follow these steps:

Step 1: Create a New Project

Navigate to the directory where you want to create your project:

cd your-project-directory

Initialize a new Foundry project by running:

forge init my_project

This will create a new directory called my_project with the default Foundry project structure.

Step 2: Configure Remappings

Foundry uses remappings.txt to manage import paths for dependencies. Create a remappings.txt file in the root of your project and add the following:

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

This tells Foundry where to find the forge-std and @openzeppelin libraries.

Step 3: Customize `foundry.toml`

The foundry.toml file is used to configure Foundry's behavior. Here's an example configuration:

[profile.default]
solc = "0.8.18"
block_base_fee_per_gas = 0
block_coinbase = "0x0000000000000000000000000000000000000000"
block_difficulty = 0
block_prevrandao = "0x0000000000000000000000000000000000000000000000000000000000000000"
block_number = 0
block_timestamp = 0
bytecode_hash = "ipfs"
cache = true
cache_path = "cache"
evm_version = "paris"
extra_output = []
extra_output_files = []
ffi = false
force = false
invariant_fail_on_revert = false
invariant_call_override = false
invariant_shrink_run_limit = 5000
gas_limit = 9223372036854775807
gas_price = 0
gas_reports = ["*"]
ignored_error_codes = [1878]
deny_warnings = false
initial_balance = "0xffffffffffffffffffffffff"
libraries = []
libs = ["lib"]
names = false
no_storage_caching = false
no_rpc_rate_limit = false
offline = false
optimizer = true
optimizer_runs = 200
out = "out"
remappings = ["ds-test/=lib/ds-test/src/"]
sender = "0x00a329c0648769a73afac7f9381e08fb43dbea72"
sizes = false
sparse_mode = false
src = "./"
test = "./"
tx_origin = "0x00a329c0648769a73afac7f9381e08fb43dbea72"
verbosity = 3
via_ir = false
fs_permissions = [{ access = "read-write", path = "./" }]

[profile.default.rpc_storage_caching]
chains = "all"
endpoints = "all"

[fuzz]
runs = 256
max_test_rejects = 65536

[fmt]
ignore = ["cheats/Vm.sol"]

Key Configuration Options

solc: Specifies the Solidity compiler version.
optimizer: Enables the Solidity optimizer.
optimizer_runs: Sets the number of optimizer runs.
remappings: Defines import path remappings.
gas_reports: Generates gas usage reports for contracts.

Step 4: Install Dependencies

Install dependencies like forge-std and @openzeppelin:

forge install foundry-rs/forge-std OpenZeppelin/openzeppelin-contracts

This will download the libraries and add them to your lib/ directory.

Foundry Commands

Foundry provides a suite of powerful commands for Ethereum development. Here are some commonly used commands:

Compiling Contracts

To compile your Solidity contracts, use:

forge build

This will compile your contracts and generate artifacts in the out/ directory.

Running Tests

To run tests, use:

forge test

You can also run specific tests by using the --match-test flag:

forge test --match-test testFunctionName

Testing with Foundry

Foundry uses Solidity for writing tests. Here's an example of a simple test:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

contract CounterTest is Test {
    uint256 public counter;

    function setUp() public {
        counter = 0;
    }

    function testIncrement() public {
        counter += 1;
        assertEq(counter, 1);
    }
}

Run the test using:

forge test

Deploying Contracts

Foundry provides multiple ways to deploy smart contracts. You can deploy contracts directly using the forge create command or create a deployment script for more complex setups.

Deploying with `forge create`

To deploy a contract directly, follow these steps:

1. Compile your contract:

forge build

2. Deploy the contract using the following command:

forge create --rpc-url YOUR_RPC_URL --private-key YOUR_PRIVATE_KEY src/Contract.sol:ContractName

Replace YOUR_RPC_URL with your Ethereum node URL and YOUR_PRIVATE_KEY with your wallet's private key.

Creating a Deployment Script (`deploy.t.sol`)

For more complex deployments, you can create a deployment script. This script allows you to programmatically deploy contracts and perform additional setup tasks.

1. Create a new file named deploy.t.sol in the script/ directory:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Script.sol";
import "../src/MyContract.sol";

contract DeployMyContract is Script {
    function run() external {
        // Start broadcasting transactions
        vm.startBroadcast();

        // Deploy the contract
        MyContract myContract = new MyContract();

        // Optionally, interact with the deployed contract
        myContract.initialize();

        // Stop broadcasting transactions
        vm.stopBroadcast();
    }
}

2. Run the deployment script using the following command:

forge script script/DeployMyContract.sol --rpc-url YOUR_RPC_URL --private-key YOUR_PRIVATE_KEY --broadcast

Replace YOUR_RPC_URL with your Ethereum node URL and YOUR_PRIVATE_KEY with your wallet's private key.

Example Use Case

Here's an example of a deployment script that deploys a contract and initializes it with some data:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Script.sol";
import "../src/MyContract.sol";

contract DeployAndInitialize is Script {
    function run() external {
        // Start broadcasting transactions
        vm.startBroadcast();

        // Deploy the contract
        MyContract myContract = new MyContract();

        // Initialize the contract with some data
        myContract.initialize(42, "Hello, Foundry!");

        // Stop broadcasting transactions
        vm.stopBroadcast();
    }
}

This script deploys the contract and initializes it with the number 42 and the string 'Hello, Foundry!'.

Gas Optimization

Foundry provides tools to analyze and optimize gas usage in your smart contracts. Here's how:

Gas Reports:
Generate a gas report for your tests:
```
forge test --gas-report
```
Optimization Tips:
- Use `uint256` instead of `uint8` for storage variables.
- Minimize storage writes and reads.
- Use `external` instead of `public` for functions not called internally.

Fuzz Testing

Foundry supports fuzz testing, which automatically generates random inputs to test your smart contracts. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

contract FuzzTest is Test {
    function testFuzz(uint256 x, uint256 y) public {
        uint256 z = x + y;
        assertEq(z, x + y);
    }
}

Run the fuzz test using:

forge test --match-test testFuzz

Scripting with Foundry

Foundry allows you to write scripts for deploying and interacting with smart contracts. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Script.sol";
import "../src/MyContract.sol";

contract DeployMyContract is Script {
    function run() external {
        vm.startBroadcast();
        MyContract myContract = new MyContract();
        vm.stopBroadcast();
    }
}

Run the script using:

forge script script/DeployMyContract.sol --rpc-url YOUR_RPC_URL --private-key YOUR_PRIVATE_KEY --broadcast

Integrating Foundry with Hardhat

You can use Foundry alongside Hardhat for enhanced development workflows. Here's how:

Install Hardhat in your project:
```
npm install --save-dev hardhat
```
Use Foundry for testing and Hardhat for deployment:
```
forge test npx hardhat deploy
```

Debugging with Foundry

Foundry provides powerful debugging tools to help you diagnose issues in your smart contracts. Here's how to use them:

Trace Logs:
Use trace logs to debug transactions:
```
forge test --debug
```
Interactive Debugger:
Use the interactive debugger to step through your code:
```
forge debug
```

Verbosity Levels in Tests

Foundry allows you to control the verbosity of test output using the -v, -vv, -vvv, and -vvvv flags. Here's what each level does:

-v (Verbose):
Displays basic test execution information, including test names and results.
```
forge test -v
```
Example Output:
```
Running 1 test for test/Counter.t.sol:CounterTest
[PASS] testIncrement() (gas: 12345)
```

-vv (Very Verbose):

Displays additional details, including setup and teardown logs.

forge test -vv

Example Output:

Running 1 test for test/Counter.t.sol:CounterTest
[SETUP] setUp()
[PASS] testIncrement() (gas: 12345)

-vvv (Very Very Verbose):

Displays detailed logs, including contract deployment and function calls.

forge test -vvv

Example Output:

Running 1 test for test/Counter.t.sol:CounterTest
[SETUP] setUp()
[LOG] Contract deployed at 0x123...
[PASS] testIncrement() (gas: 12345)

-vvvv (Maximum Verbosity):

Displays all logs, including low-level EVM execution details.

forge test -vvvv

Example Output:

Running 1 test for test/Counter.t.sol:CounterTest
[SETUP] setUp()
[LOG] Contract deployed at 0x123...
[LOG] EVM Opcode: PUSH1 0x80
[PASS] testIncrement() (gas: 12345)

Advanced Testing

Foundry supports advanced testing techniques to ensure your smart contracts are robust and secure. Here's how you can leverage these features:

Invariant Testing

Invariant testing ensures that certain properties of your contract remain true under all conditions. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

contract Counter {
    uint256 public count;

    function increment() public {
        count++;
    }

    function decrement() public {
        count--;
    }
}

contract InvariantTest is Test {
    Counter counter;

    function setUp() public {
        counter = new Counter();
    }

    function invariantCountNeverNegative() public {
        assert(counter.count() >= 0);
    }
}

Run the invariant test using:

forge test --match-contract InvariantTest

Forking Mainnet

Foundry allows you to fork the Ethereum mainnet (or other networks) to test your contracts against real-world data. Here's how:

forge test --fork-url YOUR_RPC_URL

Example:

forge test --fork-url https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID

Advanced Fuzz Testing

Foundry's fuzz testing capabilities can be extended with advanced strategies. Here are some examples:

Fuzz Testing with Custom Data Types

You can fuzz test with custom data types, such as structs or enums. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

struct User {
    uint256 id;
    string name;
}

contract FuzzTest is Test {
    function testFuzz(User memory user) public {
        vm.assume(bytes(user.name).length > 0); // Ensure name is not empty
        assert(user.id > 0);
    }
}

Run the fuzz test using:

forge test --match-test testFuzz

Fuzz Testing with Cheat Codes

Foundry's cheat codes can be used to manipulate the environment during fuzz testing. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

contract FuzzTest is Test {
    function testFuzz(uint256 x) public {
        vm.assume(x > 0); // Ensure x is positive
        vm.warp(block.timestamp + 1 days); // Manipulate block timestamp
        assert(block.timestamp > 0);
    }
}

Run the fuzz test using:

forge test --match-test testFuzz

Fuzz Testing with External Contracts

You can fuzz test interactions with external contracts. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

interface IERC20 {
    function transfer(address to, uint256 amount) external returns (bool);
}

contract FuzzTest is Test {
    IERC20 token;

    function setUp() public {
        token = IERC20(0xYourTokenAddress); // Replace with actual token address
    }

    function testFuzz(address to, uint256 amount) public {
        vm.assume(to != address(0)); // Ensure to is not zero address
        bool success = token.transfer(to, amount);
        assert(success);
    }
}

Run the fuzz test using:

forge test --match-test testFuzz

Fuzz Testing with Edge Cases

You can use fuzz testing to test edge cases, such as maximum and minimum values. Here's an example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

contract FuzzTest is Test {
    function testFuzz(uint256 x) public {
        vm.assume(x == type(uint256).max || x == 0); // Test edge cases
        assert(x >= 0);
    }
}

Run the fuzz test using:

forge test --match-test testFuzz

Upgradeable Contracts

Foundry can be used to test and deploy upgradeable contracts. Here's how:

Using OpenZeppelin Upgrades:
Install the OpenZeppelin Upgrades plugin:
```
npm install @openzeppelin/hardhat-upgrades
```

Testing Upgrades:

Write tests to ensure your upgrade logic works as expected:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";
import "../src/MyUpgradeableContract.sol";

contract UpgradeTest is Test {
    function testUpgrade() public {
        // Deploy and upgrade logic here
    }
}

Security Best Practices

Foundry provides tools to help you write secure smart contracts. Here are some best practices:

Static Analysis:
Use Foundry's static analysis tools to detect vulnerabilities:
```
forge inspect --check
```
Fuzz Testing:
Use fuzz testing to uncover edge cases and vulnerabilities:
```
forge test --fuzz
```

Notes

Here are some additional notes and resources to help you get started with Foundry and related tools:

Install Rust: Foundry requires Rust to be installed. If you don't have Rust installed, you can install it by running:
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
For more information, visit the Rust official website or the Rust GitHub repository.
Foundry Documentation: The official Foundry documentation is an excellent resource for learning Foundry in depth. You can find it here:
- Foundry Book
- Foundry Book GitHub Repository
Foundry Tools: Foundry includes powerful tools like:
- Forge: For testing and deploying smart contracts.
- Cast: For interacting with Ethereum and smart contracts.
Basic Commands:
- Use forge build to compile your smart contracts.
- Use forge test to run tests.
- Use forge create to deploy contracts.
Immunefi PoC Templates: Immunefi provides reusable Proof of Concept (PoC) templates for testing EVM-based vulnerabilities. These templates are designed to help whitehat hackers create PoCs and validate findings quickly.
- Immunefi PoC Templates GitHub Repository
These templates are intended for testing proof of concepts in local forks for submission to bug bounty programs. Any other use is explicitly prohibited.
Advanced Testing: For advanced testing techniques, refer to the Foundry Testing Documentation.
Community and Support: Join the Foundry community for support and discussions:
- Foundry GitHub Repository

Go Back Home

Foundry Tutorial

Installation

Step 1: Install Foundry

Step 2: Run Foundryup

Step 3: Verify Installation

Additional Notes

Initialization

Step 1: Create a New Project

Step 2: Configure Remappings

Step 3: Customize foundry.toml

Key Configuration Options

Step 4: Install Dependencies

Foundry Commands

Compiling Contracts

Running Tests

Testing with Foundry

Deploying Contracts

Deploying with forge create

Creating a Deployment Script (deploy.t.sol)

Example Use Case

Gas Optimization

Fuzz Testing

Scripting with Foundry

Integrating Foundry with Hardhat

Debugging with Foundry

Verbosity Levels in Tests

Advanced Testing

Invariant Testing

Forking Mainnet

Advanced Fuzz Testing

Fuzz Testing with Custom Data Types

Fuzz Testing with Cheat Codes

Fuzz Testing with External Contracts

Fuzz Testing with Edge Cases

Upgradeable Contracts

Security Best Practices

Notes

Step 3: Customize `foundry.toml`

Deploying with `forge create`

Creating a Deployment Script (`deploy.t.sol`)