XCM Instructions¶

Introduction¶

XCM messages contain a series of actions and instructions that are executed by the Cross-Consensus Virtual Machine (XCVM). An action (for example, transferring a token from one blockchain to another) consists of instructions that the XCVM partly executes in the origin and destination chains.

For example, an XCM message that transfers DOT from Polkadot to Moonbeam will include the following XCM instructions (in that order), some of which are executed on Polkadot and some of which are executed on Moonbeam:

1. TransferReserveAsset — executed in Polkadot
2. ReserveAssetDeposited — executed in Moonbeam
3. ClearOrigin — executed in Moonbeam
4. BuyExecution — executed in Moonbeam
5. DepositAsset — executed in Moonbeam

Building the instructions for an XCM message from scratch is not an easy task. Consequently, there are wrapper functions and pallets that developers can leverage to use XCM features. The X-Tokens and XCM Transactor Pallets provide functions with a predefined set of XCM instructions to either send XC-20s or remotely execute on other chains via XCM.

If you're interested in experimenting with different combinations of instructions, you can use the Polkadot XCM Pallet to execute and send custom XCM messages.

This guide provides an overview of some of the most commonly used XCM instructions, including those in the above example.

Buy Execution¶

The BuyExecution instruction typically gets executed in the target chain. It takes assets from the holding register, a temporary position in the Cross-Consensus Virtual Machine (XCVM), to pay for execution fees. The target chain determines the fees to pay.

Clear Origin¶

The ClearOrigin instruction gets executed in the target chain. It clears the origin of the XCM author, thereby ensuring that later XCM instructions cannot command the authority of the author.

Deposit Asset¶

The DepositAsset instruction gets executed in the target chain. It removes the assets from the holding register, a temporary position in the Cross-Consensus Virtual Machine (XCVM), and sends them to a destination account on the target chain.

Descend Origin¶

The DescendOrigin instruction gets executed in the target chain. It mutates the origin on the target chain to match the origin on the source chain, ensuring execution on the target chain occurs on behalf of the same entity initiating the XCM message on the source chain.

Initiate Reserve Withdraw¶

The InitiateReserveWithdraw instruction gets executed in the source chain. It removes the assets from the holding register, a temporary position in the Cross-Consensus Virtual Machine (XCVM), (essentially burning them), and sends an XCM message to the reserve chain starting with the WithdrawAsset instruction.

Refund Surplus¶

The RefundSurplus instruction typically gets executed in the target chain after the XCM is processed. This instruction will take any leftover assets from the BuyExecution instruction and put the assets into the holding register, a temporary position in the Cross-Consensus Virtual Machine (XCVM).

Reserve Asset Deposited¶

The ReserveAssetDeposited instruction gets executed in the target chain. It takes a representation of the assets received in the Sovereign account and places them into the holding register, a temporary position in the Cross-Consensus Virtual Machine (XCVM).

Set Appendix¶

The SetAppendix instruction gets executed in the target chain. It sets the appendix register, which holds code that should be run after the current execution is finished.

Transfer Reserve Asset¶

The TransferReserveAsset instruction gets executed in the reserve chain. It moves assets from the origin account and deposits them into a destination account on the target chain. It then sends an XCM message to the target chain with the ReserveAssetDeposited instruction, followed by the XCM instructions that are to be executed.

Transact¶

The Transact instruction gets executed in the target chain. It dispatches encoded call data from a given origin, allowing for the execution of specific operations or functions on the target chain.

Withdraw Asset¶

The WithdrawAsset instruction can be executed in either the source or target chain. It removes assets and places them into the holding register, a temporary position in the Cross-Consensus Virtual Machine (XCVM).