Token Migration Contract Development

Token Migration Contract Development

Token migration is one of those processes where a single bug could cost your entire TVL. You burned the old token but didn't issue the new one. Or issued it twice. Or issued it correctly but the event wasn't emitted and the frontend shows the wrong state. These are real cases, not hypothetical ones.

There are several reasons for migration: rebranding (new ticker/name), technical upgrade (adding functionality), chain switching, fixing a critical vulnerability in the old token, changing tokenomics.

Migration Patterns

1:1 Swap with Burn

Classic approach: user approves old token → calls migrate(amount) → contract burns the old, mints the new.

function migrate(uint256 amount) external nonReentrant {
    require(amount > 0, "Zero amount");
    require(block.timestamp <= migrationEnd, "Migration ended");
    
    // Checks → Effects → Interactions
    migrated[msg.sender] += amount;
    totalMigrated += amount;
    
    oldToken.burnFrom(msg.sender, amount);
    newToken.mint(msg.sender, amount);
    
    emit Migrated(msg.sender, amount);
}

Requirements for the old token: a burnFrom function or transferFrom + router contract. If the old token doesn't have burnFrom — accept it to the migration contract and lock it forever (or burn in a separate transaction).

Lock & Issue (Without Burn)

Old tokens are locked on the contract, new ones are issued at 1:1 or at a conversion rate. Suitable when the old token can't be burned (for example, it trades on a CEX and you need the ability to convert back).

Merkle Proof Migration

For cases where the list of addresses and amounts are known in advance (snapshot). Instead of on-chain verification of each transaction — a Merkle tree with allowances, embedded in the contract:

function claimMigration(
    uint256 amount,
    bytes32[] calldata proof
) external {
    bytes32 leaf = keccak256(abi.encodePacked(msg.sender, amount));
    require(MerkleProof.verify(proof, merkleRoot, leaf), "Invalid proof");
    require(!claimed[msg.sender], "Already claimed");
    
    claimed[msg.sender] = true;
    newToken.mint(msg.sender, amount);
    
    emit Claimed(msg.sender, amount);
}

Advantage: no need for approve on the old token, no front-running risk, suitable for airdrop migrations.

Key Security Parameters

Limits on the contract. Maximum volume per migration call, daily limit, total limit for the entire migration period. This limits damage from a single error.

Migration deadline. Migration must end. Unmigrated old tokens after the deadline — that's normal (their holders made their choice). Perpetual migration creates eternal support burden.

Ratio verification. If conversion is not 1:1, the formula must be atomic and mathematically verified. An error in * vs / on uint256 — classic reason for infinite mint.

Pauser. Emergency stop if a problem is discovered. Only for pausing, not for changing logic.

Event logging. emit Migrated(msg.sender, amount, block.timestamp) — must be informative enough for analytics and verification.

Pitfalls

Non-atomic burn → mint. If we burn in one transaction and mint in another — between them could be a reorg or error. Always in one transaction, strict CEI pattern.

Reentrancy through old token callback. Some tokens (ERC-777) invoke a callback on sender during transferFrom. If nonReentrant isn't set — migrate() can be called recursively until allowance is drained.

Old token with fee (fee-on-transfer). Contract expects to receive X but receives X * (1 - fee%). newToken.mint(msg.sender, amount) mints more than received. Check actual balance after transferFrom: uint256 received = balanceAfter - balanceBefore.

Front-running on migration start/end. MEV-bots can monitor contract deployment and migrate other people's tokens (through approve, if not revoked). Ensure only the token owner can initiate migration.

Process

Contract development with tests: 1.5-2 days. Deployment on mainnet via multisig + timelock: +1 day. Optionally — dashboard for monitoring migration progress (% migrated tokens, top addresses, temporal analysis): +1-2 days.

Before deployment, a migration contract audit is mandatory — even if it's a small contract. Exactly "small and simple" contracts have historically contained the most expensive bugs.