Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[xcm-v5] implement RFC#100: add new InitiateTransfer instruction (#5876)
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:
```rust
/// 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:
```rust
/// 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](#2423)
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 #5209
---------
Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com>
Co-authored-by: command-bot <>- Loading branch information
1 parent
4a6e85c
commit 8fe7700