The top-level message header format is standard for all messages passing through CCTP.
Select the applicable CCTP version below:
| Field | Offset | Solidity Type | Length (bytes) | Description |
|---|---|---|---|---|
| version | 0 | uint32 | 4 | Version identifier (0, for CCTP V1) |
| sourceDomain | 4 | uint32 | 4 | Source domain ID |
| destinationDomain | 8 | uint32 | 4 | Destination domain ID |
| nonce | 12 | uint64 | 8 | Unique message nonce (see Sequential Nonces) |
| sender | 20 | bytes32 | 32 | Address of MessageTransmitter caller on source domain |
| recipient | 52 | bytes32 | 32 | Address to handle message body on destination domain |
| destinationCaller | 84 | bytes32 | 32 | Address permitted to call MessageTransmitter on destination domain, or bytes32(0) if message can be received by any address |
| messageBody | 116 | bytes | dynamic | Application-specific message to be handled by recipient |
A message nonce is a unique identifier for a message that can only be used once on the destination domain. In CCTP V1, message nonces are implemented using Sequential Nonces, where the next available nonce on a source domain is an integer. On the destination domain, messages can be received in any order, and used nonces are stored as a hash of the source domain and nonce integer value.
| Field | Offset | Solidity Type | Length (bytes) | Description |
|---|---|---|---|---|
| version | 0 | uint32 | 4 | Version identifier (1, for CCTP V2) |
| sourceDomain | 4 | uint32 | 4 | Source domain ID |
| destinationDomain | 8 | uint32 | 4 | Destination domain ID |
| nonce | 12 | bytes32 | 32 | Unique message nonce (see Deterministic 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 Finality Thresholds) |
| finalityThresholdExecuted | 144 | uint32 | 4 | Actual finality threshold executed from source chain (see Finality Thresholds) |
| messageBody | 148 | bytes | dynamic | Application-specific message to be handled by recipient |
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 via 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.
The message format includes a dynamically sized messageBody field, used for
application-specific messages. For example, TokenMessenger defines a
BurnMessage
with data related to cross-chain transfers.
Select the applicable CCTP version below:
| Field | Offset | Solidity Type | Length (bytes) | Description |
|---|---|---|---|---|
| version | 0 | uint32 | 4 | Version identifier (0, for CCTP V1) |
| 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 |
| Field | Offset | Solidity Type | Length (bytes) | Description |
|---|---|---|---|---|
| version | 0 | uint32 | 4 | Version identifier (1, for CCTP V2) |
| 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 |
