plamentsv / zero-state-return

ZEROSTATERETURN Skill

Trigger Pattern: Vault/pool/first-depositor pattern detected
Inject Into: Depth-edge-case
Purpose: Analyze zero-state transitions in Aptos Move protocols -- initial zero state, return to zero after operations, residual assets, and re-entry vulnerabilities

Overview

This skill covers BOTH initial zero state AND return-to-zero-state analysis:

• Protocol initialization and first deposit conditions
• Protocol returning to zero after normal operations
• Residual assets when supply returns to zero
• Re-entry vulnerabilities after full exit

1. Identify Zero-State Transitions

Find all vault/pool/staking mechanisms and their zero-state boundaries:

For each state: what is the protocol behavior when this condition is true?

2. First Depositor Analysis

Can the first depositor manipulate share price?

2a. Share Minting Formula at Zero State

Classic first depositor attack on Aptos:

1. First depositor deposits minimal amount (e.g., 1 unit)
2. Attacker directly deposits tokens to the protocol's FungibleStore (unsolicited -- bypasses accounting)
3. Exchange rate inflates: totalAssets increases but totalShares stays at 1
4. Next depositor receives 0 shares due to rounding (their deposit amount < inflated share price)
5. First depositor withdraws, capturing the second depositor's funds

Checks:

• [ ] Is there a minimum first deposit requirement?
• [ ] Does the protocol use virtual shares/assets (e.g., add 1 to both numerator and denominator)?
• [ ] Is there a dead shares mechanism (burn initial shares to zero address)?
• [ ] Can unsolicited deposits to the protocol's store inflate totalAssets?
• [ ] Does the protocol use internal accounting (resistant) or direct balance queries (vulnerable)?

2b. First Deposit Protection Mechanisms

3. Return to Zero Analysis

After normal operations, can the protocol return to zero state?

3a. Return-to-Zero Scenarios

3b. Can Total Shares Reach Exactly Zero?

Trace the withdrawal/burn path:

• Can the last user withdraw ALL their shares? (no minimum balance lock?)
• Does the protocol enforce a minimum share amount that prevents reaching zero?
• If dead shares exist, totalShares never reaches 0 -- is this protection consistent?

4. Residual Asset Check

When supply returns to zero, check for stranded value:

4a. Accrued Rewards

If rewards persist AND next depositor can claim -> FINDING (severity based on amount).

4b. Unclaimed Fees

4c. Dust Balances

• Can dust (sub-unit amounts) remain in FungibleStore after all withdrawals?
• Does dust affect exchange rate calculations on re-entry? (e.g., totalAssets = 1 wei, totalShares = 0)
• Does the protocol handle totalAssets > 0 AND totalShares == 0 explicitly?

4d. Pending Operations

• Are there pending withdrawals/claims that persist after zero state?
• What happens to in-flight multi-step operations when supply hits zero?
• Are there resources or objects that reference the pool/vault state that become orphaned?

5. Re-Entry Vulnerability Analysis

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

Key question: Is the first-deposit protection (from Section 2b) applied ONLY on initial deployment, or does it also trigger when totalShares returns to 0?

Trace the share minting code:

// Pattern: Protection covers initial AND return-to-zero
if (total_shares == 0) {
    // First deposit logic with protection
}

// vs Pattern: Protection only on first-ever deposit
if (!initialized) {
    // Protection here
} else if (total_shares == 0) {
    // NO protection -- vulnerable on return-to-zero
}

5b. Default/Uninitialized State Values

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

• Default zero: Move initializes struct fields to their declared defaults (typically 0 for integers, @0x0 for addresses). If a function uses last_timestamp, start_time, or last_update in subtraction or division BEFORE it has ever been set, the result may be unexpected (e.g., timestamp::now_seconds() - 0 = enormous elapsed time, or division by a value derived from 0).
• First-call path: Trace the FIRST invocation of each state-modifying function. Does it assume a prior call already initialized dependent fields?
• Check: For each field read in a function, is there a code path where that field still holds its default value (0, @0x0, false)? If yes, does the function behave correctly with that default?

6. Empty Pool Edge Cases

6a. Division by Zero

For each division: is there a zero-check guard? If not, what transaction aborts?

6b. Zero-Amount Operations at Zero State

7. Protocol Reset Functions

Check for admin functions that can force zero state:

For each: what state persists after the "reset"? Can it be exploited?

Instantiation Parameters

{CONTRACTS}              -- Move modules containing vault/pool logic
{SHARE_VARIABLES}        -- Variables tracking total shares/supply
{ASSET_VARIABLES}        -- Variables tracking total assets/deposits
{SHARE_MINT_FORMULA}     -- Share calculation formula at deposit
{FIRST_DEPOSIT_GUARDS}   -- Existing first-deposit protections

Finding Template

**ID**: [ZS-N]
**Severity**: [typically HIGH if funds extractable, MEDIUM if DoS]
**Step Execution**: checkmark1,2,3,4,5,6,7 | x(reasons) | ?(uncertain)
**Rules Applied**: [R4:Y, R10:Y, R11:Y]
**Location**: module::function:LineN
**Title**: [Zero-state type] allows [attack] due to [residual state / missing protection]
**Description**:
- Protocol can reach totalShares=0 via [mechanism]
- When this happens, [state variable] retains value of [amount]
- A new depositor can [exploit path]
**Impact**: [Fund extraction / exchange rate manipulation / DoS]

Output Schema

Step Execution Checklist (MANDATORY)

Cross-Reference Markers

After Section 2 (First Depositor): Cross-reference with TOKEN_FLOW_TRACING.md Section 5 for unsolicited deposit vectors that amplify first-depositor attacks.

After Section 4 (Residual Assets): If residual rewards/fees found, cross-reference with ECONOMIC_DESIGN_AUDIT.md for whether fee/reward accumulation is bounded.

After Section 5 (Re-Entry): If return-to-zero is possible AND first-deposit protection is initial-only -> FINDING (minimum Medium, upgrade to High if unsolicited deposits can amplify).