web3-bug-classes

Name: web3-bug-classes
Author: shuvonsec

110stars29forks

How to install web3-bug-classes?

shuvonsec/web3-bug-bounty-hunting-ai-skills/web3-bug-classes

$npx -y skills add shuvonsec/web3-bug-bounty-hunting-ai-skills --skill web3-bug-classes

Installs into the current project.

Summary

Complete reference for all 10 DeFi smart contract bug classes. Use this when hunting for specific vulnerability types, need attack patterns for accounting desync, access control, incomplete path, off-by-one, oracle manipulation, ERC4626 vaults, reentrancy, flash loans, signature

Files · 1

View on GitHub

SKILL.md

1	# BUG CLASSES — DeFi Smart Contract Vulnerabilities
2
3	10 bug classes. Each one with root cause, vulnerable code, fix, grep patterns, and real paid examples.
4
5	---
6
7	## 1. ACCOUNTING STATE DESYNCHRONIZATION
8	> #1 Critical bug class — 28% of all Criticals on Immunefi.
9	> Real protocols: Yeet, Alchemix V3, Folks Finance, ResupplyFi, MetaPool
10
11	### What It Is
12
13	Two state variables are supposed to stay in sync. One code path updates variable A but forgets variable B. Later code reads both and makes decisions based on the stale B.
14
15	```
16	Real Value = A - B
17	If A is updated but B isn't → Real Value appears larger than it is → phantom value
18	```
19
20	### Root Cause Pattern
21
22	```solidity
23	// BEFORE (correct state):
24	// aToken.balanceOf(this) = 1000 (principal + yield)
25	// totalSupply = 1000 (only principal)
26	// yield = 1000 - 1000 = 0 ✓ correct
27
28	// Attacker triggers startUnstake:
29	totalSupply -= amount; // decremented BEFORE transfer
30	// totalSupply = 900 now
31	// aToken.balanceOf still = 1000
32	// yield appears = 1000 - 900 = 100 (PHANTOM)
33
34	// Now harvest():
35	yieldAmount = aToken.balanceOf(this) - totalSupply;
36	// = 1000 - 900 = 100 (phantom yield — no real yield was earned)
37	// Protocol harvests 100 of principal and distributes as "yield"
38	```
39
40	### Variants
41
42	Variant 1: Phantom Yield — totalSupply decremented before transfer
43	```solidity
44	// Yeet protocol (35 duplicate reports):
45	function startUnstake(uint256 amount) external {
46	totalSupply -= amount; // decremented here, transfer happens later
47	// balanceOf(this) - totalSupply now shows phantom yield
48	}
49	```
50
51	Variant 2: Fast Path Skips State Update — early return bypasses critical updates
52	```solidity
53	// Alchemix V3 claimRedemption:
54	function claimRedemption(uint256 tokenId) external {
55	if (transmuter.balance >= amount) {
56	transmuter.transfer(user, amount);
57	_burn(tokenId);
58	return; // EARLY RETURN — cumulativeEarmarked, _redemptionWeight, totalDebt never updated
59	}
60	// SLOW PATH: updates all state vars correctly
61	alchemist.redeem(...);
62	}
63	```
64
65	Variant 3: Rewards Accrue to Wrong Accumulator
66	```solidity
67	// Folks Finance Liquid Staking:
68	function addRewards(uint256 amount) external {
69	algoBalance += amount; // rewards go here
70	// MISSING: TOTAL_ACTIVE_STAKE += amount
71	}
72	function withdraw(uint256 shares) external {
73	uint256 myAmount = (shares * TOTAL_ACTIVE_STAKE) / totalSupply;
74	// TOTAL_ACTIVE_STAKE never got rewards → underflow → freeze
75	}
76	```
77
78	Variant 4: Update Happens in Wrong Order
79	```solidity
80	// Alchemix:
81	function deposit(uint256 amount) external {
82	_shares = (amount * totalShares) / totalAssets; // calculated BEFORE deposit
83	totalAssets += amount; // assets added AFTER shares calculated
84	totalShares += _shares; // shares calculation used stale totalAssets → wrong rate
85	}
86	```
87
88	### Grep Patterns
89	```bash
90	# List all balance/supply variables
91	grep -rn "totalSupply\\|totalShares\\|totalAssets\\|totalDebt\\|totalCollateral\\|cumulativeReward\\|rewardPerShare" contracts/ \| grep -v "//\\|test"
92
93	# Find ALL writes to key variables
94	grep -rn "totalSupply\s[-+]=[^=]\\|totalSupply\s*=" contracts/
95	grep -rn "cumulativeRewardPerShare\s[-+]=" contracts/
96
97	# Find all early returns in claim/redeem functions
98	grep -rn "\breturn\b" contracts/ -B3 \| grep -B3 "if\b"
99	# For each early return: which state updates are in the normal path but not this one?
100	```
101
102	### Kill Signals
103	- Only one variable is involved (no pair to desync)
104	- Both paths update all state vars identically
105	- Transfer happens AFTER state update in every path (correct CEI)
106	- Single-transaction atomicity prevents the window (no intermediate state visible)
107
108	### Real Paid Examples
109
110	\| Protocol \| Root Cause \|
111	\|----------\|-----------\|
112	\| Yeet \| `startUnstake` decrements totalSupply before transfer → phantom yield \|
113	\| Alchemix V3 \| `claimRedemption` fast path skips 3 state updates → phantom collateral \|
114	\| Folks Finance \| Rewards accrue to `algoBalance` not `TOTAL_ACTIVE_STAKE` → underflow \|
115	\| ResupplyFi \| ERC4626 near-empty vault exchange rate manipulation \|
116	\| MetaPool \| `mint()` skipped receipt check from `_deposit()` \|
117
118	---
119
120	## 2. ACCESS CONTROL
121	> #2 Critical bug class — 19% of all Criticals. $953M lost in 2024 alone.
122	> Real protocols: Wormhole ($10M), ZeroLend, Flare FAssets, Parity ($150M frozen)
123
124	### What It Is
125
126	A function that should be restricted is callable by anyone. Or a function checks the wrong condition (existence vs. ownership). Or a modifier uses `if` instead of `require` and silently does nothing for non-admins.
127
128	### Root Cause Patterns
129
130	Variant 1: Missing Modifier on Sibling Function
131	```solidity
132	func

People who liked this also viewed

6 picks

Type

web3-bug-classes

110stars29forks

View on GitHub

How to install web3-bug-classes?

shuvonsec/web3-bug-bounty-hunting-ai-skills/web3-bug-classes

$npx -y skills add shuvonsec/web3-bug-bounty-hunting-ai-skills --skill web3-bug-classes

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# BUG CLASSES — DeFi Smart Contract Vulnerabilities
2
3	10 bug classes. Each one with root cause, vulnerable code, fix, grep patterns, and real paid examples.
4
5	---
6
7	## 1. ACCOUNTING STATE DESYNCHRONIZATION
8	> #1 Critical bug class — 28% of all Criticals on Immunefi.
9	> Real protocols: Yeet, Alchemix V3, Folks Finance, ResupplyFi, MetaPool
10
11	### What It Is
12
13	Two state variables are supposed to stay in sync. One code path updates variable A but forgets variable B. Later code reads both and makes decisions based on the stale B.
14
15	```
16	Real Value = A - B
17	If A is updated but B isn't → Real Value appears larger than it is → phantom value
18	```
19
20	### Root Cause Pattern
21
22	```solidity
23	// BEFORE (correct state):
24	// aToken.balanceOf(this) = 1000 (principal + yield)
25	// totalSupply = 1000 (only principal)
26	// yield = 1000 - 1000 = 0 ✓ correct
27
28	// Attacker triggers startUnstake:
29	totalSupply -= amount; // decremented BEFORE transfer
30	// totalSupply = 900 now
31	// aToken.balanceOf still = 1000
32	// yield appears = 1000 - 900 = 100 (PHANTOM)
33
34	// Now harvest():
35	yieldAmount = aToken.balanceOf(this) - totalSupply;
36	// = 1000 - 900 = 100 (phantom yield — no real yield was earned)
37	// Protocol harvests 100 of principal and distributes as "yield"
38	```
39
40	### Variants
41
42	Variant 1: Phantom Yield — totalSupply decremented before transfer
43	```solidity
44	// Yeet protocol (35 duplicate reports):
45	function startUnstake(uint256 amount) external {
46	totalSupply -= amount; // decremented here, transfer happens later
47	// balanceOf(this) - totalSupply now shows phantom yield
48	}
49	```
50
51	Variant 2: Fast Path Skips State Update — early return bypasses critical updates
52	```solidity
53	// Alchemix V3 claimRedemption:
54	function claimRedemption(uint256 tokenId) external {
55	if (transmuter.balance >= amount) {
56	transmuter.transfer(user, amount);
57	_burn(tokenId);
58	return; // EARLY RETURN — cumulativeEarmarked, _redemptionWeight, totalDebt never updated
59	}
60	// SLOW PATH: updates all state vars correctly
61	alchemist.redeem(...);
62	}
63	```
64
65	Variant 3: Rewards Accrue to Wrong Accumulator
66	```solidity
67	// Folks Finance Liquid Staking:
68	function addRewards(uint256 amount) external {
69	algoBalance += amount; // rewards go here
70	// MISSING: TOTAL_ACTIVE_STAKE += amount
71	}
72	function withdraw(uint256 shares) external {
73	uint256 myAmount = (shares * TOTAL_ACTIVE_STAKE) / totalSupply;
74	// TOTAL_ACTIVE_STAKE never got rewards → underflow → freeze
75	}
76	```
77
78	Variant 4: Update Happens in Wrong Order
79	```solidity
80	// Alchemix:
81	function deposit(uint256 amount) external {
82	_shares = (amount * totalShares) / totalAssets; // calculated BEFORE deposit
83	totalAssets += amount; // assets added AFTER shares calculated
84	totalShares += _shares; // shares calculation used stale totalAssets → wrong rate
85	}
86	```
87
88	### Grep Patterns
89	```bash
90	# List all balance/supply variables
91	grep -rn "totalSupply\\|totalShares\\|totalAssets\\|totalDebt\\|totalCollateral\\|cumulativeReward\\|rewardPerShare" contracts/ \| grep -v "//\\|test"
92
93	# Find ALL writes to key variables
94	grep -rn "totalSupply\s[-+]=[^=]\\|totalSupply\s*=" contracts/
95	grep -rn "cumulativeRewardPerShare\s[-+]=" contracts/
96
97	# Find all early returns in claim/redeem functions
98	grep -rn "\breturn\b" contracts/ -B3 \| grep -B3 "if\b"
99	# For each early return: which state updates are in the normal path but not this one?
100	```
101
102	### Kill Signals
103	- Only one variable is involved (no pair to desync)
104	- Both paths update all state vars identically
105	- Transfer happens AFTER state update in every path (correct CEI)
106	- Single-transaction atomicity prevents the window (no intermediate state visible)
107
108	### Real Paid Examples
109
110	\| Protocol \| Root Cause \|
111	\|----------\|-----------\|
112	\| Yeet \| `startUnstake` decrements totalSupply before transfer → phantom yield \|
113	\| Alchemix V3 \| `claimRedemption` fast path skips 3 state updates → phantom collateral \|
114	\| Folks Finance \| Rewards accrue to `algoBalance` not `TOTAL_ACTIVE_STAKE` → underflow \|
115	\| ResupplyFi \| ERC4626 near-empty vault exchange rate manipulation \|
116	\| MetaPool \| `mint()` skipped receipt check from `_deposit()` \|
117
118	---
119
120	## 2. ACCESS CONTROL
121	> #2 Critical bug class — 19% of all Criticals. $953M lost in 2024 alone.
122	> Real protocols: Wormhole ($10M), ZeroLend, Flare FAssets, Parity ($150M frozen)
123
124	### What It Is
125
126	A function that should be restricted is callable by anyone. Or a function checks the wrong condition (existence vs. ownership). Or a modifier uses `if` instead of `require` and silently does nothing for non-admins.
127
128	### Root Cause Patterns
129
130	Variant 1: Missing Modifier on Sibling Function
131	```solidity
132	func

People who liked this also viewed

6 picks

Type