diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69e81d269..e5d8ba341 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,7 +72,7 @@ As a small change in the Foundry CLIs can have a large impact on the book, most Each output file has three anchors you can use: -**Display the command *and* the output** +**Display the command _and_ the output** ```handlebars {{#include ../output/abc/xyz:all}} diff --git a/src/README.md b/src/README.md index 788ed453e..7c2656730 100644 --- a/src/README.md +++ b/src/README.md @@ -4,6 +4,10 @@ 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. +> ✨ **Announcements** +> +> [Stay up to date](./announcements.md) with the latest changes to Foundry. + > 📖 **Contributing** > > You can contribute to this book on [GitHub](https://github.com/foundry-rs/book). @@ -66,6 +70,7 @@ Help us improve Foundry: [Contributing](./contributing.md) References, troubleshooting, and more. +- [Announcements](./announcements.md) - [FAQ](./faq.md) - [CLI Reference](./reference/cli/) - [forge Commands](./reference/forge/) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c6b6e0762..2d1e3234b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -18,7 +18,7 @@ # Forge Overview -- [Overview of Forge](forge/README.md) +- [Forge](forge/README.md) - [Tests](./forge/tests.md) - [Writing Tests](./forge/writing-tests.md) - [Cheatcodes](./forge/cheatcodes.md) @@ -45,15 +45,15 @@ # Cast Overview -- [Overview of Cast](./cast/README.md) +- [Cast](./cast/README.md) # Anvil Overview -- [Overview of Anvil](./anvil/README.md) +- [Anvil](./anvil/README.md) # Chisel Overview -- [Overview of Chisel](./chisel/README.md) +- [Chisel](./chisel/README.md) # Configuration @@ -79,6 +79,7 @@ # Appendix +- [Announcements](./announcements.md) - [FAQ](./faq.md) - [Help us improve Foundry](./contributing.md) - [References](./reference/README.md) @@ -98,6 +99,7 @@ - [`forge config`](./reference/cli/forge/config.md) - [`forge coverage`](./reference/cli/forge/coverage.md) - [`forge create`](./reference/cli/forge/create.md) + - [`forge debug`](./reference/cli/forge/debug.md) - [`forge doc`](./reference/cli/forge/doc.md) - [`forge eip712`](./reference/cli/forge/eip712.md) - [`forge flatten`](./reference/cli/forge/flatten.md) @@ -285,6 +287,7 @@ - [forge verify-check](./reference/forge/forge-verify-check.md) - [forge flatten](./reference/forge/forge-flatten.md) - [Utility Commands](./reference/forge/utility-commands.md) + - [forge debug](./reference/forge/forge-debug.md) - [forge bind](./reference/forge/forge-bind.md) - [forge cache](./reference/forge/forge-cache.md) - [forge cache clean](./reference/forge/forge-cache-clean.md) diff --git a/src/announcements.md b/src/announcements.md new file mode 100644 index 000000000..911fa7193 --- /dev/null +++ b/src/announcements.md @@ -0,0 +1,131 @@ +## Announcements + +Stay up to date with the latest changes to Foundry. + +## 🚨 Actions required + +Upgrade your installation of `foundryup`! + +Run: `curl -L https://foundry.paradigm.xyz | bash` + +Upgrading ensures your installation defaults to updating to the **latest stable release** instead of the **latest nightly build**. + +If you do not upgrade you will **continue to receive nightly builds by default** which will start to contain more **significant breaking changes**. + +## Releases + +### 0.3 (stable) + +The Foundry [`0.3` release](https://github.com/foundry-rs/foundry/releases/tag/v0.3.0) marks an exciting new chapter for Foundry. By moving to [stable releases](https://github.com/foundry-rs/foundry/releases/tag/stable), we aim to provide a reliable development environment for the EVM ecosystem. Our next priority is the `1.0` release in early 2025, polishing Foundry for the long term. + +Big shoutout to the Foundry community - your bug reports, feature requests and contributions have shaped what Foundry is today. + +## FAQ + +#### How do I know which version I have installed? + +The latest version of `foundryup` is `0.3.1`. + +If you run `foundryup --version` and it does not return this or returns an error you are not up to date. + +#### How do I update `foundryup`? + +Run: `curl -L https://foundry.paradigm.xyz | bash` + +As a security best practice it is recommended you manually follow the [redirect](https://foundry.paradigm.xyz), inspect the [installer](https://raw.githubusercontent.com/foundry-rs/foundry/master/foundryup/install) you are about to run and the new version of [`foundryup`](https://raw.githubusercontent.com/foundry-rs/foundry/master/foundryup/foundryup) you are about to install. + +After the initial update you'll be able to update to the latest version of `foundryup` by running: + +```sh +foundryup --update +``` + +#### How do I install multiple versions? + +Easily install different versions using: + +```sh +foundryup --install +``` + +e.g. + +```sh +foundryup --install nightly +foundryup --install stable +foundryup --install 0.3.0 +``` + +#### How do I know which versions I have installed? + +Run + +```sh +foundryup --list +``` + +This will output a list as follows: + +```sh +foundryup: nightly +foundryup: - forge 0.3.0 (017c59d 2025-01-14T00:25:28.977200980Z) +foundryup: - cast 0.3.0 (017c59d 2025-01-14T00:25:28.933986754Z) +foundryup: - anvil 0.3.0 (017c59d 2025-01-14T00:25:29.065516554Z) +foundryup: - chisel 0.3.0 (017c59d 2025-01-14T00:25:29.021147876Z) + +foundryup: stable +foundryup: - forge 0.3.0 (5a8bd89 2024-12-20T08:46:21.555250780Z) +foundryup: - cast 0.3.0 (5a8bd89 2024-12-20T08:46:21.564365462Z) +foundryup: - anvil 0.3.0 (5a8bd89 2024-12-20T08:46:21.565569027Z) +foundryup: - chisel 0.3.0 (5a8bd89 2024-12-20T08:46:21.536871477Z) + +foundryup: v0.3.0 +foundryup: - forge 0.3.0 (5a8bd89 2024-12-19T17:17:10.245193696Z) +foundryup: - cast 0.3.0 (5a8bd89 2024-12-19T17:17:10.252265834Z) +foundryup: - anvil 0.3.0 (5a8bd89 2024-12-19T17:17:10.248488022Z) +foundryup: - chisel 0.3.0 (5a8bd89 2024-12-19T17:17:10.201917651Z) +``` + +#### How do I switch between versions? + +Easily manage your installations with: + +```sh +foundryup --use +``` + +e.g. + +```sh +foundryup --use nightly +foundryup --use stable +foundryup --use 0.3.0 +``` + +#### How do I configure `foundry-toolchain`? + +The `foundry-toolchain` GitHub Action will use the latest `stable` release by default. + +If you would prefer to use a different release you can set the `version` key: + +```yml +- name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + with: + version: +``` + +e.g. + +```yml +- name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + with: + version: nightly +``` + +#### I prefer using nightly builds. + +You are still able to receive the latest `nightly` builds by running `foundryup --install nightly` + +**Be cautious — nightly builds may include breaking changes that are difficult to debug without context.** diff --git a/src/anvil/README.md b/src/anvil/README.md index 2c9f8b251..11374ce90 100644 --- a/src/anvil/README.md +++ b/src/anvil/README.md @@ -1,31 +1,91 @@ -## Overview of Anvil +## 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 a fast local Ethereum development node. -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](../getting-started/installation.md). +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](../getting-started/installation.md). -> Note: If you have an older version of Foundry installed, you'll need to re-install `foundryup` in order for Anvil to be downloaded. +### Getting started -### How to use Anvil +To use Anvil, simply type `anvil`. To fork against a live Ethereum network run `anvil --fork-url `. -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. +Let's fork Ethereum mainnet at the latest block: -Anvil is highly configurable. You can run `anvil -h` to see all the configuration options. +```console +$ anvil --fork-url https://eth.merkle.io -Some basic options are: -```bash -# Number of dev accounts to generate and configure. [default: 10] -anvil -a, --accounts + _ _ + (_) | | + __ _ _ __ __ __ _ | | + / _` | | '_ \ \ \ / / | | | | + | (_| | | | | | \ V / | | | | + \__,_| |_| |_| \_/ |_| |_| -# The EVM hardfork to use. [default: latest] -anvil --hardfork + 0.2.0 (c4fcf12 2024-12-12T00:23:45.094165202Z) + https://github.com/foundry-rs/foundry -# Port number to listen on. [default: 8545] -anvil -p, --port +Available Accounts +================== + +(0) 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000.000000000000000000 ETH) +(1) 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000.000000000000000000 ETH) +(2) 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC (10000.000000000000000000 ETH) +(3) 0x90F79bf6EB2c4f870365E785982E1f101E93b906 (10000.000000000000000000 ETH) +(4) 0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65 (10000.000000000000000000 ETH) +(5) 0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc (10000.000000000000000000 ETH) +(6) 0x976EA74026E726554dB657fA54763abd0C3a0aa9 (10000.000000000000000000 ETH) +(7) 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955 (10000.000000000000000000 ETH) +(8) 0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f (10000.000000000000000000 ETH) +(9) 0xa0Ee7A142d267C1f36714E4a8F75612F20a79720 (10000.000000000000000000 ETH) + +Private Keys +================== + +(0) 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 +(1) 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d +(2) 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a +(3) 0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6 +(4) 0x47e179ec197488593b187f80a00eb0da91f1b9d0b13f8733639f19c30a34926a +(5) 0x8b3a350cf5c34c9194ca85829a2df0ec3153be0318b5e2d3348e872092edffba +(6) 0x92db14e403b83dfe3df233f83dfa3a0d7096f21ca9b0d6d6b8d88b2b4ec1564e +(7) 0x4bbbf85ce3377467afe5d46f804f221813b2bb87f24d81f60f1fcdbf7cbf4356 +(8) 0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97 +(9) 0x2a871d0798f97d79848a013d4936a73bf4cc922c825d33c1cf7073dff6d409c6 + +Wallet +================== +Mnemonic: test test test test test test test test test test test junk +Derivation path: m/44'/60'/0'/0/ + + +Fork +================== +Endpoint: https://eth.merkle.io +Block number: 21387064 +Block hash: 0x904aee789b82ac0412448bc2ea9bb3774d10c2dae4a0e5b7f6451ac2ecd0787a +Chain ID: 1 + +Base Fee +================== + +26049293674 + +Gas Limit +================== + +30000000 + +Genesis Timestamp +================== + +1734014216 + +Listening on 127.0.0.1:8545 ``` +
+ > 📚 **Reference** > > See the [`anvil` Reference](../reference/anvil/) for in depth information on Anvil and its capabilities. - diff --git a/src/cast/README.md b/src/cast/README.md index 09c683a75..109a0e5a9 100644 --- a/src/cast/README.md +++ b/src/cast/README.md @@ -1,37 +1,56 @@ -## Overview of Cast +## 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! +Cast is a Swiss Army knife for interacting with Ethereum applications from the command line. You can make smart contract calls, send transactions, or retrieve any type of chain data - all from your command-line! -### How to use Cast +The `cast` binary can be used both within and outside of a Foundry project. -To use Cast, run the [`cast`](../reference/cast/cast.md) command followed by a subcommand: +Cast is part of the Foundry suite and is installed alongside `forge`, `chisel`, and `anvil`. If you haven't installed Foundry +yet, see [Foundry installation](../getting-started/installation.md). -```bash -$ cast +### Getting started + +Here are a few examples of what you can do: + +**Check the latest block on Ethereum Mainnet**: + +```sh +cast block-number --rpc-url https://eth.merkle.io +``` + +**Check the Ether balance of `vitalik.eth`** + +```sh +cast balance vitalik.eth --ether --rpc-url https://eth.merkle.io +``` + +**Replay and trace a transaction** + +```sh +cast run 0x9c32042f5e997e27e67f82583839548eb19dc78c4769ad6218657c17f2a5ed31 --rpc-url https://eth.merkle.io ``` -#### Examples +Optionally, pass `--etherscan-api-key ` to decode transaction traces using verified source maps, providing more detailed and human-readable information. -Let's use `cast` to retrieve the total supply of the DAI token: +**Retrieve the total supply of the DAI token** -```bash +```sh {{#include ../output/cast/cast-call:all}} ``` -`cast` also provides many convenient subcommands, such as for decoding calldata: +**Decode calldata** -```bash +```sh {{#include ../output/cast/cast-4byte-decode:all}} ``` -You can also use `cast` to send arbitrary messages. Here's an example of sending a message between two Anvil accounts. +**Send messages between two Anvil accounts** -```bash -$ cast send --private-key 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc $(cast from-utf8 "hello world") --rpc-url http://127.0.0.1:8545/ +```sh +cast send --private-key 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc $(cast from-utf8 "hello world") --rpc-url http://127.0.0.1:8545/ ```
> 📚 **Reference** -> +> > See the [`cast` Reference](../reference/cast/) for a complete overview of all the available subcommands. diff --git a/src/chisel/README.md b/src/chisel/README.md index af6e175be..c1e909485 100644 --- a/src/chisel/README.md +++ b/src/chisel/README.md @@ -1,23 +1,56 @@ -## Overview of Chisel +## 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 a fast, utilitarian, and verbose Solidity REPL. + +The `chisel` binary 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. 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](../getting-started/installation.md). +yet, see [Foundry installation](../getting-started/installation.md). + +### Getting started + +To use Chisel, simply type `chisel`. + +```sh +chisel +``` + +From here, start writing Solidity code! Chisel will offer verbose feedback on each input. -> Note: If you have an older version of Foundry installed, you'll need to re-install `foundryup` in order for Chisel to be downloaded. +Create a variable `a` and query it: -### How to use Chisel +```console +➜ uint256 a = 123; +➜ a +Type: uint256 +├ Hex: 0x7b +├ Hex (full word): 0x000000000000000000000000000000000000000000000000000000000000007b +└ Decimal: 123 +``` -To use Chisel, simply type `chisel`. From there, start writing Solidity code! Chisel will offer verbose feedback on each input. +Finally, run `!source` to see `a` was applied: -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. +```solidity +// SPDX-License-Identifier: UNLICENSED +pragma solidity ^0.8.28; + +import {Vm} from "forge-std/Vm.sol"; + +contract REPL { + Vm internal constant vm = Vm(address(uint160(uint256(keccak256("hevm cheat code"))))); + + /// @notice REPL contract entry point + function run() public { + uint256 a = 123; + } +} +``` To see available commands, type `!help` within the REPL. +
+ > 📚 **Reference** > > See the [`chisel` Reference](../reference/chisel/) for in depth information on Chisel and its capabilities. - diff --git a/src/forge/README.md b/src/forge/README.md index 40561bb1a..dea8e200c 100644 --- a/src/forge/README.md +++ b/src/forge/README.md @@ -1,3 +1,68 @@ -## Overview of Forge +## Forge Forge is a command-line tool that ships with Foundry. Forge tests, builds, and deploys your smart contracts. + +Forge is part of the Foundry suite and is installed alongside `cast`, `chisel`, and `anvil`. If you haven't installed Foundry +yet, see [Foundry installation](../getting-started/installation.md). + +### Getting started + +The best way to understand Forge is to simply try it (in less than 30 seconds!). + +First, let's initialize a new `counter` example repository: + +```sh +$ forge init counter +``` + +Next `cd` into `counter` and build : + +```sh +$ forge build +``` + +```console +[⠊] Compiling... +[⠔] Compiling 27 files with Solc 0.8.28 +[⠒] Solc 0.8.28 finished in 452.13ms +Compiler run successful! +``` + +Let's [test](https://book.getfoundry.sh/forge/tests#tests) our contracts: + +```sh +$ forge test +``` + +```console +[⠊] Compiling... +No files changed, compilation skipped + +Ran 2 tests for test/Counter.t.sol:CounterTest +[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 31121, ~: 31277) +[PASS] test_Increment() (gas: 31293) +Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 5.35ms (4.86ms CPU time) + +Ran 1 test suite in 5.91ms (5.35ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) +``` + +Finally, let's run our deployment script: + +```sh +$ forge script script/Counter.s.sol +``` + +```console +[⠊] Compiling... +No files changed, compilation skipped +Script ran successfully. +Gas used: 109037 + +If you wish to simulate on-chain transactions pass a RPC URL. +``` + +
+ +> 📚 **Reference** +> +> See the [`forge` Reference](../reference/forge/) for a complete overview of all the available subcommands. diff --git a/src/forge/debugger.md b/src/forge/debugger.md index 57d778cd0..8f6ee34c9 100644 --- a/src/forge/debugger.md +++ b/src/forge/debugger.md @@ -2,7 +2,7 @@ Forge ships with an interactive debugger. -The debugger is accessible on [`forge test`](../reference/forge/forge-test.md) and on [`forge script`](../reference/forge/forge-script.md) +The debugger is accessible on [`forge debug`](../reference/forge/forge-debug.md) and on [`forge test`](../reference/forge/forge-test.md). Using `forge test`: @@ -20,6 +20,22 @@ If you have multiple contracts with the same function name, you need to limit th 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`: + +```sh +$ 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: + +```sh +$ 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 ![An image of the debugger UI](../images/debugger.png) diff --git a/src/output/cast/cast-call b/src/output/cast/cast-call index d44253527..b3725bd21 100644 --- a/src/output/cast/cast-call +++ b/src/output/cast/cast-call @@ -3,6 +3,6 @@ $ cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()(uint256)" --rpc-url https://eth-mainnet.alchemyapi.io/v2/Lc7oIGYeL_QvInzI0Wiu_pOZZDEKBrdf // ANCHOR_END: command // ANCHOR: output -3422853925491548919334544079 [3.422e27] +3558143720191111418243988461 [3.558e27] // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/cheatcodes/forge-test-cheatcodes b/src/output/cheatcodes/forge-test-cheatcodes index d5be2e8c0..d33063258 100644 --- a/src/output/cheatcodes/forge-test-cheatcodes +++ b/src/output/cheatcodes/forge-test-cheatcodes @@ -8,8 +8,8 @@ No files changed, compilation skipped Ran 2 tests for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest [PASS] testFail_IncrementAsNotOwner() (gas: 8314) [PASS] test_IncrementAsOwner() (gas: 29161) -Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 448.05µs (154.98µs CPU time) +Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 483.96µs (163.77µs CPU time) -Ran 1 test suite in 5.84ms (448.05µs CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) +Ran 1 test suite in 5.86ms (483.96µs CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/cheatcodes/forge-test-cheatcodes-expectrevert b/src/output/cheatcodes/forge-test-cheatcodes-expectrevert index 86322ce90..f45622c67 100644 --- a/src/output/cheatcodes/forge-test-cheatcodes-expectrevert +++ b/src/output/cheatcodes/forge-test-cheatcodes-expectrevert @@ -7,8 +7,8 @@ No files changed, compilation skipped Ran 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest [PASS] test_IncrementAsOwner() (gas: 29161) -Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 384.57µs (61.04µs CPU time) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 383.06µs (49.64µs CPU time) -Ran 1 test suite in 5.82ms (384.57µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +Ran 1 test suite in 5.77ms (383.06µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/cheatcodes/forge-test-cheatcodes-tracing b/src/output/cheatcodes/forge-test-cheatcodes-tracing index a41c496d9..f9f7eb1a3 100644 --- a/src/output/cheatcodes/forge-test-cheatcodes-tracing +++ b/src/output/cheatcodes/forge-test-cheatcodes-tracing @@ -15,8 +15,8 @@ Traces: │ └─ ← [Revert] Unauthorized() └─ ← [Revert] Unauthorized() -Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 392.58µs (64.16µs CPU time) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 421.03µs (83.50µs CPU time) -Ran 1 test suite in 5.88ms (392.58µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +Ran 1 test suite in 5.99ms (421.03µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/cheatcodes/forge-test-simple b/src/output/cheatcodes/forge-test-simple index 93469b47e..8e496cd1b 100644 --- a/src/output/cheatcodes/forge-test-simple +++ b/src/output/cheatcodes/forge-test-simple @@ -4,13 +4,13 @@ $ forge test --match-test test_IncrementAsOwner // ANCHOR_END: command // ANCHOR: output Compiling 24 files with Solc 0.8.10 -Solc 0.8.10 finished in 1.09s +Solc 0.8.10 finished in 1.10s Compiler run successful! Ran 1 test for test/OwnerUpOnly.t.sol:OwnerUpOnlyTest [PASS] test_IncrementAsOwner() (gas: 29161) -Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 366.04µs (49.34µs CPU time) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 455.99µs (84.60µs CPU time) -Ran 1 test suite in 5.80ms (366.04µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +Ran 1 test suite in 5.89ms (455.99µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/deps/forge-install b/src/output/deps/forge-install index 165a0beaa..5407a33db 100644 --- a/src/output/deps/forge-install +++ b/src/output/deps/forge-install @@ -3,7 +3,7 @@ $ forge install transmissions11/solmate // ANCHOR_END: command // ANCHOR: output -Installing solmate in /tmp/tmp.BW3xowADu1/deps/lib/solmate (url: Some("https://github.com/transmissions11/solmate"), tag: None) +Installing solmate in /tmp/tmp.8c7PAzC67H/deps/lib/solmate (url: Some("https://github.com/transmissions11/solmate"), tag: None) Installed solmate // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/deps/tree b/src/output/deps/tree index abb51fcf6..cac595a49 100644 --- a/src/output/deps/tree +++ b/src/output/deps/tree @@ -8,6 +8,6 @@ lib ├── solmate └── weird-erc20 -3 directories, 0 files +4 directories, 0 files // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/foundry-template/forge-build b/src/output/foundry-template/forge-build index d7fc7c439..cff880ce0 100644 --- a/src/output/foundry-template/forge-build +++ b/src/output/foundry-template/forge-build @@ -4,7 +4,7 @@ $ forge build // ANCHOR_END: command // ANCHOR: output Compiling 28 files with Solc 0.8.28 -Solc 0.8.28 finished in 1.09s +Solc 0.8.28 finished in 1.10s Compiler run successful! // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/foundry-template/forge-test b/src/output/foundry-template/forge-test index 573770956..dae877722 100644 --- a/src/output/foundry-template/forge-test +++ b/src/output/foundry-template/forge-test @@ -9,8 +9,8 @@ Ran 3 tests for tests/Foo.t.sol:FooTest [PASS] testFork_Example() (gas: 3755) [PASS] testFuzz_Example(uint256) (runs: 1000, μ: 9111, ~: 9111) [PASS] test_Example() (gas: 11861) -Suite result: ok. 3 passed; 0 failed; 0 skipped; finished in 20.65ms (20.41ms CPU time) +Suite result: ok. 3 passed; 0 failed; 0 skipped; finished in 20.65ms (20.38ms CPU time) -Ran 1 test suite in 21.85ms (20.65ms CPU time): 3 tests passed, 0 failed, 0 skipped (3 total tests) +Ran 1 test suite in 21.73ms (20.65ms CPU time): 3 tests passed, 0 failed, 0 skipped (3 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/fuzz_testing/forge-test-fail-fuzz b/src/output/fuzz_testing/forge-test-fail-fuzz index eb1ba006f..2bca559f0 100644 --- a/src/output/fuzz_testing/forge-test-fail-fuzz +++ b/src/output/fuzz_testing/forge-test-fail-fuzz @@ -8,9 +8,9 @@ Solc 0.8.10 finished in 1.04s Compiler run successful! Ran 1 test for test/Safe.t.sol:SafeTest -[FAIL: EvmError: Revert; counterexample: calldata=0x29facca70000000000000000000000000000000021d5d6329a57a732fbd311bd1768ac4f args=[44974827536600106895869556161837050959 [4.497e37]]] testFuzz_Withdraw(uint256) (runs: 0, μ: 0, ~: 0) -Suite result: FAILED. 0 passed; 1 failed; 0 skipped; finished in 691.02µs (371.12µs CPU time) +[FAIL: EvmError: Revert; counterexample: calldata=0x29facca700000000000000000008b5a210bf77df16e1e4bfb8406769ffc0307cc53a743d args=[834204769179293694580214976748980775394848113291850813 [8.342e53]]] testFuzz_Withdraw(uint256) (runs: 3, μ: 19531, ~: 19531) +Suite result: FAILED. 0 passed; 1 failed; 0 skipped; finished in 800.27µs (465.42µs CPU time) -Ran 1 test suite in 8.46ms (691.02µs CPU time): 0 tests passed, 1 failed, 0 skipped (1 total tests) +Ran 1 test suite in 6.23ms (800.27µs CPU time): 0 tests passed, 1 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/fuzz_testing/forge-test-no-fuzz b/src/output/fuzz_testing/forge-test-no-fuzz index 38d3fbe68..0bda1f162 100644 --- a/src/output/fuzz_testing/forge-test-no-fuzz +++ b/src/output/fuzz_testing/forge-test-no-fuzz @@ -4,13 +4,13 @@ $ forge test // ANCHOR_END: command // ANCHOR: output Compiling 24 files with Solc 0.8.10 -Solc 0.8.10 finished in 1.08s +Solc 0.8.10 finished in 1.09s Compiler run successful! Ran 1 test for test/Safe.t.sol:SafeTest [PASS] test_Withdraw() (gas: 19463) -Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 370.11µs (43.23µs CPU time) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 397.00µs (52.65µs CPU time) -Ran 1 test suite in 5.95ms (370.11µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +Ran 1 test suite in 5.72ms (397.00µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/fuzz_testing/forge-test-success-fuzz b/src/output/fuzz_testing/forge-test-success-fuzz index 014ff1dc3..fbca1b77f 100644 --- a/src/output/fuzz_testing/forge-test-success-fuzz +++ b/src/output/fuzz_testing/forge-test-success-fuzz @@ -4,13 +4,13 @@ $ forge test // ANCHOR_END: command // ANCHOR: output Compiling 1 files with Solc 0.8.10 -Solc 0.8.10 finished in 1.04s +Solc 0.8.10 finished in 1.05s Compiler run successful! Ran 1 test for test/Safe.t.sol:SafeTest -[PASS] testFuzz_Withdraw(uint96) (runs: 257, μ: 19370, ~: 19631) -Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 4.88ms (4.56ms CPU time) +[PASS] testFuzz_Withdraw(uint96) (runs: 257, μ: 19526, ~: 19631) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 4.88ms (4.55ms CPU time) -Ran 1 test suite in 6.00ms (4.88ms CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +Ran 1 test suite in 5.86ms (4.88ms CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/hello_foundry/forge-build b/src/output/hello_foundry/forge-build index d31f2ca2f..b333ec106 100644 --- a/src/output/hello_foundry/forge-build +++ b/src/output/hello_foundry/forge-build @@ -4,7 +4,7 @@ $ forge build // ANCHOR_END: command // ANCHOR: output Compiling 27 files with Solc 0.8.19 -Solc 0.8.19 finished in 1.09s +Solc 0.8.19 finished in 1.07s Compiler run successful! // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/hello_foundry/forge-init b/src/output/hello_foundry/forge-init index 53d6aa2ee..b0cc71d8b 100644 --- a/src/output/hello_foundry/forge-init +++ b/src/output/hello_foundry/forge-init @@ -3,8 +3,8 @@ $ forge init hello_foundry // ANCHOR_END: command // ANCHOR: output -Initializing /tmp/tmp.dgcskWFKeq/hello_foundry... -Installing forge-std in /tmp/tmp.dgcskWFKeq/hello_foundry/lib/forge-std (url: Some("https://github.com/foundry-rs/forge-std"), tag: None) +Initializing /tmp/tmp.nRme4kZLDG/hello_foundry... +Installing forge-std in /tmp/tmp.nRme4kZLDG/hello_foundry/lib/forge-std (url: Some("https://github.com/foundry-rs/forge-std"), tag: None) Installed forge-std v1.9.5 Initialized forge project // ANCHOR_END: output diff --git a/src/output/hello_foundry/forge-test b/src/output/hello_foundry/forge-test index 26b4604cd..2c4b55552 100644 --- a/src/output/hello_foundry/forge-test +++ b/src/output/hello_foundry/forge-test @@ -6,10 +6,10 @@ $ forge test No files changed, compilation skipped Ran 2 tests for test/Counter.t.sol:CounterTest -[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 31054, ~: 31288) +[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 30977, ~: 31288) [PASS] test_Increment() (gas: 31303) -Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 8.29ms (7.98ms CPU time) +Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 8.42ms (8.10ms CPU time) -Ran 1 test suite in 9.36ms (8.29ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) +Ran 1 test suite in 9.76ms (8.42ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/hello_foundry/tree b/src/output/hello_foundry/tree index 9ca6a65ac..32d3e06b2 100644 --- a/src/output/hello_foundry/tree +++ b/src/output/hello_foundry/tree @@ -9,6 +9,6 @@ $ tree . -d -L 1 ├── src └── test -4 directories +5 directories // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/hello_foundry/tree-with-files b/src/output/hello_foundry/tree-with-files index d51de89dc..a33658964 100644 --- a/src/output/hello_foundry/tree-with-files +++ b/src/output/hello_foundry/tree-with-files @@ -24,6 +24,6 @@ $ tree . -L 3 -I output └── test └── Counter.t.sol -8 directories, 11 files +9 directories, 11 files // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/nft_tutorial/forge-test b/src/output/nft_tutorial/forge-test index f3b226f6a..2ef8aeade 100644 --- a/src/output/nft_tutorial/forge-test +++ b/src/output/nft_tutorial/forge-test @@ -14,7 +14,7 @@ Ran 8 tests for test/OpenZeppelinNft.t.sol:OpenZeppelinNftTests [PASS] testMintPricePaid() (gas: 81554) [PASS] testNewMintOwnerRegistered() (gas: 190956) [PASS] testSafeContractReceiver() (gas: 273151) -Suite result: ok. 8 passed; 0 failed; 0 skipped; finished in 1.53ms (1.18ms CPU time) +Suite result: ok. 8 passed; 0 failed; 0 skipped; finished in 1.55ms (1.23ms CPU time) Ran 8 tests for test/SolmateNft.sol:SolmateNftTests [PASS] testBalanceIncremented() (gas: 217400) @@ -25,8 +25,8 @@ Ran 8 tests for test/SolmateNft.sol:SolmateNftTests [PASS] testMintPricePaid() (gas: 81321) [PASS] testNewMintOwnerRegistered() (gas: 190741) [PASS] testSafeContractReceiver() (gas: 272655) -Suite result: ok. 8 passed; 0 failed; 0 skipped; finished in 1.53ms (1.34ms CPU time) +Suite result: ok. 8 passed; 0 failed; 0 skipped; finished in 1.55ms (1.33ms CPU time) -Ran 2 test suites in 6.25ms (3.07ms CPU time): 16 tests passed, 0 failed, 0 skipped (16 total tests) +Ran 2 test suites in 6.14ms (3.09ms CPU time): 16 tests passed, 0 failed, 0 skipped (16 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/test_filters/forge-test-match-contract-and-test b/src/output/test_filters/forge-test-match-contract-and-test index eb3d8a567..7eb94766b 100644 --- a/src/output/test_filters/forge-test-match-contract-and-test +++ b/src/output/test_filters/forge-test-match-contract-and-test @@ -4,14 +4,14 @@ $ forge test --match-contract ComplicatedContractTest --match-test test_Deposit // ANCHOR_END: command // ANCHOR: output Compiling 24 files with Solc 0.8.10 -Solc 0.8.10 finished in 1.05s +Solc 0.8.10 finished in 1.07s Compiler run successful! Ran 2 tests for test/ComplicatedContract.t.sol:ComplicatedContractTest [PASS] test_DepositERC20() (gas: 102193) [PASS] test_DepositETH() (gas: 61414) -Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 1.27ms (1.67ms CPU time) +Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 1.18ms (1.50ms CPU time) -Ran 1 test suite in 5.53ms (1.27ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) +Ran 1 test suite in 6.17ms (1.18ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/output/test_filters/forge-test-match-path b/src/output/test_filters/forge-test-match-path index d2a26d535..f7544fbdd 100644 --- a/src/output/test_filters/forge-test-match-path +++ b/src/output/test_filters/forge-test-match-path @@ -4,13 +4,13 @@ $ forge test --match-path test/ContractB.t.sol // ANCHOR_END: command // ANCHOR: output Compiling 1 files with Solc 0.8.10 -Solc 0.8.10 finished in 1.02s +Solc 0.8.10 finished in 1.03s Compiler run successful! Ran 1 test for test/ContractB.t.sol:ContractBTest [PASS] testExample() (gas: 257) -Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 300.38µs (57.30µs CPU time) +Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 321.99µs (51.93µs CPU time) -Ran 1 test suite in 5.66ms (300.38µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) +Ran 1 test suite in 5.80ms (321.99µs CPU time): 1 tests passed, 0 failed, 0 skipped (1 total tests) // ANCHOR_END: output // ANCHOR_END: all diff --git a/src/reference/anvil/README.md b/src/reference/anvil/README.md index 05b77324d..5bc10d8b9 100644 --- a/src/reference/anvil/README.md +++ b/src/reference/anvil/README.md @@ -45,7 +45,7 @@ This allows you to test CREATE2 deployments locally without forking. #### Supported RPC Methods ##### Standard Methods -The standard methods are based on [this](https://eth.wiki/json-rpc/API) reference. +The standard methods are based on [this](https://ethereum.org/en/developers/docs/apis/json-rpc/) reference. * `web3_clientVersion` diff --git a/src/reference/cli/SUMMARY.md b/src/reference/cli/SUMMARY.md index f25b07a24..651f08f00 100644 --- a/src/reference/cli/SUMMARY.md +++ b/src/reference/cli/SUMMARY.md @@ -13,6 +13,7 @@ - [`forge config`](./forge/config.md) - [`forge coverage`](./forge/coverage.md) - [`forge create`](./forge/create.md) + - [`forge debug`](./forge/debug.md) - [`forge doc`](./forge/doc.md) - [`forge eip712`](./forge/eip712.md) - [`forge flatten`](./forge/flatten.md) @@ -171,3 +172,4 @@ - [`chisel view`](./chisel/view.md) - [`chisel clear-cache`](./chisel/clear-cache.md) - [`chisel eval`](./chisel/eval.md) + diff --git a/src/reference/cli/forge/debug.md b/src/reference/cli/forge/debug.md new file mode 100644 index 000000000..a799619ed --- /dev/null +++ b/src/reference/cli/forge/debug.md @@ -0,0 +1,345 @@ +# forge debug + +Debugs a single smart contract as a script + +```bash +$ forge debug --help +``` + +```txt +Usage: forge debug [OPTIONS] [ARGS]... + +Arguments: + + The contract you want to run. Either the file path or contract name. + + If multiple contracts exist in the same file you must specify the + target contract with --target-contract. + + [ARGS]... + Arguments to pass to the script function + +Options: + --target-contract + The name of the contract you want to run + + [aliases: tc] + + -s, --sig + The signature of the function you want to call in the contract, or raw + calldata + + [default: run()] + + --debug + Open the script in the debugger + + --dump + File path to dump execution details as JSON + + -h, --help + Print help (see a summary with '-h') + + -j, --threads + Number of threads to use. Specifying 0 defaults to the number of + logical cores + + [aliases: jobs] + +Cache options: + --force + Clear the cache and artifacts folder and recompile + +Build options: + --no-cache + Disable the cache + + --eof + Use EOF-enabled solc binary. Enables via-ir and sets EVM version to + Prague. Requires Docker to be installed. + + Note that this is a temporary solution until the EOF support is merged + into the main solc release. + + --skip ... + Skip building files whose names contain the given filter. + + `test` and `script` are aliases for `.t.sol` and `.s.sol`. + +Linker options: + --libraries + Set pre-linked libraries + + [env: DAPP_LIBRARIES=] + +Compiler options: + --ignored-error-codes + Ignore solc warnings by error code + + --deny-warnings + Warnings will trigger a compiler error + + --no-auto-detect + Do not auto-detect the `solc` version + + --use + 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. + + --via-ir + Use the Yul intermediate representation compilation pipeline + + --no-metadata + Do not append any metadata to the bytecode. + + This is equivalent to setting `bytecode_hash` to `none` and + `cbor_metadata` to `false`. + + --ast + Includes the AST as JSON in the compiler output + + --evm-version + The target EVM version + + --optimize [] + Activate the Solidity optimizer + + [possible values: true, false] + + --optimizer-runs + The number of runs specifies roughly how often each opcode of the + deployed code will be executed across the life-time of the contract. + This means it is a trade-off parameter between code size (deploy cost) + and code execution cost (cost after deployment). An `optimizer_runs` + parameter of `1` will produce short but expensive code. In contrast, a + larger `optimizer_runs` parameter will produce longer but more gas + efficient code + + --extra-output ... + Extra output to include in the contract's artifact. + + Example keys: evm.assembly, ewasm, ir, irOptimized, metadata + + For a full description, see + + + --extra-output-files ... + Extra output to write to separate files. + + Valid values: metadata, ir, irOptimized, ewasm, evm.assembly + +Project options: + -o, --out + The path to the contract artifacts folder + + --revert-strings + Revert string configuration. + + Possible values are "default", "strip" (remove), "debug" + (Solidity-generated revert strings) and "verboseDebug" + + --build-info + Generate build info files + + --build-info-path + Output path to directory that build info files will be written to + + --root + The project's root path. + + By default root of the Git repository, if in one, or the current + working directory. + + -C, --contracts + The contracts source directory + + -R, --remappings + The project's remappings + + --remappings-env + The project's remappings from the environment + + --cache-path + The path to the compiler cache + + --lib-paths + The path to the library folder + + --hardhat + Use the Hardhat-style project layout. + + This is the same as using: `--contracts contracts --lib-paths + node_modules`. + + [aliases: hh] + + --config-path + Path to the config file + +EVM options: + -f, --fork-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. + + [aliases: rpc-url] + + --fork-block-number + Fetch state from a specific block number over a remote endpoint. + + See --fork-url. + + --fork-retries + Number of retries. + + See --fork-url. + + --fork-retry-backoff + Initial retry backoff on encountering errors. + + See --fork-url. + + --no-storage-caching + Explicitly disables the use of RPC caching. + + All storage slots are read entirely from the endpoint. + + This flag overrides the project's configuration file. + + See --fork-url. + + --initial-balance + The initial balance of deployed test contracts + + --sender
+ The address which will be executing tests/scripts + + --ffi + Enable the FFI cheatcode + + --always-use-create-2-factory + Use the create 2 factory in all cases including tests and + non-broadcasting scripts + + --create2-deployer
+ The CREATE2 deployer address to use, this will override the one in the + config + +Fork config: + --compute-units-per-second + Sets the number of assumed available compute units per second for this + provider + + default value: 330 + + See also --fork-url and + + + --no-rpc-rate-limit + Disables rate limiting for this node's provider. + + See also --fork-url and + + + [aliases: no-rate-limit] + +Executor environment config: + --code-size-limit + EIP-170: Contract code size limit in bytes. Useful to increase this + because of tests. By default, it is 0x6000 (~25kb) + + --chain + The chain name or EIP-155 chain ID + + [aliases: chain-id] + + --gas-price + The gas price + + --block-base-fee-per-gas + The base fee in a block + + [aliases: base-fee] + + --tx-origin
+ The transaction origin + + --block-coinbase
+ The coinbase of the block + + --block-timestamp + The timestamp of the block + + --block-number + The block number + + --block-difficulty + The block difficulty + + --block-prevrandao + The block prevrandao value. NOTE: Before merge this field was mix_hash + + --block-gas-limit + The block gas limit + + [aliases: gas-limit] + + --memory-limit + The memory limit per EVM execution in bytes. If this limit is + exceeded, a `MemoryLimitOOG` result is thrown. + + The default is 128MiB. + + --disable-block-gas-limit + Whether to disable the block gas limit checks + + [aliases: no-gas-limit] + + --isolate + Whether to enable isolation of calls. In isolation mode all top-level + calls are executed as a separate transaction in a separate EVM + context, enabling more precise gas accounting and transaction state + changes + + --odyssey + Whether to enable Odyssey features + +Display options: + --color + The color of the log messages + + Possible values: + - auto: Intelligently guess whether to use color output (default) + - always: Force color output + - never: Force disable color output + + --json + Format log messages as JSON + + -q, --quiet + Do not print log messages + + -v, --verbosity... + Verbosity level of the log messages. + + Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv). + + Depending on the context the verbosity levels have different meanings. + + For example, the verbosity levels of the EVM are: + - 2 (-vv): Print logs for all tests. + - 3 (-vvv): Print execution traces for failing tests. + - 4 (-vvvv): Print execution traces for all tests, and setup traces + for failing tests. + - 5 (-vvvvv): Print execution and setup traces for all tests, + including storage changes. +``` \ No newline at end of file diff --git a/src/reference/config/formatter.md b/src/reference/config/formatter.md index e198d3e99..08df55ec9 100644 --- a/src/reference/config/formatter.md +++ b/src/reference/config/formatter.md @@ -205,6 +205,18 @@ Style of underscores in number literals. Valid values are: - `thousands`: Add an underscore every thousand, if greater than 9999. i.e. `1000` is formatted as `1000` and `10000` as `10_000` - `remove`: Remove all underscores +### `hex_underscore` + +- Type: string +- Default: `remove` +- Environment: `FOUNDRY_FMT_HEX_UNDERSCORE` or `DAPP_FMT_HEX_UNDERSCORE` + +Style of underscores in bytes literals. Valid values are: + +- `preserve`: Use the underscores defined in the source code +- `remove` (default): Remove all underscores +- `bytes`: Add underscore as separator between byte boundaries. i.e. `hex"deadbeef"` is formatted as `hex"de_ad_be_ef"` + ### `wrap_comments` - Type: bool diff --git a/src/reference/forge/forge-debug.md b/src/reference/forge/forge-debug.md new file mode 100644 index 000000000..c8e9899b2 --- /dev/null +++ b/src/reference/forge/forge-debug.md @@ -0,0 +1,100 @@ +## 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 `. + +The signature can be a fragment (`()`), 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 `. + +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][cheatcodes] are still available. + +You can also specify a block number to fork from by passing `--fork-block-number `. 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][debugger]. + +### 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][debugger]. + +{{#include evm-options.md}} + +{{#include executor-options.md}} + +{{#include core-build-options.md}} + +{{#include common-options.md}} + +### EXAMPLES + +1. Execute the `run()` function in a contract: + ```sh + forge debug src/Contract.sol + ``` + +2. Open a script in the debugger: + ```sh + forge debug src/Contract.sol --debug + ``` + +3. Execute the `foo()` function in a contract: + ```sh + forge debug src/Contract.sol --sig "foo()" + ``` + +4. Execute a contract with a function that takes parameters: + ```sh + forge debug src/Contract.sol --sig "foo(string,uint256)" "hello" 100 + ``` + +5. Execute a contract with raw calldata: + ```sh + forge debug src/Contract.sol --sig "0x..." + ``` + +### SEE ALSO + +[forge](./forge.md), [forge test](./forge-test.md) + +[debugger]: ../../forge/debugger.md +[cheatcodes]: ../../cheatcodes/ diff --git a/src/reference/forge/forge.md b/src/reference/forge/forge.md index 1f17b7125..4f187ccbd 100644 --- a/src/reference/forge/forge.md +++ b/src/reference/forge/forge.md @@ -91,6 +91,9 @@ This program is a set of tools to build, test, fuzz, debug and deploy Solidity s #### Utility Commands +[forge debug](./forge-debug.md) +    Debug a single smart contract as a script. + [forge bind](./forge-bind.md)     Generate Rust bindings for smart contracts. diff --git a/src/reference/forge/utility-commands.md b/src/reference/forge/utility-commands.md index 341cbed96..bd3e78e18 100644 --- a/src/reference/forge/utility-commands.md +++ b/src/reference/forge/utility-commands.md @@ -1,9 +1,10 @@ ## Utility Commands +- [forge debug](./forge-debug.md) - [forge bind](./forge-bind.md) -- [forge cache](./forge-cache.md) -- [forge cache clean](./forge-cache-clean.md) -- [forge cache ls](./forge-cache-ls.md) -- [forge script](./forge-script.md) +- [forge cache](./forge-cache.md) +- [forge cache clean](./forge-cache-clean.md) +- [forge cache ls](./forge-cache-ls.md) +- [forge script](./forge-script.md) - [forge upload-selectors](./forge-upload-selectors.md) - [forge doc](./forge-doc.md)