# User Guide

The Migrate.Fun Platform enables token holders to migrate from an old token to a new token seamlessly. Users receive Migration Fungible Tokens (MFT) as receipts during migration, which can be redeemed for new tokens after the migration period ends.

#### Key Concepts

* **Old Token**: Your current token that you want to migrate from
* **New Token**: The updated token you'll receive after migration
* **MFT (MigrateFun Receipt Token)**: Receipt tokens that prove your migration
* **Exchange Rate**: How many new tokens you receive per old token
* **Claims Period**: 90-day window to claim tokens after migration

#### User Journey Overview

<figure><img src="https://4286468624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOgRfdaiR7s4iruXoVU9%2Fuploads%2FXOjLZpq3UcqTtQ8nYzSS%2FScreenshot%202025-12-17%20at%209.31.24%E2%80%AFAM.png?alt=media&#x26;token=95ff73e2-35e5-48e4-81c8-388974f8bd44" alt=""><figcaption></figcaption></figure>

### Migration Phases

#### Phase 1: Active Migration Period

**Duration**: Set by project admin (typically 7-30 days)

**What You Can Do**:

* Migrate old tokens to receive MFT receipts
* View migration progress and statistics via details page
* Check your balances and entitlements in your self-custodial wallet

**What You Cannot Do**:

* Claim new tokens (must wait for migration to end)
* Get refunds (unless migration fails)

#### Phase 2: Post-Migration Claims

**Duration**: 90 days after migration ends

**What You Can Do**:

* Burn MFT to claim new tokens (1:1)
* Claim via merkle proof if you missed migration (late claims window)
* Check claim status and history

**What You Cannot Do**:

* Migrate more old tokens
* Get refunds (unless protected migration failed)

#### Phase 3: Expired Period

**After**: 90 days post-migration

**What Happens**:

* Claims no longer available
* Unclaimed tokens returned to project admin
* Must contact project directly for resolution

### Pre-Migration Preparation

#### Step 1: Check Eligibility

**Requirements**

* Hold old tokens in your wallet
* Have sufficient SOL for transaction fees (\~0.01 SOL)
* Wallet connected to the migratefun platform

**Verify Project Details**

1. Navigate to migration platform
2. Find your project in the list
3. Check:
   * Migration dates (start and end)
   * Exchange rate
   * Fee percentage
   * Protection status
   * Token info (CA, Pool ID)&#x20;

#### Step 2: Prepare Your Wallet

**Supported Wallets**

* Phantom
* Solflare
* MetaMask
* Other Solana-compatible wallets via Walletconnect

**Wallet Setup**

1. Ensure wallet has old tokens
2. Add at least 0.02 SOL for fees

#### Step 3: Understand the Exchange Rate

**How It Works**

* **Exchange Rate**: Displayed as ratio (e.g., 1.5:1)
* **Calculation**: `new_tokens = old_tokens × exchange_rate`

<figure><img src="https://4286468624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOgRfdaiR7s4iruXoVU9%2Fuploads%2FZUrHr8xYE9UriHPOTUD7%2FScreenshot%202025-12-17%20at%209.33.21%E2%80%AFAM.png?alt=media&#x26;token=59657ed9-240c-4a90-81fc-1869a94b109d" alt=""><figcaption></figcaption></figure>

### During Migration

#### Step 1: Connect to Platform

1. **Navigate to Migration Panel**
   * Go to platform URL
   * Click "Migration" tab
2. **Connect Wallet**
   * Click "Connect Wallet"
   * Select your wallet provider
   * Approve connection

#### Step 2: Select Project

1. **View Available Projects**
   * Shows all active migrations
   * Filter by token name, time, progress&#x20;
2. **Select Your Project**
   * Click on project card
   * Review project details
   * Verify token addresses match

#### Step 3: Migrate Tokens

**Enter Amount**

1. **Check Your Balance**
   * Display shows available old tokens
   * "Max" button for full migration
2. **Enter Migration Amount**
   * Type amount or use percentage buttons
   * Preview shows MFT you'll receive
   * Check fee information

**Execute Migration**

1. **Click "Migrate"**
   * Review transaction details
   * Approve in wallet
   * Wait for confirmation
