Skip to content

Commit 667a6d7

Browse files
shaunxwshaunxw
authored
xtokens and xcm-support documentations (#404)
* Add xtokens module docstring. * Add xtokens readme. * Add documentations for xcm-support. * Add xtokens and xcm-support entries in main readme.
1 parent 8d7e297 commit 667a6d7

File tree

5 files changed

+88
-2
lines changed

5 files changed

+88
-2
lines changed

‎README.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ The Open Runtime Module Library (ORML) is a community maintained collection of S
2323
- Provides scheduled balance locking mechanism, in a *graded vesting* way.
2424
- [orml-gradually-update](./gradually-update)
2525
- Provides way to adjust numeric parameter gradually over a period of time.
26+
- [orml-xtokens](./xtokens)
27+
- Provides way to do cross-chain assets transfer.
28+
- [orml-xcm-support](./xcm-support)
29+
- Provides traits, types, and implementations to support XCM integration.
2630

2731
## Example
2832

@@ -48,7 +52,7 @@ ORML use `Cargo.dev.toml` to avoid workspace conflicts with project cargo config
4852
- change the command to `make dev-check` etc which does the copy. (For the full list of `make` commands, check `Makefile`)
4953

5054
# Web3 Foundation Grant Project
51-
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.
55+
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.
5256

5357
# Projects using ORML
5458
- [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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# XCM Support Module.
2+
3+
## Overview
4+
5+
The XCM support module provides supporting traits, types and implementations,
6+
to support cross-chain message(XCM) integration with ORML modules.

‎xcm-support/src/lib.rs

+17
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
//! # XCM Support Module.
2+
//!
3+
//! ## Overview
4+
//!
5+
//! The XCM support module provides supporting traits, types and
6+
//! implementations, to support cross-chain message(XCM) integration with ORML
7+
//! modules.
8+
19
#![cfg_attr(not(feature = "std"), no_std)]
210

311
use frame_support::{dispatch::DispatchResult, traits::Get};
@@ -16,14 +24,19 @@ pub use currency_adapter::MultiCurrencyAdapter;
1624

1725
mod currency_adapter;
1826

27+
/// The XCM handler to execute XCM locally.
1928
pub trait XcmHandler<AccountId> {
2029
fn execute_xcm(origin: AccountId, xcm: Xcm) -> DispatchResult;
2130
}
2231

32+
/// Convert `MultiAsset` to `CurrencyId`.
2333
pub trait CurrencyIdConversion<CurrencyId> {
34+
/// Get `CurrencyId` from `MultiAsset`. Returns `None` if conversion failed.
2435
fn from_asset(asset: &MultiAsset) -> Option<CurrencyId>;
2536
}
2637

38+
/// A `MatchesFungible` implementation. It matches relay chain tokens or
39+
/// parachain tokens that could be decoded from a general key.
2740
pub struct IsConcreteWithGeneralKey<CurrencyId, FromRelayChainBalance>(
2841
PhantomData<(CurrencyId, FromRelayChainBalance)>,
2942
);
@@ -51,6 +64,8 @@ where
5164
}
5265
}
5366

67+
/// A `FilterAssetLocation` implementation. Filters native assets and ORML
68+
/// tokens via provided general key to `MultiLocation` pairs.
5469
pub struct NativePalletAssetOr<Pairs>(PhantomData<Pairs>);
5570
impl<Pairs: Get<BTreeSet<(Vec<u8>, MultiLocation)>>> FilterAssetLocation for NativePalletAssetOr<Pairs> {
5671
fn filter_asset_location(asset: &MultiAsset, origin: &MultiLocation) -> bool {
@@ -69,6 +84,8 @@ impl<Pairs: Get<BTreeSet<(Vec<u8>, MultiLocation)>>> FilterAssetLocation for Nat
6984
}
7085
}
7186

87+
/// `CurrencyIdConversion` implementation. Converts relay chain tokens, or
88+
/// parachain tokens that could be decoded from a general key.
7289
pub struct CurrencyIdConverter<CurrencyId, RelayChainCurrencyId>(
7390
PhantomData<CurrencyId>,
7491
PhantomData<RelayChainCurrencyId>,

‎xtokens/README.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Xtokens Module
2+
3+
## Overview
4+
5+
The xtokens module provides cross-chain token transfer functionality, by cross-consensus
6+
messages(XCM).
7+
8+
The xtokens module provides functions for
9+
- Token transfer from parachains to relay chain.
10+
- Token transfer between parachains, including relay chain tokens like DOT,
11+
KSM, and parachain tokens like ACA, aUSD.
12+
13+
## Notes
14+
15+
#### Unit tests
16+
17+
Unit tests could be added once Polkadot has XCM simulator. https://github.com/paritytech/polkadot/issues/2544
18+
19+
#### Integration tests
20+
21+
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:
22+
23+
- Transfer relay chain tokens to relay chain.
24+
- Use dispatchable call `transfer_to_relay_chain`.
25+
- Transfer tokens issued by parachain A, from parachain A to parachain B.
26+
- Use dispatchable call `transfer_to_parachain`.
27+
- Sending the tx from parachain A.
28+
- Set the destination as Parachain B.
29+
- Set the currency ID as parachain A token.
30+
- Transfer tokens issued by parachain B, from parachain A to parachain B.
31+
- Use dispatchable call `transfer_to_parachain`.
32+
- Sending the tx from parachain A.
33+
- Set the destination as Parachain B.
34+
- Set the currency ID as parachain B token.
35+
- Transfer tokens issued by parachain C, from parachain A to parachain B.
36+
- Use dispatchable call `transfer_to_parachain`.
37+
- Sending the tx from parachain A.
38+
- Set the destination as Parachain B.
39+
- Set the currency ID as parachain C token.

‎xtokens/src/lib.rs

+21-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
//! # Xtokens Module
2+
//!
3+
//! ## Overview
4+
//!
5+
//! The xtokens module provides cross-chain token transfer functionality, by
6+
//! cross-consensus messages(XCM).
7+
//!
8+
//! The xtokens module provides functions for
9+
//! - Token transfer from parachains to relay chain.
10+
//! - Token transfer between parachains, including relay chain tokens like DOT,
11+
//! KSM, and parachain tokens like ACA, aUSD.
12+
//!
13+
//! ## Interface
14+
//!
15+
//! ### Dispatchable functions
16+
//!
17+
//! - `transfer_to_relay_chain`: Transfer relay chain tokens to relay chain.
18+
//! - `transfer_to_parachain`: Transfer tokens to a sibling parachain.
19+
120
#![cfg_attr(not(feature = "std"), no_std)]
221
#![allow(clippy::from_over_into)]
322
#![allow(clippy::unused_unit)]
@@ -57,6 +76,7 @@ pub mod module {
5776
pub trait Config: frame_system::Config {
5877
type Event: From<Event<Self>> + IsType<<Self as frame_system::Config>::Event>;
5978

79+
/// The balance type.
6080
type Balance: Parameter
6181
+ Member
6282
+ AtLeast32BitUnsigned
@@ -137,7 +157,7 @@ pub mod module {
137157
Ok(().into())
138158
}
139159

140-
/// Transfer tokens to parachain.
160+
/// Transfer tokens to a sibling parachain.
141161
#[pallet::weight(10)]
142162
#[transactional]
143163
pub fn transfer_to_parachain(

0 commit comments

Comments
 (0)