pallet-xcm: add new flexible transfer_assets() call/extrinsic (#2388)

# Motivation (+testing)

### Enable easy `ForeignAssets` transfers using `pallet-xcm` 

We had just previously added capabilities to teleport fees during
reserve-based transfers, but what about reserve-transferring fees when
needing to teleport some non-fee asset?

This PR aligns everything under either explicit reserve-transfer,
explicit teleport, or this new flexible `transfer_assets()` which can
mix and match as needed with fewer artificial constraints imposed to the
user.

This will enable, for example, a (non-system) parachain to teleport
their `ForeignAssets` assets to AssetHub while using DOT to pay fees.
(the assets are teleported - as foreign assets should from their owner
chain - while DOT used for fees can only be reserve-based transferred
between said parachain and AssetHub).

Added `xcm-emulator` tests for this scenario ^.

# Description

Reverts `(limited_)reserve_transfer_assets` to only allow reserve-based
transfers for all `assets` including fees.

Similarly `(limited_)teleport_assets` only allows teleports for all
`assets` including fees.
    
For complex combinations of asset transfers where assets and fees may
have different reserves or different reserve/teleport trust
configurations, users can use the newly added `transfer_assets()`
extrinsic which is more flexible in allowing more complex scenarios.

`assets` (excluding `fees`) must have same reserve location or otherwise
be teleportable to `dest`.
No limitations imposed on `fees`.

- for local reserve: transfer assets to sovereign account of destination
chain and forward a notification XCM to `dest` to mint and deposit
reserve-based assets to `beneficiary`.
- for destination reserve: burn local assets and forward a notification
to `dest` chain to withdraw the reserve assets from this chain's
sovereign account and deposit them to `beneficiary`.
- for remote reserve: burn local assets, forward XCM to reserve chain to
move reserves from this chain's SA to `dest` chain's SA, and forward
another XCM to `dest` to mint and deposit reserve-based assets to
`beneficiary`.
- for teleports: burn local assets and forward XCM to `dest` chain to
mint/teleport assets and deposit them to `beneficiary`.

## Review notes

Only around 500 lines are prod code (see `pallet_xcm/src/lib.rs`), the
rest of the PR is new tests and improving existing tests.

---------

Co-authored-by: command-bot <>

cumulus/parachains/integration-tests/emulated/common/src/macros.rs

@@ -120,3 +120,102 @@ macro_rules! test_parachain_is_trusted_teleporter {
 		}
 	};
 }
