solidity-coding

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

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 代替