Migrating from V1 to V2 - EVM CCTP Contracts

Overview

This guide helps you migrate your CCTP integration from V1 to V2 contracts. V2 introduces breaking changes in function signatures and event structures that require code updates.

V1 and V2 are separate protocol deployments. You cannot send V1 messages to V2 contracts or vice versa. Both versions can coexist on the same chain.

Migration Checklist

Review new V2 features and determine which to use
Update depositForBurn function calls with new parameters
Replace depositForBurnWithCaller usage
Update event listeners for new event signatures
Add fee calculation logic
Configure new role addresses
Update message handler interface (if applicable)
Deploy or connect to V2 contracts
Test integration thoroughly

API Changes

depositForBurn Function

The depositForBurn function signature has changed significantly.

V1 to V2 Comparison

// Approve USDC
usdc.approve(address(tokenMessenger), amount);

// Deposit for burn
uint64 nonce = tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    burnToken
);

// Approve USDC
usdc.approve(address(tokenMessenger), amount);

// Deposit for burn with new parameters
tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    burnToken,
    bytes32(0),              // destinationCaller (new)
    maxFee,                  // maxFee (new)
    minFinalityThreshold     // minFinalityThreshold (new)
);
// Note: V2 does not return nonce

Parameter Mapping

Parameter	V1	V2	Notes
`amount`	✅	✅	Same
`destinationDomain`	✅	✅	Same
`mintRecipient`	✅	✅	Same
`burnToken`	✅	✅	Same
`destinationCaller`	❌	✅	New - use `bytes32(0)` for any caller
`maxFee`	❌	✅	New - must be < amount and >= minFee
`minFinalityThreshold`	❌	✅	New - minimum 500, use 1000 for most cases
Return value	`uint64 nonce`	none	V2 doesn’t return nonce

Migration Example

// V1 code
function bridgeUSDC(uint256 amount, uint32 destDomain, bytes32 recipient) external {
    usdc.approve(address(tokenMessengerV1), amount);
    
    uint64 nonce = tokenMessengerV1.depositForBurn(
        amount,
        destDomain,
        recipient,
        address(usdc)
    );
    
    emit BridgeInitiated(nonce, amount);
}

// V2 code
function bridgeUSDC(uint256 amount, uint32 destDomain, bytes32 recipient) external {
    usdc.approve(address(tokenMessengerV2), amount);
    
    // Calculate required fee
    uint256 minFeeAmount = tokenMessengerV2.getMinFeeAmount(amount);
    uint256 maxFee = minFeeAmount + 1000; // Add buffer
    
    tokenMessengerV2.depositForBurn(
        amount,
        destDomain,
        recipient,
        address(usdc),
        bytes32(0),                           // Any caller can relay
        maxFee,                               // Maximum fee willing to pay
        1000                                  // Confirmed finality
    );
    
    // Note: Cannot use nonce anymore, use event filtering instead
    emit BridgeInitiated(amount);
}

depositForBurnWithCaller Removal

depositForBurnWithCaller is removed in V2. Use depositForBurn with the destinationCaller parameter instead.

// Specify authorized caller
tokenMessenger.depositForBurnWithCaller(
    amount,
    destinationDomain,
    mintRecipient,
    burnToken,
    destinationCaller
);

// Use main depositForBurn function
tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    burnToken,
    destinationCaller,    // Moved to main function
    maxFee,
    minFinalityThreshold
);

replaceDepositForBurn

replaceDepositForBurn() is not available in V2. Message replacement functionality has been removed.

If you rely on message replacement:

Alternative 1: Send a new message with updated parameters
Alternative 2: Implement application-level message invalidation logic
Alternative 3: Use hook data to encode conditional logic

Event Changes

DepositForBurn Event

The event signature has changed significantly.

Event Structure Comparison

event DepositForBurn(
    uint64 indexed nonce,
    address indexed burnToken,
    uint256 amount,
    address indexed depositor,
    bytes32 mintRecipient,
    uint32 destinationDomain,
    bytes32 destinationTokenMessenger,
    bytes32 destinationCaller
);

