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/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/README.md b/xtokens/README.md new file mode 100644 index 000000000..7032f29b8 --- /dev/null +++ b/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. diff --git a/xtokens/src/lib.rs b/xtokens/src/lib.rs index cada34e21..92f4ad9b3 100644 --- a/xtokens/src/lib.rs +++ b/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> + IsType<::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(