CCTP Solana Programs and Interfaces

Solana CCTP programs are written in Rust and leverage the Anchor framework. The Solana CCTP V2 protocol implementation is split into two programs: MessageTransmitterV2 and TokenMessengerMinterV2. TokenMessengerMinterV2 encapsulates the functionality of both TokenMessengerV2 and TokenMinterV2 contracts on EVM chains. To ensure alignment with EVM contracts' logic and state, and to facilitate future upgrades and maintenance, the code and state of Solana programs reflect the EVM counterparts as closely as possible.

The Solana CCTP source code is available on GitHub. The interface below serves as a reference for permissionless messaging functions exposed by the programs.

The interface below serves as a reference for permissionless messaging functions exposed by the TokenMessengerMinter and MessageTransmitter programs. The full IDLs can be found onchain using a block explorer. MessageTransmitterV2 IDL and TokenMessengerMinterV2 IDL.

Please see the instruction rust files or quick-start for PDA information.

• TokenMessengerMinterV2#deposit_for_burn_with_hook (extends deposit_for_burn by adding hook data)
• TokenMessengerMinterV2#handle_receive_unfinalized_message (replaces handle_receive_message)
• TokenMessengerMinterV2#handle_receive_finalized_message (replaces handle_receive_message)

• TokenMessengerMinterV2#deposit_for_burn
• MessageTransmitterV2#send_message
• MessageTransmitterV2#receive_message
• MessageTransmitterV2#reclaim_event_account (5 day waiting window added, see TokenMessengerMinterV2 section for more information)

• TokenMessengerV2#handle_receive_message
• TokenMessengerV2#replace_deposit_for_burn
• TokenMessengerV2#deposit_for_burn_with_caller
• MessageTransmitterV2#replace_message
• MessageTransmitterV2#send_message_with_caller

depositForBurn

Deposits and burns tokens from sender to be minted on destination domain. Minted tokens will be transferred to mintRecipient.

Parameters

depositForBurnWithHook

Deposits and burns tokens from sender to be minted on destination domain, and emits a cross-chain message with additional hook data appended. In addition to the standard deposit_for_burn parameters, deposit_for_burn_with_hook 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.

Parameters

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 for remoteDomain.

Additionally, reads the feeExecuted parameter from the BurnMessage. If nonzero, the feeExecuted amount is minted to the feeRecipient.

Parameters

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 for remoteDomain.

Similar to handleReceiveFinalizedMessage, but is called for messages which are not finalized (finalityThresholdExecuted < 2000).

Unlike handleReceiveFinalizedMessage, handleReceiveUnfinalizedMessage has the following messageBody parameter:

• expirationBlock. If expirationBlock ≤ blockNumber on the destination domain, the message will revert and must be re-signed without the expiration block.

Parameters

receiveMessage

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

Remaining Accounts

If the receiveMessage instruction is being called with a deposit for burn message that will be received by the TokenMessengerMinterV2, additional remainingAccounts are required so they can be passed with the CPI to TokenMessengerMinter#handle_receive_finalized_message or TokenMessengerMinter#handle_receive_unfinalized_message:

sendMessage

Sends a message to the destination domain and recipient. Stores message in a MessageSent account which will be attested by Circle's attestation service.

Parameters

These notes are applicable to all CCTP versions.

When calling depositForBurn on a non-Solana chain with Solana as the destination, the mintRecipient should be a hex encoded USDC token account address. The token account* must exist at the time receiveMessage is called on Solana* or else this instruction will revert. An example of converting an address from Base58 to hex taken from the Solana quickstart tutorial in Typescript can be seen below:

import { bs58 } from "@coral-xyz/anchor/dist/cjs/utils/bytes";
import { hexlify } from "ethers";

const solanaAddressToHex = (solanaAddress: string): string =>
  hexlify(bs58.decode(solanaAddress));

When specifying the mintRecipient for Solana deposit_for_burn instruction calls, the address must be given as the 32 byte version of the hex address in base58 format. An example taken from the Solana quickstart tutorial in Typescript can be seen below:

import { getBytes } from "ethers";
import { PublicKey } from "@solana/web3.js";

const evmAddressToBytes32 = (address: string): string =>
  `0x000000000000000000000000${address.replace("0x", "")}`;

const evmAddressToBase58PublicKey = (addressHex: string): PublicKey =>
  new PublicKey(getBytes(evmAddressToBytes32(addressHex)));

Program events like DepositForBurn , MintAndWithdraw , and MessageReceived are emitted as Anchor CPI events. This means a self-CPI is made into the program with the serialized event as instruction data so it is persisted in the transaction and can be fetched later on as needed. More information can be seen in the Anchor implementation PR, and an example of reading CPI events can be seen in the solana-cctp-contracts repository.

MessageSent events are different, as they are stored in accounts. Please see the MessageSent Event Storage section for more info.

This table highlights the key workflow improvements of CCTP over CCTP V1 in terms of enhanced cross-chain messaging, fewer manual steps, and greater control over message acceptance:

WHAT'S NEXT

• CCTP Block Confirmations