Overview of XC-20 Transfers¶

Introduction¶

The right combination of XCM instructions can be used to move an asset from one parachain to another. Currently, there are two main types of asset transfers using XCM: asset teleporting and remote transfers.

Asset teleporting consists of moving an asset from one blockchain to another by destroying the amount being transferred in the origin chain and creating a clone (same amount as destroyed) on the target chain. In such cases, each chain holds the native asset as a reserve, similar to a burn-mint bridging mechanism. The model requires a certain degree of trust, as any of the two chains could maliciously mint more assets.

Remote transfers consist of moving an asset from one blockchain to another via an intermediate account in the origin chain that is trustlessly owned by the target chain. This intermediate account is known as the "Sovereign" account. In such cases, the origin chain asset is not destroyed but held by the Sovereign account. The XCM execution in the target chain mints a wrapped (also referred to as "virtual" or "cross-chain" asset) representation to a target address. The wrapped representation is always interchangeable on a 1:1 basis with the native asset. This is similar to a lock-mint and burn-unlock bridging mechanism. The chain where the asset originated is called the reserve chain.

Moonbeam currently uses remote transfers for XC-20 transfers via XCM.

This page covers the fundamentals of XCM remote transfers. If you want to learn how to perform XC-20 token transfers, please refer to the XC-20 transfers via the Substrate API or the XC-20 transfers via the Ethereum API guides.

XCM Instructions for Asset Transfers¶

The X-Tokens Pallet and X-Tokens Precompile make it easy to send assets cross-chain by abstracting away the process of building the XCM message for the transfer. This guide aims to fill in some knowledge gaps about the abstracted logic, in particular, what XCM instructions are used to build the XCM message to send assets cross-chain.

The XCM instructions used by the X-Tokens Pallet extrinsics are defined in the X-Tokens Open Runtime Module Library repository.

The set of XCM instructions to be used depends on the token being transferred and the route taken. For example, there is one set of XCM instructions for sending the native asset back to its origin chain (reserve chain), such as xcDOT from Moonbeam back to Polkadot, and another set of XCM instructions for sending the native asset from the origin chain to a destination chain, such as DOT from Polkadot to Moonbeam.

The following sections provide some examples of the XCM instructions involved in token transfers via XCM.

Instructions to Transfer a Reserve Asset from the Reserve Chain¶

For example, to move DOT to Moonbeam, the following XCM instructions are used:

1. TransferReserveAsset - gets executed in Polkadot. Assets are transferred from the origin account and deposited into Moonbeam's Sovereign account on Polkadot
2. ReserveAssetDeposited - gets executed in Moonbeam. Mints the DOT representation on Moonbeam, called xcDOT
3. ClearOrigin - gets executed in Moonbeam. Clears origin information, which was Polkadot's Sovereign account on Moonbeam
4. BuyExecution - gets executed in Moonbeam. As such, execution fees are determined by Moonbeam. In this particular scenario, part of the minted xcDOT is used to pay for XCM execution
5. DepositAsset - gets executed in Moonbeam. Ultimately, it sends assets to a destination account on Moonbeam

To check how the instructions for an XCM message are built to transfer self-reserve (native) assets to a target chain, such as DOT to Moonbeam, you can refer to the transfer_self_reserve_asset function in the X-Tokens Open Runtime Module Library repository (as an example).

It calls TransferReserveAsset and passes in assets, dest, and xcm as parameters. In particular, the xcm parameter includes the BuyExecution and DepositAsset instructions. If you then head over to the Polkadot GitHub repository, you can find the TransferReserveAsset instruction. The XCM message is constructed by combining the ReserveAssetDeposited and ClearOrigin instructions with the xcm parameter, which, as mentioned, includes the BuyExecution and DepositAsset instructions.

Instructions to Transfer a Reserve Asset back to the Reserve Chain¶

To move xcDOT from Moonbeam back to Polkadot, the instructions that are used are:

1. WithdrawAsset - gets executed in Moonbeam. Takes the funds from the sender
2. InitiateReserveWithdraw - gets executed in Moonbeam. Burns the funds while sending an XCM message to the destination chain to execute the remainder of the token transfer
3. WithdrawAsset - gets executed in Polkadot. Takes the funds from Moonbeam's Sovereign account on Polkadot
4. ClearOrigin - gets executed in Polkadot. Clears origin information, which was Moonbeam's Sovereign account on Moonbeam
5. BuyExecution - gets executed in Polkadot. As such, Polkadot determines the execution fees. In this scenario, part of the DOTs being sent are used to pay for the execution of the XCM
6. DepositAsset - gets executed in Polkadot. Ultimately, it sends assets to a destination account on Polkadot

To check how the instructions for an XCM message are built to transfer reserve assets to a target chain, such as xcDOT to Polkadot, you can refer to the transfer_to_reserve function in the X-Tokens Open Runtime Module Library repository.

It calls WithdrawAsset, then InitiateReserveWithdraw, and passes in assets, dest, and xcm as parameters. In particular, the xcm parameter includes the BuyExecution and DepositAsset instructions. If you then head over to the Polkadot GitHub repository, you can find the InitiateReserveWithdraw instruction. The XCM message is constructed by combining the WithdrawAsset and ClearOrigin instructions with the xcm parameter, which, as mentioned, includes the BuyExecution and DepositAsset instructions.