Solidity Code Review Guide

When to Apply

Apply this methodology when performing a security audit, peer review, or general assessment of Solidity smart contracts. It is designed to identify vulnerabilities, ensure adherence to best practices, and verify the robustness of the contract logic.

Pre-Review Checklist

Before beginning the manual review, ensure the following items are addressed:

• Compilation: Verify the code compiles without errors using the project's build system (Foundry, Hardhat, etc.).
• Test Suite: Run the existing test suite. Ensure tests pass and review coverage reports to identify untested logic.
• Dependencies: Identify all external libraries and inherited contracts. Verify versions are pinned and trusted.
• Documentation: Review technical specifications and NatSpec comments to understand intended behavior.
• Known Issues: Check for previous audit reports or documented "known risks" provided by the developers.
• Scope: Define the exact list of contracts and functions that are within the audit scope.

Review Methodology

1. Step 1: Scope & Architecture: Map out the contract inheritance, external dependencies, and system architecture.
2. Step 2: Manual Line-by-Line Review: Perform a deep dive into critical functions, focusing on state changes and value transfers.
3. Step 3: Automated Analysis: Run static analysis tools (Slither, Aderyn, Solhint) to catch common patterns and style violations.
4. Step 4: Vulnerability Pattern Matching: Specifically check for known SCWE patterns (Reentrancy, Access Control, etc.).
5. Step 5: Integration & Edge Cases: Analyze how contracts interact and test boundary conditions (e.g., zero values, max integers).

Severity Classification

Severity	Criteria	Examples
Critical	Direct loss of funds, permanent contract lock, or total compromise.	Reentrancy, Unprotected withdraw, Logic error in transfer.
High	Significant impact on system functionality or exploitable under realistic conditions.	Access control bypass, Unchecked external calls, Oracle manipulation.
Medium	Limited impact or requires specific, difficult-to-achieve conditions.	Timestamp dependence, Front-running, Denial of Service (DoS).
Low	Best practice violations, informational findings, or minor optimizations.	Missing events, Floating pragma, Unused variables.

Key Inspection Areas

Access Control & Authorization

• Verify onlyOwner or role-based access on all sensitive state-changing functions.
• Ensure initializers are protected and can only be called once.
• Check for tx.origin usage instead of msg.sender.

External Call Safety

• Follow the Check-Effects-Interactions (CEI) pattern strictly.
• Use call() instead of transfer() or send() for ETH transfers.
• Handle return values of all external calls.

State Management & Reentrancy

• Use ReentrancyGuard for functions making external calls.
• Check for cross-contract reentrancy where state is shared.
• Ensure state variables are updated before external interactions.

Arithmetic & Type Safety

• For Solidity <0.8.0, ensure SafeMath is used.
• Check for precision loss in divisions (multiply before dividing).
• Verify safe casting between types (e.g., uint256 to uint8).

Token Handling (ERC20/721)

• Use SafeERC20 for transfer and transferFrom.
• Account for "fee-on-transfer" tokens if applicable.
• Verify approve race condition handling.

Upgrade Mechanisms

• Check for storage gaps in logic contracts to prevent collisions.
• Ensure logic contracts do not use selfdestruct or delegatecall.
• Verify the proxy admin has restricted access.

Event Emissions

• Emit events for all significant state changes (ownership, parameters, transfers).
• Use indexed parameters for efficient off-chain filtering.

NatSpec Documentation

• Ensure @notice, @param, and @return are accurate.
• Use @dev to document complex logic or security assumptions.

Style Guide Compliance

• Code follows the official Solidity style guide conventions.
• Naming conventions: PascalCase (contracts), camelCase (functions), UPPER_CASE (constants).
• Function ordering: by visibility (external → public → internal → private), then by mutability (state-changing → view → pure) within each group.
• Function modifier order: visibility, mutability, virtual, override, custom.
• See the Solidity Style Guide Reference for the full checklist.

Reporting Format

Findings should be documented using the following template:

[SEVERITY] Finding Title

ID: SCWE-XXX (replace with actual SCWE ID, e.g., SCWE-046 — see search_vulnerabilities) Location: ContractName.sol:L42 Description: Detailed explanation of the vulnerability and how it can be triggered. Impact: What happens if this is exploited (e.g., "User funds can be stolen"). Remediation: Specific code changes or architectural adjustments to fix the issue.

Enhanced with MCP

When using the solidity-agent-toolkit, leverage these tools in a structured review workflow:

Step 1 — Static Analysis:

• run_slither — Comprehensive static analysis with SCWE-mapped findings
• run_aderyn — Fast Rust-based vulnerability scanner
• run_solhint — Linting and style enforcement

Step 2 — Pattern Detection:

• match_vulnerability_patterns — Regex-based detection of 32+ common vulnerability patterns

Step 3 — Vulnerability Lookup:

• search_vulnerabilities — Search the OWASP SCWE database by keyword
• get_remediation — Get specific fix guidance with code examples for any SCWE ID
• check_vulnerability — Check if code matches a known SCWE pattern

Step 4 — Style & Quality:

• check_style — Automated Solidity style guide compliance (12 rules)
• format_code — Auto-format Solidity code
• validate_natspec — Verify NatSpec documentation completeness

Step 5 — Full Audit:

• Use the security_audit prompt for a structured, guided audit process
• Use the code_review prompt for comprehensive code quality assessment

References

• Smart Contract Audit Checklist
• Solidity Style Guide Reference