foundry-template AGENTS.md

AGENTS.md

Foundry-based template for developing Solidity smart contracts. Dependencies are managed as Node.js packages (via Bun) and remapped through remappings.txt instead of git submodules.

Stack

• Solidity 0.8.29 (pragma >=0.8.29), EVM target shanghai, optimizer on (10,000 runs)
• Foundry (forge) — compile, test, fuzz, format, deploy
• Forge Std v1.9.7 — test and scripting framework
• OpenZeppelin Contracts 5.3.0 — pre-installed contract library
• Bun — dependency manager (deps installed as Node.js packages, remapped in remappings.txt)
• Prettier 3.5 — formatter for JSON/Markdown/YAML
• Solhint 5.1 — Solidity linter

Commands

Forge

• forge build — compile contracts
• forge build --sizes — compile and print contract sizes (CI build step)
• forge test — run the test suite
• forge test -vvv — run tests with console2 logs shown
• forge test --gas-report — run tests with a gas report
• forge coverage — generate a coverage report
• forge fmt — format Solidity
• forge fmt --check — check Solidity formatting without writing
• forge clean — delete out/ and cache/
• forge config — print the resolved Foundry config
• forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545 — deploy Foo to a local node (requires MNEMONIC or ETH_FROM)
• forge script script/DeployBrowser.s.sol --broadcast --fork-url http://localhost:8545 --browser — deploy Foo to a local node (requires you to connect your wallet at localhost:9545)

Bun scripts (package.json)

• bun install — install Node.js dependencies (add a matching entry to remappings.txt afterward)
• bun run build — forge build
• bun run test — forge test
• bun run clean — rm -rf cache out
• bun run forge-check — forge fmt --check
• bun run forge-write — forge fmt
• bun run solhint-check — Solhint over {script,src,tests}/**/*.sol
• bun run prettier:check — Prettier check over **/*.{json,md,yml}
• bun run prettier:write — Prettier write over **/*.{json,md,yml}
• bun run full-check — forge-check + solhint-check + prettier:check (the CI lint gate)
• bun run full-write — forge-write + prettier:write (auto-fix formatting)