Send XCM Messages¶
Introduction¶
One of the core FRAME pallets that enables parachains to engage in cross-chain communication using the Cross-Consensus Message (XCM) format is pallet-xcm. It facilitates the sending, execution, and management of XCM messages, thereby allowing parachains to interact with other chains within the ecosystem. Additionally, pallet-xcm, also referred to as the XCM pallet, supports essential operations like asset transfers, version negotiation, and message routing.
This page provides a detailed overview of the XCM pallet's key features, its primary roles in XCM operations, and the main extrinsics it offers. Whether aiming to execute XCM messages locally or send them to external chains, this guide covers the foundational concepts and practical applications you need to know.
XCM Frame Pallet Overview¶
The pallet-xcm provides a set of pre-defined, commonly used XCVM programs in the form of a set of extrinsics.
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.
Note
For further details on the XCM configuration, refer to the XCM Configuration page.
Where the XCM format defines a set of instructions used to construct XCVM programs, pallet-xcm defines a set of extrinsics that can be utilized to build XCVM programs, either to target the local or external chains. The pallet-xcm functionality is divided into three categories:
-
Primitive - dispatchable functions to execute XCM locally
-
High-level - functions for asset transfers between chains
-
Version negotiation-specific - functions for managing XCM version compability
Key Roles of the XCM Pallet¶
The XCM pallet plays a central role in managing cross-chain messages, with its primary responsibilities including:
-
Execute XCM messages - interacts with the XCM executor to validate and execute messages, adhering to predefined security and filter criteria
-
Send messages across chains - allows authorized origins to send XCM messages, enabling controlled cross-chain communication
-
Reserve-based transfers and teleports - supports asset movement between chains, governed by filters that restrict operations to authorized origins
-
XCM version negotiation - ensures compatibility by selecting the appropriate XCM version for inter-chain communication
-
Asset trapping and recovery - manages trapped assets, enabling safe reallocation or recovery when issues occur during cross-chain transfers
-
Support for XCVM operations - oversees state and configuration requirements necessary for executing cross-consensus programs within the XCVM framework
Primary Extrinsics of the XCM Pallet¶
This page will highlight the two Primary Primitive Calls responsible for sending and executing XCVM programs as dispatchable functions within the pallet.
Execute¶
The execute call directly interacts with the XCM executor, allowing for the execution of XCM messages originating from a locally signed origin. The executor validates the message, ensuring it complies with any configured barriers or filters before executing.
Once validated, the message is executed locally, and an event is emitted to indicate the result—whether the message was fully executed or only partially completed. Execution is capped by a maximum weight (max_weight); if the required weight exceeds this limit, the message will not be executed.
pub fn execute<T: Config>(
message: Box<VersionedXcm<<T as Config>::RuntimeCall>>,
max_weight: Weight,
)
Note
For further details on the execute extrinsic, see the pallet-xcm documentation.
Warning
Partial execution of messages may occur depending on the constraints or barriers applied.
Send¶
The send call enables XCM messages to be sent to a specified destination. This could be a parachain, smart contract, or any external system governed by consensus. Unlike the execute call, the message is not executed locally but is transported to the destination chain for processing.
The destination is defined using a Location, which describes the target chain or system. This ensures precise delivery through the configured XCM transport mechanism.
pub fn send<T: Config>(
dest: Box<MultiLocation>,
message: Box<VersionedXcm<<T as Config>::RuntimeCall>>,
)
Note
For further information about the send extrinsic, check the pallet-xcm documentation.
XCM Router¶
The XcmRouter is a critical component the XCM pallet requires to facilitate sending XCM messages. It defines where messages can be sent and determines the appropriate XCM transport protocol for the operation.
For instance, the Kusama network employs the ChildParachainRouter, which restricts routing to Downward Message Passing (DMP) from the relay chain to parachains, ensuring secure and controlled communication.
// Only one router so far - use DMP to communicate with child parachains.
ChildParachainRouter<Runtime, XcmPallet, PriceForChildParachainDelivery>,
)>;
Note
For more details on XCM transport protocols, see the XCM Channels page.
| Created: October 18, 2024