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