CCTP Technical Guide

Technical explainer for CCTP V2

CCTP V2 Message Passing

Cross-Chain Transfer Protocol (CCTP) uses generalized message passing to facilitate the native burning and minting of USDC across supported blockchains, also known as domains. Message passing is a three-step process:

1. An onchain component on the source domain emits a message.
2. Circle’s offchain attestation service signs the message.
3. The onchain component at the destination domain receives the message, and forwards the message body to the specified recipient.

Onchain components serve the same purpose across all domains, but their implementations differ between EVM-compatible and non-EVM domains. Moreover, there are both implementation and naming differences between CCTP V2 and previous versions due to the addition of Fast Transfer and other improvements.

For EVM Chains

The relationship between CCTP V2’s onchain components and Circle’s offchain Attestation Service is illustrated below for a burn-and-mint of USDC between EVM-compatible domains:

On EVM domains, the onchain component for cross-chain burning and minting is called TokenMessengerV2, which is built on top of MessageTransmitterV2, an onchain component for generalized message passing.

In the diagram above, a token depositor calls the TokenMessengerV2#depositForBurn function to deposit a native token (such as USDC), which delegates to the TokenMinterV2 contract to burn the token. The TokenMessengerV2 contract then sends a message via the MessageTransmitterV2#sendMessage function. After sufficient block confirmations, Circle’s offchain attestation service, Iris, signs the message. An API consumer must query this attestation and submits it onchain to the destination domain’s MessageTransmitterV2#receiveMessage function.

To send an arbitrary message, directly call MessageTransmitterV2#sendMessage. The message recipient must implement the following methods to handle messages based on their finality threshold:

• Implement IMessageHandlerV2#handleReceiveFinalizedMessage to receive messages with finalityThresholdExecuted ≥ 2000.
• Implement IMessageHandlerV2#handleReceiveUnfinalizedMessage to receive messages with finalityThresholdExecuted < 2000.

This distinction allows the recipient to control the level of finality it requires before accepting a message.

For Non-EVM Chains

CCTP is also available on several non-EVM blockchains where USDC is natively issued, extending cross-chain functionality to the broader ecosystem. While most non-EVM domains support CCTP V1, Circle is expanding support to include later CCTP versions.

CCTP V2 Message Format

Message Header

The top-level message header format is standard for all messages passing through CCTP.

Field	Offset	Solidity Type	Length (bytes)	Description
version	0	uint32	4	Version identifier - use 1 for CCTP
sourceDomain	4	uint32	4	Source domain ID
destinationDomain	8	uint32	4	Destination domain ID
nonce	12	bytes32	32	Unique message nonce (see CCTP V2 Nonces)
sender	44	bytes32	32	Address of MessageTransmitterV2 caller on source domain
recipient	76	bytes32	32	Address to handle message body on destination domain
destinationCaller	108	bytes32	32	Address permitted to call MessageTransmitterV2 on destination domain, or bytes32(0) if message can be received by any address
minFinalityThreshold	140	uint32	4	Minimum finality threshold before allowed to attest (see CCTP V2 Finality Thresholds)
finalityThresholdExecuted	144	uint32	4	Actual finality threshold executed from source chain (see CCTP V2 Finality Thresholds)
messageBody	148	bytes	dynamic	Application-specific message to be handled by recipient

CCTP V2 Nonces

A CCTP V2 nonce is a unique identifier for a message that can only be used once on the destination domain. Circle assigns CCTP V2 nonces offchain. The nonce for each message in a transaction can be queried through the /v2/messages API, using the transaction hash as a query parameter.

Why we use bytes32 type for addresses

CCTP is built to support EVM chains, which use 20 byte addresses, and non-EVM chains, many of which use 32 byte addresses. We provide a Message.sol library as a reference implementation for converting between address and bytes32 in Solidity.

Message Body

The message format includes a dynamically sized messageBody field, used for application-specific messages. For example, TokenMessengerV2 defines a BurnMessageV2 with data related to cross-chain transfers.

