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:
An onchain component on the source domain emits a message.
Circle’s offchain attestation service signs the message.
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.
The relationship between CCTP’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 crosschain burning and minting is
called TokenMessengerV2, which is built on top of MessageTransmitterV2,
an onchain component for generalized message passing.In the diagram, 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:
A CCTP nonce is a unique identifier for a message that can only be used once on
the destination domain. Circle assigns CCTP nonces offchain. The nonce for each
message in a transaction can be queried through the
GET /v2/messages endpoint, using
the transaction hash as a query parameter.
Why bytes32 type for addressesCCTP is built to support EVM chains, which use 20 byte addresses, and non-EVM
chains, many of which use 32 byte addresses. Circle provides a
Message.sol library
as a reference implementation for converting between address and bytes32 in
Solidity.
The message format includes a dynamically sized messageBody field, used for
application-specific messages. For example, TokenMessengerV2 defines a
BurnMessageV2
with data related to crosschain 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
API Service Rate LimitThe 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.
CCTP endpoints enable advanced capabilities 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 public endpoints. Click on any endpoint for its API
reference.
Returns the fees for USDC transfers between specified source and destination domains.
Calculate transaction costs before initiating a Fast or Standard Transfer.
Deprecated endpointThe 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 preceding table), which remains active and valid.
CCTP has 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, 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.
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.
For information about CCTP transfer fees, including fee tables by blockchain,
the maxFee parameter, and Standard Transfer fee switch support, see
CCTP Fees.
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 crosschain compatibility without altering the core CCTP protocol.
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.
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.
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 capabilities
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.
