state-invariant-detection

Name: state-invariant-detection
Author: quillai-network

114stars23forks

How to install state-invariant-detection?

quillai-network/quillshield_skills/state-invariant-detection

$npx -y skills add quillai-network/quillshield_skills --skill state-invariant-detection

Installs into the current project.

Summary

Detects broken mathematical relationships between state variables in smart contracts. Automatically infers invariants (totalSupply = sum(balances), conservation laws, ratio constraints) then finds functions that violate them. Catches unauthorized minting, broken tokenomics, accou

Files · 1

View on GitHub

SKILL.md

1	# State Invariant Detection
2
3	Automatically infer mathematical relationships between state variables, then find functions that break those relationships. Catches the most devastating DeFi vulnerabilities: unauthorized minting, broken tokenomics, accounting discrepancies, and state desynchronization.
4
5	## When to Use
6
7	- Auditing token contracts for supply/balance mismatches
8	- Analyzing staking, vault, or pool contracts for accounting errors
9	- Detecting conservation law violations in treasury/fund management
10	- Finding AMM/DEX constant product violations
11	- Verifying that aggregate variables stay synchronized with individual records
12
13	## When NOT to Use
14
15	- Guard-state consistency analysis (use semantic-guard-analysis)
16	- Full multi-dimensional audit (use behavioral-state-analysis)
17	- Entry point identification only (use entry-point-analyzer)
18
19	## Core Concept: State Variable Proportionality
20
21	Hypothesis: In well-designed contracts, state variables maintain mathematical relationships (invariants) that should never be violated.
22
23	When a function modifies one side of a relationship without updating the other, the invariant breaks — creating exploitable accounting errors.
24
25	## Five Types of State Relationships
26
27	### Type 1: Sum Relationships (Aggregation)
28
29	```
30	totalSupply = Σ balance[i] for all users i
31	```
32
33	Found in: ERC20 tokens, staking pools, vaults, share systems
34
35	### Type 2: Difference Relationships (Conservation)
36
37	```
38	totalFunds = availableFunds + lockedFunds
39	```
40
41	Found in: Treasuries, liquidity pools, vesting contracts
42
43	### Type 3: Ratio Relationships (Proportional)
44
45	```
46	k = reserveA × reserveB (constant product)
47	sharePrice = totalAssets / totalShares
48	```
49
50	Found in: AMMs, DEXs, vault share pricing, collateralization
51
52	### Type 4: Monotonic Relationships (Ordering)
53
54	```
55	newValue ≥ oldValue (only increases)
56	```
57
58	Found in: Timestamps, nonces, accumulated rewards, total distributions
59
60	### Type 5: Synchronization Relationships (Coupling)
61
62	```
63	If stateA changes, stateB must change correspondingly
64	```
65
66	Found in: Deposit/mint pairs, burn/release pairs, collateral/borrowing power
67
68	For detailed definitions and examples, see [{baseDir}/references/invariant-types.md]({baseDir}/references/invariant-types.md).
69
70	## The Three-Phase Detection Architecture
71
72	### Phase 1: State Variable Clustering
73
74	Group state variables that appear to be related.
75
76	Algorithm:
77
78	```
79	For each pair of state variables (A, B):
80	1. Track all functions that modify A
81	2. Track all functions that modify B
82	3. Calculate co-modification frequency:
83
84	CoMod(A, B) = \|Functions modifying both A and B\| / \|Functions modifying A or B\|
85
86	4. If CoMod(A, B) > 0.6 → A and B are likely related
87	```
88
89	Example:
90
91	```solidity
92	// mint() modifies BOTH totalSupply and balances → co-modified
93	// burn() modifies BOTH totalSupply and balances → co-modified
94	// transfer() modifies ONLY balances → does not co-modify
95
96	CoMod(totalSupply, balances) = 2/3 = 66.7%
97	Cluster identified: (totalSupply, balances)
98	```
99
100	### Phase 2: Invariant Inference
101
102	Determine the mathematical relationship between clustered variables.
103
104	Method 1 — Delta Pattern Matching:
105
106	```
107	mint(): Δtotal = +amount, Δbalance = +amount → Same direction, same magnitude
108	burn(): Δtotal = -amount, Δbalance = -amount → Same direction, same magnitude
109	transfer(): Δbalance1 = -x, Δbalance2 = +x → Net zero change
110
111	Inference: totalSupply = Σ balances (Aggregation invariant)
112	```
113
114	Method 2 — Delta Correlation:
115
116	```
117	If ΔA = ΔB in all cases → Direct proportional (A = B + constant)
118	If ΔA = -ΔB in all cases → Inverse proportional (A + B = constant)
119	If ΔA × constant = ΔB → Ratio relationship
120	If ΔA occurs whenever ΔB → Synchronization invariant
121	```
122
123	Method 3 — Expression Mining:
124
125	Parse actual code operations:
126
127	```solidity
128	// Code: totalSupply += amount; balances[user] += amount;
129	// Extracted: Δtotal = Δbalance
130	// Inferred: total = Σ balances
131
132	// Code: available = total - locked;
133	// Extracted: available + locked = total
134	// Inferred: Conservation law
135	```
136
137	Invariant Confidence:
138
139	```
140	Confidence(I) = \|functions preserving I\| / \|functions modifying variables in I\|
141	```
142
143	\| Confidence \| Classification \|
144	\|-----------\|---------------\|
145	\| ≥ 90% \| STRONG invariant \|
146	\| 70-89% \| MODERATE invariant \|
147	\| < 70% \| WEAK/NO invariant \|
148
149	### Phase 3: Invariant Violation Detection
150
151	Find functions that break established relationships.
152
153	**Algor

