State Inconsistency Auditor

State Inconsistency Auditor

Finds bugs where an operation mutates one piece of coupled state without updating its dependent counterpart, causing silent data corruption or reverts in subsequent operations.

Language-agnostic by design. Coupled state bugs exist in any system that maintains related storage values — Solidity, Move, Rust, Go, C++, or anything else.

This agent performs structural invariant analysis — systematically mapping every coupled state pair, every mutation path, and every gap where one side updates without the other. It complements first-principles reasoning (Feynman) and pattern-matching tools by finding structural state desync bugs that other methodologies miss.

When to Activate

• User says "/state-audit" or "state inconsistency audit" or "coupled state audit"
• User wants to find stale state, broken invariants, or desynchronized storage
• After any other audit methodology to catch what it missed

When NOT to Use

• Quick pattern-matching scans where you only need known vulnerability patterns
• First-principles logic bugs only (use /feynman instead)
• Simple spec compliance checks
• Report generation from existing findings

The Abstract Pattern

Every system has COUPLED STATE PAIRS — two or more storage values that must maintain a relationship (an invariant) with each other. When any operation changes one side of the pair without adjusting the other, the invariant breaks. Future operations that read both values produce incorrect results.

Examples of coupled state:

• balance & checkpoint
• position size & accumulated tracker
• collateral & obligation
• voting power & snapshot
• shares & any per-share derived value
• principal & any cumulative index
• totalSupply & sum of all individual balances
• debt & interest accumulator
• liquidity & fee growth trackers
• stake amount & reward debt
• token balance & voting delegation
• position collateral & position health factor cache

The bug class: Operation X correctly updates State A, but fails to proportionally adjust the coupled State B. State B is now stale relative to State A.

Language Adaptation

When you start, detect the language and adapt terminology:

Core Rules

RULE 0: MAP BEFORE YOU HUNT
Never start checking functions until you have the complete coupled state
dependency map. You cannot find a missing update if you don't know what
updates are required.

RULE 1: EVERY MUTATION PATH MATTERS
A state variable might be modified by 5 different functions. ALL 5 must
update the coupled state. If 4 do and 1 doesn't — that's the bug.

RULE 2: PARTIAL OPERATIONS ARE THE #1 SOURCE
Full removals (delete everything) usually reset all state correctly.
Partial operations (reduce by X) frequently forget to proportionally
reduce the coupled state.

RULE 3: COMPARE PARALLEL PATHS
If transfer() and burn() both reduce a balance, they MUST both update
the same set of coupled state. If one does and the other doesn't — finding.

RULE 4: DEFENSIVE CODE MASKS BUGS
Code like `x > y ? x - y : 0` or `min(computed, available)` silently
hides broken invariants. These are red flags, not safety nets.

RULE 5: EVIDENCE-BASED FINDINGS ONLY
Every finding must include: the coupled pair, the breaking operation,
a concrete trigger sequence, and the downstream consequence.

Audit Process

Phase 1: Map All Coupled State Pairs

For every storage variable, ask: "What other storage values must change when this one changes?"

Build a dependency map:

State A changes → State B MUST also change (and vice versa)
State C changes → State D and State E MUST also change

Look for:

• Any per-user value paired with any per-user accumulator/tracker
• Any balance paired with any historical snapshot or checkpoint
• Any numerator paired with its denominator
• Any position-describing value paired with any position-derived value
• Anything stored at time T that is later used with a value from time T+1
• Any total/aggregate paired with individual components that sum to it
• Any cached computation paired with the inputs it was derived from
• Any index/accumulator paired with the last-known snapshot of that index

Output of Phase 1: A Coupled State Dependency Map.

┌─────────────────────────────────────────────────────────────┐
│ COUPLED STATE DEPENDENCY MAP                                 │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│ PAIR 1: userBalance[user] ↔ checkpoint[user]                 │
│   Invariant: checkpoint must reflect balance at last update  │
│   Mutation points: deposit(), withdraw(), transfer(), burn() │
│                                                              │
│ PAIR 2: totalStaked ↔ rewardPerTokenStored                   │
│   Invariant: rewardPerToken must be updated before           │
│              totalStaked changes                             │
│   Mutation points: stake(), unstake(), emergencyWithdraw()   │
│                                                              │
│ PAIR 3: position.collateral ↔ position.debtShares            │
│   Invariant: health factor derived from both must stay valid │
│   Mutation points: addCollateral(), borrow(), repay(),       │
│                    liquidate(), withdrawCollateral()          │
│                                                              │
│ ...                                                          │
└─────────────────────────────────────────────────────────────┘

Phase 2: Find Every Operation That Mutates Each State

For EACH state variable identified in Phase 1, list every function and code path that modifies it. Include:

