From c5791953291ee1cef121d171be0cfb3b312050bf Mon Sep 17 00:00:00 2001 From: Shaun Wang Date: Wed, 17 Mar 2021 14:12:47 +1300 Subject: [PATCH 1/4] Add xtokens module docstring. --- xtokens/src/lib.rs | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/xtokens/src/lib.rs b/xtokens/src/lib.rs index cada34e21..655f1492e 100644 --- a/xtokens/src/lib.rs +++ b/xtokens/src/lib.rs @@ -1,3 +1,21 @@ +//! Xtokens Module +//! +//! ## Overview +//! The xtokens module provides cross-chain token transfer, by cross-consensus +//! messages(XCM). +//! +//! The xtokens module provides functions for +//! - Token transfer from parachains to relay chain. +//! - Token transfer between parachains, including relay chain token like DOT, +//! KSM, and parachain tokens like ACA, aUSD. +//! +//! ## Interface +//! +//! ### Dispatchable functions +//! +//! - `transfer_to_relay_chain`: Transfer relay chain tokens to relay chain. +//! - `transfer_to_parachain`: Transfer tokens to a sibling parachain. + #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::from_over_into)] #![allow(clippy::unused_unit)] @@ -57,6 +75,7 @@ pub mod module { pub trait Config: frame_system::Config { type Event: From> + IsType<::Event>; + /// The balance type. type Balance: Parameter + Member + AtLeast32BitUnsigned @@ -137,7 +156,7 @@ pub mod module { Ok(().into()) } - /// Transfer tokens to parachain. + /// Transfer tokens to a sibling parachain. #[pallet::weight(10)] #[transactional] pub fn transfer_to_parachain( From ba38bf15bc99189b95e34e03dd0b44bb34181482 Mon Sep 17 00:00:00 2001 From: Shaun Wang Date: Wed, 17 Mar 2021 14:39:14 +1300 Subject: [PATCH 2/4] Add xtokens readme. --- xtokens/README.md | 39 +++++++++++++++++++++++++++++++++++++++ xtokens/src/lib.rs | 2 +- 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 xtokens/README.md diff --git a/xtokens/README.md b/xtokens/README.md new file mode 100644 index 000000000..3c2070f11 --- /dev/null +++ b/xtokens/README.md @@ -0,0 +1,39 @@ +# Xtokens Module + +## Overview + +The xtokens module provides cross-chain token transfer, by cross-consensus +messages(XCM). + +The xtokens module provides functions for +- Token transfer from parachains to relay chain. +- Token transfer between parachains, including relay chain tokens like DOT, + KSM, and parachain tokens like ACA, aUSD. + +## Notes + +#### Unit tests + +Unit tests could be added once Polkadot has XCM simulator. https://github.com/paritytech/polkadot/issues/2544 + +#### Integration tests + +Integration tests could be done manually after integrating xtokens into runtime. To cover the full features, set up at least 4 relay chain validators and 3 collators of different parachains, and use dispatchable calls to include all these scenarios: + +- Transfer relay chain tokens to relay chain. + - Use dispatchable call `transfer_to_relay_chain`. +- Transfer tokens issued by parachain A, from parachain A to parachain B. + - Use dispatchable call `transfer_to_parachain`. + - Sending the tx from parachain A. + - Set the destination as Parachain B. + - Set the currency ID as parachain A token. +- Transfer tokens issued by parachain B, from parachain A to parachain B. + - Use dispatchable call `transfer_to_parachain`. + - Sending the tx from parachain A. + - Set the destination as Parachain B. + - Set the currency ID as parachain B token. +- Transfer tokens issued by parachain C, from parachain A to parachain B. + - Use dispatchable call `transfer_to_parachain`. + - Sending the tx from parachain A. + - Set the destination as Parachain B. + - Set the currency ID as parachain C token. diff --git a/xtokens/src/lib.rs b/xtokens/src/lib.rs index 655f1492e..5f18e7364 100644 --- a/xtokens/src/lib.rs +++ b/xtokens/src/lib.rs @@ -6,7 +6,7 @@ //! //! The xtokens module provides functions for //! - Token transfer from parachains to relay chain. -//! - Token transfer between parachains, including relay chain token like DOT, +//! - Token transfer between parachains, including relay chain tokens like DOT, //! KSM, and parachain tokens like ACA, aUSD. //! //! ## Interface From d95b325f5630dbadfca7e85f5436d464a1133f01 Mon Sep 17 00:00:00 2001 From: Shaun Wang Date: Wed, 17 Mar 2021 14:58:43 +1300 Subject: [PATCH 3/4] Add documentations for xcm-support. --- xcm-support/README.md | 6 ++++++ xcm-support/src/lib.rs | 17 +++++++++++++++++ xtokens/src/lib.rs | 3 ++- 3 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 xcm-support/README.md diff --git a/xcm-support/README.md b/xcm-support/README.md new file mode 100644 index 000000000..11fa712a6 --- /dev/null +++ b/xcm-support/README.md @@ -0,0 +1,6 @@ +# XCM Support Module. + +## Overview + +The XCM support module provides supporting traits, types and implementations, +to support cross-chain message(XCM) integration with ORML modules. diff --git a/xcm-support/src/lib.rs b/xcm-support/src/lib.rs index 890744d97..a2a59ed31 100644 --- a/xcm-support/src/lib.rs +++ b/xcm-support/src/lib.rs @@ -1,3 +1,11 @@ +//! # XCM Support Module. +//! +//! ## Overview +//! +//! The XCM support module provides supporting traits, types and +//! implementations, to support cross-chain message(XCM) integration with ORML +//! modules. + #![cfg_attr(not(feature = "std"), no_std)] use frame_support::{dispatch::DispatchResult, traits::Get}; @@ -16,14 +24,19 @@ pub use currency_adapter::MultiCurrencyAdapter; mod currency_adapter; +/// The XCM handler to execute XCM locally. pub trait XcmHandler { fn execute_xcm(origin: AccountId, xcm: Xcm) -> DispatchResult; } +/// Convert `MultiAsset` to `CurrencyId`. pub trait CurrencyIdConversion { + /// Get `CurrencyId` from `MultiAsset`. Returns `None` if conversion failed. fn from_asset(asset: &MultiAsset) -> Option; } +/// A `MatchesFungible` implementation. It matches relay chain tokens or +/// parachain tokens that could be decoded from a general key. pub struct IsConcreteWithGeneralKey( PhantomData<(CurrencyId, FromRelayChainBalance)>, ); @@ -51,6 +64,8 @@ where } } +/// A `FilterAssetLocation` implementation. Filters native assets and ORML +/// tokens via provided general key to `MultiLocation` pairs. pub struct NativePalletAssetOr(PhantomData); impl, MultiLocation)>>> FilterAssetLocation for NativePalletAssetOr { fn filter_asset_location(asset: &MultiAsset, origin: &MultiLocation) -> bool { @@ -69,6 +84,8 @@ impl, MultiLocation)>>> FilterAssetLocation for Nat } } +/// `CurrencyIdConversion` implementation. Converts relay chain tokens, or +/// parachain tokens that could be decoded from a general key. pub struct CurrencyIdConverter( PhantomData, PhantomData, diff --git a/xtokens/src/lib.rs b/xtokens/src/lib.rs index 5f18e7364..a2319de27 100644 --- a/xtokens/src/lib.rs +++ b/xtokens/src/lib.rs @@ -1,6 +1,7 @@ -//! Xtokens Module +//! # Xtokens Module //! //! ## Overview +//! //! The xtokens module provides cross-chain token transfer, by cross-consensus //! messages(XCM). //! From 0b19f30599335b298d79014a22547eb09d81e7c0 Mon Sep 17 00:00:00 2001 From: Shaun Wang Date: Wed, 17 Mar 2021 15:02:27 +1300 Subject: [PATCH 4/4] Add xtokens and xcm-support entries in main readme. --- README.md | 6 +++++- xtokens/README.md | 2 +- xtokens/src/lib.rs | 4 ++-- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7cc205fcc..273d09e80 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,10 @@ The Open Runtime Module Library (ORML) is a community maintained collection of S - Provides scheduled balance locking mechanism, in a *graded vesting* way. - [orml-gradually-update](./gradually-update) - Provides way to adjust numeric parameter gradually over a period of time. +- [orml-xtokens](./xtokens) + - Provides way to do cross-chain assets transfer. +- [orml-xcm-support](./xcm-support) + - Provides traits, types, and implementations to support XCM integration. ## Example @@ -48,7 +52,7 @@ ORML use `Cargo.dev.toml` to avoid workspace conflicts with project cargo config - change the command to `make dev-check` etc which does the copy. (For the full list of `make` commands, check `Makefile`) # Web3 Foundation Grant Project -ORML is part of the bigger `Open-Web3-Stack` initiative, that is currently under a General Grant from Web3 Foundation. See Application details [here](https://github.com/open-web3-stack/General-Grants-Program/blob/master/grants/speculative/open_web3_stack.md). The 1st milestone has been delivered. +ORML is part of the bigger `Open-Web3-Stack` initiative, that is currently under a General Grant from Web3 Foundation. See Application details [here](https://github.com/open-web3-stack/General-Grants-Program/blob/master/grants/speculative/open_web3_stack.md). The 1st milestone has been delivered. # Projects using ORML - [If you intend or are using ORML, please add your project here](https://github.com/open-web3-stack/open-runtime-module-library/edit/master/README.md) diff --git a/xtokens/README.md b/xtokens/README.md index 3c2070f11..7032f29b8 100644 --- a/xtokens/README.md +++ b/xtokens/README.md @@ -2,7 +2,7 @@ ## Overview -The xtokens module provides cross-chain token transfer, by cross-consensus +The xtokens module provides cross-chain token transfer functionality, by cross-consensus messages(XCM). The xtokens module provides functions for diff --git a/xtokens/src/lib.rs b/xtokens/src/lib.rs index a2319de27..92f4ad9b3 100644 --- a/xtokens/src/lib.rs +++ b/xtokens/src/lib.rs @@ -2,8 +2,8 @@ //! //! ## Overview //! -//! The xtokens module provides cross-chain token transfer, by cross-consensus -//! messages(XCM). +//! The xtokens module provides cross-chain token transfer functionality, by +//! cross-consensus messages(XCM). //! //! The xtokens module provides functions for //! - Token transfer from parachains to relay chain.