Agent instructionsScan: pass
Solidity Foundry CLAUDE.md
CLAUDE.md for a Foundry project: forge fmt/build/test gates, fuzz and invariant test conventions, a security checklist, and a hard no-deploy rule.
Add a trust badge to your README
[](https://waxmark.app/items/solidity-foundry-claude-md/scan)
# {{PROJECT_NAME}}
Solidity {{SOLC_VERSION}} smart contracts built with Foundry. Contracts in `src/`, tests in `test/`, deployment scripts in `script/`, dependencies in `lib/` (git submodules via `forge install`). Config in `foundry.toml`.
## Commands
| Task | Command |
|------|---------|
| Build | `forge build` |
| Test | `forge test` (verbose traces on failure: `forge test -vvv`) |
| One test | `forge test --match-test testTransfer_RevertsWhenPaused -vvvv` |
| One contract's tests | `forge test --match-contract {{MAIN_CONTRACT}}Test` |
| Format | `forge fmt` (check only: `forge fmt --check`) |
| Gas report | `forge test --gas-report` |
| Gas snapshot | `forge snapshot` (compare: `forge snapshot --diff`) |
| Coverage | `forge coverage` |
| Local chain | `anvil` (in a separate terminal) |
| Add dependency | `forge install <org>/<repo>@<tag>` then add a `remappings.txt` entry |
Definition of done: `forge fmt --check`, `forge build` (zero warnings), and `forge test` all exit 0. Paste the test summary line. If you changed any function body, run `forge snapshot --diff` and report gas deltas over 1%.
## Never deploy
- Do not run `forge script ... --broadcast`, `forge create`, `cast send`, or anything that signs and sends a transaction. Simulate only: `forge script script/Deploy.s.sol` without `--broadcast` is allowed.
- Do not read, print, or pass private keys, mnemonics, or RPC URLs with embedded keys. If a task seems to need one, stop and describe what the human should run.
- Do not call `cast wallet import` or touch `~/.foundry/keystores`.
- `anvil` default accounts are the only keys you may use, and only against a local `anvil` instance.
## Code conventions
- One contract per file; file name equals contract name. Interfaces in `src/interfaces/I<Name>.sol`.
- Order inside a contract: type declarations, constants, immutables, storage, events, errors, modifiers, constructor, receive/fallback, external, public, internal, private. View/pure last within each visibility group.
- Custom errors, not `require` strings: `error Unauthorized(address caller);` then `if (msg.sender != owner) revert Unauthorized(msg.sender);`.
- Emit an event for every state change an off-chain reader could care about.
- NatSpec (`@notice`, `@param`, `@return`, `@dev`) on every external and public function. Run `forge doc` to check it parses.
- Use OpenZeppelin from `lib/openzeppelin-contracts` for ERC standards, access control, and reentrancy guards. Do not reimplement them.
- No floating pragma: `pragma solidity {{SOLC_VERSION}};` exactly.
## Security checklist (apply to every change in `src/`)
- Reentrancy: external calls and ETH transfers happen last (checks-effects-interactions). Add `nonReentrant` on any function that calls out and changes state.
- Access control: every state-changing function has an explicit modifier (`onlyOwner`, `onlyRole(...)`) or a comment stating why it is intentionally permissionless.
- Arithmetic: rely on 0.8 checked math; use `unchecked` only in loops where the bound is proven in a comment.
- Input validation: zero-address checks on every address parameter in constructors and setters.
- External calls: use `SafeERC20` for tokens; check return values of low-level `call`; never assume a token reverts on failure.
- Upgradeability: if the contract is behind a proxy, never reorder or remove storage variables; append only, and keep the `__gap`.
- Oracle and price inputs: never read spot price from a single AMM pool.
- Mention each checklist item you considered in the report, with "n/a" where it does not apply.
## Tests
- Test contract per source contract: `test/{{MAIN_CONTRACT}}.t.sol`, `contract {{MAIN_CONTRACT}}Test is Test`. Shared setup in `test/Base.t.sol`.
- Naming: `test_<Function>_<Condition>` for happy paths, `test_RevertWhen_<Condition>`, `testFuzz_<Function>`, `invariant_<Property>`.
- Reverts: `vm.expectRevert(Unauthorized.selector)` or `vm.expectRevert(abi.encodeWithSelector(Unauthorized.selector, caller))`. Never bare `vm.expectRevert()` without an argument.
- Fuzz tests take parameters; constrain with `bound(x, min, max)` rather than `vm.assume` where possible. Fuzz runs are set in `foundry.toml` under `[fuzz] runs`; do not lower them to make a test pass.
- Invariant tests: `test/invariant/<Name>.invariant.t.sol` with a handler contract in `test/invariant/handlers/`. Register with `targetContract(address(handler))`. Each invariant asserts one property (for example total supply equals sum of balances).
- Fork tests use `vm.createSelectFork(vm.envString("MAINNET_RPC_URL"))` and are tagged with `--match-path test/fork/*`; skip them when the env var is unset.
## Do not
- Do not edit anything under `lib/`; pin a different tag with `forge update` and commit the submodule change.
- Do not change `foundry.toml` optimizer settings, `evm_version`, or `via_ir` without saying so in the report.
- Do not delete or weaken an existing test to make the suite pass.
- Do not use `tx.origin` for authorization, `block.timestamp` as a randomness source, or `selfdestruct`.