Building Secure Contracts Skill

Overview

This skill applies systematic security analysis to smart contracts and secure API contracts. The core principle: every state mutation must be proven safe through invariant verification before an external call executes. It covers both EVM (Solidity) and Solana (Rust) ecosystems with platform-specific vulnerability patterns.

Vulnerability taxonomy: OpenSCV (94 classified security issues) Critical patterns: CEI, reentrancy guards, access modifiers, SafeMath equivalents Risk landscape: $1.8B+ in DeFi exploits Q3 2025 (access control: $953M, reentrancy: $420M)

When to Use

• Before deploying any smart contract to mainnet
• When auditing existing contracts for security vulnerabilities
• When reviewing API contracts for invariant violations
• When adding new entry points or external calls to existing contracts
• When upgrading proxy contracts (storage slot collision risk)
• When integrating oracles, flash loans, or third-party DeFi protocols

Iron Laws

1. NEVER make external calls before updating state — Checks-Effects-Interactions (CEI) is non-negotiable; any external call before state update is a reentrancy vector regardless of perceived safety.
2. NEVER assume access control is correct without reading every modifier — access control failures account for ~53% of 2024 DeFi losses; verify every onlyOwner, onlyRole, and custom guard.
3. NEVER trust integer arithmetic without explicit bounds checking — Solidity 0.8+ has native overflow protection but custom assembly, unchecked blocks, and Rust/Solana code require explicit verification.
4. ALWAYS enumerate all contract invariants before analysis — invariants are the ground truth for correctness; a violation is always a bug; document them in NatSpec before reviewing the implementation.
5. ALWAYS test reentrancy across full call chains, not just single functions — cross-function reentrancy (withdraw + transfer sharing state) is as dangerous as direct reentrancy.

Phase 1: Contract Reconnaissance

Goal: Map the attack surface before deep analysis.

Steps

1. Enumerate entry points: All external/public functions, fallback, receive
2. Identify state-mutating functions: Functions that modify storage
3. Map access control boundaries: Roles, modifiers, ownership checks
4. Catalog external calls: call(), transfer(), ERC20 hooks, interface calls
5. Identify trust boundaries: User input, oracle feeds, cross-contract calls

Output Format

markdown
1## Contract Reconnaissance
2
3### Entry Points
4
5- [ ] `withdraw(uint256 amount)` — external, state-mutating, calls msg.sender
6- [ ] `deposit()` — payable, updates balances mapping
7
8### Access Control Map
9
10- [ ] `onlyOwner`: [list of functions]
11- [ ] `onlyRole(ADMIN_ROLE)`: [list of functions]
12- [ ] No modifier (verify intent): [list of functions]
13
14### External Calls
15
16- [ ] `msg.sender.call{value: amount}("")` at withdraw():L45
17- [ ] `token.transferFrom(...)` at deposit():L23
18
19### Trust Boundaries
20
21- [ ] User-supplied amount at withdraw():L40
22- [ ] Oracle price feed at getPrice():L67 — manipulation risk

Phase 2: Reentrancy Analysis

Goal: Identify all reentrancy vectors (direct, cross-function, read-only).

Checks-Effects-Interactions Verification

For each function with external calls:

markdown
1### Function: withdraw(uint256 amount)
2
3#### CEI Order Analysis
4
5- L40: CHECK — require(balances[msg.sender] >= amount) ✓
6- L45: EXTERNAL CALL — msg.sender.call{value: amount}("") ← VIOLATION
7- L48: EFFECT — balances[msg.sender] -= amount ← STATE AFTER CALL
8
9**FINDING**: Classic reentrancy — balance updated after external call.
10**Fix**: Move L48 before L45 (CEI pattern)
11**Severity**: Critical
12
13#### Fixed Pattern
14
15```solidity
16require(balances[msg.sender] >= amount);
17balances[msg.sender] -= amount;  // Effect BEFORE external call
18(bool success, ) = msg.sender.call{value: amount}("");
19require(success);
20```

Cross-Function Reentrancy Check

Identify shared state between functions that both make external calls:

markdown
1### Shared State: balances mapping
2
3- withdraw() reads + writes balances + makes external call
4- emergencyWithdraw() reads + writes balances + makes external call
5  **RISK**: Reentrancy from withdraw() into emergencyWithdraw() bypasses checks

Phase 3: Access Control Audit

Goal: Verify every state-mutating function has appropriate guards.

Access Control Checklist

For each function:

