Migration Pools

Swap old tokens for new tokens at a 1:1 rate. The simplest migration — send 1000 old, get 1000 new. No vesting, no bonus, no catches.

When You'll See This

Token rebrands (ALPHA → OMEGA), contract upgrades, mint rotations after security incidents.

Step 1 — Find the Pool in TUI

$ aex tui
[8] → DeFi panel
[i] → Migration sub-tab
[j/k] → Navigate to your pool
[Enter] → View details

Step 2 — Check Your Token Balance

$ aex balance --keypair wallet.json

Step 3 — Execute the Migration

Amounts are in raw units (including decimals). For 6 decimals: 1,000 tokens = 1,000,000,000 raw.

$ aex migrate swap 7xKq...3nPd 5000000000 --keypair wallet.json

Migration swap submitted!
  Pool: 7xKq...3nPd
  Sent: 5,000.000000 ALPHA
  Received: 5,000.000000 OMEGA
  TX: 5Uxj...7kPm

Step 4 — Verify in TUI

Go back to the TUI (auto-refreshes every 5 seconds). Confirm your migration was counted in the stats.

Adding a Referral

$ aex migrate swap 7xKq...3nPd 5000000000 --referrer <referrer_pubkey> --keypair wallet.json

You get the same 5,000 OMEGA. The referrer gets a bonus from the vault (e.g., 250 OMEGA at 5% referral rate).

Common Errors

Convert old tokens at a fixed ratio (e.g., 10 old = 1 new). The ratio is set in the pool's param0 (numerator) and param1 (denominator) fields.

How the Ratio Works

output = input_amount * param0 / param1

Example: param0=1, param1=10
  Send 10,000 old → get 1,000 new (10:1 consolidation)

Swap Command

$ aex migrate swap <pool> <amount_raw> --keypair wallet.json

Common Uses

Token consolidation (reduce circulating supply), decimal changes (e.g., 9 decimals → 6 decimals), cross-chain parity adjustments.

Fixed ratio conversion with an authority fee deducted from the output. The fee (in param2 as bps) lets the authority earn revenue from the migration.

Calculation

gross_output = input * param0 / param1
fee = gross_output * param2 / 10000
net_output = gross_output - fee

Example: ratio 1:1, fee 200 bps (2%)
  Send 1,000 → gross 1,000 → fee 20 → receive 980

Swap Command

$ aex migrate swap <pool> <amount> --keypair wallet.json

Swap old tokens for new tokens, but the new tokens are locked and unlock gradually over time. You come back periodically to claim unlocked portions.

When You'll See This

Projects preventing post-migration dumps, loyalty rewards, token launches with gradual distribution.

Step 1 — Check Vesting Schedule in TUI

Type: 3 (Vesting)
Flags: VEST
Vest Duration: 2592000s (30 days)
Claim Interval: 604800s (7 days)
Ratio: 1:1

Tokens vest over 30 days. Claim once per week. Each claim: ~23.3% of total.

Step 2 — Execute the Initial Swap

$ aex migrate swap <pool> 10000000000000 --keypair wallet.json

This creates a MigrationClaimPDA linked to your wallet. You're entitled to 10,000 new tokens, but they're locked.

Step 3 — Claim Unlocked Tokens (Weekly)

$ aex migrate claim <pool> --keypair wallet.json

Vesting claim submitted!
  Entitled: 10,000.000000 V2
  Already claimed: 0.000000
  Now claimable: 2,333.333333 V2

Vesting Math

elapsed = min(now - first_deposit, vest_duration)
intervals_passed = floor(elapsed / claim_interval)
total_intervals = vest_duration / claim_interval
unlocked = total_entitled * intervals_passed / total_intervals
claimable = unlocked - already_claimed

Automating Claims

# crontab -e
0 12 * * 1 /path/to/aex migrate claim <pool> --keypair /path/to/wallet.json

Early migrants get a bonus that shrinks over time. The bonus starts at param2 bps and linearly decays to 0 by the pool's end time.

Calculation

remaining = end_time - now
total_window = end_time - start_time
bonus_pct = param2 * remaining / total_window
output = input * (10000 + bonus_pct) / 10000

Day 1 of 30-day pool (bonus=2000 bps):
  bonus = 2000 * 29/30 = 1933 bps (19.33%)
  Send 1,000 → receive 1,193

Day 29:
  bonus = 2000 * 1/30 = 66 bps (0.66%)
  Send 1,000 → receive 1,006

Old tokens are permanently destroyed via CPI burn. The program calls the SPL Token burn instruction directly. This is irreversible — there is no old_vault to reclaim from.

How It Differs

Normal migration: old tokens go into old_vault (authority can reclaim later). Burn migration: old tokens are burned on the spot. Total old supply decreases permanently.

Swap Command

$ aex migrate swap <pool> <amount> --keypair wallet.json

Use Cases

Deflationary token upgrades, security incident remediation (destroy compromised mint supply), permanent token retirement.

Merge multiple old token communities into one new token. The authority creates separate migration pools per old token, each with its own conversion ratio.

Example: 3-Token Merge

Pool A: OLD_A → NEW (ratio 1:1)     p0=1, p1=1
Pool B: OLD_B → NEW (ratio 2:1)     p0=1, p1=2
Pool C: OLD_C → NEW (ratio 5:1)     p0=1, p1=5

