Skip to main content

​
What’s New in V2

Version 2 of the EVM CCTP Contracts introduces significant enhancements to the Cross-Chain Transfer Protocol while maintaining backward compatibility in the core message transmission architecture. V2 focuses on fee mechanisms, security features, and execution flexibility.

​
Key Improvements Over V1

Fee Mechanism

Support for destination domain fees with configurable minimum fees and fee recipients

Finality Thresholds

Messages can specify minimum finality requirements (500, 1000, or 2000) for flexible security/speed tradeoffs

Hook Execution

Optional hookData parameter enables custom logic execution on the destination domain

Denylist Support

Protocol-level denylist functionality to prevent malicious actors from using the system

​
Architectural Changes

​
Contract Structure

V2 introduces a modular architecture with base contracts: 
TokenMessengerV2
└── BaseTokenMessenger
    ├── Rescuable
    ├── Denylistable
    └── Initializable

TokenMinterV2
└── TokenMinter (V1)
    └── ... (existing hierarchy)

MessageTransmitterV2
└── BaseMessageTransmitter
    └── ... (existing hierarchy)

​
Proxy Pattern

V2 contracts use the proxy pattern for upgradeability:
  • Implementation Contracts: Contain all business logic
  • Proxy Contracts: Deployed via CREATE2 for deterministic addresses across chains
  • Create2Factory: Deploys all proxies to ensure consistent addresses
Reference: src/v2/Create2Factory.sol

​
New Message Format

V2 introduces an enhanced burn message format that includes:
  • maxFee: Maximum fee willing to pay on destination domain
  • hookData: Optional data for hook execution
  • expirationBlock: Message expiration (optional)
The message body version remains separate from V1 to distinguish message formats. Reference: src/messages/v2/BurnMessageV2.sol

​
Fee Mechanism

​
How Fees Work

  1. Source Domain: User specifies maxFee in depositForBurn()
  2. Minimum Fee Validation: Contract validates maxFee >= minFeeAmount
  3. Destination Domain: Actual fee is determined by relayer/broadcaster
  4. Fee Collection: Fees are minted to the feeRecipient address
  5. Recipient Amount: User receives amount - fee

​
Fee Calculation

minFeeAmount = (amount * minFee) / MIN_FEE_MULTIPLIER
Where:
  • MIN_FEE_MULTIPLIER = 10,000,000 (enables 1/1000 basis point precision)
  • minFee is configurable by the minFeeController
Example: If minFee = 5000 (0.05%): 
Amount: 1,000,000 (1 USDC)
minFeeAmount = (1,000,000 * 5000) / 10,000,000 = 500 (0.0005 USDC)
Reference: src/v2/BaseTokenMessenger.sol:314-319

​
Finality Thresholds

V2 introduces three levels of finality:
Maximum Security: Messages attested at finalized threshold provide the highest security guarantees. No fees are charged for finalized messages.
  • Use for high-value transfers
  • Longer attestation wait time
  • Zero fee requirement
Balanced: Confirmed finality provides good security with moderate wait times.
  • Suitable for most transfers
  • Moderate attestation time
  • Fees apply
Fast Execution: TokenMessenger accepts minimum finality of 500 for fastest execution.
  • Use for low-value or time-sensitive transfers
  • Fastest attestation time
  • Fees apply
  • Lower security guarantees
Reference: src/v2/FinalityThresholds.sol

​
Hook Execution

V2 enables custom logic on the destination domain through the hookData parameter: 
// Deposit with hook
tokenMessenger.depositForBurnWithHook(
    amount,
    destinationDomain,
    recipientAddress,
    address(usdc),
    bytes32(0),
    maxFee,
    minFinalityThreshold,
    customHookData  // Interpreted by recipient contract
);

​
Hook Use Cases

  • Automated Swaps: Hook data triggers DEX swap on destination
  • NFT Claims: Hook data specifies NFT to mint after transfer
  • Conditional Transfers: Hook data defines conditions for fund release
  • Multi-Step Workflows: Hook data orchestrates complex operations
Hook data is application-specific and must be interpreted by the recipient contract or relayer on the destination domain.

​
Denylist Functionality

V2 introduces protocol-level denylist support:
  • Denylister Role: Authorized address can add/remove denylisted addresses
  • Caller Protection: Denylisted addresses cannot call depositForBurn or depositForBurnWithHook
  • Transparent: Denylist is stored on-chain and publicly verifiable
// Add to denylist (denylister only)
tokenMessenger.addToDenylist(maliciousAddress);

// Remove from denylist (denylister only)
tokenMessenger.removeFromDenylist(address);
Reference: src/roles/v2/Denylistable.sol

​
New Roles in V2

V2 introduces additional administrative roles:
RoleResponsibilitiesV1 Equivalent
feeRecipientReceives collected feesN/A (new)
denylisterManages protocol denylistN/A (new)
minFeeControllerSets minimum fee requirementsN/A (new)
ownerGeneral administrationSame
rescuerEmergency token recoverySame
pauserEmergency pauseSame
attesterManagerManages attestersSame
tokenControllerManages token pairsSame

​
When to Use V2 vs V1

​
Use V2 When:

  • ✅ You need fee collection capabilities
  • ✅ You want flexible finality requirements
  • ✅ You need hook execution for custom logic
  • ✅ You require denylist functionality
  • ✅ You want deterministic cross-chain addresses (CREATE2)
  • ✅ You need upgradeability through proxy pattern

​
Use V1 When:

  • ✅ You need simple burn-and-mint without fees
  • ✅ You don’t require hook execution
  • ✅ You prefer non-upgradeable contracts
  • ✅ You’re integrating with existing V1 deployments

​
Backward Compatibility

V2 maintains compatibility with V1 in the following ways:
  • Message Format: V1 and V2 use different message body versions
  • Message Transmitters: V1 MessageTransmitters cannot process V2 messages
  • Token Minter: V2 extends V1 TokenMinter with dual-recipient mint capability
  • Separate Deployments: V1 and V2 can coexist on the same chain
V1 and V2 are separate protocol deployments. Messages created in V1 cannot be received by V2 contracts and vice versa.

​
Next Steps

What's New

Detailed feature breakdown and technical changes

Migration Guide

Step-by-step guide for migrating from V1 to V2

Deployment

Deploy V2 contracts to your network

API Reference

Complete V2 contract API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us