Field	Offset	Solidity Type	Length (bytes)	Description
version	0	uint32	4	Version identifier - use 1 for CCTP
burnToken	4	bytes32	32	Address of burned token on source domain
mintRecipient	36	bytes32	32	Address to receive minted tokens on destination domain
amount	68	uint256	32	Amount of burned tokens
messageSender	100	bytes32	32	Address of caller of depositForBurn (or depositForBurnWithCaller) on source domain
maxFee	132	uint256	32	Maximum fee to pay on the destination domain, specified in units of burnToken
feeExecuted	164	uint256	32	Actual fee charged on the destination domain, specified in units of burnToken (capped by maxFee)
expirationBlock	196	uint256	32	An expiration block 24 hours in the future is encoded in the message before signing by attestation service, and is respected on the destination chain. If the burn expires, it must be re-signed. Expiration acts as a safety mechanism against problems with finalization, such as a stuck sequencer.
hookData	228	bytes	dynamic	Arbitrary data to be included in the depositForBurn on source domain and to be executed on destination domain

CCTP V2 API Hosts and Endpoints

CCTP provides a set of API hosts and endpoints to manage messages, attestations, and transaction details for your cross-chain USDC transfers.

API Service Hosts

Environment	URL
Testnet	https://iris-api-sandbox.circle.com
Mainnet	https://iris-api.circle.com

API Service Rate Limit

The CCTP API service rate limit is 35 requests per second. If you exceed 35 requests per second, the service blocks all API requests for the next 5 minutes and returns an HTTP 429 response.

API Endpoints

CCTP V2 endpoints enable advanced functionality such as fetching attestations for Standard Transfer or Fast Transfer burn events, verifying public keys across versions, accessing transaction details, querying fast transfer allowances and fees, and initiating re-attestation processes. Below is an overview of the CCTP V2 public endpoints. Click on any endpoint for its API reference.

Endpoint	Description	Use Case
GET /v2/publicKeys	Returns public keys for validating attestations across all supported CCTP versions.	Retrieve public keys to verify attestation authenticity for cross-chain transactions.
GET /v2/messages	Retrieves messages and attestations for a given transaction or nonce, supporting messages for all CCTP versions.	Fetch attestation status and transaction details.
POST /v2/reattest	Re-attests a soft finality V2 message to achieve finality or revive expired Fast Transfer burns.	Handle edge cases requiring updated attestations or finalize transactions with stricter rules.
GET /v2/fastBurn/USDC/allowance	Retrieves the current USDC Fast Transfer allowance remaining.	Monitor available allowance for Fast Transfer burns in real-time.
GET /v2/burn/USDC/fees	Returns the fees for USDC transfers between specified source and destination domains.	Calculate transaction costs before initiating a Fast or Standard Transfer.

Deprecated endpoint

The endpoint /v2/fastBurn/USDC/fees is deprecated. Use /v2/burn/USDC/fees instead to retrieve both Fast and Standard Transfer fees.

Note: This deprecation does not affect /v2/fastBurn/USDC/allowance (see table above), which remains active and valid.

CCTP V2 Finality Thresholds

CCTP V2 introduces the concept of a finality threshold, which is a chain-agnostic representation of the confirmation level required before an attestation is issued. This allows integrators to specify how many confirmations are needed based on their risk tolerance or use case.

In CCTP V2, each message specifies a minFinalityThreshold. This threshold indicates the minimum level of confirmation required for Circle’s attestation service (Iris) to attest to the message. Iris will not attest to a message at a confirmation level below the specified minimum threshold. This allows applications to enforce a desired level of finality before acting on an attestation on the destination chain.

Defined Finality Thresholds

CCTP V2 defines the following finality thresholds:

Finality Threshold	Value
Confirmed	1000
Finalized	2000

Messages and Finality

• Messages with a minFinalityThreshold of 1000 or lower are considered Fast messages. These messages are eligible for fast attestation at the confirmed level by Iris.
• Messages with a minFinalityThreshold of 2000 are considered Standard messages. These messages are attested to at the finalized level by Iris.

Only two finality thresholds are supported. Any minFinalityThreshold value below 1000 is treated as 1000, and any value above 1000 is treated as 2000.

CCTP V2 Fees

For CCTP V2 transfers, a fee is collected onchain at the time of USDC minting. Retrieve the applicable fee by calling the API every time before executing a transaction. Fees are subject to change with advance notice. See the table below for rates.

