Solidity Coding Standards

Solidity Coding Standards

Language Rule

• Always respond in the same language the user is using. If the user asks in Chinese, respond in Chinese. If in English, respond in English.

Coding Principles

• Pragma: Use pragma solidity ^0.8.20; — keep consistent across all files in the project
• Dependencies: OpenZeppelin Contracts 4.9.x, manage imports via remappings.txt
• Error Handling: Prefer custom errors over require strings — saves gas and is more expressive
  • Define: error InsufficientBalance(uint256 available, uint256 required);
  • Use: if (balance < amount) revert InsufficientBalance(balance, amount);
• Documentation: All public / external functions must have NatSpec (@notice, @param, @return)
• Event Indexing: Only add indexed to address type parameters — add comment if indexing other types
• Special Keywords: immutable / constant / unchecked / assembly must have inline comment explaining why

Naming Conventions

• Forbidden: Pinyin names, single-letter variables (except i/​j/​k in loops), excessive abbreviations

Code Organization Rules

Project Directory Structure

src/              — Contract source code
  interfaces/     — Interface definitions (I*.sol)
  common/         — Shared constants, types, errors (Const.sol, Types.sol)
test/             — Test files (*.t.sol)
script/           — Deployment & interaction scripts (*.s.sol)
config/           — Network config, parameters (*.json)
deployments/      — Deployment records (latest.env)
docs/             — Documentation, changelogs
lib/              — Dependencies (managed by forge install)

Configuration Management

• config/​*.json — network RPC URLs, contract addresses, business parameters
• deployments/​latest.env — latest deployed contract addresses, must update after each deployment
• foundry.toml — compiler version, optimizer settings, remappings
• Important config changes must be documented in the PR description

OpenZeppelin Library Selection Standards

When writing Solidity contracts, prioritize using battle-tested OpenZeppelin libraries over custom implementations. Select the appropriate library based on the scenario:

Access Control

Rule: Single owner → Ownable2Step; 2+ roles → AccessControl; governance/​DAO → TimelockController

Security Protection

Rule: Any contract that transfers tokens or ETH MUST use ReentrancyGuard + SafeERC20

Token Standards

Utility Libraries

Contract Upgrade

Rule: New projects prefer UUPSUpgradeable; always use Initializable for upgradeable contracts

Chainlink Integration

Library Selection Decision Flow

Does contract handle user funds/​tokens?
├── YES → Add ReentrancyGuard + SafeERC20
│         Does it need emergency stop?
│         ├── YES → Add Pausable
│         └── NO  → Skip
└── NO  → Skip

How many admin roles needed?
├── 1 role  → Ownable2Step
├── 2+ roles → AccessControl
└── DAO/​governance → TimelockController

Does contract need price data?
├── Token has Chainlink feed → AggregatorV3Interface
├── No Chainlink feed → Custom TWAP with min-liquidity check
└── No price needed → Skip

Will contract need upgrades?
├── YES → UUPSUpgradeable + Initializable
└── NO  → Standard deployment (immutable)

Anti-Patterns (Do NOT)

• Do NOT write custom transfer wrappers — use SafeERC20
• Do NOT write custom access control modifiers — use Ownable / AccessControl
• Do NOT write custom pause logic — use Pausable
• Do NOT use SafeMath on Solidity >= 0.8.0 — overflow checks are built-in
• Do NOT use require(token.transfer(...)) — use token.safeTransfer(...) via SafeERC20
• Do NOT use tx.origin for auth — use msg.sender with Ownable / AccessControl

Foundry Quick Reference

# Create new project
forge init <project-name>

# Install dependency
forge install OpenZeppelin/​[email protected]

# Build contracts
forge build

# Format code
forge fmt

# Update remappings
forge remappings > remappings.txt