Migration Analysis

Skill: MIGRATION_ANALYSIS

Trigger: Protocol has migration patterns (reinitialize, V2/V3, deprecated, upgrade, legacy, Coin-to-FA) Covers: Token type mismatches, stranded assets, interface incompatibilities, module upgrade safety Required: YES when MIGRATION flag detected

Aptos Migration Context

Aptos modules are upgradeable by default under the compatible upgrade policy. Key differences from EVM:

• Module upgrades are in-place (same address, same module name)
• Resources in global storage persist across upgrades unchanged
• New functions can be added; existing public function signatures must remain compatible
• Storage layout must be compatible: new fields only at end of structs, existing fields unchanged
• immutable policy freezes module permanently; compatible allows additive changes
• The Coin<T> to FungibleAsset migration is a major ecosystem-wide transition

Trigger Patterns

V2|V3|_deprecated|migrat|upgrade|legacy|old_token|new_token|coin_to_fungible|fungible_asset_to_coin|reinitialize

Reasoning Template

Step 1: Identify Token Transitions

Find all token migration patterns:

• Coin<T> to FungibleAsset migration (ecosystem-wide)
• Legacy module interfaces still referenced
• Deprecated functions still callable
• V1 -> V2 module patterns within the protocol

For each transition:

Step 2: Check Interface Compatibility

For each external call that involves migrated tokens or upgraded modules:

1. What type does the CALLER expect? (Coin<T> or FungibleAsset or Object<Metadata>)
2. What type does the CALLEE actually return/accept?
3. Are they the same?
4. Has the external module upgraded to use a different standard?

// Example mismatch:
// Protocol still uses Coin<USDC>
public fun deposit(coin: Coin<USDC>) { ... }
// But external DEX now returns FungibleAsset
public fun swap(...): FungibleAsset { ... }
// Mismatch: protocol receives FA but expects Coin

Aptos-specific: Check if external modules have migrated from coin to primary_fungible_store while the protocol still uses the coin interface. The aptos_framework provides automatic pairing between Coin<T> and its corresponding FungibleAsset, but this pairing has edge cases.

Step 3: Trace Token Flow Paths

For each function that interacts with migrated tokens:

1. Entry point: What token standard does the user provide?
2. Internal flow: What standard does the protocol track internally?
3. External call: What standard does the external module expect?
4. Return value: What standard is returned?

Step 3b: External Side Effect Token Compatibility

When migration changes token types or interaction patterns, check whether external call side effects produce tokens that the current logic handles correctly.

For each external call that returns tokens or triggers side effects:

Pattern: Migration changes the primary token standard (e.g., Coin -> FA), but external modules still return the old standard as rewards, receipts, or side effects. The new logic may not handle the old token type.

Check: For each external dependency, does the post-migration logic correctly handle ALL token types that external calls can produce -- including legacy types from pre-migration interactions still in flight?

Step 3c: Pre-Upgrade Resource Inventory

Before analyzing stranded asset paths, inventory what resources CURRENTLY EXIST in global storage:

Pattern: Upgrade changes which token standard the protocol uses, but global storage still holds resources from pre-upgrade operations. If the new logic only handles FungibleAsset, Coin<T> balances at user addresses are stranded.

Check: For every resource type the protocol can create pre-upgrade:

1. Does the post-upgrade logic reference this resource type?
2. Is there a migration or sweep function that covers it?
3. If NEITHER -> STRANDED ASSET FINDING (apply Rule 9 severity floor)

Step 4: Stranded Asset Analysis (Exhaustive)

CRITICAL: This step uses exhaustive methodology. Every sub-step is MANDATORY.

4a. Asset Inventory by Era

List ALL assets the protocol handles, categorized by migration era:

Rule: If V1 Entry exists but V2 Exit does not handle V1 state -> potential stranding

4b. Cross-Era Path Matrix

For EACH asset and EACH possible state combination:

Aptos-specific: Under compatible upgrade policy, public functions cannot be removed -- only new functions can be added. However, the function logic CAN change. A V1 function that previously handled Coin<T> might be updated to expect FungibleAsset internally, breaking for users with V1 state.

STRANDING RULE: If ALL exit paths = N for any state -> STRANDED ASSETS FINDING

4c. Recovery Function Inventory

Document ALL functions that could recover stranded assets:

Question: Is there a recovery path for EVERY stranding scenario in 4b?

4d. Worst-Case Scenarios (MANDATORY)

Model these specific scenarios with code traces:

Scenario 1: V1 Deposit + V2 Logic

State: User deposited via V1 function, CoinStore<T> has balance
Event: Protocol upgraded to V2 (now uses FungibleAsset internally)
Question: Can user withdraw via V2 withdraw()?
Trace: [document code path -- does V2 read CoinStore or only FungibleStore?]
Result: [SUCCESS/STRANDED + amount]

Scenario 2: Resource Persistence After Upgrade

State: Custom resource R published at user address by V1 logic
Event: V2 module changes struct R layout (adds new field at end)
Question: Can V2 functions read/use the old R?
Trace: [compatible upgrade -- struct deserialization with new fields defaulting]
Result: [SUCCESS/ABORT + which functions break]

Scenario 3: Paired Coin/FA Migration

State: Protocol has Coin<T> and paired FungibleAsset for same underlying
Event: External module migrates to FA only, stops accepting Coin<T>
Question: Can protocol still interact with external module?
Trace: [does protocol auto-convert via coin::coin_to_fungible_asset?]
Result: [SUCCESS/STRANDED + which paths break]

4e. Step 4 Completion Checklist

• 4a: ALL assets inventoried with entry/exit paths per era
• 4b: Cross-era path matrix completed for all state combinations
• 4c: Recovery functions enumerated with limitations
• 4d: All three worst-case scenarios modeled with code traces
• For EVERY stranding possibility: recovery path exists OR finding created

Step Execution Output: check4a,4b,4c,4d,4e or ?4X(incomplete reason)