From f9427aa49f1696a14809e14e67bb74eac483c7fa Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Mon, 11 Oct 2021 23:59:27 -0700 Subject: [PATCH 01/10] Create a README for XCMv1 detailing notable changes --- xcm/src/v1/README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 xcm/src/v1/README.md diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md new file mode 100644 index 000000000000..9e40d3d98b17 --- /dev/null +++ b/xcm/src/v1/README.md @@ -0,0 +1,24 @@ +# XCM Version 1 + +## 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 1 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 be converted 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 is defaulted to 1. +- v1 Orders that contain `MultiAsset` as argument(s) will need to explicitly specify the amount and dtails of assets. This is to prevent accidental misuse of `All` to possibly transfer, spend or otherwise perform unintended operations on `All` assets. +- For v1 Orders that do allow the notion of `All` to be used as wildcards, they will instead use a new type called `MultiAssetFilter`. From c0eb9220d6ed94e56efe9a95cd1e9ab00de18d27 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:28:39 -0700 Subject: [PATCH 02/10] Update xcm/src/v1/README.md Co-authored-by: Gavin Wood --- xcm/src/v1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index 9e40d3d98b17..e5e3002491f4 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -20,5 +20,5 @@ Most changes should automatically be resolved via the conversion traits (i.e. `T ### 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 is defaulted to 1. -- v1 Orders that contain `MultiAsset` as argument(s) will need to explicitly specify the amount and dtails 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 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. - For v1 Orders that do allow the notion of `All` to be used as wildcards, they will instead use a new type called `MultiAssetFilter`. From 3f46cafcc46b202937697b23b9889bd19cb0e5fe Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:28:46 -0700 Subject: [PATCH 03/10] Update xcm/src/v1/README.md Co-authored-by: David --- xcm/src/v1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index e5e3002491f4..1c4cdc9426ee 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -10,7 +10,7 @@ Most changes should automatically be resolved via the conversion traits (i.e. `T - 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 1 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`). +- 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 be converted 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. From 1d66a75c9bacac924d4a034349b6c9aa6f38e0cc Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:29:12 -0700 Subject: [PATCH 04/10] Update xcm/src/v1/README.md Co-authored-by: David --- xcm/src/v1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index 1c4cdc9426ee..e0b42091949c 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -19,6 +19,6 @@ Most changes should automatically be resolved via the conversion traits (i.e. `T - 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 is defaulted to 1. +- `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. - For v1 Orders that do allow the notion of `All` to be used as wildcards, they will instead use a new type called `MultiAssetFilter`. From 99898027a7b7a6a3ede7732244c2660b665321b4 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:31:14 -0700 Subject: [PATCH 05/10] Update xcm/src/v1/README.md Co-authored-by: David --- xcm/src/v1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index e0b42091949c..2802c32ba936 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -11,7 +11,7 @@ Most changes should automatically be resolved via the conversion traits (i.e. `T ### 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 be converted to v1 MultiAsset, since v1 does not contain these variants. +- 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. From c9839e724e45ca56fa588addce5821d1506f8b5a Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:31:20 -0700 Subject: [PATCH 06/10] Update xcm/src/v1/README.md Co-authored-by: David --- xcm/src/v1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index 2802c32ba936..410ab54b69c1 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -21,4 +21,4 @@ Most changes should automatically be resolved via the conversion traits (i.e. `T ### 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. -- For v1 Orders that do allow the notion of `All` to be used as wildcards, they will instead use a new type called `MultiAssetFilter`. +- v1 Orders that do allow the notion of `All` to be used as wildcards, will instead use a new type called `MultiAssetFilter`. From 08cc892dafde7df7a85a8f1a3075911ac273f2b4 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:34:28 -0700 Subject: [PATCH 07/10] Link to relevant PR for a full list of changes --- xcm/src/v1/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index 410ab54b69c1..bdd6a809dd76 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -1,4 +1,5 @@ # 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. From 968cd455933a8408efb3ad26ba87cc5d10fd2396 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:35:11 -0700 Subject: [PATCH 08/10] Typo --- xcm/src/v1/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xcm/src/v1/README.md b/xcm/src/v1/README.md index bdd6a809dd76..2985125b11a4 100644 --- a/xcm/src/v1/README.md +++ b/xcm/src/v1/README.md @@ -1,5 +1,5 @@ # XCM Version 1 -The comprehensive list of changes can be found in (this PR description)[https://github.com/paritytech/polkadot/pull/2815#issue-608567900]. +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. From 8c0e62c06e9836b7f84875346a0a0813ba2d73bf Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 00:48:29 -0700 Subject: [PATCH 09/10] Add notable changes to top-level XCM rustdoc --- xcm/src/v1/mod.rs | 46 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/xcm/src/v1/mod.rs b/xcm/src/v1/mod.rs index 6f96dc739491..13bf71f84efa 100644 --- a/xcm/src/v1/mod.rs +++ b/xcm/src/v1/mod.rs @@ -14,7 +14,51 @@ // You should have received a copy of the GNU General Public License // along with Polkadot. If not, see . -//! Version 1 of the Cross-Consensus Message format data structures. +//! # XCM Version 1 +//! Version 1 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/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`. use super::{ v0::{Response as OldResponse, Xcm as OldXcm}, From 8c82ca32d7ebe682f209e73ccae792c9e2d4f6eb Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Tue, 12 Oct 2021 01:00:23 -0700 Subject: [PATCH 10/10] Appease spellchecker --- scripts/gitlab/lingua.dic | 1 + xcm/src/v1/mod.rs | 14 +++++++------- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/scripts/gitlab/lingua.dic b/scripts/gitlab/lingua.dic index 7c50d1fbc666..24f642591f51 100644 --- a/scripts/gitlab/lingua.dic +++ b/scripts/gitlab/lingua.dic @@ -27,6 +27,7 @@ blockchain/MS borked broadcast/UDSMG BTC/S +canonicalization canonicalize/D CentOS CLI/MS diff --git a/xcm/src/v1/mod.rs b/xcm/src/v1/mod.rs index 13bf71f84efa..87c016432018 100644 --- a/xcm/src/v1/mod.rs +++ b/xcm/src/v1/mod.rs @@ -26,15 +26,15 @@ //! //! ### 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. +//! has changed - instead of being a property of the junction, v1 `MultiLocation`s 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 +//! ### `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. +//! we do not expect v0 `MultiLocation` to ever fail to be upgraded to v1. //! -//! ### MultiAsset +//! ### `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`). @@ -42,7 +42,7 @@ //! `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. +//! 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.