Contract responsibilities
- TokenMessengerV2: Entrypoint for crosschain USDC transfer. Routes messages to burn USDC on a source chain, and mint USDC on a destination chain.
- MessageTransmitterV2: Generic message passing. Sends all messages on the source chain, and receives all messages on the destination chain.
- TokenMinterV2: Responsible for minting and burning USDC. Contains chain-specific settings used by burners and minters.
- MessageV2: Provides helper functions for crosschain transfers, such as
bytes32ToAddressandaddressToBytes32, which are commonly used when bridging between EVM and non-EVM chains. These conversions are simple: prepend 12 zero bytes to an EVM address, or strip them to convert back.
Note: If you’re writing your own integration, it’s more gas-efficient to
include this logic directly in your
contract
rather than calling an external one.
Mainnet contract addresses
TokenMessengerV2: Mainnet
MessageTransmitterV2: Mainnet
TokenMinterV2: Mainnet
MessageV2: Mainnet
Testnet contract addresses
TokenMessengerV2: Testnet
MessageTransmitterV2: Testnet
TokenMinterV2: Testnet
MessageV2: Testnet
CCTP Interface
This section provides the Smart Contract Interface exposed by CCTP, outlining the available functions, and their parameters. The interface below serves as a reference for permissionless messaging functions exposed by the TokenMessengerV2 and MessageTransmitterV2 functions.TokenMessengerV2
depositForBurn
Deposits and burns tokens from sender to be minted on destination domain, and emits a crosschain message by calling MessageTransmitter’ssendMessage
function. Minted tokens will be transferred to mintRecipient.
Note: There is a $10 million limit on the amount of USDC that can be burned
in a single CCTP transaction. If the amount exceeds this limit, the transaction
will revert. If you need to transfer more than this limit, break up your
transfers into multiple transactions.For Fast Transfers, you should always
check the remaining allowance
before initiating a transfer to ensure there is enough to complete your
transfer.
| Field | Type | Description |
|---|---|---|
amount | uint256 | Amount of tokens to deposit and burn |
destinationDomain | uint32 | Destination domain ID to send the message to |
mintRecipient | bytes32 | Address of mint recipient on destination domain (must be converted to 32 byte array, that is, prefix with zeros if needed) |
burnToken | address | Address of contract to burn deposited tokens on local domain |
destinationCaller | bytes32 | Address as bytes32 which can call receiveMessage on destination domain. If set to bytes32(0), any address can call receiveMessage |
maxFee | uint256 | Max fee paid for fast burn, specified in units of burnToken |
minFinalityThreshold | uint32 | Minimum finality threshold at which burn will be attested |
depositForBurnWithHook
Deposits and burns tokens from sender to be minted on destination domain, and emits a crosschain message with additional hook data appended. In addition to the standarddepositForBurn parameters, depositForBurnWithHook accepts a
dynamic-length hookData parameter, allowing the caller to include additional
metadata to the attested message, which can be used to trigger custom logic on
the destination chain.
Note: There is a $10 million limit on the amount of USDC that can be burned
in a single CCTP transaction. If the amount exceeds this limit, the transaction
will revert. If you need to transfer more than this limit, break up your
transfers into multiple transactions.For Fast Transfers, you should always
check the remaining allowance
before initiating a transfer to ensure there is enough to complete your
transfer.
| Field | Type | Description |
|---|---|---|
amount | uint256 | Amount of tokens to burn |
destinationDomain | uint32 | Destination domain to send the message to |
mintRecipient | bytes32 | Address of mint recipient on destination domain (must be converted to 32 byte array, that is, prefix with zeros if needed) |
burnToken | address | Address of contract to burn deposited tokens on local domain |
destinationCaller | bytes32 | Address as bytes32 which can call receiveMessage on destination domain. If set to bytes32(0), any address can call receiveMessage |
maxFee | uint256 | Max fee paid for fast burn, specified in units of burnToken |
minFinalityThreshold | uint32 | Minimum finality threshold at which burn will be attested |
hookData | bytes | Additional metadata attached to the attested message, which can be used to trigger custom logic on the destination chain |
getMinFeeAmount
Calculates and returns the minimum fee required for a given amount in a Standard Transfer. If theminFee (per unit of burnToken) is non-zero, the specified
maxFee must be at least the returned minimum fee. Otherwise, the burn will
revert onchain.
Parameters
| Field | Type | Description |
|---|---|---|
amount | uint256 | The amount used to compute the minimum fee. Must be greater than 1 if standard fee is applied |
handleReceiveFinalizedMessage
Handles incoming message received by the local MessageTransmitter, and takes the appropriate action. For a burn message, mints the associated token to the requested recipient on the local domain. Validates the function sender is the local MessageTransmitter, and the remote sender is a registered remote TokenMessenger forremoteDomain.
Parameters
| Field | Type | Description |
|---|---|---|
remoteDomain | uint32 | The domain where the message originated from |
sender | bytes32 | The sender of the message (remote TokenMessenger) |
finalityThresholdExecuted | uint32 | Specifies the level of finality Iris signed the message with |
messageBody | bytes (dynamic length) | The message body bytes |
handleReceiveUnfinalizedMessage
Handles incoming message received by the local MessageTransmitter, and takes the appropriate action. For a burn message, mints the associated token to the requested recipient on the local domain. Validates the function sender is the local MessageTransmitter, and the remote sender is a registered remote TokenMessenger forremoteDomain.
Similar to handleReceiveFinalizedMessage, but is called for messages which are
not finalized (finalityThresholdExecuted < 2000).
Unlike handleReceiveFinalizedMessage, handleReceiveUnfinalizedMessage has
the following messageBody parameters:
expirationBlock. IfexpirationBlock≤blockNumberon the destination domain, the message will revert and must be re-signed without the expiration block.feeExecuted. If nonzero, thefeeExecutedis minted to thefeeRecipient.
| Field | Type | Description |
|---|---|---|
remoteDomain | uint32 | The domain where the message originated from |
sender | bytes32 | The sender of the message (remote TokenMessenger) |
finalityThresholdExecuted | uint32 | Specifies the level of finality Iris signed the message with |
messageBody | bytes (dynamic length) | The message body bytes (see Message format) |
MessageTransmitterV2
receiveMessage
Receive message on destination chain by passing message and attestation. EmitsMessageReceived event. Messages with a given nonce can only be broadcast
successfully once for a pair of domains. The message body of a valid message is
passed to the specified recipient for further processing.
Parameters
| Field | Type | Description |
|---|---|---|
message | bytes | Encoded message (see Message format) |
attestation | bytes | Signed attestation received from attestation service (Iris) |
sendMessage
Sends a message to the recipient on the destination domain. Emits aMessageSent event which will be attested by Circle’s attestation service.
Parameters
| Field | Type | Description |
|---|---|---|
destinationDomain | uint32 | Destination domain ID to send the message to |
recipient | bytes32 | Address of recipient on destination domain |
destinationCaller | bytes32 | Address as bytes32 which can call receiveMessage on destination domain. If set to bytes32(0), any address can call receiveMessage |
minFinalityThreshold | uint32 | Minimum finality threshold requested. Initially, supported values for minFinalityThreshold are [1, 2000]. A value outside of the support values range will be interpreted as 2000 (finalized) by the attestation service (Iris). For a value within the supported range, the attestation service (Iris) will attest the message with a finalityThresholdExecuted >= minFinalityThreshold. Initial thresholds supported: 1000: Confirmed 2000: Finalized |
messageBody | bytes | App-specific message to be handled by recipient |