12 releases (1 stable)
1.0.0 | Aug 1, 2024 |
---|---|
0.13.0 | Jun 26, 2024 |
0.12.0 | Jun 3, 2024 |
0.8.0 | Mar 18, 2024 |
0.0.0 |
|
#2 in #cross-chain
114 downloads per month
230KB
6K
SLoC
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, USDT.
Notes
Integration tests
Integration tests could be done manually after integrating xtokens
into a 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.
- Transfer tokens issued by parachain A, from parachain A to parachain B.
- 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.
- 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.
- Sending the tx from parachain A.
- Set the destination as Parachain B.
- Set the currency ID as parachain C token.
Transfer multiple currencies
- Transfer relay chain tokens to relay chain, and use relay chain token as fee
- Transfer relay chain tokens to parachain, and use relay chain token as fee
- Transfer tokens issued by parachain A, from parachain A to parachain B, and use parachain A token as a fee
- Transfer tokens issued by parachain B, from parachain A to parachain B, and use parachain B token as a fee
- Transfer tokens issued by parachain C, from parachain A to parachain B, and use parachain C token as a fee
- Transfer tokens issued by parachain B, from parachain A to parachain B, and use relay chain token as fee
Notice, in the case of parachain A transfer parachain B token to parachain B, and use relay chain token as fee. Because fee asset is relaychain token, and non fee asset is parachain B token, this is two different chain. We call chain of fee asset as fee_reserve
, and chain of non fee asset as non_fee_reserve
. And in this case fee_reserve
location is also refer to destination parachain.
The current implementation sends two XCM from a sender parachain. First XCM is sent to the fee reserve chain which will also route the XCM message to the destination parachain. Second XCM directly sent to destination parachain.
The fee amount in fee asset is split into two parts:
- Fee asset sent to fee reserve chain = fee_amount - min_xcm_fee
- Fee asset sent to dest reserve chain = min_xcm_fee
Parachains should implement config MinXcmFee
in xtokens
module config:
parameter_type_with_key! {
pub MinXcmReserveFee: |location: Location| -> Option<u128> {
#[allow(clippy::match_ref_pats)] // false positive
match (location.parents, location.first_interior()) {
(1, Some(Parachain(parachains::statemine::ID))) => Some(4_000_000_000),
_ => None,
}
};
}
If Parachain don't want have this case, can simply return None. A default implementation is provided by DisabledParachainFee
in xcm-support
.
parameter_type_with_key! {
pub ParachainMinFee: |_location: Location| -> Option<u128> {
None
};
}
Notice the implementation for now also relies on SelfLocation
which is already in xtokens
config. The SelfLocation
can be set to the absolute view (1, Parachain(THIS_PARACHAIN_ID))
and refers to the sender parachain. The alternative is to set SelfLocation
to relative view (0, Here)
to adhere to Polkadot guidelines.
We use SelfLocation
to fund fee to sender's parachain sovereign account on destination parachain, which asset is originated from sender account on sender parachain. This means if user setup too much fee, the fee will not returned to user, instead deposit to sibling parachain sovereign account on destination parachain.
Dependencies
~22–38MB
~620K SLoC