Migrate your CCT token pools from CCIP v1 to v2 (Burn & Mint) using Hardhat

Guide Versions

This guide is available in multiple versions. Choose the one that matches your needs.

This migration guide helps you upgrade a deployed Burn & Mint Cross-Chain Token (CCT) setup from CCIP v1 (1.5.x / 1.6.x) to CCIP v2, while keeping your existing token addresses and minimizing disruption.

In this guide you will:

Confirm prerequisites and record your existing CCIP v1 deployment details.
Deploy new CCIP v2 Burn Mint token pools on each chain.
Configure the v2 pools to accept messages from both the old v1 pools and the new v2 pools.
Cut over CCIP routing by calling TokenAdminRegistry.setPool on each chain.
Validate transfers end-to-end, then optionally clean up legacy configuration.

Before You Begin

1 Set up your development environment

Install Node.js and npm:
- Make sure you have Node.js v22.10.0 or above installed. If not, install Node.js v22.10.0 using their documentation.
- npm is bundled with Node.js. If you can't run npm, reinstall/update Node.js from the official installer.
Install/Update Chainlink CCIP-CLI. You can also find the GitHub repository here.

npm install -g @chainlink/ccip-cli

Verify the installation by running the following command:

ccip-cli --version

Clone the repository and navigate to the project directory:

CCIP 2.0 template

Clone the CCIP 2.0 Hardhat template for a smoother CCT setup.

git clone https://github.com/smartcontractkit/docs-cct-hardhat.git
cd docs-cct-hardhat

Create a .env file by copying the .env.example file, and fill in the required values:

cp .env.example .env

# Keystore name (created via `npx hardhat keystore set`)
KEYSTORE_NAME=<your_private_key_name>

# RPC URLs
ETHEREUM_SEPOLIA_RPC_URL=your_eth_sepolia_rpc
ARBITRUM_SEPOLIA_RPC_URL=your_arbitrum_sepolia_rpc

# Etherscan API key (required only if you pass --verify to deployment tasks)
ETHERSCAN_API_KEY=your_etherscan_api_key

Complete List of Supported Chains

View the complete list of supported chains in the helper-config.ts file.

To make sure your terminal has access to these variables, run the following command:

source .env

Build the project:

npm install && npx hardhat compile

Create an encrypted Hardhat keystore, if you haven't already:

npx hardhat keystore set <your_private_key_name>

2 What this guide assumes

EVM-to-EVM only: this page is strictly for Ethereum Sepolia ↔ Arbitrum Sepolia. - Burn & Mint pools only: standard BurnMintTokenPool migrations (no custom pools). - Admin control: you control the TokenAdminRegistry administrator role for the token on both chains. - Token permissions: you can grant the required mint/burn permissions to the new v2 pools on each chain. - Pool-owner actions: you can execute pool-owner actions on both chains (for example, applyChainUpdates, removeRemotePool). - Existing v1 deployment: you are migrating an already-live CCIP v1 setup (1.5.x or 1.6.x), not doing a new registration.

Migration Guide

Set these variables once for cleaner copy/paste

This guide uses explicit addresses so you don't need local deployments/ files. Start by exporting your token addresses, then we'll export the v1/v2 pool addresses as we discover them.

# Token addresses (existing deployments)
export ETHEREUM_SEPOLIA_TOKEN=0x...
export ARBITRUM_SEPOLIA_TOKEN=0x...

1 Step 1: Confirm the live CCIP v1 pool (and record v1 addresses)

This step answers two questions, on both chains:

Which pool is currently live for your token? (read from TokenAdminRegistry.getTokenConfig)
Is that pool a v1.5/v1.6 pool? (read typeAndVersion() from the pool)

getTokenConfig.ts

View the token config query task on GitHub.

Read the token config on Ethereum Sepolia:

npx hardhat getTokenConfig \
  --tokenaddress $ETHEREUM_SEPOLIA_TOKEN \
  --network sepolia

Your output should look something like this:

========================================
📋 Get Token Config
========================================
Chain:        Ethereum Sepolia
Token:        0x9602399103Ff5F87587Ac5A28E1551A0bA0c6C0D
Action:       Read getTokenConfig
========================================

Token Config:
  administrator:        0xYourAdminAddress
  pendingAdministrator: 0x0000000000000000000000000000000000000000
  tokenPool:            0xOldSepoliaV1PoolAddress

Export the v1 pool address:

