From 7994803ea8b9e3584febaa596ba3ab9dbff6694c Mon Sep 17 00:00:00 2001 From: Szegoo Date: Sat, 22 Oct 2022 15:37:10 +0200 Subject: [PATCH 1/4] Xcm-Simulator Docs --- xcm/xcm-simulator/src/lib.rs | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/xcm/xcm-simulator/src/lib.rs b/xcm/xcm-simulator/src/lib.rs index 69a8e088a0da..b53b8810f1fc 100644 --- a/xcm/xcm-simulator/src/lib.rs +++ b/xcm/xcm-simulator/src/lib.rs @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Polkadot. If not, see . -//! Test kit to simulate cross-chain message passing and XCM execution +//! Test kit to simulate cross-chain message passing and XCM execution. pub use codec::Encode; pub use paste; @@ -62,6 +62,7 @@ pub enum MessageKind { Xcmp, } +/// Encodes the provided Xcm message based on the `message_kind`. pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec { match message_kind { MessageKind::Ump | MessageKind::Dmp => VersionedXcm::<()>::from(message).encode(), @@ -76,6 +77,9 @@ pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec { } } +/// Expects a relay chain struct as an argument and implements UMP for it. The +/// provided struct needs to have the `Runtime` and `XcmConfig` defined. Also +/// expects the `TestExternalities` to be provided in the relay chain struct. #[macro_export] #[rustfmt::skip] macro_rules! decl_test_relay_chain { @@ -108,6 +112,10 @@ macro_rules! decl_test_relay_chain { }; } +/// Expects a parachain struct as an argument and implements`DmpMessageHandlerT` +/// and `XcmpMessageHandlerT` traits for it. The macro expects the provided struct +/// to define `Runtime`, `DmpMessageHandler` and `XcmpMessageHandler`. Also expects +/// the `TestExternalities` to be provided in the relay chain struct. #[macro_export] macro_rules! decl_test_parachain { ( @@ -153,6 +161,7 @@ macro_rules! decl_test_parachain { }; } +/// Implements the `TestExt` trait for a specified struct. #[macro_export] macro_rules! __impl_ext { // entry point: generate ext name @@ -202,6 +211,10 @@ thread_local! { = RefCell::new(VecDeque::new()); } +/// Declares a test network. Expects a network struct as an arugument and +/// implements some functionality for testing and the `ParachainXcmRouter` and +/// `RelayChainXcmRouter`. The struct needs to contain the relay chain struct +/// and an indexed list of parachains that are going to be in the network. #[macro_export] macro_rules! decl_test_network { ( @@ -215,16 +228,16 @@ macro_rules! decl_test_network { impl $name { pub fn reset() { use $crate::{TestExt, VecDeque}; - // Reset relay chain message bus + // Reset relay chain message bus. $crate::RELAY_MESSAGE_BUS.with(|b| b.replace(VecDeque::new())); - // Reset parachain message bus + // Reset parachain message bus. $crate::PARA_MESSAGE_BUS.with(|b| b.replace(VecDeque::new())); <$relay_chain>::reset_ext(); $( <$parachain>::reset_ext(); )* } } - /// Check if any messages exist in either message bus + /// Check if any messages exist in either message bus. fn exists_messages_in_any_bus() -> bool { use $crate::{RELAY_MESSAGE_BUS, PARA_MESSAGE_BUS}; let no_relay_messages_left = RELAY_MESSAGE_BUS.with(|b| b.borrow().is_empty()); From 771dbae00f5943545ebd0c9807f980b9ee957b3b Mon Sep 17 00:00:00 2001 From: Szegoo Date: Sat, 22 Oct 2022 15:56:41 +0200 Subject: [PATCH 2/4] spelling --- xcm/xcm-simulator/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xcm/xcm-simulator/src/lib.rs b/xcm/xcm-simulator/src/lib.rs index b53b8810f1fc..b643794d32c2 100644 --- a/xcm/xcm-simulator/src/lib.rs +++ b/xcm/xcm-simulator/src/lib.rs @@ -62,7 +62,7 @@ pub enum MessageKind { Xcmp, } -/// Encodes the provided Xcm message based on the `message_kind`. +/// Encodes the provided XCM message based on the `message_kind`. pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec { match message_kind { MessageKind::Ump | MessageKind::Dmp => VersionedXcm::<()>::from(message).encode(), @@ -211,7 +211,7 @@ thread_local! { = RefCell::new(VecDeque::new()); } -/// Declares a test network. Expects a network struct as an arugument and +/// Declares a test network. Expects a network struct as an argument and /// implements some functionality for testing and the `ParachainXcmRouter` and /// `RelayChainXcmRouter`. The struct needs to contain the relay chain struct /// and an indexed list of parachains that are going to be in the network. From 88066301ca8597257091006ac5c5bec692c64e68 Mon Sep 17 00:00:00 2001 From: Szegoo Date: Sat, 22 Oct 2022 17:08:09 +0200 Subject: [PATCH 3/4] examples --- xcm/xcm-simulator/src/lib.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/xcm/xcm-simulator/src/lib.rs b/xcm/xcm-simulator/src/lib.rs index b643794d32c2..d60e2d583f9c 100644 --- a/xcm/xcm-simulator/src/lib.rs +++ b/xcm/xcm-simulator/src/lib.rs @@ -80,6 +80,16 @@ pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec { /// Expects a relay chain struct as an argument and implements UMP for it. The /// provided struct needs to have the `Runtime` and `XcmConfig` defined. Also /// expects the `TestExternalities` to be provided in the relay chain struct. +/// +/// ```ignore +/// decl_test_relay_chain! { +/// pub struct Relay { +/// Runtime = relay_chain::Runtime, +/// XcmConfig = relay_chain::XcmConfig, +/// new_ext = relay_ext(), +/// } +/// } +/// ``` #[macro_export] #[rustfmt::skip] macro_rules! decl_test_relay_chain { @@ -116,6 +126,17 @@ macro_rules! decl_test_relay_chain { /// and `XcmpMessageHandlerT` traits for it. The macro expects the provided struct /// to define `Runtime`, `DmpMessageHandler` and `XcmpMessageHandler`. Also expects /// the `TestExternalities` to be provided in the relay chain struct. +/// +/// ```ignore +/// decl_test_parachain! { +/// pub struct ParaA { +/// Runtime = parachain::Runtime, +/// XcmpMessageHandler = parachain::MsgQueue, +/// DmpMessageHandler = parachain::MsgQueue, +/// new_ext = para_ext(), +/// } +/// } +/// ``` #[macro_export] macro_rules! decl_test_parachain { ( @@ -215,6 +236,18 @@ thread_local! { /// implements some functionality for testing and the `ParachainXcmRouter` and /// `RelayChainXcmRouter`. The struct needs to contain the relay chain struct /// and an indexed list of parachains that are going to be in the network. +/// +/// ```ignore +/// decl_test_network! { +/// pub struct ExampleNet { +/// relay_chain = Relay, +/// parachains = vec![ +/// (1, ParaA), +/// (2, ParaB), +/// ], +/// } +/// } +/// ``` #[macro_export] macro_rules! decl_test_network { ( From 7304c711a3934e96bb9fedfa3f7a539b4d1a9dab Mon Sep 17 00:00:00 2001 From: Szegoo Date: Mon, 24 Oct 2022 08:51:49 +0200 Subject: [PATCH 4/4] better docs --- xcm/xcm-simulator/src/lib.rs | 59 ++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/xcm/xcm-simulator/src/lib.rs b/xcm/xcm-simulator/src/lib.rs index d60e2d583f9c..a8d602037cd5 100644 --- a/xcm/xcm-simulator/src/lib.rs +++ b/xcm/xcm-simulator/src/lib.rs @@ -77,17 +77,17 @@ pub fn encode_xcm(message: Xcm<()>, message_kind: MessageKind) -> Vec { } } -/// Expects a relay chain struct as an argument and implements UMP for it. The -/// provided struct needs to have the `Runtime` and `XcmConfig` defined. Also -/// expects the `TestExternalities` to be provided in the relay chain struct. +/// The macro is implementing upward message passing(UMP) for the provided relay +/// chain struct. The struct has to provide the XCM configuration for the relay +/// chain. /// /// ```ignore /// decl_test_relay_chain! { -/// pub struct Relay { -/// Runtime = relay_chain::Runtime, -/// XcmConfig = relay_chain::XcmConfig, -/// new_ext = relay_ext(), -/// } +/// pub struct Relay { +/// Runtime = relay_chain::Runtime, +/// XcmConfig = relay_chain::XcmConfig, +/// new_ext = relay_ext(), +/// } /// } /// ``` #[macro_export] @@ -122,19 +122,19 @@ macro_rules! decl_test_relay_chain { }; } -/// Expects a parachain struct as an argument and implements`DmpMessageHandlerT` -/// and `XcmpMessageHandlerT` traits for it. The macro expects the provided struct -/// to define `Runtime`, `DmpMessageHandler` and `XcmpMessageHandler`. Also expects -/// the `TestExternalities` to be provided in the relay chain struct. +/// The macro is implementing the `XcmMessageHandlerT` and `DmpMessageHandlerT` +/// traits for the provided parachain struct. Expects the provided parachain +/// struct to define the XcmpMessageHandler and DmpMessageHandler pallets that +/// contain the message handling logic. /// /// ```ignore /// decl_test_parachain! { -/// pub struct ParaA { -/// Runtime = parachain::Runtime, -/// XcmpMessageHandler = parachain::MsgQueue, -/// DmpMessageHandler = parachain::MsgQueue, -/// new_ext = para_ext(), -/// } +/// pub struct ParaA { +/// Runtime = parachain::Runtime, +/// XcmpMessageHandler = parachain::MsgQueue, +/// DmpMessageHandler = parachain::MsgQueue, +/// new_ext = para_ext(), +/// } /// } /// ``` #[macro_export] @@ -232,20 +232,21 @@ thread_local! { = RefCell::new(VecDeque::new()); } -/// Declares a test network. Expects a network struct as an argument and -/// implements some functionality for testing and the `ParachainXcmRouter` and -/// `RelayChainXcmRouter`. The struct needs to contain the relay chain struct -/// and an indexed list of parachains that are going to be in the network. +/// Declares a test network that consists of a relay chain and multiple +/// parachains. Expects a network struct as an argument and implements testing +/// functionality, `ParachainXcmRouter` and the `RelayChainXcmRouter`. The +/// struct needs to contain the relay chain struct and an indexed list of +/// parachains that are going to be in the network. /// /// ```ignore /// decl_test_network! { -/// pub struct ExampleNet { -/// relay_chain = Relay, -/// parachains = vec![ -/// (1, ParaA), -/// (2, ParaB), -/// ], -/// } +/// pub struct ExampleNet { +/// relay_chain = Relay, +/// parachains = vec![ +/// (1, ParaA), +/// (2, ParaB), +/// ], +/// } /// } /// ``` #[macro_export]