feat: initialize Kurdistan SDK - independent fork of Polkadot SDK

pezkuwi/xcm/docs/src/cookbook/mod.rs

@@ -0,0 +1,28 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # XCM Cookbook
+//!
+//! A collection of XCM recipes.
+//!
+//! Each recipe is tested and explains all the code necessary to run it -- they're not just snippets
+//! to copy and paste.
+
+/// Configuring a teyrchain that only uses the Relay Chain native token.
+/// In the case of Pezkuwi, this recipe will show you how to launch a teyrchain with no native
+/// token -- dealing only on HEZ.
+pub mod relay_token_transactor;

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

@@ -0,0 +1,52 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # Relay Asset Transactor
+//!
+//! This example shows how to configure a teyrchain to only deal with the Relay Chain token.
+//!
+//! The first step is using the [`xcm_builder::FungibleAdapter`] to create an `AssetTransactor` that
+//! can handle the relay chain token.
+#![doc = docify::embed!("src/cookbook/relay_token_transactor/teyrchain/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 mint a derivative asset, backed one-to-one 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/teyrchain/xcm_config.rs", is_reserve)]
+//!
+//! With this setup, we are able to do a reserve asset transfer to and from the teyrchain 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 teyrchain runtime for this example
+pub mod teyrchain;
+
+/// 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;

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

@@ -0,0 +1,94 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Mock network
+
+use frame::deps::{
+	frame_system,
+	sp_io::TestExternalities,
+	sp_runtime::{AccountId32, BuildStorage},
+};
+use xcm_simulator::{decl_test_network, decl_test_relay_chain, decl_test_teyrchain, TestExt};
+
+use super::{relay_chain, teyrchain};
+
+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 = UNITS;
+
+decl_test_teyrchain! {
+	pub struct ParaA {
+		Runtime = teyrchain::Runtime,
+		XcmpMessageHandler = teyrchain::MessageQueue,
+		DmpMessageHandler = teyrchain::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,
+		teyrchains = vec![
+			(2222, ParaA),
+		],
+	}
+}
+
+pub fn para_ext() -> TestExternalities {
+	use teyrchain::{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)],
+		..Default::default()
+	}
+	.assimilate_storage(&mut t)
+	.unwrap();
+
+	let mut ext = TestExternalities::new(t);
+	ext.execute_with(|| {
+		System::set_block_number(1);
+	});
+	ext
+}

pezkuwi/xcm/docs/src/cookbook/relay_token_transactor/relay_chain/mod.rs

@@ -0,0 +1,104 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relay chain runtime mock.
+
+use frame::{
+	deps::{frame_support::weights::WeightMeter, sp_runtime::AccountId32},
+	prelude::*,
+	runtime::prelude::*,
+	traits::{IdentityLookup, ProcessMessage, ProcessMessageError},
+};
+use pezkuwi_runtime_teyrchains::inclusion::{AggregateMessageOrigin, UmpQueueId};
+use xcm::latest::prelude::*;
+
+mod xcm_config;
+pub use xcm_config::LocationToAccountId;
+use xcm_config::XcmConfig;
+
+pub type AccountId = AccountId32;
+pub type Balance = u64;
+
+parameter_types! {
+	pub const BlockHashCount: u64 = 250;
+}
+
+#[derive_impl(frame_system::config_preludes::TestDefaultConfig)]
+impl frame_system::Config for Runtime {
+	type AccountId = AccountId;
+	type Lookup = IdentityLookup<Self::AccountId>;
+	type Block = Block;
+	type AccountData = pallet_balances::AccountData<Balance>;
+}
+
+#[derive_impl(pallet_balances::config_preludes::TestDefaultConfig)]
+impl pallet_balances::Config for Runtime {
+	type AccountStore = System;
+}
+
+type Block = frame_system::mocking::MockBlock<Runtime>;
+
+parameter_types! {
+	/// Amount of weight that can be spent per block to service messages.
+	pub MessageQueueServiceWeight: Weight = Weight::from_parts(1_000_000_000, 1_000_000);
+	pub const MessageQueueHeapSize: u32 = 65_536;
+	pub const MessageQueueMaxStale: u32 = 16;
+}
+
+/// Message processor to handle any messages that were enqueued into the `MessageQueue` pallet.
+pub struct MessageProcessor;
+impl ProcessMessage for MessageProcessor {
+	type Origin = AggregateMessageOrigin;
+
+	fn process_message(
+		message: &[u8],
+		origin: Self::Origin,
+		meter: &mut WeightMeter,
+		id: &mut [u8; 32],
+	) -> Result<bool, ProcessMessageError> {
+		let para = match origin {
+			AggregateMessageOrigin::Ump(UmpQueueId::Para(para)) => para,
+		};
+		xcm_builder::ProcessXcmMessage::<
+			Junction,
+			xcm_executor::XcmExecutor<XcmConfig>,
+			RuntimeCall,
+		>::process_message(message, Junction::Teyrchain(para.into()), meter, id)
+	}
+}
+
+impl pallet_message_queue::Config for Runtime {
+	type RuntimeEvent = RuntimeEvent;
+	type Size = u32;
+	type HeapSize = MessageQueueHeapSize;
+	type MaxStale = MessageQueueMaxStale;
+	type ServiceWeight = MessageQueueServiceWeight;
+	type MessageProcessor = MessageProcessor;
+	type QueueChangeHandler = ();
+	type QueuePausedQuery = ();
+	type WeightInfo = ();
+	type IdleMaxServiceWeight = MessageQueueServiceWeight;
+}
+
+construct_runtime! {
+	pub struct Runtime {
+		System: frame_system,
+		Balances: pallet_balances,
+		MessageQueue: pallet_message_queue,
+		XcmPallet: pallet_xcm,
+	}
+}

