0x-shashi/skills/differential-review

Differential Review Skill

Compare two versions of a codebase to identify security implications of changes. Essential for protocol upgrades, bug fix verification, and dependency updates.

---

Why Differential Review?

A full audit of an already-audited codebase is wasteful if only 5% of the code changed. Differential review focuses effort on:

| Change Type | Risk Level | Examples | |-------------|------------|----------| | Logic changes | HIGH | Modified calculation, new branching, changed access control | | State variable changes | HIGH | New storage, modified types, reordered variables | | Dependency updates | MEDIUM-HIGH | OpenZeppelin upgrade, Solidity version change | | Configuration changes | MEDIUM | Changed thresholds, updated addresses, new roles | | Formatting only | NONE | Whitespace, comments, variable renames | | New code | HIGH | Entirely new functions/contracts | | Removed code | MEDIUM | Deleted security checks, removed functionality |

---

Change Classification Matrix

| Change | Security Relevant? | Needs Review? | |--------|-------------------|---------------| | Function body modified | YES | ALWAYS | | New function added | YES | FULL AUDIT | | Function removed | MAYBE | Check if security-critical | | Access control modified | YES | ALWAYS | | Storage variable added | YES (upgrade compat) | ALWAYS | | Storage variable removed | YES (dangerous) | ALWAYS | | Storage variable reordered | YES (proxy breakage) | ALWAYS | | Import changed | MAYBE | Check changelog | | Compiler version changed | MAYBE | Check breaking changes | | Comment changed | NO | Skip | | Whitespace changed | NO | Skip | | Event added/modified | LOW | Quick review | | Error message changed | NO | Skip | | Constant changed | MAYBE | Verify new value |

---

Differential Review Strategy

Step 1: Generate the Diff

# Between two git tags/commits
git diff v1.0..v2.0 -- '*.sol'
git diff v1.0..v2.0 --stat  # Summary of changed files

# Between two branches
git diff main..feature-branch -- 'contracts/'

# Exclude non-code changes
git diff v1..v2 -- '*.sol' ':!test/' ':!script/'

Step 2: Categorize Changes

Sort the diff output into categories:

1. Modified contracts → Primary review target
2. New contracts → Full audit required
3. Deleted contracts → Check for orphaned references
4. Modified tests → Understand what changed and why
5. Config changes → Deployment parameter review

Step 3: Impact Analysis

For each modified function:

• What did it do before?
• What does it do now?
• What invariants could break?
• Does the change affect other functions?
• Are existing tests still valid?

---

Common Upgrade Pitfalls

| Pitfall | Example | Impact | |---------|---------|--------| | Storage slot collision | Adding variable before existing ones in upgradeable proxy | Critical — corrupted state | | Initializer re-callable | initialize() without initializer guard after upgrade | Critical — protocol takeover | | selfdestruct in new impl | Attacker calls selfdestruct on implementation | Critical — proxy bricked | | Removed security check | Deleted onlyOwner modifier in upgrade | Critical — access control loss | | Changed function selector | Renamed function breaks integrations | High — broken integrations | | Immutable value changed | Constructor value differs in new deployment | Medium — unexpected behavior |

---

Resources

• Upgrade Safety

Workflows

• Differential Audit