@zigrivers/scaffold 3.26.0 → 3.28.0

package/content/knowledge/web3/web3-project-structure.md

@@ -0,0 +1,212 @@
+---
+name: web3-project-structure
+description: Opinionated Foundry project layout for smart-contract teams — src, test, script, lib, broadcast, foundry.toml, remappings — covering test naming, deploy provenance, and what belongs in git
+topics: [web3, project-structure, foundry, solidity]
+---
+
+A smart-contract repository is read by more adversarial eyes than almost any other kind of codebase: auditors, MEV searchers, frontrunners, and the occasional regulator. Structure carries weight that goes beyond developer ergonomics. An auditor opening the repo for the first time should be able to find the contract under review, its tests, its deploy script, and its on-chain deployment receipts within thirty seconds. Gas snapshots and fuzz seeds need a fixed home so regressions are diffable. Broadcast logs are the audit trail tying a verified contract address back to a commit SHA — losing or muddling them turns "which version is mainnet running?" into a forensic exercise. Foundry's conventions answer most of these questions; this doc records the opinionated version a team should adopt before the first PR lands.
+
+## Summary
+
+A Foundry project has six top-level directories, each answering one question: `src/` (contracts under audit), `test/` (Foundry tests mirroring `src/`), `script/` (deploy and management scripts inheriting `Script`), `lib/` (forge-installed dependencies, committed as submodules or git-trees), `broadcast/` (deploy logs keyed by chain ID and script name), and `docs/` (NatSpec-generated or hand-written architecture notes). `foundry.toml` at the root configures the compiler, fuzz/invariant runners, and formatter; `remappings.txt` aliases `lib/` paths so imports stay readable. The `.gitignore` excludes `cache/`, `out/`, and broadcast directories for ephemeral local chains (anvil, chain ID 31337), but **keeps** broadcast artifacts for canonical chain IDs (1, 10, 8453, 42161, ...) because they are the deploy provenance. Tests follow strict naming — `test_`, `testFuzz_`, `invariant_` — so the runner can pick them up and reviewers can read intent off the function name.
+
+## Deep Guidance
+
+### Top-level layout
+
+```
+project-root/
+├── src/                    # Contracts under audit — the deliverable
+│   ├── interfaces/         # I*.sol interfaces, importable by consumers
+│   ├── libraries/          # Pure libraries (no state)
+│   └── tokens/             # Domain-grouped subdirectories
+├── test/                   # Foundry tests — mirrors src/
+│   ├── unit/               # Per-contract unit tests
+│   ├── integration/        # Multi-contract / forked-mainnet tests
+│   ├── invariant/          # Invariant suites + Handler contracts
+│   └── utils/              # Shared test helpers, mocks, base contracts
+├── script/                 # Deploy + management scripts (forge script)
+│   ├── Deploy.s.sol
+│   └── Upgrade.s.sol
+├── lib/                    # forge install dependencies (submodules)
+│   ├── forge-std/
+│   ├── openzeppelin-contracts/
+│   └── solmate/
+├── broadcast/              # Deploy artifacts keyed by script + chain ID
+│   └── Deploy.s.sol/
+│       ├── 1/              # Mainnet — KEEP, this is provenance
+│       ├── 10/             # Optimism — KEEP
+│       └── 31337/          # Anvil — gitignored
+├── docs/                   # NatSpec output or hand-written architecture
+├── foundry.toml            # Project config
+├── remappings.txt          # Import aliases for lib/
+├── .gitignore
+└── README.md
+```
+
+One-liners:
+- `src/` — every contract that ships; group by domain, never by Solidity language feature
+- `test/` — mirrors `src/` so reviewers can find the test for any contract in one jump
+- `script/` — every deploy, upgrade, and ops script (parameter tuning, role grants); each inherits `forge-std/Script.sol`
+- `lib/` — third-party Solidity tracked via `forge install` (git submodules under the hood)
+- `broadcast/` — receipts from `forge script --broadcast`; partition by chain ID; **keep** canonical chains, gitignore ephemeral ones
+- `docs/` — `forge doc` output or hand-written `architecture.md`, `threat-model.md`, `invariants.md`
+
+### `foundry.toml`
+
+`foundry.toml` is the project config — compiler version, optimizer settings, fuzz/invariant runner knobs, formatter rules, and per-profile overrides. A minimal but production-shaped config:
+
+```toml
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+test = "test"
+script = "script"
+solc_version = "0.8.26"
+evm_version = "cancun"
+optimizer = true
+optimizer_runs = 200
+via_ir = false
+bytecode_hash = "none"           # Reproducible builds (no metadata hash)
+cbor_metadata = false
+gas_reports = ["*"]
+
+[profile.ci]
+fuzz = { runs = 10_000 }
+invariant = { runs = 256, depth = 128 }
+verbosity = 3
+
+[fmt]
+line_length = 120
+tab_width = 4
+bracket_spacing = true
+int_types = "long"               # uint256 not uint, by name
+quote_style = "double"
+number_underscore = "thousands"  # 1_000_000
+
+[fuzz]
+runs = 256                       # Local default; CI overrides via [profile.ci]
+max_test_rejects = 65_536
+
+[invariant]
+runs = 64
+depth = 32
+fail_on_revert = false
+```
+
+`optimizer_runs` is the only setting non-obvious enough to justify thinking. The number is **not** "how many times to run the optimizer" — it's the expected number of times each opcode will run over the contract's lifetime. Higher values trade deploy-time bytecode size for cheaper runtime gas. Defaults:
+- `200` (Solidity default) — balanced; right for most contracts including infrequently-called governance
+- `1_000_000` — protocol contracts with hot paths (AMMs, lending pools, perp engines); pay extra deploy cost once, save gas on every swap forever
+- `1` — one-shot contracts (deploy scripts, factories that deploy once and self-destruct conceptually); minimize deploy cost
+
+The `ci` profile overrides fuzz runs to 10k for thorough coverage on PRs; locally 256 keeps `forge test` snappy.
+
+### Test naming
+
+Foundry's runner discovers tests by function-name prefix. Three prefixes matter, and the convention is load-bearing — auditors read intent off the name:
+
+- `test_<unit>_<behavior>` — concrete unit tests; e.g. `test_transfer_revertsWhenInsufficientBalance`
+- `testFuzz_<unit>_<property>` — property tests with fuzzed inputs; e.g. `testFuzz_deposit_creditsExactAmount(uint256 amount)`
+- `invariant_<property>` — invariant tests run by the invariant engine over a stateful handler; e.g. `invariant_totalSupplyEqualsSumOfBalances`
+
+File mirror: a contract `src/Vault.sol` gets its tests at `test/unit/Vault.t.sol` (the `.t.sol` suffix is convention, not required, but make it consistent across the repo). Invariant suites live in `test/invariant/Vault.invariants.t.sol` with their `Handler` contract alongside.
+
+```solidity
+// test/unit/Vault.t.sol
+contract VaultTest is Test {
+    Vault vault;
+
+    function setUp() public {
+        vault = new Vault();
+    }
+
+    function test_deposit_creditsBalance() public {
+        vault.deposit{value: 1 ether}();
+        assertEq(vault.balanceOf(address(this)), 1 ether);
+    }
+
+    function testFuzz_deposit_creditsExactAmount(uint96 amount) public {
+        vm.deal(address(this), amount);
+        vault.deposit{value: amount}();
+        assertEq(vault.balanceOf(address(this)), amount);
+    }
+}
+```
+
+Use `uint96` (or another bounded type) for fuzz parameters tied to ETH amounts — full `uint256` blows the available balance and triggers `max_test_rejects` exhaustion.
+
+### Deploy scripts and `broadcast/`
+
+Deploy scripts inherit `forge-std/Script.sol` and read environment-specific addresses via `vm.envAddress`. Hard-coded addresses in script bodies are a category of bug — they survive a `git mv` from staging to mainnet and you find out at $4 gwei.
+
+```solidity
+// script/Deploy.s.sol
+import {Script} from "forge-std/Script.sol";
+import {Vault} from "../src/Vault.sol";
+
+contract Deploy is Script {
+    function run() external returns (Vault vault) {
+        address admin = vm.envAddress("ADMIN_ADDRESS");
+        uint256 pk = vm.envUint("DEPLOYER_PK");
+
+        vm.startBroadcast(pk);
+        vault = new Vault(admin);
+        vm.stopBroadcast();
+    }
+}
+```
+
+Running `forge script script/Deploy.s.sol --rpc-url $RPC --broadcast --verify` writes a receipt to `broadcast/Deploy.s.sol/<chainId>/run-latest.json` and a timestamped copy. That JSON contains the deployed address, transaction hash, block number, constructor args, and a SHA tying it back to the commit. **This is the provenance artifact.** Keep it for canonical chains; without it, "which commit deployed the mainnet Vault at 0xabc..." becomes archaeology. Verify on Etherscan in the same command (`--verify`) so the audit trail extends to the public block explorer.
+
+### `lib/` and remappings
+
+Solidity dependencies are installed via `forge install`, which adds the upstream repo as a git submodule under `lib/`:
+
+```bash
+forge install OpenZeppelin/openzeppelin-contracts@v5.0.0
+forge install transmissions11/solmate
+forge install foundry-rs/forge-std
+```
+
+Pin to a tag (`@v5.0.0`), never to `main`. Submodule SHAs are recorded in `.gitmodules` and the commit, so a fresh `forge install` after clone produces the same dependency set.
+
+Imports through `lib/openzeppelin-contracts/contracts/...` are ugly. `remappings.txt` aliases them:
+
+```
+@openzeppelin/=lib/openzeppelin-contracts/
+@openzeppelin-upgradeable/=lib/openzeppelin-contracts-upgradeable/
+solmate/=lib/solmate/src/
+forge-std/=lib/forge-std/src/
+```
+
+Then `import "@openzeppelin/contracts/token/ERC20/ERC20.sol";` resolves cleanly. Keep `remappings.txt` checked in; some IDE plugins and `forge` itself read it.
+
+### `.gitignore`
+
+```gitignore
+# Build artifacts
+cache/
+out/
+
+# Coverage
+lcov.info
+
+# Node (Hardhat carryovers, JS tooling)
+node_modules/
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Anvil / ephemeral local chains — chain ID 31337
+broadcast/*/31337/
+broadcast/**/dry-run/
+
+# Editor
+.vscode/
+.idea/
+```
+
+The load-bearing line is `broadcast/*/31337/`. Anvil's chain ID is 31337 and every local script run leaves a receipt; those are noise. Mainnet (`1`), Optimism (`10`), Base (`8453`), Arbitrum (`42161`), and other canonical chain IDs are **not** in the ignore list because their broadcast artifacts are the on-chain deploy provenance. Treat them with the same care as the contracts themselves: commit, review, and tag at release.

