polkadot-developers · nhussein11 · Sep 18, 2025 · Sep 18, 2025 · Sep 18, 2025 · Sep 18, 2025
@@ -0,0 +1,5 @@
+---
+url: https://docs.polkadot.com/chain-interactions/
+---
+
+TODO
@@ -0,0 +1,43 @@
+---
+title: XCMv5
+description: Explore XCM version 5 features, including new instructions, improved fee handling, and enhanced cross-chain communication capabilities for modern applications.
+url: https://docs.polkadot.com/develop/interoperability/versions/v5/
+---
+
+# XCM V5
+
+The latest iteration of XCM is version 5. The main RFCs defining the changes in version 5 are the following:
+
+- [Legacy #37 - SetAssetClaimer](https://github.com/polkadot-fellows/xcm-format/blob/master/proposals/0037-custom-asset-claimer.md){target=\_blank}
+- [Legacy #38 - ExecuteWithOrigin](https://github.com/polkadot-fellows/xcm-format/blob/master/proposals/0038-execute-with-origin.md){target=\_blank}
+- [#100 - InitiateTransfer instruction](https://github.com/polkadot-fellows/RFCs/pull/100){target=\_blank}
+- [#101 - Remove weight from Transact](https://github.com/polkadot-fellows/RFCs/pull/101){target=\_blank}
+- [#105 - Improved fee mechanism](https://github.com/polkadot-fellows/RFCs/pull/105){target=\_blank}
+- [#107 - Execution hints](https://github.com/polkadot-fellows/RFCs/pull/107){target=\_blank}
+- [#108 - Remove testnet network ids](https://github.com/polkadot-fellows/RFCs/pull/108){target=\_blank}
+- [#122 - InitiateTransfer origin preservation](https://github.com/polkadot-fellows/RFCs/pull/122){target=\_blank}
+
+!!! note "What are Legacy RFCs?"
+
+    The first two RFCs are legacy ones from when XCM RFCs were separate from the Polkadot Technical Fellowship RFCs. As part of the XCM V5 specification, these two were combined since the Polkadot Technical Fellowship Manifesto specifies XCM as part of its mandate.
+
+Version 5 addresses key pain points that developers faced in previous versions:
+
+- **Before XCM V5**
+    - Cross-chain transfers were limited to only one transfer type, requiring multiple different XCMs to send the entirety of the tokens.
+    - Fee management across multiple hops was extremely complicated to get right, particularly because of delivery fees.
+    - Cross-chain transfers cleared the origin, making it impossible to [`Transact`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v4/enum.Instruction.html#variant.Transact){target=\_blank} in the same XCM as a transfer.
+    - Claiming trapped assets when transfers failed was troublesome, most of the time requiring governance to intervene.
+    - Having to specify the weight for `Transact` was brittle.
+- **After XCM V5**
+    - A unified cross-chain transfer instruction handles all possible transfer types and allows multiple ones in the same XCM.
+    - The fee payment mechanism has been standardized to handle multiple types of fees, making fees much more predictable.
+    - It's now possible to preserve the origin during a cross-chain transfer, enabling the use of `Transact` in the same XCM as the transfer.
+    - A custom asset claimer can be set, reducing the need for governance to intervene for claiming trapped assets.
+    - `Transact` no longer needs to specify the weight of the call, reducing the errors in cross-chain interactions.
+
+This section aims to give you all the changes in this new version you need to make the most of the latest and greatest in cross-chain interactions.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
@@ -0,0 +1,17 @@
+---
+title: XCM Versions
+description: Explore the different versions of XCM, understand version-specific features and capabilities, and find migration guides for upgrading between versions.
+url: https://docs.polkadot.com/develop/interoperability/versions/
+---
+
+# XCM Versions
+
+XCM is a versioned language that evolves to meet the growing needs of cross-chain communication in the Polkadot ecosystem. Understanding XCM versioning is essential for developers building interoperable applications to keep up with the latest improvements.
+
+New versions are defined via [Polkadot Fellowship RFCs](https://github.com/polkadot-fellows/rfcs){target=\_blank}, ensuring each iteration is thoroughly reviewed. This entire documentation uses _XCM V5_ as the primary reference, which is the current stable version.
+
+Each new version introduces new functionality while maintaining backward compatibility where possible. By understanding version differences, you can make informed decisions about which features to use and how to future-proof your applications.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
@@ -0,0 +1,15 @@
+---
+title: From Apps
+description: Learn how to implement XCM functionality in your applications, including asset transfers, fee management, and cross-chain transactions.
+url: https://docs.polkadot.com/develop/interoperability/xcm-guides/from-apps/
+---
+
+# From Apps
+
+This section shows how to interact with XCM from applications, providing practical guidance for implementing cross-chain functionality in your dApps and services.
+
+Whether you're building a DeFi application that needs to transfer assets between chains, a cross-chain governance system, or any application requiring interoperability, these guides cover the essential patterns and best practices for working with XCM from an application perspective.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
@@ -0,0 +1,48 @@
+---
+title: XCM Guides
+description: Comprehensive guides for implementing XCM functionality in applications and understanding cross-chain interactions.
+url: https://docs.polkadot.com/develop/interoperability/xcm-guides/
+---
+
+# XCM Guides
+
+This section provides comprehensive guides for implementing XCM functionality, including application development patterns, fee management, asset transfers, and cross-chain transaction handling.
+
+Whether you're building applications that need to interact with multiple chains, managing cross-chain fees, or handling complex asset transfers, these guides offer practical solutions and best practices for implementing XCM functionality in your projects.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
+
+## Additional Resources
+
+<div class="subsection-wrapper">
+  <div class="card">
+    <a href="/develop/interoperability/send-messages/">
+      <h2 class="title">Send XCM Messages</h2>
+      <hr>
+      <p class="description">Learn the fundamentals of sending cross-chain messages using XCM, including message structure, routing, and execution patterns.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="/develop/interoperability/xcm-config/">
+      <h2 class="title">XCM Configuration</h2>
+      <hr>
+      <p class="description">Learn how to configure XCM for your chain.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="/develop/interoperability/test-and-debug/">
+      <h2 class="title">Test and Debug</h2>
+      <hr>
+      <p class="description">Learn how to test and debug cross-chain communication via the XCM Emulator to ensure interoperability and reliable execution.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="/develop/interoperability/xcm-channels/">
+      <h2 class="title">XCM Channels</h2>
+      <hr>
+      <p class="description">Learn how to configure XCM channels for your chain.</p>
+    </a>
+  </div>
+</div>
@@ -0,0 +1,49 @@
+---
+title: Interoperability
+description: Learn how Polkadot enables blockchain interoperability through Cross-Consensus Messaging (XCM), powering secure cross-chain communication.
+url: https://docs.polkadot.com/develop/interoperability/
+---
+
+# Interoperability
+
+This section covers everything you need to know about building and implementing [Cross-Consensus Messaging (XCM)](/parachains/interoperability/get-started/){target=\_blank} solutions in the Polkadot ecosystem. Whether you're working on establishing cross-chain channels, sending and receiving XCM messages, or testing and debugging your cross-chain configurations, you'll find the essential resources and tools here to support your interoperability needs, regardless of your development focus.
+
+- Not sure where to start? Visit the [Interoperability](/reference/parachains/interoperability/){target=\_blank} overview page to explore different options and find the right fit for your project.
+- Ready to dive in? Head over to [Send XCM Messages](/develop/interoperability/send-messages/) to learn how to send a message cross-chain via XCM.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
+
+## Additional Resources
+
+<div class="subsection-wrapper">
+  <div class="card"> 
+    <a href="https://paritytech.github.io/polkadot-sdk/master/xcm_docs/index.html" target="_blank"> 
+      <h2 class="title">Review the Polkadot SDK's XCM Documentation</h2>
+      <hr>
+      <p class="description">Dive into the official documentation to learn about the key components for supporting XCM in your parachain and enabling seamless cross-chain communication.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="/tutorials/interoperability/"> 
+      <h2 class="title">Follow Step-by-Step Tutorials</h2>
+      <hr>
+      <p class="description">Enhance your XCM skills with step-by-step tutorials on building interoperability solutions on Polkadot SDK-based blockchains.</p>
+    </a>
+  </div>
+  <div class="card"> 
+    <a href="https://github.com/polkadot-fellows/xcm-format" target="_blank"> 
+      <h2 class="title">Familiarize Yourself with the XCM Format</h2>
+      <hr>
+      <p class="description">Gain a deeper understanding of the XCM format and structure, including any extra data it may need and what each part of a message means.</p>
+    </a>
+  </div>
+  <div class="card"> 
+    <a href="/develop/toolkit/interoperability/"> 
+      <h2 class="title">Essential XCM Tools</h2>
+      <hr>
+      <p class="description">Explore essential tools for creating and integrating cross-chain solutions within the Polkadot ecosystem.</p>
+    </a>
+  </div>
+</div>
@@ -88,7 +88,7 @@ The Polkadot SDK allows developers to construct a runtime by combining various p
 
 The following diagram illustrates the process of selecting and combining FRAME pallets to compose a runtime:
 
-![](/images/develop/parachains/customize-parachain/overview/frame-overview-2.webp)
+![](/images/develop/parachains/customize-parachain/overview/frame-overview-2.webp){ style="background:white; padding:1em;" }
 
 This modular design allows developers to:
 

@@ -0,0 +1,41 @@
+---
+title: Customize Your Parachain
+description: Learn to build a custom parachain with Polkadot SDK's FRAME framework, which includes pallet development, testing, smart contracts, and runtime customization.
+url: https://docs.polkadot.com/develop/parachains/customize-parachain/
+---
+
+# Customize Your Parachain
+
+Learn how to build a custom parachain with Polkadot SDK's FRAME framework, which includes pallet development, testing, smart contracts, and runtime customization. Pallets are modular components within the FRAME ecosystem that contain specific blockchain functionalities. This modularity grants developers increased flexibility and control around which behaviors to include in the core logic of their parachain.
+
+The [FRAME directory](https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2506-2/substrate/frame){target=\_blank} includes a robust library of pre-built pallets you can use as examples or templates to ease development.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
+
+## Additional Resources
+
+<div class="subsection-wrapper">
+  <div class="card">
+    <a href="https://github.com/paritytech/polkadot-sdk/tree/polkadot-stable2506-2/substrate/frame" target="_blank">
+      <h2 class="title">FRAME Repository</h2>
+      <hr>
+      <p class="description">View the source code of the FRAME development environment that provides pallets you can use, modify, and extend to build the runtime logic to suit the needs of your blockchain.</p>
+    </a>
+  </div>
+    <div class="card">
+    <a href="https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html" target="_blank">
+      <h2 class="title">FRAME Rust docs</h2>
+      <hr>
+      <p class="description">Check out the Rust documentation for FRAME, Substrate's preferred framework for building runtimes.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="https://libro.blockdeep.dev/index.html" target="_blank">
+      <h2 class="title">Polkadot SDK Best Practices</h2>
+      <hr>
+      <p class="description">Understand and address common issues that can arise in blockchain development when building with the Polkadot SDK.</p>
+    </a>
+  </div>
+</div>
@@ -0,0 +1,78 @@
+---
+title: Deployment
+description: Learn how to prepare your blockchain for deployment using the Polkadot SDK, including building deterministic Wasm runtimes and generating chain specifications.
+url: https://docs.polkadot.com/develop/parachains/deployment/
+---
+
+# Deployment
+
+Learn how to prepare your blockchain for deployment using the Polkadot SDK, including building deterministic Wasm runtimes and generating chain specifications.
+
+To better understand the deployment process, check out the following section. If you're ready to start jump to [In This Section](#in-this-section) to begin working through the deployment guides.
+
+## Deployment Process
+
+Taking your Polkadot SDK-based blockchain from a local environment to production involves several steps, ensuring your network is stable, secure, and ready for real-world use. The following diagram outlines the process at a high level:
+
+```mermaid
+flowchart TD
+    %% Group 1: Pre-Deployment
+    subgraph group1 [Pre-Deployment]
+        direction LR
+        A("Local <br>Development <br>and Testing") --> B("Runtime <br>Compilation")
+        B --> C("Generate <br>Chain <br>Specifications")
+        C --> D("Prepare <br>Deployment <br>Environment")
+        D --> E("Acquire <br>Coretime")
+    end
+
+    %% Group 2: Deployment
+    subgraph group2 [Deployment]
+        F("Launch <br>and <br>Monitor")
+    end
+
+    %% Group 3: Post-Deployment
+    subgraph group3 [Post-Deployment]
+        G("Maintenance <br>and <br>Upgrades")
+    end
+
+    %% Connections Between Groups
+    group1 --> group2
+    group2 --> group3
+
+    %% Styling
+    style group1 stroke:#6e7391,stroke-width:1px
+    style group2 stroke:#6e7391,stroke-width:1px
+    style group3 stroke:#6e7391,stroke-width:1px
+```
+
+- **Local development and testing**: The process begins with local development and testing. Developers focus on building the runtime by selecting and configuring the necessary pallets while refining network features. In this phase, running a local TestNet is essential to verify transactions and ensure the blockchain behaves as expected. Unit and integration tests ensure the network works as expected before launch. Thorough testing is conducted, not only for individual components but also for interactions between pallets.
+
+- **Runtime compilation**: Polkadot SDK-based blockchains are built with Wasm, a highly portable and efficient format. Compiling your blockchain's runtime into Wasm ensures it can be executed reliably across various environments, guaranteeing network-wide compatibility and security. The [srtool](https://github.com/paritytech/srtool){target=\_blank} is helpful for this purpose since it allows you to compile [deterministic runtimes](/develop/parachains/deployment/build-deterministic-runtime/){target=\_blank}.
+
+- **Generate chain specifications**: The chain spec file defines the structure and configuration of your blockchain. It includes initial node identities, session keys, and other parameters. Defining a well-thought-out chain specification ensures that your network will operate smoothly and according to your intended design.
+
+- **Deployment environment**: Whether launching a local test network or a production-grade blockchain, selecting the proper infrastructure is vital. For further information about these topics, see the [Nodes and Validators](/nodes-and-validators/){target=\_blank} section.
+
+- **Acquire coretime**: To build on top of the Polkadot network, users need to acquire coretime (either on-demand or in bulk) to access the computational resources of the relay chain. This allows for the secure validation of parachain blocks through a randomized selection of relay chain validators.
+
+    If you’re building a standalone blockchain (solochain) that won’t connect to Polkadot as a parachain, you can skip the preceding step, as there’s no need to acquire coretime or implement [Cumulus](/develop/parachains/#cumulus){target=\_blank}.
+
+- **Launch and monitor**: Once everything is configured, you can launch the blockchain, initiating the network with your chain spec and Wasm runtime. Validators or collators will begin producing blocks, and the network will go live. Post-launch, monitoring is vital to ensuring network health—tracking block production, node performance, and overall security.
+
+- **Maintenance and upgrade**: A blockchain continues to evolve post-deployment. As the network expands and adapts, it may require runtime upgrades, governance updates, coretime renewals, and even modifications to the underlying code. For an in-depth guide on this topic, see the [Maintenance](/develop/parachains/maintenance/){target=\_blank} section.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
+
+## Additional Resources
+
+<div class="subsection-wrapper">
+  <div class="card">
+    <a href="https://paritytech.github.io/polkadot-sdk/master/staging_chain_spec_builder/index.html" target="_blank">
+      <h2 class="title">Check Out the Chain Spec Builder Docs</h2>
+      <hr>
+      <p class="description">Learn about Substrate’s chain spec builder utility.</p>
+    </a>
+  </div>
+</div>
@@ -0,0 +1,32 @@
+---
+title: Maintenance
+description: Learn how to maintain Polkadot SDK-based networks, covering runtime monitoring, upgrades, and storage migrations for optimal blockchain performance.
+url: https://docs.polkadot.com/develop/parachains/maintenance/
+---
+
+# Maintenance
+
+Learn how to maintain Polkadot SDK-based networks, focusing on runtime monitoring, upgrades, and storage migrations for optimal performance. Proper maintenance ensures your blockchain remains secure, efficient, and adaptable to changing needs. These sections will guide you through monitoring your network, using runtime versioning, and performing forkless upgrades to keep your blockchain secure and up-to-date without downtime.
+
+## In This Section
+
+:::INSERT_IN_THIS_SECTION:::
+
+## Additional Resources
+
+<div class="subsection-wrapper">
+  <div class="card">
+    <a href="https://paritytech.github.io/polkadot-sdk/master/pallet_example_single_block_migrations/index.html" target="_blank">
+      <h2 class="title">Single Block Migration Example</h2>
+      <hr>
+      <p class="description">Check out an example pallet demonstrating best practices for writing single-block migrations while upgrading pallet storage.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="https://paritytech.github.io/polkadot-sdk/master/pallet_example_single_block_migrations/index.html" target="_blank">
+      <h2 class="title">Client Telemetry Crate</h2>
+      <hr>
+      <p class="description">Check out the docs on Substrate's client telemetry, a part of Substrate that allows ingesting telemetry data with, for example, Polkadot telemetry.</p>
+    </a>
+  </div>
+</div>