For a more practical approach to utilizing XCM, refer to the XCM Docs. Please keep in mind that XCM is under active development.
This pallet provides some default implementations for traits required by
XcmConfig. The XCM
executor is also included as an associated type within the pallet's configuration.
Where the XCM format defines a set of instructions used to construct XCVM programs,
defines a set of extrinsics that can be utilized to build XCVM programs, either to target the local
or external chains.
pallet-xcm's functionality is separated into three categories:
Remember, all XCMs are XCVM programs that follow the XCM format. It is the job of the XCM executor is to handle and execute these programs.
- Primitive, dispatchable functions to locally execute an XCM.
- High-level, dispatchable functions for asset transfers.
- Version negotiation-specific dispatchable functions.
There are two primary primitive extrinsics. These extrinsics handle sending and executing XCVM programs as dispatchable functions within the pallet.
execute- This call contains direct access to the XCM executor. It is the job of the executor to check the message and ensure that no barrier/filter will block the execution of the XCM. Once it is deemed valid, the message will then be locally executed, therein returning the outcome as an event. This operation is executed on behalf of whichever account has signed the extrinsic. It's possible for only a partial execution to occur.
send- This call specifies where a message should be sent (via a transport method) externally to a particular destination, i.e. a parachain, smart contract, or any system which is governed by consensus. In contrast to
execute, the executor is not called locally, as the execution will occur on the destination chain.
The XCM pallet needs the
XcmRouter to send XCMs. It is used to dictate where XCMs are allowed to
be sent, and which XCM transport protocol to use. For example, Kusama, the canary network, uses the
ChildParachainRouter which only allows for Downward Message Passing from the relay to parachains
You can read more about XCM transport protocols here.
Asset Transfer Extrinsics
Several extrinsics within the pallet handle asset transfer logic. They define a predetermined set of
instructions for sending and executing XCMs. Two variants of these functions are prefixed with
limited_. They have the same functionality but can specify a weight to pay for the XCM fee.
Otherwise, the fee is taken as needed from the asset being transferred.
reserve_transfer_assets- Transfer some assets from the local chain to the sovereign account of a destination chain and forward an XCM containing a
ReserveAssetDepositedinstruction, which serves as a notification.
teleport_assets- Teleport some assets from the local chain to some destination chain.
Transfer Reserve vs. Teleport
While both extrinsics deal with transferring assets, they exhibit fundamentally different behavior.
Teleporting an asset implies a two-step process: the assets are taken out of circulating supply (typically by burning/destroying) in the origin chain and re-minted to whatever account is specified at the destination. Teleporting should only occur if there is an inherent and bilateral trust between the two chains, as the tokens destroyed at the origin could not necessarily be guaranteed to have the same properties when minted at the destination. There has to be trust that the a particular chain burned, or re-minted the assets.
Transferring or reserving an asset implies that equivalent assets (i.e, native currency, like
KSM) are withdrawn from sovereign account of the origin chain and deposited into the sovereign account on the destination chain. Unlike teleporting an asset, it is not destroyed and re-minted, rather a trusted, third entity is used (i.e., Asset Hub) to reserve the assets, wherein the sovereign account of the destination chain on the reserve chain obtains ownership of these assets.
It's worth noting that this means that some other mechanism is needed to ensure that the balance on the destination does not exceed the amount being held in reserve chain.
A sovereign account refers to an account within a particular consensus system. Even though accounts may be different in terms of factors such as an address format, XCM agnostic nature enables communication between these sovereign accounts that are in other consensus systems.
Version Negotiation Extrinsics
The following extrinsics require root, as they are only used when bypassing XCM version negotiation. They change any relevant storage aspects that enforce anything to do with XCM version negotiations.
force_xcm_version- Modifies the
SupportedVersionstorage to change a particular destination's stated XCM version.
force_default_xcm_version- Modifies the
SafeXcmVersionstorage, which stores the default XCM version to use when the destination's version is unknown.
force_subscribe_version_notify- Sends an XCM with a
SubscribeVersioninstruction to a destination.
force_unsubscribe_version_notify- Sends an XCM with a
UnsubscribeVersioninstruction to a destination.
Fees in the XCM Pallet
Message fees are only paid if the interior location does not equal the interpreting consensus system
(known as Here in the context of an XCM
Multilocation). Otherwise, the chain bears the fees. If
applicable, fees are withdrawn from the assets from the specified
MultiLocation and used as
payment to execute any subsequent instructions within the XCM.
Fees are generally dependent on several factors within the
XcmConfig. For example, the barrier may
negate any fees to be paid at all.
Before any XCM is sent, and if the destination chain’s barrier requires it, a
BuyExecution instruction is used to buy
the necessary weight for the XCM. XCM fee calculation is handled by the Trader, which iteratively
calculates the total fee based on the number of instructions.
The Trader used to calculate the weight (time for computation in consensus) to include in the message. Fee calculation in XCM is highly configurable and, for this reason, subjective to whichever configuration is in place.