CCTP Sui packages and interfaces V1

​

Overview

​

Receive Message Flow

​

Interacting with TokenMessengerMinter from other Packages

​

Testnet

​

Package IDs

​

Shared Object IDs

​

Mainnet

​

Package IDs

​

Shared Object IDs

​

Interface

​

TokenMessengerMinter

​

deposit_for_burn

• Intended to be called directly by EOA (rather than a dependent package). The initiating EOA will be the “owner” (e.g. message sender) of the message and have the ability to call replace_deposit_for_burn() to update the mint_recipient or destination_caller. If the calling EOA is not trusted by the mint recipient or destination caller, deposit_for_burn_with_package_auth() should be called instead with the integrating package owning the message.
• The generic type T is the coin’s one-time witness (OTW) type for the specific coin type to be burned.
• BurnMessage and Message structs are returned, but it is not required to do anything with these structs; they are returned for convenience.

​

deposit_for_burn_with_package_auth

• This function uses a DepositForBurnTicket struct for parameters so that the calling package can call create_deposit_for_burn_ticket() (not version-gated) from their package with parameters, and call deposit_for_burn_with_package_auth() (version-gated) from a PTB so packages don’t have to be updated during CCTP V1 package upgrades.
• DepositForBurnTicket also requires an Auth parameter. This is required to securely assign a sender address associated with the calling contract to the message. Any struct that implements the drop trait can be used as an authenticator, but it is recommended to use a dedicated Auth struct. Calling contracts should be careful to not expose these structs to the public or else messages from their package could be replaced. An example can be found in TokenMessengerMinter on GitHub.
• The returned structs - BurnMessage and Message both have the copy ability. There is also no guarantee of execution ordering, so your package could create 5 DepositForBurnTickets in one transaction and they could be executed in any order depending on the PTB. Integrating packages should account for both of these scenarios.

​

deposit_for_burn_with_caller

• Intended to be called directly by EOA (rather than a dependent package). The initiating EOA will be the “owner” (e.g. message sender) of the message and have the ability to call replace_deposit_for_burn() to update the mint_recipient or destination_caller. If the calling EOA is not trusted by the mint recipient or destination caller, deposit_for_burn_with_caller_with_package_auth() should be called instead with the integrating package owning the message.

​

deposit_for_burn_with_caller_with_package_auth

• This function uses a DepositForBurnWithCallerTicket struct for parameters so that the calling package can call create_deposit_for_burn_with_caller_ticket() (not version-gated) from their package, and call deposit_for_burn_with_caller_with_package_auth() (version-gated) from a PTB so dependent packages don’t have to be updated during upgrades.
• DepositForBurnWithCallerTicket also requires an Auth parameter. This is required to securely assign a sender address associated with the calling contract to the message. Any struct that implements the drop trait can be used as an authenticator, but it is recommended to use a dedicated struct. Calling contracts should be careful to not expose these structs to the public or else messages from their package could be replaced. An example can be found in TokenMessengerMinter on GitHub.

​

replace_deposit_for_burn

• The new BurnMessage will reuse the amount and burn token of the original, without requiring a new Coin<T> deposit.
• The resulting mint will supersede the original mint, as long as the original mint has not confirmed yet onchain.
• A valid attestation is required before calling this function.
• This is useful in situations where the user specified an incorrect address and has no way to safely mint the previously burned USDC.

​

replace_deposit_for_burn_with_package_auth

• This function uses a ReplaceDepositForBurnTicket struct for parameters so that the calling package can call create_replace_deposit_for_burn_ticket() (not version-gated) from their package with parameters, and call deposit_for_burn_with_package_auth() (version-gated) from a PTB so packages don’t have to be updated during CCTP V1 package upgrades.

​

handle_receive_message

• Returns a StampReceiptTicketWithBurnMessage struct that can be deconstructed in a dependent package (or in a PTB) via deconstruct_stamp_receipt_ticket_with_burn_message(). This struct is returned so that dependent packages can associate the BurnMessage and StampReceiptTicket together from a PTB call and guarantee that stamp_receipt() was called.
• This must be called in a single PTB after calling receive_message() and before calling complete_receive_message(). See the Examples page for the entire flow of receiving a message.

​

MessageTransmitter

​

receive_message

• This function returns a Receipt Hot Potato struct after validating the attestation and marking the nonce as used.
• In order to destroy the Receipt and complete the message, in a single PTB, stamp_receipt() must be called with the Receipt and an Auth struct (see message_transmitter_authenticator for an example of this), and then complete_receive_message() must be called with the StampedReceipt to emit the MessageReceived event and complete the message.
• The receipt/stamp pattern is used to enforce atomicity and ensure the intended receiver contract is called.
• Intended to be called directly from an EOA when a package destination_caller is not specified on the message. Please use receive_message_with_package_auth() if a package destination_caller is specified.

​

receive_message_with_package_auth

