XCM NFT types that use Granular NFT traits (#4300)

## Overview

This PR provides new XCM types and tools for building NFT Asset
Transactors.
The new types use general and granular NFT traits from #5620.

The new XCM adapters and utility types to work with NFTs can be
considered the main deliverable of the **[XCM NFT
proposal](https://polkadot.polkassembly.io/referenda/379)**. The new
types use a more general approach, making integration into any chain
with various NFT implementations easier.

For instance, different implementations could use:
* different ID assignment approaches
    * predefined NFT IDs - pallet-uniques, pallet-nfts
* derived NFT IDs (NFT IDs are automatically derived from collection
IDs) - Unique Network, ORML/Acala, Aventus
* classless (collection-less) tokens - CoreTime NFTs, Aventus NFT
Manager NFTs
* in-class (in-collection) tokens - Unique Network, pallet-uniques,
pallet-nfts, ORML/Acala
* different approaches to storing associated data on-chain:
    * data is stored entirely separately from tokens - pallet-uniques
* data is stored partially or entirely within tokens (i.e., burning a
token means destroying it with its data) - pallet-nfts
([partially](https://github.com/paritytech/polkadot-sdk/blob/8b4cfda7589325d1a34f70b3770ab494a9d4052c/substrate/frame/nfts/src/features/create_delete_item.rs#L240-L241)),
Unique Network, ORML/Acala

With new types, these differences can be abstracted away.

Moreover, the new types provide greater flexibility for supporting
derivative NFTs, allowing several possible approaches depending on the
given chain's team's goals or restrictions (see the `pallet-derivatives`
crate docs and mock docs).

Also, this is the PR I mentioned in the
#4073 issue, as it can
be viewed as the solution. In particular, the new adapter
(`UniqueInstancesAdapter`) requires the `Update` operation with the
`ChangeOwnerFrom` strategy. This brings the attention of both a
developer and a reviewer to the `ChangeOwnerFrom` strategy (meaning that
the transfer checks if the asset can be transferred from a given account
to another account), both at trait bound and at the call site, without
sacrificing the flexibility of the NFT traits.

## New types for xcm-builder and xcm-executor

This PR introduces several XCM types.

The `UniqueInstancesAdapter` is a new `TransactAsset` adapter that
supersedes both `NonFungibleAdapter` and `NonFungiblesAdapter` (for
reserve-based transfers only, as teleports can't be implemented
appropriately without transferring the NFT metadata alongside it; no
standard solution exists for that yet. Hopefully, the Felloweship RFC
125 ([PR](polkadot-fellows/RFCs#125),
[text](https://github.com/polkadot-fellows/RFCs/blob/3a24444278f22dac414fbd2b5c4b205f73d78af7/text/0125-xcm-asset-metadata.md))
will help with that).

Thanks to the new Matcher types, the new adapter can be used instead of
both `NonFungibleAdapter` and `NonFungiblesAdapter`:
* `MatchesInstance` (a trait)
* `MatchInClassInstances`
* `MatchClasslessInstances`

The `UniqueInstancesAdapter` works with existing tokens only. To create
new tokens (derivative ones), there is the
`UniqueInstancesDepositAdapter`.

See the `pallet-derivatives` mock and tests for the usage example.

### Superseding the old adapters for pallet-uniques

Here is how the new `UniqueInstancesAdapter` in Westend Asset Hub
replaces the `NonFungiblesAdapter`:

```rust
/// Means for transacting unique assets.
pub type UniquesTransactor = UniqueInstancesAdapter<
	AccountId,
	LocationToAccountId,
	MatchInClassInstances<UniquesConvertedConcreteId>,
	pallet_uniques::asset_ops::Item<Uniques>,
>;
```

`MatchInClassInstances` allows us to reuse the already existing
`UniquesConvertedConcreteId` matcher.
The `pallet_uniques::asset_ops::Item<Uniques>` already implements the
needed traits.

So, migrating from the old adapter to the new one regarding runtime
config changes is easy.

>NOTE: `pallet_uniques::asset_ops::Item` grants access to the asset
operations of NFT items of a given pallet-uniques instance, whereas
`pallet_uniques::asset_ops::Collection` grants access to the collection
operations.

### Declarative modification of an NFT engine

If an NFT-hosting pallet only implements a transfer operation but not
the `Stash` and `Restore`, one could declaratively add them using the
`UniqueInstancesWithStashAccount` adapter.

So, you can use it with the `UniqueInstancesAdapter` as follows:
```rust
parameter_types! {
    	pub StashAccountId: AccountId = /* Some Stash Account ID */;
}

type Transactor = UniqueInstancesAdapter<
	AccountId,
	LocationToAccountId,
	Matcher,
	UniqueInstancesWithStashAccount<StashAccountId, NftEngine>,
>;
```

### Supporting derivative NFTs (reserve-based model)

There are several possible scenarios of supporting derivative NFTs (and
their collections, if applicable).

A separate NFT-hosting pallet instance could be configured to use XCM
`AssetId` as collection ID and `AssetInstance` token ID. In that case,
the asset transaction doesn't need any special treatment.

However, registering NFT collections might require a special API.
Also, if the NFT-hosting pallet can't be configured to use XCM ID types,
we would need to store a mapping between the XCM ID of the original
token and the derivative ID.

See the `pallet-derivatives` crate docs for details.
The example of its usage can be found in its mock and tests.

#### TODO

No benchmarks were run for `pallet-derivatives`, so there is no
`weights.rs` for it yet.

---------

Co-authored-by: Branislav Kontur <bkontur@gmail.com>
Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com>

Author: 3 people

Cargo.lock

@@ -356,6 +356,7 @@ members = [
 	"substrate/frame/core-fellowship",
 	"substrate/frame/delegated-staking",
 	"substrate/frame/democracy",
+	"substrate/frame/derivatives",
 	"substrate/frame/dummy-dim",
 	"substrate/frame/election-provider-multi-block",
 	"substrate/frame/election-provider-multi-phase",
@@ -1051,6 +1052,7 @@ pallet-staking-runtime-api = { path = "substrate/frame/staking/runtime-api", def
 revive-dev-node = { path = "substrate/frame/revive/dev-node/node" }
 revive-dev-runtime = { path = "substrate/frame/revive/dev-node/runtime" }
 # TODO: remove the reward stuff as they are not needed here
+pallet-derivatives = { path = "polkadot/xcm/pallet-derivatives", default-features = false }
 pallet-staking-async = { path = "substrate/frame/staking-async", default-features = false }
 pallet-staking-async-ah-client = { path = "substrate/frame/staking-async/ah-client", default-features = false }
 pallet-staking-async-parachain-runtime = { path = "substrate/frame/staking-async/runtimes/parachain" }

Cargo.toml

@@ -48,13 +48,14 @@ use testnet_parachains_constants::rococo::snowbridge::{
 };
 use xcm::latest::{prelude::*, ROCOCO_GENESIS_HASH, WESTEND_GENESIS_HASH};
 use xcm_builder::{
-	AccountId32Aliases, AliasChildLocation, AllowExplicitUnpaidExecutionFrom,
-	AllowHrmpNotificationsFromRelayChain, AllowKnownQueryResponses, AllowSubscriptionsFrom,
-	AllowTopLevelPaidExecutionFrom, DenyRecursively, DenyReserveTransferToRelayChain, DenyThenTry,
-	DescribeAllTerminal, DescribeFamily, EnsureXcmOrigin, ExternalConsensusLocationsConverterFor,
+	unique_instances::UniqueInstancesAdapter, AccountId32Aliases, AliasChildLocation,
+	AllowExplicitUnpaidExecutionFrom, AllowHrmpNotificationsFromRelayChain,
+	AllowKnownQueryResponses, AllowSubscriptionsFrom, AllowTopLevelPaidExecutionFrom,
+	DenyRecursively, DenyReserveTransferToRelayChain, DenyThenTry, DescribeAllTerminal,
+	DescribeFamily, EnsureXcmOrigin, ExternalConsensusLocationsConverterFor,
 	FrameTransactionalProcessor, FungibleAdapter, FungiblesAdapter, HashedDescription, IsConcrete,
-	LocalMint, MatchedConvertedConcreteId, NetworkExportTableItem, NoChecking, NonFungiblesAdapter,
-	ParentAsSuperuser, ParentIsPreset, RelayChainAsNative, SendXcmFeeToAccount,
+	LocalMint, MatchInClassInstances, MatchedConvertedConcreteId, NetworkExportTableItem,
+	NoChecking, ParentAsSuperuser, ParentIsPreset, RelayChainAsNative, SendXcmFeeToAccount,
 	SiblingParachainAsNative, SiblingParachainConvertsVia, SignedAccountId32AsNative,
 	SignedToAccountId32, SingleAssetExchangeAdapter, SovereignPaidRemoteExporter,
 	SovereignSignedViaLocation, StartsWith, StartsWithExplicitGlobalConsensus, TakeWeightCredit,
@@ -147,19 +148,11 @@ pub type UniquesConvertedConcreteId =
 	assets_common::UniquesConvertedConcreteId<UniquesPalletLocation>;
 
 /// Means for transacting unique assets.
-pub type UniquesTransactor = NonFungiblesAdapter<
-	// Use this non-fungibles implementation:
-	Uniques,
-	// This adapter will handle any non-fungible asset from the uniques pallet.
-	UniquesConvertedConcreteId,
-	// Convert an XCM Location into a local account id:
-	LocationToAccountId,
-	// Our chain's account ID type (we can't get away without mentioning it explicitly):
+pub type UniquesTransactor = UniqueInstancesAdapter<
 	AccountId,
-	// Does not check teleports.
-	NoChecking,
-	// The account to use for tracking teleports.
-	CheckingAccount,
+	LocationToAccountId,
+	MatchInClassInstances<UniquesConvertedConcreteId>,
+	pallet_uniques::asset_ops::Item<Uniques>,
 >;
 
 /// `AssetId`/`Balance` converter for `ForeignAssets`.

cumulus/parachains/runtimes/assets/asset-hub-rococo/src/xcm_config.rs

@@ -48,13 +48,14 @@ use westend_runtime_constants::{
 };
 use xcm::latest::{prelude::*, ROCOCO_GENESIS_HASH, WESTEND_GENESIS_HASH};
 use xcm_builder::{
-	AccountId32Aliases, AliasChildLocation, AllowExplicitUnpaidExecutionFrom,
-	AllowHrmpNotificationsFromRelayChain, AllowKnownQueryResponses, AllowSubscriptionsFrom,
-	AllowTopLevelPaidExecutionFrom, DenyRecursively, DenyReserveTransferToRelayChain, DenyThenTry,
-	DescribeAllTerminal, DescribeFamily, EnsureXcmOrigin, ExternalConsensusLocationsConverterFor,
+	unique_instances::UniqueInstancesAdapter, AccountId32Aliases, AliasChildLocation,
+	AllowExplicitUnpaidExecutionFrom, AllowHrmpNotificationsFromRelayChain,
+	AllowKnownQueryResponses, AllowSubscriptionsFrom, AllowTopLevelPaidExecutionFrom,
+	DenyRecursively, DenyReserveTransferToRelayChain, DenyThenTry, DescribeAllTerminal,
+	DescribeFamily, EnsureXcmOrigin, ExternalConsensusLocationsConverterFor,
 	FrameTransactionalProcessor, FungibleAdapter, FungiblesAdapter, HashedDescription, IsConcrete,
-	LocalMint, MatchedConvertedConcreteId, MintLocation, NetworkExportTableItem, NoChecking,
-	NonFungiblesAdapter, OriginToPluralityVoice, ParentAsSuperuser, ParentIsPreset,
+	LocalMint, MatchInClassInstances, MatchedConvertedConcreteId, MintLocation,
+	NetworkExportTableItem, NoChecking, OriginToPluralityVoice, ParentAsSuperuser, ParentIsPreset,
 	RelayChainAsNative, SendXcmFeeToAccount, SiblingParachainAsNative, SiblingParachainConvertsVia,
 	SignedAccountId32AsNative, SignedToAccountId32, SingleAssetExchangeAdapter,
 	SovereignSignedViaLocation, StartsWith, StartsWithExplicitGlobalConsensus, TakeWeightCredit,
@@ -143,19 +144,11 @@ pub type UniquesConvertedConcreteId =
 	assets_common::UniquesConvertedConcreteId<UniquesPalletLocation>;
 
 /// Means for transacting unique assets.
-pub type UniquesTransactor = NonFungiblesAdapter<
-	// Use this non-fungibles implementation:
-	Uniques,
-	// This adapter will handle any non-fungible asset from the uniques pallet.
-	UniquesConvertedConcreteId,
-	// Convert an XCM Location into a local account id:
-	LocationToAccountId,
-	// Our chain's account ID type (we can't get away without mentioning it explicitly):
+pub type UniquesTransactor = UniqueInstancesAdapter<
 	AccountId,
-	// Does not check teleports.
-	NoChecking,
-	// The account to use for tracking teleports.
-	CheckingAccount,
+	LocationToAccountId,
+	MatchInClassInstances<UniquesConvertedConcreteId>,
+	pallet_uniques::asset_ops::Item<Uniques>,
 >;
 
 /// `AssetId`/`Balance` converter for `ForeignAssets`.

cumulus/parachains/runtimes/assets/asset-hub-westend/src/xcm_config.rs

@@ -25,12 +25,13 @@ use asset_hub_westend_runtime::{
 	governance, xcm_config,
 	xcm_config::{
 		bridging, CheckingAccount, LocationToAccountId, StakingPot,
-		TrustBackedAssetsPalletLocation, WestendLocation, XcmConfig,
+		TrustBackedAssetsPalletLocation, UniquesConvertedConcreteId, UniquesPalletLocation,
+		WestendLocation, XcmConfig,
 	},
 	AllPalletsWithoutSystem, Assets, Balances, Block, ExistentialDeposit, ForeignAssets,
 	ForeignAssetsInstance, MetadataDepositBase, MetadataDepositPerByte, ParachainSystem,
 	PolkadotXcm, Revive, Runtime, RuntimeCall, RuntimeEvent, RuntimeOrigin, SessionKeys,
-	ToRococoXcmRouterInstance, TrustBackedAssetsInstance, XcmpQueue,
+	ToRococoXcmRouterInstance, TrustBackedAssetsInstance, Uniques, XcmpQueue,
 };
 pub use asset_hub_westend_runtime::{AssetConversion, AssetDeposit, CollatorSelection, System};
 use asset_test_utils::{
@@ -45,6 +46,10 @@ use frame_support::{
 		fungibles::{
 			self, Create, Inspect as FungiblesInspect, InspectEnumerable, Mutate as FungiblesMutate,
 		},
+		tokens::asset_ops::{
+			common_strategies::{Bytes, Owner},
+			Inspect as InspectUniqueAsset,
+		},
 		ContainsPair,
 	},
 	weights::{Weight, WeightToFee as WeightToFeeT},
@@ -55,10 +60,11 @@ use pallet_revive::{
 	Code, DepositLimit,
 };
 use pallet_revive_fixtures::compile_module;
+use pallet_uniques::{asset_ops::Item, asset_strategies::Attribute};
 use parachains_common::{AccountId, AssetIdForTrustBackedAssets, AuraId, Balance};
 use sp_consensus_aura::SlotDuration;
 use sp_core::crypto::Ss58Codec;
-use sp_runtime::{traits::MaybeEquivalence, Either};
+use sp_runtime::{traits::MaybeEquivalence, Either, MultiAddress};
 use std::convert::Into;
 use testnet_parachains_constants::westend::{consensus::*, currency::UNITS, fee::WeightToFee};
 use xcm::{
@@ -68,8 +74,11 @@ use xcm::{
 	},
 	VersionedXcm,
 };
-use xcm_builder::WithLatestLocationConverter;
-use xcm_executor::traits::{ConvertLocation, JustTry, WeightTrader};
+use xcm_builder::{
+	unique_instances::UniqueInstancesAdapter as NewNftAdapter, MatchInClassInstances, NoChecking,
+	NonFungiblesAdapter as OldNftAdapter, WithLatestLocationConverter,
+};
+use xcm_executor::traits::{ConvertLocation, JustTry, TransactAsset, WeightTrader};
 use xcm_runtime_apis::conversions::LocationToAccountHelper;
 
 const ALICE: [u8; 32] = [1u8; 32];
@@ -503,6 +512,166 @@ fn test_asset_xcm_take_first_trader_not_possible_for_non_sufficient_assets() {
 		});
 }
 
+fn test_nft_asset_transactor_works<T: TransactAsset>() {
+	ExtBuilder::<Runtime>::default()
+		.with_tracing()
+		.with_collators(vec![AccountId::from(ALICE)])
+		.with_session_keys(vec![(
+			AccountId::from(ALICE),
+			AccountId::from(ALICE),
+			SessionKeys { aura: AuraId::from(sp_core::sr25519::Public::from_raw(ALICE)) },
+		)])
+		.build()
+		.execute_with(|| {
+			let collection_id = 42;
+			let item_id = 101;
+
+			let alice = AccountId::from(ALICE);
+			let bob = AccountId::from(BOB);
+			let ctx = XcmContext { origin: None, message_id: XcmHash::default(), topic: None };
+
+			assert_ok!(Balances::mint_into(&alice, 2 * UNITS));
+
+			assert_ok!(Uniques::create(
+				RuntimeHelper::origin_of(alice.clone()),
+				collection_id,
+				MultiAddress::Id(alice.clone()),
+			));
+
+			assert_ok!(Uniques::mint(
+				RuntimeHelper::origin_of(alice.clone()),
+				collection_id,
+				item_id,
+				MultiAddress::Id(bob.clone()),
+			));
+
+			let attr_key = vec![0xA, 0xA, 0xB, 0xB];
+			let attr_value = vec![0xC, 0x0, 0x0, 0x1, 0xF, 0x0, 0x0, 0xD];
+
+			assert_ok!(Uniques::set_attribute(
+				RuntimeHelper::origin_of(alice.clone()),
+				collection_id,
+				Some(item_id),
+				attr_key.clone().try_into().unwrap(),
+				attr_value.clone().try_into().unwrap(),
+			));
+
+			let collection_location = UniquesPalletLocation::get()
+				.appended_with(GeneralIndex(collection_id.into()))
+				.unwrap();
+			let item_asset: Asset =
+				(collection_location, AssetInstance::Index(item_id.into())).into();
+
+			let alice_account_location: Location = alice.clone().into();
+			let bob_account_location: Location = bob.clone().into();
+
+			// Can't deposit the token that isn't withdrawn
+			assert_err!(
+				T::deposit_asset(&item_asset, &alice_account_location, Some(&ctx),),
+				XcmError::FailedToTransactAsset("AlreadyExists")
+			);
+
+			// Alice isn't the owner, she can't withdraw the token
+			assert_noop!(
+				T::withdraw_asset(&item_asset, &alice_account_location, Some(&ctx),),
+				XcmError::FailedToTransactAsset("NoPermission")
+			);
+
+			// Bob, the owner, can withdraw the token
+			assert_ok!(T::withdraw_asset(&item_asset, &bob_account_location, Some(&ctx),));
+
+			// The token is withdrawn
+			assert_eq!(
+				Item::<Uniques>::inspect(&(collection_id, item_id), Owner::default()),
+				Err(pallet_uniques::Error::<Runtime>::UnknownItem.into()),
+			);
+
+			// But the attribute data is preserved as the pallet-uniques works that way.
+			assert_eq!(
+				Item::<Uniques>::inspect(
+					&(collection_id, item_id),
+					Bytes(Attribute(attr_key.as_slice()))
+				),
+				Ok(attr_value.clone()),
+			);
+
+			// Can't withdraw the already withdrawn token
+			assert_err!(
+				T::withdraw_asset(&item_asset, &bob_account_location, Some(&ctx),),
+				XcmError::FailedToTransactAsset("UnknownCollection")
+			);
+
+			// Deposit the token to alice
+			assert_ok!(T::deposit_asset(&item_asset, &alice_account_location, Some(&ctx),));
+
+			// The token is deposited
+			assert_eq!(
+				Item::<Uniques>::inspect(&(collection_id, item_id), Owner::default()),
+				Ok(alice.clone()),
+			);
+
+			// The attribute data is the same
+			assert_eq!(
+				Item::<Uniques>::inspect(
+					&(collection_id, item_id),
+					Bytes(Attribute(attr_key.as_slice()))
+				),
+				Ok(attr_value.clone()),
+			);
+
+			// Can't deposit the token twice
+			assert_err!(
+				T::deposit_asset(&item_asset, &alice_account_location, Some(&ctx),),
+				XcmError::FailedToTransactAsset("AlreadyExists")
+			);
+
+			// Transfer the token directly
+			assert_ok!(T::transfer_asset(
+				&item_asset,
+				&alice_account_location,
+				&bob_account_location,
+				&ctx,
+			));
+
+			// The token's owner has changed
+			assert_eq!(
+				Item::<Uniques>::inspect(&(collection_id, item_id), Owner::default()),
+				Ok(bob.clone()),
+			);
+
+			// The attribute data is the same
+			assert_eq!(
+				Item::<Uniques>::inspect(
+					&(collection_id, item_id),
+					Bytes(Attribute(attr_key.as_slice()))
+				),
+				Ok(attr_value.clone()),
+			);
+		});
+}
+
+#[test]
+fn test_new_nft_config_works_as_the_old_one() {
+	type OldNftTransactor = OldNftAdapter<
+		Uniques,
+		UniquesConvertedConcreteId,
+		LocationToAccountId,
+		AccountId,
+		NoChecking,
+		CheckingAccount,
+	>;
+
+	type NewNftTransactor = NewNftAdapter<
+		AccountId,
+		LocationToAccountId,
+		MatchInClassInstances<UniquesConvertedConcreteId>,
+		Item<Uniques>,
+	>;
+
+	test_nft_asset_transactor_works::<OldNftTransactor>();
+	test_nft_asset_transactor_works::<NewNftTransactor>();
+}
+
 #[test]
 fn test_assets_balances_api_works() {
 	use assets_common::runtime_api::runtime_decl_for_fungibles_api::FungiblesApi;