markdown
1### Function Audit: updateTreasury(address newTreasury)
2
3- [ ] Has access modifier? → NO ← FINDING: Missing onlyOwner
4- [ ] Modifier verified in contract? → N/A (not present)
5- [ ] Owner transferable safely? → N/A
6- [ ] Time lock for critical changes? → NO
7
8**Severity**: Critical — anyone can redirect protocol treasury
9**Fix**: Add `onlyOwner` modifier and time-lock for parameter changes

Role Confusion Patterns

markdown
1### Role Check: PAUSER_ROLE vs ADMIN_ROLE
2
3- pause() requires: PAUSER_ROLE
4- unpause() requires: PAUSER_ROLE (RISK: pauser can also unpause)
5- grantRole() requires: ADMIN_ROLE
6
7**Issue**: Pauser can unilaterally pause and unpause — should require separate roles
8**Severity**: Medium

Phase 4: Integer Arithmetic Analysis

Goal: Identify overflow, underflow, precision loss, and rounding direction bugs.

Arithmetic Boundary Analysis

markdown
1### Function: calculateReward(uint256 principal, uint256 rate)
2
3- L88: `uint256 reward = principal * rate / 1e18`
4  - Multiplication before division: OK (avoids precision loss)
5  - Overflow check: principal \* rate could overflow if both > sqrt(uint256.max)
6  - Rounding: truncates toward zero — check if favors protocol or user
7  - `unchecked` block? → NO → Solidity 0.8+ protects this
8
9### Unchecked Block Analysis
10
11- L102-108: `unchecked { ... }`
12  - Why unchecked? Check comment and verify mathematician's claim
13  - Is the claimed impossibility of overflow actually proven?
14  - [UNVERIFIED] claim: "amount < balance guarantees no underflow"

Phase 5: Invariant Verification

Goal: Identify and verify all contract-level invariants.

markdown
1### Contract Invariants: LiquidityPool
2
31. **Solvency**: sum(balances) == address(this).balance — [VERIFIED L90]
42. **Total supply**: totalSupply == sum(all user shares) — [UNVERIFIED]
53. **Fee bound**: fee <= MAX_FEE (1000 bps) — [VERIFIED by require at L45]
64. **Non-zero denominator**: totalSupply > 0 before share calculation — [VIOLATED at L67, division-by-zero risk on first deposit]
7
8### Invariant Violation Findings
9
10**FINDING**: Invariant 4 violated — first depositor can cause division by zero
11
12- Location: L67 `shares = amount * totalSupply / totalAssets`
13- When: totalSupply == 0 on first deposit
14- Impact: DoS attack on first deposit; protocol initialization blocked
15- Fix: Handle zero totalSupply case separately with initial share ratio

Output: Security Report

markdown
1# Security Report: [Contract Name]
2
3## Summary
4
5- Functions analyzed: N
6- Findings: N (Critical: X, High: Y, Medium: Z, Low: W)
7- Invariants verified: N of M
8- CEI violations: N
9
10## Critical Findings
11
12### [F-01] Reentrancy in withdraw()
13
14- Location: `src/Pool.sol:L45`
15- Pattern: External call before state update (CEI violation)
16- Impact: Complete fund drainage
17- Fix: Apply CEI pattern — update state before external call
18- 5 Whys: [root cause chain]
19
20## Invariant Status
21
22| Invariant                  | Status     | Evidence            |
23| -------------------------- | ---------- | ------------------- |
24| sum(balances) == balance   | VERIFIED   | L90 invariant check |
25| totalSupply == sum(shares) | UNVERIFIED | No test coverage    |
26
27## Recommendations
28
291. [Critical] Fix reentrancy in withdraw() before deployment
302. [High] Add reentrancy guard as defense-in-depth
313. [Medium] Add formal invariant tests via Foundry invariant suite

Integration with Agent-Studio

Recommended Workflow

1. Invoke audit-context-building for initial code reconnaissance
2. Invoke building-secure-contracts for contract-specific analysis
3. Feed findings into security-architect for threat modeling
4. Use static-analysis (Semgrep/CodeQL) for automated confirmation
5. Use medusa-security for fuzzing-based invariant testing

Complementary Skills

Anti-Patterns

Memory Protocol

Before starting: Check .claude/context/memory/learnings.md for prior contract audits of the same protocol or token standard.

During analysis: Write incremental findings to context report as discovered. Do not wait until the end.

After completion: Record key findings and patterns to .claude/context/memory/learnings.md. Record architecture decisions (CEI enforcement patterns, invariant frameworks) to decisions.md.