From 63d405527b63897a679fae584e536f9b22b37400 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 01:43:01 -0700 Subject: [PATCH 1/6] Create a README for XCMv2 detailing notable changes --- xcm/src/v2/README.md | 21 +++++++++++++++++++++ xcm/src/v2/mod.rs | 32 +++++++++++++++++++++++++++++++- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 xcm/src/v2/README.md diff --git a/xcm/src/v2/README.md b/xcm/src/v2/README.md new file mode 100644 index 000000000000..4330a4cc2dba --- /dev/null +++ b/xcm/src/v2/README.md @@ -0,0 +1,21 @@ +# XCM Version 2 +The comprehensive list of changes can be found in [this PR description](https://github.com/paritytech/polkadot/pull/3629#issue-968428279). + +## Changes to be aware of +The biggest change here is the restructuring of XCM messages: instead of having `Order` and `Xcm` types, the `Xcm` type now simply wraps a `Vec` containing `Instruction`s. However, most changes should still be automatically convertible via the `try_from` and `from` conversion functions. + +### Junction +- No special attention necessary + +### MultiLocation +- No special attention necessary + +### MultiAsset +- No special attention necessary + +### XCM and Order +- `Xcm` and `Order` variants are now combined under a single `Instruction` enum. +- `Order` is now obsolete and replaced entirely by `Instruction`. +- `Xcm` is now a simple wrapper around a `Vec`. +- During conversion from `Order` to `Instruction`, we do not handle `BuyExecution`s that have nested XCMs, i.e. if the `instructions` field in the `BuyExecution` enum struct variant is not empty, then the conversion will fail. To address this, rewrite the XCM using `Instruction`s in chronological order. +- During conversion from `Xcm` to `Instruction`, we do not handle `RelayedFrom` messages at all. diff --git a/xcm/src/v2/mod.rs b/xcm/src/v2/mod.rs index 60bec66ed963..0e1f6d2099db 100644 --- a/xcm/src/v2/mod.rs +++ b/xcm/src/v2/mod.rs @@ -14,7 +14,37 @@ // You should have received a copy of the GNU General Public License // along with Cumulus. If not, see . -//! Version 1 of the Cross-Consensus Message format data structures. + +//! # XCM Version 2 +//! Version 2 of the Cross-Consensus Message format data structures. The comprehensive list of +// !changes can be found in +//! [this PR description](https://github.com/paritytech/polkadot/pull/3629#issue-968428279). +//! +//! ## Changes to be aware of +//! The biggest change here is the restructuring of XCM messages: instead of having `Order` and +//! `Xcm` types, the `Xcm` type now simply wraps a `Vec` containing `Instruction`s. However, most +//! changes should still be automatically convertible via the `try_from` and `from` conversion +//! functions. +//! +//! ### Junction +//! - No special attention necessary +//! +//! ### MultiLocation +//! - No special attention necessary +//! +//! ### MultiAsset +//! - No special attention necessary +//! +//! ### XCM and Order +//! - `Xcm` and `Order` variants are now combined under a single `Instruction` enum. +//! - `Order` is now obsolete and replaced entirely by `Instruction`. +//! - `Xcm` is now a simple wrapper around a `Vec`. +//! - During conversion from `Order` to `Instruction`, we do not handle `BuyExecution`s that have +//! nested XCMs, i.e. if the `instructions` field in the `BuyExecution` enum struct variant is +//! not empty, then the conversion will fail. To address this, rewrite the XCM using +//! `Instruction`s in chronological order. +//! - During conversion from `Xcm` to `Instruction`, we do not handle `RelayedFrom` messages at +//! all. use super::v1::{Order as OldOrder, Response as OldResponse, Xcm as OldXcm}; use crate::{DoubleEncoded, GetWeight}; From 7fb5ec582f5c6a1991f12ab368eca80f5a5a7cec Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 01:45:52 -0700 Subject: [PATCH 2/6] Typo --- xcm/src/v2/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v2/mod.rs b/xcm/src/v2/mod.rs index 0e1f6d2099db..2b6a90c2afd1 100644 --- a/xcm/src/v2/mod.rs +++ b/xcm/src/v2/mod.rs @@ -17,7 +17,7 @@ //! # XCM Version 2 //! Version 2 of the Cross-Consensus Message format data structures. The comprehensive list of -// !changes can be found in +//! changes can be found in //! [this PR description](https://github.com/paritytech/polkadot/pull/3629#issue-968428279). //! //! ## Changes to be aware of From aa7f1e6688b9550e20c7b8411dacc5ac147ba8ac Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 02:03:59 -0700 Subject: [PATCH 3/6] Appease spellcheck and cargo fmt --- xcm/src/v2/mod.rs | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/xcm/src/v2/mod.rs b/xcm/src/v2/mod.rs index 2b6a90c2afd1..ae7cfddf843d 100644 --- a/xcm/src/v2/mod.rs +++ b/xcm/src/v2/mod.rs @@ -14,27 +14,26 @@ // You should have received a copy of the GNU General Public License // along with Cumulus. If not, see . - //! # XCM Version 2 //! Version 2 of the Cross-Consensus Message format data structures. The comprehensive list of //! changes can be found in //! [this PR description](https://github.com/paritytech/polkadot/pull/3629#issue-968428279). -//! +//! //! ## Changes to be aware of //! The biggest change here is the restructuring of XCM messages: instead of having `Order` and //! `Xcm` types, the `Xcm` type now simply wraps a `Vec` containing `Instruction`s. However, most //! changes should still be automatically convertible via the `try_from` and `from` conversion //! functions. -//! +//! //! ### Junction //! - No special attention necessary -//! -//! ### MultiLocation +//! +//! ### `MultiLocation` //! - No special attention necessary -//! -//! ### MultiAsset +//! +//! ### `MultiAsset` //! - No special attention necessary -//! +//! //! ### XCM and Order //! - `Xcm` and `Order` variants are now combined under a single `Instruction` enum. //! - `Order` is now obsolete and replaced entirely by `Instruction`. From 5934e8f0f396781d7302b84a51f7c0e09407d2ad Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 04:24:10 -0700 Subject: [PATCH 4/6] Add XCM pallet item to be aware of --- xcm/src/v2/README.md | 3 +++ xcm/src/v2/mod.rs | 5 +++++ 2 files changed, 8 insertions(+) diff --git a/xcm/src/v2/README.md b/xcm/src/v2/README.md index 4330a4cc2dba..7c87b7eb9516 100644 --- a/xcm/src/v2/README.md +++ b/xcm/src/v2/README.md @@ -19,3 +19,6 @@ The biggest change here is the restructuring of XCM messages: instead of having - `Xcm` is now a simple wrapper around a `Vec`. - During conversion from `Order` to `Instruction`, we do not handle `BuyExecution`s that have nested XCMs, i.e. if the `instructions` field in the `BuyExecution` enum struct variant is not empty, then the conversion will fail. To address this, rewrite the XCM using `Instruction`s in chronological order. - During conversion from `Xcm` to `Instruction`, we do not handle `RelayedFrom` messages at all. + +### XCM Pallet +- The `Weigher` configuration item must have sensible weights defined for `BuyExecution` and `DepositAsset` instructions. Failing that, dispatch calls to `teleport_assets` and `reserve_transfer_assets` will fail with `UnweighableMessage`. diff --git a/xcm/src/v2/mod.rs b/xcm/src/v2/mod.rs index ae7cfddf843d..a34df762e4b8 100644 --- a/xcm/src/v2/mod.rs +++ b/xcm/src/v2/mod.rs @@ -44,6 +44,11 @@ //! `Instruction`s in chronological order. //! - During conversion from `Xcm` to `Instruction`, we do not handle `RelayedFrom` messages at //! all. +//! +//! ### XCM Pallet +//! - The `Weigher` configuration item must have sensible weights defined for `BuyExecution` and +//! `DepositAsset` instructions. Failing that, dispatch calls to `teleport_assets` and +//! `reserve_transfer_assets` will fail with `UnweighableMessage`. use super::v1::{Order as OldOrder, Response as OldResponse, Xcm as OldXcm}; use crate::{DoubleEncoded, GetWeight}; From ff31332461ef5a7e0a6ead438623bb0679b9e888 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 21:12:26 -0700 Subject: [PATCH 5/6] cargo fmt --- xcm/src/v2/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v2/mod.rs b/xcm/src/v2/mod.rs index a34df762e4b8..444a6ae86811 100644 --- a/xcm/src/v2/mod.rs +++ b/xcm/src/v2/mod.rs @@ -44,7 +44,7 @@ //! `Instruction`s in chronological order. //! - During conversion from `Xcm` to `Instruction`, we do not handle `RelayedFrom` messages at //! all. -//! +//! //! ### XCM Pallet //! - The `Weigher` configuration item must have sensible weights defined for `BuyExecution` and //! `DepositAsset` instructions. Failing that, dispatch calls to `teleport_assets` and From 04e5ac4d7c5a53f55a2e39dbf8e2f4501efcb56b Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Fri, 22 Oct 2021 08:00:47 -0700 Subject: [PATCH 6/6] Remove all XCM README.md --- xcm/src/v1/README.md | 25 ------------------------- xcm/src/v2/README.md | 24 ------------------------ 2 files changed, 49 deletions(-) delete mode 100644 xcm/src/v1/README.md delete mode 100644 xcm/src/v2/README.md diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md deleted file mode 100644 index 2985125b11a4..000000000000 --- a/xcm/src/v1/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# XCM Version 1 -The comprehensive list of changes can be found in [this PR description](https://github.com/paritytech/polkadot/pull/2815#issue-608567900). - -## Changes to be aware of -Most changes should automatically be resolved via the conversion traits (i.e. `TryFrom` and `From`). The list here is mostly for incompatible changes that result in an `Err(())` when attempting to convert XCM objects from v0. - -### Junction -- `v0::Junction::Parent` cannot be converted to v1, because the way we represent parents in v1 has changed - instead of being a property of the junction, v1 MultiLocations now have an extra field representing the number of parents that the MultiLocation contains. - -### MultiLocation -- The `try_from` conversion method will always canonicalize the v0 MultiLocation before attempting to do the proper conversion. Since canonicalization is not a fallible operation, we do not expect v0 MultiLocation to ever fail to be upgraded to v1. - -### MultiAsset -- Stronger typing to differentiate between a single class of `MultiAsset` and several classes of `MultiAssets` is introduced. As the name suggests, a `Vec` that is used on all APIs will instead be using a new type called `MultiAssets` (note the `s`). -- All `MultiAsset` variants whose name contains "All" in it, namely `v0::MultiAsset::All`, `v0::MultiAsset::AllFungible`, `v0::MultiAsset::AllNonFungible`, `v0::MultiAsset::AllAbstractFungible`, `v0::MultiAsset::AllAbstractNonFungible`, `v0::MultiAsset::AllConcreteFungible` and `v0::MultiAsset::AllConcreteNonFungible`, will fail to convert to v1 MultiAsset, since v1 does not contain these variants. -- Similarly, all `MultiAsset` variants whose name contains "All" in it can be converted into a `WildMultiAsset`. -- `v0::MultiAsset::None` is not represented at all in v1. - -### XCM -- No special attention necessary - -### Order -- `v1::Order::DepositAsset` and `v1::Order::DepositReserveAsset` both introduced a new `max_asset` field that limits the maximum classes of assets that can be deposited. During conversion from v0, the `max_asset` field defaults to 1. -- v1 Orders that contain `MultiAsset` as argument(s) will need to explicitly specify the amount and details of assets. This is to prevent accidental misuse of `All` to possibly transfer, spend or otherwise perform unintended operations on `All` assets. -- v1 Orders that do allow the notion of `All` to be used as wildcards, will instead use a new type called `MultiAssetFilter`. diff --git a/xcm/src/v2/README.md b/xcm/src/v2/README.md deleted file mode 100644 index 7c87b7eb9516..000000000000 --- a/xcm/src/v2/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# XCM Version 2 -The comprehensive list of changes can be found in [this PR description](https://github.com/paritytech/polkadot/pull/3629#issue-968428279). - -## Changes to be aware of -The biggest change here is the restructuring of XCM messages: instead of having `Order` and `Xcm` types, the `Xcm` type now simply wraps a `Vec` containing `Instruction`s. However, most changes should still be automatically convertible via the `try_from` and `from` conversion functions. - -### Junction -- No special attention necessary - -### MultiLocation -- No special attention necessary - -### MultiAsset -- No special attention necessary - -### XCM and Order -- `Xcm` and `Order` variants are now combined under a single `Instruction` enum. -- `Order` is now obsolete and replaced entirely by `Instruction`. -- `Xcm` is now a simple wrapper around a `Vec`. -- During conversion from `Order` to `Instruction`, we do not handle `BuyExecution`s that have nested XCMs, i.e. if the `instructions` field in the `BuyExecution` enum struct variant is not empty, then the conversion will fail. To address this, rewrite the XCM using `Instruction`s in chronological order. -- During conversion from `Xcm` to `Instruction`, we do not handle `RelayedFrom` messages at all. - -### XCM Pallet -- The `Weigher` configuration item must have sensible weights defined for `BuyExecution` and `DepositAsset` instructions. Failing that, dispatch calls to `teleport_assets` and `reserve_transfer_assets` will fail with `UnweighableMessage`.