## Best Practices Guidelines for writing maintainable, secure, and efficient Foundry projects. ### Before you ship * Run `forge test` with `-vvvv` at least once * Run `forge lint` and `forge fmt --check` * Verify deployments with the exact compiler settings * Store production keys in encrypted keystores or hardware wallets * Keep `.env` files out of version control ### Writing contracts #### Use named imports Import only what you need to reduce compilation time and make dependencies explicit: :::code-group ```solidity [Good] import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; ``` ```solidity [Avoid] import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; ``` ::: #### Format with forge fmt Use the built-in formatter for consistent code style: ```bash $ forge fmt ``` Check formatting without modifying files: ```bash $ forge fmt --check ``` Configure formatting in `foundry.toml`: ```toml [foundry.toml] [fmt] line_length = 120 tab_width = 4 bracket_spacing = true ``` #### Avoid "Stack too deep" errors The EVM limits access to the top 16 stack slots. When you hit this error, the fix is usually to restructure your code—group variables into structs, split large functions into smaller helpers, or use block scoping. See the [Stack Too Deep guide](/guides/stack-too-deep) for causes, solutions, and when to use `via-ir` as a last resort. #### Organize contract layout Follow a consistent ordering within contracts: 1. Type declarations (structs, enums) 2. State variables 3. Events 4. Errors 5. Modifiers 6. Constructor 7. External functions 8. Public functions 9. Internal functions 10. Private functions ### Writing tests #### Naming conventions Use descriptive names that explain behavior: | Pattern | Usage | Example | |---------|-------|---------| | `test_Description` | Standard tests | `test_TransferUpdatesBalances` | | `testFuzz_Description` | Fuzz tests | `testFuzz_TransferAnyAmount` | | `test_RevertWhen_Condition` | Revert tests | `test_RevertWhen_InsufficientBalance` | | `test_RevertIf_Condition` | Alternative revert naming | `test_RevertIf_NotOwner` | ```solidity function test_TransferUpdatesBalances() public { token.transfer(bob, 100); assertEq(token.balanceOf(bob), 100); } function test_RevertWhen_TransferExceedsBalance() public { vm.expectRevert(Token.InsufficientBalance.selector); token.transfer(bob, type(uint256).max); } ``` #### Test organization Structure test files to mirror your source files: :::file-tree * +src/ * Token.sol * Vault.sol * +governance/ * Governor.sol * +test/ * Token.t.sol * Vault.t.sol * +governance/ * Governor.t.sol ::: Group related tests in the same contract: ```solidity [test/Token.t.sol] contract TokenTransferTest is Test { function test_TransferUpdatesBalances() public { } function test_TransferEmitsEvent() public { } function test_RevertWhen_InsufficientBalance() public { } } contract TokenApprovalTest is Test { function test_ApproveUpdatesAllowance() public { } function test_TransferFromUsesAllowance() public { } } ``` #### Use test harnesses Create harness contracts to expose internal functions for testing: :::code-group ```solidity [test/harnesses/TokenHarness.sol] import {Token} from "../../src/Token.sol"; contract TokenHarness is Token { function exposed_mint(address to, uint256 amount) external { _mint(to, amount); } function exposed_burn(address from, uint256 amount) external { _burn(from, amount); } } ``` ```solidity [test/Token.t.sol] import {TokenHarness} from "./harnesses/TokenHarness.sol"; contract TokenInternalTest is Test { TokenHarness token; function setUp() public { token = new TokenHarness(); } function test_MintIncreasesSupply() public { token.exposed_mint(alice, 1000); assertEq(token.totalSupply(), 1000); } } ``` ::: #### Prefer bound() over assume() Use `bound(){:solidity}` to constrain fuzz inputs instead of `vm.assume(){:solidity}`: :::code-group ```solidity [Good] function testFuzz_Transfer(uint256 amount) public { amount = bound(amount, 1, token.balanceOf(alice)); token.transfer(bob, amount); } ``` ```solidity [Avoid] function testFuzz_Transfer(uint256 amount) public { vm.assume(amount > 0 && amount <= token.balanceOf(alice)); token.transfer(bob, amount); } ``` ::: `vm.assume(){:solidity}` discards invalid inputs, which can slow down fuzzing. `bound(){:solidity}` transforms inputs to valid ranges. ### Writing scripts #### Separate concerns Split complex deployments into focused scripts: :::file-tree * +script/ * DeployToken.s.sol * DeployVault.s.sol * ConfigureVault.s.sol * Deploy.s.sol Orchestrates all deployments ::: ```solidity [script/Deploy.s.sol] import {DeployToken} from "./DeployToken.s.sol"; import {DeployVault} from "./DeployVault.s.sol"; contract DeployScript is Script { function run() public { DeployToken tokenDeployer = new DeployToken(); address token = tokenDeployer.run(); DeployVault vaultDeployer = new DeployVault(); vaultDeployer.run(token); } } ``` #### Use environment variables for configuration Never hardcode addresses or keys in scripts: ```solidity [Good] function run() public { address admin = vm.envAddress("ADMIN_ADDRESS"); uint256 initialSupply = vm.envOr("INITIAL_SUPPLY", uint256(1_000_000 ether)); vm.startBroadcast(); new Token(admin, initialSupply); vm.stopBroadcast(); } ``` #### Log deployment information Output addresses and transaction details for verification: ```solidity function run() public { vm.startBroadcast(); Token token = new Token(); console.log("Token deployed at:", address(token)); console.log("Chain ID:", block.chainid); console.log("Deployer:", msg.sender); vm.stopBroadcast(); } ``` ### Security #### Run taint analysis Use `forge taint` to detect dangerous data flows from untrusted sources: ```bash [Check a specific contract] $ forge taint src/Vault.sol ``` ```bash [Check all contracts] $ forge taint ``` Taint analysis identifies when user-controlled data flows into sensitive operations without validation. #### Enable the linter Catch common issues with `forge lint`: ```bash $ forge lint ``` Configure rules in `foundry.toml`: ```toml [foundry.toml] [lint] severity = "warning" exclude = ["script/**"] ``` #### Test access control Verify that protected functions reject unauthorized callers: ```solidity function test_RevertWhen_CallerNotOwner() public { vm.prank(attacker); vm.expectRevert(Ownable.OwnableUnauthorizedAccount.selector); vault.withdrawAll(); } ``` #### Test edge cases Cover boundary conditions in your tests: ```solidity function test_TransferZeroAmount() public { token.transfer(bob, 0); assertEq(token.balanceOf(bob), 0); } function test_TransferMaxAmount() public { deal(address(token), alice, type(uint256).max); vm.prank(alice); token.transfer(bob, type(uint256).max); } ``` ### Key management #### Use encrypted keystores Store keys encrypted, not as plaintext environment variables: ```bash [Create a keystore] $ cast wallet import deployer --interactive ``` ```bash [Use the keystore] $ forge script script/Deploy.s.sol --account deployer --broadcast --rpc-url https://ethereum.reth.rs/rpc ``` #### Use hardware wallets for production For mainnet deployments, use a hardware wallet: ```bash $ forge script script/Deploy.s.sol --ledger --broadcast --rpc-url https://ethereum.reth.rs/rpc ``` #### Separate development and production keys Use different keys for different environments: | Environment | Key source | |-------------|------------| | Local development | Anvil default keys | | Testnets | Encrypted keystore | | Mainnet | Hardware wallet | Anvil provides pre-funded accounts for local testing: ```bash [Start Anvil] $ anvil ``` ```bash [Use Anvil's first account] $ forge script script/Deploy.s.sol --broadcast --rpc-url http://localhost:8545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 ``` :::warning Never use Anvil's default keys on public networks. They are publicly known. ::: #### Protect environment files Keep `.env` files out of version control: ```gitignore [.gitignore] .env .env.* ``` Use `.env.example` to document required variables: ```bash [.env.example] $ RPC_URL= $ ETHERSCAN_API_KEY= # Use `cast wallet import` instead of PRIVATE_KEY ```