migration-analysis

name	migration-analysis
description	Trigger Pattern Program upgrades, account data layout changes, deprecated instructions, token migrations - Inject Into Breadth agents, depth-state-trace

Skill: Migration Analysis (Solana)

Trigger Pattern: Program upgrades, account data layout changes, deprecated instructions, token migrations Inject Into: Breadth agents, depth-state-trace Finding prefix: [MG-N] Rules referenced: S1, S3, S4, S9, R4, R9, R10

upgrade|authority|reinitialize|deprecated|migrat|legacy|v2|V2|old_mint|new_mint|
BPFLoaderUpgradeable|set_authority|close_account

Reasoning Template

Step 1: Identify Token and Account Transitions

Find all migration patterns:

• Old mint -> New mint (SPL Token migrations, token rebranding, Token-2022 migration)
• Deprecated instructions still callable
• Account data layout changes across program versions
• PDA seed schema changes

For each transition:

Old Entity	New Entity	Migration Instruction	Bidirectional?	Account Type

Step 2: Check Account Data Layout Compatibility

For each program upgrade that changes account data structures:

1. What fields exist in the OLD account data layout?
2. What fields exist in the NEW account data layout?
3. Are new fields APPENDED (safe) or INSERTED/REORDERED (breaking)?
4. Does the discriminator change between versions? (Anchor uses first 8 bytes)

// Example mismatch:
// V1 layout: [discriminator(8)][authority(32)][amount(8)]  = 48 bytes
// V2 layout: [discriminator(8)][authority(32)][new_field(8)][amount(8)] = 56 bytes
// BREAKING: V1 accounts read `amount` at offset 40, but V2 expects it at offset 48

Account Type	V1 Layout (fields + offsets)	V2 Layout (fields + offsets)	Compatible?	Migration Path

Step 3: Trace Account Flow Paths

For each instruction that interacts with migrated accounts:

1. Entry point: What account data version does the user provide?
2. Internal flow: What version does the program expect?
3. CPI calls: What version do CPI target programs expect?
4. Return data: What version does the program write back?

Instruction	Account Expected	Actual Account Version	CPI Target Expects	Mismatch?

Step 3b: CPI Side Effect Compatibility

When migration changes program behavior, check whether CPI callers handle the changes:

CPI Call	Pre-Migration Behavior	Post-Migration Behavior	Caller Handles Both?	Mismatch?

Pattern: Program upgrade changes return data or account mutations from a CPI, but callers were written for the old behavior. After upgrade, CPI results are misinterpreted.

Step 3c: Pre-Upgrade Account Inventory

Before analyzing stranded asset paths, inventory all accounts the program owns:

Account Type	How Created	Current Lamports/Tokens	Post-Upgrade Logic Handles?	Close Path Post-Upgrade?
{pda_vault}	PDA init	SOL + SPL tokens	YES/NO	{instruction or NONE}
{user_state}	User init	Rent-exempt SOL	YES/NO	{instruction or NONE}
{legacy_acct}	V1 init	Held from V1 ops	YES/NO	{instruction or NONE}

Pattern: Upgrade changes which accounts the program reads/writes, but old accounts still hold SOL (rent) and tokens. If new logic cannot close or drain old accounts, assets are stranded.

Step 4: Stranded Asset Analysis (ENHANCED)

4a. Asset Inventory by Era

Asset/Account	V1 Creation Path	V2 Creation Path	V1 Close Path	V2 Close Path
{pda_vault}	initialize()	initialize_v2()	close_vault()	close_vault_v2()
{user_account}	create_user()	create_user()	close_user()	close_user()

Rule: If V1 Creation exists but V2 Close doesn't handle V1 state -> potential stranding.

4b. Cross-Era Path Matrix

Account Era	State Condition	Available Close/Drain Paths	Works?	Reason
V1 PDA vault	V2 program deployed	close_vault_v2()	Y/N	{why}
V1 PDA vault	V1 instruction removed	close_vault()	Y/N	{why}
V1 user state	In-flight during upgrade	???	Y/N	{why}

STRANDING RULE: If ALL close/drain paths fail for any account state -> STRANDED ASSETS FINDING

4c. Recovery Function Inventory

Function	Who Can Call	What Accounts Can Recover	Limitations
close_account()	Authority only	Program-owned accounts	Requires active authority
migrate_v1()	Any user	V1 user accounts	One-time per account
sweep_lamports()	Authority	Unclaimed rent	Cannot recover user deposits

4d. Worst-Case Scenarios (MANDATORY)

Scenario 1: V1 Account + V2 Program