People who liked this also viewed

6 picks

Type

state-invariant-detection

114stars23forks

View on GitHub

How to install state-invariant-detection?

quillai-network/quillshield_skills/state-invariant-detection

$npx -y skills add quillai-network/quillshield_skills --skill state-invariant-detection

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# State Invariant Detection
2
3	Automatically infer mathematical relationships between state variables, then find functions that break those relationships. Catches the most devastating DeFi vulnerabilities: unauthorized minting, broken tokenomics, accounting discrepancies, and state desynchronization.
4
5	## When to Use
6
7	- Auditing token contracts for supply/balance mismatches
8	- Analyzing staking, vault, or pool contracts for accounting errors
9	- Detecting conservation law violations in treasury/fund management
10	- Finding AMM/DEX constant product violations
11	- Verifying that aggregate variables stay synchronized with individual records
12
13	## When NOT to Use
14
15	- Guard-state consistency analysis (use semantic-guard-analysis)
16	- Full multi-dimensional audit (use behavioral-state-analysis)
17	- Entry point identification only (use entry-point-analyzer)
18
19	## Core Concept: State Variable Proportionality
20
21	Hypothesis: In well-designed contracts, state variables maintain mathematical relationships (invariants) that should never be violated.
22
23	When a function modifies one side of a relationship without updating the other, the invariant breaks — creating exploitable accounting errors.
24
25	## Five Types of State Relationships
26
27	### Type 1: Sum Relationships (Aggregation)
28
29	```
30	totalSupply = Σ balance[i] for all users i
31	```
32
33	Found in: ERC20 tokens, staking pools, vaults, share systems
34
35	### Type 2: Difference Relationships (Conservation)
36
37	```
38	totalFunds = availableFunds + lockedFunds
39	```
40
41	Found in: Treasuries, liquidity pools, vesting contracts
42
43	### Type 3: Ratio Relationships (Proportional)
44
45	```
46	k = reserveA × reserveB (constant product)
47	sharePrice = totalAssets / totalShares
48	```
49
50	Found in: AMMs, DEXs, vault share pricing, collateralization
51
52	### Type 4: Monotonic Relationships (Ordering)
53
54	```
55	newValue ≥ oldValue (only increases)
56	```
57
58	Found in: Timestamps, nonces, accumulated rewards, total distributions
59
60	### Type 5: Synchronization Relationships (Coupling)
61
62	```
63	If stateA changes, stateB must change correspondingly
64	```
65
66	Found in: Deposit/mint pairs, burn/release pairs, collateral/borrowing power
67
68	For detailed definitions and examples, see [{baseDir}/references/invariant-types.md]({baseDir}/references/invariant-types.md).
69
70	## The Three-Phase Detection Architecture
71
72	### Phase 1: State Variable Clustering
73
74	Group state variables that appear to be related.
75
76	Algorithm:
77
78	```
79	For each pair of state variables (A, B):
80	1. Track all functions that modify A
81	2. Track all functions that modify B
82	3. Calculate co-modification frequency:
83
84	CoMod(A, B) = \|Functions modifying both A and B\| / \|Functions modifying A or B\|
85
86	4. If CoMod(A, B) > 0.6 → A and B are likely related
87	```
88
89	Example:
90
91	```solidity
92	// mint() modifies BOTH totalSupply and balances → co-modified
93	// burn() modifies BOTH totalSupply and balances → co-modified
94	// transfer() modifies ONLY balances → does not co-modify
95
96	CoMod(totalSupply, balances) = 2/3 = 66.7%
97	Cluster identified: (totalSupply, balances)
98	```
99
100	### Phase 2: Invariant Inference
101
102	Determine the mathematical relationship between clustered variables.
103
104	Method 1 — Delta Pattern Matching:
105
106	```
107	mint(): Δtotal = +amount, Δbalance = +amount → Same direction, same magnitude
108	burn(): Δtotal = -amount, Δbalance = -amount → Same direction, same magnitude
109	transfer(): Δbalance1 = -x, Δbalance2 = +x → Net zero change
110
111	Inference: totalSupply = Σ balances (Aggregation invariant)
112	```
113
114	Method 2 — Delta Correlation:
115
116	```
117	If ΔA = ΔB in all cases → Direct proportional (A = B + constant)
118	If ΔA = -ΔB in all cases → Inverse proportional (A + B = constant)
119	If ΔA × constant = ΔB → Ratio relationship
120	If ΔA occurs whenever ΔB → Synchronization invariant
121	```
122
123	Method 3 — Expression Mining:
124
125	Parse actual code operations:
126
127	```solidity
128	// Code: totalSupply += amount; balances[user] += amount;
129	// Extracted: Δtotal = Δbalance
130	// Inferred: total = Σ balances
131
132	// Code: available = total - locked;
133	// Extracted: available + locked = total
134	// Inferred: Conservation law
135	```
136
137	Invariant Confidence:
138
139	```
140	Confidence(I) = \|functions preserving I\| / \|functions modifying variables in I\|
141	```
142
143	\| Confidence \| Classification \|
144	\|-----------\|---------------\|
145	\| ≥ 90% \| STRONG invariant \|
146	\| 70-89% \| MODERATE invariant \|
147	\| < 70% \| WEAK/NO invariant \|
148
149	### Phase 3: Invariant Violation Detection
150
151	Find functions that break established relationships.
152
153	**Algor

People who liked this also viewed

6 picks

Type