event DepositForBurn(
    address indexed burnToken,
    uint256 amount,
    address indexed depositor,
    bytes32 mintRecipient,
    uint32 destinationDomain,
    bytes32 destinationTokenMessenger,
    bytes32 destinationCaller,
    uint256 maxFee,                      // NEW
    uint32 indexed minFinalityThreshold, // NEW
    bytes hookData                       // NEW
);

Migration Impact

Key Changes:

❌ nonce removed (was indexed)
✅ minFinalityThreshold added (indexed)
✅ maxFee added
✅ hookData added

Event Listener Migration

// V1 - Listen by nonce
const filter = tokenMessenger.filters.DepositForBurn(
    nonce,              // indexed
    null,               // burnToken
    null                // depositor
);

const events = await tokenMessenger.queryFilter(filter);
console.log('Amount:', events[0].args.amount);

// V2 - Listen by finality threshold or burnToken
const filter = tokenMessenger.filters.DepositForBurn(
    null,               // burnToken
    null,               // depositor
    1000                // minFinalityThreshold (indexed)
);

const events = await tokenMessenger.queryFilter(filter);
console.log('Amount:', events[0].args.amount);
console.log('Max Fee:', events[0].args.maxFee);
console.log('Hook Data:', events[0].args.hookData);

MintAndWithdraw Event

event MintAndWithdraw(
    address indexed mintRecipient,
    uint256 amount,
    address indexed mintToken
);

event MintAndWithdraw(
    address indexed mintRecipient,
    uint256 amount,
    address indexed mintToken,
    uint256 feeCollected  // NEW
);

Migration: Update event listeners to include feeCollected field.

Fee Management

Calculating Fees

V2 requires fee calculation before calling depositForBurn.

// Get minimum fee amount
uint256 minFeeAmount = tokenMessenger.getMinFeeAmount(amount);

// Add buffer for fee fluctuation (optional)
uint256 maxFee = minFeeAmount.mul(110).div(100); // 10% buffer

// Ensure maxFee < amount
require(maxFee < amount, "Fee exceeds amount");

tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    address(usdc),
    bytes32(0),
    maxFee,
    minFinalityThreshold
);

Fee Recipient

Set up fee collection:

// Owner sets fee recipient
tokenMessenger.setFeeRecipient(treasuryAddress);

// Fees are automatically minted to feeRecipient
// when messages are processed as unfinalized

Zero Fee Transfers

To avoid fees entirely, use finalized messages:

// Use finalized threshold (2000) for zero-fee transfers
tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    address(usdc),
    bytes32(0),
    0,      // maxFee can be 0 for finalized
    2000    // FINALITY_THRESHOLD_FINALIZED
);

Finalized messages take longer to process but don’t incur fees.

Message Handler Interface

If you implement custom message handlers, update your interface.

Interface Changes

contract MyHandler is IMessageHandler {
    function handleReceiveMessage(
        uint32 sourceDomain,
        bytes32 sender,
        bytes calldata messageBody
    ) external override returns (bool) {
        // Process message
        return true;
    }
}

contract MyHandler is IMessageHandlerV2 {
    function handleReceiveFinalizedMessage(
        uint32 sourceDomain,
        bytes32 sender,
        uint32 finalityThresholdExecuted,
        bytes calldata messageBody
    ) external override returns (bool) {
        // Process finalized message (no fee deduction)
        return true;
    }

    function handleReceiveUnfinalizedMessage(
        uint32 sourceDomain,
        bytes32 sender,
        uint32 finalityThresholdExecuted,
        bytes calldata messageBody
    ) external override returns (bool) {
        // Process unfinalized message (fee deducted)
        require(
            finalityThresholdExecuted >= 500,
            "Finality too low"
        );
        return true;
    }
}

Role Configuration

V2 introduces new administrative roles.

Required Role Addresses

V1 Roles
V2 Roles

