XCM v1

[gavofyork]

A number of changes and renames to the XCM framework, with the centrepiece being a safer, more ergonomic MultiAsset where matching is a lot less verbose/tedious and the underlying code is simpler. Additionally, Assets has been largely rewritten, optimising a number of operations and removing a lot of superfluous code.

This fixes a number of issues with the existing MultiAsset:

• No type safety over where masks should be allowed
• Unspecified/incorrect behaviour where multiple wildcards are used in asset arithmetic
• Overly complicated matching and construction code needed

It replaces the large, unwieldy and overly general MultiAsset with:

• MultiAsset: A single asset type, either a single non-fungible instance or a non-zero amount of a fungible.
• MultiAssets: A vec of MultiAsset, sorted, with no duplicate non-fungibles or repetitions of the same fungible.
• WildMultiAsset: A wildcard which describes classes of assets; either All assets or all of a particular identified class of fungibles or non-fungibles.
• MultiAssetFilter: A means of filtering a collection of assets. Takes the form of either a WildMultiAsset value or a MultiAssets value. Unlike with the old Vec<MultiAsset> paradigm, the two cannot be combined - it's either one wildcard or a list of definite assets.

A number of conversions are provided to allow ease of use:

• u128::into() and AssetInstance::into() will convert into a Fungibility, as will anything which itself will convert into an AssetInstance.
• Junction::into(), MultiLocation::into() and Vec::<u8>::into() will convert into a AssetId.
• (), [u8; 4], [u8; 8], [u8; 16], [u8; 32] and Vec<u8> will convert into an AssetInstance. A u128 will NOT convert and must be stated explicitly with Index(u128), since otherwise this collides with the u128::into() of Fungibility.
• (AssetId, Fungibility)::into() will convert into a MultiAsset or MultiAssets; AssetId and Fungibility can both be optionally substituted with a type that converts into them, allowing for e.g. (Junction, u128)::into().
• Vec<MultiAsset>::into() will convert into MultiAssets and MultiAssetFilter
• MultiAsset::into() and MultiAssets::into() will convert into MultiAssetFilter
• (AssetId, WildFungibility)::into() will convert into a WildMultiAsset and MultiAssetFilter; AssetId can be optionally substituted with a type that converts into it.

Compatibility

The v0 API remains in place and unchanged with one minor exception (AssetInstance::Index moving from a struct item to a tuple item). XCM messages may be converted between v0::Xcm API and v1::Xcm API with .try_into(). VersionedXcm supports both.

Automatic backwards compatibility is provided for incoming messages, so runtimes using this code will be able to interpret and execute v0::Xcm messages sent from older runtimes.

Messages sent as part of executing an XCM operation (e.g. DepositReserveAsset sending the ReserveAssetDeposited message) will be authored under the v1::Xcm API. A new trait WrapVersion is provided to determine which version they will eventually be encoded with prior to sending based on the destination. Chains concerned about destination chains being unable to interpret v1 messages should implement this trait to ensure that such destintions have messages first translated to v0::Xcm for encoding. A ForceV0 implementation is given which does a blanket v0 translation for all destinations, however it is not recommended for general use since v0 does not support all v1 features and messsages using them will fail to be encoded and sent.

Compatibility v0 -> v1 (receiving messages from a legacy chain)

• BuyExecution::fees is required to be a single, definite (non-wild) asset. fees: vec![MultiAsset::All], a typical pattern in the past, has no equivalent in v1. This is due to an internal change in xcm_executer and cannot easily be worked around. If the v0 chain has vec![MultiAsset::All] hardcoded for the fees parameter, it will need to be upgraded to specify fees explicitly and with only a single, definite asset. Avoid bad pattern of wildcard fees #3578 fixes this usage in pallet_xcm and all chains should be upgrades to use it ASAP.
• Vec<MultiAsset> may contain at most one wildcard, and if it does, it must be the only element.
• MultiAsset::AllFungible and MultiAsset::AllNonFungible have no equivalent in v1 and messages using them will result in failure.

Compatibility v1 -> v0 (sending messages to a legacy chain)

• BuyExecution::orders has no equivalent in v0 and messages where it is not empty will fail translation.

