Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

XCM Cookbook #2633

Merged
merged 45 commits into from
May 16, 2024
Merged
Show file tree
Hide file tree
Changes from 34 commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
6bcd6a0
Move XCM docs to rust docs
franciscoaguirre Dec 5, 2023
8bbde01
Add an XCM configuration guide
franciscoaguirre Dec 11, 2023
7ac4e96
Move configuration to cookbook instead
franciscoaguirre Dec 12, 2023
1475b56
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre Dec 13, 2023
6556e06
Add relay_token_transactor example to cookbook
franciscoaguirre Dec 14, 2023
ddb2ea8
Put back what got deleted from xcm-simulator-example
franciscoaguirre Dec 14, 2023
9d7d8df
Publish and license
franciscoaguirre Dec 14, 2023
51aec90
".git/.scripts/commands/fmt/fmt.sh"
Dec 14, 2023
cb50a66
fix(xcm-docs): Update to XCM v4
franciscoaguirre Feb 13, 2024
dc97b47
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre Feb 13, 2024
7619a74
chore(xcm-docs): Replace deprecated CurrencyAdapter with FungibleAdapter
franciscoaguirre Feb 15, 2024
d6badb1
Update polkadot/xcm/docs/src/cookbook/relay_token_transactor/mod.rs
franciscoaguirre Feb 15, 2024
2df362a
Update polkadot/xcm/docs/src/cookbook/relay_token_transactor/mod.rs
franciscoaguirre Feb 15, 2024
4d78127
Update polkadot/xcm/docs/src/cookbook/relay_token_transactor/mod.rs
franciscoaguirre Feb 15, 2024
38b9533
Update polkadot/xcm/docs/src/glossary.rs
franciscoaguirre Feb 15, 2024
f038965
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
834492f
Update polkadot/xcm/docs/src/lib.rs
franciscoaguirre Feb 15, 2024
f7278b6
Update polkadot/xcm/docs/src/glossary.rs
franciscoaguirre Feb 15, 2024
0d3092f
Update polkadot/xcm/docs/src/cookbook/relay_token_transactor/tests.rs
franciscoaguirre Feb 15, 2024
cd6746d
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
3001aa8
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
d2605cf
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
a2b8978
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
3d022af
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
1863b25
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
17aeea0
Update polkadot/xcm/docs/src/fundamentals.rs
franciscoaguirre Feb 15, 2024
845cb40
docs(xcm-docs): Improve relay token transactor recipe
franciscoaguirre Feb 15, 2024
521be8c
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre Feb 15, 2024
6f5e5b1
WIP
franciscoaguirre Mar 14, 2024
e21a588
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre May 1, 2024
a07ef52
fix: Cargo.lock
franciscoaguirre May 1, 2024
7a658d4
doc(xcm-docs): more explanations and diagrams
franciscoaguirre May 1, 2024
0de7bd4
feat: move mock_message_queue to xcm-simulator
franciscoaguirre May 1, 2024
3c603e4
fix: fmt
franciscoaguirre May 1, 2024
ae33cc7
feat: address feedback
franciscoaguirre May 14, 2024
bb564e2
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre May 14, 2024
b918c90
fix(xcm-cookbook): add license to every file
franciscoaguirre May 14, 2024
e9a1a58
fix(xcm-docs): fmt
franciscoaguirre May 14, 2024
8c0721c
fix(xcm-simulator): getters were removed
franciscoaguirre May 14, 2024
8ce59e4
fix(xcm-simulator-example): fmt
franciscoaguirre May 14, 2024
c919085
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre May 14, 2024
f35fe7a
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre May 14, 2024
2f469b3
fix: revert Cargo.lock
franciscoaguirre May 14, 2024
c657f5c
Merge branch 'master' into cis-xcm-rust-docs
franciscoaguirre May 15, 2024
3b76222
fix: update Cargo.lock
franciscoaguirre May 15, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 85 additions & 9 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,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",
Expand Down
39 changes: 39 additions & 0 deletions polkadot/xcm/docs/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
[package]
name = "xcm-docs"
description = "Documentation and guides for XCM"
version = "0.1.0"
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 = { package = "polkadot-sdk-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"
9 changes: 9 additions & 0 deletions polkadot/xcm/docs/mermaid/location_hierarchy.mmd
Original file line number Diff line number Diff line change
@@ -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]
4 changes: 4 additions & 0 deletions polkadot/xcm/docs/mermaid/structure.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
flowchart
docs[xcm_docs] --> fundamentals
docs --> guides
docs --> cookbook
6 changes: 6 additions & 0 deletions polkadot/xcm/docs/mermaid/transport_protocols.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
flowchart
relay[Relaychain] --"DMP"--> paraA["Parachain(2000)"]
relay --"DMP"--> paraB["Parachain(2001)"]

paraA --"UMP"--> relay
paraB --"UMP"--> relay
3 changes: 3 additions & 0 deletions polkadot/xcm/docs/mermaid/universal_location.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
flowchart
universe[Universal Location] --> polkadot[Polkadot]
universe --> ethereum[Ethereum]
6 changes: 6 additions & 0 deletions polkadot/xcm/docs/mermaid/usdt_location.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
flowchart
relay[Polkadot] --> assetHub["Asset Hub"]
relay --> anotherPara["Another parachain"]

assetHub --> assetsPallet["Assets Pallet"]
assetsPallet --> usdt[1984]
11 changes: 11 additions & 0 deletions polkadot/xcm/docs/src/cookbook/mod.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
//! # 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 parachain that only uses the Relay Chain native token.
/// In the case of Polkadot, this recipe will show you how to launch a parachain with no native
/// token -- dealing only on DOT.
pub mod relay_token_transactor;
franciscoaguirre marked this conversation as resolved.
Show resolved Hide resolved
35 changes: 35 additions & 0 deletions polkadot/xcm/docs/src/cookbook/relay_token_transactor/mod.rs
Original file line number Diff line number Diff line change
@@ -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::FungibleAdapter`] 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 mint a derivative asset, backed one-to-on from the Relay
franciscoaguirre marked this conversation as resolved.
Show resolved Hide resolved
//! 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;
Original file line number Diff line number Diff line change
@@ -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 = 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
}
Loading
Loading