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

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

	Scheme A: Constructor Only	Scheme B: Initializer Only	Scheme C: Hybrid
Approach	All init in constructor params	Deploy empty, call initialize() after	Constructor handles known params; initialize() handles post-deploy dependencies
Atomicity	Deploy fails = nothing exists, no dangerous half-init state	Risk of "deployed but not initialized" window	Partially atomic — constructor part is safe, initializer part has the window
Front-run risk	None — constructor cannot be front-run	initialize() can be front-run if unprotected	Only the initializer portion has risk
Gas	One tx for deploy + init	Deploy tx + N init txs	Deploy tx + 1 init tx
Flexibility	Low — all params must be known at deploy time	High — can set dependencies after other contracts deploy	Medium — split between deploy-time and post-deploy
Upgradeable	Not compatible with proxy patterns	Required for UUPS / Transparent Proxy	Partial — constructor sets proxy-safe params, initializer for the rest