plamentsv/storage-lifecycle

STORAGE_LIFECYCLE Skill (Soroban)

Trigger Pattern: Always required for Soroban audits Inject Into: Breadth agents, depth agents Finding prefix: [SL-N] Rules referenced: R8, R10, R14

Soroban has three distinct storage types — Instance, Persistent, and Temporary — with fundamentally different lifetime semantics. Using the wrong storage type is a critical design flaw. Instance and Persistent entries expire if TTL is not extended; Temporary entries are permanently deleted at expiration with no recovery path.

1. Storage Type Audit

For every storage key defined (typically in a DataKey enum or equivalent), verify the correct storage type is used:

| DataKey Variant | Storage Type Used | Correct Type? | Justification | |----------------|------------------|--------------|---------------| | {key} | Instance / Persistent / Temporary | YES/NO | {why this type is correct or wrong} |

Selection rules:

• Instance: Contract-wide config that lives and dies with the contract itself (admin address, fee parameters, pause flag). Shared 64KB limit with all other Instance entries for this contract.
• Persistent: User-specific state that must survive indefinitely (balances, positions, allowances that should not expire). Requires explicit TTL extension. Archived entries can be restored but require a fee.
• Temporary: Truly ephemeral data that becomes invalid after a period (short-lived signatures, nonces with expiry, one-time-use proofs). Permanently deleted at expiry — no recovery.

Common misclassifications to flag:

• User balances stored as Temporary (funds permanently lost at expiry)
• Escrow or locked funds stored as Temporary
• Allowances stored as Temporary without the protocol communicating expiry to users
• Voting records or governance state stored as Temporary (votes silently discarded)

2. TTL Management

Soroban entries expire if their TTL is not extended. Identify all critical entries and verify TTL extension logic:

| DataKey | Storage Type | TTL Extended? | Extension Location | Threshold Value | Extend-To Value | Reasonable? | |---------|-------------|--------------|-------------------|----------------|-----------------|-------------| | {key} | Persistent/Instance | YES/NO | {fn:line or NONE} | {ledgers or NONE} | {ledgers or NONE} | YES/NO |

Check for:

• Critical entries (admin, balances, config) never having their TTL extended → will expire after the initial minimum TTL (~17 days at default settings)
• extend_ttl called with threshold = 0 (extends on every call, expensive) vs reasonable threshold
• extend_ttl called only in some code paths but not others (e.g., extended on deposit but not on query)
• Extend-to value set too low (e.g., 100 ledgers ≈ 8 minutes) causing rapid re-expiry

TTL extension pattern (correct):

let max_ttl = env.ledger().max_entry_ttl();
env.storage().persistent().extend_ttl(&key, max_ttl / 2, max_ttl);

Dangerous anti-pattern:

// Never extends TTL — entry will expire after initial minimum
env.storage().persistent().set(&DataKey::Balance(user), &balance);
// (no extend_ttl call anywhere for this key)

3. Instance Storage Bounds

Instance storage is shared across ALL instance entries for a contract and has a hard cap of approximately 64KB. Unbounded growth causes contract failure.

| DataKey | Stored in Instance? | Data Type | Can Grow Unboundedly? | Current Bound | Risk | |---------|--------------------|-----------|-----------------------|---------------|------| | {key} | YES/NO | {type} | YES/NO | {N entries or unbounded} | HIGH/MED/LOW |

Check for:

• Vec<T> stored in Instance storage — grows with each push
• Map<K, V> stored in Instance storage — grows with each new key
• Any collection type in Instance storage that users or external callers can add to

Attack: If Instance storage approaches 64KB, ALL contract operations that touch instance storage fail, effectively bricking the contract. An attacker who can add entries (e.g., via a public function that appends to an Instance-stored Vec) can DoS the entire contract.

Estimate growth: For each unbounded Instance collection, estimate: what is the maximum realistic entry size? How many entries before 64KB is reached? Is that number reachable by a malicious actor?

3b. Persistent Storage Single-Entry Growth DoS

Even though Persistent storage has no shared size limit, each individual ledger entry has a ~64KB size limit. A single Persistent key holding a growing collection hits this limit the same way Instance storage does.

| Persistent Key | Data Type | Grows With Users? | Approx Entries Before ~64KB | Permissionless Append? | Risk | |---------------|-----------|-------------------|----------------------------|------------------------|------| | {key} | {Vec/Map} | YES/NO | {estimate} | YES/NO | HIGH/MED/LOW |

