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:

1. Fee asset sent to fee reserve chain = fee_amount - min_xcm_fee
2. 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.