pezkuwi/xcm/docs/src/cookbook/relay_token_transactor/relay_chain/xcm_config.rs

@@ -0,0 +1,169 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relay chain XCM configuration
+
+use frame::{
+	deps::frame_system,
+	runtime::prelude::*,
+	traits::{Disabled, Everything, Nothing},
+};
+use xcm::latest::prelude::*;
+use xcm_builder::{
+	AccountId32Aliases, DescribeAllTerminal, DescribeFamily, EnsureXcmOrigin,
+	FrameTransactionalProcessor, FungibleAdapter, HashedDescription, IsConcrete,
+	SignedToAccountId32,
+};
+use xcm_executor::XcmExecutor;
+
+use super::{AccountId, Balances, Runtime, RuntimeCall, RuntimeEvent, RuntimeOrigin};
+
+parameter_types! {
+	pub HereLocation: Location = Location::here();
+	pub ThisNetwork: NetworkId = NetworkId::Pezkuwi;
+}
+
+/// Converter from XCM Locations to accounts.
+/// This generates sovereign accounts for Locations and converts
+/// local AccountId32 junctions to local accounts.
+pub type LocationToAccountId = (
+	HashedDescription<AccountId, DescribeFamily<DescribeAllTerminal>>,
+	AccountId32Aliases<ThisNetwork, AccountId>,
+);
+
+mod asset_transactor {
+	use super::*;
+
+	/// AssetTransactor for handling the Relay Chain token.
+	pub type FungibleTransactor = FungibleAdapter<
+		// Use this `fungible` implementation.
+		Balances,
+		// This transactor handles the native token.
+		IsConcrete<HereLocation>,
+		// How to convert an XCM Location into a local account id.
+		// Whenever assets are handled, the location is turned into an account.
+		// This account is the one where balances are withdrawn/deposited.
+		LocationToAccountId,
+		// The account id type, needed because `fungible` is generic over it.
+		AccountId,
+		// Not tracking teleports.
+		(),
+	>;
+
+	/// All asset transactors, in this case only one
+	pub type AssetTransactor = FungibleTransactor;
+}
+
+mod weigher {
+	use super::*;
+	use xcm_builder::FixedWeightBounds;
+
+	parameter_types! {
+		pub const WeightPerInstruction: Weight = Weight::from_parts(1, 1);
+		pub const MaxInstructions: u32 = 100;
+	}
+
+	pub type Weigher = FixedWeightBounds<WeightPerInstruction, RuntimeCall, MaxInstructions>;
+}
+
+parameter_types! {
+	pub UniversalLocation: InteriorLocation = [GlobalConsensus(NetworkId::Pezkuwi)].into();
+}
+
+pub struct XcmConfig;
+impl xcm_executor::Config for XcmConfig {
+	type RuntimeCall = RuntimeCall;
+	type XcmSender = ();
+	type XcmEventEmitter = ();
+	type AssetTransactor = asset_transactor::AssetTransactor;
+	type OriginConverter = ();
+	// We don't need to recognize anyone as a reserve
+	type IsReserve = ();
+	type IsTeleporter = ();
+	type UniversalLocation = UniversalLocation;
+	// This is not safe, you should use `xcm_builder::AllowTopLevelPaidExecutionFrom<T>` in a
+	// production chain
+	type Barrier = xcm_builder::AllowUnpaidExecutionFrom<Everything>;
+	type Weigher = weigher::Weigher;
+	type Trader = ();
+	type ResponseHandler = ();
+	type AssetTrap = ();
+	type AssetLocker = ();
+	type AssetExchanger = ();
+	type AssetClaims = ();
+	type SubscriptionService = ();
+	type PalletInstancesInfo = ();
+	type FeeManager = ();
+	type MaxAssetsIntoHolding = frame::traits::ConstU32<1>;
+	type MessageExporter = ();
+	type UniversalAliases = Nothing;
+	type CallDispatcher = RuntimeCall;
+	type SafeCallFilter = Everything;
+	type Aliasers = Nothing;
+	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
+	type XcmRecorder = ();
+}
+
+/// Converts a local signed origin into an XCM location. Forms the basis for local origins
+/// sending/executing XCMs.
+pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, ThisNetwork>;
+
+impl pallet_xcm::Config for Runtime {
+	// No one can call `send`
+	type SendXcmOrigin = EnsureXcmOrigin<RuntimeOrigin, ()>;
+	type XcmRouter = super::super::network::RelayChainXcmRouter; // Provided by xcm-simulator
+															  // Anyone can execute XCM programs
+	type ExecuteXcmOrigin = EnsureXcmOrigin<RuntimeOrigin, LocalOriginToLocation>;
+	// We execute any type of program
+	type XcmExecuteFilter = Everything;
+	// How we execute programs
+	type XcmExecutor = XcmExecutor<XcmConfig>;
+	// We don't allow teleports
+	type XcmTeleportFilter = Nothing;
+	// We allow all reserve transfers.
+	// This is so it can act as a reserve for its native token.
+	type XcmReserveTransferFilter = Everything;
+	// Same weigher executor uses to weigh XCM programs
+	type Weigher = weigher::Weigher;
+	// Same universal location
+	type UniversalLocation = UniversalLocation;
+	// No version discovery needed
+	const VERSION_DISCOVERY_QUEUE_SIZE: u32 = 0;
+	type AdvertisedXcmVersion = pallet_xcm::CurrentXcmVersion;
+	type AdminOrigin = frame_system::EnsureRoot<AccountId>;
+	// No locking
+	type TrustedLockers = ();
+	type MaxLockers = frame::traits::ConstU32<0>;
+	type MaxRemoteLockConsumers = frame::traits::ConstU32<0>;
+	type RemoteLockConsumerIdentifier = ();
+	// How to turn locations into accounts
+	type SovereignAccountOf = LocationToAccountId;
+	// A currency to pay for things and its matcher, we are using the relay token
+	type Currency = Balances;
+	type CurrencyMatcher = IsConcrete<HereLocation>;
+	// Pallet benchmarks, no need for this example
+	type WeightInfo = pallet_xcm::TestWeightInfo;
+	// Runtime types
+	type RuntimeOrigin = RuntimeOrigin;
+	type RuntimeCall = RuntimeCall;
+	type RuntimeEvent = RuntimeEvent;
+	// Aliasing is disabled: xcm_executor::Config::Aliasers is set to `Nothing`.
+	type AuthorizedAliasConsideration = Disabled;
+}

