We'd love your help! Thanks for caring about the book.
The book is intended to serve both as a guide to getting started with Forge and Cast, as well as a quick reference for both of these tools.
The book is split into some major chapters:
- Getting Started, which is intended to walk people through installing Foundry
- Forge Guide, which is intended to be a complete-ish tour of Forge
- Cast Guide, which is similarly intended to be a tour of Cast
- Additional Guides, which is a collection of other various topics such as CI, shell autocompletions
- Reference, which is intended to contain complete reference sheets on Forge and Cast, as well as related tools
Within each chapter there are multiple sections and subsections.
For this particular book, it is OK to assume some familiarity with Solidity and general concepts from other smart contract toolchains, such as Hardhat and Truffle.
The book follows the Rust Code of Conduct.
If you think that some content is missing or out-of-date, feel free to open an issue. If you find multiple pieces of content lacking, please open up a separate issue for each.
The issues will then be labeled so other contributors can find chunks of work they are interested in more easily.
The issue should contain what is missing, or what could be improved, in as much detail as you deem necessary.
Feel free to contribute changes to the book by opening a pull request - anything is welcome, from reformulating a sentence, fixing a typo, to adding new sections or chapters.
When your pull request is open, other contributors will take a look and may request changes. Do not be discouraged!
If your pull request is merged, or your issue was addressed, feel free to ping @all-contributors to be added to the README. More information here: https://allcontributors.org/docs/en/bot/overview
This section documents the standards for writing used throughout the book.
- Use second person ("you") – Address the reader directly
- ✅ "You can run this command..."
- ❌ "We can run this command..." / "Let's run this command..."
- Write in a clear, direct, and professional tone
- Assume familiarity with Solidity and smart contract concepts
The book uses three primary page structures:
Introductory pages that orient readers and link to related content.
Structure:
- Brief introduction (≤3 paragraphs)
- Card grid or link list to child pages
- Optional "Next steps" section
Step-by-step tutorials that walk readers through a task.
Structure:
- Introduction – What you'll accomplish
- Prerequisites – Required tools, knowledge, or setup
- Steps – Numbered instructions (use H4 for each step)
- Verify – How to confirm success
- Next steps – Related guides or reference material
Technical documentation for commands, APIs, or configuration.
Structure:
- Summary – One-sentence description
- Usage – Command syntax or API signature
- Options/Parameters – Table or definition list
- Examples – Practical usage examples
- H2 (
##) – Page title (every page starts with H2, not H1) - H3 (
###) – Major sections - H4 (
####) – Subsections
## Page Title
### Section
#### Subsection- Introductions – Keep to ≤3 paragraphs; get to the point quickly
- Prefer bullet points – Use lists over long paragraphs when presenting multiple items
- Be concise – Avoid unnecessary words and filler phrases
Always specify the language for syntax highlighting:
```solidity
contract Example {}
```For terminal commands, prefix each command with $ :
```bash
$ forge build
```Most CLI output is auto-generated to stay in sync with Foundry changes.
Each output file has three anchors:
Display the command and the output:
Display just the command:
Display just the output:
Learn more in the output folder.
Do not inline Solidity code. Instead, include source files from the projects folder:
// [!include ~/snippets/projects/hello_foundry/src/Counter.sol]This allows examples to be updated in one place and stay consistent across pages.
Learn more about including snippets in the Vocs documentation.
The documentation uses Vocs, which provides several useful markdown extensions.
Use titles instead of comments for single-action commands:
```bash [Check an address balance]
$ cast balance vitalik.eth --ether
```Use // @log: to show command output inline:
```bash
$ forge test -vv
// @log: Ran 2 tests for test/Counter.t.sol:CounterTest
// @log: [PASS] test_Increment() (gas: 31293)
// @log: Suite result: ok. 2 passed; 0 failed; 0 skipped
```Use ::::steps for sequential instructions:
::::steps
### Install foundryup
```bash
$ curl -L https://foundry.paradigm.xyz | bash
```
### Install Foundry
```bash
$ foundryup
```
::::Use callouts for warnings, tips, and notes:
:::tip
Run any command with `--help` for detailed usage.
:::
:::warning
This will overwrite existing files.
:::
:::note
This feature requires Foundry v1.0 or later.
:::Use Cards and Card components for navigation grids:
import { Cards, Card } from 'vocs'
<Cards>
<Card
title="Forge"
description="Build and test smart contracts."
to="/forge/overview"
icon="lucide:hammer"
/>
</Cards>Use :::code-group for tabbed code examples. Code groups are ideal for:
- Related commands – Multiple ways to do the same thing (e.g., install options)
- Good vs. bad examples – Show preferred and discouraged patterns
- Multi-file examples – Related files that work together (e.g., test + harness)
:::code-group
```bash [npm]
$ npm install
```
```bash [pnpm]
$ pnpm install
```
```bash [bun]
$ bun install
```
:::For good/bad examples, use clear tab names:
:::code-group
```solidity [Good]
import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
```
```solidity [Avoid]
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
```
:::For multi-file examples, use file paths as tab names:
:::code-group
```solidity [test/harnesses/TokenHarness.sol]
contract TokenHarness is Token {
function exposed_mint(address to, uint256 amount) external {
_mint(to, amount);
}
}
```
```solidity [test/Token.t.sol]
contract TokenInternalTest is Test {
function test_MintIncreasesSupply() public {
token.exposed_mint(alice, 1000);
assertEq(token.totalSupply(), 1000);
}
}
```
:::Learn more in the Vocs Markdown Reference.