# V1 .env configuration
MESSAGE_TRANSMITTER_PAUSER_ADDRESS=<address>
TOKEN_MINTER_PAUSER_ADDRESS=<address>
MESSAGE_TRANSMITTER_RESCUER_ADDRESS=<address>
TOKEN_MESSENGER_RESCUER_ADDRESS=<address>
TOKEN_MINTER_RESCUER_ADDRESS=<address>
TOKEN_CONTROLLER_ADDRESS=<address>

# V2 .env configuration (all V1 roles plus:)

# Existing V1 roles
MESSAGE_TRANSMITTER_V2_PAUSER_ADDRESS=<address>
TOKEN_MINTER_V2_PAUSER_ADDRESS=<address>
MESSAGE_TRANSMITTER_V2_RESCUER_ADDRESS=<address>
TOKEN_MESSENGER_V2_RESCUER_ADDRESS=<address>
TOKEN_MINTER_V2_RESCUER_ADDRESS=<address>
TOKEN_CONTROLLER_ADDRESS=<address>

# NEW V2 roles
TOKEN_MESSENGER_V2_FEE_RECIPIENT_ADDRESS=<address>
TOKEN_MESSENGER_V2_DENYLISTER_ADDRESS=<address>
TOKEN_MESSENGER_V2_MIN_FEE_CONTROLLER_ADDRESS=<address>

Role Responsibilities

Role	Description	When to Update
feeRecipient	Receives collected fees	Set during initialization
denylister	Manages protocol denylist	Set during initialization
minFeeController	Sets minimum fee requirements	Set during initialization

Contract Interface Differences

New Functions in V2

// Fee management
function setFeeRecipient(address _feeRecipient) external;
function setMinFeeController(address _minFeeController) external;
function setMinFee(uint256 _minFee) external;
function getMinFeeAmount(uint256 amount) external view returns (uint256);

// Denylist management
function addToDenylist(address account) external;
function removeFromDenylist(address account) external;
function isDenylisted(address account) external view returns (bool);

// Hook support
function depositForBurnWithHook(
    uint256 amount,
    uint32 destinationDomain,
    bytes32 mintRecipient,
    address burnToken,
    bytes32 destinationCaller,
    uint256 maxFee,
    uint32 minFinalityThreshold,
    bytes calldata hookData
) external;

Removed Functions in V2

// ❌ Removed - Use depositForBurn with destinationCaller parameter
function depositForBurnWithCaller(...) external returns (uint64 nonce);

// ❌ Removed - Message replacement not supported
function replaceDepositForBurn(...) external;

Smart Contract Migration Example

Complete example showing V1 to V2 migration:

contract MyBridgeV1 {
    ITokenMessenger public tokenMessenger;
    IERC20 public usdc;
    
    constructor(address _tokenMessenger, address _usdc) {
        tokenMessenger = ITokenMessenger(_tokenMessenger);
        usdc = IERC20(_usdc);
    }
    
    function bridge(
        uint256 amount,
        uint32 destDomain,
        bytes32 recipient
    ) external {
        usdc.transferFrom(msg.sender, address(this), amount);
        usdc.approve(address(tokenMessenger), amount);
        
        uint64 nonce = tokenMessenger.depositForBurn(
            amount,
            destDomain,
            recipient,
            address(usdc)
        );
        
        emit Bridged(nonce, msg.sender, amount);
    }
    
    event Bridged(uint64 indexed nonce, address indexed user, uint256 amount);
}

