Solidity Security Best Practices

When to Apply

• Reviewing smart contract code for common vulnerabilities.
• Implementing critical patterns like Checks-Effects-Interactions.
• Auditing access control and upgradeability logic.
• Preparing for a security audit or bug bounty.
• Debugging unexpected behavior in external contract interactions.

Security Thinking Framework

When reviewing or writing Solidity code, apply these foundational principles as a mental checklist. Each principle addresses a category of vulnerability and guides your reasoning.

Core Principles

Security Decision Process

When you encounter a function, ask these questions in order:

1. Who can call this? — Check access control (onlyOwner, hasRole, msg.sender validation)
2. What inputs does it accept? — Validate all parameters (zero address, bounds, empty values)
3. What state does it change? — Ensure state updates happen before external interactions
4. Does it interact externally? — Apply CEI, use SafeERC20, check return values
5. Can it be called recursively? — Add ReentrancyGuard if external calls are present
6. Is the state change visible? — Emit events for off-chain tracking
7. Can it be paused? — Implement circuit breakers for critical operations

SCSVS-Based Audit Workflow

Organize your review by OWASP SCSVS categories. For each category, focus on the specific threat model.

Architecture & Design (SCSVS-ARCH)

• Proxy patterns: correct admin separation, storage gaps, initializer protection
• Contract boundaries: minimal surface area, no circular dependencies
• Delegatecall: only to trusted, immutable targets

Code Quality (SCSVS-CODE)

• Explicit visibility on all functions
• Fixed pragma (no floating versions)
• No deprecated functions (throw, suicide, constant for functions)
• No unused code, no variable shadowing

Authorization (SCSVS-AUTH)

• Access control on ALL state-changing functions
• No tx.origin for authentication — use msg.sender
• Protected initializers (callable once only)
• Privileged roles require multi-sig or timelock

Communication (SCSVS-COMM)

• Return values of external calls checked and handled
• No delegatecall to untrusted contracts
• Pull-over-push pattern for payments
• CEI pattern or ReentrancyGuard on all functions with external calls

Cryptography (SCSVS-CRYPTO)

• No on-chain randomness (block.timestamp, blockhash)
• EIP-712 for structured data signatures
• abi.encode instead of abi.encodePacked for dynamic types in hashing
• Signature malleability protection
• ecrecover result validated (not address(0))

DeFi-Specific (SCSVS-DEFI)

• Slippage protection on swaps and liquidity operations
• Flash loan resistance in price-sensitive logic
• Oracle manipulation protection (TWAP, multiple sources)
• No reliance on address(this).balance for internal accounting
• Fee-on-transfer and rebasing token compatibility

Blockchain-Specific (SCSVS-BLOCK)

• No block property dependence for critical logic (timestamp, difficulty)
• Front-running protection (commit-reveal, slippage limits)
• Gas griefing protection for relayer patterns

Bridge & Cross-Chain (SCSVS-BRIDGE)

• Message validation across chains
• Replay protection for cross-chain messages
• Trust model verification for bridge relayers

Governance (SCSVS-GOV)

• Timelock on governance actions
• Proposal execution safety
• Flash loan governance attack protection

Component Security (SCSVS-COMP)

• Dependency audit (OpenZeppelin version pinning)
• Known vulnerability checks against dependencies
• Interface compliance verification

Security Patterns by Priority

Critical

• CEI Pattern: Always update state before external calls to prevent reentrancy. The most common vulnerability source is performing state changes after an external call.
• Reentrancy Guard: Use mutex locks (OpenZeppelin ReentrancyGuard) for functions with external interactions. Protects against both same-function and cross-function reentrancy.
• Access Control: Restrict sensitive functions with role-based modifiers (Ownable, AccessControl). Every state-changing function must have explicit authorization.
• Safe External Calls: Use SafeERC20 for token transfers to handle non-standard return values. Always check .call() return values with require.

High

• Input Validation: Validate all parameters — zero address, bounds, empty arrays, zero amounts. Use custom errors (revert InvalidAmount()) for gas-efficient validation.
• Upgrade Safety: Protect initializers with initializer modifier, verify storage compatibility across upgrades, restrict upgrade admin access.
• Circuit Breakers: Implement Pausable functionality (OpenZeppelin) for emergency response. Critical for DeFi protocols handling user funds.

Medium

• Signature Security: Use nonces + EIP-712 domain separators to prevent replay attacks. Validate ecrecover does not return address(0).
• Randomness: Never use on-chain data (block.timestamp, blockhash) for randomness. Use Chainlink VRF or commit-reveal schemes.
• Event Emission: Emit events for all significant state changes. Use indexed parameters for efficient off-chain filtering.

Enhanced with MCP

If you have the solidity-agent-toolkit MCP server configured, use these tools to augment your manual review:

Suspect a known vulnerability?

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

Want automated scanning?

• match_vulnerability_patterns — Regex-based detection of 32+ common vulnerability patterns
• run_slither — Comprehensive static analysis with SCWE-mapped findings
• run_aderyn — Fast Rust-based vulnerability scanner

Need reference data?

• scwe://{id} — Full vulnerability details including description, remediation, and code examples
• scwe://category/{category} — Browse all vulnerabilities by SCSVS category
• sctop10://list — OWASP Smart Contract Top 10 overview

Full audit workflow?

• Use the security_audit prompt for a structured, guided audit process
• Use the vulnerability_fix prompt for step-by-step remediation assistance

References

• OWASP Smart Contract Top 10 (2026)