Migration Analysis

Skill: Migration Analysis (Soroban)

Trigger Pattern: Contract upgrades via update_current_contract_wasm, storage migration, deprecated functions, token migrations Inject Into: Breadth agents, depth-state-trace Finding prefix: [MG-N] Rules referenced: R4, R9, R10

update_current_contract_wasm|upgrade|migrate|deprecated|migrat|
legacy|v2|V2|old_token|new_token|storage_migration|DataKey::

Key Soroban difference from EVM: There is no proxy pattern (no delegatecall). There is no BPFLoaderUpgradeable (Solana model). Soroban contract upgrade uses env.deployer().update_current_contract_wasm(new_wasm_hash), which replaces the contract's WASM bytecode while preserving ALL storage in-place. The contract address and all storage entries survive the upgrade unchanged. This means:

1. Storage migration (if needed) must be performed manually — there is no automatic migration callback.
2. If the new WASM reads storage with a different key schema or different data type than what old WASM wrote, the reads will fail or silently return defaults.
3. Instance data, Persistent data, and Temporary data all persist through an upgrade — their TTLs continue ticking independently.

Step 1: Identify Upgrade and Migration Patterns

Find all upgrade-related patterns:

• update_current_contract_wasm calls (the actual WASM upgrade mechanism)
• Storage migration functions (functions that read old-format data and write new-format data)
• Deprecated functions still callable after upgrade
• Old storage key definitions that may conflict with new ones
• Token migrations (old Stellar classic asset → new SAC, or old custom token → new token)

For each transition:

Critical question for each upgrade entry point: Is the upgrade function properly access-controlled with require_auth(&admin_address)? An unprotected update_current_contract_wasm is a CRITICAL vulnerability allowing any caller to replace the contract with arbitrary WASM.

Step 2: Storage Schema Compatibility

For each upgrade that changes storage data structures:

1. What data keys and types exist in the OLD WASM?
2. What data keys and types exist in the NEW WASM?
3. Are new fields ADDED to a new key (safe) or do they REPLACE existing keys with different types (breaking)?
4. Does the new WASM attempt to deserialize old data with a new struct layout?

// Example mismatch:
// V1 storage: DataKey::VaultState -> VaultStateV1 { owner: Address, balance: i128 }
// V2 storage: DataKey::VaultState -> VaultStateV2 { owner: Address, balance: i128, fee_rate: u32 }
// BREAKING: V2 reads VaultStateV2 from key DataKey::VaultState,
//           but the stored bytes are VaultStateV1 — deserialization fails (trap) OR
//           interprets the trailing bytes of balance as fee_rate (silent corruption).

Soroban deserialization behavior on mismatch:

• If new struct has MORE fields than stored data has bytes: Soroban SDK will likely panic (trap) at runtime when deserializing.
• If new struct has FEWER fields: the extra stored bytes may be silently ignored (data loss).
• If field TYPES change (e.g., i128 → u64): deserialization may silently reinterpret bytes.

Check for each storage key: does V2 WASM read the same key as V1 WASM wrote? If both use the same key but different types, this is a migration hazard.

Step 3: Trace Storage Access Paths Through Upgrade

For each contract function that accesses upgraded storage:

1. Entry point: What storage key does the user-facing function read/write?
2. Internal flow: What data type does the function deserialize from that key?
3. External calls: What type do external contracts (invoke_contract) expect from this contract?
4. TTL: What storage class (Instance / Persistent / Temporary) holds the data, and is the TTL extended during migration?

Step 3b: External Contract Side Effect Compatibility

When the upgrade changes the contract's behavior, check whether external callers handle the changes:

Pattern: Contract upgrade changes function return values or events, but external contracts that call this contract via invoke_contract were written for the old interface. After upgrade, return values are misinterpreted by callers.

Step 3c: Pre-Upgrade Storage Inventory

Before analyzing stranded asset paths, inventory all storage entries the contract owns:

Pattern: Upgrade changes which storage keys the contract reads/writes, but old keys still hold value. If new logic cannot read or close old keys, assets associated with them are stranded.

Step 4: Stranded Asset Analysis

4a. Asset Inventory by Era

Rule: If V1 Write exists but V2 Withdraw does not handle V1 storage key/type -> potential stranding.

4b. Cross-Era Access Matrix

STRANDING RULE: If ALL withdraw/close paths fail for any storage state combination -> STRANDED ASSETS FINDING

4c. Recovery Function Inventory

4d. Worst-Case Scenarios (MANDATORY)

Scenario 1: V1 Storage + V2 WASM — No Migration Called