pezkuwi/xcm/docs/src/cookbook/relay_token_transactor/tests.rs

@@ -0,0 +1,137 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+use frame::testing_prelude::*;
+use test_log::test;
+use xcm::prelude::*;
+use xcm_executor::traits::{ConvertLocation, TransferType};
+use xcm_simulator::TestExt;
+
+use super::{
+	network::{MockNet, ParaA, Relay, ALICE, BOB, CENTS, INITIAL_BALANCE},
+	relay_chain, teyrchain,
+};
+
+#[docify::export]
+#[test]
+fn reserve_asset_transfers_work() {
+	// Scenario:
+	// ALICE on the relay chain holds some of Relay Chain's native tokens.
+	// She transfers them to BOB's account on the teyrchain using a reserve transfer.
+	// BOB receives Relay Chain native token derivatives on the teyrchain,
+	// which are backed one-to-one with the real tokens on the Relay Chain.
+	//
+	// NOTE: We could've used ALICE on both chains because it's a different account,
+	// but using ALICE and BOB makes it clearer.
+
+	// We restart the mock network.
+	MockNet::reset();
+
+	// ALICE starts with INITIAL_BALANCE on the relay chain
+	Relay::execute_with(|| {
+		assert_eq!(relay_chain::Balances::free_balance(&ALICE), INITIAL_BALANCE);
+	});
+
+	// BOB starts with 0 on the teyrchain
+	ParaA::execute_with(|| {
+		assert_eq!(teyrchain::Balances::free_balance(&BOB), 0);
+	});
+
+	// ALICE on the Relay Chain sends some Relay Chain native tokens to BOB on the teyrchain.
+	// The transfer is done with the `transfer_assets` extrinsic in the XCM pallet.
+	// The extrinsic figures out it should do a reserve asset transfer
+	// with the local chain as reserve.
+	Relay::execute_with(|| {
+		// The teyrchain id is specified in the network.rs file in this recipe.
+		let destination: Location = Teyrchain(2222).into();
+		let beneficiary: Location =
+			AccountId32 { id: BOB.clone().into(), network: Some(NetworkId::Pezkuwi) }.into();
+		// We need to use `u128` here for the conversion to work properly.
+		// If we don't specify anything, it will be a `u64`, which the conversion
+		// will turn into a non-fungible token instead of a fungible one.
+		let assets: Assets = (Here, 50u128 * CENTS as u128).into();
+		assert_ok!(relay_chain::XcmPallet::transfer_assets_using_type_and_then(
+			relay_chain::RuntimeOrigin::signed(ALICE),
+			Box::new(VersionedLocation::from(destination.clone())),
+			Box::new(VersionedAssets::from(assets)),
+			Box::new(TransferType::LocalReserve),
+			Box::new(VersionedAssetId::from(AssetId(Location::here()))),
+			Box::new(TransferType::LocalReserve),
+			Box::new(VersionedXcm::from(
+				Xcm::<()>::builder_unsafe().deposit_asset(AllCounted(1), beneficiary).build()
+			)),
+			WeightLimit::Unlimited,
+		));
+
+		// ALICE now has less Relay Chain tokens.
+		assert_eq!(relay_chain::Balances::free_balance(&ALICE), INITIAL_BALANCE - 50 * CENTS);
+
+		// The funds of the sovereign account of the teyrchain increase by 50 cents,
+		// the ones transferred over to BOB.
+		// The funds in this sovereign account represent how many Relay Chain tokens
+		// have been sent to this teyrchain.
+		// If the teyrchain wants to send those assets somewhere else they have to go
+		// via the reserve, and this balance is updated accordingly.
+		// This is why the derivatives are backed one-to-one.
+		let teyrchains_sovereign_account =
+			relay_chain::LocationToAccountId::convert_location(&destination).unwrap();
+		assert_eq!(relay_chain::Balances::free_balance(teyrchains_sovereign_account), 50 * CENTS);
+	});
+
+	ParaA::execute_with(|| {
+		// On the teyrchain, BOB has received the derivative tokens
+		assert_eq!(teyrchain::Balances::free_balance(&BOB), 50 * CENTS);
+
+		// BOB gives back half to ALICE in the relay chain
+		let destination: Location = Parent.into();
+		let beneficiary: Location =
+			AccountId32 { id: ALICE.clone().into(), network: Some(NetworkId::Pezkuwi) }.into();
+		// We specify `Parent` because we are referencing the Relay Chain token.
+		// This chain doesn't have a token of its own, so we always refer to this token,
+		// and we do so by the Location of the Relay Chain.
+		let assets: Assets = (Parent, 25u128 * CENTS as u128).into();
+		assert_ok!(teyrchain::XcmPallet::transfer_assets_using_type_and_then(
+			teyrchain::RuntimeOrigin::signed(BOB),
+			Box::new(VersionedLocation::from(destination)),
+			Box::new(VersionedAssets::from(assets)),
+			Box::new(TransferType::DestinationReserve),
+			Box::new(VersionedAssetId::from(AssetId(Location::parent()))),
+			Box::new(TransferType::DestinationReserve),
+			Box::new(VersionedXcm::from(
+				Xcm::<()>::builder_unsafe().deposit_asset(AllCounted(1), beneficiary).build()
+			)),
+			WeightLimit::Unlimited,
+		));
+
+		// BOB's balance decreased
+		assert_eq!(teyrchain::Balances::free_balance(&BOB), 25 * CENTS);
+	});
+
+	Relay::execute_with(|| {
+		// ALICE's balance increases
+		assert_eq!(
+			relay_chain::Balances::free_balance(&ALICE),
+			INITIAL_BALANCE - 50 * CENTS + 25 * CENTS
+		);
+
+		// The funds in the teyrchain's sovereign account decrease.
+		let teyrchain: Location = Teyrchain(2222).into();
+		let teyrchains_sovereign_account =
+			relay_chain::LocationToAccountId::convert_location(&teyrchain).unwrap();
+		assert_eq!(relay_chain::Balances::free_balance(teyrchains_sovereign_account), 25 * CENTS);
+	});
+}

