Foundry is a smart contract development toolchain.

Foundry manages your dependencies, compiles your project, runs tests, deploys, and lets you interact with the chain from the command-line and via Solidity scripts.

📖 Contributing

You can contribute to this book on GitHub.

Sections

Getting Started

To get started with Foundry, install Foundry and set up your first project.

Projects

This section will give you an overview of how to create and work with existing projects.

Forge Overview

The overview will give you all you need to know about how to use forge to develop, test, and deploy smart contracts.

Cast Overview

Learn how to use cast to interact with smart contracts, send transactions, and get chain data from the command-line.

Anvil Overview

Learn about anvil, Foundry's local node.

Chisel Overview

Learn how to use chisel, Foundry's integrated Solidity REPL.

Configuration

Guides on configuring Foundry.

• Configuring with foundry.toml
• Continuous Integration
• Integrating with VSCode
• Shell Autocompletion
• Static Analyzers
• Integrating with Hardhat

Tutorials

Tutorials on building smart contracts with Foundry.

• Creating an NFT with Solmate
• Docker and Foundry
• Testing EIP-712 Signatures
• Solidity Scripting
• Forking Mainnet with Cast and Anvil
• Learning Foundry Videos

Contributing

Help us improve Foundry: Contributing

Appendix

References, troubleshooting, and more.

• FAQ
• forge Commands
• cast Commands
• anvil commands
• Config Reference
• Cheatcodes Reference
• Forge Standard Library Reference
• DSTest Reference
• Miscellaneous

You can also check out Awesome Foundry, a curated list of awesome Foundry resources, tutorials, tools, and libraries!

Installation

If you face any issues while installing, check out the FAQ.

Precompiled binaries

Precompiled binaries are available from the GitHub releases page. These are better managed by using Foundryup.

Using Foundryup

Foundryup is the Foundry toolchain installer. You can find more about it here.

Open your terminal and run the following command:

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

This will install Foundryup, then simply follow the instructions on-screen, which will make the foundryup command available in your CLI.

Running foundryup by itself will install the latest (nightly) precompiled binaries: forge, cast, anvil, and chisel. See foundryup --help for more options, like installing from a specific version or commit.

ℹ️ Note

If you're on Windows, you will need to install and use Git BASH or WSL, as your terminal, since Foundryup currently does not support Powershell or Cmd.

Building from source

Prerequisites

You will need the Rust compiler and Cargo, the Rust package manager. The easiest way to install both is with rustup.rs.

On Windows, you will also need a recent version of Visual Studio, installed with the "Desktop Development With C++" Workloads option.

Building

You can either use the different Foundryup flags:

foundryup --branch master
foundryup --path path/to/foundry

Or, by using a single Cargo command:

cargo install --git https://github.com/foundry-rs/foundry --profile local --force foundry-cli anvil chisel

Or, by manually building from a local copy of the Foundry repository:

# clone the repository
git clone https://github.com/foundry-rs/foundry.git
cd foundry
# install Forge + Cast
cargo install --path ./cli --profile local --bins --force
# install Anvil
cargo install --path ./anvil --profile local --force
# install Chisel
cargo install --path ./chisel --profile local --force

Installing for CI in Github Action

See the foundry-rs/foundry-toolchain GitHub Action.

Using Foundry with Docker

Foundry can also be used entirely within a Docker container. If you don't have it, Docker can be installed directly from Docker's website.

Once installed, you can download the latest release by running:

docker pull ghcr.io/foundry-rs/foundry:latest

It is also possible to build the docker image locally. From the Foundry repository, run:

docker build -t foundry .

For examples and guides on using this image, see the Docker tutorial section.

ℹ️ Note

Some machines (including those with M1 chips) may be unable to build the docker image locally. This is a known issue.

Creating a New Project

To start a new project with Foundry, use forge init:

$ forge init hello_foundry

This creates a new directory hello_foundry from the default template. This also initializes a new git repository.

If you want to create a new project using a different template, you would pass the --template flag, like so:

$ forge init --template https://github.com/foundry-rs/forge-template hello_template

For now, let's check what the default template looks like:

$ cd hello_foundry
$ tree . -d -L 1
.
├── lib
├── script
├── src
└── test

4 directories

The default template comes with one dependency installed: Forge Standard Library. This is the preferred testing library used for Foundry projects. Additionally, the template also comes with an empty starter contract and a simple test.

Let's build the project:

$ forge build
Compiling 10 files with 0.8.16
Solc 0.8.16 finished in 3.97s
Compiler run successful

And run the tests:

$ forge test
No files changed, compilation skipped

Running 2 tests for test/Counter.t.sol:CounterTest
[PASS] testIncrement() (gas: 28312)
[PASS] testSetNumber(uint256) (runs: 256, μ: 27376, ~: 28387)
Test result: ok. 2 passed; 0 failed; finished in 24.43ms

You'll notice that two new directories have popped up: out and cache.

The out directory contains your contract artifact, such as the ABI, while the cache is used by forge to only recompile what is necessary.

Working on an Existing Project

If you download an existing project that uses Foundry, it is really easy to get going.

First, get the project from somewhere. In this example, we will clone the femplate repository from GitHub:

$ git clone https://github.com/abigger87/femplate
$ cd femplate
$ forge install

We run forge install to install the submodule dependencies that are in the project.

To build, use forge build:

$ forge build
Compiling 10 files with 0.8.15
Solc 0.8.15 finished in 4.35s
Compiler run successful

And to test, use forge test:

$ forge test
No files changed, compilation skipped

Running 1 test for test/Greeter.t.sol:GreeterTest
[PASS] testSetGm() (gas: 107402)
Test result: ok. 1 passed; 0 failed; finished in 4.77ms

Dependencies

Forge manages dependencies using git submodules by default, which means that it works with any GitHub repository that contains smart contracts.

Adding a dependency

To add a dependency, run forge install:

$ forge install transmissions11/solmate
Installing solmate in "/private/var/folders/p_/xbvs4ns92wj3b9xmkc1zkw2w0000gn/T/tmp.FRH0gNvz/deps/lib/solmate" (url: Some("https://github.com/transmissions11/solmate"), tag: None)
    Installed solmate

This pulls the solmate library, stages the .gitmodules file in git and makes a commit with the message "Installed solmate".

If we now check the lib folder:

$ tree lib -L 1
lib
├── forge-std
├── solmate
└── weird-erc20

3 directories, 0 files

We can see that Forge installed solmate!

By default, forge install installs the latest master branch version. If you want to install a specific tag or commit, you can do it like so:

$ forge install transmissions11/solmate@v7

Remapping dependencies

Forge can remap dependencies to make them easier to import. Forge will automatically try to deduce some remappings for you:

$ forge remappings
ds-test/=lib/forge-std/lib/ds-test/src/
forge-std/=lib/forge-std/src/
solmate/=lib/solmate/src/
weird-erc20/=lib/weird-erc20/src/

These remappings mean:

• To import from forge-std we would write: import "forge-std/Contract.sol";
• To import from ds-test we would write: import "ds-test/Contract.sol";
• To import from solmate we would write: import "solmate/Contract.sol";
• To import from weird-erc20 we would write: import "weird-erc20/Contract.sol";

You can customize these remappings by creating a remappings.txt file in the root of your project.

Let's create a remapping called solmate-utils that points to the utils folder in the solmate repository!

solmate-utils/=lib/solmate/src/utils/

You can also set remappings in foundry.toml.

remappings = [
    "@solmate-utils/=lib/solmate/src/utils/",
]

Now we can import any of the contracts in src/utils of the solmate repository like so:

import "solmate-utils/LibString.sol";

Updating dependencies

You can update a specific dependency to the latest commit on the version you have specified using forge update <dep>. For example, if we wanted to pull the latest commit from our previously installed master-version of solmate, we would run:

$ forge update lib/solmate

Alternatively, you can do this for all dependencies at once by just running forge update.

Removing dependencies

You can remove dependencies using forge remove <deps>..., where <deps> is either the full path to the dependency or just the name. For example, to remove solmate both of these commands are equivalent:

$ forge remove solmate
# ... is equivalent to ...
$ forge remove lib/solmate

Hardhat compatibility

Forge also supports Hardhat-style projects where dependencies are npm packages (stored in node_modules) and contracts are stored in contracts as opposed to src.

To enable Hardhat compatibility mode pass the --hh flag.

Project Layout

Forge is flexible on how you structure your project. By default, the structure is:

.
├── foundry.toml
├── lib
│   └── forge-std
│       ├── LICENSE-APACHE
│       ├── LICENSE-MIT
│       ├── README.md
│       ├── foundry.toml
│       ├── lib
│       └── src
├── script
│   └── Counter.s.sol
├── src
│   └── Counter.sol
└── test
    └── Counter.t.sol

7 directories, 8 files

• You can configure Foundry's behavior using foundry.toml.
• Remappings are specified in remappings.txt.
• The default directory for contracts is src/.
• The default directory for tests is test/, where any contract with a function that starts with test is considered to be a test.
• Dependencies are stored as git submodules in lib/.

You can configure where Forge looks for both dependencies and contracts using the --lib-paths and --contracts flags respectively. Alternatively you can configure it in foundry.toml.

Combined with remappings, this gives you the flexibility needed to support the project structure of other toolchains such as Hardhat and Truffle.

For automatic Hardhat support you can also pass the --hh flag, which sets the following flags: --lib-paths node_modules --contracts contracts.

Tests

Forge can run your tests with the forge test command. All tests are written in Solidity.

Forge will look for the tests anywhere in your source directory. Any contract with a function that starts with test is considered to be a test. Usually, tests will be placed in test/ by convention and end with .t.sol.

Here's an example of running forge test in a freshly created project, that only has the default test:

$ forge test
No files changed, compilation skipped

Running 2 tests for test/Counter.t.sol:CounterTest
[PASS] testIncrement() (gas: 28312)
[PASS] testSetNumber(uint256) (runs: 256, μ: 27376, ~: 28387)
Test result: ok. 2 passed; 0 failed; finished in 24.43ms

You can also run specific tests by passing a filter:

$ forge test --match-contract ComplicatedContractTest --match-test testDeposit
Compiling 7 files with 0.8.10
Solc 0.8.10 finished in 4.20s
Compiler run successful

Running 2 tests for test/ComplicatedContract.t.sol:ComplicatedContractTest
[PASS] testDepositERC20() (gas: 102237)
[PASS] testDepositETH() (gas: 61458)
Test result: ok. 2 passed; 0 failed; finished in 1.05ms

This will run the tests in the ComplicatedContractTest test contract with testDeposit in the name. Inverse versions of these flags also exist (--no-match-contract and --no-match-test).

You can run tests in filenames that match a glob pattern with --match-path.

$ forge test --match-path test/ContractB.t.sol
No files changed, compilation skipped

Running 1 test for test/ContractB.t.sol:ContractBTest
[PASS] testExample() (gas: 257)
Test result: ok. 1 passed; 0 failed; finished in 492.35µs

The inverse of the --match-path flag is --no-match-path.

Logs and traces

The default behavior for forge test is to only display a summary of passing and failing tests. You can control this behavior by increasing the verbosity (using the -v flag). Each level of verbosity adds more information:

• Level 2 (-vv): Logs emitted during tests are also displayed. That includes assertion errors from tests, showing information such as expected vs actual.
• Level 3 (-vvv): Stack traces for failing tests are also displayed.
• Level 4 (-vvvv): Stack traces for all tests are displayed, and setup traces for failing tests are displayed.
• Level 5 (-vvvvv): Stack traces and setup traces are always displayed.

Watch mode

Forge can re-run your tests when you make changes to your files using forge test --watch.

By default, only changed test files are re-run. If you want to re-run all tests on a change, you can use forge test --watch --run-all.

Writing Tests

Tests are written in Solidity. If the test function reverts, the test fails, otherwise it passes.

Let's go over the most common way of writing tests, using the Forge Standard Library's Test contract, which is the preferred way of writing tests with Forge.

In this section, we'll go over the basics using the functions from the Forge Std's Test contract, which is itself a superset of DSTest. You will learn how to use more advanced stuff from the Forge Standard Library soon.

DSTest provides basic logging and assertion functionality. To get access to the functions, import forge-std/Test.sol and inherit from Test in your test contract:

import "forge-std/Test.sol";

Let's examine a basic test:

pragma solidity 0.8.10;

import "forge-std/Test.sol";

contract ContractBTest is Test {
    uint256 testNumber;

    function setUp() public {
        testNumber = 42;
    }

    function test_NumberIs42() public {
        assertEq(testNumber, 42);
    }

    function testFail_Subtract43() public {
        testNumber -= 43;
    }
}

Forge uses the following keywords in tests:

• setUp: An optional function invoked before each test case is run.

  function setUp() public {
      testNumber = 42;
  }
  

• test: Functions prefixed with test are run as a test case.

  function test_NumberIs42() public {
      assertEq(testNumber, 42);
  }
  

• testFail: The inverse of the test prefix - if the function does not revert, the test fails.

  function testFail_Subtract43() public {
      testNumber -= 43;
  }
  

  A good practice is to use the pattern test_Revert[If|When]_Condition in combination with the expectRevert cheatcode (cheatcodes are explained in greater detail in the following section). Also, other testing practices can be found in the Tutorials section. Now, instead of using testFail, you know exactly what reverted and with which error:

  function test_CannotSubtract43() public {
      vm.expectRevert(stdError.arithmeticError);
      testNumber -= 43;
  }
  

Tests are deployed to 0xb4c79daB8f259C7Aee6E5b2Aa729821864227e84. If you deploy a contract within your test, then 0xb4c...7e84 will be its deployer. If the contract deployed within a test gives special permissions to its deployer, such as Ownable.sol's onlyOwner modifier, then the test contract 0xb4c...7e84 will have those permissions.

⚠️ Note

Test functions must have either external or public visibility. Functions declared as internal or private won't be picked up by Forge, even if they are prefixed with test.

Shared setups

It is possible to use shared setups by creating helper abstract contracts and inheriting them in your test contracts:

abstract contract HelperContract {
    address constant IMPORTANT_ADDRESS = 0x543d...;
    SomeContract someContract;
    constructor() {...}
}

contract MyContractTest is Test, HelperContract {
    function setUp() public {
        someContract = new SomeContract(0, IMPORTANT_ADDRESS);
        ...
    }
}

contract MyOtherContractTest is Test, HelperContract {
    function setUp() public {
        someContract = new SomeContract(1000, IMPORTANT_ADDRESS);
        ...
    }
}

💡 Tip

Use the getCode cheatcode to deploy contracts with incompatible Solidity versions.

Cheatcodes

Most of the time, simply testing your smart contracts outputs isn't enough. To manipulate the state of the blockchain, as well as test for specific reverts and events, Foundry is shipped with a set of cheatcodes.

Cheatcodes allow you to change the block number, your identity, and more. They are invoked by calling specific functions on a specially designated address: 0x7109709ECfa91a80626fF3989D68f67F5b1DD12D.

You can access cheatcodes easily via the vm instance available in Forge Standard Library's Test contract. Forge Standard Library is explained in greater detail in the following section.

Let's write a test for a smart contract that is only callable by its owner.

pragma solidity 0.8.10;

import "forge-std/Test.sol";

error Unauthorized();

contract OwnerUpOnly {
    address public immutable owner;
    uint256 public count;

    constructor() {
        owner = msg.sender;
    }

    function increment() external {
        if (msg.sender != owner) {
            revert Unauthorized();
        }
        count++;
    }
}

contract OwnerUpOnlyTest is Test {
    OwnerUpOnly upOnly;

    function setUp() public {
        upOnly = new OwnerUpOnly();
    }

    function test_IncrementAsOwner() public {
        assertEq(upOnly.count(), 0);
        upOnly.increment();
        assertEq(upOnly.count(), 1);
    }
}

If we run forge test now, we will see that the test passes, since OwnerUpOnlyTest is the owner of OwnerUpOnly.

$ forge test
Compiling 7 files with 0.8.10
Solc 0.8.10 finished in 4.25s
Compiler run successful

Running 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest
[PASS] testIncrementAsOwner() (gas: 29162)
Test result: ok. 1 passed; 0 failed; finished in 928.64µs

Let's make sure that someone who is definitely not the owner can't increment the count:

contract OwnerUpOnlyTest is Test {
    OwnerUpOnly upOnly;

    // ...

    function testFail_IncrementAsNotOwner() public {
        vm.prank(address(0));
        upOnly.increment();
    }
}

If we run forge test now, we will see that all the test pass.

$ forge test
No files changed, compilation skipped

Running 2 tests for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest
[PASS] testFailIncrementAsNotOwner() (gas: 8413)
[PASS] testIncrementAsOwner() (gas: 29162)
Test result: ok. 2 passed; 0 failed; finished in 1.03ms

The test passed because the prank cheatcode changed our identity to the zero address for the next call (upOnly.increment()). The test case passed since we used the testFail prefix, however, using testFail is considered an anti-pattern since it does not tell us anything about why upOnly.increment() reverted.

If we run the tests again with traces turned on, we can see that we reverted with the correct error message.

$ forge test -vvvv --match-test testFail_IncrementAsNotOwner
No files changed, compilation skipped

Running 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest
[PASS] testFailIncrementAsNotOwner() (gas: 8413)
Traces:
  [8413] OwnerUpOnlyTest::testFailIncrementAsNotOwner() 
    ├─ [0] VM::prank(0x0000000000000000000000000000000000000000) 
    │   └─ ← ()
    ├─ [247] 0xce71…c246::increment() 
    │   └─ ← 0x82b42900
    └─ ← 0x82b42900

Test result: ok. 1 passed; 0 failed; finished in 2.01ms

To be sure in the future, let's make sure that we reverted because we are not the owner using the expectRevert cheatcode:

contract OwnerUpOnlyTest is Test {
    OwnerUpOnly upOnly;

    // ...

    // Notice that we replaced `testFail` with `test`
    function test_RevertWhen_CallerIsNotOwner() public {
        vm.expectRevert(Unauthorized.selector);
        vm.prank(address(0));
        upOnly.increment();
    }
}

If we run forge test one last time, we see that the test still passes, but this time we are sure that it will always fail if we revert for any other reason.

$ forge test
No files changed, compilation skipped

Running 2 tests for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest
[PASS] testIncrementAsNotOwner() (gas: 8739)
[PASS] testIncrementAsOwner() (gas: 29162)
Test result: ok. 2 passed; 0 failed; finished in 1.15ms

Another cheatcode that is perhaps not so intuitive is the expectEmit function. Before looking at expectEmit, we need to understand what an event is.

Events are inheritable members of contracts. When you emit an event, the arguments are stored on the blockchain. The indexed attribute can be added to a maximum of three parameters of an event to form a data structure known as a "topic." Topics allow users to search for events on the blockchain.

pragma solidity 0.8.10;

import "forge-std/Test.sol";

contract EmitContractTest is Test {
    event Transfer(address indexed from, address indexed to, uint256 amount);

    function test_ExpectEmit() public {
        ExpectEmit emitter = new ExpectEmit();
        // Check that topic 1, topic 2, and data are the same as the following emitted event.
        // Checking topic 3 here doesn't matter, because `Transfer` only has 2 indexed topics.
        vm.expectEmit(true, true, false, true);
        // The event we expect
        emit Transfer(address(this), address(1337), 1337);
        // The event we get
        emitter.t();
    }

    function test_ExpectEmit_DoNotCheckData() public {
        ExpectEmit emitter = new ExpectEmit();
        // Check topic 1 and topic 2, but do not check data
        vm.expectEmit(true, true, false, false);
        // The event we expect
        emit Transfer(address(this), address(1337), 1338);
        // The event we get
        emitter.t();
    }
}

