polkadot-sdk [xcm-v5] implement RFC#100: add new InitiateTransfer instruction

A new instruction InitiateTransfer is introduced that initiates an assets transfer from the chain it is executed on, to another chain. The executed transfer is point-to-point (chain-to-chain) with all of the transfer properties specified in the instruction parameters. The instruction also allows specifying another XCM program to be executed on the remote chain. If a transfer requires going through multiple hops, an XCM program can compose this instruction to be used at every chain along the path, on each hop describing that specific leg of the transfer.

Note: Transferring assets that require different paths (chains along the way) is not supported within same XCM because of the async nature of cross chain messages. This new instruction, however, enables initiating transfers for multiple assets that take the same path even if they require different transfer types along that path.

The usage and composition model of InitiateTransfer is the same as with existing DepositReserveAsset, InitiateReserveWithdraw and InitiateTeleport instructions. The main difference comes from the ability to handle assets that have different point-to-point transfer type between A and B. The other benefit is that it also allows specifying remote fee payment and transparently appends the required remote fees logic to the remote XCM.

We can specify the desired transfer type for some asset(s) using:

/// Specify which type of asset transfer is required for a particular `(asset, dest)` combination.
pub enum AssetTransferFilter {
	/// teleport assets matching `AssetFilter` to `dest`
	Teleport(AssetFilter),
	/// reserve-transfer assets matching `AssetFilter` to `dest`, using the local chain as reserve
	ReserveDeposit(AssetFilter),
	/// reserve-transfer assets matching `AssetFilter` to `dest`, using `dest` as reserve
	ReserveWithdraw(AssetFilter),
}

This PR adds 1 new XCM instruction:

/// Cross-chain transfer matching `assets` in the holding register as follows:
///
/// Assets in the holding register are matched using the given list of `AssetTransferFilter`s,
/// they are then transferred based on their specified transfer type:
///
/// - teleport: burn local assets and append a `ReceiveTeleportedAsset` XCM instruction to
///   the XCM program to be sent onward to the `dest` location,
///
/// - reserve deposit: place assets under the ownership of `dest` within this consensus system
///   (i.e. its sovereign account), and append a `ReserveAssetDeposited` XCM instruction
///   to the XCM program to be sent onward to the `dest` location,
///
/// - reserve withdraw: burn local assets and append a `WithdrawAsset` XCM instruction
///   to the XCM program to be sent onward to the `dest` location,
///
/// The onward XCM is then appended a `ClearOrigin` to allow safe execution of any following
/// custom XCM instructions provided in `remote_xcm`.
///
/// The onward XCM also potentially contains a `BuyExecution` instruction based on the presence
/// of the `remote_fees` parameter (see below).
///
/// If a transfer requires going through multiple hops, an XCM program can compose this instruction
/// to be used at every chain along the path, describing that specific leg of the transfer.
///
/// Parameters:
/// - `dest`: The location of the transfer next hop.
/// - `remote_fees`: If set to `Some(asset_xfer_filter)`, the single asset matching
///   `asset_xfer_filter` in the holding register will be transferred first in the remote XCM
///   program, followed by a `BuyExecution(fee)`, then rest of transfers follow.
///   This guarantees `remote_xcm` will successfully pass a `AllowTopLevelPaidExecutionFrom` barrier.
/// - `remote_xcm`: Custom instructions that will be executed on the `dest` chain. Note that
///   these instructions will be executed after a `ClearOrigin` so their origin will be `None`.
///
/// Safety: No concerns.
///
/// Kind: *Command*.
///
InitiateTransfer {
	destination: Location,
	remote_fees: Option<AssetTransferFilter>,
	assets: Vec<AssetTransferFilter>,
	remote_xcm: Xcm<()>,
}

An InitiateTransfer { .. } instruction shall transfer to dest, all assets in the holding register that match the provided assets and remote_fees filters. These filters identify the assets to be transferred as well as the transfer type to be used for transferring them. It shall handle the local side of the transfer, then forward an onward XCM to dest for handling the remote side of the transfer.

It should do so using same mechanisms as existing DepositReserveAsset, InitiateReserveWithdraw, InitiateTeleport instructions but practically combining all required XCM instructions to be remotely executed into a single remote XCM program to be sent over to dest.

Furthermore, through remote_fees: Option<AssetTransferFilter>, it shall allow specifying a single asset to be used for fees on dest chain. This single asset shall be remotely handled/received by the first instruction in the onward XCM and shall be followed by a BuyExecution instruction using it. If remote_fees is set to None, the first instruction in the onward XCM shall be a UnpaidExecution instruction. The rest of the assets shall be handled by subsequent instructions, thus also finally allowing single asset buy execution barrier security recommendation.