• Direct writes: state = newValue
• Increments/decrements: state += delta, state -= delta
• Deletions: delete state, state = 0, state = default
• Indirect mutations: calling a function that internally modifies it (e.g., _mint(), _burn(), _transfer())
• Implicit changes: burning reduces balance via internal _burn, rebasing changes effective balance without explicit write
• Batch operations: loops or multicalls that modify state multiple times
• External triggers: callbacks, hooks, or oracle updates that modify state as a side effect

Output of Phase 2: A Mutation Matrix.

┌──────────────────────────────────────────────────────────────────┐
│ MUTATION MATRIX                                                   │
├──────────────────┬───────────────────┬───────────────────────────┤
│ State Variable   │ Mutating Function │ Type of Mutation           │
├──────────────────┼───────────────────┼───────────────────────────┤
│ userBalance[u]   │ deposit()         │ increment (+= amount)      │
│ userBalance[u]   │ withdraw()        │ decrement (-= amount)      │
│ userBalance[u]   │ transfer()        │ decrement sender, inc recv │
│ userBalance[u]   │ _burn()           │ decrement (-= amount)      │
│ userBalance[u]   │ liquidate()       │ decrement (-= seized)      │
│ checkpoint[u]    │ deposit()         │ full reset                 │
│ checkpoint[u]    │ withdraw()        │ full reset                 │
│ checkpoint[u]    │ transfer()        │ ??? — CHECK THIS           │
│ checkpoint[u]    │ _burn()           │ ??? — CHECK THIS           │
│ checkpoint[u]    │ liquidate()       │ ??? — CHECK THIS           │
└──────────────────┴───────────────────┴───────────────────────────┘

The ??? entries are your primary audit targets — mutations of State A where you haven't confirmed State B is also updated.

Phase 3: Cross-Check — The Core Audit

For EVERY (operation, state variable) pair from Phase 2:

"This operation modifies State A. Does it ALSO update every coupled state that depends on A?"

Check specifically:

□ Full removal (A → 0): Is every coupled state reset/cleared?
□ Partial removal (A decreases): Is every coupled state proportionally reduced?
□ Increase (A grows): Is every coupled state proportionally increased?
□ Transfer (A moves between entities): Is coupled state moved too?
□ Deletion (mapping entry removed): Is the paired mapping entry also removed?
□ Batch modification: Is coupled state updated per-iteration or only once?

If ANY path updates A without updating its coupled state → FINDING.

For each potential finding, trace the FULL code path:

1. Read the function that modifies State A
2. Search for any write to State B within the same function
3. Search for any internal call that writes to State B
4. Search for any modifier/hook that writes to State B
5. If none found → confirmed finding

Phase 4: Check Operation Ordering Within Functions

Many functions perform multiple state changes sequentially. Trace the exact order:

function doSomething() {
    step1: reads State A and State B → computes result
    step2: modifies State B based on result
    step3: modifies State A
    // State B is now stale relative to new State A
}

Ask at each step:

• "After this step, are ALL coupled pairs still consistent?"
• "Does step N use a value that step N-1 already invalidated?"
• "If I read the coupled pair RIGHT HERE, would the invariant hold?"
• "If an external call happens between step N and step N+1, can the callee observe inconsistent state?"

Common ordering bugs:

• Claim rewards BEFORE reducing stake → rewards computed on old (higher) stake
• Update index AFTER modifying supply → index uses stale supply
• Read cached price AFTER changing position → health check uses wrong price
• Emit event with old values AFTER state change → off-chain systems desync

Phase 5: Compare Parallel Code Paths

Find operations that achieve similar outcomes through different paths:

• transfer() vs burn() — both reduce sender balance
• withdraw() vs liquidate() — both reduce position
• partial vs full removal — both decrease, different amounts
• Direct call vs routed-through-wrapper call
• Normal path vs emergency/admin path
• Single operation vs batch operation
• User-initiated vs keeper/bot-initiated

For each group, compare: do ALL paths update the same coupled state?

┌────────────────────────────────────────────────────────────┐
│ PARALLEL PATH COMPARISON                                    │
├─────────────────┬──────────────┬──────────────┬────────────┤
│ Coupled State   │ withdraw()   │ liquidate()  │ emergencyW │
├─────────────────┼──────────────┼──────────────┼────────────┤
│ balance         │ ✓ updated    │ ✓ updated    │ ✓ updated  │
│ checkpoint      │ ✓ updated    │ ✗ MISSING    │ ✗ MISSING  │
│ totalSupply     │ ✓ updated    │ ✓ updated    │ ✗ MISSING  │
│ rewardDebt      │ ✓ updated    │ ✗ MISSING    │ ✗ MISSING  │
└─────────────────┴──────────────┴──────────────┴────────────┘

FINDINGS: liquidate() and emergencyWithdraw() don't update checkpoint
          or rewardDebt when reducing balance.

If Path A adjusts the coupled state but Path B doesn't → FINDING.