XCM reference

This section provides reference information for the cross-consensus message (XCM) format.

Instructions

As you learned in Cross-consensus communication, the XCM executor is a program that executes an ordered set of instructions in a virtual machine running on the recipient consensus system. It's worth noting that some instructions are dependent on other instructions. The order in which instructions are listed in the Instruction enumeration reflects some of these dependencies. For example, an asset must be added to the holding register before it can be deposited somewhere else. In general, you also use a similar order for instructions when you construct a message to be sent to the receiving system. However, for your convenience, this reference section lists the instructions in alphabetic order instead of the order in which they are defined.

BuyExecution

Pays for the execution of the current message by removing assets from the holding register. You must specify the fees parameter to identify the asset to remove from the holding register to pay execution fees. You can also specify a weight_limit for the maximum fee to be purchased. If the weight_limit you specify is lower than the estimated weight of the message, the XCM executor stops execution with the TooExpensive error.

The following example illustrates the settings for a BuyExecution instruction:

{
  BuyExecution: {
    fees: {
      id: {
        Concrete: {
          parents: 0
          interior: Here
        }
      }
      fun: {
        Fungible: 1,000,000
      }
    }
    weightLimit: {
      Limited: 1,000,000
    }
  }
}

The following example illustrates using the instruction in a Rust program:

BuyExecution { fees, weight_limit } => {
    if let Some(weight) = Option::<u64>::from(weight_limit) {
        // pay for `weight` using up to `fees` of the holding register.
        let max_fee =
            self.holding.try_take(fees.into()).map_err(|_| XcmError::NotHoldingFees)?;
        let unspent = self.trader.buy_weight(weight, max_fee)?;
        self.holding.subsume_assets(unspent);
    }
    Ok(())
},

ClaimAsset

Creates assets that are being held on behalf of the location identified in the origin register. You must specify the assets parameter to identify the assets to be claimed. The asset you specify must match exactly with the assets available to be claimed by the origin with the given ticket. You must specify the ticket using the MultiLocation type. The claim ticket for the asset is an abstract identifier to help locate the asset to be claimed.

ClearError

Clears the error register. You can use this instruction to manually clear the last error from the error register.

ClearOrigin

Clears the origin register. You can use this instruction to ensure that later instructions cannot take over the authority of the original origin. For example, if you have instructions that are being relayed from an untrusted source, as is often the case with ReserveAssetDeposited, you can use ClearOrigin to prevent the original origin from being used to execute the instruction.

The following example appends the ReserveAssetDeposited and ClearOrigin instructions to an existing message:

let mut message = vec![ReserveAssetDeposited(assets), ClearOrigin];
message.extend(xcm.0.into_iter());

DepositAsset

Subtracts the specified asset from the holding register and deposits on-chain equivalent assets under the ownership of the specified beneficiary. You must specify the assets to remove using the MultiAssetFilter type.

The following example illustrates a simple message that includes a DepositAsset instruction:

ParaA::execute_with(|| {
        let message = Xcm(vec![
            WithdrawAsset((Here, send_amount).into()),
            buy_execution((Here, send_amount)),
            DepositAsset { assets: All.into(), max_assets: 1, beneficiary: Parachain(2).into() },
        ]);
        // Send withdraw and deposit
        assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone()));
    });

DepositReserveAsset

Removes the assets from the holding register and deposits on-chain equivalent assets into the sovereign account under the ownership of the destination. This instruction also sends a follow-up message to destination of the ReserveAssetDeposited instruction with the given effects.

DescendOrigin

Changes the origin to some interior location within the context of the current value in the origin register.

ExchangeAsset

Reduces assets in the holding register up to the amount specified by the give parameter and increases assets in the holding register with a minimum amount of alternative assets specified by the receive parameter.

HrmpChannelAccepted

Sends a notification message that an open channel request has been accepted by the recipient. After sending this notification, the channel is opened when the relay chain session changes. This message should originate directly on the relay chains and is intended to be sent by the relay chain to a parachain.

HrmpChannelClosing

Sends a message to notify a recipient that the sender who initiated the request to open a channel has decided to close the channel. After sending this notification, the channel is closed when the relay chain session changes. This message should originate directly on the relay chains and is intended to be sent by the relay chain to a parachain.

HrmpNewChannelOpenRequest

Sends a request from a parachain to the relay chain to open a new channel for communication with another parachain. Messages passed using the HRMP transport protocol are always routed through a relay chain. This message should originate directly on the relay chains and is intended to be sent by the relay chain to a parachain.

InitiateReserveWithdraw

Reduces the value of the holding register by the assets and sends XCM instructions beginning with WithdrawAsset to a reserve location.

InitiateTeleport

Removes the assets from the holding register and sends a message beginning with ReceiveTeleportedAsset instruction to a specified destination location.

NOTE: The destination location MUST respect the origin for the instruction as a valid teleportation origin for all assets. If it does not, then the assets may be lost.

QueryHolding

Sends a QueryResponse message with the assets value equal to the holding contents, or a portion thereof.

