Circle USYC 백서 전문

urnTicket` 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](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move). * 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. **Parameters** | Field | Type | Description | | :- | :- | :- | | deposit\_for\_burn\_ticket | `DepositForBurnTicket<T, Auth>` | Struct containing parameters and authenticator struct. | | state | `&State` | Shared `State` object for the `TokenMessengerMinter` package. | | message\_transmitter\_state | `&mut MessageTransmitterState` | Shared `State` object for the `MessageTransmitter` package. | | deny\_list | `&DenyList` | DenyList shared object for the stablecoin token `T`. Constant address: `0x403` | | treasury | `&mut Treasury<T>` | Treasury shared object for the stablecoin token `T`. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [deposit\_for\_burn\_with\_caller](https://github.com/circlefin/sui-cctp/blob/649ed8a06840271ddc1ad66bb215d51be8265c31/packages/token_messenger_minter/sources/deposit_for_burn.move#L177) Same as `deposit_for_burn` but with an additional parameter, `destination_caller`. This parameter specifies which address has permission to call `receive_message` on the destination domain for the message. **Remarks:** * 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. <Note> **Destination Caller Notes** If the `destination_caller` does not represent a valid address, then it will not be possible to broadcast the message on the destination domain. This is an advanced feature, and the standard `deposit_for_burn` should be preferred for use cases where a specific destination caller is not required. *Note: If destination is a non-Move chain,* `destination_caller` *address should be converted to hex and passed in using the @0x123 address format.* </Note> **Parameters** | Field | Type | Description | | :- | :- | :- | | coins | `Coin<T>` | Coin of type T to be burned. Full amount in coins will be burned. | | destination\_domain | `u32` | Destination domain identifier. | | mint\_recipient | `address` | Address of mint recipient on destination domain *Note: If destination is a non-Move chain,* `mint_recipient` *address should be converted to hex and passed in using the @0x123 address format.* | | destination\_caller | `address` | Address of caller on destination chain. | | state | `&State` | Shared `State` object for the `TokenMessengerMinter` package. | | message\_transmitter\_state | `&mut MessageTransmitterState` | Shared `State` object for the `MessageTransmitter` package. | | deny\_list | `&DenyList` | DenyList shared object for the stablecoin token T. Constant address: `0x403` | | treasury | `&mut Treasury<T>` | Treasury shared object for the stablecoin token T. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [deposit\_for\_burn\_with\_caller\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L212) The same as `deposit_for_burn_with_caller()`, but intended to be called with an `Auth` struct from a dependent package. The calling package will be the "owner" (e.g. message\_sender) of the message and have the ability to call `replace_deposit_for_burn_with_package_auth()` to update the `mint_recipient` or `destination_caller`. This would be similar to a wrapper contract on EVM chains calling into `TokenMessenger` and being the message sender. Direct callers (where EOAs are trusted and should be the owner) should use `deposit_for_burn_with_caller()` instead. **Remarks:** * 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](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move). <Note> **Destination Caller Notes** If the `destination_caller` does not represent a valid address, then it will not be possible to broadcast the message on the destination domain. This is an advanced feature, and the standard `deposit_for_burn` should be preferred for use cases where a specific destination caller is not required. *Note: If destination is a non-Move chain,* `destination_caller` *address should be converted to hex and passed in using the @0x123 address format.* </Note> **Parameters** | Field | Type | Description | | :- | :- | :- | | deposit\_for\_burn\_with\_caller\_ticket | `DepositForBurnWithCallerTicket<T, Auth>` | Struct containing parameters and authenticator struct. | | state | `&State` | Shared `State` object for the `TokenMessengerMinter` package. | | message\_transmitter\_state | `&mut MessageTransmitterState` | Shared `State` object for the `MessageTransmitter` package. | | deny\_list | `&DenyList` | DenyList shared object for the stablecoin token T. Constant address: `0x403` | | treasury | `&mut Treasury<T>` | Treasury shared object for the stablecoin token T. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [replace\_deposit\_for\_burn](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L259) Replace a `BurnMessage` to change the mint recipient and/or destination caller. Allows the sender of a previous `BurnMessage` (created by `deposit_for_burn` or `deposit_for_burn_with_caller`) to send a new `BurnMessage` to replace the original. **Remarks:** * 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. **Parameters** | Field | Type | Description | | :- | :- | :- | | original\_message | `vector<u8>` | Original message bytes (to replace). | | original\_attestation | `vector<u8>` | Original attestation bytes. | | new\_destination\_caller | `Option<address>` | The new destination caller, which may be the same as the original destination caller, a new destination caller, or an empty destination caller, indicating that any destination caller is valid. | | new\_mint\_recipient | `Option<address>` | The new mint recipient, which may be the same as the original mint recipient, or different. | | state | `&State` | Shared State object for the `TokenMessengerMinter` package. | | message\_transmitter\_state | `&mut MessageTransmitterState` | Shared State object for the `MessageTransmitter` package. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [replace\_deposit\_for\_burn\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L282) Same as `replace_deposit_for_burn()`, but intended to be called when `deposit_for_burn_with_package_auth()` or `deposit_for_burn_with_caller_with_package_auth()` was called for the original message where the calling package is the message sender. **Remarks:** * 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. **Parameters** | Field | Type | Description | | :- | :- | :- | | replace\_deposit\_for\_burn\_ticket | `ReplaceDepositForBurnTicket<Auth>` | Struct containing parameters and authenticator struct. | | state | `&State` | Shared State object for the `TokenMessengerMinter` package. | | message\_transmitter\_state | `&mut MessageTransmitterState` | Shared State object for the `MessageTransmitter` package. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [handle\_receive\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/handle_receive_message.move#L131) Handles an incoming message from `MessageTransmitter`, and mints USDC to the recipient for valid messages. This function can only be called with a mutable reference to a `Receipt` object, which can only be created via a call with a valid message to the `message_transmitter::receive_message()` function. `state`, `mt_state`, `deny_list`, and `treasury` parameters are all shared objects. **Remarks:** * 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](/cctp/v1/transfer-usdc-on-testnet-from-sui-to-ethereum) page for the entire flow of receiving a message. **Parameters** | Field | Type | Description | | :- | :- | :- | | receipt | `Receipt` | Original message bytes (to replace). | | state | `&State` | Shared State object for the `TokenMessengerMinter` package. | | deny\_list | `&DenyList` | DenyList shared object for the stablecoin token T. Constant address: `0x403` | | treasury | `&mut Treasury<T>` | Treasury shared object for the stablecoin token T. | | ctx | `&TxContext` | `TxContext` for the transaction. | ### MessageTransmitter #### [receive\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L113) Receives a message emitted from a source chain. Messages with a given nonce can only be received once for a (`sourceDomain`, `destinationDomain`) pair. **Remarks:** * This function returns a `Receipt` [Hot Potato](https://medium.com/@borispovod/move-hot-potato-pattern-bbc48a48d93c) 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](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/deposit_for_burn.move#L212) 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. **Parameters** | Field | Type | Description | | :- | :- | :- | | message | `vector<u8>` | Message bytes. | | attestation | `vector<u8>` | Signed attestation of message. | | state | `&mut State` | Shared State object for the `TokenMessengerMinter` package. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [receive\_message\_with\_package\_auth](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L146) Same as `receive_message()`, except intended to be used by a dependent package when a package is specified as `destination_caller` (rather than an EOA). **Remarks:** * 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](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move). **Parameters** | Field | Type | Description | | :- | :- | :- | | receive\_message\_ticket | `ReceiveMessageTicket<Auth>` | A `Ticket` struct containing the message, attestation, and an authenticator struct. | | state | `&mut State` | Shared State object for the `TokenMessengerMinter` package. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [stamp\_receipt](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L164) Stamps a `Receipt` struct after verifying the intended package acknowledged the message (through the `Auth` struct) by returning a `StampedReceipt` struct that can be used to complete the message via `complete_receive_message()`. **Remarks:** * 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. <Note> **Auth Parameter Notes** This is required for the `MessageTransmitter` module to approve a `Receipt` prior to its deletion. 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 `Auth` structs to the public to avoid messages being wrongly stamped. An example implementation exists in the `token_messenger_minter::message_transmitter_authenticator` module. </Note> **Parameters** | Field | Type | Description | | :- | :- | :- | | stamp\_receipt\_ticket | `StampReceiptTicket<Auth>` | `Ticket` struct created by `create_stamp_receipt_ticket()` with the `Receipt` and `Auth` struct. | | state | `&mut State` | Shared State object for the `TokenMessengerMinter` package. | | ctx | `&TxContext` | `TxContext` for the transaction. | #### [complete\_receive\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/receive_message.move#L178) Completes the message by emitting a `MessageReceived` event for a stamped receipt and destroying the receipt. Cannot be called without a `StampedReceipt` (returned from `stamp_receipt()`). **Parameters** | Field | Type | Description | | :- | :- | :- | | stamped\_receipt | `StampedReceipt` | A stamped receipt returned from a `stamp_receipt()` call. | | state | `&State` | Shared State object for the `TokenMessengerMinter` package. | #### [send\_message](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/message_transmitter/sources/send_message.move#L66) Sends a message to the destination domain and recipient. The created `Message` struct is returned, but it is not required to do anything with this struct, it is returned for convenience. **Remarks:** * 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](https://github.com/circlefin/sui-cctp/blob/004950f742a161b6acfe2331630233ac3de0f3ad/packages/token_messenger_minter/sources/message_transmitter_authenticator.move). * 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. **Parameters** | Field | Type | Description | | :- | :- | :- | | send\_message\_ticket | `SendMessageTicket<Auth>` | A struct containing the necessary information to send a message created via `create_send_message_ticket()`. | | state | `&mut State` | Shared State object for the `Toke