pezkuwi/xcm/docs/src/cookbook/relay_token_transactor/teyrchain/mod.rs

@@ -0,0 +1,56 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # Runtime
+
+use frame::{deps::frame_system, runtime::prelude::*, traits::IdentityLookup};
+use xcm_executor::XcmExecutor;
+use xcm_simulator::mock_message_queue;
+
+mod xcm_config;
+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)]
+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)]
+impl pallet_balances::Config for Runtime {
+	type AccountStore = System;
+}

pezkuwi/xcm/docs/src/cookbook/relay_token_transactor/teyrchain/xcm_config.rs

@@ -0,0 +1,195 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # XCM Configuration
+
+use frame::{
+	deps::frame_system,
+	runtime::prelude::*,
+	traits::{Disabled, Everything, Nothing},
+};
+use xcm::latest::prelude::*;
+use xcm_builder::{
+	AccountId32Aliases, DescribeAllTerminal, DescribeFamily, EnsureXcmOrigin,
+	FrameTransactionalProcessor, FungibleAdapter, HashedDescription, IsConcrete,
+	SignedToAccountId32,
+};
+use xcm_executor::XcmExecutor;
+
+use super::{AccountId, Balances, MessageQueue, Runtime, RuntimeCall, RuntimeEvent, RuntimeOrigin};
+
+parameter_types! {
+	pub RelayLocation: Location = Location::parent();
+	pub ThisNetwork: NetworkId = NetworkId::Pezkuwi;
+}
+
+pub type LocationToAccountId = (
+	HashedDescription<AccountId, DescribeFamily<DescribeAllTerminal>>,
+	AccountId32Aliases<ThisNetwork, AccountId>,
+);
+
+/// Configuration related to asset transactors
+#[docify::export]
+mod asset_transactor {
+	use super::*;
+
+	parameter_types! {
+		pub ParentRelayLocation: Location = Location::parent();
+	}
+
+	/// AssetTransactor for handling the relay chain token
+	pub type FungibleTransactor = FungibleAdapter<
+		// Use this implementation of the `fungible::*` traits.
+		// `Balances` is the name given to the balances pallet in this particular recipe.
+		// Any implementation of the traits would suffice.
+		Balances,
+		// This transactor deals with the native token of the Relay Chain.
+		// This token is referenced by the Location of the Relay Chain relative to this chain
+		// -- Location::parent().
+		IsConcrete<ParentRelayLocation>,
+		// How to convert an XCM Location into a local account id.
+		// This is also something that's configured in the XCM executor.
+		LocationToAccountId,
+		// The type for account ids, only needed because `fungible` is generic over it.
+		AccountId,
+		// Not tracking teleports.
+		// This recipe only uses reserve asset transfers to handle the Relay Chain token.
+		(),
+	>;
+
+	/// Actual configuration item that'll be set in the XCM config.
+	/// A tuple could be used here to have multiple transactors, each (potentially) handling
+	/// different assets.
+	/// In this recipe, we only have one.
+	pub type AssetTransactor = FungibleTransactor;
+}
+
+/// Configuration related to token reserves
+#[docify::export]
+mod is_reserve {
+	use super::*;
+
+	parameter_types! {
+		/// Reserves are specified using a pair `(AssetFilter, Location)`.
+		/// Each pair means that the specified Location is a reserve for all the assets in AssetsFilter.
+		/// Here, we are specifying that the Relay Chain is the reserve location for its native token.
+		pub RelayTokenForRelay: (AssetFilter, Location) =
+		  (Wild(AllOf { id: AssetId(Parent.into()), fun: WildFungible }), Parent.into());
+	}
+
+	/// The wrapper type xcm_builder::Case is needed in order to use this in the configuration.
+	pub type IsReserve = xcm_builder::Case<RelayTokenForRelay>;
+}
+
+mod weigher {
+	use super::*;
+	use xcm_builder::FixedWeightBounds;
+
+	parameter_types! {
+		pub const WeightPerInstruction: Weight = Weight::from_parts(1, 1);
+		pub const MaxInstructions: u32 = 100;
+	}
+
+	pub type Weigher = FixedWeightBounds<WeightPerInstruction, RuntimeCall, MaxInstructions>;
+}
+
+parameter_types! {
+	pub UniversalLocation: InteriorLocation = [GlobalConsensus(NetworkId::Pezkuwi), Teyrchain(2222)].into();
+}
+
+pub struct XcmConfig;
+impl xcm_executor::Config for XcmConfig {
+	type RuntimeCall = RuntimeCall;
+	type XcmSender = ();
+	type XcmEventEmitter = ();
+	type AssetTransactor = asset_transactor::AssetTransactor;
+	type OriginConverter = ();
+	// The declaration of which Locations are reserves for which Assets.
+	type IsReserve = is_reserve::IsReserve;
+	type IsTeleporter = ();
+	type UniversalLocation = UniversalLocation;
+	// This is not safe, you should use `xcm_builder::AllowTopLevelPaidExecutionFrom<T>` in a
+	// production chain
+	type Barrier = xcm_builder::AllowUnpaidExecutionFrom<Everything>;
+	type Weigher = weigher::Weigher;
+	type Trader = ();
+	type ResponseHandler = ();
+	type AssetTrap = ();
+	type AssetLocker = ();
+	type AssetExchanger = ();
+	type AssetClaims = ();
+	type SubscriptionService = ();
+	type PalletInstancesInfo = ();
+	type FeeManager = ();
+	type MaxAssetsIntoHolding = frame::traits::ConstU32<1>;
+	type MessageExporter = ();
+	type UniversalAliases = Nothing;
+	type CallDispatcher = RuntimeCall;
+	type SafeCallFilter = Everything;
+	type Aliasers = Nothing;
+	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
+	type XcmRecorder = ();
+}
+
+/// Converts a local signed origin into an XCM location. Forms the basis for local origins
+/// sending/executing XCMs.
+pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, ThisNetwork>;
+
+impl pallet_xcm::Config for Runtime {
+	// We turn off sending for these tests
+	type SendXcmOrigin = EnsureXcmOrigin<RuntimeOrigin, ()>;
+	type XcmRouter = super::super::network::TeyrchainXcmRouter<MessageQueue>; // Provided by xcm-simulator
+																		   // Anyone can execute XCM programs
+	type ExecuteXcmOrigin = EnsureXcmOrigin<RuntimeOrigin, LocalOriginToLocation>;
+	// We execute any type of program
+	type XcmExecuteFilter = Everything;
+	// How we execute programs
+	type XcmExecutor = XcmExecutor<XcmConfig>;
+	// We don't allow teleports
+	type XcmTeleportFilter = Nothing;
+	// We allow all reserve transfers
+	type XcmReserveTransferFilter = Everything;
+	// Same weigher executor uses to weigh XCM programs
+	type Weigher = weigher::Weigher;
+	// Same universal location
+	type UniversalLocation = UniversalLocation;
+	// No version discovery needed
+	const VERSION_DISCOVERY_QUEUE_SIZE: u32 = 0;
+	type AdvertisedXcmVersion = pallet_xcm::CurrentXcmVersion;
+	type AdminOrigin = frame_system::EnsureRoot<AccountId>;
+	// No locking
+	type TrustedLockers = ();
+	type MaxLockers = frame::traits::ConstU32<0>;
+	type MaxRemoteLockConsumers = frame::traits::ConstU32<0>;
+	type RemoteLockConsumerIdentifier = ();
+	// How to turn locations into accounts
+	type SovereignAccountOf = LocationToAccountId;
+	// A currency to pay for things and its matcher, we are using the relay token
+	type Currency = Balances;
+	type CurrencyMatcher = IsConcrete<RelayLocation>;
+	// Pallet benchmarks, no need for this recipe
+	type WeightInfo = pallet_xcm::TestWeightInfo;
+	// Runtime types
+	type RuntimeOrigin = RuntimeOrigin;
+	type RuntimeCall = RuntimeCall;
+	type RuntimeEvent = RuntimeEvent;
+	// Aliasing is disabled: xcm_executor::Config::Aliasers is set to `Nothing`.
+	type AuthorizedAliasConsideration = Disabled;
+}

