MessageTransmitter

Contract responsible for sending and receiving messages across chains

Overview

The MessageTransmitter contract is the core component of CCTP that handles cross-chain message transmission. It manages message dispatch, receipt, and validation, ensuring secure communication between different blockchain domains.

State Variables

localDomain · uint32 · required

Domain of the chain on which the contract is deployed. This is an immutable value set during contract deployment.

version · uint32 · required

Message format version. This is an immutable value that defines the structure of messages handled by this contract.

maxMessageBodySize · uint256 · required

Maximum size of message body in bytes. This value can be updated by the contract owner to accommodate larger messages.

nextAvailableNonce · uint64 · required

Next available nonce from this source domain. This counter increments with each message sent to ensure uniqueness.

Functions

sendMessage

Sends a message to the destination domain and recipient.

function sendMessage(
    uint32 destinationDomain,
    bytes32 recipient,
    bytes calldata messageBody
) external returns (uint64)

destinationDomain · uint32 · required

Domain of destination chain

recipient · bytes32 · required

Address of message recipient on destination chain as bytes32

messageBody · bytes · required

Raw bytes content of message

Returns: uint64 - The nonce reserved by the message

Behavior:

• Increments the nonce counter
• Formats the message with version, domains, nonce, sender, and recipient
• Emits a MessageSent event with the complete message
• Reverts if the contract is paused
• Reverts if message body exceeds maxMessageBodySize

sendMessageWithCaller

Sends a message to the destination domain and recipient, specifying a destinationCaller that is authorized to receive the message on the destination domain.

function sendMessageWithCaller(
    uint32 destinationDomain,
    bytes32 recipient,
    bytes32 destinationCaller,
    bytes calldata messageBody
) external returns (uint64)

destinationDomain · uint32 · required

Domain of destination chain

recipient · bytes32 · required

Address of message recipient on destination chain as bytes32

destinationCaller · bytes32 · required

Caller on the destination domain, as bytes32. Must be nonzero.

messageBody · bytes · required

Raw bytes content of message

Returns: uint64 - The nonce reserved by the message

If the destinationCaller does not represent a valid address, it will not be possible to broadcast the message on the destination domain. This is an advanced feature - the standard sendMessage() should be preferred for most use cases.

receiveMessage

Receives a message from a source domain. Messages with a given nonce can only be broadcast once for a (sourceDomain, destinationDomain) pair.

function receiveMessage(
    bytes calldata message,
    bytes calldata attestation
) external returns (bool success)

message · bytes · required

Message bytes containing:

• version (4 bytes, uint32)
• sourceDomain (4 bytes, uint32)
• destinationDomain (4 bytes, uint32)
• nonce (8 bytes, uint64)
• sender (32 bytes, bytes32)
• recipient (32 bytes, bytes32)
• destinationCaller (32 bytes, bytes32)
• messageBody (dynamic bytes)

attestation · bytes · required

Concatenated 65-byte signature(s) of message, in increasing order of the attester address recovered from signatures. Must contain exactly the threshold number of valid signatures.

Returns: bool - true if successful

Message Format:

Field	Bytes	Type	Index
version	4	uint32	0
sourceDomain	4	uint32	4
destinationDomain	4	uint32	8
nonce	8	uint64	12
sender	32	bytes32	20
recipient	32	bytes32	52
destinationCaller	32	bytes32	84
messageBody	dynamic	bytes	116

Validation:

• Verifies attestation signatures
• Validates message format
• Checks destination domain matches local domain
• Validates destination caller (if specified)
• Validates message version
• Ensures nonce has not been used before
• Marks nonce as used upon successful receipt
• Calls handleReceiveMessage() on the recipient contract

Attestations must have signatures in increasing order of attester address. If signatures are not in order, or if there are duplicate or incorrect number of signatures, verification will fail.

replaceMessage

Replaces a message with a new message body and/or destination caller. Allows the sender of a previous message to send a new message with the same nonce.

function replaceMessage(
    bytes calldata originalMessage,
    bytes calldata originalAttestation,
    bytes calldata newMessageBody,
    bytes32 newDestinationCaller
) external

originalMessage · bytes · required

Original message to replace

originalAttestation · bytes · required

Valid attestation of originalMessage

newMessageBody · bytes · required

New message body of replaced message

newDestinationCaller · bytes32 · required

The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller (bytes32(0), indicating that any destination caller is valid)

Behavior:

• Validates the original attestation signatures
• Verifies msg.sender matches the sender of the original message
• Verifies the source domain of the original message matches local domain
• Reuses the original message’s nonce
• Emits a new MessageSent event with the replacement message

The new message will reuse the original message’s nonce. For a given nonce, all replacement message(s) and the original message are valid to broadcast on the destination domain, until the first message at the nonce confirms, at which point all others are invalidated.

setMaxMessageBodySize

Sets the maximum message body size. Only callable by the contract owner.

function setMaxMessageBodySize(
    uint256 newMaxMessageBodySize
) external

newMaxMessageBodySize · uint256 · required

New maximum message body size, in bytes

This value should not be reduced without good reason, to avoid impacting users who rely on large messages.

Events

MessageSent

Emitted when a new message is dispatched.

event MessageSent(bytes message)

message · bytes

Raw bytes of the complete message including all headers and body

MessageReceived

Emitted when a new message is received.

event MessageReceived(
    address indexed caller,
    uint32 sourceDomain,
    uint64 indexed nonce,
    bytes32 sender,
    bytes messageBody
)

caller · address

Caller (msg.sender) on destination domain

sourceDomain · uint32

The source domain this message originated from

nonce · uint64

The nonce unique to this message

sender · bytes32

The sender of this message

messageBody · bytes

Message body bytes

MaxMessageBodySizeUpdated

Emitted when the maximum message body size is updated.

event MaxMessageBodySizeUpdated(uint256 newMaxMessageBodySize)

newMaxMessageBodySize · uint256

New maximum message body size, in bytes