Introduction to Cross-Consensus Message Format (XCM)
The Cross-Consensus Message Format, or XCM, is a messaging format and language used to communicate between consensus systems.
One of Polkadot's main functionalities is interoperability amongst parachains and any other participating consensus-driven systems. XCM is the language through which complex, cross-consensus interactions can occur. Two blockchains can "speak" XCM to seamlessly interact with each other using a standard messaging format.
We typically discuss XCM in the context of parachains, but please bear this in mind that it expands to the domain of all consensus systems! Remember, a consensus system here means any system or protocol that achieves finality to agree on the latest and correct state, whether it's a Polkadot parachain, an EVM smart contract, or other bridged consensus systems.
XCM is not meant to be only specific to Polkadot, but rather its primary intention is to define a generic and common format amongst different consensus systems to communicate.
It's important to note that XCM does not define how messages are delivered but rather define how they should look, act, and contain relative instructions to the on-chain actions the message intends to perform.
XCMP, or Cross Chain Message Passing, is the actual network-layer protocol to deliver XCM-formatted messages to other participating parachains. There are also other ways to define transport layer protocols for delivering XCM messages.
XCM has four high-level core design principles which it stands to follow:
- Asynchronous: XCM messages in no way assume that the sender will be blocking on its completion.
- Absolute: XCM messages are guaranteed to be delivered and interpreted accurately, in order and in a timely fashion. Once a message is sent, one can be sure it will be processed as it was intended to be.
- Asymmetric: XCM messages, by default, do not have results that let the sender know that the message was received - they follow the 'fire and forget' paradigm. Any results must be separately communicated to the sender with an additional message back to the origin.
- Agnostic: XCM makes no assumptions about the nature of the consensus systems between which the messages are being passed. XCM as a message format should be usable in any system that derives finality through consensus.
These four crucial design decisions allow for XCM messages to be a reliable yet convenient way to properly convey the intentions from one consensus system to another without any compatibility issues.
A Format, Not a Protocol
What started as an approach to cross-chain communication, has evolved into a format for Cross-Consensus Communication that is not only conducted between chains, but also between smart contracts, pallets, bridges, and even sharded enclaves like SPREE.
XCM cannot actually send messages between systems. It is a format for how message transfer should be performed, similar to how RESTful services use REST as an architectural style of development, where HTTP requests contain specific parameters to perform some action.
Similar to UDP, out of the box XCM is a "fire and forget" model, unless there is a separate XCM message designed to be a response message which can be sent from the recipient to the sender. All error handling should also be done on the recipient side.
XCM is not designed in a way where every system supporting the format is expected to be able to interpret any possible XCM message. Practically speaking, one can imagine that some messages will not have reasonable interpretations under some systems or will be intentionally unsupported.
Furthermore, it's essential to realize that XCM messages by themselves are not considered transactions. XCM describes how to change the state of the target network, but the message by itself doesn't perform the state change.
This partly ties to what is called asynchronous composability, which allows XCM messages to bypass the concept of time-constrained mechanisms, like on-chain scheduling and execution over time in the correct order in which it was intended.
XCM Tech Stack
XCM can be used to express the meaning of the messages over each of these three communication channels.
XCM v3 - What's new?
XCM v3 is currently in the process of being approved and audited but is merged in the Polkadot codebase. The upgrade to XCM v3 will open the doors to multi-hop, multi-network communications.
XCM v3 introduces some key features and additions to cross-consensus messaging, including:
Programmability - the ability to have expectations for messages, which allow for more comprehensive use cases, safe dispatches for version checking, branching, and NFT/Asset support.
Functional Multichain Decomposition - the ability to define mechanisms to cross-reference and perform actions on other chains on behalf of the origin chain (remote locking), context/id for these messages, and asset namespacing.
Bridging - introduces the concept of a universal location, which allows for a base reference for global consensus systems for multi-hop setups. This location is above the parent relay chain or other consensus systems like Ethereum or Bitcoin.
Why does XCM v3 matter?
A core part of the vision that XCM v3 provides is improving communication between the chains to make system parachains a reality. For example, the Polkadot relay chain handles more than just parachain management and shared security - it handles user balances/assets, auctions, governance, and staking. Ideally, the relay chain should be for what it's intended to be - a place for shared security. System parachains can alleviate these core responsibilities from the relay chain but only by using a standard format like XCM.
This is where system parachains come in, where each of these core responsibilities can be delegated to a system parachain respectively.
XCM v3's bridging, functional multichain decomposition, and programmability upgrades are crucial to bringing ecosystems together using a common communication abstraction.
XCM v3 Instruction & Register Overview
To reflect the functionality above, XCM v3 introduced a multitude of new instructions to include within its messages. This list isn't exhaustive, however contains the necessary instruction sets to showcase the previously explained concepts of XCM v3.
New registers have been introduced in order to accommodate some of the new instructions:
Transact Status Register- A register that expresses the result of the encoded call within a
Transactinstruction that has been dispatched.
Topic Register- A register that can set any value and is for use cases such as crafting IDs for messages. A
Topicis also part of
Note that most of these instruction definitions came from the source code, which you may explore for more depth!
These are the primary instructions that enable programmability and branching to be possible. Branching in this context is the ability for errors and logic to be handled as needed when dealing with a message.
ExpectAsset(MultiAssets)- Checks if the Holding register has a specific amount of assets, throws an error if it doesn't.
ExpectError(Option<(u32, Error)>)- Ensures the Error register contains the given error, and throws an error if it doesn't.
ExpectOrigin(MultiLocation)- Ensures the Origin register contains the expected origin, and throws an error if it doesn't.
QueryPallet- Queries the existence of a particular pallet type.
ExpectPallet- Ensure that a particular pallet with a particular version exists.
ReportTransactStatus(QueryResponseInfo)- Send a
QueryResponsemessage containing the value of the Transact Status Register to some destination.
ClearTransactStatus- Set the Transact Status Register to its default, cleared, value.
Functional Multichain Decomposition
These instructions highlight the key instructions focused on Functional Multichain Decomposition.
LockAsset(MultiAsset, MultiLocation)- Lock the locally held asset and prevent further transfer or withdrawal.
UnlockAsset(MultiAsset, MultiLocation)- Remove the lock over
asseton this chain and (if nothing else is preventing it) allow the asset to be transferred.
NoteUnlockable(MultiAsset, MultiLocation)- Asset (
asset) has been locked on the
originsystem and may not be transferred. It may only be unlocked with the receipt of the
UnlockAssetinstruction from this chain.
RequestUnlock(MultiAsset, MultiLocation)- Send an
UnlockAssetinstruction to the
lockerfor the given
Cross-Consensus Message Format (XCM)
For an updated and complete description of the cross-consensus message format please see the xcm-format repository on GitHub.
The Anatomy of an XCMP Interaction
A smart contract that exists on parachain
A will route a message to parachain
B in which another
smart contract is called that makes a transfer of some assets within that chain.
Charlie executes the smart contract on parachain
A, which initiates a new cross-chain message for
the destination of a smart contract on parachain
The collator node of parachain
A will place this new cross-chain message into its outbound
messages queue, along with a
destination and a
The collator node of parachain
B routinely pings all other collator nodes asking for new messages
(filtering by the
destination field). When the collator of parachain
B makes its next ping, it
will see this new message on parachain
A and add it into its own inbound queue for processing into
the next block.
Validators for parachain
A will also read the outbound queue and know the message. Validators for
B will do the same. This is so that they will be able to verify the message transmission
When the collator of parachain
B is building the next block in its chain, it will process the new
message in its inbound queue as well as any other messages it may have found/received.
During processing, the message will execute the smart contract on parachain
B and complete the
asset transfer as intended.
The collator now hands this block to the validator, which itself will verify that this message was
processed. If the message was processed and all other aspects of the block are valid, the validator
will include this block for parachain
B into the Relay Chain.
Check out our animated video below that explores how XCMP works.
Shawn Tabrizi: XCM - The Backbone Of A Multichain Future | Polkadot Decoded 2022 - High level overview which should answer “What is XCM?
XCM: The Cross-Consensus Message Format - Detailed blog post by Dr. Gavin Wood about the XCM Format.
XCM Format specification - The best starting point for understanding the XCM API at a technical level.
Gavin Wood, Polkadot founder: XCM v3 | Polkadot Decoded 2022 - High level overview of XCM and specifically the new features available in XCM v3.
XCMP Scheme - Full technical description of cross-chain communication on the Web3 Foundation research wiki.
Messaging Overview - An overview of the messaging schemes from the Polkadot Parachain Host Implementor's guide.
Sub0 Online: Getting Started with XCM - Your First Cross Chain Messages - Code focused workshop on how XCM v1 works, and the core concepts of XCM.
XCM: Cross-Consensus Messaging Audit - Technical audit report by Quarkslab prepared for Parity.
XCM pallet code - The pallet that contains XCM logic from the Polkadot code repository
XCM Config & Pallet-XCM | Polkadot Deep Dives - A technical deep dive into
pallet-xcmand the XCM configuration.