feat(guides): add steps (#1610)

Author: yash-atreya

vocs/docs/pages/guides/deterministic-deployments-using-create2.md

@@ -14,15 +14,18 @@ With `CREATE2`, you can use the same deployer account to deploy contracts to the
 
 For the best user experience it is recommended to avoid having different addresses of the same deployment across different EVM chains.
 
-## Getting started
+:::note
+This guide is intended to help you get started with configuring deterministic deployments using `CREATE2`.
+By default, `new Counter{salt: salt}()` will use the deterministic deployer at [`0x4e59b44847b379578588920ca78fbf26c0b4956c`](https://github.com/Arachnid/deterministic-deployment-proxy). Note that the deployer may not be available on all EVM chains.
+A different deployer address can be configured by setting `create2_deployer` in `foundry.toml` or by using `--create2-deployer` argument.
 
-> ℹ️ **Note**
->
-> This guide is intended to help you get started with configuring deterministic deployments using `CREATE2`.
-> By default, `new Counter{salt: salt}()` will use the deterministic deployer at [`0x4e59b44847b379578588920ca78fbf26c0b4956c`](https://github.com/Arachnid/deterministic-deployment-proxy). Note that the deployer may not be available on all EVM chains.
-> A different deployer address can be configured by setting `create2_deployer` in `foundry.toml` or by using `--create2-deployer` argument.
+:::
 
-## Configuring your `foundry.toml`
+Follow these steps to set up deterministic deployments:
+
+::::steps
+
+### Configure your `foundry.toml`
 
 In order to reliably deploy to deterministic addresses we will need to make sure our bytecode stays the same. To do so configure our `foundry.toml` as follows:
 
@@ -34,15 +37,23 @@ bytecode_hash = "none"
 cbor_metadata = false
 ```
 
-### Solc version
+### Pin your Solc version
 
 It is required to pin your `solc` (Solidity) version. It is generally recommended to use a recent version or, if preferred, the latest version.
 
-### EVM version
+```toml
+solc = "<SOLC_VERSION>"
+```
+
+### Set your EVM version
 
 Next, configure your `evm_version`. It is generally recommended to use the most recent hardfork but depending on your deployment targets this may need to use an older hardfork due to opcode incompatibilities.
 
-### Metadata and bytecode
+```toml
+evm_version = "<EVM_VERSION>"
+```
+
+### Configure metadata and bytecode settings
 
 By default the Solidity compiler appends the hash of the metadata file at end of the bytecode. This bytecode includes things like the compiler version and the ABI.
 
@@ -141,11 +152,11 @@ cbor_metadata = false
 
 You are not including the metadata hash as part of the bytecode. This means that whilst your bytecode can now be deterministic you won't be able to have a [`full match`](https://docs.sourcify.dev/docs/full-vs-partial-match/#full-perfect-matches), only a [`partial match`](https://docs.sourcify.dev/docs/full-vs-partial-match/#partial-matches) when verifying your contracts. Depending on your requirements this may be acceptable.
 
-### Optimizer
+### Configure the optimizer
 
 If you are enabling the `optimizer` make sure your `optimizer_runs` stay consistent.
 
-### Create2 factory
+### Set up the CREATE2 factory
 
 By default, your contracts won't use the default (or specified using the `create2_deployer` configuration) create2 factory and will default to executing the create2 opcode from the contract it's executed on. For example, this behavior occurs when running tests or executing scripts without a private key.
 
@@ -157,6 +168,8 @@ always_use_create_2_factory = true
 
 If you wish to always use the create2 factory. This comes handy if you wish to use the create2 factory deployment addresses in your tests for example.
 
+::::
+
 ## Deploying the contract
 
 When using Solidity's default `CREATE` where the new address of a contract is determined by taking the `hash` of the `sender`'s address and the `sender`'s `nonce`:

vocs/docs/pages/guides/eip712.md

@@ -50,7 +50,7 @@ Uniswap's `Permit2` system utilizes the `PermitHash.sol` library to create hashe
 
 Our objective is to focus on a few hashing functions within `PermitHash.sol`. We will provide these functions with sample data and then use `vm.eip712HashStruct` —with the same data and the canonical EIP-712 type definition— to determine if the generated hashes match.
 
-#### Setting up the test environment
+### Setting up the test environment
 
 Before starting with the validations, we have to create the `PermitHash.t.sol` test file.
 

vocs/docs/pages/guides/forking-mainnet-with-cast-anvil.md

@@ -6,7 +6,11 @@ description: Fork live Ethereum networks using Anvil and interact with real cont
 
 By combining [Anvil][anvil] and [Cast][cast], you can fork and test by interacting with contracts on a real network. The goal of this guide is to show you how to transfer DAI tokens from someone who holds DAI to an account created by Anvil.
 
-## Getting started
+Follow these steps to fork mainnet and transfer DAI tokens:
+
+::::steps
+
+### Fork mainnet with Anvil
 
 Let's start by forking mainnet.
 
@@ -16,7 +20,7 @@ anvil --fork-url https://mainnet.infura.io/v3/$INFURA_KEY
 
 You will see 10 accounts are created with their public and private keys. We will work with `0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266` (Let's call this user Alice).
 
-## Transferring DAI
+### Set up environment variables
 
 Go to Etherscan and search for holders of DAI tokens ([here](https://etherscan.io/token/0x6b175474e89094c44da98b954eedeac495271d0f#balances)). Let's pick a random account. In this example we will be using `0xfc2eE3bD619B7cfb2dE2C797b96DeeCbD7F68e46`. Let's export our contracts and accounts as environment variables:
 
@@ -26,6 +30,8 @@ export DAI=0x6b175474e89094c44da98b954eedeac495271d0f
 export UNLUCKY_USER=0xfc2eE3bD619B7cfb2dE2C797b96DeeCbD7F68e46
 ```
 
+### Check initial balances
+
 We can check Alice's balance using [`cast call`][cast-call]:
 
 ```sh
@@ -44,6 +50,8 @@ cast call $DAI \
 21840114973524208109322438
 ```
 
+### Transfer DAI tokens
+
 Let's transfer some tokens from the unlucky user to Alice using [`cast send`][cast-send]:
 
 ```sh
@@ -60,6 +68,8 @@ blockNumber             15052891
 ...
 ```
 
+### Verify the transfer
+
 Let's check that the transfer worked:
 
 ```sh
@@ -74,6 +84,8 @@ cast call $DAI \
 21540114973524208109322438
 ```
 
+::::
+
 [anvil]: ../reference/anvil/
 [cast]: ../cast/reference/
 [cast-call]: ../cast/reference/cast-call.md

vocs/docs/pages/guides/project-setup/clone-a-verified-contract.mdx

@@ -4,6 +4,10 @@ description: Clone verified on-chain contracts as Foundry projects with source c
 
 ## Clone a Verified Contract
 
+::::steps
+
+### Clone the contract
+
 To clone an on-chain verified contract as a Forge project, use [`forge clone`](/forge/reference/forge-clone), say [WETH9](https://etherscan.io/address/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2) on Ethereum mainnet:
 
 ```sh
@@ -12,16 +16,24 @@ To clone an on-chain verified contract as a Forge project, use [`forge clone`](/
 
 This creates a new directory `WETH9`, configures it as a foundry project and clones all the source code of the contract into it. This also initializes a new `git` repository.
 
+### Review the cloned project
+
+After cloning, you'll see the following output:
+
 ```sh
 // [!include ~/snippets/clone_contract/forge-clone:output]
 ```
 
 The cloned Forge project comes with an additional `.clone.meta` metadata file besides those ordinary files that a normal Forge project has.
 
+### Examine the metadata
+
 Let's see what the `.clone.meta` file looks like:
 
 ```sh
 // [!include ~/snippets/clone_contract/clone-meta:output]
 ```
 
 `clone.meta` is a compact JSON data file that contains the information of the on-chain contract instance, e.g., contract address, constructor arguments, etc. More details of the metadata can be found in the [reference](/forge/reference/forge-clone).
+
+::::

vocs/docs/pages/guides/project-setup/creating-a-new-project.md

@@ -4,6 +4,10 @@ description: Initialize a new Foundry project using forge init with default temp
 
 ## Creating a New Project
 
+::::steps
+
+#### Initialize the project
+
 To start a new project with Foundry, use [`forge init`](/forge/reference/forge-init):
 
 ```sh
@@ -12,31 +16,42 @@ To start a new project with Foundry, use [`forge init`](/forge/reference/forge-i
 
 This creates a new directory `hello_foundry` from the default template. This also initializes a new `git` repository.
 
+:::info
 If you want to create a new project using a different template, you would pass the `--template` flag, like so:
-
 ```sh
 forge init --template https://github.com/foundry-rs/forge-template hello_template
 ```
+:::
 
-For now, let's check what the default template looks like:
+#### Navigate to the project directory
+
+Move into your newly created project:
 
 ```sh
 cd hello_foundry
 ```
 
+#### Explore the project structure
+
+Let's check what the default template looks like:
+
 ```sh
 // [!include ~/snippets/output/hello_foundry/tree:all]
 ```
 
 The default template comes with one dependency installed: Forge Standard Library. This is the preferred testing library used for Foundry projects. Additionally, the template also comes with an empty starter contract and a simple test.
 
-Let's build the project:
+#### Build the project
+
+Compile your contracts:
 
 ```sh
 // [!include ~/snippets/output/hello_foundry/forge-build:all]
 ```
 
-And run the tests:
+#### Run the tests
+
+Execute the test suite:
 
 ```sh
 // [!include ~/snippets/output/hello_foundry/forge-test:all]
@@ -45,3 +60,5 @@ And run the tests:
 You'll notice that two new directories have popped up: `out` and `cache`.
 
 The `out` directory contains your contract artifact, such as the ABI, while the `cache` is used by `forge` to only recompile what is necessary.
+
+::::

vocs/docs/pages/guides/scripting-with-solidity.md

@@ -8,7 +8,7 @@ Solidity scripting is a way to declaratively deploy contracts using Solidity, in
 
 Solidity scripts are like the scripts you write when working with tools like Hardhat; what makes Solidity scripting different is that they are written in Solidity instead of JavaScript, and they are run on the fast Foundry EVM backend, which provides advanced simulation with dry-run capabilities.
 
-## Overview
+## How `forge script` works?
 
 `forge script` does not work in an asynchronous manner. First, it collects all transactions from the script, and only then does it broadcast them all. It can essentially be split into 4 phases:
 
@@ -23,21 +23,25 @@ Transactions that previously failed or timed-out can be submitted again by provi
 
 Given this flow, it's important to be aware that transactions whose behaviour can be influenced by external state/actors might have a different result than what was simulated on step `2`, e.g. front running.
 
-## Getting started
+## Setup `Counter` Project
 
 Let's try to deploy the basic `Counter` contract Foundry provides:
 
 ```sh
 forge init Counter
 ```
 
-Next let's try compiling our contracts to make sure everything is in order.
+Next compile our contracts to make sure everything is in order.
 
 ```sh
 forge build
 ```
 
-## Deploying our contract
+## Deploying the `Counter` contract
+
+::::steps
+
+### Get RPC and Etherscan API Keys
 
 We are going to deploy the `Counter` contract to the Sepolia testnet but in order to do so we will need to complete a few prerequisites:
 
@@ -70,7 +74,7 @@ Some faucets require you to have a balance on Ethereum mainnet.
 
 If so, claim the testnet ETH on a wallet you control and transfer the testnet ETH to your newly created deployer keypair.
 
-4. Get a Sepolia Etherscan API key.
+4. Get a Sepolia Etherscan API key [here](https://docs.etherscan.io/getting-started/viewing-api-usage-statistics).
 
 ### Configuring `foundry.toml`
 
@@ -352,3 +356,5 @@ Transactions saved to: /home/user/counter/broadcast/Counter.s.sol/31337/run-late
 
 Sensitive values saved to: /home/user/counter/cache/Counter.s.sol/31337/run-latest.json
 ```
+
+::::