package/content/knowledge/web3/web3-requirements.md

@@ -0,0 +1,152 @@
+---
+name: web3-requirements
+description: Problem framing, invariants, threat model, trust assumptions, and success metrics for shipping smart contracts and protocols to EVM chains
+topics: [web3, requirements, invariants, threat-model, security]
+---
+
+A smart contract shipped to an EVM chain without a written invariant set, a threat model, and an explicit list of trust assumptions is a guessing game with adversarial counterparties and irreversible state. This document defines the acceptance spec for a contract or protocol going to Ethereum mainnet, an L2 (Optimism, Arbitrum, Base), or a compatible sidechain. The audience is a senior Solidity engineer or protocol architect who can ship code but has not yet hardened it against funded adversaries. The goal is to force, in writing, the questions an auditor will ask on day one.
+
+## Summary
+
+A web3 requirements doc states what the contract does for which users (problem framing), enumerates the invariants that must hold across every reachable state, names the threat model in terms of capabilities and time horizon, lists each trust assumption as a documented failure mode, and defines success in concrete economic, gas, or capability terms. State invariants up front and write them as Foundry invariant tests before you finish the implementation. If you cannot enumerate your trust assumptions, you have not designed a protocol — you have written code that happens to compile.
+
+## Deep Guidance
+
+### Problem framing
+
+The framing answers one question: what does this contract do for which users so that what becomes possible. Write it before you open `forge init`. The template below forces concrete nouns and verbs; if you find yourself writing "leverage" or "unlock value" you are not ready.
+
+```
+This contract does <user-visible action> for <user class> so that <decision/outcome>.
+```
+
+Worked example — a yield vault: "This contract lets monthly retail depositors deposit ETH and earn variable yield routed through Aave v3, so that they can hold a yield-bearing position without managing positions themselves." That sentence implies the whole surface area: deposit, withdraw, accounting for accrued yield, an external adapter to Aave, an admin for adapter rotation. Everything else is implementation.
+
+Drop the framing into a `docs/spec.md` block at the top of the repo. Keep out-of-scope explicit — out-of-scope is where audits find missing checks.
+
+```markdown
+# docs/spec.md
+user_action: deposit ETH; withdraw ETH + accrued yield
+user_class: retail depositors holding their own keys (EOAs and Safe multisigs)
+outcome: passive yield routed through Aave v3 on Optimism
+out_of_scope:
+  - non-ETH assets
+  - leveraged positions
+  - cross-chain bridging (vault is single-chain only)
+  - permissioned access (anyone with ETH can deposit)
+```
+
+### Invariants
+
+Invariants are properties that must hold across every reachable state and every call sequence. They are not unit-test assertions about one transaction — they are global truths the protocol exposes. Write them in English first, then in a Foundry invariant test before you finish the implementation. If an invariant is hard to state in one sentence, decompose it; if it cannot be tested with a fuzzer, it is not really an invariant.
+
+Opinionated defaults for a vault-style contract:
+
+- **Conservation**: `totalAssets()` is greater than or equal to the sum of user-owed principal. The vault never owes more than it can pay.
+- **Solvency**: at any block, a full sequential withdrawal of every depositor at their current share would not revert for accounting reasons.
+- **Monotonicity of share price**: in the absence of admin-triggered loss recognition, `convertToAssets(1e18)` is non-decreasing. A surprise drop indicates a bug or an external loss the protocol failed to flag.
+- **Access control**: only `admin` can call functions tagged `onlyAdmin`. Stated as `forall caller != admin, call to onlyAdmin function reverts`.
+- **No reentrancy reachable state**: no external call to user-controlled code happens before state writes are finalized in any deposit/withdraw path.
+
+Encode them as Foundry invariant tests. The handler is the load-bearing part — a weak handler proves nothing.
+
+```solidity
+// test/invariant/VaultInvariants.t.sol
+pragma solidity ^0.8.24;
+
+import {Test} from "forge-std/Test.sol";
+import {Vault} from "src/Vault.sol";
+import {VaultHandler} from "./VaultHandler.sol";
+
+contract VaultInvariants is Test {
+    Vault internal vault;
+    VaultHandler internal handler;
+
+    function setUp() public {
+        vault = new Vault();
+        handler = new VaultHandler(vault);
+        targetContract(address(handler));
+    }
+
+    /// Conservation: assets under management cover all outstanding shares.
+    function invariant_solvency() public view {
+        uint256 owed = vault.convertToAssets(vault.totalSupply());
+        assertGe(vault.totalAssets(), owed, "vault is insolvent");
+    }
+
+    /// Share price is monotonic in the absence of admin loss recognition.
+    function invariant_sharePriceMonotonic() public view {
+        assertGe(vault.convertToAssets(1e18), handler.lastSharePrice());
+    }
+}
+```
+
+Run with `forge test --match-contract VaultInvariants --fuzz-runs 50000`. A passing invariant suite at 50k runs is a precondition for audit submission — not a substitute for it.
+
+### Threat model
+
+A threat model names who attacks, with what capabilities, on what time horizon, and — critically — who you do not defend against. Skipping the last part is how teams ship contracts that are "secure" against an unspecified adversary and break against a real one.
+
+Rubric, in order of how often each is skipped:
+
+- **Capabilities**: what can the attacker do on-chain. Concretely: deploy arbitrary contracts, hold arbitrary token balances, call any public function in any order, observe and reorder mempool transactions (front-running), pay arbitrary gas, hold flash-loan-scale capital (think hundreds of millions of dollars for a single transaction on mainnet), submit governance proposals if your protocol has on-chain governance, manipulate spot prices on thin DEX pools.
+- **Time horizon**: are we defending across one block (atomic flash-loan attack), one transaction batch (sandwich), a governance timelock window (typically 24-72 hours), or months (slow-roll oracle drift). Different defenses apply at each horizon.
+- **Out of scope**: name them. Common honest answers: nation-state actors capable of reorgs on L1, the chain itself going down or censoring, supply-chain compromise of a dependency outside the audit boundary, social-engineering of the multisig signers, an exploit in the underlying L2 sequencer.
+
+Concrete attack scenarios to write down before audit:
+
+- **Oracle manipulation**: an adversary moves the price reported by a feed (spot DEX TWAP on a thin pool, a stale Chainlink feed during a fast move) and exploits a function that trusts it. Defense: use a Chainlink feed with a heartbeat check and a deviation circuit-breaker, never a single-block DEX spot price.
+- **Governance proposal abuse**: an adversary accumulates governance tokens (or buys voting power via a flash loan against a vulnerable token design) and pushes a malicious proposal — for example, upgrading the vault implementation to one that drains funds. Defense: timelock all upgrade and parameter changes; size the timelock to the off-chain alerting and response window.
+- **Reentrancy via callbacks**: any function that makes an external call into user-controlled code before finalizing state is vulnerable. Defense: checks-effects-interactions, plus `nonReentrant` on every function that touches accounting. Treat ERC-777, ERC-1363, and any token with transfer hooks as user-controlled code for this purpose.
+- **Front-running and MEV**: on a public mempool, any profitable action you broadcast is visible. Defense: commit-reveal for sensitive ordering, private mempools (Flashbots Protect) for admin actions, or making the action order-independent. Sandwich-resistance for swaps means a strict slippage cap on every quote, sourced from the caller and not from an oracle the attacker can move.
+- **Donation / inflation attack**: an attacker deposits a tiny first share, then transfers a large amount directly to the vault address to inflate share price and round the next depositor's shares to zero. Defense: virtual shares / dead shares in the ERC-4626 implementation, or an initial deposit by the deployer that is permanently locked.
+
+### Trust assumptions
+
+Every contract trusts something. The job here is to make each trust explicit, paired with the failure mode if the trust is misplaced. The list below is the minimum for a DeFi vault — extend it for your specific design.
+
+- **Price oracle (Chainlink ETH/USD on the target chain)**: trusted to be correct within the configured deviation and heartbeat. If it fails — feed goes stale during a fast move, or the off-chain operators collude — the vault can mis-price deposits and withdrawals. Mitigation: pause-on-stale check (`updatedAt` is within the heartbeat window) and an emergency pause that the multisig can trigger.
+- **Upgrade admin (3-of-5 Safe multisig)**: trusted to act in users' interest and to keep keys secure. If three signers are compromised, they can upgrade the vault to drain funds. Mitigation: 48-hour timelock on every upgrade; off-chain monitoring with on-call alerting; a separate guardian role with veto power on suspicious upgrades but no positive authority.
+- **Underlying protocol (Aave v3)**: trusted to honor its own accounting and not to grief depositors. If Aave's pool is compromised, the vault inherits the loss. Mitigation: cap exposure per adapter; document the inherited risk in the user-facing README.
+- **Solidity compiler and toolchain**: trusted to compile source to faithful bytecode. Mitigation: pin a specific `solc` version (e.g. `0.8.24`), reproducible builds via Foundry's `forge build --deterministic`, and verified source on Etherscan.
+- **The chain itself**: trusted not to reorg meaningfully or to censor the contract. For L2s, also trusted to honor its withdrawal-window guarantees. Document the chain-specific risk (e.g. "this protocol is deployed on Base; a Base sequencer outage halts deposits and withdrawals until it recovers").
+
+Each line is a documented risk. Surface them in the user-facing docs — not just in the audit report — so depositors can size their exposure.
+
+### Success metrics
+
+State success in concrete numbers, written before launch. Vague goals ("be secure", "have lots of users") let the team declare victory after any outcome. Three categories to name:
+
+- **Economic security**: a $-TVL bar paired with a no-exploit time horizon. Example: `$50M TVL with no successful exploit in the first 6 months post-launch`. The dollar figure forces the team to size the bug bounty (a useful default: 10% of TVL up to a cap), and the time horizon forces a monitoring commitment.
+- **Gas budget**: per-function ceilings on the target chain, measured by `forge snapshot`. Example: `deposit costs less than 200k gas on Optimism; withdraw less than 250k`. Encode these as snapshot tests in CI so a regression breaks the build, not just makes things slightly more expensive.
+- **Capability counts**: scale targets that drive design. Example: `supports 10,000 unique depositors without unbounded loops`, or `supports adapter rotation without migrating user balances`. Each capability target rules out a class of naive implementations (no `address[] depositors` you iterate over).
+
+```solidity
+// test/gas/Snapshot.t.sol
+pragma solidity ^0.8.24;
+import {Test} from "forge-std/Test.sol";
+import {Vault} from "src/Vault.sol";
+
+contract GasSnapshot is Test {
+    Vault internal vault;
+    address internal user = address(0xBEEF);
+
+    function setUp() public { vault = new Vault(); vm.deal(user, 10 ether); }
+
+    function test_gas_deposit() public {
+        vm.prank(user);
+        uint256 g = gasleft();
+        vault.deposit{value: 1 ether}();
+        uint256 used = g - gasleft();
+        assertLt(used, 200_000, "deposit exceeds gas budget");
+    }
+}
+```
+
+A few more disciplines that pay off late but cost little up front:
+
+- **Deployment script as code**: the canonical deployment lives in `script/Deploy.s.sol`, not in a one-off REPL session. Anyone should be able to reproduce mainnet bytecode from a tagged commit.
+- **Pause-and-recover drill**: before mainnet, simulate the full incident response on a fork — the multisig signs, the contract pauses, an exploit is contained, an upgrade is queued through timelock, and depositors are made whole. If the runbook is not exercised, it does not exist.
+- **Post-deploy verification**: verified source on Etherscan or the L2 explorer, a published address registry (one line per chain) committed to the repo, and a public read-only dashboard for the invariant metrics so anyone can re-derive solvency from on-chain state.
+
+Taken together — framing, invariants, threat model, trust assumptions, success metrics — these five sections are what an auditor will ask for in the kickoff call. Write them before you ship, commit them next to the contracts, and treat any drift as a scope change that requires re-auditing.

