# 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
### 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)
#### 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`
### 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
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**
**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**
#### Step 3: Claim Tokens
**Standard Merkle Claim**
1. **Requirements**
* Still hold old tokens (full or partial)
* Valid merkle proof
* Within claim period
2. **Process**
* 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**
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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.emblem.wiki/migratefun/user-guide.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.