export ETHEREUM_SEPOLIA_V1_POOL=0xOldSepoliaV1PoolAddress

Repeat on Arbitrum Sepolia:

npx hardhat getTokenConfig \
  --tokenaddress $ARBITRUM_SEPOLIA_TOKEN \
  --network arbitrumSepolia

Your output should look something like this:

Token Config:
  administrator:        0xYourAdminAddress
  pendingAdministrator: 0x0000000000000000000000000000000000000000
  tokenPool:            0xOldArbitrumV1PoolAddress

Export the v1 pool address:

export ARBITRUM_SEPOLIA_V1_POOL=0xOldArbitrumV1PoolAddress

getTypeAndVersion.ts

View the type/version query task on GitHub.

Confirm the v1 pool version on Ethereum Sepolia:

npx hardhat getTypeAndVersion \
  --address $ETHEREUM_SEPOLIA_V1_POOL \
  --network sepolia

Your output should look something like this:

typeAndVersion: BurnMintTokenPool 1.6.1

Confirm the v1 pool version on Arbitrum Sepolia:

npx hardhat getTypeAndVersion \
  --address $ARBITRUM_SEPOLIA_V1_POOL \
  --network arbitrumSepolia

Your output should look something like this:

typeAndVersion: BurnMintTokenPool 1.6.1

2 Step 2: Record your v1 lane configuration (remote pools + rate limits)

Before deploying anything, snapshot your current v1 configuration so you can keep behavior consistent after migration.

getSupportedChains.ts

View the supported-chains query task on GitHub.

List configured remote chains on the Sepolia v1 pool:

npx hardhat getSupportedChains \
  --tokenpool $ETHEREUM_SEPOLIA_V1_POOL \
  --network sepolia

Your output should look something like this:

Supported Remote Chains: 1

  [0] Arbitrum Sepolia (3478487238524512106)
       Remote Pools: 1
         [0] 0xOldArbitrumV1PoolAddress

List configured remote chains on the Arbitrum v1 pool:

npx hardhat getSupportedChains \
  --tokenpool $ARBITRUM_SEPOLIA_V1_POOL \
  --network arbitrumSepolia

Your output should look something like this:

Supported Remote Chains: 1

  [0] Ethereum Sepolia (16015286601757825753)
       Remote Pools: 1
         [0] 0xOldSepoliaV1PoolAddress

getCurrentRateLimits.ts

View the rate limiter query task on GitHub.

Snapshot current v1 rate limits on the Sepolia → Arbitrum lane:

npx hardhat getCurrentRateLimits \
  --tokenpool $ETHEREUM_SEPOLIA_V1_POOL \
  --destchain arbitrumSepolia \
  --network sepolia

Your output should look something like this:

Pool Version: v1

  Outbound Enabled:  true
  Outbound Capacity: 1000000000000000000000
  Outbound Rate:     100000000000000000
  Inbound  Enabled:  true
  Inbound  Capacity: 1000000000000000000000
  Inbound  Rate:     100000000000000000

Snapshot current v1 rate limits on the Arbitrum → Sepolia lane:

npx hardhat getCurrentRateLimits \
  --tokenpool $ARBITRUM_SEPOLIA_V1_POOL \
  --destchain sepolia \
  --network arbitrumSepolia

Your output should look something like this:

Pool Version: v1

  Outbound Enabled:  true
  Outbound Capacity: 1000000000000000000000
  Outbound Rate:     100000000000000000
  Inbound  Enabled:  true
  Inbound  Capacity: 1000000000000000000000
  Inbound  Rate:     100000000000000000

Record these values, you'll reuse them when configuring the v2 pools in Step 5.

3 Step 3: Deploy new v2 pools (per chain)

Deploy a new v2 BurnMintTokenPool on each chain, pointing to your existing token address on that chain.

deployBurnMintTokenPool.ts

View the Burn & Mint pool deployment task on GitHub.

Deploy the v2 pool on Ethereum Sepolia:

npx hardhat deployTokenPool \
  --tokenaddress $ETHEREUM_SEPOLIA_TOKEN \
  --network sepolia

Your output should look something like this:

🔥⚒️  Deploy Burn & Mint Token Pool

[Step 1] Deploying BurnMintTokenPool on Ethereum Sepolia
Token Pool deployed at: 0xNewSepoliaV2PoolAddress