package/content/knowledge/web3/web3-security.md

@@ -0,0 +1,163 @@
+---
+name: web3-security
+description: Layered security practices for smart contracts heading to mainnet — defense-in-depth, Checks-Effects-Interactions, pull payments, OpenZeppelin primitives, pause + multisig, and input validation discipline
+topics: [web3, security, solidity, openzeppelin, defense-in-depth]
+---
+
+A smart contract is a public, immutable bank vault that anyone on the planet can call. The mempool is hostile, the bytecode is permanent, and the only patch deployment is a redeploy + migration that your users may or may not follow. Most exploits aren't novel cryptography — they're missed standard patterns: a state update after an external call, a `tx.origin` check that a phishing contract bypassed, a `transfer` to a contract that reverts and bricks an auction. Layered defense beats clever one-off mitigations, every time.
+
+## Summary
+
+Layer your defenses: a written spec with invariants, secure-by-construction patterns, static analysis and forge tests, an external audit, then a bug bounty — each catches what the previous layer missed. Use `Checks-Effects-Interactions` religiously and wrap any function that touches an external contract with `ReentrancyGuard` from OpenZeppelin. Prefer `pull payments` (users withdraw) over push (contract sends) so a malicious or buggy recipient cannot stall everyone else. Treat `OpenZeppelin` as your baseline — audited, well-known primitives (`AccessControl`, `Pausable`, `SafeERC20`) have fewer surprises than hand-rolled equivalents. Wire a `Pausable` kill-switch to a 2-of-N or 3-of-N Safe multisig and time-lock the truly dangerous operations.
+
+## Deep Guidance
+
+### Defense-in-depth layered model
+
+Treat security as five distinct layers, each independently valuable. The point of layering is that any single layer will miss something — the protocol survives because the next layer catches it.
+
+1. **Spec and invariants** — Before any Solidity, write down what must always be true: "total supply equals sum of balances," "no user can withdraw more than they deposited," "only governance can change fee tiers," "the protocol is solvent at every block." These become the oracle for tests, fuzzing, and audit conversations. A contract without a written invariant set is a contract whose author has not decided what "correct" means, and reviewers cannot tell you whether the code is correct against an undefined target.
+2. **Secure-by-construction patterns** — CEI, pull-payments, `ReentrancyGuard`, custom errors with parameters, `immutable` where possible, explicit visibility. Most exploits target contracts that skipped one of these — the pattern existed, the author didn't reach for it.
+3. **Tooling** — Slither for static analysis on every PR, Foundry fuzz and invariant tests aimed directly at the spec from layer 1, Echidna or Halmos for deeper property testing, mythril or symbolic execution where it earns its keep. CI fails the build on new Slither high/medium findings; coverage gates keep the test suite from rotting.
+4. **Audit** — One or two reputable firms (Trail of Bits, OpenZeppelin, Spearbit, Code4rena contest). Audit late enough that the code is frozen, early enough that fixes don't push the launch. Code freeze before audit, no scope creep during. Treat every finding — even "informational" — as a real signal about your design.
+5. **Bug bounty** — Immunefi or Cantina, sized to the TVL at risk. A $50k bounty on a $50M protocol is an insult to whitehats and an invitation to blackhats; scale rewards to the prize. Run the bounty continuously, not for a launch week and then off.
+
+See `web3-audit-workflow.md` for the tooling integration details and `web3-common-vulnerabilities.md` for the SWC-level checklist that audits work through.
+
+### Checks-Effects-Interactions
+
+The single most important pattern in Solidity. Order every state-changing function as: (1) **Check** preconditions and inputs, (2) update **Effects** in storage, (3) make external **Interactions** last. Reentrancy exploits work by letting an attacker re-enter your function before step 2 has run; CEI removes that window.
+
+Vulnerable:
+
+```solidity
+function withdraw() external {
+    uint256 amount = balances[msg.sender];
+    (bool ok, ) = msg.sender.call{value: amount}(""); // INTERACTION first
+    require(ok, "send failed");
+    balances[msg.sender] = 0;                          // EFFECT after — exploitable
+}
+```
+
+Corrected with CEI plus `ReentrancyGuard` as a belt-and-braces backstop:
+
+```solidity
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+contract Vault is ReentrancyGuard {
+    mapping(address => uint256) public balances;
+    error NothingToWithdraw();
+    error TransferFailed();
+
+    function withdraw() external nonReentrant {
+        uint256 amount = balances[msg.sender];     // CHECK
+        if (amount == 0) revert NothingToWithdraw();
+        balances[msg.sender] = 0;                  // EFFECT (before interaction)
+        (bool ok, ) = msg.sender.call{value: amount}(""); // INTERACTION last
+        if (!ok) revert TransferFailed();
+    }
+}
+```
+
+`nonReentrant` is cheap insurance for the case where you, or a future maintainer, miss a CEI ordering somewhere subtle (cross-function reentrancy, view-function reentrancy on read-after-write).
+
+### Pull-payments over push
+
+Never proactively send funds to N users in a loop. One reverting recipient bricks the whole batch — a single griefing contract can stall every auction, raffle, or dividend you ship. Instead, credit each user's balance in storage and let them pull:
+
+```solidity
+mapping(address => uint256) public pending;
+
+function _credit(address user, uint256 amount) internal {
+    pending[user] += amount;
+}
+
+function claim() external nonReentrant {
+    uint256 amount = pending[msg.sender];
+    if (amount == 0) revert NothingToWithdraw();
+    pending[msg.sender] = 0;
+    (bool ok, ) = msg.sender.call{value: amount}("");
+    if (!ok) revert TransferFailed();
+}
+```
+
+The contract's job is bookkeeping; the user's job is taking custody. If their withdrawal fails — recipient is a contract that reverts, ran out of gas, or hit a blacklist — only they are affected, and they can fix it on their side without coordinating with everyone else in the queue. OpenZeppelin's `PullPayment` contract is a drop-in implementation if you want one less thing to write.
+
+The rare exceptions where push is acceptable: payouts to a single, trusted address you control (your treasury); ERC-20 `transfer` calls inside `SafeERC20` where you've already validated the recipient. Even then, never wrap a push in a user-iterating loop.
+
+### OpenZeppelin as baseline
+
+Pin a specific OpenZeppelin Contracts version in `foundry.toml` remappings and inherit from their primitives instead of hand-rolling. The core set worth knowing cold:
+
+- `ReentrancyGuard` — the `nonReentrant` modifier shown above. Tracks a `_status` slot to reject reentrant calls cheaply.
+- `Pausable` — `whenNotPaused` modifier on user-facing entry points; emergency `_pause()` callable by a privileged role. Pair with `AccessControl` so the pauser role is granular and revocable.
+- `AccessControl` — role-based permissions instead of a single `owner`. Lets you separate `PAUSER_ROLE`, `UPGRADER_ROLE`, and `TREASURER_ROLE` to different keys, with `DEFAULT_ADMIN_ROLE` controlling grants. Deep dive in `web3-access-control.md`.
+- `SafeERC20` — `safeTransfer`, `safeTransferFrom`, `forceApprove`. Handles non-standard tokens that don't return a bool (USDT) and the approve-race-condition pattern. Use it for every ERC-20 interaction without exception.
+- `EIP712` and `Nonces` — typed structured signatures and replay-protected nonces when you need permit-style or meta-tx flows.
+
+These are audited, widely deployed, and reviewed continuously by the ecosystem. A hand-rolled `nonReentrant` will pass review once and then rot as the team rotates; OZ's gets re-validated every release and every external audit of every protocol that uses it. Pin the version (`@openzeppelin/contracts@5.0.2`) in `package.json` and the remapping so an `npm update` cannot silently swap your security primitives, and read the changelog before upgrading — major versions occasionally change defaults (initializer patterns, role bytes32 encoding) in ways that matter.
+
+### Pause + emergency multisig
+
+Wire a kill-switch on every entry point that moves funds, and put the pause key behind a Safe multisig — never an EOA. Two-of-three for small protocols, three-of-five for serious TVL, with signers on different hardware in different physical locations.
+
+```solidity
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
+
+contract Market is AccessControl, Pausable {
+    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
+
+    constructor(address multisig) {
+        _grantRole(DEFAULT_ADMIN_ROLE, multisig); // multisig owns role management
+        _grantRole(PAUSER_ROLE, multisig);
+    }
+
+    function pause() external onlyRole(PAUSER_ROLE) { _pause(); }
+    function unpause() external onlyRole(PAUSER_ROLE) { _unpause(); }
+
+    function trade(uint256 amount) external whenNotPaused {
+        // ... real logic ...
+    }
+}
+```
+
+Anything irreversible — upgrading an implementation, draining the treasury, raising fee caps, changing oracle sources — goes behind a `TimelockController` with a 24–72 hour delay so users have time to exit if the multisig is compromised or coerced. The pause itself stays instantaneous (you can't time-lock an emergency); the dangerous knobs are slow.
+
+Two adjacent practices worth wiring up at the same time:
+
+- Publish a public dashboard or `roles.md` of who holds which role and where the timelock points, so users can verify the kill-switch exists and is wired correctly. An invisible kill-switch is a trust claim, not a security control.
+- Rehearse a pause-and-recover with the multisig signers at least once before mainnet so the first time someone signs is not the night of an incident. Practice the unhappy path: signer unavailable, hardware wallet bricked, mis-typed function selector.
+- Subscribe the multisig to an on-chain monitoring service (OpenZeppelin Defender, Forta, Tenderly Alerts) that pages on anomalous activity — large withdrawals, oracle deviation, paused-state changes. The kill-switch is only useful if someone is watching.
+
+### Input validation and visibility
+
+Validate every input at the public boundary with custom errors that carry the offending values — they're cheaper than revert strings and far more useful when triaging a failed tx:
+
+```solidity
+error AmountZero();
+error AmountExceedsCap(uint256 requested, uint256 cap);
+error RecipientZero();
+
+uint256 public immutable cap;            // immutable: set in constructor, never changes
+uint8 public constant DECIMALS = 18;     // constant: known at compile time
+
+function deposit(address to, uint256 amount) external whenNotPaused {
+    if (to == address(0)) revert RecipientZero();
+    if (amount == 0) revert AmountZero();
+    if (amount > cap) revert AmountExceedsCap(amount, cap);
+    // ...
+}
+```
+
+Mark functions `external` rather than `public` unless you call them internally — `external` is cheaper and signals "this is an entry point, audit the inputs." Use `immutable` for constructor-set values (deploy-time addresses, supply caps, the multisig address) and `constant` for compile-time literals; both save gas and tell the reader "this cannot change," which is itself a security property. Default state variables to `private` or `internal` and expose specific getters where you need them, rather than leaning on `public` which generates a getter you may not have meant to commit to as part of the ABI.
+
+Custom errors with parameters are strictly better than `require(cond, "string")`: they're cheaper, they survive ABI decoding so off-chain tools can show the failing values, and they force you to name the failure mode rather than describe it. Reserve `require` strings for one-off scripts and tests.
+
+### What NOT to use
+
+- **`tx.origin` for authorization** — `tx.origin` is the EOA that started the transaction, which a phishing contract can trick a user into being. Always check `msg.sender` (the immediate caller). `tx.origin` is acceptable only for narrow checks like "refuse to be called by any contract" (`require(tx.origin == msg.sender)`), and even that is fragile in a post-EIP-3074 / account-abstraction world.
+- **Raw low-level `call` without checking return data** — `(bool ok, ) = addr.call(...)` ignores the actual return payload; an unverified `ok` says "the call returned," not "the call succeeded as intended." Use `SafeERC20` for tokens and check `ok` plus decode return data for everything else. Bubble up the revert reason where the caller cares.
+- **Unbounded loops over user-supplied arrays** — gas grows with N, an attacker submits a million-element array, the function reverts forever and locks whatever it gated. Cap input lengths or paginate. The same hazard applies to iterating over a `users` mapping that anyone can grow.
+- **Calling arbitrary user-supplied addresses** — every external call is a trust boundary. Whitelist the targets you call (routers, oracles, your own modules) via an admin-managed allowlist; never `target.call(data)` where `target` came from `msg.sender`. If the protocol genuinely needs to integrate with arbitrary external contracts, isolate the interaction in a sandbox contract with no privileges and no funds beyond the immediate call's value.
+- **`block.timestamp` for fine-grained ordering or randomness** — miners (or proposers post-merge) have a small window to nudge it. Fine for "did 24 hours pass since deploy"; not fine for "who got the millisecond-precise winning bid" or as an entropy source.