XCM (Cross-Consensus Messaging) is not a static protocol; it evolves through versioned format changes that introduce new message types, asset transfer semantics, and execution instructions. When a new XCM version is enacted via a Polkadot runtime upgrade, it becomes the native language that the relay chain and system parachains understand. This is a hard compatibility boundary: a parachain runtime that sends an XCM message using an older or newer format than the receiving chain expects will see that message fail, potentially locking assets or breaking critical cross-chain workflows.
Protocols
XCM Version Enactment History
A technical registry mapping specific XCM format versions to the Polkadot runtime upgrades that enacted them. Tracks the availability of new message types, asset transfer semantics, and breaking changes across the relay chain and system parachains.
introduction
INTEROPERABILITY LIFECYCLE
Why XCM Version Enactment Matters
Each XCM version enactment is a network-wide upgrade to the language that parachains, bridges, and dapps use to communicate.
The enactment history is therefore an operational dependency for every team building on Polkadot. Parachain developers must track which XCM version is live on the relay chain and on destination chains like Asset Hub or Bridge Hub to ensure their runtime's XCM configuration is compatible. Bridge operators, such as those managing Snowbridge or third-party connectors, need to know exactly when new asset transfer instructions became available to safely enable new cross-chain routes. Exchanges and custodians that accept deposits from the Polkadot ecosystem must understand which XCM versions support teleport versus reserve-backed transfers to correctly credit user accounts and manage liquidity.
A mismatch between a dapp's XCM assumptions and the network's enacted version is a common source of silent failures and stuck funds. Chainscore Labs helps teams avoid these scenarios by auditing XCM configurations against the canonical enactment history, reviewing upgrade compatibility paths, and designing monitoring that alerts on version-related message failures before they impact users.
PROTOCOL COMPATIBILITY MATRIX
XCM Version Enactment Registry
Maps specific XCM format versions to the runtime upgrades that activated them on Polkadot. Parachain teams, bridge operators, and wallet providers use this registry to determine when new message types, asset transfer semantics, or instruction sets became available, and to identify breaking changes that require integration updates.
| XCM Version | Enacting Runtime Upgrade | Key Changes & Risks | Affected Systems | Action Required |
|---|---|---|---|---|
XCM v2 | Verify against canonical Polkadot release notes (approx. runtime 9200+) | Introduced asset trapping, version negotiation, and new instructions like Transact. Breaking change from v1; old message formats rejected. | Parachains, bridges, wallets, exchanges supporting multi-asset transfers | Audit all XCM message construction for v2 compliance. Ensure Transact origin checks are in place. |
XCM v3 | Verify against canonical Polkadot release notes (approx. runtime 9370+) | Added multi-hop routing, fee estimation, and QueryPallet/QueryResponse for cross-chain reads. Increased complexity in barrier and fee handling. | Parachains using complex routing, bridges, DeFi protocols with cross-chain queries | Review barrier configurations for new instruction types. Test fee estimation logic for multi-hop paths. |
XCM v4 | Verify against canonical Polkadot release notes (approx. runtime 1002000+) | Unified asset model (Fungible/NonFungible), deprecated MultiAsset in favor of Asset. Introduced InitiateTransfer for simplified transfers. Breaking change for v3 message consumers. | All parachains, Asset Hub, bridges, wallets, custodians, indexers | Migrate all XCM message construction to v4 Asset model. Update transfer initiation logic to use InitiateTransfer. Re-audit asset trapping and claiming. |
XCM v5 (Current) | Verify against canonical Polkadot release notes | Further instruction set refinements and potential deprecations. Teams must verify exact changes against the Fellowship XCM spec. | All XCM-consuming systems | Monitor Fellowship RFCs for v5 stabilization. Test against Westend/Rococo before mainnet enactment. |
Version Negotiation Logic | Introduced in v2, refined in v3/v4 | Remote chains may reject messages if version negotiation fails or falls back to an unsupported version. Silent message drops possible. | Parachains, bridges, wallets constructing XCM to unknown destinations | Implement robust version discovery and fallback handling. Monitor for |
Asset Trapping & Claiming | v2+ | Failed transfers trap assets in the XCM pallet. Incorrect claim logic can permanently lock funds. v4 Asset model changes claim semantics. | Parachains, Asset Hub, custodians, exchanges | Audit asset claim processes for v4 compatibility. Ensure trapped asset monitoring alerts are active. |
Fee Payment & Weight | v3+ | v3 introduced | Parachains, relay chain, bridges | Validate fee asset reserves on all destination chains. Test with worst-case weight scenarios. Monitor for |
technical-context
RUNTIME COUPLING AND GOVERNANCE
How XCM Versions Are Enacted
XCM versions are not negotiated; they are enacted through runtime upgrades on the relay chain and system parachains, creating a synchronous network-wide standard.
On Polkadot, a new XCM version becomes available for production use only when a runtime upgrade incorporating it is enacted on-chain. The XCM format, defined by the xcm crate version integrated into the Polkadot-SDK, is compiled into the WebAssembly runtime blob. This blob is then proposed, voted on via OpenGov, and atomically applied across all relay chain validators at a specific block. There is no dynamic negotiation or feature detection; a parachain's ability to interpret a new XCM message is gated entirely by its own runtime version and the relay chain's XCM configuration.
The enactment process creates a tight coupling between the relay chain and system parachains like Asset Hub and Bridge Hub. A relay chain upgrade that introduces a new XCM version (e.g., XCMv3 to XCMv4) does not automatically upgrade the system parachains. Each system parachain must pass its own governance motion to upgrade its runtime to a version that includes the new XCM logic. During the interim, the relay chain's XCM pallet may need to perform versioned message translation, converting messages from the new format to an older one for delivery to a not-yet-upgraded parachain. This translation layer is a critical operational component, and its failure can halt cross-chain message delivery.
For parachain teams, bridge operators, and wallet providers, the key operational signal is not the release of a new xcm crate, but the specific runtime upgrade referenda on Polkadot and its system parachains. Monitoring these governance events is the only reliable way to know when a new asset transfer type, instruction, or fee model becomes available on the production network. Teams that upgrade their own parachains to use new XCM features before the relay chain enacts the corresponding version risk sending messages that cannot be executed, leading to trapped assets or failed teleports. Chainscore Labs provides upgrade readiness reviews and XCM compatibility audits to help teams sequence these changes safely.
IMPACT BY ROLE
Who Is Affected by XCM Version Changes
Parachain Developers and Collators
Parachain teams are the primary consumers of new XCM versions. A runtime upgrade enacting a new XCM version introduces new message types, asset transfer semantics, or instruction sets that a parachain must explicitly support to use.
Immediate actions:
- Audit the new XCM version's release notes for breaking changes in
Transact,ReserveAssetDeposit, or fee handling. - Update your parachain's XCM configuration to accept the new version. Failing to do so may result in messages being filtered out by the barrier.
- Test cross-chain message flows against the new version on Westend or Rococo before the relay chain upgrade enacts.
Operational risk: If your parachain does not upgrade its XCM config in sync with the relay chain, it may lose the ability to receive messages from chains that have already adopted the new version. Chainscore offers XCM compatibility audits to validate your configuration against the latest enacted version.
implementation-impact
XCM VERSION ENACTMENT
Key Integration Impacts by Version
Each XCM version enactment introduces new message types, asset transfer semantics, and breaking changes that directly affect parachain runtimes, bridge pallets, and off-chain indexers.
01
Parachain Runtime Compatibility
A new XCM version means the relay chain and system parachains will begin sending messages using the latest format. Parachain teams must ensure their runtime's XCM executor and barrier configurations can decode and safely handle these new messages. Failure to upgrade in sync can lead to message execution failures, trapped assets, or a halt in cross-chain communication with the relay chain and Asset Hub. Teams should audit their XCM configuration against the newly enacted version's spec.
02
Bridge Pallet and Message Indexer Updates
Trustless bridges like Snowbridge and off-chain indexers that parse XCM messages must be updated to support new instruction sets and version negotiation. A bridge pallet that cannot decode a new XCM version will reject incoming messages, breaking cross-chain asset flows. Indexers will fail to parse blocks containing new message formats, leading to data gaps. Operators should monitor the exact XCM version enacted and validate their decoding libraries against the canonical specification.
03
Asset Teleportation and Reserve Transfers
XCM version changes often introduce new asset transfer semantics, such as improvements to fee payment, reserve asset routing, or teleportation logic. Wallets, exchanges, and custodians that construct XCM messages for asset transfers must update their message-building logic to use the latest, supported instructions. Using deprecated transfer patterns after an enactment can result in transactions being rejected or assets being trapped in the holding register, requiring manual governance intervention to recover.
04
Governance and Treasury Operations
OpenGov referenda and treasury disbursements that execute cross-chain messages (e.g., moving funds from the relay chain to a parachain) will begin using the newly enacted XCM version. Governance participants and multisig operators should verify that their proposal-creation tools generate valid XCM for the current runtime. A proposal encoded with an outdated XCM format will fail on execution, potentially delaying time-sensitive treasury payments or causing a governance deadlock.
05
XCM Version Negotiation and Fallback
When a new XCM version is enacted, the relay chain will attempt to negotiate the highest common version with each connected parachain. If a parachain has not yet upgraded its runtime to support the new version, communication will fall back to an older, mutually supported version. While this prevents a complete break, the parachain will be unable to use new features. Teams should actively monitor version negotiation logs to confirm their runtime is operating at the intended XCM version and not silently falling back.
06
Chainscore XCM Compatibility Audit
Chainscore Labs provides targeted XCM integration audits for parachain teams, bridge operators, and custodians. An audit covers barrier configuration, executor safety, version negotiation logic, and asset recovery paths against the specific XCM version enacted in a given runtime upgrade. Teams can engage Chainscore for a pre-upgrade review to identify breaking changes or a post-enactment validation to confirm their system is correctly handling the new message format.
XCM VERSION ENACTMENT IMPACT
Compatibility and Risk Matrix
Evaluates the operational and integration impact of new XCM versions introduced in specific runtime upgrades, identifying affected systems and required actions.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
New XCM Instructions | Introduction of new transfer types or programmatic instructions (e.g., Transact, DepositAsset). | Parachain developers, dapp teams, bridge operators. | Audit new message handling logic. Review Chainscore's XCM integration audit service. |
Asset Transfer Semantics | Changes to asset trapping, claiming, or fee payment mechanisms. | Wallets, exchanges, custodians, Asset Hub integrators. | Update transaction construction and error handling. Verify against canonical test vectors. |
Version Negotiation | Alteration to the | Parachain collators, HRMP channel managers. | Ensure your runtime's |
Barrier and Filter Rules | New or modified barrier types that reject previously valid XCM messages. | Parachain governance bodies, treasury managers. | Review and update your chain's XCM filter configuration to avoid blocked essential messages. |
Fee Model | Introduction of new weight or fee structures for XCM execution. | Parachain economic model designers, dapp teams subsidizing user transactions. | Recalibrate fee estimation and user subsidy models. Chainscore can provide an economic impact assessment. |
Cross-Consensus Messaging Format | Breaking change to the core XCM data structure or encoding. | All XCM-sending and receiving chains, bridge protocols. | Mandatory coordinated runtime upgrade. Verify compatibility with all connected chains before enactment. |
Query Response Definitions | New or changed response types for | Liquid staking protocols, reserve-backed asset issuers. | Update off-chain monitoring and proof verification scripts to parse new response formats. |
XCM VERSION ENACTMENT HISTORY
Parachain Upgrade Checklist for New XCM Versions
A practical checklist for parachain teams, bridge operators, and infrastructure providers to validate readiness when a new XCM format version is enacted on the relay chain. Each item identifies a specific area of risk and the signal or artifact that confirms compatibility.
What to check: Verify that your parachain's XCM executor correctly handles the new xcm_version field in UpwardMessageSender and DownwardMessageHandler configurations. The relay chain will negotiate the highest common version with your parachain; if your runtime does not advertise the new version, messages will fall back to an older format.
Why it matters: A mismatch can cause message delivery failures or silent downgrades to a legacy XCM format, potentially breaking asset transfer semantics or instruction encoding.
Readiness signal: Successful exchange of QueryXcmVersion / XcmVersionChangeNotified messages between your parachain and the relay chain on a testnet that has enacted the target runtime.
resource-links
SOURCE SET
Canonical Resources
Use these sources to verify when an XCM version became available, which runtime enacted it, and whether a parachain or integration can safely rely on the new format. Treat the on-chain runtime, governance preimage, and Polkadot-SDK implementation as the authoritative evidence chain.
Chains We Build On
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
XCM VERSION ENACTMENT FAQ
Frequently Asked Questions
Common operational and integration questions about how XCM format versions are introduced, what changes they bring, and how teams should respond.
Check the XcmVersion constant or the SupportedVersion storage item in your parachain's runtime. This value is typically set during genesis or updated via a runtime upgrade. You can query it directly through the chain's state endpoint or by using Polkadot.js Apps to inspect the polkadotXcm pallet's storage. Cross-reference this with the enactment history to confirm whether your runtime's version aligns with the relay chain's expected version for message processing.
Trusted by Industry Leaders
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
L
Lee Erswell
CEO, Telos Foundation
how to get started
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
01
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
02
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
03
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
04
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Explore More Solutions
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Book a Call
Start a build
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.