foundry-scripting-and-deploy

Files (1)

• SKILL.md

SKILL.md (first lines)

# Foundry Scripting and Deployment

You are writing a `forge script` or running a deployment. A script that touches mainnet is a piece of production code; treat it like one. The script is read, reviewed, and re-run. Hardcoded addresses and "I'll fix it later" comments are bugs in waiting.

## The Iron Laws

1. **NEVER HARDCODE A PRIVATE KEY.** Not in the script, not in a config file, not in a comment. Read from `vm.envUint("PRIVATE_KEY")` or use an account / keystore flag. A leaked key takes seconds to drain.
2. **NEVER COMMIT A `.env` FILE.** `.env` belongs in `.gitignore`. Commit `.env.example` with placeholders instead. If you discover a committed `.env`, rotate every key in it immediately — git history is forever.
3. **NEVER RUN `forge script ... --broadcast` WITHOUT A DRY RUN FIRST.** Always run once without `--broadcast` to inspect the simulated traces. Production deploys that revert mid-way cost real gas and real time.
4. **NEVER DEPLOY WITHOUT A CHAIN-ID GUARD.** Every deploy script that encodes chain-specific addresses (oracles, bridges, tokens) asserts `block.chainid` at the top. Deploying the mainnet config to a testnet is embarrassing; deploying the testnet config to mainnet is a catastrophe.
5. **ALWAYS EMIT DEPLOYED ADDRESSES AS JSON.** Downstream tooling (bots, subgraphs, frontends) reads your deploys. Log `{"contract":"Vault","address":"0x...","tx":"0x..."}` so they can parse it, not a human-readable paragraph.
6. **NEVER SKIP VERIFICATION.** Pass `--verify` (or run `forge verify-contract` after) for every mainnet and testnet deploy. Unverified contracts are opaque; users cannot audit what they are signing into.

## Script file shape

```solidity
// SPDX-License-Identifier: MIT
pragma solidity 0.8.26;

import {Script, console2} from "forge-std/Script.sol";
import {Vault} from "../src/Vault.sol";

contract DeployVault is Script {
    function run() external returns (Vault vault) {
        uint256 deployerPk = vm.envUint("DEPLOYER_PRIVATE_KEY");
        address asset = vm.envAddress("VAULT_ASSET");

        vm.startBroadcast(deployerPk);
        vault = new Vault(asset);
        vm.stopBroadcast();

        console2.log("{\"contract\":\"Vault\",\"address\":\"%s\"}", address(vault));
    }
}
```

Conventions:

- One deploy per script file. `DeployVault.s.sol` deploys `Vault`. Don't chain five unrelated deploys in one script.
- Always `return` the deployed contract. Makes composition cleaner when one script calls another.
- Use `console2.log` not `console.log`. `console2` is the updated log API in newer forge-std and does not silently truncate.

## Broadcasting forms

`vm.startBroadcast` has three forms. Pick deliberately.

| Form | Sender | When |
|---|---|---|
| `vm.startBroadcast()` | Default sender inferred from `--sender`, `--private-key`, `--mnemonic`, or `--account` flags passed to `forge script`. | Local dev, flexible CI that provides creds via flags. |
| `vm.startBroadcast(uint256 pk)` | The address derived from `pk`. | Explicit env-var key (`vm.envUint`). |
| `vm.startBroadcast(address from)` | `from`. Requires forge to know the key for `from` (via account, keystore, etc.). | Deploy from a hardware wallet or a named keystore account. |

Prefer `vm.startBroadcast()` with CLI-level auth (`--account deployer` + Foundry keystore) over raw private keys in env. Keystore is encrypted at rest; `.env` is plaintext.

## Environment variable handling

All runtime config comes from env. Read in the script, never from a committed constant.

```solidity
uint256 deployerPk   = vm.envUint("DEPLOYER_PRIVATE_KEY");
address registry     = vm.envAddress("REGISTRY_ADDRESS");
string memory name   = vm.envString("TOKEN_NAME");
bytes32 salt         = vm.envBytes32("CREATE2_SALT");
uint256 chainId      = block.chainid; // read from context, not env
```

### Defaults for local anvil

When developers run the script against anvil, they shouldn't have to set every env var. Use `vm.envOr` for local defaults:

```solidity
// Anvil's default first key, safe because it's well-known and worthless.
uint256 deployerPk = vm.envOr(
    "DEPLOYER_PRIVATE_KEY",
    uint256(0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80)
);
```

**Rule**: fallback defaults are only for local anvil. Never fall back on a mainnet path. The dev private key above is public — do not fund it.

### .env.example

Commit this. Real values never.

```
# .env.example
DEPLOYER_PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
RPC_URL_MAINNET=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
RPC_URL_SEPOLIA=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
ETHERSCAN_API_KEY=YOUR_ETHERSCAN_KEY
VAULT_ASSET=0x0000000000000000000000000000000000000000
```

## Chain-ID guards

Multi-chain scripts read config by chain ID.

```solidity
contract DeployVault is Script {
    struct ChainConfig {
        address asset;
        address oracle;
    }

    function _configForChain() internal view returns (ChainConfig memory c) {
        if (block.chainid == 1) {
            // Mainnet
            c.asset  = 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48; // USDC
            c.oracle = 0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6;
        } else if (block.chainid == 11155111) {
            // Sepolia
            c.asset  = 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238;
            c.oracle = 0xA2F78ab2355fe2f984D808B5CeE7FD0A93D5270E;
        } else if (block.chainid == 31337) {
            // Anvil — deploy mocks in setUp instead
            revert("configure anvil mocks in setUp");
        } else {
            revert(string.concat("unsupported chain: ", vm.toString(block.chainid)));
        }

From idchain-world/id-agents, MIT.

More from idchain-world/id-agents