solidity-best-practices

Solidity Best Practices

When to use this skill

Use when the user asks about:

• Writing or reviewing Solidity code
• Smart contract design patterns
• Gas optimization techniques in Solidity
• Security best practices for contract development
• Structuring a Solidity project

Development Guidelines

1. Project Structure

Recommended contract organization:

• contracts/ — main contract source files
• contracts/interfaces/ — interface definitions (IProtocol.sol)
• contracts/libraries/ — shared library code
• contracts/utils/ — utility contracts (access control, pausable, etc.)
• test/ — test files mirroring the contracts directory structure
• script/ — deployment and interaction scripts

2. Coding Standards

Follow these Solidity style conventions:

• Use Solidity 0.8.x or later (built-in overflow checks)
• Specify exact compiler version with pragma solidity 0.8.24; (not floating ^)
• Order contract elements: state variables, events, errors, modifiers, constructor, external, public, internal, private functions
• Use custom errors instead of require strings (saves gas): error InsufficientBalance(uint256 available, uint256 required);
• Use immutable for variables set once in the constructor
• Use constant for compile-time known values
• Prefix internal/private functions with underscore: _validateInput()
• Use NatSpec comments for all public/external functions

3. Gas Optimization Patterns

High-impact optimizations:

• Storage packing: Group variables smaller than 32 bytes together in a single storage slot (e.g., uint128 a; uint128 b; uses one slot vs two for uint256)
• Calldata over memory: Use calldata for external function array/struct parameters that are read-only
• Caching storage reads: Read a storage variable into a local variable if accessed multiple times in a function
• Short-circuit conditions: Place cheap checks before expensive ones in require chains
• Unchecked math: Use unchecked {} for arithmetic that provably cannot overflow (e.g., loop counters)
• Avoid zero-to-nonzero writes: Initializing a storage slot from 0 costs 20,000 gas vs 5,000 for nonzero-to-nonzero
• Use mappings over arrays when you don't need iteration — mappings have O(1) access
• Batch operations: Combine multiple operations into single transactions where possible