Create a README for XCMv2 detailing notable changes (#4059)

* Create a README for XCMv2 detailing notable changes

* Typo

* Appease spellcheck and cargo fmt

* Add XCM pallet item to be aware of

* cargo fmt

* Remove all XCM README.md

polkadot/xcm/src/v1/README.md

@@ -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<MultiAsset>` 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`.

polkadot/xcm/src/v2/mod.rs

@@ -14,7 +14,41 @@
 // You should have received a copy of the GNU General Public License
 // along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
 
-//! 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<Instruction>`.
+//! - 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`.
 
 use super::v1::{Order as OldOrder, Response as OldResponse, Xcm as OldXcm};
 use crate::{DoubleEncoded, GetWeight};