/migration-analysis

name: "migration-analysis"
description: "Trigger Protocol has migration patterns (reinitialize, V2/V3, deprecated, upgrade, legacy, Coin-to-FA) - Covers Token type mismatches, stranded assets, interface incompatibiliti..."

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:

| Old Standard/Type | New Standard/Type | Migration Function | Bidirectional? | Framework Support? | |-------------------|-------------------|-------------------|----------------|-------------------| | Coin<CoinType> | FungibleAsset | coin::coin_to_fungible_asset | YES (coin::fungible_asset_to_coin) | aptos_framework | | ModuleV1::Resource | ModuleV2::Resource | custom migrate() | {YES/NO} | N/A |

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?

| Function | User Provides | Protocol Tracks | External Expects | Mismatch? | |----------|---------------|-----------------|------------------|-----------|

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:

| External Call | Pre-Migration Side Effect | Post-Migration Side Effect | Logic Handles Both? | Mismatch? | |---------------|--------------------------|---------------------------|---------------------|-----------| | {ext_call} | Returns Coin<T> | Returns FungibleAsset | YES/NO | {describe} |

**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:

| Resource Type | Published At | How It Arrived | Post-Upgrade Logic Handles? | Exit Path Post-Upgrade? | |---------------|-------------|---------------|----------------------------|------------------------| | Coin<T> store | User addresses | User deposits via coin::register + deposit | YES/NO | {function or NONE} | | FungibleStore | Object addresses | primary_fungible_store::deposit | YES/NO | {function or NONE} | | Custom resource | @protocol | Module initialization | YES/NO | {function or NONE} |

**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:

| Asset | V1 Entry Path | V2 Entry Path | V1 Exit Path | V2 Exit Path | |-------|---------------|---------------|--------------|--------------| | Coin<T> balance | deposit_coin() | N/A (removed) | withdraw