contract MyBridgeV2 {
    ITokenMessengerV2 public tokenMessenger;
    IERC20 public usdc;
    uint32 public defaultFinality;
    
    constructor(
        address _tokenMessenger,
        address _usdc,
        uint32 _defaultFinality
    ) {
        tokenMessenger = ITokenMessengerV2(_tokenMessenger);
        usdc = IERC20(_usdc);
        defaultFinality = _defaultFinality;
    }
    
    function bridge(
        uint256 amount,
        uint32 destDomain,
        bytes32 recipient
    ) external {
        usdc.transferFrom(msg.sender, address(this), amount);
        usdc.approve(address(tokenMessenger), amount);
        
        // Calculate minimum fee
        uint256 minFeeAmount = tokenMessenger.getMinFeeAmount(amount);
        uint256 maxFee = minFeeAmount > 0 
            ? minFeeAmount + (minFeeAmount / 10)  // 10% buffer
            : 0;
        
        require(maxFee < amount, "Fee too high");
        
        tokenMessenger.depositForBurn(
            amount,
            destDomain,
            recipient,
            address(usdc),
            bytes32(0),          // Any caller
            maxFee,
            defaultFinality
        );
        
        emit Bridged(msg.sender, amount, maxFee);
    }
    
    function bridgeWithHook(
        uint256 amount,
        uint32 destDomain,
        bytes32 recipient,
        bytes calldata hookData
    ) external {
        usdc.transferFrom(msg.sender, address(this), amount);
        usdc.approve(address(tokenMessenger), amount);
        
        uint256 minFeeAmount = tokenMessenger.getMinFeeAmount(amount);
        uint256 maxFee = minFeeAmount > 0
            ? minFeeAmount + (minFeeAmount / 10)
            : 0;
        
        require(maxFee < amount, "Fee too high");
        
        tokenMessenger.depositForBurnWithHook(
            amount,
            destDomain,
            recipient,
            address(usdc),
            bytes32(0),
            maxFee,
            defaultFinality,
            hookData
        );
        
        emit BridgedWithHook(msg.sender, amount, maxFee, hookData);
    }
    
    event Bridged(
        address indexed user,
        uint256 amount,
        uint256 maxFee
    );
    
    event BridgedWithHook(
        address indexed user,
        uint256 amount,
        uint256 maxFee,
        bytes hookData
    );
}

Frontend Integration Changes

ethers.js v6 Example

import { ethers } from 'ethers';

// V1 deposit
async function depositForBurnV1(
  tokenMessenger: Contract,
  amount: bigint,
  destinationDomain: number,
  mintRecipient: string,
  burnToken: string
) {
  const tx = await tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    burnToken
  );
  
  const receipt = await tx.wait();
  const event = receipt.logs
    .map(log => tokenMessenger.interface.parseLog(log))
    .find(e => e?.name === 'DepositForBurn');
  
  return event?.args.nonce;  // Get nonce
}

import { ethers } from 'ethers';

// V2 deposit
async function depositForBurnV2(
  tokenMessenger: Contract,
  amount: bigint,
  destinationDomain: number,
  mintRecipient: string,
  burnToken: string,
  minFinalityThreshold: number = 1000
) {
  // Calculate minimum fee
  const minFee = await tokenMessenger.getMinFeeAmount(amount);
  const maxFee = minFee > 0n ? minFee + (minFee / 10n) : 0n;
  
  if (maxFee >= amount) {
    throw new Error('Amount too low for fee');
  }
  
  const tx = await tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    mintRecipient,
    burnToken,
    ethers.ZeroHash,        // destinationCaller (any)
    maxFee,
    minFinalityThreshold
  );
  
  const receipt = await tx.wait();
  const event = receipt.logs
    .map(log => tokenMessenger.interface.parseLog(log))
    .find(e => e?.name === 'DepositForBurn');
  
  // Note: No nonce in V2
  return {
    txHash: receipt.hash,
    maxFee: event?.args.maxFee,
    hookData: event?.args.hookData
  };
}

Testing Your Migration

Test Checklist

Test Fee Calculation

// Test minimum fee calculation
uint256 amount = 1000000; // 1 USDC
uint256 minFee = tokenMessenger.getMinFeeAmount(amount);
assert(minFee > 0 && minFee < amount);

Test Basic Transfer

// Test basic V2 transfer
usdc.approve(address(tokenMessenger), amount);
tokenMessenger.depositForBurn(
    amount,
    destinationDomain,
    recipientBytes32,
    address(usdc),
    bytes32(0),
    minFee,
    1000
);

Test Hook Transfer

// Test transfer with hook data
bytes memory hookData = abi.encode("TEST", address(this));
tokenMessenger.depositForBurnWithHook(
    amount,
    destinationDomain,
    recipientBytes32,
    address(usdc),
    bytes32(0),
    minFee,
    1000,
    hookData
);