[Step 2] Granting mint and burn roles to token pool: 0xNewSepoliaV2PoolAddress
✅ Roles granted successfully!

Export the new v2 pool address:

export ETHEREUM_SEPOLIA_V2_POOL=0xNewSepoliaV2PoolAddress

Deploy the v2 pool on Arbitrum Sepolia:

npx hardhat deployTokenPool \
  --tokenaddress $ARBITRUM_SEPOLIA_TOKEN \
  --network arbitrumSepolia

Your output should look something like this:

🔥⚒️  Deploy Burn & Mint Token Pool

[Step 1] Deploying BurnMintTokenPool on Arbitrum Sepolia
Token Pool deployed at: 0xNewArbitrumV2PoolAddress

[Step 2] Granting mint and burn roles to token pool: 0xNewArbitrumV2PoolAddress
✅ Roles granted successfully!

Export the new v2 pool address:

export ARBITRUM_SEPOLIA_V2_POOL=0xNewArbitrumV2PoolAddress

4 Step 4 (Recommended): Pause outbound transfers on the v1 pools

This recommended step throttles new outbound traffic on v1 while you cut over. Use capacity = 2 and rate = 1 as the most restrictive (near-zero) configuration we document for v1 pools while keeping the lane configured.

updateRateLimiters.ts

View the rate limiter update task on GitHub.

Pause outbound on the Sepolia v1 pool (lane to Arbitrum Sepolia):

npx hardhat updateRateLimiters \
  --tokenpool $ETHEREUM_SEPOLIA_V1_POOL \
  --destchain arbitrumSepolia \
  --outboundcapacity 2 \
  --outboundrate 1 \
  --network sepolia

Your output should look something like this:

========================================
⚡️ Update Rate Limiters
========================================
Pool Version: v1 (setChainRateLimiterConfig)

New Configuration:
  Outbound Enabled:  true
  Outbound Capacity: 2
  Outbound Rate:     1

Pause outbound on the Arbitrum v1 pool (lane to Ethereum Sepolia):

npx hardhat updateRateLimiters \
  --tokenpool $ARBITRUM_SEPOLIA_V1_POOL \
  --destchain sepolia \
  --outboundcapacity 2 \
  --outboundrate 1 \
  --network arbitrumSepolia

5 Step 5: Configure the v2 pools (applyChainUpdates)

On each chain, configure the v2 pool to recognize the lane to the remote chain.

Critical migration rule: the destPools list must include both the old v1 remote pool address and the new v2 remote pool address. This allows in-flight messages sent via v1 (before cutover) to still validate after you cut over to v2.

applyChainUpdates.ts

View the applyChainUpdates task (JSON mode recommended) on GitHub.

Configure the Sepolia v2 pool (remote chain: Arbitrum Sepolia)

Update input/apply-chain-updates.json:

{
  "_comment": "Configure Sepolia v2 pool → Arbitrum Sepolia. Replace 0x... placeholders with your real addresses.",
  "sourcePool": "0xNewSepoliaV2PoolAddress",
  "remoteChains": [
    {
      "destChain": "ARBITRUM_SEPOLIA",
      "destPools": ["0xOldArbitrumV1PoolAddress", "0xNewArbitrumV2PoolAddress"],
      "destToken": "0xYourArbitrumTokenAddress",
      "outboundRateLimit": { "enabled": false, "capacity": "0", "rate": "0" },
      "inboundRateLimit": { "enabled": false, "capacity": "0", "rate": "0" }
    }
  ]
}

If you had v1 rate limits enabled, copy the values you recorded in Step 2 into outboundRateLimit and inboundRateLimit so the v2 pool behavior stays consistent.

Run the task on Ethereum Sepolia:

npx hardhat applyChainUpdates --viajsonfile --network sepolia

Your output should look something like this:

========================================
🔗 Apply Chain Updates (JSON mode)
========================================
Source Chain:  Ethereum Sepolia
Token Pool:    0xNewSepoliaV2PoolAddress
Remote Chains: 1

  [0] Arbitrum Sepolia
      Pools: 2
        [0] 0xOldArbitrumV1PoolAddress
        [1] 0xNewArbitrumV2PoolAddress

✅ Chain updates applied successfully!

Configure the Arbitrum v2 pool (remote chain: Ethereum Sepolia)

Update input/apply-chain-updates.json:

{
  "_comment": "Configure Arbitrum v2 pool → Ethereum Sepolia. Replace 0x... placeholders with your real addresses.",
  "sourcePool": "0xNewArbitrumV2PoolAddress",
  "remoteChains": [
    {
      "destChain": "ETHEREUM_SEPOLIA",
      "destPools": ["0xOldSepoliaV1PoolAddress", "0xNewSepoliaV2PoolAddress"],
      "destToken": "0xYourSepoliaTokenAddress",
      "outboundRateLimit": { "enabled": false, "capacity": "0", "rate": "0" },
      "inboundRateLimit": { "enabled": false, "capacity": "0", "rate": "0" }
    }
  ]
}

Run the task on Arbitrum Sepolia:

npx hardhat applyChainUpdates --viajsonfile --network arbitrumSepolia

Your output should look something like this:

Source Chain:  Arbitrum Sepolia
Token Pool:    0xNewArbitrumV2PoolAddress
Remote Chains: 1

  [0] Ethereum Sepolia
      Pools: 2
        [0] 0xOldSepoliaV1PoolAddress
        [1] 0xNewSepoliaV2PoolAddress

✅ Chain updates applied successfully!

6 Step 6: Verify v2 configuration (before cutover)

Verify that each v2 pool has two remote pools configured for the lane: [remoteV1Pool, remoteV2Pool].

getRemotePools.ts

View the remote pool query task on GitHub.

Check remote pools on the Sepolia v2 pool:

npx hardhat getRemotePools \
  --tokenpool $ETHEREUM_SEPOLIA_V2_POOL \
  --destchain arbitrumSepolia \
  --network sepolia

Your output should look something like this:

Chain Supported: Yes
Remote Pools:    2
  [0] 0xOldArbitrumV1PoolAddress
  [1] 0xNewArbitrumV2PoolAddress

Check remote pools on the Arbitrum v2 pool:

npx hardhat getRemotePools \
  --tokenpool $ARBITRUM_SEPOLIA_V2_POOL \
  --destchain sepolia \
  --network arbitrumSepolia

Your output should look something like this:

Chain Supported: Yes
Remote Pools:    2
  [0] 0xOldSepoliaV1PoolAddress
  [1] 0xNewSepoliaV2PoolAddress

getCurrentRateLimits.ts

View the rate limiter query task on GitHub.

Re-check rate limits on the v2 pools (optional but recommended)

Sepolia v2 pool (lane to Arbitrum):

npx hardhat getCurrentRateLimits \
  --tokenpool $ETHEREUM_SEPOLIA_V2_POOL \
  --destchain arbitrumSepolia \
  --network sepolia

Arbitrum v2 pool (lane to Sepolia):

npx hardhat getCurrentRateLimits \
  --tokenpool $ARBITRUM_SEPOLIA_V2_POOL \
  --destchain sepolia \
  --network arbitrumSepolia

7 Step 7: Cut over routing (TokenAdminRegistry.setPool)

This is the migration cutover step. On each chain, update TokenAdminRegistry so your token routes through the new v2 pool.

setPool.ts

View the setPool task on GitHub.

Cut over on Ethereum Sepolia:

npx hardhat setPool \
  --tokenaddress $ETHEREUM_SEPOLIA_TOKEN \
  --tokenpool $ETHEREUM_SEPOLIA_V2_POOL \
  --network sepolia

Your output should look something like this:

========================================
🏊 Set Token Pool
========================================
Chain:        Ethereum Sepolia
Token Pool:   0xNewSepoliaV2PoolAddress
Action:       Set token pool
========================================

✅ Pool Set Complete on Ethereum Sepolia!

Cut over on Arbitrum Sepolia:

npx hardhat setPool \
  --tokenaddress $ARBITRUM_SEPOLIA_TOKEN \
  --tokenpool $ARBITRUM_SEPOLIA_V2_POOL \
  --network arbitrumSepolia

8 Step 8: Validate end-to-end (Sepolia → Arbitrum) with ccip-cli

Send a small test transfer from Ethereum Sepolia → Arbitrum Sepolia and confirm it succeeds.

Set the router address for Ethereum Sepolia (from the CCIP Directory or helper-config.ts in the template):

export ETHEREUM_SEPOLIA_ROUTER=0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59

Send a transfer on default finality:

