XCM Cookbook

Cargo.toml

@@ -182,6 +182,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,39 @@
+[package]
+name = "xcm-docs"
+description = "Documentation and guides for XCM"
+version = "0.0.1"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+repository.workspace = true
+authors.workspace = true
+edition.workspace = true
+publish = false
+
+[dependencies]
+# For XCM stuff
+xcm = { path = "../../xcm", package = "staging-xcm" }
+xcm-executor = { path = "../../xcm/xcm-executor", package = "staging-xcm-executor" }
+xcm-builder = { path = "../../xcm/xcm-builder", package = "staging-xcm-builder" }
+xcm-simulator = { path = "../../xcm/xcm-simulator" }
+pallet-xcm = { path = "../../xcm/pallet-xcm" }
+
+# For building FRAME runtimes
+frame = { path = "../../../substrate/frame", features = ["experimental", "runtime"] }
+codec = { package = "parity-scale-codec", version = "3.6.9" }
+scale-info = { version = "2.6.0", default-features = false }
+polkadot-parachain-primitives = { path = "../../../polkadot/parachain" }
+polkadot-runtime-parachains = { path = "../../../polkadot/runtime/parachains" }
+polkadot-primitives = { path = "../../../polkadot/primitives" }
+sp-runtime = { path = "../../../substrate/primitives/runtime" }
+sp-std = { path = "../../../substrate/primitives/std" }
+sp-io = { path = "../../../substrate/primitives/io" }
+
+# Some pallets
+pallet-message-queue = { path = "../../../substrate/frame/message-queue" }
+pallet-balances = { path = "../../../substrate/frame/balances" }
+
+# For building docs
+simple-mermaid = { git = "https://github.com/kianenigma/simple-mermaid.git", branch = "main" }
+docify = "0.2.6"
+
+[dev-dependencies]
+test-log = "0.2.14"

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/mod.rs

@@ -0,0 +1,7 @@
+//! # XCM Cookbook
+//!
+//! A collection of tested examples to do useful things in XCM.
+
+/// Configuring a parachain that only uses the relay chain token.
+/// Useful for a parachain that only wants to deal with DOT.
+pub mod relay_token_transactor;

polkadot/xcm/docs/src/cookbook/relay_token_transactor/mod.rs

@@ -0,0 +1,35 @@
+//! # Relay asset transactor
+//!
+//! This example shows how to configure a parachain to only deal with the relay chain token.
+//!
+//! The first step is using the [`xcm_builder::CurrencyAdapter`] to create an `AssetTransactor` that
+//! can handle the relay chain token.
+#![doc = docify::embed!("src/cookbook/relay_token_transactor/parachain/xcm_config.rs", asset_transactor)]
+//!
+//! The second step is to configure `IsReserve` to recognize the relay chain as a reserve for its
+//! own asset.
+//! With this, you'll be able to easily get derivatives from the relay chain by using the xcm
+//! pallet's `transfer_assets` extrinsic.
+//!
+//! The `IsReserve` type takes a type that implements `ContainsPair<MultiAsset, MultiLocation>`.
+//! In this case, we want a type that contains the pair `(relay_chain_native_token, relay_chain)`.
+#![doc = docify::embed!("src/cookbook/relay_token_transactor/parachain/xcm_config.rs", is_reserve)]
+//!
+//! With this setup, we are able to do a reserve asset transfer to and from the parachain and relay
+//! chain.
+#![doc = docify::embed!("src/cookbook/relay_token_transactor/tests.rs", reserve_asset_transfers_work)]
+//!
+//! For the rest of the code, be sure to check the contents of this module.
+
+/// The parachain runtime for this example
+pub mod parachain;
+
+/// The relay chain runtime for this example
+pub mod relay_chain;
+
+/// The network for this example
+pub mod network;
+
+/// Tests for this example
+#[cfg(test)]
+pub mod tests;

polkadot/xcm/docs/src/cookbook/relay_token_transactor/network.rs