Test Event Parsing

// Verify event structure
const events = await tokenMessenger.queryFilter(
  tokenMessenger.filters.DepositForBurn()
);
const event = events[0];
assert(event.args.maxFee !== undefined);
assert(event.args.minFinalityThreshold === 1000);

Common Migration Issues

Issue: “Insufficient max fee” Error

Cause: maxFee is less than the minimum required fee. Solution: Call getMinFeeAmount() before depositForBurn():

uint256 minFee = tokenMessenger.getMinFeeAmount(amount);
uint256 maxFee = minFee + buffer;
tokenMessenger.depositForBurn(..., maxFee, ...);

Issue: Missing Nonce in V2

Cause: V2 doesn’t return nonce from depositForBurn(). Solution: Use transaction hash or event filtering instead:

const tx = await tokenMessenger.depositForBurn(...);
const receipt = await tx.wait();
const identifier = receipt.hash;  // Use tx hash instead of nonce

Issue: “Caller is denylisted” Error

Cause: Calling address is on the protocol denylist. Solution: Check denylist status:

bool denylisted = tokenMessenger.isDenylisted(msg.sender);
if (denylisted) {
    revert("Address is denylisted");
}

Issue: Wrong destinationCaller Format

Cause: Using address instead of bytes32. Solution: Convert address to bytes32:

// Wrong
tokenMessenger.depositForBurn(..., destinationCallerAddress, ...);

// Correct
bytes32 destinationCaller = bytes32(uint256(uint160(destinationCallerAddress)));
tokenMessenger.depositForBurn(..., destinationCaller, ...);

// Or use any caller
tokenMessenger.depositForBurn(..., bytes32(0), ...);

Next Steps

V2 Deployment

Deploy V2 contracts to your network

TokenMessengerV2 API

Complete V2 API reference

Integration Guide

Build on CCTP V2

Testing Guide

Test your V2 integration

​Overview

​Migration Checklist

​API Changes

​depositForBurn Function

​V1 to V2 Comparison

​Parameter Mapping

​Migration Example

​depositForBurnWithCaller Removal

​replaceDepositForBurn

​Event Changes

​DepositForBurn Event

​Event Structure Comparison

​Migration Impact

​Event Listener Migration

​MintAndWithdraw Event

​Fee Management

​Calculating Fees

​Fee Recipient

​Zero Fee Transfers

​Message Handler Interface

​Interface Changes

​Role Configuration

​Required Role Addresses

​Role Responsibilities

​Contract Interface Differences

​New Functions in V2

​Removed Functions in V2

​Smart Contract Migration Example

​Frontend Integration Changes

​ethers.js v6 Example

​Testing Your Migration

​Test Checklist

​Common Migration Issues

​Issue: “Insufficient max fee” Error

​Issue: Missing Nonce in V2

​Issue: “Caller is denylisted” Error

​Issue: Wrong destinationCaller Format

​Next Steps

V2 Deployment

TokenMessengerV2 API

Integration Guide

Testing Guide

Overview

Migration Checklist

API Changes

depositForBurn Function

V1 to V2 Comparison

Parameter Mapping

Migration Example

depositForBurnWithCaller Removal

replaceDepositForBurn

Event Changes

DepositForBurn Event

Event Structure Comparison

Migration Impact

Event Listener Migration

MintAndWithdraw Event

Fee Management

Calculating Fees

Fee Recipient

Zero Fee Transfers

Message Handler Interface

Interface Changes

Role Configuration

Required Role Addresses

Role Responsibilities

Contract Interface Differences

New Functions in V2

Removed Functions in V2

Smart Contract Migration Example

Frontend Integration Changes

ethers.js v6 Example

Testing Your Migration

Test Checklist

Common Migration Issues

Issue: “Insufficient max fee” Error

Issue: Missing Nonce in V2

Issue: “Caller is denylisted” Error

Issue: Wrong destinationCaller Format

Next Steps