Dangerous pattern: DataKey::AllUsers → Vec<Address> stored as a single Persistent entry. At ~32 bytes per Address, this hits ~64KB at ~2,000 entries.

Correct pattern: Variable DataKeys — one Persistent entry per user/item: DataKey::User(address) → UserData. This distributes data across unlimited entries with no single-entry size constraint.

Check for: Any Persistent storage key that stores a collection type (Vec<T>, Map<K,V>) where the collection grows with protocol usage (new users, new positions, new orders). If the append operation is permissionless or low-cost, flag as DoS risk (same severity as Instance storage DoS).

4. Archival Risk Assessment

Persistent entries that are not extended will eventually be archived by the network. Archived entries can be restored but this requires paying a fee and providing a Merkle proof — not a default user flow.

| DataKey | Persistent? | TTL Extended? | Archive Risk | Recovery Path Exists? | User Impact if Archived | |---------|------------|--------------|-------------|----------------------|------------------------| | {key} | YES/NO | YES/NO | HIGH/MED/LOW | YES/NO | {impact description} |

High-risk patterns:

• User positions/balances that are never TTL-extended → users who haven't interacted for ~17 days lose access until they (or someone) pays for restoration
• Protocol-owned accounts (liquidity pools, vaults) with no TTL extension mechanism → pool becomes inaccessible
• Admin key archived → protocol loses all admin capabilities

For each HIGH risk entry: verify whether the protocol documentation communicates archival risk to users and whether the smart contract itself provides a restore helper function.

5. Temporary Data Critical Assessment

Temporary storage is permanently deleted when it expires — there is no archival, no restoration, no recovery. Verify no critical value is stored as Temporary:

| DataKey | Temporary Storage? | Critical Value? | Deletion Impact | Finding? | |---------|-------------------|-----------------|----------------|---------| | {key} | YES/NO | YES/NO | {what is lost} | [SL-N] if critical + Temporary |

Critical values that MUST NOT use Temporary storage:

• Token balances or positions
• Locked/escrowed funds
• Governance votes or proposals
• Access control grants
• Any value that represents user funds or irreversible commitments

Acceptable Temporary storage uses:

• Price oracle observations with explicit expiry
• Short-lived authorization proofs (e.g., CLOB order validity windows)
• Rate-limiting counters that naturally reset
• Replay-protection nonces where expiry is intentional

6. Storage Key Collision

Soroban storage keys are arbitrary Val types. If the same key value is written to different storage types, they are separate entries (no collision). However, within the same storage type, key values must be unique across all uses.

| Storage Type | Key Values in Use | Any Duplicates? | Collision Impact | |-------------|------------------|----------------|-----------------| | Instance | {list DataKey variants} | YES/NO | {if YES: which keys collide and what is overwritten} | | Persistent | {list DataKey variants} | YES/NO | {if YES: which keys collide and what is overwritten} | | Temporary | {list DataKey variants} | YES/NO | {if YES: which keys collide and what is overwritten} |

Collision patterns to check:

• DataKey enum variants that serialize to the same byte representation (e.g., tuple variants with the same structure but different semantic meaning)
• Dynamic keys using (symbol, address) tuples where two different contexts could produce the same tuple
• Integer keys used across multiple logical namespaces without a discriminator prefix

Finding Template

**ID**: [SL-N]
**Severity**: [Critical if funds permanently lost, High if DoS/archival risk, Medium if config risk]
**Step Execution**: ✓1,2,3,4,5,6 | ✗(reasons) | ?(uncertain)
**Rules Applied**: [R8:✓/✗, R10:✓/✗, R14:✓/✗]
**Location**: src/{contract}.rs:LineN
**Title**: {DataKey} stored as {wrong type / missing TTL extension} — {impact}
**Description**: [Specific storage type misuse with the key, the type used, and why it is wrong]
**Impact**: [Permanent fund loss / contract DoS / config expiry / inaccessible protocol]

---

Step Execution Checklist (MANDATORY)

| Section | Required | Completed? | Notes | |---------|----------|------------|-------| | 1. Storage Type Audit | YES | ✓/✗/? | Every DataKey variant | | 2. TTL Management | YES | ✓/✗/? | Every Persistent and Instance key | | 3. Instance Storage Bounds | YES | ✓/✗/? | All collections in Instance storage | | 4. Archival Risk Assessment | YES | ✓/✗/? | All Persistent keys without TTL extension | | 5. Temporary Data Critical Assessment | YES | ✓/✗/? | All Temporary keys | | 6. Storage Key Collision | YES | ✓/✗/? | All DataKey variants per storage type |