The BuyExecution appended to the onward XCM specifies WeightLimit::Unlimited, thus being limited only by the remote_fees asset "amount". This is a deliberate decision for enhancing UX - in practice, people/dApps care about limiting the amount of fee asset used and not the actually used weight.

The onward XCM, following the assets transfers instructions, ClearOrigin or DescendOrigin instructions shall be appended to stop acting on behalf of the source chain, then the caller-provided remote_xcm shall also be appended, allowing the caller to control what to do with the transferred assets.

Closes https://github.com/paritytech/polkadot-sdk/issues/5209

Sep 30 '24 16:09 acatangiu

The CI pipeline was cancelled due to failure one of the required jobs. Job name: test-linux-stable 1/3 Logs: https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7468091

Sep 30 '24 16:09 paritytech-cicd-pr

bot fmt

Oct 21 '24 18:10 franciscoaguirre

@franciscoaguirre https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7613099 was started for your command "$PIPELINE_SCRIPTS_DIR/commands/fmt/fmt.sh". Check out https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/pipelines?page=1&scope=all&username=group_605_bot to know what else is being executed currently.

Comment bot cancel 4-44585eb2-73c0-4bf3-bae6-9b126e51e58e to cancel this command or bot cancel to cancel all commands in this pull request.

Oct 21 '24 18:10 command-bot[bot]

@franciscoaguirre Command "$PIPELINE_SCRIPTS_DIR/commands/fmt/fmt.sh" has finished. Result: https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7613099 has finished. If any artifacts were generated, you can download them from https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7613099/artifacts/download.

Oct 21 '24 18:10 command-bot[bot]

bot bench cumulus-assets --subcommand=xcm --runtime=asset-hub-westend --pallet=pallet_xcm_benchmarks::fungible

Oct 21 '24 18:10 franciscoaguirre

@franciscoaguirre https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7613164 was started for your command "$PIPELINE_SCRIPTS_DIR/commands/bench/bench.sh" --subcommand=xcm --runtime=asset-hub-westend --runtime_dir=assets --target_dir=cumulus --pallet=pallet_xcm_benchmarks::fungible. Check out https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/pipelines?page=1&scope=all&username=group_605_bot to know what else is being executed currently.

Comment bot cancel 5-86b96800-45d0-4fd4-9b24-2db1df23f354 to cancel this command or bot cancel to cancel all commands in this pull request.

Oct 21 '24 18:10 command-bot[bot]

@franciscoaguirre Command "$PIPELINE_SCRIPTS_DIR/commands/bench/bench.sh" --subcommand=xcm --runtime=asset-hub-westend --runtime_dir=assets --target_dir=cumulus --pallet=pallet_xcm_benchmarks::fungible has finished. Result: https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7613164 has finished. If any artifacts were generated, you can download them from https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7613164/artifacts/download.

Oct 21 '24 19:10 command-bot[bot]

bot bench polkadot-pallet --subcommand=xcm --runtime=westend --pallet=pallet_xcm_benchmarks::fungible bot bench polkadot-pallet --subcommand=xcm --runtime=rococo --pallet=pallet_xcm_benchmarks::fungible

bot bench cumulus-assets --subcommand=xcm --runtime=asset-hub-rococo --pallet=pallet_xcm_benchmarks::fungible

bot bench cumulus-coretime --subcommand=xcm --runtime=coretime-westend --pallet=pallet_xcm_benchmarks::fungible bot bench cumulus-coretime --subcommand=xcm --runtime=coretime-rococo --pallet=pallet_xcm_benchmarks::fungible

bot bench cumulus-bridge-hubs --subcommand=xcm --runtime=bridge-hub-rococo --pallet=pallet_xcm_benchmarks::fungible bot bench cumulus-bridge-hubs --subcommand=xcm --runtime=bridge-hub-westend --pallet=pallet_xcm_benchmarks::fungible

bot bench cumulus-people --subcommand=xcm --runtime=people-westend --pallet=pallet_xcm_benchmarks::fungible bot bench cumulus-people --subcommand=xcm --runtime=people-rococo --pallet=pallet_xcm_benchmarks::fungible

Oct 21 '24 21:10 franciscoaguirre

@franciscoaguirre https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/7614459 was started for your command "$PIPELINE_SCRIPTS_DIR/commands/bench/bench.sh" --subcommand=xcm --runtime=westend --target_dir=polkadot --pallet=pallet_xcm_benchmarks::fungible. Check out https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/pipelines?page=1&scope=all&username=group_605_bot to know what else is being executed currently.

Comment bot cancel 8-e7d694cc-6a14-4239-9240-44e35ed4a275 to cancel this command or bot cancel to cancel all commands in this pull request.