majiayu000 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:
- Modified contracts → Primary review target
- New contracts → Full audit required
- Deleted contracts → Check for orphaned references
- Modified tests → Understand what changed and why
- 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