# Project Guide

### Overview

The Migrate.Fun Platform enables project administrators to migrate their community from an old token to a new token while automatically creating liquidity pools. This guide will walk you through the entire process.

#### Key Benefits

* ✅ Automated token migration
* ✅ Automatic liquidity pool creation
* ✅ Built-in security features
* ✅ Optional user protection mechanisms
* ✅ Support for multiple AMMs (Raydium, Meteora, PumpSwap)
* ✅ Support for multiple launchpads (Pumpfun, Bonkfun)

***

### Before You Begin

#### Prerequisites

**1. Existing Liquidity Pool**

You must have an existing liquidity pool containing your old token on one of these platforms:

* Raydium (v4, CPMM, bonk.fun)
* Meteora (DAMM v1, DAMM v2, believe)
* PumpSwap (pump.fun)

**2. New Token**

You need either:

* An existing new token mint address, OR
* Token details to create a new token (name, symbol, supply)

**3. Wallet Requirements**

* Sufficient SOL for:
  * Platform creation fee (at platform discretion)
  * Transaction fees (\~0.01 SOL)
  * Token creation (0.1 SOL-2 SOL pending migrating platform)
* New tokens for distribution (if using existing token)

**4. Planning Your Migration**

Decide on:

* **Migration dates**: Start and end times
* **Exchange rate**: How many new tokens per old token
* **Migration fee**: 5% of total liquidity migrated 
* **Protection type**: Unprotected (trust-based) or Protected (with safeguards)

***

### Step-by-Step Setup Guide

#### Step 1: Connect Your Wallet

1. Navigate to the migration platform
2. Click "Connect Wallet"
3. Choose your wallet (Phantom, Solflare, WalletConnect, etc.)
4. Approve connection

#### Step 2: Enter Your Pool Information

**Finding Your Pool ID**

1. Go to your DEX platform (Raydium/Meteora/PumpSwap)
2. Find your token's liquidity pool
3. Copy the pool address/ID

**In the Platform**

1. Paste your pool ID in the "Pool ID" field
2. Click "Fetch Pool Info"
3. Verify the detected tokens are correct
4. Select which token is the quote token (SOL, USDC, USD1)

#### Step 3: Configure Your New Token

**Option A: Create New Token**

1. Select "Create New Token"
2. Enter token details:
   * **Name**: Full token name (e.g., "Hustle Token")
   * **Symbol**: Token ticker (e.g., "HSTL")
   * **Supply**: Total supply (e.g., 1,000,000,000)
   * **Time Window:** Length of migration (e.g., 14 days)
   * **Penalty Rate:** Late claims ratio (e.g., 15%)
3. Click "Create Token"
4. Approve the transaction

**Option B: Use Existing Token**

1. Select "Use Existing Token"
2. Enter your new token mint address
3. The platform will verify the token exists

#### Step 4: Set Migration Parameters

**Basic Settings**

* **Project ID**: Unique identifier (Automatically assigned)
* **Project Name**: Display name (Automatically assigned)
* **Exchange Rate**: How many new tokens per 1 old token (if supply increase)
  * Example: 1.5 = users get 1.5 new tokens for each old token
  * Maximum: 1000x (1000 new per 1 old)

**Migration Period**

* **Start Date/Time**: When migration begins
  * Must be scheduled at least 5 minutes into the future
  * Cannot be scheduled in the past
* **End Date/Time**: When migration ends
  * Minimum: 5 minutes from start
  * Maximum: 365 days 
  * Recommended: 7-30 days

**Fees**

* **Platform Fee**: Fixed at 5% of total liquidity migrated
  * Automatically deducted from swap proceeds in quote token
  * Goes to platform treasury

#### Step 5: Choose Protection Level

**Unprotected Migration** 

* **For**: Established projects with community trust
* **Best When**: You have an established reputation
* **Used for:** Urgency required or participation levels are irrelevant

**Protected Migration (Default)**

Protected migrations ensure meaningful community participation before proceeding.

* **For**: New projects or those wanting extra security
* **Features**:
  * Set target migration percentage (5%-95%)
  * Automatic evaluation at deadline
  * Refunds in quote token if target not met
  * 90-day claim period protection
* **Admin Access**: Must wait 90 days OR get platform admin approval

**To Enable Protection:**

1. Check "Enable Protected Migration"
2. Set target percentage (e.g., 75% of supply must migrate)
3. Platform calculates target amount automatically

#### Step 6: Bonk.fun Migraton (Pre-migration)

If you want to split LP tokens with BONK.fun:

1. Check "Enable BONK.fun Integration"
2. The split is automatically set to:

   * Memes: 0.3% swap fee: 65% burned, 25% creator, 10% Bonkfun
   * Tech: 1.5% swap fee: 66% to creator, 33% to Bonkfun
   * These percentages are hardcoded and cannot be changed

   #### Step 7: Pump.fun Migration  (Post-migration)

   When deploying on bonding curve

   1. Choose deploy (Create, bond, and graduate)
   2. SOL is deployed to bonding curve
      * 85 SOL buyout of bonding curve
      * Successive purchases using additional SOL
      * Goal to meet target market cap
      * Combination of onchain tools and sniper protection used

#### Step 7: Review and Create

1. Review all settings carefully
2. Check estimated costs:
   * Platform fee
   * Gas fees
   * Token creation (if applicable)
3. Click "Create Migration Project"
4. Approve all transactions in your wallet

#### Step 8: Deposit New Tokens

After project creation:

1. You'll be prompted to deposit new tokens
2. Enter the amount to deposit
   * Must cover all potential migrations
   * Formula: `old_token_supply × exchange_rate`
3. Approve token transfer
4. Click "Deposit Tokens"

#### Step 9: Initialize Project

Final step to activate:

1. Click "Initialize Project"
2. This will:
   * Create MFT (receipt) token
   * Activate the migration
   * Start accepting user migrations

***

### Migration Types

#### Standard Migration

* Users migrate at will during the period
* Receive MFT tokens as receipts
* Can claim new tokens after migration ends

#### Percentage-Based Migration (Protected)

* Has a target percentage goal
* Evaluated at deadline
* If successful: Proceeds to pool creation
* If failed: Users get refunds

#### BONK.fun Enhanced Migration

* Creates pool with specified fee settings (hardcoded)
* Bonk.fun gets respective share of LP tokens 
* Project admin receives specified share of LP tokens
* Both portions locked via NFTs
* Split percentages and recipient address are hardcoded for security

***

### Managing Your Migration

#### During Migration Period

**Monitor Progress**

* Check dashboard for:
  * Total migrated
  * Number of participants
  * Time remaining
  * Current percentage (if protected)

**Pause/Resume (If Needed)**

* Project admin can pause migration if issues arise
* Platform admin can provide support in emergency situations

**Communication**

* Consistent communication from official and team memeber channels
* Share migration and details link
* Keep community information
* Post regular updates

#### After Migration Ends

**Finalize Swap**

Once migration period ends:

1. Navigate to your project dashboard
2. Click "Finalize Swap"
3. Set slippage tolerance (usually 0.5-1%)
4. This will:
   * Sell collected old tokens for SOL/USDC/USD1
   * Create new liquidity pool
   * Lock LP tokens in streamflow for 30 days (Raydium)
   * Lock LP NFT in vesting contract for 30 days (Meteora)
   * Lock LP tokens via Raydium Locker, permanently (Bonkfun)
   * Burns LP tokens via controlled account, permanently  (Pumpswap) 

**Pool Creation Options**

* **Raydium**: Creates CPMM pool
* **Meteora:** Creates DAMM v2 pool
* **Bonk.fun**: Creates Raydium CPMM with split LP tokens
* **Pump.fun:** Creates pumpswap AMM with dynamic fee system

***

### Post-Migration Actions

#### Admin Dashboard Overview

The Admin Panel provides comprehensive control over your migration project through various stages:

**Available Actions by Stage**

1. **After Project Creation**
   * **Deposit New Tokens**: Fund the migration with new tokens
   * **Initialize Project**: Activate the migration to start accepting users
2. **During Migration Period**
   * **Monitor Progress**: View real-time migration statistics
   * **Track Participants**: See number of users who have migrated
   * **View Remaining Time**: Countdown to migration end
3. **After Migration Ends**

* **Create Merkle Tree**: Set up claims for non-migrators
* **Finalize Swap**: Execute market sell and create liquidity pool
* **Deploy Liquidity Pool:** Set price per token and initialize 
* **Lock LP Tokens**: Secure liquidity for 90 days
* **Enable Claims:** Allow users to claim new tokens
* **Admin Withdraw**: Access funds in special circumstances and exchange requests
* **Recover Unclaimed**: Retrieve unclaimed tokens after 90-day claims period

#### For Unprotected Migrations

**Immediate Actions (After Migration Ends)**

* **Finalize Swap**: Sell collected old tokens and create new pool
* **Emergency Withdraw**: Can withdraw immediately if swap fails
* **Recover Unclaimed**: Access unclaimed tokens right away

**LP Token Management**

