MigrateFlow

Factory-based token migration dApp for BNB Chain with on-chain Merkle verification and delayed claims.

• Deploys per-project Migrator contracts from MigratorFactory.
• Lets holders prove eligibility from snapshot data and migrate via approve -> migrate -> claim.
• Supports CSV-based snapshots, optional Moralis holder fetch, and optional IPFS snapshot sharing.
• Includes owner-only project admin actions for funding and token withdrawals.

Problem

Token migrations need a deterministic way to map holders to allocations, collect old tokens, and release new tokens on a schedule.
MigrateFlow implements this with Merkle proofs on-chain and a web flow for project owners and holders.

Who It Is For

• Token project teams migrating from a legacy token contract.
• Token holders claiming allocations from a published snapshot.

Key Features

• MigratorFactory.createMigration deploys migration contracts and assigns ownership to the caller.
• Migrator.migrate verifies Merkle proofs and records user allocations after old-token deposit.
• Migrator.claim unlocks new-token claims after claimStartTime.
• Owner controls: updateMerkleRoot, withdrawOldTokens, withdrawRemainingTokens.
• /create route for migration creation and snapshot processing.
• /project/[address] route for eligibility check, approval, deposit, and claim.
• /api/snapshot integration with Moralis and a 5,000-holder auto-fetch cap.
• Optional IPFS snapshot upload/load using Pinata + gateway URLs.

Tech Stack

• Smart contracts: Solidity ^0.8.20, Foundry, OpenZeppelin.
• Frontend: Next.js (App Router), React, TypeScript, Tailwind CSS.
• Web3 client: wagmi, viem, ethers.
• Services: Moralis API, Pinata IPFS.

How It Works

Migration Creation Flow

1. Project owner opens /create.
2. Enters old/new token addresses and claim delay.
3. Builds a Merkle root from CSV data or Moralis holder data.
4. Optionally uploads snapshot JSON to IPFS.
5. Deploys a new migration contract through the factory.

Eligibility Verification Flow

1. Holder opens /project/[address] (optionally with ?snapshot=<cid>).
2. Loads snapshot from IPFS or uploads local snapshot JSON.
3. Checks wallet eligibility and retrieves proof + amount.
4. Approves old token allowance to the migration contract.

Claim Flow

1. Holder calls migrate(amount, proof) to deposit old tokens and lock allocation.
2. After claimStartTime, holder calls claim() to receive new tokens.
3. Owner can fund reward pool and manage withdrawals from the project admin panel.

Repository Structure

contracts/
  src/        Core contracts (Migrator, MigratorFactory, mocks)
  test/       Foundry tests
  script/     Foundry deployment/admin scripts
  broadcast/  Recorded script execution artifacts

frontend/
  src/app/        Next.js routes and API route
  src/components/ UI and owner admin panel
  src/hooks/      Migration, vesting, snapshot hooks
  src/utils/      Merkle, Moralis, IPFS utilities

scripts/
  Local Merkle/hash debugging scripts

Setup

Prerequisites

• Node.js 18+
• Foundry

Contracts

cd contracts
forge install
forge build
forge test -vvv

Frontend

cd frontend
npm install
cp .env.example .env.local
npm run dev

Optional Utility Scripts

cd scripts
npm install
node generateMerkle.js
node debugHash.js
node debugFullTree.js

Environment Variables

Frontend (frontend/.env.local)

Variable	Purpose
NEXT_PUBLIC_RPC_URL	BSC RPC URL used by wagmi transport
NEXT_PUBLIC_PINATA_JWT	Pinata JWT used for client-side IPFS upload
NEXT_PUBLIC_GATEWAY_URL	Base URL for IPFS snapshot retrieval
MORALIS_API_KEY	Key used by /api/snapshot route

Contracts (contracts/.env)

Variable	Purpose
PRIVATE_KEY	Deployer key for Foundry broadcast scripts
RPC_URL	RPC URL used by script execution

Deployment Notes

• Foundry scripts are included for factory deploy, migrator deploy, test token deploy, and Merkle root updates.
• Broadcast artifacts include:
  • Chain 56 factory: 0x4c33aef2a64a1a91adb398a80a68858368441d34
  • Chain 97 factory: 0xb39a6d3c95821f127220d3a33cbde5b59fe8ccd6
• Frontend constants target the chain 56 factory.
• UI enforces BNB Chain for interactive flows.

Limitations

• Auto-fetch is capped at 5,000 holders; larger sets require CSV import.
• Snapshot amount parsing assumes 18 decimals in current frontend paths.
• Claims require owner-funded new-token liquidity in each migration contract.
• Merkle root is owner-updatable.
• Snapshot persistence is localStorage-based per project address when not loaded by CID.

License

This repository currently has mixed SPDX headers (MIT and UNLICENSED) and no root LICENSE file.

Notes

• Broadcast run-latest.json files are repository records and should be treated as deployment artifacts, not live-state guarantees.