State: User created account via V1 initialize() with deposited tokens
Event: Program upgraded to V2 with new data layout
Question: Can user close/withdraw via V2 instructions?
Trace: [document instruction path and deserialization]
Result: [SUCCESS/STRANDED + amount]

Scenario 2: In-Flight During Upgrade

State: User initiated multi-instruction operation (e.g., unstake request) at slot N
Event: Program upgrade deployed at slot N+1
Question: Can user complete operation at slot N+2?
Trace: [document instruction path]
Result: [SUCCESS/STRANDED + amount]

Scenario 3: PDA Seed Change

State: PDA derived with seeds [b"vault", user.key()] in V1
Event: V2 changes seeds to [b"vault_v2", user.key()]
Question: Can V2 program access the V1 PDA? Are V1 tokens recoverable?
Trace: [document PDA derivation and account lookup]
Result: [SUCCESS/STRANDED + amount]

4e. Step 4 Completion Checklist

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

Step 4f: User-Blocks-Admin Scenarios

Admin/Migration Instruction	Precondition Required	User Action That Blocks It	Timing Window	Severity
{admin_ix}	{precondition}	{user_action}	{window}	{assess}

Solana-specific patterns:

• User creates token accounts owned by program PDA -> non-zero balance prevents PDA closure
• User initiates pending operations (unstake, withdrawal request) -> in-flight state blocks migration
• User creates many small accounts -> iteration over accounts exceeds CU limit for admin migration instruction

Step 5: Upgrade Authority Lifecycle

Check	Status	Evidence
Upgrade authority identified?	{pubkey or multisig}	{source location}
Is authority a multisig (Squads)?	YES/NO
Can authority be revoked (program made immutable)?	YES/NO
If revoked: are all config parameters frozen?	YES/NO
If revoked: can stranded assets be recovered?	YES/NO	Apply Rule 9
Buffer validation during upgrade?	YES/NO	Can malicious buffer be substituted?
IDL discriminator stability?	YES/NO	Changed discriminators break all callers

Step 6: Downstream Integration Compatibility

Program Change	Downstream Consumer	Expected Interface	Post-Migration Actual	Breaking?
{change}	CPI callers	{expected IDL}	{actual IDL}	YES/NO
{change}	Indexers (Geyser, Helius)	{expected account layout}	{actual layout}	YES/NO
{change}	Frontend/SDK	{expected instruction format}	{actual}	YES/NO

Pattern: Program upgrade changes instruction discriminators, account layouts, or CPI behavior, but downstream consumers (other programs calling via CPI, indexers, SDKs) were built for the old interface.

Key Questions (Must Answer All)

1. Data Layout: Are ALL existing accounts readable by the new program version?
2. PDA Stability: Do ALL PDAs remain derivable with the same seeds after upgrade?
3. Migration Completeness: Can ALL V1 accounts be migrated/closed via V2 paths?
4. Stranded Assets: Is there any combination of (old_account_state + new_program) that traps funds?
5. Authority Lifecycle: Is the upgrade authority appropriately secured and revocable?

Common False Positives

1. Append-only layout changes: New fields added at end with defaults -- backward compatible
2. Versioned deserialization: Program explicitly handles both V1 and V2 layouts
3. Admin-controlled migration: Stranded accounts recoverable via authority instructions

Finding Template

**ID**: [MG-N]
**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: (see checklist below)
**Rules Applied**: [S1:___, S3:___, S4:___, S9:___, R4:___, R9:___, R10:___]
**Severity**: Critical/High/Medium/Low/Info
**Location**: programs/{program}/src/{file}.rs:LineN

**Account Transition**:
- Old: {old_layout/mint/PDA}
- New: {new_layout/mint/PDA}
- Mismatch Point: {where layouts/seeds diverge}

**Description**: {what is wrong}
**Impact**: {stranded funds, corrupted state, broken CPI callers}
**Evidence**: {code showing mismatch}

---

Step Execution Checklist (MANDATORY)

Step	Required	Completed?	Notes
1. Identify Token and Account Transitions	YES
2. Check Account Data Layout Compatibility	YES
3. Trace Account Flow Paths	YES
3b. CPI Side Effect Compatibility	YES
3c. Pre-Upgrade Account Inventory	YES
4. Stranded Asset Analysis (4a-4e)	YES
4f. User-Blocks-Admin Scenarios	YES
5. Upgrade Authority Lifecycle	YES
6. Downstream Integration Compatibility	YES

If any step skipped, document valid reason (N/A, immutable program, single version, no CPI callers).