State: User has balance stored at DataKey::BalanceV1(user_address) in Persistent storage
Event: Contract upgraded to V2; V2 uses DataKey::BalanceV2(user_address)
Question: Can user withdraw via V2 withdraw() function?
Trace: [document storage key lookup and deserialization in V2 withdraw()]
Result: [SUCCESS / STRANDED + amount]

Scenario 2: In-Flight During Upgrade

State: User submitted a multi-step operation (e.g., unlock request) at ledger N
       Contract stores pending operation at DataKey::PendingOp(user_address)
Event: Contract upgraded at ledger N+1; V2 no longer reads DataKey::PendingOp
Question: Can user complete their operation at ledger N+2?
Trace: [document function path and storage access in V2]
Result: [SUCCESS / STRANDED + amount]

Scenario 3: Storage Key Renamed

State: V1 uses DataKey::Config for configuration struct ConfigV1
Event: V2 uses DataKey::Config for configuration struct ConfigV2 with additional fields
Question: Does V2 correctly read V1-written Config data?
Trace: [document deserialization: ConfigV2::from(stored_bytes) where stored_bytes is ConfigV1]
Result: [SUCCESS (if additive and defaults apply) / TRAP / SILENT_CORRUPTION]

Scenario 4: TTL Expiry During Migration Window

State: User's balance is in Persistent storage with a TTL set at V1 initialization
Event: Contract is upgraded; migration requires user to call migrate_user() within TTL window
Question: What happens if user does not call migrate_user() before TTL expires?
Trace: [document TTL of Persistent entries and whether upgrade extends TTLs]
Result: [DATA_WIPED_ON_EXPIRY / SAFE (TTL auto-extended by upgrade)]

4e. Step 4 Completion Checklist

• 4a: ALL storage keys inventoried with write/withdraw paths per era
• 4b: Cross-era access matrix completed for all state combinations
• 4c: Recovery functions enumerated with limitations
• 4d: All four worst-case scenarios modeled with traces
• For EVERY stranding possibility: recovery path exists OR finding created

Step 4f: User-Blocks-Admin Scenarios

Soroban-specific patterns:

• User has a large balance in old-format storage -> migration function must iterate over user entries, which may exceed compute budget if too many entries exist
• User calls a function that creates storage with the old key format after the upgrade announcement but before the actual upgrade (extends the "old format exists" window)
• User purposely extends TTL of old-format storage entries to prevent their expiry and the associated cleanup path

Step 5: Upgrade Authority Lifecycle

Step 6: Downstream Integration Compatibility

Pattern: Contract upgrade changes function signatures, argument types, or event structures, but downstream consumers built against the old interface continue to call the new WASM with old argument encoding — calls may trap (wrong arg count) or silently pass with misinterpreted arguments.

Soroban ABI note: Soroban functions are identified by their name (as a Symbol). There is no ABI checksum like EVM function selectors. An upgraded function with the same name but different argument types will accept the old call encoding, potentially silently misinterpreting arguments.

Key Questions (Must Answer All)

1. Storage Compatibility: Are ALL existing storage entries readable by the new WASM version?
2. Key Stability: Do ALL storage key definitions remain identical after upgrade?
3. Migration Completeness: Can ALL V1 storage entries be migrated or withdrawn via V2 paths?
4. Stranded Assets: Is there any combination of (old_storage_state + new_WASM) that traps user funds?
5. Authority Security: Is the upgrade function properly access-controlled and is the authority appropriately secured?
6. TTL Safety: Do storage entry TTLs survive the upgrade and migration window without expiry?

Common False Positives

1. Additive storage schema: New fields added with new keys, old keys still readable by V2 — backward compatible
2. Versioned deserialization: Contract explicitly handles both V1 and V2 data layouts via enum variants
3. Admin-controlled migration: Stranded accounts recoverable via authority-gated migration function
4. Atomic upgrade+migrate: If update_current_contract_wasm is called within the same function that writes migrated storage, the migration is effectively atomic

Finding Template

**ID**: [MG-N]
**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: (see checklist below)
**Rules Applied**: [R4:___, R9:___, R10:___]
**Severity**: Critical/High/Medium/Low/Info
**Location**: src/{file}.rs:LineN

**Storage Transition**:
- Old: {old_key / old_type / old_storage_class}
- New: {new_key / new_type / new_storage_class}
- Mismatch Point: {where key or type diverges}

**Description**: {what is wrong}
**Impact**: {stranded funds, corrupted state, bricked contract, broken callers}
**Evidence**: {code showing mismatch}

Step Execution Checklist (MANDATORY)

If any step skipped, document valid reason (N/A, no upgrade function, immutable contract, single version, no external callers).