Each pool is independent. Users migrate from whichever old token they hold.

First-come, first-served migration with a global cap on total tokens distributed. Once the cap is hit, the pool stops accepting swaps.

Cap Enforcement

cap = param2 (raw token units)

If total_distributed + output > cap:
  output = cap - total_distributed  (partial fill)

Next swap after cap: ERR_CAP

The authority must co-sign every swap transaction. Only wallets the authority approves can migrate. There's no on-chain whitelist — the authority's bot gates access in real-time.

How It Works

1. User requests migration via off-chain channel
2. Authority's bot verifies eligibility
3. Bot co-signs the transaction
4. User submits the co-signed TX

Use Cases

KYC-gated migrations, holder snapshots (only snapshot holders approved), geographic restrictions, tiered access.

Each wallet has a cumulative limit on how much they can migrate. Tracked via the MigrationClaimPDA. Anti-whale mechanism for fair distribution.

How It Works

max_per_wallet = param2 (raw token units)

On each swap:
  if user_total_migrated + amount > max_per_wallet:
    ERR_CAP

Multiple swaps are fine as long as total stays under the cap. The claim PDA tracks cumulative amount.

Combines time-decay bonus (Type 4) with vesting (Type 3). Rush to lock in the early-bird bonus, then claim tokens gradually as they vest.

Parameters

param2 = bonus_bps (e.g., 2000 = 20% max bonus)
param3 = vest_duration (seconds)
param4 = claim_interval (seconds)

Example: 20% bonus, 28-day vest, daily claims
  Day 1: swap 1000 → entitled to 1190 (19% bonus)
  Day 2+: claim ~42.5 tokens per day for 28 days

Old tokens burned immediately, new tokens vest gradually. The strongest commitment mechanism — irreversible destruction + illiquid new tokens.

Parameters

param2 = vest_duration (seconds)
param3 = claim_interval (seconds)

Example: 60-day vest, weekly claims
  Swap: 5000 old tokens burned forever
  Week 1: claim ~583 new tokens
  Week 8+: claim final remainder

Send SOL (lamports, not SPL tokens) to buy new tokens at a fixed rate. Direct SOL-to-token sale.

Parameters

param0 = tokens_per_sol (in raw units per 1 SOL)
param2 = cap (optional, total tokens to sell)

Example: param0 = 1000000000 (1000 tokens per SOL, 6 decimals)
  Send 5 SOL → receive 5,000 tokens

Swap Command

# Amount is in lamports (1 SOL = 1,000,000,000 lamports)
$ aex migrate swap <pool> 5000000000 --keypair wallet.json

Set up a referral link for any migration pool with the REF flag, share it with others, earn rewards when they migrate, and claim your accumulated rewards.

Step 1 — Create Your Referral Link

$ aex migrate ref-init <pool_address> --keypair your_wallet.json

Referral link created!
  Pool: <pool_address>
  Your RefLink PDA: 4Kxp...7mNq
  Level: 0 (direct)

Your referral "link" is just your public key. Share it — friends add --referrer <your_pubkey> to their swap.

Step 2 — Friends Migrate Through Your Link

$ aex migrate swap <pool> 5000000000 --referrer <your_pubkey> --keypair friend.json

Friend gets full 5,000 tokens.
You get credited: 5,000 * 5% = 250 tokens (from vault).

Step 3 — Check & Claim Earnings

$ aex migrate ref-show <pool> --keypair your_wallet.json
$ aex migrate ref-claim <pool> --keypair your_wallet.json

Multi-Level Chains

Alice (L3) → Bob (L2) → Carol (L1) → User Dave

$ aex migrate ref-init <pool> --keypair alice.json
$ aex migrate ref-init <pool> --parent <alice_pubkey> --keypair bob.json
$ aex migrate ref-init <pool> --parent <bob_pubkey> --keypair carol.json

Dave swaps 10,000 tokens:
  Carol (L1): 10,000 * 5% = 500 tokens
  Bob (L2):   500 * 50% = 250 tokens
  Alice (L3): 250 * 25% = 62 tokens

Earnings Table

The complete guide for pool creators: create a pool, deposit tokens, monitor, handle emergencies, close, and reclaim.

Create a Migration Pool

$ aex migrate create <old_mint> <new_mint> --type 0 \
  --start $(date -d '+1 hour' +%s) \
  --end $(date -d '+30 days' +%s) \
  --name "ALPHA to OMEGA" \
  --desc "Token rebrand migration" \
  --keypair authority.json

Deposit New Tokens

$ aex migrate deposit <pool> <amount_raw> --keypair authority.json

Monitor in TUI

$ aex tui → [8] → [i] → [Enter]
Watch: Migrated count, Users, Remaining balance, Progress bar.

Emergency: Pause

$ aex migrate pause <pool> --keypair authority.json

Close After End Time

$ aex migrate close <pool> --keypair authority.json

Remaining new tokens returned to your wallet.
Collected old tokens returned to your wallet.

Transfer Authority

$ aex migrate auth <pool> --step init --new-auth <pubkey> --keypair authority.json
$ aex migrate auth <pool> --step complete --keypair new_authority.json