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.19; — 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

Initialization Strategy

When a contract involves state initialization (external addresses, business parameters, role assignments), DO NOT default to any single approach. Follow this workflow:

Workflow

1. Evaluate: Is the contract upgradeable? Are all dependencies known at deploy time? Are there cross-contract deployment order constraints?
2. Present options: Show the developer the three initialization schemes below with their trade-offs
3. Let the developer choose: Do not assume a scheme — different projects and contracts have different needs
4. Implement: Apply the chosen scheme with the safety rules listed below

Scheme Comparison

When to Suggest Each Scheme

Safety Rules (Apply Regardless of Scheme)

• One-shot lock: Any setter that should only be called once must enforce require(currentValue == address(0)) or a bool initialized flag — prevent re-initialization
• No unprotected initializers: initialize() functions must have access control (onlyOwner, initializer modifier, or deployer-only check)
• Immutable preference: Values known at deploy time should use immutable over regular storage — saves gas on every read
• No complex external calls in constructor: Constructor should not call external contracts for state-changing operations (swap, addLiquidity) — the contract is not fully constructed yet
• Deploy script responsibility: When using Scheme C, the deploy script must call initialize() in the same transaction batch or immediately after — document the required call sequence

Event Design Patterns

Reason-Annotated Events（原因标注事件）

When an event represents a conditional/branching outcome (the same action can happen for different reasons), add a string reason parameter to make on-chain data self-documenting:

// GOOD — on-chain data is self-explanatory
event WithdrawalFailed(address indexed user, uint256 amount, string reason);
emit WithdrawalFailed(user, amount, "insufficient balance");
emit WithdrawalFailed(user, amount, "cooldown not expired");

event ProposalRejected(uint256 indexed proposalId, string reason);
emit ProposalRejected(id, "quorum not reached");
emit ProposalRejected(id, "voting period ended");

// BAD — must read contract source to understand why
event WithdrawalFailed(address indexed user, uint256 amount);

适用场景：

• 资金去向分叉：同一笔资金因不同条件流向不同地址
• 操作被拒绝/降级：用户请求未完全满足，附带原因
• 状态转换：同一个状态变更可能由不同触发条件引起
• 管理员操作：记录 why（如 "security incident", "parameter tuning"）

不适用场景：

• 事件只有一种触发路径（无分支）→ 不需要 reason
• 高频事件（每笔 swap/transfer）→ string 消耗额外 gas，用 uint8 reasonCode 代替

Reason 实现方式选择

// 方式 A：string literal（推荐，可读性最好）
emit WithdrawalFailed(user, amount, "cooldown not expired");

// 方式 B：uint8 code（高频场景省 gas）
event SwapRejected(address indexed user, uint256 amount, uint8 reasonCode);
// 0 = slippage, 1 = insufficient liquidity, 2 = paused
emit SwapRejected(user, amount, 0);

General Event Design Rules

• 每个改变状态的 external / public 函数必须 emit 至少一个事件
• 事件参数应包含足够信息让前端/indexer 无需额外 RPC 调用就能重建完整上下文
• NatSpec @param 必须为 reason 参数列出所有可能的值

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 Foundry)

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

Oracle and Off-Chain Services

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 oracle feed → AggregatorV3Interface
├── No oracle 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

MCP-Assisted Contract Generation (if available)

When OpenZeppelinContracts MCP is configured, prefer using it to generate base contracts instead of writing from scratch:

Workflow: MCP generates base → apply this skill's naming/structure rules → customize business logic → apply /solidity-security rules

Why MCP over manual: MCP output is validated against the same rule-set as OZ Contracts Wizard — imports, modifiers, security checks are guaranteed correct. Manual coding risks missing imports or using wrong OZ versions.

When NOT to use MCP: Heavily custom contracts with non-standard patterns, contracts that don't fit any OZ template, or when you need fine-grained control from line 1.

Graceful degradation: If MCP is not configured, fall back to the Library Selection Standards above and write contracts manually following all rules in this skill.

Foundry Quick Reference