• The maxFee parameter in depositForBurn specifies the maximum fee that can be charged during minting.
  • If maxFee is less than the minimum Standard Transfer fee, the burn reverts onchain.
  • If maxFee is equal to or greater than the minimum Fast Transfer fee and minFinalityThreshold is 1000 or lower, the attestation is eligible for Fast Transfer. In this case, the Fast Transfer fee (which varies by chain) is charged onchain at minting.
• If the attestation results in a Standard Transfer—for example, because maxFee is below the Fast Transfer fee or minFinalityThreshold is greater than 1000—the Standard Transfer fee is charged onchain at minting.

The minimumFee field in the /v2/burn/USDC/fees response represents the required fee rate in basis points (bps). To calculate the maxFee to include in depositForBurn, multiply this value by the amount to be transferred.

CCTP V2 Fast Transfer Fee

Source chain	Fee
Arbitrum	1 bps (0.01%)
Base	1 bps (0.01%)
Codex	1 bps (0.01%)
Ethereum	1 bps (0.01%)
Ink	2 bps (0.02%)
Linea	14 bps (0.14%)
OP Mainnet	1 bps (0.01%)
Plume	2 bps (0.02%)
Solana	1 bps (0.01%)
Unichain	1 bps (0.01%)
World Chain	1 bps (0.01%)

Note: Chains without Fast Transfer fees

Some chains don’t appear in the Fast Transfer fee table because their standard attestation times are already very fast. Consequently, Fast Transfer is not applicable when these chains are used as the source chain for burns.

Affected chains: Avalanche, HyperEVM, Polygon PoS, Sei, Sonic, XDC.

Standard Transfer Fee Switch

Some chains support a Standard Transfer fee switch, which enables enforcing a minimum fee during a CCTP V2 Standard Transfer.

• Some deployments of the TokenMessengerV2 contract include a fee switch that enforces a minimum onchain fee. This fee is collected during USDC minting in a Standard Transfer. See tables below for supported chains.
• TokenMessengerV2 contracts with fee switch support include the getMinFeeAmount function, which calculates and returns the minimum fee required for a given burn amount, in units of the burnToken.

Important:
Calling getMinFeeAmount on a chain that uses an older TokenMessengerV2 contract (without fee switch support) will result in an error. Refer to the tables below to determine which contract version is deployed on each EVM chain.

CCTP V2 TokenMessenger Contracts (No Standard Transfer Fee Switch support)

Source Chain	Contract Source Code
Arbitrum	7d70310
Avalanche	7d70310
Base	7d70310
Codex	7d70310
Ethereum	7d70310
Linea	7d70310
OP Mainnet	7d70310
Polygon POS	7d70310
Sonic	7d70310
Unichain	7d70310
World Chain	7d70310

CCTP V2 TokenMessenger Contracts (with Standard Transfer Fee Switch support)

Source Chain	Contract Source Code
Sei	2f9a2ba

CCTP V2 Hooks

Hooks in CCTP V2 are metadata that can be attached to a burn message, allowing integrators to execute custom logic at the destination chain. Hook execution is left entirely to the integrator, offering maximum flexibility and enabling broader cross-chain compatibility without altering the core CCTP protocol.

Design overview

CCTP does not implement hook execution in the core protocol. Instead, hooks are treated as opaque metadata passed along with the burn message. This design allows integrators to define and control how hooks are processed on the destination chain, based on their own infrastructure and trust model.

Key benefits

• Maximum flexibility for integrators

  • Determine execution timing: pre-mint or post-mint
  • Implement custom recovery or error-handling strategies if hook execution fails
  • Choose any execution environment (EVM or non-EVM); even non-EVM chains can support Hooks as data passed into a function call.

• Consistency with the destinationCaller pattern

  • CCTP V2 continues the destinationCaller model from CCTP V1.
  • In most integrations, the destinationCaller is expected to handle hook execution, making it a natural extension of an existing pattern familiar to integrators.

• Improved Compliance and Security Separation

  • Compliance: By delegating hook execution to the integrator, the protocol maintains a clear boundary between CCTP’s core message-passing functionality and application-specific logic. This modular approach helps integrators meet their own compliance requirements with greater flexibility.
  • Security: By keeping hook execution outside the core protocol, CCTP maintains a smaller and more focused security surface, while allowing integrators to manage their own execution environments independently.

WHAT’S NEXT

• CCTP FAQ