Move XCM docs to rust docs

Cargo.toml

@@ -180,6 +180,7 @@ members = [
 	"polkadot/utils/generate-bags",
 	"polkadot/utils/remote-ext-tests/bags-list",
 	"polkadot/xcm",
+	"polkadot/xcm/docs",
 	"polkadot/xcm/pallet-xcm",
 	"polkadot/xcm/pallet-xcm-benchmarks",
 	"polkadot/xcm/procedural",

polkadot/xcm/docs/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "xcm-docs"
+description = "Documentation and guides for XCM"
+version = "0.0.1"
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+edition.workspace = true
+
+[dependencies]
+# For XCM stuff
+xcm = { version = "5.0.0", package = "staging-xcm" }
+xcm-executor = { version = "5.0.0", package = "staging-xcm-executor" }
+xcm-simulator = "5.0.0"
+
+# For building FRAME runtimes
+frame = { path = "../../../substrate/frame", features = ["experimental", "runtime"] }
+codec = { package = "parity-scale-codec", version = "3.6.9" }
+polkadot-parachain-primitives = { path = "../../../polkadot/parachain" }
+polkadot-primitives = { path = "../../../polkadot/primitives" }
+sp-runtime = { path = "../../../substrate/primitives/runtime" }
+sp-std = { path = "../../../substrate/primitives/std" }
+sp-io = { path = "../../../substrate/primitives/io" }
+
+# For building docs
+simple-mermaid = { git = "https://github.com/kianenigma/simple-mermaid.git", branch = "main" }
+docify = "0.2.6"

polkadot/xcm/docs/mermaid/location_hierarchy.mmd

@@ -0,0 +1,9 @@
+flowchart
+	relay[Relaychain] --> paraA["Parachain(1000)"]
+	relay --> paraB["Parachain(2000)"]
+
+	paraA --> pallet[Pallet]
+	pallet --> indexA[Index 1]
+	pallet --> indexB[Index 2]
+
+	paraA --> account[Account]

polkadot/xcm/docs/mermaid/structure.mmd

@@ -0,0 +1,4 @@
+flowchart
+	docs[xcm_docs] --> fundamentals
+	docs --> guides
+	docs --> cookbook

polkadot/xcm/docs/mermaid/universal_location.mmd

@@ -0,0 +1,3 @@
+flowchart
+	universe[Universal Location] --> polkadot[Polkadot]
+	universe --> ethereum[Ethereum]

polkadot/xcm/docs/mermaid/usdt_location.mmd

@@ -0,0 +1,6 @@
+flowchart
+	relay[Polkadot] --> assetHub["Asset Hub"]
+	relay --> anotherPara["Another parachain"]
+
+	assetHub --> assetsPallet["Foreign Assets Pallet"]
+	assetsPallet --> usdt[1984]

polkadot/xcm/docs/src/cookbook.rs

@@ -0,0 +1 @@
+

polkadot/xcm/docs/src/fundamentals.rs

@@ -0,0 +1,141 @@
+//! # XCM Fundamentals
+//!
+//! XCM standardizes usual actions users take in consensus systems.
+//! For example, dealing with assets locally, on other chains, and locking them.
+//! XCM programs can both be executed locally or sent to a different consensus system.
+//! Examples of consensus systems are blockchains and smart contracts.
+//!
+//! The goal of XCM is to allow multi-chain ecosystems to thrive via specialization.
+//! Very specific functionalities can be abstracted away and standardized in this common language.
+//! Then, every member of the ecosystem can implement the subset of the language that makes sense for them.
+//!
+//! The language evolves over time to accomodate the needs of the community
+//! via the [RFC process](https://github.com/paritytech/xcm-format/blob/master/proposals/0001-process.md).
+//!
+//! XCM is the language, it deals with interpreting and executing programs.
+//! It does not deal with actually **sending** these programs from one consensus system to another.
+//! This responsability falls to a transport protocol.
+//! XCM can even be interpreted on the local system, with no need of a transport protocol.
+//! However, automatic and composable workflows can be achieved via the use of one.
+//!
+//! At the core of XCM lies the XCVM, the Cross-Consensus Virtual Machine.
+//! It's the virtual machine that executes XCM programs.
+//! It is a specification that comes with the language.
+//!
+//! For this docs, we'll use a Rust implementation of XCM and the XCVM, consisting of the following parts:
+//! - XCM: Holds the definition of an XCM program, the instructions and main concepts.
+//! - Executor: Implements the XCVM, capable of executing XCMs. Highly configurable.
+//! - Builder: A collection of types used to configure the executor.
+//! - XCM Pallet: A FRAME pallet for interacting with the executor.
+//! - Simulator: A playground to tinker with different XCM programs and executor configurations.
+//!
+//! XCM programs are composed of Instructions, which reference Locations and Assets.
+//!
+//! ## Locations
+//!
+//! Locations are XCM's vocabulary of places we want to talk about in our XCM programs.
+//! They are used to reference things like 32-byte accounts, governance bodies, smart contracts, blockchains and more.
+//!
+//! Locations are hierarchical.
+//! This means some places in consensus are wholly encapsulated in other places.
+//! Say we have two systems A and B.
+//! If any change in A's state implies a change in B's state, then we say A is interior to B.
+//!
+#![doc = simple_mermaid::mermaid!("../mermaid/location_hierarchy.mmd")]
+//!
+//! Parachains are interior to their relaychain, since a change in their state implies a change in the relaychain's state.
+//!
+//! Because of this hierarchy, the way we represent locations is with both a number of **parents**, times we move __up__ the hierarchy,
+//! and a sequence of **junctions**, the steps we take __down__ the hierarchy after going up the specified amount of parents.
+//!
+//! In Rust, this is specified with the following datatype:
+//! ```ignore
+//! pub struct Location {
+//!   parents: u8,
+//!   interior: Junctions,
+//! }
+//! ```
+//!
+//! Many junctions are available, parachains, pallets, 32 and 20 byte accounts, governance bodies, and arbitrary indices
+//! are the most common.
+//! A full list of available junctions can be found in the [format](https://github.com/paritytech/xcm-format#interior-locations--junctions)
+//! and [Junction enum](xcm::v3::prelude::Junction).
+//!
+//! We'll use a file system notation to represent locations, and start with relative locations.
+//! In the diagram, the location of parachain 1000 as seen from all other locations is as follows:
+//! - From the relaychain: `Parachain(1000)`
+//! - From parachain 1000 itself: `Here`
+//! - From parachain 2000: `../Parachain(1000)`
+//!
+//! Relative locations are interpreted by the system that is executing an XCM program, which is the receiver of a message
+//! in the case where it's sent.
+//!
+//! Locations can also be absolute.
+//! Keeping in line with our filesystem analogy, we can imagine the root of our filesystem to exist.
+//! This would be a location with no parents, that is also the parent of all systems that derive their own consensus, say
+//! Polkadot or Ethereum or Bitcoin.
+//! Such a location does not exist concretely, but we can still use this definition for it.
+//! This is the **universal location**.
+//! We need the universal location to be able to describe locations in an absolute way.
+//!
+#![doc = simple_mermaid::mermaid!("../mermaid/universal_location.mmd")]
+//!
+//! Here, the absolute location of parachain 1000 would be `GlobalConsensus(Polkadot)/Parachain(1000)`.
+//!
+//! ## Assets
+//!
+//! We want to be able to reference assets in our XCM programs, if only to be able to pay for fees.
+//! Assets are represented using locations.
+//!
+//! The native asset of a chain is represented by the location to that chain.
+//! For example, DOT is represented by the location of the Polkadot relaychain.
+//! If the interpreting chain has its own asset, it would be represented by `Here`.
+//!
+//! How do we represent other assets?
+//! The asset hub system parachain in Polkadot, for example, holds a lot of assets.
+//! To represent each of them, it uses the indices we mentioned, and it makes them interior to the
+//! assets pallet instance it uses.
+//! USDT, an example asset that lives on asset hub, is identified by the location
+//! `Parachain(1000)/PalletInstance(53)/GeneralIndex(1984)`, when seen from the Polkadot relaychain.
+//!
+#![doc = simple_mermaid::mermaid!("../mermaid/usdt_location.mmd")]
+//!
+//! The whole type can be seen in the [format](https://github.com/paritytech/xcm-format#6-universal-asset-identifiers)
+//! and [rust docs](xcm::v3::prelude::MultiAsset).
+//!
+//! ## Instructions
+//!
+//! Given the vocabulary to talk about both locations, chains and accounts, and assets, we now need a way to
+//! express what we want the consensus system to do when executing our programs.
+//! We need a way of writing our programs.
+//!
+//! XCM programs are composed of a sequence of instructions.
+//!
+//! All available instructions can be seen in the [format](https://github.com/paritytech/xcm-format#5-the-xcvm-instruction-set)
+//! and the [Instruction enum](xcm::v3::prelude::Instruction).
+//!
+//! A very simple example is the following:
+//!
+//! ```ignore
+//! let message = Xcm(vec![
+//!   TransferAsset { assets, beneficiary },
+//! ]);
+//! ```
+//!
+//! This instruction is enough to transfer `assets` from the account of the **origin** of a message to the `beneficiary` account.
+//! However, because of XCM's generality, fees need to be paid explicitly.
+//! This next example sheds more light on this:
+//!
+//! ```ignore
+//! let message = Xcm(vec![
+//!   WithdrawAsset(assets),
+//!   BuyExecution { fees, weight_limit },
+//!   DepositAsset { assets, beneficiary },
+//! ]);
+//! ```
+//!
+//! Here we see the process of transferring assets was broken down into smaller instructions, and we add the explicit fee payment
+//! step in the middle.
+//! `WithdrawAsset` withdraws assets from the account of the **origin** of the message for usage inside this message's execution.
+//! `BuyExecution` explicitly buys execution for this program using the assets specified in `fees`, with a sanity check of `weight_limit`.
+//! `DepositAsset` has the same operands as the original `TransferAsset` instruction, specifying `assets` and a `beneficiary` account.

polkadot/xcm/docs/src/glossary.rs

@@ -0,0 +1,81 @@
+//! # Glossary
+//! 
+//! ## XCM (Cross-Consensus Messaging)
+//! 
+//! A messaging format meant to communicate intentions between consensus systems.
+//! XCM could also refer to a single message.
+//! 
+//! ## Instructions
+//! 
+//! XCMs are composed of a sequence of instructions.
+//! Each instruction aims to convey a particular intention.
+//! There are instructions for transferring and locking assets, handling fees, calling arbitrary blobs, and more.
+//! 
+//! ## Consensus system
+//! 
+//! A system that can reach any kind of consensus.
+//! For example, relay chains, parachains, smart contracts.
+//! 
+//! ## MultiLocation
+//! 
+//! A way of addressing consensus systems.
+//! These could be relative or absolute.
+//! 
+//! ## Junction
+//! 
+//! The different ways of descending down a `MultiLocation` hierarchy.
+//! A junction can be a Parachain, an Account, or more.
+//! 
+//! ## MultiAsset
+//! 
+//! A way of identifying assets in the same or another consensus system, by using a `MultiLocation`.
+//! 
+//! ## Sovereign account
+//! 
+//! An account on a consensus system that is controlled by an account in another consensus system.
+//! 
+//! ## Teleport
+//! 
+//! A way of transferring assets between two consensus systems without the need of a third party.
+//! It consists of the sender system burning the asset that wants to be sent over and the recipient minting an equivalent amount of that asset.
+//! It requires a lot of trust between the two systems, since failure to mint or burn will reduce the total issuance of the token.
+//! 
+//! ## Reserve asset transfer
+//! 
+//! A way of transferring assets between two consensus systems that don't trust each other, by using a third system they both trust, called the reserve.
+//! The real asset only exists on the reserve, both sender and recipient only deal with derivatives.
+//! It consists of the sender burning a certain amount of derivatives, telling the reserve to move real assets from its sovereign account to the destination's sovereign account, and then telling the recipient to mint the right amount of derivatives.
+//! 
+//! ## XCVM
+//! 
+//! The virtual machine behind XCM.
+//! Every XCM is an XCVM programme.
+//! Holds state in registers.
+//! 
+//! ## Holding register
+//! 
+//! An XCVM register used to hold arbitrary `Asset`s during the execution of an XCVM programme.
+//! 
+//! ## Barrier
+//! 
+//! An XCM executor configuration item that works as a firewall for incoming XCMs.
+//! All XCMs have to pass the barrier to be executed, else they are dropped.
+//! It can be used for whitelisting only certain types or messages or messages from certain senders.
+//! 
+//! ## UMP (Upward Message Passing)
+//! 
+//! Transport-layer protocol that allows parachains to send messages upwards to their relay chain.
+//! 
+//! ## DMP (Downward Message Passing)
+//! 
+//! Transport-layer protocol that allows the relay chain to send messages downwards to one of their parachains.
+//! 
+//! ## XCMP (Cross-Consensus Message Passing)
+//! 
+//! Transport-layer protocol that allows parachains to send messages between themselves, without going through the relay chain.
+//! 
+//! ## HRMP (Horizontal Message Passing)
+//! 
+//! Transport-layer protocol that allows a parachain to send messages to a sibling parachain going through the relay chain.
+//! It's a precursor to XCMP, also known as XCMP-lite.
+//! It uses a mixture of UMP and VMP.

polkadot/xcm/docs/src/guides/mod.rs

@@ -0,0 +1,7 @@
+//! # XCM Guides
+//!
+//! These guides aim to get you up and running with XCM.
+
+/// Guide on configuring the XCM executor in the most simple way possible for
+/// using the relaychain's token for fee payment.
+pub mod simple_configuration;