pezkuwi/xcm/docs/src/fundamentals.rs

@@ -0,0 +1,178 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # 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/0032-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 responsibility 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 these docs, we'll use a Rust implementation of XCM and the XCVM, consisting of the following
+//! parts:
+//! - [`XCM`](xcm): Holds the definition of an XCM program, the instructions and main concepts.
+//! - [`Executor`](xcm_executor): Implements the XCVM, capable of executing XCMs. Highly
+//!   configurable.
+//! - [`Builder`](xcm_builder): A collection of types used to configure the executor.
+//! - [`XCM Pallet`](pallet_xcm): A FRAME pallet for interacting with the executor.
+//! - [`Simulator`](xcm_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")]
+//!
+//! Teyrchains are interior to their Relay Chain, since a change in their state implies a change in
+//! the Relay Chain'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 number of parents.
+//!
+//! In Rust, this is specified with the following datatype:
+//! ```ignore
+//! pub struct Location {
+//!   parents: u8,
+//!   interior: Junctions,
+//! }
+//! ```
+//!
+//! Many junctions are available; teyrchains, 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::v4::prelude::Junction).
+//!
+//! We'll use a file system notation to represent locations, and start with relative locations.
+//! In the diagram, the location of teyrchain 1000 as seen from all other locations is as follows:
+//! - From the relaychain: `Teyrchain(1000)`
+//! - From teyrchain 1000 itself: `Here`
+//! - From teyrchain 2000: `../Teyrchain(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 Pezkuwi 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 teyrchain 1000 would be
+//! `GlobalConsensus(Pezkuwi)/Teyrchain(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 of that chain.
+//! For example, HEZ is represented by the location of the Pezkuwi 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 teyrchain in Pezkuwi, 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
+//! `Teyrchain(1000)/PalletInstance(53)/GeneralIndex(1984)`, when seen from the Pezkuwi relaychain.
+#![doc = simple_mermaid::mermaid!("../mermaid/usdt_location.mmd")]
+//!
+//! Asset Hub also has another type of assets called `ForeignAssets`.
+//! These assets are identified by the XCM Location to their origin.
+//! Two such assets are a Teyrchain asset, like Moonbeam's GLMR, and KSM, from the cousin Kusama
+//! network. These are represented as `../Teyrchain(2004)/PalletInstance(10)` and
+//! `../../GlobalConsensus(Kusama)` respectively.
+//!
+//! The whole type can be seen in the [format](https://github.com/paritytech/xcm-format#6-universal-asset-identifiers)
+//! and [rust docs](xcm::v4::prelude::Asset).
+//!
+//! ## 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::v4::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: assets, weight_limit },
+//!   DepositAsset { assets: AssetFilter(Wild(All)), 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` uses a
+//! wildcard, specifying all remaining `assets` after subtracting the fees and a `beneficiary`
+//! account.
+//!
+//! ## Next steps
+//!
+//! Continue with the [guides](crate::guides) for step-by-step tutorials on XCM,
+//! or jump to the [cookbook](crate::cookbook) to see examples.
+//!
+//! The [glossary](crate::glossary) can be useful if some of the terms are confusing.

