foundry-rs/book

A book on all things Foundry, available at https://book.getfoundry.sh.

📖 Foundry Book

A book on all things Foundry. Read now.

Contributing

Check our contributing guidelines. Feel free to contribute wording, sentences, chapters, and guides!

The book is build with mdbook, which you can get by running cargo install mdbook.

The book also requires mdbook-external-links: cargo install mdbook-external-links.

To see the book change live run:

mdbook serve

To run the book with docker, run:

docker run -p 3000:3000 -v `pwd`:/book peaceiris/mdbook serve

To add a new section (file) to the book, add it to SUMMARY.md.

For a more structured overview of the current issues, see the GitHub project.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Zero Ekkusu 📖 👀 🚧	Rootul Patel 📖 🚧 👀	zk-tarts 📖	Nicholas 📖	metehan 📖	Harris 🚧	Rajesh Muppalla 🚧
Matt Solomon 📖	Ruvaag 🚧	awolff 🚧	kayaba-attribution 📖	Noah Citron 👀	Sabnock 📖	Ikko Ashimine 🚧
Ed Mazurek 🚧	devtooligan 🚧 📖	0xfoobar 📖	odyslam.eth 🚧	FredCoen ✅	bblanc42 📖	0xMySt1c 🚧
Bjerg 🚧 📖 👀	Georgios Konstantopoulos 👀	Devan Non 📖	josht 🚧	dmfxyz 🚧 👀 📖	Drake Evans 🚧	Paul Razvan Berg 🚧
Perelyn Sama 🚧 📖	N 📖	John Adler 🚧	0xTaylor 🚧	0xCookedRice 🚧	Dan Hepworth 🚧	tobias 🚧
anticlimactic 🚧 📖	Pedro Maia 📖	Erick 🚧	Will Minshew 📖	Dave Belvedere 🚧	A.L. 🚧	p0n1 🚧
Rohan Kulkarni 🚧	Galmoli 🚧	Tom 🚧	Andrey Leutwiler Gomes 🚧 📖	Joshua Trujillo 📖	calnix 📖	Matthias Seitz 🚧 📖
xaaru 🚧	Wias Liaw 🚧	Shawn Harmsen 📖 🚧	Ward Bradt 🚧	ｓｉｇｈ 📖	James Bachini 🚧	Zach Obront 🚧
Scott Tsai 🚧	Kristian Quirapas 🚧	Bruno Filetti 📖	Pranesh A S 🚧	0xYYY 📖	Julian Martinez 🚧	Tirth Patel 🚧
Nader Dabit 🚧	h00p30 📖	beskay 🚧	fangjun 🚧	Bento Box 📖	appleseed-iii 📖	soyboy 📖
double v 👀	skaunov 🚧	t11s 🚧	Murphy Law 📖	Arbiter 📖	neodaoist 📖	minaminao 🚧
Fidel Ramos 🚧	Elijah Sullivan 📖	m0ham3dx 🚧	Yuqi Liu 🚧	ControlCplusControlV 🚧	Charles Azanlekor 🚧	Abhi Gulati 🚧
Karim Helmy 🚧	HashHaran 📖	omahs 🚧	Franfran 📖	DaniPopes 🚧	Stijn Balk 📖	Salief Lewis 📖
ryzhak 📖	Enrique Ortiz 📖	Massimiliano Tomassoli 📖	mr-roh 📖	Chirag Baghasingh 📖	Amin Bashiri 📖	ibremseth 📖
Alexe Luca Spataru 📖	Riley 📖	Yotam Bar-On 📖	Tudor 📖	Chris Cushman 📖	ernestor.eth 📖	Asir Shahriar Roudra 📖
stitetsati 📖	William Cheung 💻	Zhuo Zhang 💻	Anton Totomanov 💻

This project follows the all-contributors specification.

book's Issues

Add Awesome Foundry to list of resources

Awesome Foundry has a list of projects, tools, and libraries that use Foundry, that can be used as learning material for people wanting to see code.

https://github.com/crisgarner/awesome-foundry

Improve command references

I think we should consider restructuring the command references to be more in line with something like Cargo's book. Their documentation is really good.

Document `cast compute-address`

PR: foundry-rs/foundry#862
Issue: foundry-rs/foundry#861

Features that need to be released before the book

Fixes

• foundry-rs/foundry#482

Features

• foundry-rs/foundry#291

Add license

Which one?

Add section on discarding fuzzer inputs

In our fuzzing guide we should make use of vm.assume, or at least have a section dedicated to it, as it is the preferred tool to discard fuzzer inputs.

Ref: #37 / #60

Document `forge run`

This is the original PR, but it might have changed a bit since then - most notably the debugger is accessible only through this command for the time being.

DSTest examples might be incorrect

File: ds-test.md

Issue: The docs might be incorrect

Getting TypeError: No unique declaration found after argument-dependent lookup. when an int_const is passed to an assertion function.

// function assertEq(uint a, uint b) internal;
assertEq(1 ether, 1e18 wei);

Meanwhile, logging works fine:

// event log_uint(uint);
emit log_uint(1 ether);

Solution: I will fix the docs if others are getting the same error.

