From fc6edde65076ccc38cc052a58bb0f5a029b08cf8 Mon Sep 17 00:00:00 2001 From: Keith Yeung Date: Wed, 13 Oct 2021 04:17:30 -0700 Subject: [PATCH] Create a README for XCMv1 detailing notable changes (#4058) * Create a README for XCMv1 detailing notable changes * Update xcm/src/v1/README.md Co-authored-by: Gavin Wood * Update xcm/src/v1/README.md Co-authored-by: David * Update xcm/src/v1/README.md Co-authored-by: David * Update xcm/src/v1/README.md Co-authored-by: David * Update xcm/src/v1/README.md Co-authored-by: David * Link to relevant PR for a full list of changes * Typo * Add notable changes to top-level XCM rustdoc * Appease spellchecker Co-authored-by: Gavin Wood Co-authored-by: David --- scripts/gitlab/lingua.dic | 1 + xcm/src/v1/README.md | 25 +++++++++++++++++++++ xcm/src/v1/mod.rs | 46 ++++++++++++++++++++++++++++++++++++++- 3 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 xcm/src/v1/README.md 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/README.md b/xcm/src/v1/README.md new file mode 100644 index 000000000000..2985125b11a4 --- /dev/null +++ b/xcm/src/v1/README.md @@ -0,0 +1,25 @@ +# 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/v1/mod.rs b/xcm/src/v1/mod.rs index 6f96dc739491..87c016432018 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 `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 +//! 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},