2. **Transaction Process**
   * Old tokens transferred to vault
   * MFT tokens minted to your wallet
   * UserMigration record created

**Post-Migration Verification**

1. **Check MFT Balance**
   * MFT balance updated immediately
   * Shows in wallet token list
2. **View Migration Record**
   * Transaction history updated
   * Migration stats displayed

#### Step 4: Multiple Migrations

You can migrate multiple times during the active period:

1. **Partial Migrations**
   * Migrate portions at different times
   * All migrations accumulate
   * Single UserMigration record tracks total
2. **Benefits**

   * Test with small amount first
   * Dollar-cost average entry
   * Flexibility in timing

   ### Post-Migration Claims

#### When Claims Begin

Claims are available immediately after:

1. Migration period ends
2. MerkleTree snapshot is taken
3. Admin finalizes swap
4. Pool creation completes
5. Claims are enabled

#### Step 1: Access Claims Panel

1. **Navigate to Platform**
   * Connect wallet
   * Go to "Claims" section
2. **Select Project**
   * Find your migration project
   * Click to view details
   * Choose claim tokens

#### Step 2: Claim with MFT

**Process Overview**

1. **Check MFT Balance**
   * Shows total MFT held
   * Preview new tokens to receive
2. **Enter Claim Amount**
   * Partial or full claims allowed
   * 1:1 exchange (1 MFT = 1 new token)
3. **Execute Claim**

<figure><img src="https://4286468624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOgRfdaiR7s4iruXoVU9%2Fuploads%2F1jGuRUrDUinK3ZK2a9uA%2FScreenshot%202025-12-17%20at%209.35.42%E2%80%AFAM.png?alt=media&#x26;token=1ffd05ba-edb9-4cbe-8bed-b9d14394e255" alt=""><figcaption></figcaption></figure>

**Technical Details**

* **Smart Contract**: `claim_with_mft.rs`
* **MFT Burning**: Permanent and irreversible
* **New Token Transfer**: From project vault to your wallet
* **Gas Fees**: \~0.005 SOL per claim

#### Step 3: Verify Receipt

1. **Check Balances**
   * New token balance increased
   * MFT balance decreased
   * Transaction in history
2. **Add Token to Wallet**
   * Copy new token mint address
   * Add custom token in wallet
   * Icon and metadata appear

## Merkle Tree Claims

For users who missed the migration deadline, claims via merkle tree are available for 90 days.

#### Eligibility

You're eligible if:

* Held old tokens at snapshot time
* Didn't migrate during active period
* Within 90-day claims window
* Project created merkle tree

#### Step 1: Check Eligibility

1. **Access Claims Panel**
   * Navigate to MerkleClaims ceck
   * Enter wallet address
   * System checks eligibility
2. **View Claim Amount**
   * Shows snapshot balance
   * Applies any penalty rate
   * Displays claimable amount

#### Step 2: Generate Proof

1. **Automatic Generation**
   * Click "Generate Proof"
   * Backend creates merkle proof
   * Proof data displayed
2. **Proof Components**

<figure><img src="https://4286468624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOgRfdaiR7s4iruXoVU9%2Fuploads%2FQJ0nCqyqnxvd4hEZg3oP%2FScreenshot%202025-12-17%20at%209.37.29%E2%80%AFAM.png?alt=media&#x26;token=ad04a0c6-65e3-4c34-a152-3980d25b7f1b" alt=""><figcaption></figcaption></figure>

#### Step 3: Claim Tokens

**Standard Merkle Claim**

1. **Requirements**
   * Still hold old tokens (full or partial)
   * Valid merkle proof
   * Within claim period
2. **Process**

<figure><img src="https://4286468624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOgRfdaiR7s4iruXoVU9%2Fuploads%2FW4r9QdhbvmizYyYCH0O0%2FScreenshot%202025-12-17%20at%209.38.17%E2%80%AFAM.png?alt=media&#x26;token=f5709096-71b8-4f44-9605-da662e7ebd7e" alt=""><figcaption></figcaption></figure>