Document additional optimizer settings

See the docs and PRs foundry-rs/foundry#795 / foundry-rs/foundry#678

Micro tasks

Any small inconsistencies I've noticed, which anyone can fix:

• add example for getCode cheatcode
• add example for ffi cheatcode
• beautify prank cheatcode example and add ##### Example heading
• clarify or simplify expectCall cheatcode example
• fix errors at the begging of ds-test.md
• make examples in writing-tests.md consistent
• beautify cheatcodes.md to be cleaner and easier to read and navigate
• fix the look (style) of ds-test.md
• reorder cheatcodes in the reference docs? see this comment

Document `cast proof`

See foundry-rs/foundry#722

No guidance on how to import "cheats.expectRevert"

While reading the Writing Tests chapter, I stumbled upon the following code snippet:

function testCannotSubtract43() public {
    cheats.expectRevert(abi.encodeWithSignature("Panic(uint256)", 0x11));
    testNumber -= 43;
}

I tried to run it but I got the following error:

Error:
   0: Compiler run failed
      DeclarationError: Undeclared identifier.
        --> /Users/paulrberg/workspace/templates/foundry-template/test/Contract.t.sol:22:9:
         |
      22 |         cheats.expectRevert(abi.encodeWithSignature("Panic(uint256)", 0x11));
         |         ^^^^^^

It looks like the docs are not showing how to import and initialize the cheats when first mentioning them.

Add note about `extcodesize` for `vm.mockCall`

If you mock a call on an address with no code the call might fail regardless because Solidity does an extcodesize check before calls under normal circumstances. Can be fixed by using vm.etch in tandem

Write a guide on migrating from Hardhat

We should add a guide on how to convert an existing codebase from Hardhat to Foundry over time.

Tracing notes

• New contracts are yellow
• Logs are cyan

Document `forge run` with arguments

See foundry-rs/foundry#920 (comment)

Document `cast index`

See foundry-rs/foundry#676

Document `cast pretty-calldata`

See foundry-rs/foundry#764

Document new gas reports

Ref: foundry-rs/foundry#637

Automate some documentation

It would be nice to automate some parts of the documentation, such as the overall reference for cast, forge and the output of specific commands. This will require some scripts, and it might be possible to use the output of forge --help/cast --help or rustdoc in some way.

We still want to retain examples and so on, so it will require some thinking. If this can be pulled off, it would mean that some documentation is essentially written by improving the output of the help commands on the relevant commands upstream in Foundry, which will increase the quality of those

Document contract verification

See foundry-rs/foundry#695

Chapters on upcoming features

We should add chapters on the following features when they are released:

Landed recently:

• #38
• #31
• #39

Coming later:

• Coverage reports
• Invariant tests
• Symbolic testing
• Mutation testing
• Documentation generation
• Deployment system

Switch host

The book should probably be deployed to Netlify or Vercel so we can have previews in pull requests

Document new `label` cheatcode

Ref: foundry-rs/foundry#629

Document `--match-path` and `--no-match-path` for `forge test`

See foundry-rs/foundry#662

The relevant file this should be updated in is ./src/forge/tests.md

Document the new formatter

See foundry-rs/foundry#201

It is a pretty barebones opinionated formatter with write and diff capabilities, but it is not configurable. Regardless, we should document it (and also add it to the GHA example)

Book restructuring

I want to restructure the book a bit by including section headers, draft chapters and removing some chapters that just take up space.

Draft SUMMARY.md:

# Summary

[Introduction](./README.md)

# Getting Started

- [Installation](./getting-started/installation.md)
- [First Steps with Foundry](./getting-started/first-steps.md)

# Forge Overview

- [What is Forge?](./forge/README.md)
- [Projects]()
  - [Creating a New Project](./forge/creating-a-new-project.md)
  - [Working on an Existing Project](./forge/working-on-an-existing-project.md)
  - [Dependencies](./forge/dependencies.md)
  - [Project Layout](./forge/project-layout.md)
  - [Configuring with `foundry.toml`](./forge/config.md)
- [Tests](./forge/tests.md)
  - [Writing Tests](./forge/writing-tests.md)
  - [Cheatcodes](./forge/cheatcodes.md)
  - [Understanding Traces](./forge/traces.md)
  - [Forking Mode](./forge/forking-mode.md)
  - [Coverage Reports]()
- [Advanced Testing](./forge/advanced-testing.md)
  - [Fuzz Testing](./forge/fuzz-testing.md)
  - [Invariant Testing]()
  - [Symbolic Testing]()
  - [Table Testing]()
  - [Mutation Testing]()
- [Linting and Formatting]()
- [Generating Documentation]()
- [Deploying and Verifying](./forge/deploying.md)
- [Gas Tracking](./forge/gas-tracking.md)
  - [Gas Reports]()
  - [Gas Snapshots]()
- [Debugger](./forge/debugger.md)

# Cast Overview

- [What is Cast?](./cast/cast-overview.md)

# Additional Configuration

- [Integrating with VSCode](./guides/vscode.md)
- [Shell Autocompletion](./guides/shell-autocompletion.md)
- [Continuous Integration](./forge/continous-integration.md)