contract ExpectEmit {
    event Transfer(address indexed from, address indexed to, uint256 amount);

    function t() public {
        emit Transfer(msg.sender, address(1337), 1337);
    }
}

When we call vm.expectEmit(true, true, false, true);, we want to check the 1st and 2nd indexed topic for the next event.

The expected Transfer event in test_ExpectEmit() means we are expecting that from is address(this), and to is address(1337). This is compared against the event emitted from emitter.t().

In other words, we are checking that the first topic from emitter.t() is equal to address(this). The 3rd argument in expectEmit is set to false because there is no need to check the third topic in the Transfer event, since there are only two. It does not matter even if we set to true.

The 4th argument in expectEmit is set to true, which means that we want to check "non-indexed topics", also known as data.

For example, we want the data from the expected event in test_ExpectEmit - which is amount - to equal to the data in the actual emitted event. In other words, we are asserting that amount emitted by emitter.t() is equal to 1337. If the fourth argument in expectEmit was set to false, we would not check amount.

In other words, test_ExpectEmit_DoNotCheckData is a valid test case, even though the amounts differ, since we do not check the data.

📚 Reference

See the Cheatcodes Reference for a complete overview of all the available cheatcodes.

Forge Standard Library Overview

Forge Standard Library (Forge Std for short) is a collection of helpful contracts that make writing tests easier, faster, and more user-friendly.

Using Forge Std is the preferred way of writing tests with Foundry.

It provides all the essential functionality you need to get started writing tests:

• Vm.sol: Up-to-date cheatcodes interface
• console.sol and console2.sol: Hardhat-style logging functionality
• Script.sol: Basic utilities for Solidity scripting
• Test.sol: A superset of DSTest containing standard libraries, a cheatcodes instance (vm), and Hardhat console

Simply import Test.sol and inherit from Test in your test contract:

import "forge-std/Test.sol";