* LP tokens automatically locked for 30 days 
* Will be released to admin wallet after lock period
* For Bonk.fun: Both portions locked via Raydium NFTs and fees claimed on site
* For Pump.fun: LP tokens are burned and fees collected on site

#### For Protected Migrations

**Evaluation (At Deadline)**

Protected migrations have a target percentage that must be met:

1. **Automatic Evaluation**
   * System checks total migrated vs target amount
   * Occurs automatically at migration deadline
   * No admin action required
2. **If Successful (Target Met)**
   * Migration proceeds normally
   * Finalize swap available
   * Create liquidity pool
   * Enter 90-day claims period
3. **If Failed (Target Not Met)**
   * Migration marked as failed
   * Pool creation blocked
   * Users can claim SOL refunds
   * Proportional to migration amount

**Refund Process (Failed Migrations)**

When a protected migration fails:

1. **Automatic SOL Recovery**
   * Old tokens sold for SOL/USDC/USD1
   * Proceeds allocated for refunds
   * Proportional distribution
2. **User Refund Claims**
   * Users claim via Refund Panel
   * Receives share of recovered SOL
   * Based on tokens migrated
   * One-time claim only
3. **Admin Actions**
   * Cannot create pool
   * Cannot withdraw funds
   * Must wait for refund period
   * Can recover after claims expire

**90-Day Claims Period**

For successful protected migrations:

* Users have 90 days to claim tokens
* Admin cannot withdraw during this period
* After 90 days: Admin can recover unclaimed 
* Applies to both MFT and merkle claims

**Special Circumstance Access**

* Platform admin can enable emergency withdraw
* Centralized exchange portal requests
* Allows immediate access to funds for true emergencies
* Bypasses 90-day wait period
* Must be enabled by platform administrator
* Should be rare exception

***

### Admin Panel Functions Guide

#### Core Administrative Functions

**1. Deposit New Tokens**

**When**: After project creation, before initialization 

**Purpose**: Fund the migration vault with new tokens 

**Process**:

1. Navigate to Admin Panel
2. Find your project in the list
3. Click "Deposit New Tokens"
4. Enter amount to deposit
5. Approve token transfer
6. Confirm transaction

**Important**: Deposit enough to cover all potential migrations (old\_supply × exchange\_rate)

**2. Initialize Project**

**When**: After depositing new tokens **Purpose**: Activate migration and create MFT tokens **Process**:

1. Ensure new tokens are deposited
2. Click "Initialize Project"
3. This creates MFT (receipt) tokens
4. Migration becomes active for users

**3. Finalize Swap**

**When**: After migration period ends 

**Purpose**: Sell old tokens and create liquidity pool 

**Process**:

1. Wait for migration period to end
2. Click "Finalize Swap"
3. Set slippage tolerance (0.5-1% typical)
4. System executes market sell
5. Creates new pool with proceeds

**Pool Creation Details**:

* Uses collected SOL/USDC/USD1 from swap
* Pairs with deposited new tokens
* Creates pool based on selection
* LP tokens go to program vault

**4. Lock LP Tokens**

**When**: After pool creation 

**Purpose**: Secure liquidity for 30 days 

**Process**:

**Standard Projects**:

1. Click "Lock LP Tokens"
2. LP tokens locked via StreamFlow
3. 30-day vesting period
4. Released to admin after period

**BONK.fun Projects**:

1. Click "Lock LP for BONK.fun"
2. % locked for Bonk.fun official recipient (hardcoded address)
3. % locked for creator
4. Both use Raydium NFT locks
5. Split percentages cannot be modified (hardcoded for security)

**5. Emergency Withdraw**

**When**: Special circumstances only 

**Purpose**: Recover funds when normal flow fails 

**Available For**:

* **Unprotected**: After migration ends
* **Protected**: After 90 days OR with platform approval

**Process**:

1. Navigate to Emergency section
2. Select token type (old/new/SOL)
3. Click "Emergency Withdraw"
4. Funds sent to admin wallet

**Valid Use Cases**:

* Pool creation failure
* Liquidity issues
* Technical problems
* Platform-approved emergencies

**6. Recover Unclaimed Tokens**

**When**: After claims period expires 

**Purpose**: Retrieve tokens not claimed by users 

**Timing**:

* **Unprotected**: Immediately after migration
* **Protected**: After 90-day claims period

**Process**:

1. Wait for eligible period
2. Click "Recover Unclaimed"
3. Remaining tokens sent to admin
4. Includes both old and new tokens

***

### Merkle Tree Claims System (late claims)

#### Merkle Claims Overview

