Add relay_token_transactor example to cookbook

polkadot/xcm/docs/Cargo.toml

@@ -13,6 +13,7 @@ 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"] }
@@ -27,7 +28,11 @@ 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/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,37 @@
+//! # 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,76 @@
+//! Mock network
+
+use frame::deps::frame_system;
+use frame::deps::sp_runtime::{BuildStorage, AccountId32};
+use frame::deps::sp_io::TestExternalities;
+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,43 @@
+//! # Runtime
+
+use frame::prelude::*;
+use frame::runtime::prelude::*;
+use frame::deps::frame_system;
+use frame::traits::IdentityLookup;
+use xcm_executor::XcmExecutor;
+
+mod xcm_config;
+use xcm_config::XcmConfig;
+use crate::mock_message_queue;
+
+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;
+}