solidity-patterns

# Solidity Design Patterns ## Checks-Effects-Interactions (CEI) The most critical pattern in Solidity. All functions that interact with external contracts must follow this order: 1. **Checks** — validate inputs and preconditions 2. **Effects** — update state 3. **Interactions** — call external contracts ```solidity function withdraw(uint256 amount) external { // CHECKS if (amount == 0) revert ZeroAmount(); if (balances[msg.sender] < amount) revert InsufficientBalance(); // EFFECTS balances[msg.sender] -= amount; // INTERACTIONS (bool success,) = msg.sender.call{value: amount}(""); if (!success) revert TransferFailed(); emit Withdrawn(msg.sender, amount); } ``` Violating CEI is the root cause of reentrancy. Even with ReentrancyGuard, always write CEI-compliant code as defense in depth. ## Pull-Over-Push Never iterate over recipients to push funds. Let users withdraw (pull) their own funds. ```solidity // BAD: Push pattern — one revert blocks everyone function distributeRewards(address[] calldata recipients, uint256[] calldata amounts) external { for (uint256 i; i < recipients.length; ++i) { payable(recipients[i]).transfer(amounts[i]); // reverts if any fails } } // GOOD: Pull pattern — each user claims independently mapping(address => uint256) public pendingRewards; function claimReward() external { uint256 amount = pendingRewards[msg.sender]; if (amount == 0) revert NothingToClaim(); pendingRewards[msg.sender] = 0; (bool success,) = msg.sender.call{value: amount}(""); if (!success) revert TransferFailed(); emit RewardClaimed(msg.sender, amount); } ``` ## Guard Check Pattern Centralize validation in modifiers or internal functions for reuse and consistency. ```solidity error Unauthorized(); error InvalidAmount(); error Expired(uint256 deadline); modifier onlyWhitelisted() { if (!whitelist[msg.sender]) revert Unauthorized(); _; } modifier validAmount(uint256 amount) { if (amount == 0 || amount > MAX_AMOUNT) revert InvalidAmount(); _; } modifier beforeDeadline(uint256 deadline) { if (block.timestamp > deadline) revert Expired(deadline); _; } function deposit(uint256 amount, uint256 deadline) external onlyWhitelisted validAmount(amount) beforeDeadline(deadline) { // core logic only — all checks in modifiers } ``` ## State Machine Pattern Enforce valid state transitions for multi-phase protocols (auctions, vesting, governance). ```solidity enum AuctionState { Created, Bidding, Ended, Settled } AuctionState public state; error InvalidState(AuctionState expected, AuctionState actual); modifier inState(AuctionState expected) { if (state != expected) revert InvalidState(expected, state); _; } function startBidding() external onlyOwner inState(AuctionState.Created) { state = AuctionState.Bidding; emit BiddingStarted(block.timestamp); } function endBidding() external onlyOwner inState(AuctionState.Bidding) { state = AuctionState.Ended; emit BiddingEnded(block.timestamp); } function settle() external inState(AuctionState.Ended) { state = AuctionState.Settled; // settlement logic } ``` ## Access Restriction Pattern Layer access control for different privilege levels. ```solidity import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol"; contract Treasury is AccessControl { bytes32 public constant MANAGER_ROLE = keccak256("MANAGER_ROLE"); bytes32 public constant EXECUTOR_ROLE = keccak256("EXECUTOR_ROLE"); uint256 public constant LARGE_THRESHOLD = 100 ether; function executeSmall(address to, uint256 amount) external onlyRole(EXECUTOR_ROLE) { if (amount >= LARGE_THRESHOLD) revert ExceedsThreshold(); _transfer(to, amount); } function executeLarge(address to, uint256 amount) external onlyRole(MANAGER_ROLE) { _transfer(to, amount); } } ``` ## Commit-Reveal Pattern Prevent front-running by splitting actions into commit and reveal phases. ```solidity struct Commitment { bytes32 hash; uint64 timestamp; bool revealed; } mapping(address => Commitment) public commitments; uint256 public constant REVEAL_WINDOW = 1 hours; uint256 public constant MIN_COMMIT_AGE = 1 minutes; function commit(bytes32 hash) external { commitments[msg.sender] = Commitment({ hash: hash, timestamp: uint64(block.timestamp), revealed: false }); emit Committed(msg.sender, hash); } function reveal(uint256 value, bytes32 salt) external { Commitment storage c = commitments[msg.sender]; if (c.hash == bytes32(0)) revert NoCommitment(); if (c.revealed) revert AlreadyRevealed(); if (block.timestamp < c.timestamp + MIN_COMMIT_AGE) revert TooEarly(); if (block.timestamp > c.timestamp + REVEAL_WINDOW) revert RevealExpired(); bytes32 expected = keccak256(abi.encodePacked(msg.sender, value, salt)); if (c.hash != expected) revert InvalidReveal(); c.revealed = true; _processReveal(msg.sender, value); } ``` ## Pattern Selection Checklist | Situation | Pattern | |-----------|---------| | External calls after state changes | Checks-Effects-Interactions | | Distributing funds to many users | Pull-over-Push | | Repeated precondition checks | Guard Check / modifiers | | Multi-phase protocol flow | State Machine | | Tiered permissions | Access Restriction | | Sensitive action prone to front-running | Commit-Reveal | ## Anti-Patterns to Avoid - Nested external calls within loops - `tx.origin` for authorization (phishing vector) - `transfer()` / `send()` for ETH transfers (2300 gas limit breaks with EIP-1884) - Implicit state transitions without explicit enum tracking - Boolean flags instead of proper state machines