The following example illustrates a QueryHolding instruction that returns a QueryResponse with the identifier query_id_set:

ParaA::execute_with(|| {
	let message = Xcm(vec![
			QueryHolding {
				query_id: query_id_set,
				dest: Parachain(1).into(),
				assets: All.into(),
				max_response_weight: 1_000_000_000,
			},
	]);
});

QueryResponse

Provides expected information from the origin.

| response: Expresses the content of the message that resulted from the query instruction. | max_weight | Specifies the maximum weight that handling this response should take. If proper execution requires more weight than you specify, an error is returned. If the execution requires less than you specify, the difference might be added to the surplus weight register at run time.

The Response type is used to express information content in the QueryResponse XCM instruction. Depending on the query, it can represent the following different data types:

• Null
• Assets { assets: MultiAssets }
• ExecutionResult { result: Result<(), (u32, Error)> }
• Version { version: Compact }

The following example illustrates checking that a QueryResponse message was received and the information in the response is a newly deposited asset:

ParaA::execute_with(|| {
	assert_eq!(
			parachain::MsgQueue::received_dmp(),
			vec![Xcm(vec![QueryResponse {
					query_id: query_id_set,
					response: Response::Assets(MultiAssets::new()),
					max_weight: 1_000_000_000,
			}])],
	);
});

ReceiveTeleportedAsset

Accrues assets into the holding register equivalent to the assets removed from the current origin. The origin must be trusted to have removed the assets as a consequence of sending this message.

RefundSurplus

Increases the refunded weight register to the value of the surplus weight register. This instruction enables fees previously paid using the BuyExecution instruction to be moved into holding register to match the amount added to the refunded weight register.

ReportError

Reports the contents of the error register to the specified destination using XCM. A QueryResponse message of type ExecutionOutcome is sent to the destination with the given query_id and the outcome of the XCM.

ReserveAssetDeposited

Adds derivative assets to the holding register to represent the assets received from the value in the origin register. The origin must be trusted to act as a reserve for the assets.

SetAppendix

Sets the appendix register. The appendix register provides any code that should run after the current program completes execution. After the current program ends successfully, or after an error where the Error Handler is empty, the appendix register is cleared and its contents are used to replace the programme register. The estimated weight of this instruction must include the estimated weight of the appendix code. At run-time,the surplus weight register should be increased by the estimated weight of the appendix prior to being changed.

SetErrorHandler

Sets the error handler register. The error handler register provides any code that should run if the program encounters an error. After a program encounters an error, this register is cleared and its contents are used to replace the programme register. The estimated weight of this instruction must include the estimated weight of the error_handler code. At run-time, the surplus weight register should be increased by the estimated weight of the error handler prior to being changed.

SubscribeVersion

Sends a QueryResponse message to Origin specifying XCM version in the response field. Any upgrades to the local consensus that result in a later version of XCM being supported should elicit a similar response.

Transact

Dispatches the encoded call using the dispatch-origin for the call as expressed by the context you specify using the origin_type parameter.

TransferAsset

Withdraws assets from the ownership of Origin and deposit equivalent assets under the ownership of beneficiary.

TransferReserveAsset

Withdraws assets from the ownership of the current origin and deposits equivalent assets under the ownership of the sovereign account for the destination. This instruction also sends an additional message with ReserveAssetDeposited and any instructions specified with the xcm parameter to the specified destination.

The following example illustrates using the TransferReserveAsset instruction that contains a message with two additional instructions:

let mut message = Xcm(vec![TransferReserveAsset {
    assets,
    dest,
    xcm: Xcm(vec![
        BuyExecution { fees, weight_limit: Unlimited },
        DepositAsset { assets: Wild(All), max_assets, beneficiary },
    ]),
}]);

Trap

Throws an error of type Trap.

UnsubscribeVersion

Cancels the effect of a previous SubscribeVersion instruction from Origin.

WithdrawAsset

Removes the specified assets from the sending account on the local consensus system and adds them to the value in the holding register.

Registers

Most XCVM registers can't be modified directly. They are set to specific values to start and are only be manipulated by specific instructions, under certain circumstances, or according to certain rules. The XCVM includes the following registers:

Origins

In some cases, you might want to manipulate the origin stored in the origin register to grant more or fewer permissions for performing specific operations or executing specific XCM instructions. You can use the following origin types to manipulate how the origin for XCM instructions is interpreted.

The implications of using different origins depend on the code you are calling. Depending on your chain logic and permissions, you might not be able to generate the origin you want to use. For example, most users can't generate the Superuser origin, but it's possible for the chain logic to do so.

The following example illustrates specifying the origin type in a Transact instruction:

Transact {
	origin_type: OriginKind::SovereignAccount,
	require_weight_at_most: weight,
	call: call.encode().into(),
},

For additional examples of converting origins, see the origin_conversion module.

Errors

If the program executing XCM instructions encounters a problem, it stops execution and identifies the type of problem encountered with one of the following errors:

Concrete identifiers uniquely identify a single asset through its location in a consensus system relative to the context where an instruction is executed.