CO
Smart Contract Architecture
Guidelines for smart contract architecture.
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
Smart Contract Architecture
- Make contracts upgradeable only when necessary — use the proxy pattern (EIP-1967) with explicit storage layout management to avoid storage collisions.
- Follow checks-effects-interactions pattern: validate inputs first, update state second, make external calls last to prevent reentrancy attacks.
- Minimize on-chain storage — store only essential state on-chain and use events/logs for historical data and off-chain indexing.
Smart Contract Architecture
- Make contracts upgradeable only when necessary — use the proxy pattern (EIP-1967/UUPS) with explicit storage layout management and storage gaps to avoid collisions.
- Follow checks-effects-interactions pattern in every external function: validate inputs, update contract state, then make external calls to prevent reentrancy attacks.
- Minimize on-chain storage — store only essential state on-chain. Use events/logs for historical data and off-chain indexing (The Graph, custom indexers).
- Use OpenZeppelin or audited library contracts for standard patterns (ERC-20, ERC-721, AccessControl, ReentrancyGuard) — never re-implement security-critical primitives.
- Implement access control with role-based permissions (AccessControl) rather than simple onlyOwner — separate admin, operator, and upgrader roles.
- Design for gas optimization: pack storage variables into 32-byte slots, use calldata instead of memory for read-only function parameters, batch operations where possible.
- Emit events for every state change — they are the primary interface for off-chain services and frontend applications to track contract activity.