/foundry

Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.

Primary LanguageRustApache License 2.0Apache-2.0

foundry

Github Actions Telegram Chat Crates.io

Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.

Foundry consists of:

  • Forge: Ethereum testing framework (like Truffle, Hardhat and Dapptools).
  • Cast: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.

demo

Installation

First run the command below to get foundryup, the Foundry toolchain installer:

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

Then in a new terminal session or after reloading your PATH, run it to get the latest forge and cast binaries:

foundryup

Advanced ways to use foundryup and other documentation can be found in the foundryup package. Happy forging!

Libusb error when running forge/cast

If you are using the binaries as released, you may see the following error on MacOS:

dyld: Library not loaded: /usr/local/opt/libusb/lib/libusb-1.0.0.dylib

In order to fix this, you must install libusb like so:

brew install libusb

Forge

More documentation can be found in the forge package and in the CLI README.

Features

  1. Fast & flexible compilation pipeline:
    1. Automatic Solidity compiler version detection & installation (under ~/.svm)
    2. Incremental compilation & caching: Only changed files are re-compiled
    3. Parallel compilation
    4. Non-standard directory structures support (e.g. can build Hardhat repos)
  2. Tests are written in Solidity (like in DappTools)
  3. Fast fuzz Tests with shrinking of inputs & printing of counter-examples
  4. Fast remote RPC forking mode leveraging Rust's async infrastructure like tokio
  5. Flexible debug logging:
    1. Dapptools-style, using DsTest's emitted logs
    2. Hardhat-style, using the popular console.sol contract
  6. Portable (5-10MB) & easy to install statically linked binary without requiring Nix or any other package manager
  7. Abstracted over EVM implementations (currently supported: Sputnik, EvmOdin)

How Fast?

Forge is quite fast at both compiling (leveraging the ethers-solc package) and testing.

Some benchmarks below:

Project Forge DappTools Speedup
guni-lev 28.6s 2m36s 5.45x
solmate 6s 46s 7.66x
geb 11s 40s 3.63x
vaults 1.4s 5.5s 3.9x

It also works with "non-standard" directory structures (i.e. contracts not in src/, libraries not in lib/). When tested with openzeppelin-contracts, Hardhat compilation took 15.244s, whereas Forge took 9.449 (~4s cached)

Cast

Cast is a swiss army knife for interacting with Ethereum applications from the command line.

More documentation can be found in the cast package.

Setup

Configuring foundry/forge

foundry is designed to be very configurable. You can create a TOML file called foundry.toml place it in the project or any other parent directory, and it will apply the options in that file. See Config Readme for all available options.

Configurations can be arbitrarily namespaced by profiles. Foundry's default configuration is also named default. The selected profile is the value of the FOUNDRY_PROFILE environment variable, or if it is not set, "default". FOUNDRY_ or DAPP_ prefixed environment variables, like FOUNDRY_SRC take precedence, see Default Profile

forge init creates a basic, extendable foundry.toml file.

To set all .dapprc env vars run source .dapprc beforehand.

To see all currently set options run forge config, to only see the basic options (as set with forge init) run forge config --basic, this can be used to create a new foundry.toml file with forge config --basic > foundry.toml. By default forge config shows the currently selected foundry profile and its values. It also accepts the same arguments as forge build.

VSCode

juanfranblanco/vscode-solidity describes in detail how to configure the vscode extension.

If you're using dependency libraries, then you'll need _ Remappings_ so the extension can find the imports.

The easiest way to add remappings is creating a remappings.txt file in the root folder, which can be generated with auto inferred remappings:

forge remappings > remappings.txt

See also ./cli/README.md.

Alternatively you can use the extension's dir structure settings to configure your contracts and dependency directory. If your contracts are stored in ./src and libraries in ./lib, you can add

"solidity.packageDefaultDependenciesContractsDirectory": "src",
"solidity.packageDefaultDependenciesDirectory": "lib"

to your .vscode file

It's also recommended to specify a solc compiler version for the extension, read more:

"solidity.compileUsingRemoteVersion": "v0.8.10"

Autocompletion

You can generate autocompletion shell scripts for bash, elvish, fish, powershell, and zsh.

Example (zsh / oh-my-zsh)

mkdir -p ~/.oh-my-zsh/completions
forge completions zsh > ~/.oh-my-zsh/completions/_forge
cast completions zsh > ~/.oh-my-zsh/completions/_cast
source ~/.zshrc

Contributing

Directory structure

This repository contains several Rust crates:

  • forge: Library for building and testing a Solidity repository.
  • cast: Library for interacting with a live Ethereum JSON-RPC compatible node, or for parsing data.
  • cli: Command line interfaces to cast and forge.
  • evm-adapters: Unified layer of abstraction over multiple EVM types. Currently supported EVMs: Sputnik, Evmodin.
  • utils: Utilities for parsing ABI data, will eventually be upstreamed to ethers-rs.

Rust Toolchain

We use the stable Rust toolchain. Install by running: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh.

Minimum Supported Rust Version

The current minimum supported Rust version is rustc 1.54.0 (a178d0322 2021-07-26).

Testing

cargo check
cargo test
cargo doc --open

Formatting

We use the nightly toolchain for formatting and linting.

cargo +nightly fmt
cargo +nightly clippy --all-features -- -D warnings

Getting Help

First, see if the answer to your question can be found in the API documentation. If the answer is not there, try opening an issue with the question.

To join the Foundry community, you can use our main telegram to chat with us!

To receive help with Foundry, you can use our support telegram to asky any questions you may have.

Acknowledgements

  • Foundry is a clean-room rewrite of the testing framework dapptools. None of this would have been possible without the DappHub team's work over the years.
  • Matthias Seitz: Created ethers-solc which is the backbone of our compilation pipeline, as well as countless contributions to ethers, in particular the abigen macros.
  • Rohit Narurkar: Created the Rust Solidity version manager svm-rs which we use to auto-detect and manage multiple Solidity versions.
  • Brock Elmore: For extending the VM's cheatcodes and implementing structured call tracing, a critical feature for debugging smart contract calls.
  • All the other contributors to the ethers-rs & foundry repositories and chatrooms.