* Can claim up to snapshot amount
* Must have old tokens to exchange
* Proportional claiming allowed
* Single claim allowance (no exceptions)

**Penalty Rates**

* Admin may set penalty (0-100%)
* Encourages timely migration
* Applied to claim amount
* Penalized tokens count towards unclaimed amount

#### Technical Flow

*Merkle claim process*

1. Verify merkle proof against root
2. Check user still holds old tokens
3. Calculate claimable = min(snapshot, balance)
4. Transfer old tokens to vault
5. Apply penalty if configured
6. Transfer new tokens to user
7. Record claim to prevent duplicates

### Protected Migration Refunds

#### Understanding Protected Migrations

**What Makes It Protected**

* Target percentage set (e.g., 25% must migrate)
* Automatic evaluation at deadline
* Refunds if target not met
* 90-day claims protection

#### Failed Migration Process

**Step 1: Automatic Evaluation**

At migration deadline:

1. System checks total migrated vs target
2. If below target: Migration marked failed
3. Notification sent to users

**Step 2: SOL Recovery**

Admin executes recovery:

1. Old tokens sold for SOL/USDC
2. Proceeds allocated to refund pool
3. Proportional shares calculated

#### Claiming Refunds

**Step 1: Access Refund Panel**

1. **Navigate to Platform**
   * Connect wallet
   * Go to "Refunds" section
2. **Check Eligibility**
   * Must have migrated tokens
   * Shows your migration amount
   * Displays refund share

**Step 2: Claim SOL Refund**

1. **Calculate Your Share**

<figure><img src="https://4286468624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCOgRfdaiR7s4iruXoVU9%2Fuploads%2FN6QPMESzFllAaPQKeuTP%2FScreenshot%202025-12-17%20at%209.41.31%E2%80%AFAM.png?alt=media&#x26;token=6303020f-1ab8-49e7-8234-f0013c13ae06" alt=""><figcaption></figcaption></figure>

1. **Execute Claim**
   * Click "Claim Refund"
   * SOL sent to wallet
   * One-time claim only

**Step 3: Verify Receipt**

* Check SOL balance increase
* Transaction confirmed
* Claim marked complete

### Troubleshooting

#### Common Issues

**"Insufficient Balance"**

**Cause**: Not enough old tokens or SOL **Solution**:

* Check token balance in wallet
* Add SOL for fees (0.02 SOL recommended)
* Verify correct token selected

**"Migration Window Closed"**

**Cause**: Outside active migration period **Solution**:

* Check migration dates
* Wait for claims period if migration ended
* Use merkle claims if available

**"Claims Not Enabled"**

**Cause**: Migration not finalized **Solution**:

* Wait for admin to finalize post-migration steps
* Check project status
* Contact project admin

**"Invalid Merkle Proof"**

**Cause**: Incorrect proof or not eligible **Solution**:

* Regenerate proof from backend
* Verify snapshot eligibility
* Check wallet address matches

**"Transaction Failed"**

**Cause**: Network congestion or slippage **Solution**:

* Retry transaction
* Increase priority fee
* Wait for less congestion

#### Wallet Issues

**Tokens Not Showing**

1. Add custom token:
   * Copy token mint address
   * Add to wallet token list
   * Refresh balance

**Transaction Stuck**

1. Cancel pending:
   * Open wallet
   * Find pending transaction
   * Cancel or speed up

**Connection Problems**

1. Reconnect wallet:

   * Disconnect from platform
   * Clear browser cache
   * Reconnect wallet

   ## Best Practices

#### For Users

1. **Before Migrating**
   * Verify project legitimacy
   * Check exchange rate and fees
   * Test with small amount first
2. **During Migration**
   * Double-check amounts
   * Save transaction IDs
   * Monitor for confirmation
3. **After Migration**
   * Claim promptly after period ends
   * Add new token to wallet
   * Keep records for taxes

#### Security Tips

1. **Wallet Safety**
   * Never share seed phrase
   * Use hardware wallet if possible
   * Verify transaction details
2. **Platform Verification**
   * Check official URLs
   * Verify contract addresses
   * Look for audits
3. **Transaction Safety**
   * Start with small amounts
   * Verify recipient addresses
   * Check network status