Migration Analysis

Skill: Migration Analysis (Sui)

Trigger Pattern: Package upgrades, version transitions, deprecated functions, object layout changes Inject Into: Breadth agents, depth-state-trace Finding prefix: [MG-N] Rules referenced: R4, R8, R9, R10, R13

upgrade|UpgradeCap|UpgradeTicket|version|v2|V2|deprecated|migrat|legacy|old_coin|new_coin|
compatible|additive|dependency_only|package::authorize_upgrade

Sui packages are immutable once published. "Upgrades" create new package versions at new addresses via the UpgradeCap mechanism. Old objects may reference old package versions, and mixed-version state is a primary Sui migration concern. Unlike EVM proxy upgrades where old code is replaced, Sui old package code remains callable forever.

Step 1: Identify Token Transitions

Find all token/object migration patterns:

• Old Coin<OldType> -> New Coin<NewType> (token rebranding, coin type changes)
• Old object layouts -> New object layouts (fields added via upgrade)
• Deprecated functions still callable via old package version
• Shared objects created by V1 that must work with V2 functions

For each transition:

Sui-specific check: Is this a true package upgrade (same package lineage via UpgradeCap) or a separate package deployment (new address, no lineage)? True upgrades maintain type compatibility; separate deployments create entirely new types -- pkg_v1::module::Type != pkg_v2::module::Type.

Step 2: Check Interface Compatibility

For each function in the new package version interacting with existing objects:

1. What fields does the OLD object layout have?
2. What fields does the NEW version's functions expect?
3. Are new fields appended (compatible upgrade) or does the layout change (breaking)?
4. Does the struct definition change in a way that breaks compatible upgrade rules?

// Example: V1 object layout
struct Pool has key, store {
    id: UID,
    balance: Balance<SUI>,
    fee_bps: u64,
}
// V2 cannot change this layout under `compatible` policy.
// New fields require a new struct or dynamic fields.

Sui upgrade compatibility rules:

• compatible: Can change function implementations, add new functions, add new types. CANNOT change existing struct layouts, remove public functions, or change function signatures.
• additive: Can only add new modules/functions. Cannot change existing code.
• dependency_only: Can only change dependency versions.
• immutable: No changes possible (UpgradeCap destroyed).

Step 3: Trace Token Flow Paths

For each function that interacts with migrated tokens/objects:

1. Entry point: What object version does the user provide?
2. Internal flow: What version does the protocol logic expect?
3. External call: What version do external packages expect?
4. Return value: What version is returned?

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

Step 3b: External Side Effect Compatibility

When migration changes token types or interaction patterns, check whether external package side effects produce tokens/objects the current logic handles:

Pattern: Migration changes the primary coin type (e.g., V1 -> V2), but external packages still return the old type as rewards or receipts.

Step 3c: Pre-Upgrade Object Inventory

Before analyzing stranded asset paths, inventory what shared objects and owned objects exist on-chain:

Sui-specific: Unlike EVM where contract storage persists across upgrades, Sui objects are typed. If a new package is published (not a lineage upgrade), V1 objects CANNOT be read by new package functions because the types differ.

Step 4: Stranded Asset Analysis (ENHANCED)

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

4a. Asset Inventory by Version

Rule: If V1 Entry exists but V2 Exit doesn't handle V1-created objects -> potential stranding.

Sui-specific: Shared objects persist across compatible upgrades. For new package publications (not upgrades), the type is a DIFFERENT type even if structurally identical.

4b. Cross-Version Path Matrix

STRANDING RULE: If ALL exit paths = N for any object state -> STRANDED ASSETS FINDING (apply Rule 9: minimum MEDIUM)

4c. Recovery Function Inventory

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

4d. Worst-Case Scenarios (MANDATORY)

Scenario 1: V1 Object + V2 Package (Compatible Upgrade)

State: User holds Receipt object created by V1 package
Event: Package upgraded to V2 via compatible upgrade
Question: Can user call V2 redeem() with V1 Receipt?
Trace: [document type compatibility and field access]
Result: [SUCCESS/STRANDED + amount]

Scenario 2: V1 Object + New Package (Non-Upgrade Publication)

State: User holds Receipt<OldPackage::COIN> object
Event: Protocol publishes new package at new address
Question: Can user interact with new package using old object?
Trace: [OldPackage::Receipt != NewPackage::Receipt -- different types]
Result: [STRANDED unless explicit migration exists]

Scenario 3: Old Package Bypass After Upgrade

State: Protocol upgrades to V2 with new security checks
Event: Attacker calls V1 functions on shared objects
Question: Do V1 functions bypass V2 security checks?
Trace: [document old function code path]
Result: [SAFE/BYPASS POSSIBLE]

Scenario 4: Dynamic Field Key Type Mismatch

State: Objects have dynamic fields with V1 key types
Event: V2 changes key type or field structure
Question: Can V2 code read/remove V1-era dynamic fields?
Trace: [document dynamic field access path]
Result: [SUCCESS/STRANDED + orphaned dynamic fields]