Migration Analysis

Skill: MIGRATION_ANALYSIS

Trigger: Protocol has migration patterns (reinitializer, V2/V3, deprecated, upgrade, legacy) Covers: Token type mismatches, stranded assets, interface incompatibilities

Trigger Patterns

reinitializer|V2|V3|_deprecated|migrat|upgrade|legacy|oldToken|newToken

Reasoning Template

Step 1: Identify Token Transitions

Find all token migration patterns:

• Old token -> New token (e.g., USDC v1 -> v2, DAI -> sDAI, TokenV1 -> TokenV2)
• Legacy interfaces still referenced
• Deprecated functions still callable

For each transition: | Old Token | New Token | Migration Function | Bidirectional? |

Step 2: Check Interface Compatibility

For each external call that involves migrated tokens:

1. What token type does the CALLER expect?
2. What token type does the CALLEE actually return/accept?
3. Are they the same?

// Example mismatch:
interface IExternalProtocol {
    function deposit(address asset, uint256 amount) external returns (uint256);
    // Expects: canonical token
    // Actually returns: receipt token denominated in bridged variant?
}

Step 3: Trace Token Flow Paths

For each function that interacts with migrated tokens:

1. Entry point: What token does the user provide?
2. Internal flow: What token does the protocol track?
3. External call: What token does the external contract expect?
4. Return value: What token denomination 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:

Pattern: Migration changes the primary token (e.g., V1 -> V2), but external contracts still return the old token 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 Balance Inventory

Before analyzing stranded asset paths, inventory what the contract CURRENTLY HOLDS:

Pattern: Upgrade changes which token the protocol uses (V1 -> V2), but the contract still holds V1 tokens from pre-upgrade operations. If the new logic only handles V2, V1 balances are stranded.

Check: For every asset type the contract can hold pre-upgrade:

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

Step 4: Stranded Asset Analysis

CRITICAL: This step uses exhaustive methodology to ensure no stranded asset scenarios are missed. 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 doesn't handle V1 state -> potential stranding

4b. Cross-Era Path Matrix

For EACH asset and EACH possible state combination:

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 100 tokens via V1 deposit()
Event: Protocol upgraded to V2
Question: Can user withdraw via V2 withdraw()?
Trace: [document code path]
Result: [SUCCESS/STRANDED + amount]

Scenario 2: In-Flight During Upgrade

State: User initiated withdrawal at V1 block N
Event: Upgrade happened at block N+1
Question: Can user complete withdrawal at block N+2?
Trace: [document code path]
Result: [SUCCESS/STRANDED + amount]

Scenario 3: External Token Type Mismatch

State: Protocol received TokenA from external contract
Event: External contract now returns TokenB
Question: Can protocol process/withdraw TokenA?
Trace: [document code path]
Result: [SUCCESS/STRANDED + amount]

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: checkmark4a,4b,4c,4d,4e or ?4X(incomplete reason)

Step 5: External Call Token Verification

For each external call:

1. Read the PRODUCTION external contract (not mock)
2. Verify actual token type accepted/returned
3. Compare with what the protocol sends/expects

| External Contract | Function | Protocol Sends | Contract Expects | Match? |
|-------------------|----------|----------------|------------------|--------|
| ExternalPool | deposit | depositAsset | depositAsset | YES |
| ExternalPool | withdraw | receiptTokens | receiptTokens | YES |
| PriceOracle | getPrice | - | Returns USD or ETH? | VERIFY |