pezkuwi/xcm/docs/src/glossary.rs

@@ -0,0 +1,124 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # 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, teyrchains, smart contracts.
+//! Most messaging between consensus systems has to be done asynchronously, for this, XCM is used.
+//! Between two smart contracts on the same teyrchain, however, communication can be done
+//! synchronously.
+//!
+//! ## [`Location`](xcm::v4::prelude::Location)
+//!
+//! A way of addressing consensus systems.
+//! These could be relative or absolute.
+//!
+//! ## [`Junction`](xcm::v4::prelude::Junction)
+//!
+//! The different ways of descending down a [`Location`](xcm::v4::prelude::Location) hierarchy.
+//! A junction can be a Teyrchain, an Account, or more.
+//!
+//! ## [`Asset`](xcm::v4::prelude::Asset)
+//!
+//! A way of identifying assets in the same or another consensus system, by using a
+//! [`Location`](xcm::v4::prelude::Location).
+//!
+//! ## Sovereign account
+//!
+//! An account in a consensus system that is controlled by an account in another consensus system.
+//!
+//! Runtimes use a converter between a [`Location`](xcm::v4::prelude::Location) and an account.
+//! These converters implement the [`ConvertLocation`](xcm_executor::traits::ConvertLocation) trait.
+//!
+//! ## 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 or increase 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.
+//! In practice, the reserve chain can also be one of the source or destination.
+//!
+//! ## XCVM
+//!
+//! The virtual machine behind XCM.
+//! Every XCM is an XCVM programme.
+//! Holds state in registers.
+//!
+//! An implementation of the virtual machine is the [`xcm-executor`](xcm_executor::XcmExecutor).
+//!
+//! ## 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.
+//!
+//! Lots of barrier definitions exist in [`xcm-builder`](xcm_builder).
+//!
+//! ## VMP (Vertical Message Passing)
+//!
+//! Umbrella term for both UMP (Upward Message Passing) and DMP (Downward Message Passing).
+//!
+//! The following diagram shows the uses of both protocols:
+#![doc = simple_mermaid::mermaid!("../mermaid/transport_protocols.mmd")]
+//!
+//! ## UMP (Upward Message Passing)
+//!
+//! Transport-layer protocol that allows teyrchains 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
+//! teyrchains.
+//!
+//! ## XCMP (Cross-Consensus Message Passing)
+//!
+//! Transport-layer protocol that allows teyrchains to send messages between themselves, without
+//! going through the relay chain.
+//!
+//! ## HRMP (Horizontal Message Passing)
+//!
+//! Transport-layer protocol that allows a teyrchain to send messages to a sibling teyrchain going
+//! through the relay chain. It's a precursor to XCMP, also known as XCMP-lite.
+//! It uses a mixture of UMP and DMP.

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