• This function is version-gated and should be called from a PTB to prevent breaking changes when an upgrade occurs.
• This function uses a ReceiveMessageTicket for parameters so that the calling package can call create_receive_message_ticket() (not version-gated) from their package with parameters, and call receive_message_with_package_auth() (version-gated) from a PTB so packages don’t have to be upgraded during CCTP V1 package upgrades.
• ReceiveMessageTicket also requires an Auth parameter. This is required whenever a package is assigned as a destination_caller. destination_caller address should be set to the Auth identifier returned from the auth_caller_identifier() function with the package’s Auth struct. Any struct that implements the drop trait can be used as an authenticator, but it is recommended to use a dedicated Auth struct. Calling contracts should be careful to not expose these structs to the public or else messages intended for their package could be received by others. An example can be found in TokenMessengerMinter on GitHub.

​

stamp_receipt

• This function is version-gated and should be called from a PTB to prevent breaking changes in dependent packages when a CCTP V1 upgrade occurs.
• create_stamp_receipt_ticket() is safe to be called directly from a package (not version-gated), and it’s returned Ticket struct can be passed into stamp_receipt() in a PTB.

​

complete_receive_message

​

send_message

• This function uses a SendMessageTicket for parameters so that the calling package can call create_send_message_ticket() (not version-gated) from their package with parameters, and call send_message() (version-gated) from a PTB so packages don’t have to be updated during CCTP V1 package upgrades.
• For USDC transfers, this function is called directly by the TokenMessengerMinter package in deposit_for_burn().
• SendMessageTicket also requires an Auth parameter. This is required in order to assign a sender to the message. Any struct that implements the drop trait can be used as an authenticator, but it is recommended to use a dedicated Auth struct. Calling contracts should be careful to not expose these objects to the public or else their messages could be replaced. An example can be found in TokenMessengerMinter on GitHub.
• The returned struct (Message) has the copy ability. There is also no guarantee of execution ordering, so your package could create 5 SendMessageTickets in one transaction and they could be executed in any order depending on the PTB. Integrating packages should account for both of these scenarios.

​

send_message_with_caller

​

replace_message

• The sender package of the replaced message must be the same as the caller of the original message. This is identified using the Auth generic parameter. See stamp_receipt for more info on Auth structs.

​

Additional Notes

​

Destination Callers for Sui as Destination Chain

​

Mint Recipient Addresses for Sui as Source Chain

​

Mint Recipient Addresses for Sui as Destination Chain

​

CCTP V1 Package Upgrades and Versioning

​

Integrating with CCTP V1 Sui from other Packages

​

Private Auth Structs

​

Ticket Pattern

• receive_message_with_package_auth()
• stamp_receipt()

• deposit_for_burn_with_package_auth()
• deposit_for_burn_with_caller_with_package_auth()
• replace_deposit_for_burn_with_package_auth()

1. The integrating package calls create_replace_deposit_for_burn_ticket() with an Auth struct it defined, and returns this ticket.
2. The PTB calls deposit_for_burn_with_caller_with_package_auth() with the ticket on behalf of the integrator.
3. token_messenger_minter will validate if the type hash of Auth matches the original sender in the burn message.

​

PTB Function Call Ordering

​

Ticket Pattern Examples

// Prepare the ReceiveMessageTicket by calling create_receive_message_ticket() from within your package.
let receive_msg_ticket = your_package::prepare_receive_message_ticket(message, attestation);
// Receive the message on MessageTransmitter.
let receipt = message_transmitter::receive_message_with_package_auth(receive_msg_ticket, ...);
// Pass the Receipt into TokenMessengerMinter to mint the USDC.
let ticket_with_burn_message = token_messenger_minter::handle_receive_message(receipt, ...);
// In your package you can call deconstruct_stamp_receipt_ticket_with_burn_message to deconstruct the ticket
// and burn_message and securely take some action with the burn_message (e.g. swap some tokens, send them somewhere, etc.)
let stamp_receipt_ticket = your_package::take_some_action(ticket_with_burn_message, ...);
// Stamp the receipt
let stamped_receipt = message_transmitter::stamp_receipt(stamp_receipt_ticket);
// Complete the message and destroy the StampedReceipt
message_transmitter::complete_receive_message(stamped_receipt);

// Prepare the DepositForBurnWithCallerTicket by calling create_deposit_for_burn_with_caller_with_package_auth
// directly from your package with the input parameters and your Auth struct. Integrators can also take other
// actions here as needed.
let deposit_for_burn_ticket = your_package::prepare_deposit_for_burn_ticket(coins, ...);
// Call deposit for burn and burn the USDC
let (burn_message, message) = token_messenger_minter::deposit_for_burn_with_caller_with_package_auth(
  deposit_for_burn_ticket,
  ...
);
// Optionally, take some other action in your package based on the output message.
// Note that BurnMessage and Message have the copy ability so the possibility of them being copied should be
// handled in third party packages if post-actions are needed.
your_package::post_deposit_for_burn(burn_message, message, ...);