zero-state-return

name	zero-state-return
description	Trigger Always inject into Arithmetic agent (extends existing ZERO_STATE_ECONOMICS) - Purpose Check protocol return-to-zero state, not just initial zero state

ZERO_STATE_RETURN Skill (Soroban)

Trigger: Always inject into Arithmetic agent (extends existing ZERO_STATE_ECONOMICS) Purpose: Check protocol return-to-zero state, not just initial zero state Finding prefix: [ZS-N] Rules referenced: R5, R10, R13

Overview

ZERO_STATE_ECONOMICS checks initial zero state. This skill EXTENDS it to cover:

• Protocol returning to zero after normal operations
• Residual assets when LP/share supply returns to zero
• Re-entry vulnerabilities after full exit
• Soroban-specific: i128 division edge cases at zero, empty Instance/Persistent storage states

1. Return-to-Zero Scenarios

After normal operations, can the protocol return to:

State	Trigger	Check
total_shares == 0 (i128)	All users burned shares / withdrew	Recreates first-depositor conditions?
total_deposited == 0	All funds withdrawn	Residual rewards or time-decay state in Persistent storage?
Empty Instance storage keys	All operational state cleared	Can protocol still function on next call?
Zero liquidity	All LP positions closed	What happens to accumulated fees / ratio snapshots?

2. Residual Asset Check

When LP/share supply returns to zero, check for:

2a. Accrued Rewards / Time-Decay State

• Do rewards or time-decay state persist in Instance/Persistent storage when total_shares = 0?
• If YES → inflates exchange rate for next depositor

2b. Unclaimed Fees / Ratio Snapshot State

• Fee accumulators (performance/management fees) in Instance storage that persist?
• Ratio snapshots (high water marks, benchmarks) reset when all shares burned?
• Can first new depositor capture accumulated fees?

2c. Token Balance Dust

• Can dust remain in contract's token balance after all shares burned?
• Does dust affect exchange rate when total_shares = 0?
• Soroban note: No separate token account to close — balance is in the SEP-41 token's Persistent storage for the contract's address.

2d. Pending Operations

• Pending withdrawal receipts / claim tickets in Persistent storage that persist when total_shares = 0?
• Do sub-contract or cross-contract positions retain allocated funds after all shares burned?

3. Re-Entry Vulnerability Analysis

Does re-entering zero state recreate first-depositor attack conditions?

Scenario	Initial State	Return-to-Zero State	Same Vulnerability?
First depositor attack	total_shares=0, total_value=0	total_shares=0, total_value=X (residual)	WORSE if residual > 0
Exchange rate manipulation	No shares exist	No shares, but token balance > 0	YES + amplified
Donation attack	Clean state	Dirty state (residual, unsolicited dust)	YES + pre-seeded

Key question: Does first-depositor protection apply only on initial initialize() or also on return-to-zero re-deposits?

Soroban-specific: If protection is if total_shares == 0 { require(amount >= MIN_FIRST_DEPOSIT) }, does it fire on return-to-zero? Is MIN_FIRST_DEPOSIT in Instance storage (accessible) or hardcoded?

4. Protocol Reset Functions

Check for admin functions that can force zero state:

• emergency_withdraw() — clears ALL tracked state (totals, accumulators, snapshots)?
• close_vault() — what Persistent/Instance keys persist after calling?
• migrate() — old contract retains residual token balances?
• force_deallocate() — creates accounting mismatch between state and token balance?

Soroban-specific: Instance storage has no single "close all" operation. Verify each DataKey variant is explicitly cleared during reset, not just main accounting keys.

5. Zero-State Return Checklist

## Zero-State Return Analysis for [Contract / Vault]

### Can protocol return to zero state?
- [ ] All users can withdraw / burn shares (no locked funds)
- [ ] total_shares (i128) can reach exactly 0

### What persists when total_shares = 0?
- [ ] Accrued rewards / time-decay state: [amount / none]
- [ ] Protocol fees / ratio snapshots: [amount / none / resets]
- [ ] Token balance dust: [yes / no]
- [ ] Pending operations in Persistent storage: [list / none]
- [ ] Sub-contract allocations: [zeroed / residual]

### Re-entry vulnerability?
- [ ] Initial zero state protected: [yes / no / how]
- [ ] Return-to-zero state protected: [yes / no / how]
- [ ] Same protection mechanism: [yes / no]

### Exchange rate at return-to-zero:
- [ ] Formula: [show calculation using i128 values]
- [ ] With residual X: [panic? wrong value?]
- [ ] Can attacker inflate rate before re-entry: [yes / no]

5b. Default / Uninitialized State Values

For each state variable used in arithmetic or control flow, check its initial value before any user interaction:

• Missing key returns None: e.storage().instance().get::<_, i128>(&DataKey::X) returns None if never written. unwrap() panics; unwrap_or(0) silently treats as 0.
• First-call path: Trace FIRST invocation of each state-modifying function. Does it assume initialize() already set dependent keys?
• Signed zero vs missing: Soroban storage does NOT default to 0 — absent keys return None. Confusion between "key present with value 0" and "key absent" can cause bugs.

6. Code Patterns to Check

// Pattern 1: Guard covers initial zero only — what about return-to-zero?
if vault.total_shares == 0i128 {
    return Ok(1_000_000i128); // 1:1 rate
}
// QUESTION: What if total_shares returns to 0 but token balance > 0?

// Pattern 2: i128 exchange rate with division by zero
let rate = vault.total_value
    .checked_div(vault.total_shares)
    .ok_or(Error::DivisionByZero)?;
// QUESTION: What if total_value > 0 and total_shares = 0?

// Pattern 3: First deposit protection
if vault.total_shares == 0i128 {
    require!(deposit_amount >= MIN_FIRST_DEPOSIT, Error::DepositTooSmall);
}
// QUESTION: Does this fire for RE-deposits after full exit?

// Pattern 4: Time-decay state
let unlocked = vault.decay_amount * elapsed_ledgers / DECAY_DURATION_LEDGERS;
// QUESTION: Does decay_amount persist when total_shares = 0?

7. Finding Template

**ID**: [ZS-N]
**Severity**: [typically HIGH if funds extractable]
**Location**: src/{file}.rs:LineN
**Title**: Return-to-zero state allows [attack] due to [residual state in storage]
**Description**:
- Protocol can return to total_shares=0 via [mechanism]
- When this happens, [storage key] retains value of [amount] (i128)
- A new depositor can [exploit path]
**Impact**: [Fund extraction / exchange rate manipulation / unfair distribution]
**PoC Scenario**:
1. Users deposit and earn rewards
2. All users withdraw, total_shares = 0i128
3. Residual state remains: {DataKey::DecayAmount} = X in Instance storage
4. Attacker deposits minimum amount
5. Attacker claims X rewards via inflated share-to-value ratio

8. Integration with ZERO_STATE_ECONOMICS

This skill does NOT replace ZERO_STATE_ECONOMICS. It EXTENDS it:

Check	ZERO_STATE_ECONOMICS	ZERO_STATE_RETURN
Initial zero state / first depositor	YES	—
Return to zero	—	YES
Residual assets (time-decay, fees, dust)	—	YES
Re-entry vulnerability	—	YES
i128 division-by-zero guards	YES (partial)	YES (both initial and return paths)
Missing storage key defaults	—	YES

When applying ZERO_STATE_ECONOMICS, ALSO apply ZERO_STATE_RETURN.