# Tutorials

- [Creating an NFT with Solmate and Foundry](./tutorials/solmate-nft.md)
- [Incremental Adoption]()

# References

- [`forge` Reference]()
- [`cast` Reference](./reference/cast.md)
- [`foundry.toml` Reference](./reference/config.md)
- [`ds-test` Reference](./reference/ds-test.md)
- [Cheatcodes Reference](./reference/cheatcodes.md)

Document `forge inspect`

See these PRs:

• Implementation: foundry-rs/foundry#873
• Docs: foundry-rs/foundry#901

And this issue: foundry-rs/foundry#859

Add Test Contract address to foundry.toml Reference

Test contracts are deployed to 0xb4c79dab8f259c7aee6e5b2aa729821864227e84, but this address is not listed in the config.md reference.

A quick test confirms this is the deploy address.

//SPDX-License-Identifier: UNLICENSED
pragma solidity >=0.8.0 <0.9.0;

import "ds-test/test.sol";

contract JustChecking is DSTest{
    function testDeployer() public {
        emit log_named_address("msg.sender", msg.sender);
        emit log_named_address("tx.origin", tx.origin);
        emit log_named_address("this", address(this));
    }
}

Output

Logs:
  msg.sender: 0x00a329c0648769a73afac7f9381e08fb43dbea72
  tx.origin: 0x00a329c0648769a73afac7f9381e08fb43dbea72
  this: 0xb4c79dab8f259c7aee6e5b2aa729821864227e84

I do not know if there is an environment variable in Forge to control the test deploy address. In DS-Test this environment variable is called DAPP_TEST_ADDRESS (see here).

It is useful to have this address somewhere in the documentation because this contract is the default owner of contracts deployed by the test.

Document `cast find-block`

See foundry-rs/foundry#766

Document `cast send/call <calldata>`

It is now possible to also just pass raw calldata directly to cast send and cast call, see foundry-rs/foundry#742

Document new `cheats.expectRevert` variant

See foundry-rs/foundry#962

Document artifact configuration

It is possible to configure what is put in the contract artifacts (e.g. metadata, source maps, wasm bytecode and so on).

See this diff (including the tests) and the PR: foundry-rs/foundry#762

Document `cast 4byte-event`

See foundry-rs/foundry#680

Enable mdbook tests

See here

Document offline mode

See foundry-rs/foundry#727

Document watch modes

Both forge build and forge test have a watch mode now.

Relevant PRs:

• Implementation: foundry-rs/foundry#817

Relevant issues:

• foundry-rs/foundry#813
• foundry-rs/foundry#868

Document new `forge test --debug`

See foundry-rs/foundry#920 (comment)

Chapter on fuzzing

Enable link preview for the book

Enable link preview for the Foundry Book (https://onbjerg.github.io/foundry-book/) to be show on social media

I will make a thumbnail - lmk!

Default chain ID is 99, not 1

Should be updated in the places where it is referenced, e.g. the foundry.toml Reference

All contributors

cracks knuckles

Add contributing guide

Should contain:

• General ideas on structure
• General ideas on wording
• What the labels mean

Document fork caching

Forge can now cache data from forked endpoints, see foundry-rs/foundry#1006

Should also include an update on how to persist the cache in CI

Creating an NFT with Solmate guide would lock funds in contract

Error in guide: https://onbjerg.github.io/foundry-book/tutorials/solmate-nft.html

Withdraw function uses OpenZeppelin PullPayment but mint function doesn't transfer funds to escrow

Funds would be locked in contract.
Guide should include test to check funds can be withdrawn.

Guide doesn't compile as Nft used for both contract and test contract.

Update examples to include new output

The output of foundry test in particular has changed

Cast guide

Not sure what to put here yet.

Chapters on current features

Meta

• Introduction

Getting started

• Installation
• First steps with Foundry

Forge

• Creating a new project
• Working on an existing project
• Dependencies
  • Add sections on forge remove and forge update
  • Document release/tag behavior
• Project layout
• foundry.toml
• Tests
  • Writing tests
  • Cheatcodes
  • Understanding traces
• Advanced Testing
  • Fuzz testing
• Continous integration
• Debugger
• Cache
• Deployment (as of now, forge create)

Additional guides

• Incremental adoption
• Integrating with VSCode
• Shell autocompletion

Reference

• ds-test Reference
• foundry.toml Reference
• Cheatcodes Reference

Document `vm.assume`

New cheatcode landed: foundry-rs/foundry#725

Encountered error using "expectRevert"

Encountered error

> forge test
compiling...
Compiling 1 files with 0.8.12
Compilation finished successfully
Error:
   0: Compiler run failed
      TypeError: Member "expectRevert" not found or not visible after argument-dependent lookup in contract CheatCodes.
        --> /Users/rootulp/git/rootulp/hello_foundry/src/Contract.sol:43:5:
         |
      43 |     cheats.expectRevert(
         |     ^^^^^^^^^^^^^^^^^^^

while trying to reproduce and update the output for https://github.com/onbjerg/foundry-book/blame/master/src/forge/cheatcodes.md#L124