For users who miss the migration deadline, you can create a merkle tree-based claims system allowing them to claim tokens within a 90-day window.

#### Creating a Merkle Tree Snapshot

**Merkle Claims Prerequisites**

* Migration period must be ended
* No existing merkle tree for the project

**Process**

1. **Navigate to Claims Snapshot**
   * Go to Admin Panel
   * Select "Create Claims Snapshot"
2. **Take Snapshot**
   * System identifies all non-migrated token holders
   * Includes partial migrators (remaining balance)
   * Excludes AMM pools, burn addresses
   * Shows preview of eligible recipients
3. **Set Penalty Rate (Optional)**
   * Slide to set distribution percentage (0-100%)
   * 100% = full tokens, 50% = half tokens
   * Quick select buttons: 25%, 50%, 75%, 100%
   * Penalty encourages timely migration
4. **Review Recipients**
   * Table shows addresses and amounts
   * Can manually exclude addresses
   * Categories shown (User, LP Pool, Unknown)
   * Export to CSV for records
5. **Create Merkle Tree**
   * Click "Create Merkle Tree"
   * **WARNING**: This is permanent!
   * Cannot change after creation
   * Uploads to claims backend
   * Generates merkle root on-chain

**Post-Creation**

* Users can claim via Claims Panel
* 90-day expiration period
* Admin recovers unclaimed after expiry
* Merkle proofs verified on-chain

#### Merkle Tree Management

**Viewing Status**

* Check if merkle tree exists
* View creation timestamp
* See total claimable amount
* Monitor claim progress

**Claims Monitoring**

* Track number of claims
* View remaining unclaimed
* Export claim history
* Check individual claim status

***

### Platform Admin Functions

#### Emergency Override Powers

Platform administrators have special privileges for protected migrations:

**Toggle Emergency Withdraw**

**Purpose**: Enable project admin to withdraw during claims period 

**When to Use**:

* Project admin needs emergency access
* Technical issues preventing normal flow
* Verified emergency situations
* Exchange requests
* Special edge case situations 

**Process**:

1. Platform admin reviews request
2. Executes `toggle_project_emergency_withdraw`
3. Sets `enabled = true`
4. Project admin can now use emergency withdraw

**Security Notes**:

* Only for protected migrations
* Bypasses 90-day wait
* Should be rare exception
* All actions logged on-chain

#### Platform Configuration

Platform admins can update global settings:

**Update Platform Fees**

* Modify project creation fee
* Adjust platform fee percentage
* Change treasury address
* Pause/unpause platform

**Claim Platform Fees**

* Withdraw accumulated platform fees
* Transfer from treasury to admin
* Track fee collection metrics

***

### Security Best Practices

#### For Project Admins

1. **Private Key Security**
   * Use hardware wallets
   * Never share private keys
   * Use multisig if possible
2. **Transaction Verification**
   * Always verify transaction details
   * Check addresses carefully
   * Use small test amounts first
3. **Timing Considerations**
   * Plan migration periods carefully
   * Cannot extend once started
   * Consider time zones
4. **Communication**
   * Keep community informed
   * Provide clear instructions
   * Have support channels ready

#### For Protected Migrations - Security

1. **Target Setting**
   * Set realistic targets (10-30%)
   * Consider community size
   * Account for inactive wallets
2. **Emergency Planning**
   * Document emergency procedures
   * Have platform admin contact
   * Prepare contingency plans
3. **Claims Period**
   * 90 days is mandatory
   * Cannot be shortened
   * Plan accordingly

***

### Troubleshooting

#### Common Issues

**"Insufficient Balance"**

* **Cause**: Not enough SOL for fees
* **Solution**: Add more SOL to wallet (minimum 0.2 SOL recommended)

**"Pool Not Found"**

* **Cause**: Invalid pool ID or unsupported DEX
* **Solution**: Verify pool ID, ensure pool is on supported platform

**"Invalid Exchange Rate"**

* **Cause**: Rate too high or zero
* **Solution**: Set rate between 0.0001 and 1000

**"Migration Already Exists"**

* **Cause**: Project ID already used
* **Solution**: Choose different project ID

**"Token Program Mismatch"**

* **Cause**: Mixing SPL and Token-2022
* **Solution**: Ensure both tokens use same program

#### Transaction Failures

**During Creation**

1. Check wallet has enough SOL
2. Verify all inputs are valid
3. Try refreshing and reconnecting wallet
4. Use different RPC if timeout occurs

**During Finalization**

1. Increase slippage tolerance
2. Wait for less network congestion
3. Ensure pool has sufficient liquidity