ccip-cli send \
  --source ethereum-testnet-sepolia \
  --router $ETHEREUM_SEPOLIA_ROUTER \
  --dest ethereum-testnet-sepolia-arbitrum-1 \
  --transfer-tokens $ETHEREUM_SEPOLIA_TOKEN=1.23 \
  --receiver 0xYourReceiverAddress \
  --wallet hardhat:$KEYSTORE_NAME \
  --rpc "$ETHEREUM_SEPOLIA_RPC_URL" \
  --rpc "$ARBITRUM_SEPOLIA_RPC_URL"

Your output should look something like this:

Fee: 130129888907619n = 0.000130129888907619 ETH
🚀 Sending message ... messageId => 0x4a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293

(Optional) Request block-depth faster than finality with depth 32

Only use this if your v2 pools explicitly allow block-depth faster than finality. If this fails, omit --extra and retry with default finality.

ccip-cli send \
  --source ethereum-testnet-sepolia \
  --router $ETHEREUM_SEPOLIA_ROUTER \
  --dest ethereum-testnet-sepolia-arbitrum-1 \
  --transfer-tokens $ETHEREUM_SEPOLIA_TOKEN=1.23 \
  --receiver 0xYourReceiverAddress \
  --extra finality=32 \
  --wallet hardhat:$KEYSTORE_NAME \
  --rpc "$ETHEREUM_SEPOLIA_RPC_URL" \
  --rpc "$ARBITRUM_SEPOLIA_RPC_URL"

9 Step 9: Confirm your token now routes through v2 pools

Re-run the Step 1 checks. You should now see the v2 pool addresses as the live tokenPool on both chains, and typeAndVersion should report v2.

Ethereum Sepolia:

npx hardhat getTokenConfig --tokenaddress $ETHEREUM_SEPOLIA_TOKEN --network sepolia
npx hardhat getTypeAndVersion --address $ETHEREUM_SEPOLIA_V2_POOL --network sepolia

Your output should look something like this:

Token Config:
  tokenPool:            0xNewSepoliaV2PoolAddress

typeAndVersion: BurnMintTokenPool 2.0.0

Arbitrum Sepolia:

npx hardhat getTokenConfig --tokenaddress $ARBITRUM_SEPOLIA_TOKEN --network arbitrumSepolia
npx hardhat getTypeAndVersion --address $ARBITRUM_SEPOLIA_V2_POOL --network arbitrumSepolia

Your output should look something like this:

Token Config:
  tokenPool:            0xNewArbitrumV2PoolAddress

typeAndVersion: BurnMintTokenPool 2.0.0

10 Step 10: Safety checks and cleanup (after v1 inflight settles)

After cutover, keep the v1 remote pool addresses configured on the v2 pools until you are confident there are no more in-flight v1 messages. There is no cost to waiting longer.

Once you're ready, remove the old v1 remote pool addresses from the v2 pools.

removeRemotePool.ts

View the remote pool removal task on GitHub.

On the Sepolia v2 pool, remove the old Arbitrum v1 pool address:

npx hardhat removeRemotePool \
  --tokenpool $ETHEREUM_SEPOLIA_V2_POOL \
  --destchain arbitrumSepolia \
  --remotepooladdress $ARBITRUM_SEPOLIA_V1_POOL \
  --network sepolia

Your output should look something like this:

➖ Remove Remote Pool

⚠️  WARNING: All inflight transactions from this pool will be rejected after removal.

Current Remote Pools: 2
  [0] 0xOldArbitrumV1PoolAddress
  [1] 0xNewArbitrumV2PoolAddress

✅ Remote pool removed successfully!

On the Arbitrum v2 pool, remove the old Sepolia v1 pool address:

npx hardhat removeRemotePool \
  --tokenpool $ARBITRUM_SEPOLIA_V2_POOL \
  --destchain sepolia \
  --remotepooladdress $ETHEREUM_SEPOLIA_V1_POOL \
  --network arbitrumSepolia

addRemotePool.ts

View the remote pool add task on GitHub (recovery).

Recovery example (re-add the old pool address, then retry cleanup later):

npx hardhat addRemotePool \
  --tokenpool $ETHEREUM_SEPOLIA_V2_POOL \
  --destchain arbitrumSepolia \
  --remotepooladdress $ARBITRUM_SEPOLIA_V1_POOL \
  --network sepolia

Migrate your CCT token pools from CCIP v1 to v2 (Burn & Mint) using Hardhat

Guide Versions

Before You Begin

Migration Guide

What's next

Get the latest Chainlink content straight to your inbox.