chore: improve documentation of individual binaries (#1371)

* start adding new docs

* update refs

* clean up

* note

* add anvil overview

* fix list

* fix spacing

Author: zerosnacks

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}}

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
 

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 <RPC_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 <ACCOUNTS>
+                             _   _
+                            (_) | |
+      __ _   _ __   __   __  _  | |
+     / _` | | '_ \  \ \ / / | | | |
+    | (_| | | | | |  \ V /  | | | |
+     \__,_| |_| |_|   \_/   |_| |_|
 
-# The EVM hardfork to use. [default: latest]
-anvil --hardfork <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 <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
 ```
 
+<br>
+
 > 📚 **Reference**
 >
 > See the [`anvil` Reference](../reference/anvil/) for in depth information on Anvil and its capabilities.
-

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 <subcommand>
+### 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 <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 <Your Private Key> 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc $(cast from-utf8 "hello world") --rpc-url http://127.0.0.1:8545/
+```sh
+cast send --private-key <PRIVATE_KEY> 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc $(cast from-utf8 "hello world") --rpc-url http://127.0.0.1:8545/
 ```
 
 <br>
 
 > 📚 **Reference**
-> 
+>
 > See the [`cast` Reference](../reference/cast/) for a complete overview of all the available subcommands.

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.
 
+<br>
+
 > 📚 **Reference**
 >
 > See the [`chisel` Reference](../reference/chisel/) for in depth information on Chisel and its capabilities.
-

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.
+```
+
+<br>
+
+> 📚 **Reference**
+>
+> See the [`forge` Reference](../reference/forge/) for a complete overview of all the available subcommands.