+
+#[macro_export]
+macro_rules! include_penpal_create_foreign_asset_on_asset_hub {
+	( $penpal:ident, $asset_hub:ident, $relay_ed:expr, $weight_to_fee:expr) => {
+		$crate::impls::paste::paste! {
+			pub fn penpal_create_foreign_asset_on_asset_hub(
+				asset_id_on_penpal: u32,
+				foreign_asset_at_asset_hub: MultiLocation,
+				ah_as_seen_by_penpal: MultiLocation,
+				is_sufficient: bool,
+				asset_owner: AccountId,
+				prefund_amount: u128,
+			) {
+				use frame_support::weights::WeightToFee;
+				let ah_check_account = $asset_hub::execute_with(|| {
+					<$asset_hub as [<$asset_hub Pallet>]>::PolkadotXcm::check_account()
+				});
+				let penpal_check_account =
+					$penpal::execute_with(|| <$penpal as [<$penpal Pallet>]>::PolkadotXcm::check_account());
+				let penpal_as_seen_by_ah = $asset_hub::sibling_location_of($penpal::para_id());
+
+				// prefund SA of Penpal on AssetHub with enough native tokens to pay for creating
+				// new foreign asset, also prefund CheckingAccount with ED, because teleported asset
+				// itself might not be sufficient and CheckingAccount cannot be created otherwise
+				let sov_penpal_on_ah = $asset_hub::sovereign_account_id_of(penpal_as_seen_by_ah);
+				$asset_hub::fund_accounts(vec![
+					(sov_penpal_on_ah.clone().into(), $relay_ed * 100_000_000_000),
+					(ah_check_account.clone().into(), $relay_ed * 1000),
+				]);
+
+				// prefund SA of AssetHub on Penpal with native asset
+				let sov_ah_on_penpal = $penpal::sovereign_account_id_of(ah_as_seen_by_penpal);
+				$penpal::fund_accounts(vec![
+					(sov_ah_on_penpal.into(), $relay_ed * 1_000_000_000),
+					(penpal_check_account.clone().into(), $relay_ed * 1000),
+				]);
+
+				// Force create asset on $penpal and prefund [<$penpal Sender>]
+				$penpal::force_create_and_mint_asset(
+					asset_id_on_penpal,
+					ASSET_MIN_BALANCE,
+					is_sufficient,
+					asset_owner,
+					None,
+					prefund_amount,
+				);
+
+				let require_weight_at_most = Weight::from_parts(1_100_000_000_000, 30_000);
+				// `OriginKind::Xcm` required by ForeignCreators pallet-assets origin filter
+				let origin_kind = OriginKind::Xcm;
+				let call_create_foreign_assets =
+					<$asset_hub as Chain>::RuntimeCall::ForeignAssets(pallet_assets::Call::<
+						<$asset_hub as Chain>::Runtime,
+						pallet_assets::Instance2,
+					>::create {
+						id: foreign_asset_at_asset_hub,
+						min_balance: ASSET_MIN_BALANCE,
+						admin: sov_penpal_on_ah.into(),
+					})
+					.encode();
+				let buy_execution_fee_amount = $weight_to_fee::weight_to_fee(
+					&Weight::from_parts(10_100_000_000_000, 300_000),
+				);
+				let buy_execution_fee = MultiAsset {
+					id: Concrete(MultiLocation { parents: 1, interior: Here }),
+					fun: Fungible(buy_execution_fee_amount),
+				};
+				let xcm = VersionedXcm::from(Xcm(vec![
+					WithdrawAsset { 0: vec![buy_execution_fee.clone()].into() },
+					BuyExecution { fees: buy_execution_fee.clone(), weight_limit: Unlimited },
+					Transact { require_weight_at_most, origin_kind, call: call_create_foreign_assets.into() },
+					ExpectTransactStatus(MaybeErrorCode::Success),
+					RefundSurplus,
+					DepositAsset { assets: All.into(), beneficiary: penpal_as_seen_by_ah },
+				]));
+				// Send XCM message from penpal => asset_hub
+				let sudo_penpal_origin = <$penpal as Chain>::RuntimeOrigin::root();
+				$penpal::execute_with(|| {
+					assert_ok!(<$penpal as [<$penpal Pallet>]>::PolkadotXcm::send(
+						sudo_penpal_origin.clone(),
+						bx!(ah_as_seen_by_penpal.into()),
+						bx!(xcm),
+					));
+					type RuntimeEvent = <$penpal as Chain>::RuntimeEvent;
+					assert_expected_events!(
+						$penpal,
+						vec![
+							RuntimeEvent::PolkadotXcm(pallet_xcm::Event::Sent { .. }) => {},
+						]
+					);
+				});
+				$asset_hub::execute_with(|| {
+					type ForeignAssets = <$asset_hub as [<$asset_hub Pallet>]>::ForeignAssets;
+					assert!(ForeignAssets::asset_exists(foreign_asset_at_asset_hub));
+				});
+			}
+		}
+	};
+}

cumulus/parachains/integration-tests/emulated/common/src/xcm_helpers.rs

@@ -59,3 +59,17 @@ pub fn xcm_transact_unpaid_execution(
 		Transact { require_weight_at_most, origin_kind, call },
 	]))
 }
+
+/// Helper method to get the non-fee asset used in multiple assets transfer
+pub fn non_fee_asset(assets: &MultiAssets, fee_idx: usize) -> Option<(MultiLocation, u128)> {
+	let asset = assets.inner().into_iter().enumerate().find(|a| a.0 != fee_idx)?.1.clone();
+	let asset_id = match asset.id {
+		Concrete(id) => id,
+		_ => return None,
+	};
+	let asset_amount = match asset.fun {
+		Fungible(amount) => amount,
+		_ => return None,
+	};
+	Some((asset_id, asset_amount))
+}