xtokens and xcm-support documentations

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)

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.

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<AccountId> {
 	fn execute_xcm(origin: AccountId, xcm: Xcm) -> DispatchResult;
 }
 
+/// Convert `MultiAsset` to `CurrencyId`.
 pub trait CurrencyIdConversion<CurrencyId> {
+	/// Get `CurrencyId` from `MultiAsset`. Returns `None` if conversion failed.
 	fn from_asset(asset: &MultiAsset) -> Option<CurrencyId>;
 }
 
+/// A `MatchesFungible` implementation. It matches relay chain tokens or
+/// parachain tokens that could be decoded from a general key.
 pub struct IsConcreteWithGeneralKey<CurrencyId, FromRelayChainBalance>(
 	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<Pairs>(PhantomData<Pairs>);
 impl<Pairs: Get<BTreeSet<(Vec<u8>, MultiLocation)>>> FilterAssetLocation for NativePalletAssetOr<Pairs> {
 	fn filter_asset_location(asset: &MultiAsset, origin: &MultiLocation) -> bool {
@@ -69,6 +84,8 @@ impl<Pairs: Get<BTreeSet<(Vec<u8>, MultiLocation)>>> FilterAssetLocation for Nat
 	}
 }
 
+/// `CurrencyIdConversion` implementation. Converts relay chain tokens, or
+/// parachain tokens that could be decoded from a general key.
 pub struct CurrencyIdConverter<CurrencyId, RelayChainCurrencyId>(
 	PhantomData<CurrencyId>,
 	PhantomData<RelayChainCurrencyId>,

xtokens/README.md

@@ -0,0 +1,39 @@
+# Xtokens Module
+
+## Overview
+
+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.
+- 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.

xtokens/src/lib.rs

@@ -1,3 +1,22 @@
+//! # Xtokens Module
+//!
+//! ## Overview
+//!
+//! 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.
+//! - Token transfer between parachains, including relay chain tokens 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 +76,7 @@ pub mod module {
 	pub trait Config: frame_system::Config {
 		type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
 
+		/// The balance type.
 		type Balance: Parameter
 			+ Member
 			+ AtLeast32BitUnsigned
@@ -137,7 +157,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(