@@ -0,0 +1,26 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # XCM Guides
+//!
+//! These guides aim to get you up and running with XCM.
+//!
+//! Coming soon.
+//!
+//! ## Next steps
+//!
+//! Jump to the [cookbook](crate::cookbook) for different examples.

pezkuwi/xcm/docs/src/lib.rs

@@ -0,0 +1,66 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+// This file is part of Pezkuwi.
+
+// Pezkuwi is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Pezkuwi is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Pezkuwi.  If not, see <http://www.gnu.org/licenses/>.
+
+//! # XCM Docs
+//!
+//! Documentation and guides for XCM
+//!
+//! Welcome to the Cross-Consensus Messaging documentation!
+//!
+//! XCM is a **language** for communicating **intentions** between **consensus systems**.
+//! Whether you're a developer, a blockchain enthusiast, or just interested in Pezkuwi, this guide
+//! aims to provide you with an easy-to-understand and comprehensive introduction to XCM.
+//!
+//! ## Getting started
+//!
+//! Head over to the [fundamentals](fundamentals) section.
+//! Then, go to the [guides](guides), to learn about how to do things with XCM.
+//!
+//! ## Cookbook
+//!
+//! There's also the [cookbook](cookbook) for useful recipes for XCM.
+//!
+//! ## Glossary
+//!
+//! There's a [glossary](glossary) with common terms used throughout the docs.
+//!
+//! ## Contribute
+//!
+//! To contribute to the format, check out the [RFC process](https://github.com/paritytech/xcm-format/blob/master/proposals/0032-process.md).
+//! To contribute to these docs, [make a PR](https://github.com/pezkuwichain/pezkuwi-sdk).
+//!
+//! ## Why Rust Docs?
+//!
+//! Rust Docs allow docs to be as close to the source as possible.
+//! They're also available offline automatically for anyone who has the `pezkuwi-sdk` repo locally.
+//!
+//! ## Docs structure
+#![doc = simple_mermaid::mermaid!("../mermaid/structure.mmd")]
+// Frame macros reference features which this crate does not have
+#![allow(unexpected_cfgs)]
+
+/// Fundamentals of the XCM language. The virtual machine, instructions, locations and assets.
+pub mod fundamentals;
+
+/// Step-by-step guides to set up an XCM environment and start hacking.
+pub mod guides;
+
+/// Useful recipes for programs and configurations.
+pub mod cookbook;
+
+/// Glossary
+pub mod glossary;