@@ -0,0 +1,74 @@
+//! Mock network
+
+use frame::deps::{
+	frame_system,
+	sp_io::TestExternalities,
+	sp_runtime::{AccountId32, BuildStorage},
+};
+use xcm_simulator::{decl_test_network, decl_test_parachain, decl_test_relay_chain, TestExt};
+
+use super::{parachain, relay_chain};
+
+pub const ALICE: AccountId32 = AccountId32::new([0u8; 32]);
+pub const BOB: AccountId32 = AccountId32::new([1u8; 32]);
+pub const UNITS: u64 = 10_000_000_000;
+pub const CENTS: u64 = 100_000_000;
+pub const INITIAL_BALANCE: u64 = 1 * UNITS;
+
+decl_test_parachain! {
+	pub struct ParaA {
+		Runtime = parachain::Runtime,
+		XcmpMessageHandler = parachain::MessageQueue,
+		DmpMessageHandler = parachain::MessageQueue,
+		new_ext = para_ext(),
+	}
+}
+
+decl_test_relay_chain! {
+	pub struct Relay {
+		Runtime = relay_chain::Runtime,
+		RuntimeCall = relay_chain::RuntimeCall,
+		RuntimeEvent = relay_chain::RuntimeEvent,
+		XcmConfig = relay_chain::XcmConfig,
+		MessageQueue = relay_chain::MessageQueue,
+		System = relay_chain::System,
+		new_ext = relay_ext(),
+	}
+}
+
+decl_test_network! {
+	pub struct MockNet {
+		relay_chain = Relay,
+		parachains = vec![
+			(2222, ParaA),
+		],
+	}
+}
+
+pub fn para_ext() -> TestExternalities {
+	use parachain::{MessageQueue, Runtime, System};
+
+	let t = frame_system::GenesisConfig::<Runtime>::default().build_storage().unwrap();
+	let mut ext = frame::deps::sp_io::TestExternalities::new(t);
+	ext.execute_with(|| {
+		System::set_block_number(1);
+		MessageQueue::set_para_id(2222.into());
+	});
+	ext
+}
+
+pub fn relay_ext() -> TestExternalities {
+	use relay_chain::{Runtime, System};
+
+	let mut t = frame_system::GenesisConfig::<Runtime>::default().build_storage().unwrap();
+
+	pallet_balances::GenesisConfig::<Runtime> { balances: vec![(ALICE, INITIAL_BALANCE)] }
+		.assimilate_storage(&mut t)
+		.unwrap();
+
+	let mut ext = TestExternalities::new(t);
+	ext.execute_with(|| {
+		System::set_block_number(1);
+	});
+	ext
+}

polkadot/xcm/docs/src/cookbook/relay_token_transactor/parachain/mod.rs

@@ -0,0 +1,40 @@
+//! # Runtime
+
+use frame::{deps::frame_system, prelude::*, runtime::prelude::*, traits::IdentityLookup};
+use xcm_executor::XcmExecutor;
+
+mod xcm_config;
+use crate::mock_message_queue;
+use xcm_config::XcmConfig;
+
+pub type Block = frame_system::mocking::MockBlock<Runtime>;
+pub type AccountId = frame::deps::sp_runtime::AccountId32;
+pub type Balance = u64;
+
+construct_runtime! {
+	pub struct Runtime {
+		System: frame_system,
+		MessageQueue: mock_message_queue,
+		Balances: pallet_balances,
+		XcmPallet: pallet_xcm,
+	}
+}
+
+#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
+impl frame_system::Config for Runtime {
+	type Block = Block;
+	type AccountId = AccountId;
+	type Lookup = IdentityLookup<AccountId>;
+	type AccountData = pallet_balances::AccountData<Balance>;
+}
+
+impl mock_message_queue::Config for Runtime {
+	type RuntimeEvent = RuntimeEvent;
+	type XcmExecutor = XcmExecutor<XcmConfig>;
+}
+
+#[derive_impl(pallet_balances::config_preludes::TestDefaultConfig as pallet_balances::DefaultConfig)]
+impl pallet_balances::Config for Runtime {
+	type Balance = Balance;
+	type AccountStore = System;
+}