contract ContractTest is Test { ...

Now, you can:

// Access Hevm via the `vm` instance
vm.startPrank(alice);

// Assert and log using Dappsys Test
assertEq(dai.balanceOf(alice), 10000e18);

// Log with the Hardhat `console` (`console2`)
console.log(alice.balance);

// Use anything from the Forge Std std-libraries
deal(address(dai), alice, 10000e18);

To import the Vm interface or the console library individually:

import "forge-std/Vm.sol";

import "forge-std/console.sol";

Note: console2.sol contains patches to console.sol that allows Forge to decode traces for calls to the console, but it is not compatible with Hardhat.

import "forge-std/console2.sol";

Standard libraries

Forge Std currently consists of six standard libraries.

Std Logs

Std Logs expand upon the logging events from the DSTest library.

Std Assertions

Std Assertions expand upon the assertion functions from the DSTest library.

Std Cheats

Std Cheats are wrappers around Forge cheatcodes that make them safer to use and improve the DX.

You can access Std Cheats by simply calling them inside your test contract, as you would any other internal function:

// set up a prank as Alice with 100 ETH balance
hoax(alice, 100 ether);

Std Errors

Std Errors provide wrappers around common internal Solidity errors and reverts.

Std Errors are most useful in combination with the expectRevert cheatcode, as you do not need to remember the internal Solidity panic codes yourself. Note that you have to access them through stdError, as this is a library.

// expect an arithmetic error on the next call (e.g. underflow)
vm.expectRevert(stdError.arithmeticError);

Std Storage

Std Storage makes manipulating contract storage easy. It can find and write to the storage slot(s) associated with a particular variable.

The Test contract already provides a StdStorage instance stdstore through which you can access any std-storage functionality. Note that you must add using stdStorage for StdStorage in your test contract first.

// find the variable `score` in the contract `game`
// and change its value to 10
stdstore
    .target(address(game))
    .sig(game.score.selector)
    .checked_write(10);

Std Math

Std Math is a library with useful mathematical functions that are not provided in Solidity.

Note that you have to access them through stdMath, as this is a library.

// get the absolute value of -10
uint256 ten = stdMath.abs(-10)

📚 Reference

See the Forge Standard Library Reference for a complete overview of Forge Standard Library.

Understanding Traces

Forge can produce traces either for failing tests (-vvv) or all tests (-vvvv).

Traces follow the same general format:

  [<Gas Usage>] <Contract>::<Function>(<Parameters>)
    ├─ [<Gas Usage>] <Contract>::<Function>(<Parameters>)
    │   └─ ← <Return Value>
    └─ ← <Return Value>

Each trace can have many more subtraces, each denoting a call to a contract and a return value.

If your terminal supports color, the traces will also come with a variety of colors:

• Green: For calls that do not revert
• Red: For reverting calls
• Blue: For calls to cheat codes
• Cyan: For emitted logs
• Yellow: For contract deployments

The gas usage (marked in square brackets) is for the entirety of the function call. You may notice, however, that sometimes the gas usage of one trace does not exactly match the gas usage of all its subtraces:

  [24661] OwnerUpOnlyTest::testIncrementAsOwner()
    ├─ [2262] OwnerUpOnly::count()
    │   └─ ← 0
    ├─ [20398] OwnerUpOnly::increment()
    │   └─ ← ()
    ├─ [262] OwnerUpOnly::count()
    │   └─ ← 1
    └─ ← ()

The gas unaccounted for is due to some extra operations happening between calls, such as arithmetic and store reads/writes.

Forge will try to decode as many signatures and values as possible, but sometimes this is not possible. In these cases, the traces will appear like so:

  [<Gas Usage>] <Address>::<Calldata>
    └─ ← <Return Data>

Fork Testing

Forge supports testing in a forked environment with two different approaches:

• Forking Mode — use a single fork for all your tests via the forge test --fork-url flag
• Forking Cheatcodes — create, select, and manage multiple forks directly in Solidity test code via forking cheatcodes

Which approach to use? Forking mode affords running an entire test suite against a specific forked environment, while forking cheatcodes provide more flexibility and expressiveness to work with multiple forks in your tests. Your particular use case and testing strategy will help inform which approach to use.

Forking Mode

To run all tests in a forked environment, such as a forked Ethereum mainnet, pass an RPC URL via the --fork-url flag:

forge test --fork-url <your_rpc_url>

The following values are changed to reflect those of the chain at the moment of forking:

• block_number
• chain_id
• gas_limit
• gas_price
• block_base_fee_per_gas
• block_coinbase
• block_timestamp
• block_difficulty

It is possible to specify a block from which to fork with --fork-block-number:

forge test --fork-url <your_rpc_url> --fork-block-number 1

Forking is especially useful when you need to interact with existing contracts. You may choose to do integration testing this way, as if you were on an actual network.

Caching

If both --fork-url and --fork-block-number are specified, then data for that block is cached for future test runs.

The data is cached in ~/.foundry/cache/rpc/<chain name>/<block number>. To clear the cache, simply remove the directory or run forge clean (removes all build artifacts and cache directories).

It is also possible to ignore the cache entirely by passing --no-storage-caching, or with foundry.toml by configuring no_storage_caching and rpc_storage_caching.

Improved traces

Forge supports identifying contracts in a forked environment with Etherscan.

To use this feature, pass the Etherscan API key via the --etherscan-api-key flag:

forge test --fork-url <your_rpc_url> --etherscan-api-key <your_etherscan_api_key>

Alternatively, you can set the ETHERSCAN_API_KEY environment variable.

Forking Cheatcodes

Forking cheatcodes allow you to enter forking mode programatically in your Solidity test code. Instead of configuring forking mode via forge CLI arguments, these cheatcodes allow you to use forking mode on a test-by-test basis and work with multiple forks in your tests. Each fork is identified via its own unique uint256 identifier.

Usage

Important to keep in mind that all test functions are isolated, meaning each test function is executed with a copy of the state after setUp and is executed in its own stand-alone EVM.

Therefore forks created during setUp are available in tests. The code example below uses createFork to create two forks, but does not select one initially. Each fork is identified with a unique identifier (uint256 forkId), which is assigned when it is first created.

Enabling a specific fork is done via passing that forkId to selectFork.

createSelectFork is a one-liner for createFork plus selectFork.

There can only be one fork active at a time, and the identifier for the currently active fork can be retrieved via activeFork.

Similar to roll, you can set block.number of a fork with rollFork.

To understand what happens when a fork is selected, it is important to know how the forking mode works in general:

Each fork is a standalone EVM, i.e. all forks use completely independent storage. The only exception is the state of the msg.sender and the test contract itself, which are persistent across fork swaps. In other words all changes that are made while fork A is active (selectFork(A)) are only recorded in fork A's storage and are not available if another fork is selected. However, changes recorded in the test contract itself (variables) are still available because the test contract is a persistent account.

The selectFork cheatcode sets the remote section with the fork's data source, however the local memory remains persistent across fork swaps. This also means selectFork can be called at all times with any fork, to set the remote data source. However, it is important to keep in mind the above rules for read/write access always apply, meaning writes are persistent across fork swaps.

Examples

Create and Select Forks

contract ForkTest is Test {
    // the identifiers of the forks
    uint256 mainnetFork;
    uint256 optimismFork;
    
    //Access variables from .env file via vm.envString("varname")
    //Replace ALCHEMY_KEY by your alchemy key or Etherscan key, change RPC url if need
    //inside your .env file e.g: 
    //MAINNET_RPC_URL = 'https://eth-mainnet.g.alchemy.com/v2/ALCHEMY_KEY'
    //string MAINNET_RPC_URL = vm.envString("MAINNET_RPC_URL");
    //string OPTIMISM_RPC_URL = vm.envString("OPTIMISM_RPC_URL");

    // create two _different_ forks during setup
    function setUp() public {
        mainnetFork = vm.createFork(MAINNET_RPC_URL);
        optimismFork = vm.createFork(OPTIMISM_RPC_URL);
    }

    // demonstrate fork ids are unique
    function testForkIdDiffer() public {
        assert(mainnetFork != optimismFork);
    }

    // select a specific fork
    function testCanSelectFork() public {
        // select the fork
        vm.selectFork(mainnetFork);
        assertEq(vm.activeFork(), mainnetFork);

        // from here on data is fetched from the `mainnetFork` if the EVM requests it and written to the storage of `mainnetFork`
    }

    // manage multiple forks in the same test
    function testCanSwitchForks() public {
        vm.selectFork(mainnetFork);
        assertEq(vm.activeFork(), mainnetFork);

        vm.selectFork(optimismFork);
        assertEq(vm.activeFork(), optimismFork);
    }

    // forks can be created at all times
    function testCanCreateAndSelectForkInOneStep() public {
        // creates a new fork and also selects it
        uint256 anotherFork = vm.createSelectFork(MAINNET_RPC_URL);
        assertEq(vm.activeFork(), anotherFork);
    }

    // set `block.number` of a fork
    function testCanSetForkBlockNumber() public {
        vm.selectFork(mainnetFork);
        vm.rollFork(1_337_000);

        assertEq(block.number, 1_337_000);
    }
}

Separated and persistent storage

As mentioned each fork is essentially an independent EVM with separated storage.

Only the accounts of msg.sender and the test contract (ForkTest) are persistent when forks are selected. But any account can be turned into a persistent account: makePersistent.

An account that is persistent is unique, i.e. it exists on all forks

contract ForkTest is Test {
    // the identifiers of the forks
    uint256 mainnetFork;
    uint256 optimismFork;
    
    //Access variables from .env file via vm.envString("varname")
    //Replace ALCHEMY_KEY by your alchemy key or Etherscan key, change RPC url if need
    //inside your .env file e.g: 
    //MAINNET_RPC_URL = 'https://eth-mainnet.g.alchemy.com/v2/ALCHEMY_KEY'
    //string MAINNET_RPC_URL = vm.envString("MAINNET_RPC_URL");
    //string OPTIMISM_RPC_URL = vm.envString("OPTIMISM_RPC_URL");

    // create two _different_ forks during setup
    function setUp() public {
        mainnetFork = vm.createFork(MAINNET_RPC_URL);
        optimismFork = vm.createFork(OPTIMISM_RPC_URL);
    }

    // creates a new contract while a fork is active
    function testCreateContract() public {
        vm.selectFork(mainnetFork);
        assertEq(vm.activeFork(), mainnetFork);
        
        // the new contract is written to `mainnetFork`'s storage
        SimpleStorageContract simple = new SimpleStorageContract();
        
        // and can be used as normal
        simple.set(100);
        assertEq(simple.value(), 100);
        
        // after switching to another contract we still know `address(simple)` but the contract only lives in `mainnetFork` 
        vm.selectFork(optimismFork);
        
        /* this call will therefore revert because `simple` now points to a contract that does not exist on the active fork
        * it will produce following revert message:
        * 
        * "Contract 0xCe71065D4017F316EC606Fe4422e11eB2c47c246 does not exist on active fork with id `1`
        *       But exists on non active forks: `[0]`"
        */
        simple.value();
    }
    
     // creates a new _persistent_ contract while a fork is active
     function testCreatePersistentContract() public {
        vm.selectFork(mainnetFork);
        SimpleStorageContract simple = new SimpleStorageContract();
        simple.set(100);
        assertEq(simple.value(), 100);
        
        // mark the contract as persistent so it is also available when other forks are active
        vm.makePersistent(address(simple));
        assert(vm.isPersistent(address(simple))); 
        
        vm.selectFork(optimismFork);
        assert(vm.isPersistent(address(simple))); 
        
        // This will succeed because the contract is now also available on the `optimismFork`
        assertEq(simple.value(), 100);
     }
}

contract SimpleStorageContract {
    uint256 public value;

    function set(uint256 _value) public {
        value = _value;
    }
}

For more details and examples, see the forking cheatcodes reference.

Advanced Testing

Forge comes with a number of advanced testing methods:

• Fuzz Testing
• Invariant Testing
• Differential Testing

In the future, Forge will also support these:

• Symbolic Execution
• Mutation Testing

Each chapter dives into what problem the testing methods solve, and how to apply them to your own project.

Fuzz Testing

Forge supports property based testing.

Property-based testing is a way of testing general behaviors as opposed to isolated scenarios.

Let's examine what that means by writing a unit test, finding the general property we are testing for, and converting it to a property-based test instead:

pragma solidity 0.8.10;

import "forge-std/Test.sol";

contract Safe {
    receive() external payable {}

    function withdraw() external {
        payable(msg.sender).transfer(address(this).balance);
    }
}

contract SafeTest is Test {
    Safe safe;

    // Needed so the test contract itself can receive ether
    // when withdrawing
    receive() external payable {}

    function setUp() public {
        safe = new Safe();
    }

    function test_Withdraw() public {
        payable(address(safe)).transfer(1 ether);
        uint256 preBalance = address(this).balance;
        safe.withdraw();
        uint256 postBalance = address(this).balance;
        assertEq(preBalance + 1 ether, postBalance);
    }
}

Running the test, we see it passes:

$ forge test
Compiling 6 files with 0.8.10
Solc 0.8.10 finished in 3.78s
Compiler run successful

Running 1 test for test/Safe.t.sol:SafeTest
[PASS] testWithdraw() (gas: 19462)
Test result: ok. 1 passed; 0 failed; finished in 873.70µs

This unit test does test that we can withdraw ether from our safe. However, who is to say that it works for all amounts, not just 1 ether?

The general property here is: given a safe balance, when we withdraw, we should get whatever is in the safe.

Forge will run any test that takes at least one parameter as a property-based test, so let's rewrite:

contract SafeTest is Test {
    // ...

    function testFuzz_Withdraw(uint256 amount) public {
        payable(address(safe)).transfer(amount);
        uint256 preBalance = address(this).balance;
        safe.withdraw();
        uint256 postBalance = address(this).balance;
        assertEq(preBalance + amount, postBalance);
    }
}

If we run the test now, we can see that Forge runs the property-based test, but it fails for high values of amount:

$ forge test
Compiling 1 files with 0.8.10
Solc 0.8.10 finished in 1.69s
Compiler run successful

Running 1 test for test/Safe.t.sol:SafeTest
[FAIL. Reason: EvmError: Revert Counterexample: calldata=0x215a2f200000000000000000000000000000000000000001000000000000000000000000, args=[79228162514264337593543950336]] testWithdraw(uint256) (runs: 47, μ: 19554, ~: 19554)
Test result: FAILED. 0 passed; 1 failed; finished in 8.75ms

The default amount of ether that the test contract is given is 2**96 wei (as in DappTools), so we have to restrict the type of amount to uint96 to make sure we don't try to send more than we have:

    function testFuzz_Withdraw(uint96 amount) public {

And now it passes:

$ forge test
Compiling 1 files with 0.8.10
Solc 0.8.10 finished in 1.67s
Compiler run successful

Running 1 test for test/Safe.t.sol:SafeTest
[PASS] testWithdraw(uint96) (runs: 256, μ: 19078, ~: 19654)
Test result: ok. 1 passed; 0 failed; finished in 19.56ms

You may want to exclude certain cases using the assume cheatcode. In those cases, fuzzer will discard the inputs and start a new fuzz run:

function testFuzz_Withdraw(uint96 amount) public {
    vm.assume(amount > 0.1 ether);
    // snip
}

There are different ways to run property-based tests, notably parametric testing and fuzzing. Forge only supports fuzzing.

Interpreting results

You might have noticed that fuzz tests are summarized a bit differently compared to unit tests:

• "runs" refers to the amount of scenarios the fuzzer tested. By default, the fuzzer will generate 256 scenarios, but this and other test execution parameters can be setup by the user. Fuzzer configuration details are provided here.
• "μ" (Greek letter mu) is the mean gas used across all fuzz runs
• "~" (tilde) is the median gas used across all fuzz runs

Configuring fuzz test execution

Fuzz tests execution is governed by parameters that can be controlled by users via Forge configuration primitives. Configs can be applied globally or on a per-test basis. For details on this topic please refer to 📚 Global config and 📚 In-line config.

Invariant Testing

Overview

Invariant testing allows for a set of invariant expressions to be tested against randomized sequences of pre-defined function calls from pre-defined contracts. After each function call is performed, all defined invariants are asserted.

Invariant testing is a powerful tool to expose incorrect logic in protocols. Due to the fact that function call sequences are randomized and have fuzzed inputs, invariant testing can expose false assumptions and incorrect logic in edge cases and highly complex protocol states.

Invariant testing campaigns have two dimensions, runs and depth:

• runs: Number of times that a sequence of function calls is generated and run.
• depth: Number of function calls made in a given run. All defined invariants are asserted after each function call is made. If a function call reverts, the depth counter still increments.

These and other invariant configuration aspects are explained here.

Similar to how standard tests are run in Foundry by prefixing a function name with test, invariant tests are denoted by prefixing the function name with invariant (e.g., function invariant_A()).

Configuring invariant test execution

Invariant tests execution is governed by parameters that can be controlled by users via Forge configuration primitives. Configs can be applied globally or on a per-test basis. For details on this topic please refer to 📚 Global config and 📚 In-line config.

Defining Invariants

Invariants are conditions expressions that should always hold true over the course of a fuzzing campaign. A good invariant testing suite should have as many invariants as possible, and can have different testing suites for different protocol states.

Examples of invariants are:

• "The xy=k formula always holds" for Uniswap
• "The sum of all user balances is equal to the total supply" for an ERC-20 token.

There are different ways to assert invariants, as outlined in the table below:

assertGe(
    token.totalAssets(),
    token.totalSupply()
)

assertEq(
    token.totalSupply(),
    sumBalanceOf
)

assertEq(
    pool.outstandingInterest(),
    test.naiveInterest()
)

Conditional Invariants

Invariants must hold over the course of a given fuzzing campaign, but that doesn't mean they must hold true in every situation. There is the possibility for certain invariants to be introduced/removed in a given scenario (e.g., during a liquidation).

It is not recommended to introduce conditional logic into invariant assertions because they have the possibility of introducing false positives because of an incorrect code path. For example:

function invariant_example() external {
    if (protocolCondition) return;

    assertEq(val1, val2);
}

In this situation, if protocolCondition == true, the invariant is not asserted at all. Sometimes this can be desired behavior, but it can cause issues if the protocolCondition is true for the whole fuzzing campaign unexpectedly, or there is a logic error in the condition itself. For this reason its better to try and define an alternative invariant for that condition as well, for example:

function invariant_example() external {
    if (protocolCondition) {
        assertLe(val1, val2);
        return;
    };

    assertEq(val1, val2);
}

Another approach to handle different invariants across protocol states is to utilize dedicated invariant testing contracts for different scenarios. These scenarios can be bootstrapped using the setUp function, but it is more powerful to leverage invariant targets to govern the fuzzer to behave in a way that will only yield certain results (e.g., avoid liquidations).

Invariant Targets

Target Contracts: The set of contracts that will be called over the course of a given invariant test fuzzing campaign. This set of contracts defaults to all contracts that were deployed in the setUp function, but can be customized to allow for more advanced invariant testing.

Target Senders: The invariant test fuzzer picks values for msg.sender at random when performing fuzz campaigns to simulate multiple actors in a system by default. If desired, the set of senders can be customized in the setUp function.

Target Selectors: The set of function selectors that are used by the fuzzer for invariant testing. These can be used to use a subset of functions within a given target contract.

Target Artifacts: The desired ABI to be used for a given contract. These can be used for proxy contract configurations.

Target Artifact Selectors: The desired subset of function selectors to be used within a given ABI to be used for a given contract. These can be used for proxy contract configurations.

Priorities for the invariant fuzzer in the cases of target clashes are:

targetSelectors | targetArtifactSelectors > excludeContracts | excludeArtifacts > targetContracts | targetArtifacts

Function Call Probability Distribution

Functions from these contracts will be called at random with fuzzed inputs. The probability of a function being called is broken down by contract and then by function.

For example:

targetContract1: 50%
├─ function1: 50% (25%)
└─ function2: 50% (25%)

targetContract2: 50%
├─ function1: 25% (12.5%)
├─ function2: 25% (12.5%)
├─ function3: 25% (12.5%)
└─ function4: 25% (12.5%)

This is something to be mindful of when designing target contracts, as target contracts with less functions will have each function called more often due to this probability distribution.

Invariant Test Helper Functions

Invariant test helper functions are included in forge-std to allow for configurable invariant test setup. The helper functions are outlined below:

Target Contract Setup

Target contracts can be set up using the following three methods:

1. Contracts that are manually added to the targetContracts array are added to the set of target contracts.
2. Contracts that are deployed in the setUp function are automatically added to the set of target contracts (only works if no contracts have been manually added using option 1).
3. Contracts that are deployed in the setUp can be removed from the target contracts if they are added to the excludeContracts array.

Open Testing

The default configuration for target contracts is set to all contracts that are deployed during the setup. For smaller modules and more arithmetic contracts, this works well. For example:

contract ExampleContract1 {

    uint256 public val1;
    uint256 public val2;
    uint256 public val3;

    function addToA(uint256 amount) external {
        val1 += amount;
        val3 += amount;
    }

    function addToB(uint256 amount) external {
        val2 += amount;
        val3 += amount;
    }

}

This contract could be deployed and tested using the default target contract pattern:

contract InvariantExample1 is Test {

    ExampleContract1 foo;

    function setUp() external {
        foo = new ExampleContract1();
    }

    function invariant_A() external {
        assertEq(foo.val1() + foo.val2(), foo.val3());
    }

    function invariant_B() external {
        assertGe(foo.val1() + foo.val2(), foo.val1());
    }

}

This setup will call foo.addToA() and foo.addToB() with a 50%-50% probability distribution with fuzzed inputs. Inevitably, the inputs will start to cause overflows and the function calls will start reverting. Since the default configuration in invariant testing is fail_on_revert = false, this will not cause the tests to fail. The invariants will hold throughout the rest of the fuzzing campaign and the result is that the test will pass. The output will look something like this:

[PASS] invariant_A() (runs: 50, calls: 10000, reverts: 5533)
[PASS] invariant_B() (runs: 50, calls: 10000, reverts: 5533)

Handler-Based Testing

For more complex and integrated protocols, more sophisticated target contract usage is required to achieve the desired results. To illustrate how Handlers can be leveraged, the following contract will be used (an ERC-4626 based contract that accepts deposits of another ERC-20 token):

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.17;

interface IERC20Like {

    function balanceOf(address owner_) external view returns (uint256 balance_);

    function transferFrom(
        address owner_,
        address recipient_,
        uint256 amount_
    ) external returns (bool success_);

}

contract Basic4626Deposit {

    /**********************************************************************************************/
    /*** Storage                                                                                ***/
    /**********************************************************************************************/

    address public immutable asset;

    string public name;
    string public symbol;

    uint8 public immutable decimals;

    uint256 public totalSupply;

    mapping(address => uint256) public balanceOf;

    /**********************************************************************************************/
    /*** Constructor                                                                            ***/
    /**********************************************************************************************/

    constructor(address asset_, string memory name_, string memory symbol_, uint8 decimals_) {
        asset    = asset_;
        name     = name_;
        symbol   = symbol_;
        decimals = decimals_;
    }

    /**********************************************************************************************/
    /*** External Functions                                                                     ***/
    /**********************************************************************************************/

    function deposit(uint256 assets_, address receiver_) external returns (uint256 shares_) {
        shares_ = convertToShares(assets_);

        require(receiver_ != address(0), "ZERO_RECEIVER");
        require(shares_   != uint256(0), "ZERO_SHARES");
        require(assets_   != uint256(0), "ZERO_ASSETS");

        totalSupply += shares_;

        // Cannot overflow because totalSupply would first overflow in the statement above.
        unchecked { balanceOf[receiver_] += shares_; }

        require(
            IERC20Like(asset).transferFrom(msg.sender, address(this), assets_),
            "TRANSFER_FROM"
        );
    }

    function transfer(address recipient_, uint256 amount_) external returns (bool success_) {
        balanceOf[msg.sender] -= amount_;

        // Cannot overflow because minting prevents overflow of totalSupply,
        // and sum of user balances == totalSupply.
        unchecked { balanceOf[recipient_] += amount_; }

        return true;
    }

    /**********************************************************************************************/
    /*** Public View Functions                                                                  ***/
    /**********************************************************************************************/

    function convertToShares(uint256 assets_) public view returns (uint256 shares_) {
        uint256 supply_ = totalSupply;  // Cache to stack.

        shares_ = supply_ == 0 ? assets_ : (assets_ * supply_) / totalAssets();
    }

    function totalAssets() public view returns (uint256 assets_) {
        assets_ = IERC20Like(asset).balanceOf(address(this));
    }

}

Handler Functions

This contract's deposit function requires that the caller has a non-zero balance of the ERC-20 asset. In the Open invariant testing approach, deposit() and transfer() would be called with a 50-50% distribution, but they would revert on every call. This would cause the invariant tests to "pass", but in reality no state was manipulated in the desired contract at all. This is where target contracts can be leveraged. When a contract requires some additional logic in order to function properly, it can be added in a dedicated contract called a Handler.

function deposit(uint256 assets) public virtual {
    asset.mint(address(this), assets);

    asset.approve(address(token), assets);

    uint256 shares = token.deposit(assets, address(this));
}

This contract will provide the necessary setup before a function call is made in order to ensure it is successful.

Building on this concept, Handlers can be used to develop more sophisticated invariant tests. With Open invariant testing, the tests run as shown in the diagram below, with random sequences of function calls being made to the protocol contracts directly with fuzzed parameters. This will cause reverts for more complex systems as outlined above.

By manually adding all Handler contracts to the targetContracts array, all function calls made to protocol contracts can be made in a way that is governed by the Handler to ensure successful calls. This is outlined in the diagram below.

With this layer between the fuzzer and the protocol, more powerful testing can be achieved.

Handler Ghost Variables

Within Handlers, "ghost variables" can be tracked across multiple function calls to add additional information for invariant tests. A good example of this is summing all of the shares that each LP owns after depositing into the ERC-4626 token as shown above, and using that in the invariant (totalSupply == sumBalanceOf).

function deposit(uint256 assets) public virtual {
    asset.mint(address(this), assets);

    asset.approve(address(token), assets);

    uint256 shares = token.deposit(assets, address(this));

    sumBalanceOf += shares;
}

Function-Level Assertions

Another benefit is the ability to perform assertions on function calls as they are happening. An example is asserting the ERC-20 balance of the LP has decremented by assets during the deposit function call, as well as their LP token balance incrementing by shares. In this way, handler functions are similar to fuzz tests because they can take in fuzzed inputs, perform state changes, and assert before/after state.

function deposit(uint256 assets) public virtual {
    asset.mint(address(this), assets);

    asset.approve(address(token), assets);

    uint256 beforeBalance = asset.balanceOf(address(this));

    uint256 shares = token.deposit(assets, address(this));

    assertEq(asset.balanceOf(address(this)), beforeBalance - assets);

    sumBalanceOf += shares;
}

Bounded/Unbounded Functions

In addition, with Handlers, input parameters can be bounded to reasonable expected values such that fail_on_revert in foundry.toml can be set to true. This can be accomplished using the bound() helper function from forge-std. This ensures that every function call that is being made by the fuzzer must be successful against the protocol in order to get tests to pass. This is very useful for visibility and confidence that the protocol is being tested in the desired way.

function deposit(uint256 assets) external {
    assets = bound(assets, 0, 1e30);

    asset.mint(address(this), assets);

    asset.approve(address(token), assets);

    uint256 beforeBalance = asset.balanceOf(address(this));

    uint256 shares = token.deposit(assets, address(this));

    assertEq(asset.balanceOf(address(this)), beforeBalance - assets);

    sumBalanceOf += shares;
}

This can also be accomplished by inheriting non-bounded functions from dedicated "unbounded" Handler contracts that can be used for fail_on_revert = false testing. This type of testing is also useful since it can expose issues in assumptions made with bound function usage.

// Unbounded
function deposit(uint256 assets) public virtual {
    asset.mint(address(this), assets);

    asset.approve(address(token), assets);

    uint256 beforeBalance = asset.balanceOf(address(this));

    uint256 shares = token.deposit(assets, address(this));

    assertEq(asset.balanceOf(address(this)), beforeBalance - assets);

    sumBalanceOf += shares;
}

// Bounded
function deposit(uint256 assets) external {
    assets = bound(assets, 0, 1e30);

    super.deposit(assets);
}

Actor Management

In the function calls above, it can be seen that address(this) is the sole depositor in the ERC-4626 contract, which is not a realistic representation of its intended use. By leveraging the prank cheatcodes in forge-std, each Handler can manage a set of actors and use them to perform the same function call from different msg.sender addresses. This can be accomplished using the following modifier:

address[] public actors;

address internal currentActor;

modifier useActor(uint256 actorIndexSeed) {
    currentActor = actors[bound(actorIndexSeed, 0, actors.length - 1)];
    vm.startPrank(currentActor);
    _;
    vm.stopPrank();
}

Using multiple actors allows for more granular ghost variable usage as well. This is demonstrated in the functions below:

// Unbounded
function deposit(
    uint256 assets,
    uint256 actorIndexSeed
) public virtual useActor(actorIndexSeed) {
    asset.mint(currentActor, assets);

    asset.approve(address(token), assets);

    uint256 beforeBalance = asset.balanceOf(address(this));

    uint256 shares = token.deposit(assets, address(this));

    assertEq(asset.balanceOf(address(this)), beforeBalance - assets);

    sumBalanceOf += shares;

    sumDeposits[currentActor] += assets
}

// Bounded
function deposit(uint256 assets, uint256 actorIndexSeed) external {
    assets = bound(assets, 0, 1e30);

    super.deposit(assets, actorIndexSeed);
}

Differential Testing

Forge can be used for differential testing and differential fuzzing. You can even test against non-EVM executables using the ffi cheatcode.

Background

Differential testing cross references multiple implementations of the same function by comparing each one's output. Imagine we have a function specification F(X), and two implementations of that specification: f1(X) and f2(X). We expect f1(x) == f2(x) for all x that exist in an appropriate input space. If f1(x) != f2(x), we know that at least one function is incorrectly implementing F(X). This process of testing for equality and identifying discrepancies is the core of differential testing.

Differential fuzzing is an extension of differential testing. Differential fuzzing programatically generates many values of x to find discrepancies and edge cases that manually chosen inputs might not reveal.

Note: the == operator in this case can be a custom definition of equality. For example, if testing floating point implementations, you might use approximate equality with a certain tolerance.

Some real life uses of this type of testing include:

• Comparing upgraded implementations to their predecessors
• Testing code against known reference implementations
• Confirming compatibility with third party tools and dependencies

Below are some examples of how Forge is used for differential testing.

Primer: The ffi cheatcode

ffi allows you to execute an arbitrary shell command and capture the output. Here's a mock example:

import "forge-std/Test.sol";

contract TestContract is Test {

    function testMyFFI () public {
        string[] memory cmds = new string[](2);
        cmds[0] = "cat";
        cmds[1] = "address.txt"; // assume contains abi-encoded address.
        bytes memory result = vm.ffi(cmds);
        address loadedAddress = abi.decode(result, (address));
        // Do something with the address
        // ...
    }
}

An address has previously been written to address.txt, and we read it in using the FFI cheatcode. This data can now be used throughout your test contract.

Example: Differential Testing Merkle Tree Implementations

Merkle Trees are a cryptographic commitment scheme frequently used in blockchain applications. Their popularity has led to a number of different implementations of Merkle Tree generators, provers, and verifiers. Merkle roots and proofs are often generated using a language like JavaScript or Python, while proof verification usually occurs on-chain in Solidity.

Murky is a complete implementation of Merkle roots, proofs, and verification in Solidity. Its test suite includes differential tests against OpenZeppelin's Merkle proof library, as well as root generation tests against a reference JavaScript implementation. These tests are powered by Foundry's fuzzing and ffi capabilities.

Differential fuzzing against a reference TypeScript implementation

Using the ffi cheatcode, Murky tests its own Merkle root implementation against a TypeScript implementation using data provided by Forge's fuzzer:

function testMerkleRootMatchesJSImplementationFuzzed(bytes32[] memory leaves) public {
    vm.assume(leaves.length > 1);
    bytes memory packed = abi.encodePacked(leaves);
    string[] memory runJsInputs = new string[](8);

    // Build ffi command string
    runJsInputs[0] = 'npm';
    runJsInputs[1] = '--prefix';
    runJsInputs[2] = 'differential_testing/scripts/';
    runJsInputs[3] = '--silent';
    runJsInputs[4] = 'run';
    runJsInputs[5] = 'generate-root-cli';
    runJsInputs[6] = leaves.length.toString();
    runJsInputs[7] = packed.toHexString();

    // Run command and capture output
    bytes memory jsResult = vm.ffi(runJsInputs);
    bytes32 jsGeneratedRoot = abi.decode(jsResult, (bytes32));

    // Calculate root using Murky
    bytes32 murkyGeneratedRoot = m.getRoot(leaves);
    assertEq(murkyGeneratedRoot, jsGeneratedRoot);
}

Note: see Strings2.sol in the Murky Repo for the library that enables (bytes memory).toHexString()

Forge runs npm --prefix differential_testing/scripts/ --silent run generate-root-cli {numLeaves} {hexEncodedLeaves}. This calculates the Merkle root for the input data using the reference JavaScript implementation. The script prints the root to stdout, and that printout is captured as bytes in the return value of vm.ffi().

The test then calculates the root using the Solidity implementation.

Finally, the test asserts that the both roots are exactly equal. If they are not equal, the test fails.

Differential fuzzing against OpenZeppelin's Merkle Proof Library

You may want to use differential testing against another Solidity implementation. In that case, ffi is not needed. Instead, the reference implementation is imported directly into the test.

import "openzeppelin-contracts/contracts/utils/cryptography/MerkleProof.sol";
//...
function testCompatabilityOpenZeppelinProver(bytes32[] memory _data, uint256 node) public {
    vm.assume(_data.length > 1);
    vm.assume(node < _data.length);
    bytes32 root = m.getRoot(_data);
    bytes32[] memory proof = m.getProof(_data, node);
    bytes32 valueToProve = _data[node];
    bool murkyVerified = m.verifyProof(root, proof, valueToProve);
    bool ozVerified = MerkleProof.verify(proof, root, valueToProve);
    assertTrue(murkyVerified == ozVerified);
}

Differential testing against a known edge case

Differential tests are not always fuzzed -- they are also useful for testing known edge cases. In the case of the Murky codebase, the initial implementation of the log2ceil function did not work for certain arrays whose lengths were close to a power of 2 (like 129). As a safety check, a test is always run against an array of this length and compared to the TypeScript implementation. You can see the full test here.

Standardized Testing against reference data

FFI is also useful for injecting reproducible, standardized data into the testing environment. In the Murky library, this is used as a benchmark for gas snapshotting (see forge snapshot).

bytes32[100] data;
uint256[8] leaves = [4, 8, 15, 16, 23, 42, 69, 88];

function setUp() public {
    string[] memory inputs = new string[](2);
    inputs[0] = "cat";
    inputs[1] = "src/test/standard_data/StandardInput.txt";
    bytes memory result =  vm.ffi(inputs);
    data = abi.decode(result, (bytes32[100]));
    m = new Merkle();
}

function testMerkleGenerateProofStandard() public view {
    bytes32[] memory _data = _getData();
    for (uint i = 0; i < leaves.length; ++i) {
        m.getProof(_data, leaves[i]);
    }
}

src/test/standard_data/StandardInput.txt is a text file that contains an encoded bytes32[100] array. It's generated outside of the test and can be used in any language's Web3 SDK. It looks something like:

0xf910ccaa307836354233316666386231414464306335333243453944383735313..423532

The standardized testing contract reads in the file using ffi. It decodes the data into an array and then, in this example, generates proofs for 8 different leaves. Because the data is constant and standard, we can meaningfully measure gas and performance improvements using this test.

Of course, one could just hardcode the array into the test! But that makes it much harder to do consistent testing across contracts, implementations, etc.

Example: Differential Testing Gradual Dutch Auctions

The reference implementation for Paradigm's Gradual Dutch Auction mechanism contains a number of differential, fuzzed tests. It is an excellent repository to further explore differential testing using ffi.

• Differential tests for Discrete GDAs
• Differential tests for Continuous GDAs
• Reference Python implementation

Reference Repositories

• Gradual Dutch Auctions
• Murky
• Solidity Fuzzing Template

If you have another repository that would serve as a reference, please contribute it!

Overview of Forge

Forge is a command-line tool that ships with Foundry. Forge tests, builds, and deploys your smart contracts.

Deploying

Forge can deploy smart contracts to a given network with the forge create command.

Forge can deploy only one contract at a time.

To deploy a contract, you must provide a RPC URL (env: ETH_RPC_URL) and the private key of the account that will deploy the contract.

To deploy MyContract to a network:

$ forge create --rpc-url <your_rpc_url> --private-key <your_private_key> src/MyContract.sol:MyContract
compiling...
success.
Deployer: 0xa735b3c25f...
Deployed to: 0x4054415432...
Transaction hash: 0x6b4e0ff93a...

Solidity files may contain multiple contracts. :MyContract above specifies which contract to deploy from the src/MyContract.sol file.

Use the --constructor-args flag to pass arguments to the constructor:

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

import {ERC20} from "solmate/tokens/ERC20.sol";

contract MyToken is ERC20 {
    constructor(
        string memory name,
        string memory symbol,
        uint8 decimals,
        uint256 initialSupply
    ) ERC20(name, symbol, decimals) {
        _mint(msg.sender, initialSupply);
    }
}

Additionally, we can tell Forge to verify our contract on Etherscan, Sourcify or Blockscout, if the network is supported, by passing --verify.

$ forge create --rpc-url <your_rpc_url> \
    --constructor-args "ForgeUSD" "FUSD" 18 1000000000000000000000 \
    --private-key <your_private_key> \
    --etherscan-api-key <your_etherscan_api_key> \
    --verify \
    src/MyToken.sol:MyToken

Verifying a pre-existing contract

It is recommended to use the --verify flag with forge create to automatically verify the contract on explorer after a deployment. Note that for Etherscan ETHERSCAN_API_KEY must be set.

If you are verifying an already deployed contract, read on.

You can verify a contract on Etherscan, Sourcify or Blockscout with the forge verify-contract command.

You must provide:

• the contract address
• the contract name or the path to the contract <path>:<contractname>
• your Etherscan API key (env: ETHERSCAN_API_KEY) (if verifying on Etherscan).

Moreover, you may need to provide:

• the constructor arguments in the ABI-encoded format, if there are any
• compiler version used for build, with 8 hex digits from the commit version prefix (the commit will usually not be a nightly build). It is auto-detected if not specified.
• the number of optimizations, if the Solidity optimizer was activated. It is auto-detected if not specified.
• the chain ID, if the contract is not on Ethereum Mainnet

Let's say you want to verify MyToken (see above). You set the number of optimizations to 1 million, compiled it with v0.8.10, and deployed it, as shown above, to the Sepolia testnet (chain ID: 11155111). Note that --num-of-optimizations will default to 0 if not set on verification, while it defaults to 200 if not set on deployment, so make sure you pass --num-of-optimizations 200 if you left the default compilation settings.

Here's how to verify it:

forge verify-contract \
    --chain-id 11155111 \
    --num-of-optimizations 1000000 \
    --watch \
    --constructor-args $(cast abi-encode "constructor(string,string,uint256,uint256)" "ForgeUSD" "FUSD" 18 1000000000000000000000) \
    --etherscan-api-key <your_etherscan_api_key> \
    --compiler-version v0.8.10+commit.fc410830 \
    <the_contract_address> \
    src/MyToken.sol:MyToken 

Submitted contract for verification:
                Response: `OK`
                GUID: `a6yrbjp5prvakia6bqp5qdacczyfhkyi5j1r6qbds1js41ak1a`
                url: https://sepolia.etherscan.io//address/0x6a54…3a4c#code

It is recommended to use the --watch flag along with verify-contract command in order to poll for the verification result.

If the --watch flag was not supplied, you can check the verification status with the forge verify-check command:

$ forge verify-check --chain-id 11155111 <GUID> <your_etherscan_api_key>
Contract successfully verified.

💡 Tip

Use Cast's abi-encode to ABI-encode arguments.

In this example, we ran cast abi-encode "constructor(string,string,uint8,uint256)" "ForgeUSD" "FUSD" 18 1000000000000000000000 to ABI-encode the arguments.

Troubleshooting

Invalid character 'x' at position 1

Make sure the private key string does not begin with 0x.

EIP-1559 not activated

EIP-1559 is not supported or not activated on the RPC server. Pass the --legacy flag to use legacy transactions instead of the EIP-1559 ones. If you do development in a local environment, you can use Hardhat instead of Ganache.

Failed to parse tokens

Make sure the passed arguments are of correct type.

Signature error

Make sure the private key is correct.

Compiler version commit for verify

If you want to check the exact commit you are running locally, try: ~/.svm/0.x.y/solc-0.x.y --version where x and y are major and minor version numbers respectively. The output of this will be something like:

solc, the solidity compiler commandline interface
Version: 0.8.12+commit.f00d7308.Darwin.appleclang

Note: You cannot just paste the entire string "0.8.12+commit.f00d7308.Darwin.appleclang" as the argument for the compiler-version. But you can use the 8 hex digits of the commit to look up exactly what you should copy and paste from compiler version.

Known Issues

Verifying Contracts With Ambiguous Import Paths

Forge passes source directories (src, lib, test etc) as --include-path arguments to the compiler. This means that given the following project tree

|- src
|-- folder
|--- Contract.sol
|--- IContract.sol

it is possible to import IContract inside the Contract.sol using folder/IContract.sol import path.

Etherscan is not able to recompile such sources. Consider changing the imports to use relative import path.

Verifying Contracts With No Bytecode Hash

Currently, it's not possible to verify contracts on Etherscan with bytecode_hash set to none. Click here to learn more about how metadata hash is used for source code verification.

Gas Tracking

Forge can help you estimate how much gas your contract will consume.

Currently, Forge ships with two different tools for this job, but they may be merged in the future:

• Gas reports: Gas reports give you an overview of how much Forge thinks the individual functions in your contracts will consume in gas.
• Gas snapshots: Gas snapshots give you an overview of how much each test consumes in gas.

Gas reports and gas snapshots differ in some ways:

• Gas reports use tracing to figure out gas costs for individual contract calls.
  This gives more granular insight, at the cost of speed.
• Gas snapshots have more built-in tools, such as diffs and exporting the results to a file.
  Snapshots are not as granular as gas reports, but they are faster to generate.

Gas Reports

Forge can produce gas reports for your contracts. You can configure which contracts output gas reports via the gas_reports field in foundry.toml.

To produce reports for specific contracts:

gas_reports = ["MyContract", "MyContractFactory"]

To produce reports for all contracts:

gas_reports = ["*"]

To generate gas reports, run forge test --gas-report.

You can also use it in combination with other subcommands, such as forge test --match-test testBurn --gas-report, to generate only a gas report relevant to this test.

Example output:

╭───────────────────────┬─────────────────┬────────┬────────┬────────┬─────────╮
│ MockERC1155 contract  ┆                 ┆        ┆        ┆        ┆         │
╞═══════════════════════╪═════════════════╪════════╪════════╪════════╪═════════╡
│ Deployment Cost       ┆ Deployment Size ┆        ┆        ┆        ┆         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ 1082720               ┆ 5440            ┆        ┆        ┆        ┆         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Function Name         ┆ min             ┆ avg    ┆ median ┆ max    ┆ # calls │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ balanceOf             ┆ 596             ┆ 596    ┆ 596    ┆ 596    ┆ 44      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ balanceOfBatch        ┆ 2363            ┆ 4005   ┆ 4005   ┆ 5647   ┆ 2       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ batchBurn             ┆ 2126            ┆ 5560   ┆ 2584   ┆ 11970  ┆ 3       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ batchMint             ┆ 2444            ┆ 135299 ┆ 125081 ┆ 438531 ┆ 18      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ burn                  ┆ 814             ┆ 2117   ┆ 2117   ┆ 3421   ┆ 2       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ isApprovedForAll      ┆ 749             ┆ 749    ┆ 749    ┆ 749    ┆ 1       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ mint                  ┆ 26039           ┆ 31943  ┆ 27685  ┆ 118859 ┆ 22      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ safeBatchTransferFrom ┆ 2561            ┆ 137750 ┆ 126910 ┆ 461304 ┆ 8       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ safeTransferFrom      ┆ 1335            ┆ 34505  ┆ 28103  ┆ 139557 ┆ 9       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ setApprovalForAll     ┆ 24485           ┆ 24485  ┆ 24485  ┆ 24485  ┆ 12      │
╰───────────────────────┴─────────────────┴────────┴────────┴────────┴─────────╯

╭───────────────────────┬─────────────────┬────────┬────────┬────────┬─────────╮
│ Example contract      ┆                 ┆        ┆        ┆        ┆         │
╞═══════════════════════╪═════════════════╪════════╪════════╪════════╪═════════╡
│ Deployment Cost       ┆ Deployment Size ┆        ┆        ┆        ┆         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ 1082720               ┆ 5440            ┆        ┆        ┆        ┆         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Function Name         ┆ min             ┆ avg    ┆ median ┆ max    ┆ # calls │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ foo                   ┆ 596             ┆ 596    ┆ 596    ┆ 596    ┆ 44      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ bar                   ┆ 2363            ┆ 4005   ┆ 4005   ┆ 5647   ┆ 2       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ baz                   ┆ 2126            ┆ 5560   ┆ 2584   ┆ 11970  ┆ 3       │
╰───────────────────────┴─────────────────┴────────┴────────┴────────┴─────────╯

You can also ignore contracts via the gas_reports_ignore field in foundry.toml:

gas_reports_ignore = ["Example"]

This would change the output to:

╭───────────────────────┬─────────────────┬────────┬────────┬────────┬─────────╮
│ MockERC1155 contract  ┆                 ┆        ┆        ┆        ┆         │
╞═══════════════════════╪═════════════════╪════════╪════════╪════════╪═════════╡
│ Deployment Cost       ┆ Deployment Size ┆        ┆        ┆        ┆         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ 1082720               ┆ 5440            ┆        ┆        ┆        ┆         │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Function Name         ┆ min             ┆ avg    ┆ median ┆ max    ┆ # calls │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ balanceOf             ┆ 596             ┆ 596    ┆ 596    ┆ 596    ┆ 44      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ balanceOfBatch        ┆ 2363            ┆ 4005   ┆ 4005   ┆ 5647   ┆ 2       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ batchBurn             ┆ 2126            ┆ 5560   ┆ 2584   ┆ 11970  ┆ 3       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ batchMint             ┆ 2444            ┆ 135299 ┆ 125081 ┆ 438531 ┆ 18      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ burn                  ┆ 814             ┆ 2117   ┆ 2117   ┆ 3421   ┆ 2       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ isApprovedForAll      ┆ 749             ┆ 749    ┆ 749    ┆ 749    ┆ 1       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ mint                  ┆ 26039           ┆ 31943  ┆ 27685  ┆ 118859 ┆ 22      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ safeBatchTransferFrom ┆ 2561            ┆ 137750 ┆ 126910 ┆ 461304 ┆ 8       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ safeTransferFrom      ┆ 1335            ┆ 34505  ┆ 28103  ┆ 139557 ┆ 9       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ setApprovalForAll     ┆ 24485           ┆ 24485  ┆ 24485  ┆ 24485  ┆ 12      │
╰───────────────────────┴─────────────────┴────────┴────────┴────────┴─────────╯

Gas Snapshots

Forge can generate gas snapshots for all your test functions. This can be useful to get a general feel for how much gas your contract will consume, or to compare gas usage before and after various optimizations.

To generate the gas snapshot, run forge snapshot.

This will generate a file called .gas-snapshot by default with all your tests and their respective gas usage.

$ forge snapshot
$ cat .gas-snapshot

ERC20Test:testApprove() (gas: 31162)
ERC20Test:testBurn() (gas: 59875)
ERC20Test:testFailTransferFromInsufficientAllowance() (gas: 81034)
ERC20Test:testFailTransferFromInsufficientBalance() (gas: 81662)
ERC20Test:testFailTransferInsufficientBalance() (gas: 52882)
ERC20Test:testInfiniteApproveTransferFrom() (gas: 90167)
ERC20Test:testMetadata() (gas: 14606)
ERC20Test:testMint() (gas: 53830)
ERC20Test:testTransfer() (gas: 60473)
ERC20Test:testTransferFrom() (gas: 84152)

Filtering

If you would like to specify a different output file, run forge snapshot --snap <FILE_NAME>.

You can also sort the results by gas usage. Use the --asc option to sort the results in ascending order and --desc to sort the results in descending order.

Finally, you can also specify a min/max gas threshold for all your tests. To only include results above a threshold, you can use the --min <VALUE> option. In the same way, to only include results under a threshold, you can use the --max <VALUE> option.

Keep in mind that the changes will be made in the snapshot file, and not in the snapshot being displayed on your screen.

You can also use it in combination with the filters for forge test, such as forge snapshot --match-path contracts/test/ERC721.t.sol to generate a gas snapshot relevant to this test contract.

Comparing gas usage

If you would like to compare the current snapshot file with your latest changes, you can use the --diff or --check options.

--diff will compare against the snapshot and display changes from the snapshot.

It can also optionally take a file name (--diff <FILE_NAME>), with the default being .gas-snapshot.

For example:

$ forge snapshot --diff .gas-snapshot2

Running 10 tests for src/test/ERC20.t.sol:ERC20Test
[PASS] testApprove() (gas: 31162)
[PASS] testBurn() (gas: 59875)
[PASS] testFailTransferFromInsufficientAllowance() (gas: 81034)
[PASS] testFailTransferFromInsufficientBalance() (gas: 81662)
[PASS] testFailTransferInsufficientBalance() (gas: 52882)
[PASS] testInfiniteApproveTransferFrom() (gas: 90167)
[PASS] testMetadata() (gas: 14606)
[PASS] testMint() (gas: 53830)
[PASS] testTransfer() (gas: 60473)
[PASS] testTransferFrom() (gas: 84152)
Test result: ok. 10 passed; 0 failed; finished in 2.86ms
testBurn() (gas: 0 (0.000%))
testFailTransferFromInsufficientAllowance() (gas: 0 (0.000%))
testFailTransferFromInsufficientBalance() (gas: 0 (0.000%))
testFailTransferInsufficientBalance() (gas: 0 (0.000%))
testInfiniteApproveTransferFrom() (gas: 0 (0.000%))
testMetadata() (gas: 0 (0.000%))
testMint() (gas: 0 (0.000%))
testTransfer() (gas: 0 (0.000%))
testTransferFrom() (gas: 0 (0.000%))
testApprove() (gas: -8 (-0.000%))
Overall gas change: -8 (-0.000%)

--check will compare a snapshot with an existing snapshot file and display all the differences, if any. You can change the file to compare against by providing a different file name: --check <FILE_NAME>.

For example:

$ forge snapshot --check .gas-snapshot2

Running 10 tests for src/test/ERC20.t.sol:ERC20Test
[PASS] testApprove() (gas: 31162)
[PASS] testBurn() (gas: 59875)
[PASS] testFailTransferFromInsufficientAllowance() (gas: 81034)
[PASS] testFailTransferFromInsufficientBalance() (gas: 81662)
[PASS] testFailTransferInsufficientBalance() (gas: 52882)
[PASS] testInfiniteApproveTransferFrom() (gas: 90167)
[PASS] testMetadata() (gas: 14606)
[PASS] testMint() (gas: 53830)
[PASS] testTransfer() (gas: 60473)
[PASS] testTransferFrom() (gas: 84152)
Test result: ok. 10 passed; 0 failed; finished in 2.47ms
Diff in "ERC20Test::testApprove()": consumed "(gas: 31162)" gas, expected "(gas: 31170)" gas 

Debugger

Forge ships with an interactive debugger.

The debugger is accessible on forge debug and on forge test.

Using forge test:

$ forge test --debug $FUNC

Where $FUNC is the signature of the function you want to debug. For example:

$ forge test --debug "testSomething()"

If you have multiple contracts with the same function name, you need to limit the matching functions down to only one case using --match-path and --match-contract.

If the matching test is a fuzz test, the debugger will open the first failing fuzz scenario, or the last successful one, whichever comes first.

Using forge debug:

$ forge debug --debug $FILE --sig $FUNC

Where $FILE is the path to the contract you want to debug, and $FUNC is the signature of the function you want to debug. For example:

$ forge debug --debug src/SomeContract.sol --sig "myFunc(uint256,string)" 123 "hello"

You can also specify raw calldata using --sig instead of a function signature.

If your source file contains more than one contract, specify the contract you want to debug using the --target-contract flag.

Debugger layout

When the debugger is run, you are presented with a terminal divided into four quadrants:

• Quadrant 1: The opcodes in the debugging session, with the current opcode highlighted. Additionally, the address of the current account, the program counter and the accumulated gas usage is also displayed
• Quadrant 2: The current stack, as well as the size of the stack
• Quadrant 3: The source view
• Quadrant 4: The current memory of the EVM

As you step through your code, you will notice that the words in the stack and memory sometimes change color.

For the memory:

• Red words are about to be written to by the current opcode
• Green words were written to by the previous opcode
• Cyan words are being read by the current opcode

For the stack, cyan words are either being read or popped by the current opcode.

Navigating

General

• q: Quit the debugger
• h: Show help

Navigating calls

• 0-9 + k: Step a number of times backwards (alternatively scroll up with your mouse)
• 0-9 + j: Step a number of times forwards (alternatively scroll down with your mouse)
• g: Move to the beginning of the transaction
• G: Move to the end of the transaction
• c: Move to the previous call-type instruction (i.e. CALL, STATICCALL, DELEGATECALL, and CALLCODE).
• C: Move to the next call-type instruction
• a: Move to the previous JUMP or JUMPI instruction
• s: Move to the next JUMPDEST instruction
• ' + a-z: Move to <char> breakpoint set by a vm.breakpoint cheatcode

Navigating memory

• Ctrl + j: Scroll the memory view down
• Ctrl + k: Scroll the memory view up
• m: Show memory as UTF8

Navigating the stack

• J: Scroll the stack view down
• K: Scroll the stack view up
• t: Show labels on the stack to see what items the current op will consume

Overview of Cast

Cast is Foundry's command-line tool for performing Ethereum RPC calls. You can make smart contract calls, send transactions, or retrieve any type of chain data - all from your command-line!

How to use Cast

To use Cast, run the cast command followed by a subcommand:

$ cast <subcommand>

Examples

Let's use cast to retrieve the total supply of the DAI token:

$ cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()(uint256)" --rpc-url https://eth-mainnet.alchemyapi.io/v2/Lc7oIGYeL_QvInzI0Wiu_pOZZDEKBrdf
8603853182003814300330472690

cast also provides many convenient subcommands, such as for decoding calldata:

$ cast 4byte-decode 0x1F1F897F676d00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003e7
1) "fulfillRandomness(bytes32,uint256)"
0x676d000000000000000000000000000000000000000000000000000000000000
999

You can also use cast to send arbitrary messages. Here's an example of sending a message between two Anvil accounts.

$ cast send --private-key <Your Private Key> 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc $(cast --from-utf8 "hello world") --rpc-url http://127.0.0.1:8545/

📚 Reference

See the cast Reference for a complete overview of all the available subcommands.

Overview of Anvil

Anvil is a local testnet node shipped with Foundry. You can use it for testing your contracts from frontends or for interacting over RPC.

Anvil is part of the Foundry suite and is installed alongside forge, cast, and chisel. If you haven't installed Foundry yet, see Foundry installation.

Note: If you have an older version of Foundry installed, you'll need to re-install foundryup in order for Anvil to be downloaded.

How to use Anvil

To use Anvil, simply type anvil. You should see a list of accounts and private keys available for use, as well as the address and port that the node is listening on.

Anvil is highly configurable. You can run anvil -h to see all the configuration options.

Some basic options are:

#  Number of dev accounts to generate and configure. [default: 10]
anvil -a, --accounts <ACCOUNTS>

# The EVM hardfork to use. [default: latest]
anvil --hardfork <HARDFORK>

# Port number to listen on. [default: 8545]
anvil  -p, --port <PORT>

📚 Reference

See the anvil Reference for in depth information on Anvil and its capabilities.

Overview of Chisel

Chisel is an advanced Solidity REPL shipped with Foundry. It can be used to quickly test the behavior of Solidity snippets on a local or forked network.

Chisel is part of the Foundry suite and is installed alongside forge, cast, and anvil. If you haven't installed Foundry yet, see Foundry installation.

Note: If you have an older version of Foundry installed, you'll need to re-install foundryup in order for Chisel to be downloaded.

How to use Chisel

To use Chisel, simply type chisel. From there, start writing Solidity code! Chisel will offer verbose feedback on each input.

Chisel can be used both within and outside of a foundry project. If the binary is executed in a Foundry project root, Chisel will inherit the project's configuration options.

To see available commands, type !help within the REPL.

📚 Reference

See the chisel Reference for in depth information on Chisel and its capabilities.

References

• forge Commands
• cast Commands
• anvil Reference
• chisel Reference
• Config Reference
• Cheatcodes Reference
• Forge Standard Library Reference
• ds-test Reference

forge Commands

• General Commands
• Project Commands
• Build Commands
• Test Commands
• Deploy Commands
• Utility Commands

General Commands

• forge
• forge help
• forge completions

forge

NAME

forge - Build, test, fuzz, debug and deploy Solidity contracts.

SYNOPSIS

forge [options] command [args]
forge [options] --version
forge [options] --help

DESCRIPTION

This program is a set of tools to build, test, fuzz, debug and deploy Solidity smart contracts.

COMMANDS

General Commands

forge help
    Display help information about Forge.

forge completions
    Generate shell autocompletions for Forge.

Project Commands

forge init
    Create a new Forge project.

forge install
    Install one or multiple dependencies.

forge update
    Update one or multiple dependencies.

forge remove
    Remove one or multiple dependencies.

forge config
    Display the current config.

forge remappings
    Get the automatically inferred remappings for this project.

forge tree
    Display a tree visualization of the project's dependency graph.

forge geiger     Detects usage of unsafe cheat codes in a foundry project and its dependencies.

Build Commands

forge build
    Build the project's smart contracts.

forge clean
    Remove the build artifacts and cache directories.

forge inspect
    Get specialized information about a smart contract.

Test Commands

forge test
    Run the project's tests.

forge snapshot
    Create a snapshot of each test's gas usage.

Deploy Commands

forge create
    Deploy a smart contract.

forge verify-contract
    Verify smart contracts on Etherscan.

forge verify-check
    Check verification status on Etherscan.

forge flatten
    Flatten a source file and all of its imports into one file.

Utility Commands

forge debug
    Debug a single smart contract as a script.

forge bind
    Generate Rust bindings for smart contracts.

forge cache
    Manage the Foundry cache.

forge cache clean
    Cleans cached data from ~/.foundry.

forge cache ls
    Shows cached data from ~/.foundry.

forge script
    Run a smart contract as a script, building transactions that can be sent onchain.

forge upload-selectors
    Uploads abi of given contract to https://sig.eth.samczsun.com function selector database.

forge doc
    Generate documentation for Solidity source files.

OPTIONS

Special Options

-V
--version
    Print version info and exit.

Common Options

-h
--help
    Prints help information.

FILES

~/.foundry/
    Default location for Foundry's "home" directory where it stores various files.

~/.foundry/bin/
    Binaries installed using foundryup will be located here.

~/.foundry/cache/
    Forge's cache directory, where it stores cached block data and more.

~/.foundry/foundry.toml
    The global Foundry config.

~/.svm
    The location of the Forge-managed solc binaries.

EXAMPLES

1. Create a new Forge project:

   forge init hello_foundry
   

2. Build a project:

   forge build
   

3. Run a project's tests:

   forge test
   

BUGS

See https://github.com/foundry-rs/foundry/issues for issues.

forge help

NAME

forge-help - Get help for a Forge command

SYNOPSIS

forge help [subcommand]

DESCRIPTION

Prints a help message for the given command.

EXAMPLES

1. Get help for a command:

   forge help build
   

2. Help is also available with the --help flag:

   forge build --help
   

SEE ALSO

forge

forge completions

NAME

forge-completions - Generate shell completions script

SYNOPSIS

forge completions shell

DESCRIPTION

Generates a shell completions script for the given shell.

Supported shells are:

• bash
• elvish
• fish
• powershell
• zsh

OPTIONS

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Generate shell completions script for zsh:

   forge completions zsh > $HOME/.oh-my-zsh/completions/_forge
   

SEE ALSO

forge

Project Commands

• forge init
• forge install
• forge update
• forge remove
• forge config
• forge remappings
• forge tree
• forge geiger

forge init

NAME

forge-init - Create a new Forge project.

SYNOPSIS

forge init [options] [root]

DESCRIPTION

Create a new Forge project in the directory root (by default the current working directory).

The default template creates the following project layout:

.
├── foundry.toml
├── lib
│   └── forge-std
│       ├── LICENSE-APACHE
│       ├── LICENSE-MIT
│       ├── README.md
│       ├── foundry.toml
│       ├── lib
│       └── src
├── script
│   └── Counter.s.sol
├── src
│   └── Counter.sol
└── test
    └── Counter.t.sol

7 directories, 8 files

However, it is possible to create a project from another using --template.

By default, forge init will also initialize a new git repository, install some submodules and create an initial commit message.

If you do not want this behavior, pass --no-git.

OPTIONS

Init Options

--force
    Create the project even if the specified root directory is not empty.

-t template
--template template
    The template to start from.

--vscode
    Create a .vscode/settings.json file with Solidity settings, and generate a remappings.txt file.

--offline
    Do not install dependencies from the network.

VCS Options

--no-commit
    Do not create an initial commit.

--no-git
    Do not create a git repository.

Display Options

-q
--quiet
    Do not print any messages.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Create a new project:

   forge init hello_foundry
   

2. Create a new project, but do not create a git repository:

   forge init --no-git hello_foundry
   

3. Forcibly create a new project in a non-empty directory:

   forge init --force 
   

SEE ALSO

forge

forge install

NAME

forge-install - Install one or more dependencies.

SYNOPSIS

forge install [options] [deps...]

DESCRIPTION

Install one or more dependencies.

Dependencies are installed as git submodules. If you do not want this behavior, pass --no-git.

If no arguments are provided, then existing dependencies are installed.

Dependencies can be a raw URL (https://foo.com/dep), an SSH URL (git@github.com:owner/repo), or the path to a GitHub repository (owner/repo). Additionally, a ref can be added to the dependency path to install a specific version of a dependency.

A ref can be:

• A branch: owner/repo@master
• A tag: owner/repo@v1.2.3
• A commit: owner/repo@8e8128

The ref defaults to master.

You can also choose the name of the folder the dependency will be in. By default, the folder name is the name of the repository. If you want to change the name of the folder, prepend <folder>= to the dependency.

OPTIONS

Project Options

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

VCS Options

--no-commit
    Do not create a commit.

--no-git
    Install without adding the dependency as a submodule.

Display Options

-q
--quiet
    Do not print any messages.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Install a dependency:

   forge install transmissions11/solmate
   

2. Install a specific version of a dependency:

   forge install transmissions11/solmate@v7
   

3. Install multiple dependencies:

   forge install transmissions11/solmate@v7 OpenZeppelin/openzeppelin-contracts
   

4. Install a dependency without creating a submodule:

   forge install --no-git transmissions11/solmate
   

5. Install a dependency in a specific folder:

   forge install soulmate=transmissions11/solmate
   

SEE ALSO

forge, forge update, forge remove

forge update

NAME

forge-update - Update one or more dependencies.

SYNOPSIS

forge update [options] [dep]

DESCRIPTION

Update one or more dependencies.

The argument dep is a path to the dependency you want to update. Forge will update to the latest version on the ref you specified for the dependency when you ran forge install.

If no argument is provided, then all dependencies are updated.

OPTIONS

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Update a dependency:

   forge update lib/solmate
   

2. Update all dependencies:

   forge update
   

SEE ALSO

forge, forge install, forge remove

forge remove

NAME

forge-remove - Remove one or multiple dependencies.

SYNOPSIS

forge remove [options] [deps...]

DESCRIPTION

Remove one or multiple dependencies.

Dependencies can be a raw URL (https://foo.com/dep), the path to a GitHub repository (owner/repo) or the path to the dependency in the project tree.

OPTIONS

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Remove a dependency by path:

   forge remove lib/solmate
   

2. Remove a dependency by GitHub repository name:

   forge remove dapphub/solmate
   

SEE ALSO

forge, forge install, forge update

forge config

NAME

forge-config - Display the current config.

SYNOPSIS

forge config [options]

DESCRIPTION

Display the current config.

This command can be used to create a new basic foundry.toml or to see what values are currently set, taking environment variables and the global configuration file into account.

The command supports almost all flags of the other commands in Forge to allow overriding values in the displayed configuration.

OPTIONS

Config Options

--basic
    Prints a basic configuration file.

--fix
    Attempts to fix any configuration warnings.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Create a new basic config:

   forge config > foundry.toml
   

2. Enable FFI in foundry.toml:

   forge config --ffi > foundry.toml
   

SEE ALSO

forge

forge remappings

NAME

forge-remappings - Get the automatically inferred remappings for the project.

SYNOPSIS

forge remappings [options]

DESCRIPTION

Get the automatically inferred remappings for the project.

OPTIONS

Project Options

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

--lib-path path
    The path to the library folder.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Create a remappings.txt file from the inferred remappings:

   forge remappings > remappings.txt
   

SEE ALSO

forge

forge tree

NAME

forge-tree - Display a tree visualization of the project's dependency graph.

SYNOPSIS

forge tree [options]

DESCRIPTION

Display a visualization of the project's dependency graph.

$ forge tree
src/OpenZeppelinNft.sol 0.8.10
├── lib/openzeppelin-contracts/contracts/token/ERC721/ERC721.sol ^0.8.0
│   ├── lib/openzeppelin-contracts/contracts/token/ERC721/IERC721.sol ^0.8.0
│   │   └── lib/openzeppelin-contracts/contracts/utils/introspection/IERC165.sol ^0.8.0
│   ├── lib/openzeppelin-contracts/contracts/token/ERC721/IERC721Receiver.sol ^0.8.0
│   ├── lib/openzeppelin-contracts/contracts/token/ERC721/extensions/IERC721Metadata.sol ^0.8.0
│   │   └── lib/openzeppelin-contracts/contracts/token/ERC721/IERC721.sol ^0.8.0 (*)
│   ├── lib/openzeppelin-contracts/contracts/utils/Address.sol ^0.8.1
│   ├── lib/openzeppelin-contracts/contracts/utils/Context.sol ^0.8.0
│   ├── lib/openzeppelin-contracts/contracts/utils/Strings.sol ^0.8.0
│   └── lib/openzeppelin-contracts/contracts/utils/introspection/ERC165.sol ^0.8.0
│       └── lib/openzeppelin-contracts/contracts/utils/introspection/IERC165.sol ^0.8.0
├── lib/openzeppelin-contracts/contracts/utils/Strings.sol ^0.8.0
├── lib/openzeppelin-contracts/contracts/security/PullPayment.sol ^0.8.0
│   └── lib/openzeppelin-contracts/contracts/utils/escrow/Escrow.sol ^0.8.0
│       ├── lib/openzeppelin-contracts/contracts/access/Ownable.sol ^0.8.0
│       │   └── lib/openzeppelin-contracts/contracts/utils/Context.sol ^0.8.0
│       └── lib/openzeppelin-contracts/contracts/utils/Address.sol ^0.8.1
└── lib/openzeppelin-contracts/contracts/access/Ownable.sol ^0.8.0 (*)
src/SolmateNft.sol 0.8.10
├── lib/solmate/src/tokens/ERC721.sol >=0.8.0
├── lib/openzeppelin-contracts/contracts/utils/Strings.sol ^0.8.0
├── lib/openzeppelin-contracts/contracts/security/PullPayment.sol ^0.8.0 (*)
└── lib/openzeppelin-contracts/contracts/access/Ownable.sol ^0.8.0 (*)
test/OpenZeppelinNft.t.sol 0.8.10
├── lib/forge-std/src/Test.sol >=0.6.0 <0.9.0
│   ├── lib/forge-std/src/Script.sol >=0.6.0 <0.9.0
│   │   ├── lib/forge-std/src/Vm.sol >=0.6.0
│   │   ├── lib/forge-std/src/console.sol >=0.4.22 <0.9.0
│   │   └── lib/forge-std/src/console2.sol >=0.4.22 <0.9.0
│   └── lib/forge-std/lib/ds-test/src/test.sol >=0.5.0
├── src/OpenZeppelinNft.sol 0.8.10 (*)
└── lib/openzeppelin-contracts/contracts/token/ERC721/IERC721Receiver.sol ^0.8.0
test/SolmateNft.sol 0.8.10
├── lib/forge-std/src/Test.sol >=0.6.0 <0.9.0 (*)
└── src/SolmateNft.sol 0.8.10 (*)

OPTIONS

Flatten Options

--charset charset
    Character set to use in output: utf8, ascii. Default: utf8

--no-dedupe
    Do not de-duplicate (repeats all shared dependencies)

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

Common Options

-h
--help
    Prints help information.

SEE ALSO

forge

forge geiger

NAME

forge-geiger - Detects usage of unsafe cheat codes in a foundry project and its dependencies.

SYNOPSIS

forge geiger [options] [path]

DESCRIPTION

Detects usage of unsafe cheat codes in a foundry project and its dependencies.

OPTIONS

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

--check
    Run in 'check' mode. Exits with 0 if no unsafe cheat codes were found. Exits with 1 if unsafe cheat codes are detected.

--full
    Print a full report of all files even if no unsafe functions are found.

Common Options

-h
--help
    Prints help information.

SEE ALSO

forge

Build Commands

• forge build
• forge clean
• forge inspect

forge build

NAME

forge-build - Build the project's smart contracts.

SYNOPSIS

forge build or forge b [options]

DESCRIPTION

Build the project's smart contracts.

The command will try to detect the latest version that can compile your project by looking at the version requirements of all your contracts and dependencies.

You can override this behaviour by passing --no-auto-detect. Alternatively, you can pass --use <SOLC_VERSION>.

If the command detects that the Solidity compiler version it is using to build is not installed, it will download it and install it in ~/.svm. You can disable this behavior by passing --offline.

The build is incremental, and the build cache is saved in cache/ in the project root by default. If you want to clear the cache, pass --force, and if you want to change the cache directory, pass --cache-path <PATH>.

Build Modes

There are three build modes:

• Just compilation (default): Builds the project and saves the contract artifacts in out/ (or the path specified by --out <PATH>).
• Size mode (--sizes): Builds the project, displays the size of non-test contracts and exits with code 1 if any of them are above the size limit.
• Name mode (--names): Builds the project, displays the names of the contracts and exits.

The Optimizer

You can enable the optimizer by passing --optimize, and you can adjust the number of optimizer runs by passing --optimizer-runs <RUNS>.

You can also opt-in to the Solidity IR compilation pipeline by passing --via-ir. Read more about the IR pipeline in the Solidity docs.

By default, the optimizer is enabled and runs for 200 cycles.

Conditional Optimizer Usage

Many projects use the solc optimizer, either through the standard compilation pipeline or the IR pipeline. But in some cases, the optimizer can significantly slow down compilation speeds.

A config file for a project using the optimizer may look like this for regular compilation:

[profile.default]
solc-version = "0.8.17"
optimizer = true
optimizer-runs = 10_000_000

Or like this for via-ir:

[profile.default]
solc-version = "0.8.17"
via_ir = true

To reduce compilation speeds during development and testing, one approach is to have a lite profile that has the optimizer off and use this for development/testing cycle. The updated config file for regular compilation may look like this:

[profile.default]
solc-version = "0.8.17"
optimizer = true
optimizer-runs = 10_000_000

[profile.lite]
optimizer = false

Or like this for via-ir:

[profile.default]
solc-version = "0.8.17"
via_ir = true

[profile.lite.optimizer_details.yulDetails]
optimizerSteps = ''

When setup like this, forge build (or forge test / forge script) still uses the standard profile, so by default a forge script invocation will deploy your contracts with the production setting. Running FOUNDRY_PROFILE=lite forge build (and again, same for the test and script commands) will use the lite profile to reduce compilation times.

There are additional optimizer details you can configure, see the Additional Optimizer Settings section below for more info.

Artifacts

You can add extra output from the Solidity compiler to your artifacts by passing --extra-output <SELECTOR>.

The selector is a path in the Solidity compiler output, which you can read more about in the Solidity docs.

You can also write some of the compiler output to separate files by passing --extra-output-files <SELECTOR>.

Valid selectors for --extra-output-files are:

• metadata: Written as a metadata.json file in the artifacts directory
• ir: Written as a .ir file in the artifacts directory
• irOptimized: Written as a .iropt file in the artifacts directory
• ewasm: Written as a .ewasm file in the artifacts directory
• evm.assembly: Written as a .asm file in the artifacts directory

Watch Mode

The command can be run in watch mode by passing --watch [PATH...], which will rebuild every time a watched file or directory is changed. The source directory is watched by default.

Sparse Mode (experimental)

Sparse mode only compiles files that match certain criteria.

By default, this filter applies to files that have not been changed since the last build, but for commands that take file filters (e.g. forge test), sparse mode will only recompile files that match the filter.

Sparse mode is opt-in until the feature is stabilized. To opt-in to sparse mode and try it out, set sparse_mode in your configuration file.

Additional Optimizer Settings

The optimizer can be fine-tuned with additional settings. Simply set the optimizer_details table in your configuration file. For example:

[profile.default.optimizer_details]
constantOptimizer = true
yul = true

[profile.default.optimizer_details.yulDetails]
stackAllocation = true
optimizerSteps = 'dhfoDgvulfnTUtnIf'

See the compiler input description documentation for more information on available settings (specifically settings.optimizer.details).

Revert Strings

You can control how revert strings are generated by the compiler. By default, only user supplied revert strings are included in the bytecode, but there are other options:

• strip: Removes all revert strings (if possible, i.e. if literals are used) keeping side-effects.
• debug: Injects strings for compiler-generated internal reverts, implemented for ABI encoders V1 and V2 for now.
• verboseDebug: Appends further information to user-supplied revert strings (not yet implemented).

Additional Model Checker settings

Solidity's built-in model checker is an opt-in module that can be enabled via the ModelChecker object.

See Compiler Input Description settings.modelChecker and the model checker's options.

The module is available in solc release binaries for OSX and Linux. The latter requires the z3 library version [4.8.8, 4.8.14] to be installed in the system (SO version 4.8).

Similarly to the optimizer settings above, the model_checker settings must be prefixed with the profile they correspond to: [profile.default.model_checker] belongs to the [profile.default].

## foundry.toml
[profile.default.model_checker]
contracts = { '/path/to/project/src/Contract.sol' = [ 'Contract' ] }
engine = 'chc'
timeout = 10000
targets = [ 'assert' ]

The fields above are recommended when using the model checker. Setting which contract should be verified is extremely important, otherwise all available contracts will be verified which can consume a lot of time. The recommended engine is chc, but bmc and all (runs both) are also accepted. It is also important to set a proper timeout (given in milliseconds), since the default time given to the underlying solvers may not be enough. If no verification targets are given, only assertions will be checked.

The model checker will run when forge build is invoked, and will show findings as warnings if any.

OPTIONS

Build Options

--names     Print compiled contract names.

--sizes     Print compiled non-test contract sizes, exiting with code 1 if any of them are above the size limit.

--skip     Skip compilation of non-essential contract directories like test or script (usage --skip test).

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Watch Options

-w [path...]
--watch [path...]
    Watch specific file(s) or folder(s).

    By default, the project's source directory is watched.

-d delay
--delay delay
    File update debounce delay.

    During the delay, incoming change events are accumulated and only once the delay has passed, is an action taken.
    Note that this does not mean a command will be started: if --no-restart is given and a command is already running, the outcome of the action will be to do nothing.

    Defaults to 50ms. Parses as decimal seconds by default, but using an integer with the ms suffix may be more convenient.

    When using --poll mode, you'll want a larger duration, or risk overloading disk I/O.

--no-restart
    Do not restart the command while it's running.

--run-all
    Explicitly re-run the command on all files when a change is made.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Build the project:

   forge build
   

2. Build the project with solc 0.6.0:

   forge build --use solc:0.6.0
   

3. Build the project with additional artifact output:

   forge build --extra-output evm.assembly
   

4. Build the project in watch mode:

   forge build --watch
   

SEE ALSO

forge, forge clean, forge inspect

forge clean

NAME

forge-clean - Remove the build artifacts and cache directories.

SYNOPSIS

forge clean [options]

DESCRIPTION

Remove the build artifacts and cache directories.

OPTIONS

Clean Options

--root path
    The project's root path. Defaults to the current working directory.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Clean artifacts and cache in a project:

   forge clean
   

SEE ALSO

forge

forge inspect

NAME

forge-inspect - Get specialized information about a smart contract

SYNOPSIS

forge inspect [options] contract_name field

DESCRIPTION

Get specialized information about a smart contract.

The field to inspect (field) can be any of:

• abi
• b/bytes/bytecode
• deployedBytecode/deployed_bytecode/deployed-bytecode/deployedbytecode/deployed
• assembly/asm
• asmOptimized/assemblyOptimized/assemblyoptimized/assembly_optimized/asmopt/assembly-optimized/asmo/asm-optimized/asmoptimized/asm_optimized
• methods/methodidentifiers/methodIdentifiers/method_identifiers/method-identifiers/mi
• gasEstimates/gas/gas_estimates/gas-estimates/gasestimates
• storageLayout/storage_layout/storage-layout/storagelayout/storage
• devdoc/dev-doc/devDoc
• ir
• ir-optimized/irOptimized/iroptimized/iro/iropt
• metadata/meta
• userdoc/userDoc/user-doc
• ewasm/e-wasm

OPTIONS

--pretty
    Pretty print the selected field, if supported.

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Inspect the bytecode of a contract:

   forge inspect MyContract bytecode
   

2. Inspect the storage layout of a contract:

   forge inspect MyContract storage
   

SEE ALSO

forge, forge build

Test Commands

• forge test
• forge snapshot

forge test

NAME

forge-test - Run the project's tests.

SYNOPSIS

forge test [options]

DESCRIPTION

Run the project's tests.

Forking

It is possible to run the tests in a forked environment by passing --fork-url <URL>.

When the tests are running in a forked environment, you can access all the state of the forked chain as you would if you had deployed the contracts. Cheatcodes are still available.

You can also specify a block number to fork from by passing --fork-block-number <BLOCK>. When forking from a specific block, the chain data is cached to ~/.foundry/cache. If you do not want to cache the chain data, pass --no-storage-caching.

Traces that cannot be decoded by local contracts when running in a forked environment (e.g. calls to contracts that live on mainnet, like tokens) can optionally be decoded using Etherscan. To use Etherscan for trace decoding, set ETHERSCAN_API_KEY or pass --etherscan-api-key <KEY>.

Debugging

It is possible to run a test in an interactive debugger. To start the debugger, pass --debug <TEST>.

If multiple tests match the specified pattern, you must use other test filters in order to reduce the matching number of tests to exactly 1.

If the test is a unit test, it is immediately opened in the debugger.

If the test is a fuzz test, the fuzz test is run and the debugger is opened on the first failing scenario. If there are no failing scenarios for the fuzz test, the debugger is opened on the last scenario.

More information on the debugger can be found in the debugger chapter.

Gas reports

You can generate a gas report by passing --gas-report.

More information on gas reports can be found in the gas reports chapter.

List

It is possible to list the tests without running them. You can pass --json to make it easier for outside extensions to parse structured content.

OPTIONS

Test Options

-m regex
--match regex
    Only run test functions matching the specified regex pattern.
    Deprecated: See --match-test.

--match-test regex
    Only run test functions matching the specified regex pattern.

--no-match-test regex
    Only run test functions that do not match the specified regex pattern.

--match-contract regex
    Only run tests in contracts matching the specified regex pattern.

--no-match-contract regex
    Only run tests in contracts that do not match the specified regex pattern.

--match-path glob
    Only run tests in source files matching the specified glob pattern.

--no-match-path glob
    Only run tests in source files that do not match the specified glob pattern.

--debug regex
    Run a test in the debugger.

    The argument passed to this flag is the name of the test function you want to run, and it works the same as --match-test.

    If more than one test matches your specified criteria, you must add additional filters until only one test is found (see --match-contract and --match-path).

    The matching test will be opened in the debugger regardless of the outcome of the test.

    If the matching test is a fuzz test, then it will open the debugger on the first failure case. If the fuzz test does not fail, it will open the debugger on the last fuzz case.

    For more fine-grained control of which fuzz case is run, see forge debug.

--gas-report
    Print a gas report.

--allow-failure
    Exit with code 0 even if a test fails.

--fail-fast
    Stop running tests after the first failure.

--etherscan-api-key key
    Etherscan API key. If set, traces are decoded using Etherscan if --fork-url is also set.
    Environment: ETHERSCAN_API_KEY

EVM Options

-f url
--rpc-url url
--fork-url url
    Fetch state over a remote endpoint instead of starting from an empty state.

    If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block
    Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF>
     Initial retry backoff on encountering errors.

--no-storage-caching
    Explicitly disables the use of RPC caching.

    All storage slots are read entirely from the endpoint. See --fork-url.

-v
--verbosity
    Verbosity of the EVM.

    Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
    The address which will be executing tests

--initial-balance balance
    The initial balance of deployed contracts

--ffi
    Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
    The base fee in a block (in wei).

--block-coinbase address
    The coinbase of the block.

--block-difficulty difficulty
    The block difficulty.

--block-gas-limit gas_limit
    The block gas limit.

--block-number block
    The block number.

--block-timestamp timestamp
    The timestamp of the block (in seconds).

--chain-id chain_id
    The chain ID.

--gas-limit gas_limit
    The block gas limit.

--gas-price gas_price
    The gas price (in wei).

--tx-origin address
    The transaction origin.

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Watch Options

-w [path...]
--watch [path...]
    Watch specific file(s) or folder(s).

    By default, the project's source directory is watched.

-d delay
--delay delay
    File update debounce delay.

    During the delay, incoming change events are accumulated and only once the delay has passed, is an action taken.
    Note that this does not mean a command will be started: if --no-restart is given and a command is already running, the outcome of the action will be to do nothing.

    Defaults to 50ms. Parses as decimal seconds by default, but using an integer with the ms suffix may be more convenient.

    When using --poll mode, you'll want a larger duration, or risk overloading disk I/O.

--no-restart
    Do not restart the command while it's running.

--run-all
    Explicitly re-run the command on all files when a change is made.

Display Options

-j
--json
     Print the deployment information as JSON.

--list
    List tests instead of running them.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Run the tests:

   forge test
   

2. Open a test in the debugger:

   forge test --debug testSomething
   

3. Generate a gas report:

   forge test --gas-report
   

4. Only run tests in test/Contract.t.sol in the BigTest contract that start with testFail:

   forge test --match-path test/Contract.t.sol --match-contract BigTest \
     --match-test "testFail*"
   

5. List tests in desired format

   forge test --list
   forge test --list --json
   forge test --list --json --match-test "testFail*" | tail -n 1 | json_pp
   

SEE ALSO

forge, forge build, forge snapshot

forge snapshot

NAME

forge-snapshot - Create a snapshot of each test's gas usage.

SYNOPSIS

forge snapshot [options]

DESCRIPTION

Create a snapshot of each test's gas usage.

The results are written to a file named .gas-snapshot. You can change the name of the file by passing --snap <PATH>.

Fuzz tests are included by default in the snapshot. They use a static seed to achieve deterministic results.

Snapshots can be compared with --diff and --check. The first flag will output a diff, and the second will output a diff and exit with code 1 if the snapshots do not match.

OPTIONS

Snapshot Options

--asc
Sort results by gas used (ascending).

--desc
    Sort results by gas used (descending).

--min min_gas
    Only include tests that used more gas that the given amount.

--max max_gas
    Only include tests that used less gas that the given amount.

--diff path
    Output a diff against a pre-existing snapshot.

    By default the comparison is done with .gas-snapshot.

--check path
    Compare against a pre-existing snapshot, exiting with code 1 if they do not match.

    Outputs a diff if the snapshots do not match.

    By default the comparison is done with .gas-snapshot.

--snap path
    Output file for the snapshot. Default: .gas-snapshot.

Test Options

-m regex
--match regex
    Only run test functions matching the specified regex pattern.
    Deprecated: See --match-test.

--match-test regex
    Only run test functions matching the specified regex pattern.

--no-match-test regex
    Only run test functions that do not match the specified regex pattern.

--match-contract regex
    Only run tests in contracts matching the specified regex pattern.

--no-match-contract regex
    Only run tests in contracts that do not match the specified regex pattern.

--match-path glob
    Only run tests in source files matching the specified glob pattern.

--no-match-path glob
    Only run tests in source files that do not match the specified glob pattern.

--debug regex
    Run a test in the debugger.

    The argument passed to this flag is the name of the test function you want to run, and it works the same as --match-test.

    If more than one test matches your specified criteria, you must add additional filters until only one test is found (see --match-contract and --match-path).

    The matching test will be opened in the debugger regardless of the outcome of the test.

    If the matching test is a fuzz test, then it will open the debugger on the first failure case. If the fuzz test does not fail, it will open the debugger on the last fuzz case.

    For more fine-grained control of which fuzz case is run, see forge debug.

--gas-report
    Print a gas report.

--allow-failure
    Exit with code 0 even if a test fails.

--fail-fast
    Stop running tests after the first failure.

--etherscan-api-key key
    Etherscan API key. If set, traces are decoded using Etherscan if --fork-url is also set.
    Environment: ETHERSCAN_API_KEY

EVM Options

-f url
--rpc-url url
--fork-url url
    Fetch state over a remote endpoint instead of starting from an empty state.

    If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block
    Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF>
     Initial retry backoff on encountering errors.

--no-storage-caching
    Explicitly disables the use of RPC caching.

    All storage slots are read entirely from the endpoint. See --fork-url.

-v
--verbosity
    Verbosity of the EVM.

    Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
    The address which will be executing tests

--initial-balance balance
    The initial balance of deployed contracts

--ffi
    Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
    The base fee in a block (in wei).

--block-coinbase address
    The coinbase of the block.

--block-difficulty difficulty
    The block difficulty.

--block-gas-limit gas_limit
    The block gas limit.

--block-number block
    The block number.

--block-timestamp timestamp
    The timestamp of the block (in seconds).

--chain-id chain_id
    The chain ID.

--gas-limit gas_limit
    The block gas limit.

--gas-price gas_price
    The gas price (in wei).

--tx-origin address
    The transaction origin.

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Display Options

-j
--json
     Print the deployment information as JSON.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Create a snapshot:

   forge snapshot
   

2. Generate a diff:

   forge snapshot --diff
   

3. Check that the snapshots match:

   forge snapshot --check
   

SEE ALSO

forge, forge test

forge coverage

NAME

forge-coverage - Displays which parts of your code are covered by tests.

SYNOPSIS

forge coverage [options]

DESCRIPTION

Displays which parts of your code are covered by tests.

Options

Report Options

--report allows you to specify the report type to use for coverage. This flag can be used multiple times.

It has three different options and is set to summary by default.

summary
    Outputs a chart showing what percentage of your code is covered by tests.

lcov
    Creates a lcov.info file containing your coverage data in the root of your project's directory.

debug
    Outputs lines describing the location of uncovered code.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. View summarized coverage:

   forge coverage
   

2. Create lcov file with coverage data:

   forge coverage --report lcov
   

3. Output uncovered code locations:

   forge coverage --report debug
   

SEE ALSO

forge, forge test

Deploy Commands

• forge create
• forge verify-contract
• forge verify-check
• forge flatten

forge create

NAME

forge-create - Deploy a smart contract.

SYNOPSIS

forge create [options] contract

DESCRIPTION

Deploy a smart contract.

The path to the contract is in the format <path>:<contract>, e.g. src/Contract.sol:Contract.

You can specify constructor arguments with --constructor-args. Alternatively, you can specify a file containing space-separated constructor arguments with --constructor-args-path.

Dynamic linking is not supported: you should predeploy your libraries and manually specify their addresses (see --libraries).

ℹ️ Note

The --constructor-args flag must be positioned last in the command, since it takes multiple values.

OPTIONS

Build Options

--constructor-args args...
    The constructor arguments.

--constructor-args-path file
    The path to a file containing the constructor arguments.

--verify
    Verify contract after creation. Runs forge verify-contract with the appropriate parameters.

--verifier name
    The verification provider. Available options: etherscan, sourcify & blockscout. Default: etherscan.

--verifier-url url
    The optional verifier url for submitting the verification request.
    Environment: VERIFIER_URL

--unlocked
    Send via eth_sendTransaction using the --from argument or $ETH_FROM as sender.

Transaction Options

--gas-limit gas_limit
    Gas limit for the transaction.

--gas-price price
    Gas price for the transaction, or max fee per gas for EIP1559 transactions.

--priority-gas-price price
    Max priority fee per gas for EIP1559 transactions.

--value value
    Ether to send in the transaction.

    Either specified as an integer (wei), or as a string with a unit, for example:
    - 1ether
    - 10gwei
    - 0.01ether

--nonce nonce
    Nonce for the transaction.

--legacy
    Send a legacy transaction instead of an EIP1559 transaction.

    This is automatically enabled for common networks without EIP1559.

WALLET OPTIONS - RAW:

-i
--interactive <NUM>
     Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
     Defaults to 0.

--mnemonic-derivation-path <PATHS>
     The wallet derivation path. Works with both --mnemonic-path and hardware wallets.

--mnemonic-indexes <INDEXES>
     Use the private key from the given mnemonic index. Used with --mnemonic-paths.
     Defaults to 0.

--mnemonic-passphrase <PASSPHRASE>
     Use a BIP39 passphrases for the mnemonic.

--mnemonic <PATHS>
     Use the mnemonic phrases or mnemonic files at the specified paths.

--private-key <RAW_PRIVATE_KEY>
     Use the provided private key.

--private-keys <RAW_PRIVATE_KEYS>
     Use the provided private keys.

Wallet Options - Keystore

--keystore path
    Use the keystore in the given folder or file.
    Environment: ETH_KEYSTORE

--password password
    The keystore password. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
    Use a Trezor hardware wallet.

-l
--ledger
    Use a Ledger hardware wallet.

Wallet Options - Remote

-f address
--from address
    Sign the transaction with the specified account on the RPC.
    Environment: ETH_FROM

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Display Options

-j
--json
     Print the deployment information as JSON.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Deploy a contract with no constructor arguments:

   forge create src/Contract.sol:ContractWithNoConstructor
   

2. Deploy a contract with two constructor arguments:

   forge create src/Contract.sol:MyToken --constructor-args "My Token" "MT"
   

SEE ALSO

forge, forge build, forge verify-contract

forge verify-contract

NAME

forge-verify-contract - Verify smart contracts on a chosen verification provider.

SYNOPSIS

forge verify-contract [options] address contract

DESCRIPTION

Verifies a smart contract on a chosen verification provider.

You must provide:

• The contract address
• The contract name or the path to the contract (read below) In case of Etherscan verification, you must also provide:
• Your Etherscan API key, either by passing it as an argument or setting ETHERSCAN_API_KEY

To find the exact compiler version, run ~/.svm/x.y.z/solc-x.y.z --version and search for the 8 hex digits in the version string here.

The path to the contract is in the format <path>:<contract>, e.g. src/Contract.sol:Contract.

By default, smart contracts are verified in a multi-file fashion. If you want to flatten the contract before verifying, pass --flatten.

This command will try to compile the source code of the flattened contract if --flatten is passed before verifying. If you do not want that, pass --force.

You can specify ABI-encoded constructor arguments with --constructor-args. Alternatively, you can specify a file containing space-separated constructor arguments with --constructor-args-path. (Note that cache must be enabled in the config for the latter to work.)

OPTIONS

Verify Contract Options

--verifier name
    The verification provider. Available options: etherscan, sourcify & blockscout. Default: etherscan.

--verifier-url url
    The optional verifier url for submitting the verification request.
    Environment: VERIFIER_URL

--compiler-version version
    The compiler version used to build the smart contract.

    To find the exact compiler version, run ~/.svm/x.y.z/solc-x.y.z --version where x and y are major and minor version numbers respectively, then search for the 8 hex digits in the version string here.

--num-of-optimizations num
--optimizer-runs num
    The number of optimization runs used to build the smart contract.

--constructor-args args
    The ABI-encoded constructor arguments. Conflicts with --constructor-args-path.

--constructor-args-path file
    The path to a file containing the constructor arguments. Conflicts with --constructor-args.

--chain-id chain
--chain chain
    The ID or name of the chain the contract is deployed to.
    Default: mainnet

--flatten
    Flag indicating whether to flatten the source code before verifying.

    If this flag is not provided, the JSON standard input will be used instead.

-f
--force
    Do not compile the flattened smart contract before verifying.

--delay delay
    Optional timeout to apply in between attempts in seconds. Defaults to 3.

--retries retries
    Number of attempts for retrying. Defaults to 15.

--watch
    Wait for verification result after submission.
    Automatically runs forge verify-check until the verification either fails or succeeds.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Verify a contract with JSON standard input on Etherscan

   forge verify-contract <address> SomeContract --watch
   
   

2. Verify a contract on a custom Sourcify instance

   forge verify-contract --verifier sourcify \
     --verifier-url http://localhost:5000 <address> SomeContract
   

3. Verify a flattened contract built with solc v0.8.11+commit.d7f03943:

   forge verify-contract --flatten --watch --compiler-version "v0.8.11+commit.d7f03943" \
     --constructor-args $(cast abi-encode "constructor(string,string,uint256,uint256)" "ForgeUSD" "FUSD" 18 1000000000000000000000) \
     <address> MyToken
   

4. Verify a flattened contract by specifying constructor arguments in a file:

   forge verify-contract --flatten --watch --compiler-version "v0.8.11+commit.d7f03943" \
     --constructor-args-path constructor-args.txt <address> src/Token.sol:MyToken
   

   where constructor-args.txt contains the following content:

   ForgeUSD FUSD 18 1000000000000000000000
   

SEE ALSO

forge, forge create, forge flatten, forge verify-check

forge verify-check

NAME

forge-verify-check - Check verification status on a chosen verification provider.

SYNOPSIS

forge verify-check [options] id [etherscan_key]

The id is the verification identifier. For Etherscan & Bloxroute - it is the submission GUID, for Sourcify - it's the contract address.

DESCRIPTION

Check verification status on a chosen verification provider.

For Etherscan, you must provide an Etherscan API key, either by passing it as an argument or setting ETHERSCAN_API_KEY

OPTIONS

Verify Contract Options

--verifier name
    The verification provider. Available options: etherscan, sourcify & blockscout. Default: etherscan.

--verifier-url url
    The optional verifier url for submitting the verification request.
    Environment: VERIFIER_URL

--chain-id chain_id
    The chain ID the contract is deployed to (either a number or a chain name).
    Default: mainnet

--delay delay
    Optional timeout to apply in between attempts in seconds. Defaults to 3.

--retries retries
    Number of attempts for retrying. Defaults to 15.

Common Options

-h
--help
    Prints help information.

SEE ALSO

forge, forge create, forge verify-contract

forge flatten

NAME

forge-flatten - Flatten a source file and all of its imports into one file.

SYNOPSIS

forge flatten [options] file

DESCRIPTION

Flatten a source file and all of its imports into one file.

If --output <FILE> is not set, then the flattened contract will be output to stdout.

OPTIONS

Flatten Options

-o file
--output file
    The path to output the flattened contract. If not specified, the flattened contract will be output to stdout.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Flatten src/Contract.sol:

   forge flatten src/Contract.sol
   

2. Flatten src/Contract.sol and write the result to src/Contract.flattened.sol:

   forge flatten --output src/Contract.flattened.sol src/Contract.sol
   

SEE ALSO

forge, forge verify-contract

Utility Commands

• forge debug
• forge bind
• forge cache
• forge cache clean
• forge cache ls
• forge script
• forge upload-selectors
• forge doc

forge debug

NAME

forge-debug - Debug a single smart contract as a script.

SYNOPSIS

forge debug [options] path [args...]

DESCRIPTION

Debugs a single smart contract located in the source file (path) as a script.

If multiple contracts are in the specified source file, you must pass --target-contract to specify what contract you want to run.

Calls

After the script is deployed to the internal EVM a call is made to a function with the signature setUp(), if present.

By default, the script is assumed to be contained in a function with the signature run(). If you wish to run a different function, pass --sig <SIGNATURE>.

The signature can be a fragment (<function name>(<types>)), or raw calldata.

If you pass a fragment, and the function has parameters, you can add the call parameters to the end of the command (args).

Forking

It is possible to run the script in a forked environment by passing --fork-url <URL>.

When the script is running in a forked environment, you can access all the state of the forked chain as you would if you had deployed the script. Cheatcodes are still available.

You can also specify a block number to fork from by passing --fork-block-number <BLOCK>. When forking from a specific block, the chain data is cached to ~/.foundry/cache. If you do not want to cache the chain data, pass --no-storage-caching.

Debugging

It is possible to run the script in an interactive debugger. To start the debugger, pass --debug.

More information on the debugger can be found in the debugger chapter.

OPTIONS

Debug Options

--target-contract contract_name
    The name of the contract you want to run

-s signature
--sig signature
    The signature of the function you want to call in the contract, or raw calldata. Default: run()

--debug
    Open the script in the debugger.

EVM Options

-f url
--rpc-url url
--fork-url url
    Fetch state over a remote endpoint instead of starting from an empty state.

    If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block
    Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF>
     Initial retry backoff on encountering errors.

--no-storage-caching
    Explicitly disables the use of RPC caching.

    All storage slots are read entirely from the endpoint. See --fork-url.

-v
--verbosity
    Verbosity of the EVM.

    Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
    The address which will be executing tests

--initial-balance balance
    The initial balance of deployed contracts

--ffi
    Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
    The base fee in a block (in wei).

--block-coinbase address
    The coinbase of the block.

--block-difficulty difficulty
    The block difficulty.

--block-gas-limit gas_limit
    The block gas limit.

--block-number block
    The block number.

--block-timestamp timestamp
    The timestamp of the block (in seconds).

--chain-id chain_id
    The chain ID.

--gas-limit gas_limit
    The block gas limit.

--gas-price gas_price
    The gas price (in wei).

--tx-origin address
    The transaction origin.

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Execute the run() function in a contract:

   forge debug src/Contract.sol
   

2. Open a script in the debugger:

   forge debug src/Contract.sol --debug
   

3. Execute the foo() function in a contract:

   forge debug src/Contract.sol --sig "foo()"
   

4. Execute a contract with a function that takes parameters:

   forge debug src/Contract.sol --sig "foo(string,uint256)" "hello" 100
   

5. Execute a contract with raw calldata:

   forge debug src/Contract.sol --sig "0x..."
   

SEE ALSO

forge, forge test

forge bind

NAME

forge-bind - Generate Rust bindings for smart contracts.

SYNOPSIS

forge bind [options]

DESCRIPTION

Generates Rust bindings for smart contracts using ethers-rs.

The bindings are generated from the project's artifacts, which by default is ./out/. If you want to generate bindings for artifacts in a different directory, pass --bindings-path <PATH>.

There are three output options:

• Generate bindings in a crate (default)
• Generate bindings in a module by passing --module
• Generate bindings in a single file by passing --single-file

By default, the command will check that existing bindings are correct and exit accordingly. You can overwrite the existing bindings by passing --overwrite.

OPTIONS

Project Options

-b path
--bindings-path path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

--crate-name name
    The name of the Rust crate to generate, if you are generating a crate (default).
    This should be a valid crates.io crate name.

    Default: foundry-contracts

--crate-version semver
    The version of the Rust crate to generate, if you are generating a crate (default).
    This should be a standard semver version string.

    Default: 0.0.1

--module
    Generate the bindings as a module instead of a crate.

--single-file
    Generate bindings as a single file.

--overwrite
    Overwrite existing generated bindings. By default, the command will check that the bindings are correct, and then exit.
    If --overwrite is passed, it will instead delete and overwrite the bindings.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

--skip-cargo-toml
    Skip Cargo.toml consistency checks.
    This allows you to manage the ethers version without giving up on consistency checks.
    An example would be if you use additional features of ethers like ws, ipc, or rustls and get an ethers-providers version mismatch.

--skip-build
    Skips running forge build before generating binding.
    This allows you to skip the default forge build step that's executed first and instead generate bindings using the already existing artifacts.

--select-all
    By default all contracts ending with Test or Script are excluded. This will explicitly generate bindings for all contracts. Conflicts with --select and --skip.

--select regex+
    Create bindings only for contracts whose names match the specified filter(s). Conflicts with --skip.

--skip regex+
    Create bindings only for contracts whose names do not match the specified filter(s). Conflicts with --select.

Common Options

-h
--help
    Prints help information.

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

SEE ALSO

forge

forge cache

NAME

forge-cache - Manage the Foundry cache.

SYNOPSIS

forge cache [options] command [args]
forge cache [options] --version
forge cache [options] --help

DESCRIPTION

This program is a set of tools to manage the Foundry cache.

COMMANDS

forge cache clean
    Cleans cached data from ~/.foundry.

forge cache ls
    Shows cached data from ~/.foundry.

OPTIONS

Special Options

-V
--version
    Print version info and exit.

Common Options

-h
--help
    Prints help information.

forge cache clean

NAME

forge-cache-clean - Cleans cached data from ~/.foundry.

SYNOPSIS

forge cache clean [options] [--] [chains..]

DESCRIPTION

Removes files in the ~/.foundry/cache folder which is used to cache Etherscan verification status and block data.

OPTIONS

-b
--blocks
    One or more block numbers separated by comma with no spaces

--etherscan     A boolean flag that specifies to only remove the block explorer portion of the cache

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Remove the entire cache (also, forge cache clean is an alias for this)

   forge cache clean all
   

2. Remove the entire block explorer cache

   forge cache clean all --etherscan
   

3. Remove cache data for a specific chain, by name

   forge cache clean rinkeby
   

4. Remove cache data for a specific block number on a specific chain. Does not work if chain is all

   forge cache clean rinkeby -b 150000
   

5. Remove block explorer cache data for a specific chain. Does not work if --blocks are specified.

   forge cache clean rinkeby --etherscan
   

6. Specify multiple chains

   forge cache clean rinkeby mainnet
   

7. Specify multiple blocks

   forge cache clean rinkeby --blocks 530000,9000000,9200000
   

SEE ALSO

forge, forge cache

forge cache ls

NAME

forge-cache-ls - Shows cached data from ~/.foundry.

SYNOPSIS

forge cache ls [chains..]

DESCRIPTION

Lists what is in the ~/.foundry/cache folder currently.

OPTIONS

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Show the entire cache (also, forge cache ls is an alias for this)

   forge cache ls all
   

2. Show cache data for a specific chain, by name

   forge cache ls rinkeby
   

3. Specify multiple chains

   forge cache ls rinkeby mainnet
   

SEE ALSO

forge, forge cache

forge script

NAME

forge-script - Run a smart contract as a script, building transactions that can be sent onchain.

SYNOPSIS

forge script [options] path [args...]

DESCRIPTION

Run a smart contract as a script, building transactions that can be sent onchain.

Scripts can be used to apply state transitions on live contracts, or deploy and initialize a complex set of smart contracts using Solidity.

OPTIONS

--broadcast
    Broadcasts the transactions.

--debug
    Open the script in the debugger. Takes precedence over broadcast.

-g
--gas-estimate-multiplier multiplier
    Relative percentage by which to multiply all gas estimates. (i.e. set to 200 to double them)     Default: 130

--json
    Output results in JSON format.
    Note: The output is under development and prone to change.

--legacy
    Use legacy transactions instead of EIP1559 ones. This is auto-enabled for common networks without EIP1559.

--resume
    Resumes submitting transactions that failed or timed-out previously.

-s
--sig signature
    The signature of the function you want to call in the contract, or raw calldata.
    Default: run()

--skip-simulation
    Skips on-chain simulation.

--slow
    Makes sure a transaction is sent, only after its previous one has been confirmed and succeeded.

--target-contract contract_name
    The name of the contract you want to run.

--with-gas-price price
    Sets the gas price for broadcasted legacy transactions, or the max fee for broadcasted EIP1559 transactions.
    Note: To set the gas price in the execution environment of the script use --gas-price instead (see below).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Verification Options

--verify
    If it finds a matching broadcast log, it tries to verify every contract found in the receipts.

--verifier name
    The verification provider. Available options: etherscan, sourcify & blockscout. Default: etherscan.

--verifier-url url
    The optional verifier url for submitting the verification request.
    Environment: VERIFIER_URL

--delay delay
    Optional timeout to apply in between attempts in seconds. Defaults to 3.

--retries retries
    Number of attempts for retrying. Defaults to 15.

Cache Options

--force
    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

--via-ir
    Use the Yul intermediate representation compilation pipeline.

--revert-strings
    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
    Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

--silent
    Suppress all output.

Build Options

--names
    Print compiled contract names.

--sizes
    Print compiled non-test contract sizes, exiting with code 1 if any of them are above the size limit.

Watch Options

-w [path...]
--watch [path...]
    Watch specific file(s) or folder(s).

    By default, the project's source directory is watched.

-d delay
--delay delay
    File update debounce delay.

    During the delay, incoming change events are accumulated and only once the delay has passed, is an action taken.
    Note that this does not mean a command will be started: if --no-restart is given and a command is already running, the outcome of the action will be to do nothing.

    Defaults to 50ms. Parses as decimal seconds by default, but using an integer with the ms suffix may be more convenient.

    When using --poll mode, you'll want a larger duration, or risk overloading disk I/O.

--no-restart
    Do not restart the command while it's running.

--run-all
    Explicitly re-run the command on all files when a change is made.

Wallet Options - Raw

-i --interactives num
    Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
    Default: 0

--mnemonic-indexes indexes
    Use the private key from the given mnemonic index. Used with --mnemonic-path.
    Default: 0

--mnemonic-paths paths
    Use the mnemonic file at the specified path(s).

--private-key raw_private_key
    Use the provided private key.

--private-keys raw_private_keys
    Use the provided private keys.

Wallet Options - Keystore

--keystores paths
    Use the keystores in the given folders or files.
    Environment: ETH_KEYSTORE

--password passwords
    The keystore passwords. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
    Use a Trezor hardware wallet.

-l
--ledger
    Use a Ledger hardware wallet.

--hd-paths paths
    The derivation paths to use with hardware wallets.

Wallet Options - Remote

-a addresses
--froms addresses
    Sign the transaction with the specified accounts on the RPC.
    Environment: ETH_FROM

EVM Options

-f url
--rpc-url url
--fork-url url
    Fetch state over a remote endpoint instead of starting from an empty state.

    If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block
    Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF>
     Initial retry backoff on encountering errors.

--no-storage-caching
    Explicitly disables the use of RPC caching.

    All storage slots are read entirely from the endpoint. See --fork-url.

-v
--verbosity
    Verbosity of the EVM.

    Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
    The address which will be executing tests

--initial-balance balance
    The initial balance of deployed contracts

--ffi
    Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
    The base fee in a block (in wei).

--block-coinbase address
    The coinbase of the block.

--block-difficulty difficulty
    The block difficulty.

--block-gas-limit gas_limit
    The block gas limit.

--block-number block
    The block number.

--block-timestamp timestamp
    The timestamp of the block (in seconds).

--chain-id chain_id
    The chain ID.

--gas-limit gas_limit
    The block gas limit.

--gas-price gas_price
    The gas price (in wei).

--tx-origin address
    The transaction origin.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Run BroadcastTest as a script, broadcasting generated transactions on-chain

   forge script ./test/Broadcast.t.sol --tc BroadcastTest --sig "deploy()" \
       -vvv --fork-url $GOERLI_RPC_URL
   

2. Deploy a contract on Polygon (see scripting tutorial for an example script). The verifier url is different for every network.

   forge script script/NFT.s.sol:MyScript --chain-id 137 --rpc-url $RPC_URL \
       --etherscan-api-key $POLYGONSCAN_API_KEY --verifier-url https://api.polygonscan.com/api \
       --broadcast --verify -vvvv
   

3. Resume a failed script. Using the above as an example, remove --broadcast add --resume

   forge script script/NFT.s.sol:MyScript --chain-id 137 --rpc-url $RPC_URL \
       --etherscan-api-key $POLYGONSCAN_API_KEY --verifier-url https://api.polygonscan.com/api \
       --verify -vvvv --resume
   

4. Verify contracts that were just deployed with a script

   forge script script/NFT.s.sol --rpc-url $RPC_URL --verify --resume
   

forge upload-selectors

NAME

forge-upload-selectors - Uploads abi of given contract to https://sig.eth.samczsun.com function selector database.

SYNOPSIS

forge upload-selectors [options] contract

DESCRIPTION

Uploads abi of given contract to https://sig.eth.samczsun.com function selector database.

OPTIONS

Project Options

--build-info
    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

--hh
--hardhat
    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Upload ABI to selector database

   forge upload-selectors LinearVestingVault
   

forge doc

NAME

forge-doc - Generate documentation for Solidity source files.

SYNOPSIS

forge doc [options]

DESCRIPTION

Generates and builds an mdbook from Solidity source files.

OPTIONS

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

--out path     The output path for the generated mdbook. By default, it is the docs/ in project root.

--build     Build the mdbook from generated files.

--serve     Serve the documentation locally.

--hostname hostname     Hostname for serving documentation. Requires --serve.

--port port     Port for serving documentation. Requires --serve.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Generate documentation.

   forge doc
   

2. Generate and build documentation with specified output directory.

   forge doc --build --out ./documentation
   

3. Generate and serve documentation locally on port 4000.

   forge doc --serve --port 4000
   

SEE ALSO

Doc config

cast Commands

• General Commands
• Chain Commands
• Transaction Commands
• Block Commands
• Account Commands
• ENS Commands
• Etherscan Commands
• ABI Commands
• Conversion Commands
• Utility Commands
• Wallet Commands

General Commands

• cast
• cast help
• cast completions

cast

NAME

cast - Perform Ethereum RPC calls from the comfort of your command line.

SYNOPSIS

cast [options] command [args] cast [options] --version cast [options] --help

DESCRIPTION

This program is a set of tools to interact with Ethereum and perform conversions.

COMMANDS

General Commands

cast help     Display help information about Cast.

cast completions     Generate shell autocompletions for Cast.

Chain Commands

cast chain-id     Get the Ethereum chain ID.

cast chain     Get the symbolic name of the current chain.

cast client     Get the current client version.

Transaction Commands

cast publish     Publish a raw transaction to the network.

cast receipt     Get the transaction receipt for a transaction.

cast send     Sign and publish a transaction.

cast call     Perform a call on an account without publishing a transaction.

cast rpc      Perform a raw JSON-RPC request [aliases: rp]

cast tx     Get information about a transaction.

cast run     Runs a published transaction in a local environment and prints the trace.

cast estimate     Estimate the gas cost of a transaction.

cast access-list     Create an access list for a transaction.

cast logs     Get logs by signature or topic

Block Commands

cast find-block     Get the block number closest to the provided timestamp.

cast gas-price     Get the current gas price.

cast block-number     Get the latest block number.

cast basefee     Get the basefee of a block.

cast block     Get information about a block.

cast age     Get the timestamp of a block.

Account Commands

cast balance     Get the balance of an account in wei.

cast storage     Get the raw value of a contract's storage slot.

cast proof     Generate a storage proof for a given storage slot.

cast nonce     Get the nonce for an account.

cast code     Get the bytecode of a contract.

cast codesize     Get the runtime bytecode size of a contract.

ENS Commands

cast lookup-address     Perform an ENS reverse lookup.

cast resolve-name     Perform an ENS lookup.

cast namehash     Calculate the ENS namehash of a name.

Etherscan Commands

cast etherscan-source     Get the source code of a contract from Etherscan.

ABI Commands

cast abi-encode     ABI encode the given function arguments, excluding the selector.

cast 4byte     Get the function signatures for the given selector from https://sig.eth.samczsun.com.

cast 4byte-decode     Decode ABI-encoded calldata using https://sig.eth.samczsun.com.

cast 4byte-event     Get the event signature for a given topic 0 from https://sig.eth.samczsun.com.

cast calldata     ABI-encode a function with arguments.

cast pretty-calldata     Pretty print calldata.

cast --abi-decode     Decode ABI-encoded input or output data.

cast --calldata-decode     Decode ABI-encoded input data.

cast upload-signature     Upload the given signatures to https://sig.eth.samczsun.com.

Conversion Commands

cast --format-bytes32-string     Formats a string into bytes32 encoding.

cast --from-bin     Convert binary data into hex data.

cast --from-fix     Convert a fixed point number into an integer.

cast --from-utf8     Convert UTF8 to hex.

cast --parse-bytes32-string     Parses a string from bytes32 encoding.

cast --to-ascii     Convert hex data to an ASCII string.

cast --to-base     Convert a number of one base to another.

cast --to-bytes32     Right-pads hex data to 32 bytes.

cast --to-fix     Convert an integer into a fixed point number.

cast --to-hexdata     Normalize the input to lowercase, 0x-prefixed hex.

cast --to-int256     Convert a number to a hex-encoded int256.

cast --to-uint256     Convert a number to a hex-encoded uint256.

cast --to-unit     Convert an ETH amount into another unit (ether, gwei, wei).

cast --to-wei     Convert an ETH amount to wei.

cast shl     Perform a left shifting operation.

cast shr     Perform a right shifting operation.

Utility Commands

cast sig     Get the selector for a function.

cast sig-event     Generate event signatures from event string.

cast keccak     Hash arbitrary data using keccak-256.

cast compute-address     Compute the contract address from a given nonce and deployer address.

cast create2      Generate a deterministic contract address using CREATE2

cast interface     Generate a Solidity interface from a given ABI.

cast index     Compute the storage slot for an entry in a mapping.

cast --concat-hex     Concatenate hex strings.

cast --max-int     Get the maximum i256 value.

cast --min-int     Get the minimum i256 value.

cast --max-uint     Get the maximum u256 value.

cast --to-checksum-address     Convert an address to a checksummed format (EIP-55).

Wallet Commands

cast wallet     Wallet management utilities.

cast wallet new     Create a new random keypair.

cast wallet address     Convert a private key to an address.

cast wallet sign     Sign a message.

cast wallet vanity     Generate a vanity address.

cast wallet verify     Verify the signature of a message.

OPTIONS

Special Options

-V --version     Print version info and exit.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Call a function on a contract:

   cast call 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
     "balanceOf(address)(uint256)" 0x...
   

2. Decode raw calldata:

   cast --calldata-decode "transfer(address,uint256)" \
     0xa9059cbb000000000000000000000000e78388b4ce79068e89bf8aa7f218ef6b9ab0e9d0000000000000000000000000000000000000000000000000008a8e4b1a3d8000
   

3. Encode calldata:

   cast calldata "someFunc(address,uint256)" 0x... 1
   

BUGS

See https://github.com/foundry-rs/foundry/issues for issues.

cast help

NAME

cast-help - Get help for a Cast command

SYNOPSIS

cast help [subcommand]

DESCRIPTION

Prints a help message for the given command.

EXAMPLES

1. Get help for a command:

   cast help call
   

2. Help is also available with the --help flag:

   cast call --help
   

SEE ALSO

cast

cast completions

NAME

cast-completions - Generate shell completions script

SYNOPSIS

cast completions shell

DESCRIPTION

Generates a shell completions script for the given shell.

Supported shells are:

• bash
• elvish
• fish
• powershell
• zsh

OPTIONS

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Generate shell completions script for zsh:

   cast completions zsh > $HOME/.oh-my-zsh/completions/_cast
   

SEE ALSO

cast

Chain Commands

• cast chain-id
• cast chain
• cast client

cast chain-id

NAME

cast-chain-id - Get the Ethereum chain ID.

SYNOPSIS

cast chain-id [options]

DESCRIPTION

Get the Ethereum chain ID from the RPC endpoint we are connected to.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the chain ID when talking to $RPC:

   cast chain-id --rpc-url $RPC
   

2. Get the chain ID when $ETH_RPC_URL is set:

   cast chain-id
   

SEE ALSO

cast, cast chain

cast chain

NAME

cast-chain - Get the symbolic name of the current chain.

SYNOPSIS

cast chain [options]

DESCRIPTION

Get the symbolic chain name from the RPC endpoint we are connected to.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the chain name when talking to $RPC:

   cast chain --rpc-url $RPC
   

2. Get the chain name when $ETH_RPC_URL is set:

   cast chain
   

SEE ALSO

cast, cast chain-id

cast client

NAME

cast-client - Get the current client version.

SYNOPSIS

cast client [options]

DESCRIPTION

Get the current client version.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the current client version:

   cast client
   

SEE ALSO

cast

Transaction Commands

• cast publish
• cast receipt
• cast send
• cast call
• cast rpc
• cast tx
• cast run
• cast estimate
• cast access-list
• cast logs

cast publish

NAME

cast-publish - Publish a raw transaction to the network.

SYNOPSIS

cast publish [options] tx

DESCRIPTION

Publish a raw pre-signed transaction to the network.

OPTIONS

Publish Options

--async
--cast-async
    Do not wait for a transaction receipt.
    Environment: CAST_ASYNC

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Publish a pre-signed transaction:

   cast publish --rpc-url $RPC $TX
   

2. Publish a pre-signed transaction with flashbots.

   cast publish --flashbots $TX
   

SEE ALSO

cast, cast call, cast send, cast receipt

cast receipt

NAME

cast-receipt - Get the transaction receipt for a transaction.

SYNOPSIS

cast receipt [options] tx_hash [field]

DESCRIPTION

Get the transaction receipt for a transaction.

If field is specified, then only the given field of the receipt is displayed.

OPTIONS

Receipt Options

--async
--cast-async
    Do not wait for the transaction receipt if it does not exist yet.
    Environment: CAST_ASYNC

-c confirmations
--confirmations confirmations
    Wait a number of confirmations before exiting. Default: 1.

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Display Options

-j
--json
     Print the deployment information as JSON.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get a transaction receipt:

   cast receipt $TX_HASH
   

2. Get the block number the transaction was included in:

   cast receipt $TX_HASH blockNumber
   

SEE ALSO

cast, cast call, cast send, cast publish

cast send

NAME

cast-send - Sign and publish a transaction.

SYNOPSIS

cast send [options] to [sig] [args...]

DESCRIPTION

Sign and publish a transaction.

The destination (to) can be an ENS name or an address.

The signature (sig) can be:

• A fragment: someFunction(uint256,bytes32)
• A selector and encoded calldata: 0xcdba2fd40000000000000000000000000000000000000000000000000000000000007a69
• Only the function name: in this case Cast will try to fetch the function signature from Etherscan

OPTIONS

Transaction Options

--gas-limit gas_limit
    Gas limit for the transaction.

--gas-price price
    Gas price for the transaction, or max fee per gas for EIP1559 transactions.

--priority-gas-price price
    Max priority fee per gas for EIP1559 transactions.

--value value
    Ether to send in the transaction.

    Either specified as an integer (wei), or as a string with a unit, for example:
    - 1ether
    - 10gwei
    - 0.01ether

--nonce nonce
    Nonce for the transaction.

--legacy
    Send a legacy transaction instead of an EIP1559 transaction.

    This is automatically enabled for common networks without EIP1559.

--resend
    Reuse the latest nonce of the sending account.

--create code [sig args...]
    Deploy a contract by specifying raw bytecode, in place of specifying a to address.

Receipt Options

--async
--cast-async
    Do not wait for the transaction receipt if it does not exist yet.
    Environment: CAST_ASYNC

-c confirmations
--confirmations confirmations
    Wait a number of confirmations before exiting. Default: 1.

WALLET OPTIONS - RAW:

-i
--interactive <NUM>
     Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
     Defaults to 0.

--mnemonic-derivation-path <PATHS>
     The wallet derivation path. Works with both --mnemonic-path and hardware wallets.

--mnemonic-indexes <INDEXES>
     Use the private key from the given mnemonic index. Used with --mnemonic-paths.
     Defaults to 0.

--mnemonic-passphrase <PASSPHRASE>
     Use a BIP39 passphrases for the mnemonic.

--mnemonic <PATHS>
     Use the mnemonic phrases or mnemonic files at the specified paths.

--private-key <RAW_PRIVATE_KEY>
     Use the provided private key.

--private-keys <RAW_PRIVATE_KEYS>
     Use the provided private keys.

Wallet Options - Keystore

--keystore path
    Use the keystore in the given folder or file.
    Environment: ETH_KEYSTORE

--password password
    The keystore password. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
    Use a Trezor hardware wallet.

-l
--ledger
    Use a Ledger hardware wallet.

Wallet Options - Remote

-f address
--from address
    Sign the transaction with the specified account on the RPC.
    Environment: ETH_FROM

--unlocked
    Send via eth_sendTransaction using the --from argument or $ETH_FROM as sender.

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Display Options

-j
--json
     Print the deployment information as JSON.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Send some ether to Vitalik using your Ledger:

   cast send --ledger vitalik.eth --value 0.1ether
   

2. Call deposit(address token, uint256 amount) on a contract:

   cast send --ledger 0x... "deposit(address,uint256)" 0x... 1
   

3. Call a function that expects a struct:

   contract Test {
       struct MyStruct {
           address addr;
           uint256 amount;
       }
       function myfunction(MyStruct memory t) public pure {}
   }
   

   Structs are encoded as tuples (see struct encoding)

   cast send 0x... "myfunction((address,uint256))" "(0x...,1)"
   

SEE ALSO

cast, cast call, cast publish, cast receipt, struct encoding

cast call

NAME

cast-call - Perform a call on an account without publishing a transaction.

SYNOPSIS

cast call [options] to sig [args...]

DESCRIPTION

Perform a call on an account without publishing a transaction.

The destination (to) can be an ENS name or an address.

The signature (sig) can be:

• A fragment: someFunction(uint256,bytes32)
• A selector and encoded calldata: 0xcdba2fd40000000000000000000000000000000000000000000000000000000000007a69
• Only the function name: in this case Cast will try to fetch the function signature from Etherscan

OPTIONS

Query Options

-B block
--block block
    The block height you want to query at.

    Can be a block number, or any of the tags: earliest, finalized, safe, latest or pending.

WALLET OPTIONS - RAW:

-i
--interactive <NUM>
     Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
     Defaults to 0.

--mnemonic-derivation-path <PATHS>
     The wallet derivation path. Works with both --mnemonic-path and hardware wallets.

--mnemonic-indexes <INDEXES>
     Use the private key from the given mnemonic index. Used with --mnemonic-paths.
     Defaults to 0.

--mnemonic-passphrase <PASSPHRASE>
     Use a BIP39 passphrases for the mnemonic.

--mnemonic <PATHS>
     Use the mnemonic phrases or mnemonic files at the specified paths.

--private-key <RAW_PRIVATE_KEY>
     Use the provided private key.

--private-keys <RAW_PRIVATE_KEYS>
     Use the provided private keys.

Wallet Options - Keystore

--keystore path
    Use the keystore in the given folder or file.
    Environment: ETH_KEYSTORE

--password password
    The keystore password. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
    Use a Trezor hardware wallet.

-l
--ledger
    Use a Ledger hardware wallet.

Wallet Options - Remote

-f address
--from address
    Sign the transaction with the specified account on the RPC.
    Environment: ETH_FROM

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Call balanceOf(address) on the WETH contract:

   cast call 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
     "balanceOf(address)(uint256)" 0x...
   

2. Call tokenURI(uint256)(string) on the Tubby Cats NFT contract:

   export CONTRACT=0xca7ca7bcc765f77339be2d648ba53ce9c8a262bd
   export TOKEN_ID=19938
   cast call $CONTRACT "tokenURI(uint256)(string)" $TOKEN_ID
   

3. Call getAmountsOut(uint,address[]) on the Uniswap v2 router contract:

   cast call 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D \
    "getAmountsOut(uint,address[])" 1 "[0x6b...0f,0xc0...c2]"
   

SEE ALSO

cast, cast send, cast publish, cast receipt

cast rpc

NAME

cast-rpc - Perform a raw JSON-RPC request

SYNOPSIS

cast rpc [options] METHOD [PARAMS...]

DESCRIPTION

Perform a simple JSON-RPC POST request for the given method and with the params

OPTIONS

Query Options

-r url
--rpc-url url
    The URL of the provider

-w
--raw
    Pass the "params" as is      If --raw is passed the first PARAM will be taken as the value of "params". If no params are given, stdin will be used. For example:      rpc eth_getBlockByNumber '["0x123", false]' --raw      => {"method": "eth_getBlockByNumber", "params": ["0x123", false] ... }

EXAMPLES

1. Get latest eth_getBlockByNumber on localhost:

   cast rpc eth_getBlockByNumber "latest" "false"
   

2. Get eth_getTransactionByHash on localhost:

   cast rpc eth_getTransactionByHash 0x2642e960d3150244e298d52b5b0f024782253e6d0b2c9a01dd4858f7b4665a3f
   

3. Get latest eth_getBlockByNumber on etherum mainnet:

   cast rpc --rpc-url https://mainnet.infura.io/v3/ eth_getBlockByNumber "latest" "false"
   

cast tx

NAME

cast-tx - Get information about a transaction.

SYNOPSIS

cast tx [options] tx_hash [field]

DESCRIPTION

Get information about a transaction.

If field is specified, then only the given field of the transaction is displayed.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Display Options

-j
--json
     Print the deployment information as JSON.

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get information about a transaction:

   cast tx $TX_HASH
   

2. Get the sender of a transaction:

   cast tx $TX_HASH from
   

SEE ALSO

cast, cast receipt

cast run

NAME

cast-run - Runs a published transaction in a local environment and prints the trace.

SYNOPSIS

cast run [options] --rpc-url url tx_hash

DESCRIPTION

Runs a published transaction in a local environment and prints the trace.

By default, all transactions in the block prior to the transaction you want to replay are also replayed. If you want a quicker result, you can use --quick, however, results may differ from the live execution.

You can also open the transaction in a debugger by passing --debug.

OPTIONS

Run Options

--label label
    Labels an address in the trace.
    The format is <address>:<label>. Can be passed multiple times.

-q
--quick
    Executes the transaction only with the state from the previous block.
    May result in different results than the live execution!

-v
--verbose
    Addresses are fully displayed instead of being truncated.

-d
--debug
    Open the script in the debugger.

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Replay a transaction (a simple transfer):

   cast run 0xd15e0237413d7b824b784e1bbc3926e52f4726e5e5af30418803b8b327b4f8ca
   

2. Replay a transaction, applied on top of the state of the previous block:

   cast run --quick \
     0xd15e0237413d7b824b784e1bbc3926e52f4726e5e5af30418803b8b327b4f8ca
   

3. Replay a transaction with address labels:

   cast run \
     --label 0xc564ee9f21ed8a2d8e7e76c085740d5e4c5fafbe:sender \
     --label 0x40950267d12e979ad42974be5ac9a7e452f9505e:recipient \
     --label 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:weth \
     0xd15e0237413d7b824b784e1bbc3926e52f4726e5e5af30418803b8b327b4f8ca
   

4. Replay a transaction in the debugger:

   cast run --debug \
     0xd15e0237413d7b824b784e1bbc3926e52f4726e5e5af30418803b8b327b4f8ca
   

SEE ALSO

cast

cast estimate

NAME

cast-estimate - Estimate the gas cost of a transaction.

SYNOPSIS

cast estimate [options] to sig [args...]

DESCRIPTION

Estimate the gas cost of a transaction.

The destination (to) can be an ENS name or an address.

The signature (sig) can be:

• A fragment: someFunction(uint256,bytes32)
• A selector and encoded calldata: 0xcdba2fd40000000000000000000000000000000000000000000000000000000000007a69
• Only the function name: in this case Cast will try to fetch the function signature from Etherscan

OPTIONS

Transaction Options

--value value
    Ether to send in the transaction.

    Either specified as an integer (wei), or as a string with a unit, for example:
    - 1ether
    - 10gwei
    - 0.01ether

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Estimate the gas cost of calling deposit() on the WETH contract:

   cast estimate 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
     --value 0.1ether "deposit()"
   

SEE ALSO

cast, cast send, cast publish, cast receipt

cast access-list

NAME

cast-access-list - Create an access list for a transaction.

SYNOPSIS

cast access-list [options] to sig [args...]

DESCRIPTION

Create an access list for a transaction.

The destination (to) can be an ENS name or an address.

The signature (sig) can be:

• A fragment: someFunction(uint256,bytes32)
• A selector and encoded calldata: 0xcdba2fd40000000000000000000000000000000000000000000000000000000000007a69
• Only the function name: in this case Cast will try to fetch the function signature from Etherscan

OPTIONS

Query Options

-B block
--block block
    The block height you want to query at.

    Can be a block number, or any of the tags: earliest, finalized, safe, latest or pending.

WALLET OPTIONS - RAW:

-i
--interactive <NUM>
     Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
     Defaults to 0.

--mnemonic-derivation-path <PATHS>
     The wallet derivation path. Works with both --mnemonic-path and hardware wallets.

--mnemonic-indexes <INDEXES>
     Use the private key from the given mnemonic index. Used with --mnemonic-paths.
     Defaults to 0.

--mnemonic-passphrase <PASSPHRASE>
     Use a BIP39 passphrases for the mnemonic.

--mnemonic <PATHS>
     Use the mnemonic phrases or mnemonic files at the specified paths.

--private-key <RAW_PRIVATE_KEY>
     Use the provided private key.

--private-keys <RAW_PRIVATE_KEYS>
     Use the provided private keys.

Wallet Options - Keystore

--keystore path
    Use the keystore in the given folder or file.
    Environment: ETH_KEYSTORE

--password password
    The keystore password. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
    Use a Trezor hardware wallet.

-l
--ledger
    Use a Ledger hardware wallet.

Wallet Options - Remote

-f address
--from address
    Sign the transaction with the specified account on the RPC.
    Environment: ETH_FROM

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Common Options

-h
--help
    Prints help information.

SEE ALSO

cast, cast send, cast publish, cast call

cast logs

NAME

cast logs - Get logs by signature or topic.

SYNOPSIS

cast logs [options] sig_or_topic [topics_or_args...]

DESCRIPTION

Get logs by signature or topic.

The (sig_or_topic) may either be the event signature or its hashed topic (located at topics[0]).

If using a signature, remaining arguments must be in their ordinary form. If using a topic, the arguments must be as they themselves appear as topics.

OPTIONS

Query Options

--from-block from_block     The block height to start query at.

    Can also be the tags: earliest, finalized, safe, latest, or pending.

--to-block to_block     The block height to stop query at.

    Can also be the tags: earliest, finalized, safe, latest, or pending.

--address address     The contract address to filter on

WALLET OPTIONS - RAW:

-i
--interactive <NUM>
     Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
     Defaults to 0.

--mnemonic-derivation-path <PATHS>
     The wallet derivation path. Works with both --mnemonic-path and hardware wallets.

--mnemonic-indexes <INDEXES>
     Use the private key from the given mnemonic index. Used with --mnemonic-paths.
     Defaults to 0.

--mnemonic-passphrase <PASSPHRASE>
     Use a BIP39 passphrases for the mnemonic.

--mnemonic <PATHS>
     Use the mnemonic phrases or mnemonic files at the specified paths.

--private-key <RAW_PRIVATE_KEY>
     Use the provided private key.

--private-keys <RAW_PRIVATE_KEYS>
     Use the provided private keys.

Wallet Options - Keystore

--keystore path
    Use the keystore in the given folder or file.
    Environment: ETH_KEYSTORE

--password password
    The keystore password. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
    Use a Trezor hardware wallet.

-l
--ledger
    Use a Ledger hardware wallet.

Wallet Options - Remote

-f address
--from address
    Sign the transaction with the specified account on the RPC.
    Environment: ETH_FROM

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

--flashbots
    Use the Flashbots RPC URL (https://rpc.flashbots.net).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

EXAMPLES

1. Get logs using a signature:

   cast logs --from-block 15537393 --to-block latest 'Transfer (address indexed from, address indexed to, uint256 value)' 0x2e8ABfE042886E4938201101A63730D04F160A82
   

2. Get logs using a topic:

   cast logs --from-block 15537393 --to-block latest 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef 0x0000000000000000000000002e8abfe042886e4938201101a63730d04f160a82
   

SEE ALSO

cast

Block Commands

• cast find-block
• cast gas-price
• cast block-number
• cast basefee
• cast block
• cast age

cast find-block

NAME

cast-find-block - Get the block number closest to the provided timestamp.

SYNOPSIS

cast find-block [options] timestamp

DESCRIPTION

Get the block number closest to the provided timestamp.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the block number closest to New Years 2021

   cast find-block 1609459200
   

SEE ALSO

cast

cast gas-price

NAME

cast-gas-price - Get the current gas price.

SYNOPSIS

cast gas-price [options]

DESCRIPTION

Get the current gas price.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the current gas price:

   cast gas-price
   

SEE ALSO

cast, cast basefee

cast block-number

NAME

cast-block-number - Get the latest block number.

SYNOPSIS

cast block-number [options]

DESCRIPTION

Get the latest block number.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the latest block number:

   cast block-number
   

SEE ALSO

cast, cast block

cast basefee

NAME

cast-base-fee - Get the basefee of a block.

SYNOPSIS

cast base-fee [options] [block]

DESCRIPTION

Get the basefee of a block.

The specified block can be a block number, or any of the tags: earliest, finalized, safe, latest or pending. Default to latest.

OPTIONS

RPC Options

--rpc-url url
    The RPC endpoint. Accepts a URL or an existing alias in the [rpc_endpoints] table, like mainnet.     Environment: ETH_RPC_URL

Common Options

-h
--help
    Prints help information.

EXAMPLES

1. Get the basefee of the latest block:

   cast base-fee
   

2. Get the basefee of the genesis block:

   cast base-fee 1