Migrating from v0::Xcm API

• Replace xcm::v0 for xcm::v1.
• For ease of use you may want to use the prelude declaration: use xcm::v1::prelude::*;.
• xcm::latest may be used in order to track the latest XCM version. This is not generally recommended outside of the Polkadot codebase.

MultiAsset & MultiLocation

• MultiLocation::Null becomes MultiLocation::Here

• Vec<MultiAsset> as a pattern is deprecated in favour of MultiAssets (which does not support wildcards) or MultiAssetFilter (which does).

• MultiAsset::ConcreteFungible { id: MultiLocation::Null, amount: 100 } becomes MultiAsset { id: Concrete(Here), fun: Fungible(100) } or just (Here, 100).into().

• MultiAsset::ConcreteNonFungible { id: MultiLocation::X1(Junction::Parent), instance: AssetInstance::Blob(vec![0]) } becomes MultiAsset { id: Concrete(X1(Parent)), fun: NonFungible(Blob(vec![0])) } or just (Parent, vec![0]).into().

• vec![MultiAsset::All] becomes Wild(All) or All.into() (both of type MultiAssetFilter).

• vec![MultiAsset::None] becomes Definite(vec![]) (of type MultiAssetFilter) or just vec![].into() (of type MultiAssets or MultiAssetFilter).

• vec![MultiAsset::AllConcreteFungible { id: Null }] becomes Wild(AllOf(fun: WildFungible, id: Here)) or just (Here, WildFungible).into()

• MultiAsset::AllFungibles and MultiAsset::AllNonFungibles have been removed and can no longer be used.

• A MultiAsset must strictly identify an asset: there is no MultiAsset value equivalent to the old MultiAsset::None. Fungible assets may not have a zero amount. To allow for an asset value which could include "no asset", use MultiAssets (if more than one asset type is allowable) or Option<MultiAsset> (otherwise).

XCM

Within XCM, the once ubiquitous Vec<MultiAsset> has now been changed to be one of:

• MultiAssets in the Xcm items, since these describe definite (lists of) assets rather than filters and thus cannot be wild.
• MultiAsset in the Order::BuyExecution item, since it describes fees and we choose not to support fee payment in multiple asset types.
• MultiAssetFilter in all other Order items, since these select/filter assets from the Holding Register.

DepositAsset and DepositReserveAsset now both have an additional max_assets field, which states the maximum number of unique assets/asset instances which may be deposited from the Holding Register. This is trivial to provide in the case of a definite set of assets, but requires some knowledge of the expected value of the contents of Holding if wildcards are used.

There are some additional renames to Xcm:

• ReserveAssetDeposit becomes ReserveAssetDeposited
• TeleportAsset becomes ReceiveTeleportedAsset
• TransferAsset::dest becomes TransferAsset::beneficiary

And to Order:

• Null becomes Noop
• DepositAsset::dest becomes DepositAsset::beneficiary
• TransferAsset::dest becomes TransferAsset::beneficiary

Other changes

• FixedRateOfConcreteFungible has been deprecated - use FixedRateOfFungible instead.
• pallet_xcm::Config now has a new type field LocationInverter; this should be equivalent to the field of the same name in xcm_executor::Config.
• AssetInstance::Index ( index: N } becomes AssetInstance::Index(N) (NOTE: This is also the case in v0)

TODO:

• Implement all the same functionality as OldMultiAsset.
• Convert all constructor and matching code over in:
  • Polkadot codebase
  • XCM Builder tests
  • Cumulus codebase (Support XCM v1 (Companion to #2815) cumulus#561)
• Optimize:
  • Optimize subsume_assets
  • Optimize checked_sub
• Remove OldMultiAsset

[apopiak]

👍 for the MultiAsset/WildMultiAsset/MultiAssetFilter distinction

[apopiak]

late nitpick: I would expect an iterator from drain based the Substrate function of the same name
this looks more like into_inner to me

[xlc]

This is a transaction_version breaking change. Maybe need some additional label so frontend developers can be aware about this?

[shawntabrizi]

done. We also have CI which would flag this automatically when the release comes.

[shaunxw]

I think polkadot.js would need updates to include new types and type changes introduced in this PR. cc @jacogr