Skip to content
This repository has been archived by the owner on Nov 15, 2023. It is now read-only.

Commit

Permalink
Create a README for XCMv1 detailing notable changes (#4058)
Browse files Browse the repository at this point in the history 
* Create a README for XCMv1 detailing notable changes

* Update xcm/src/v1/README.md

Co-authored-by: Gavin Wood <gavin@parity.io>

* Update xcm/src/v1/README.md

Co-authored-by: David <dvdplm@gmail.com>

* Update xcm/src/v1/README.md

Co-authored-by: David <dvdplm@gmail.com>

* Update xcm/src/v1/README.md

Co-authored-by: David <dvdplm@gmail.com>

* Update xcm/src/v1/README.md

Co-authored-by: David <dvdplm@gmail.com>

* 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 <gavin@parity.io>
Co-authored-by: David <dvdplm@gmail.com>
  • Loading branch information
@KiChjang @gavofyork
@dvdplm @emostov
3 people authored and emostov committed Nov 1, 2021
1 parent 3b4818c commit fc6edde
Show file tree
Hide file tree
Showing 3 changed files with 71 additions and 1 deletion.
1 change: 1 addition & 0 deletions scripts/gitlab/lingua.dic
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ blockchain/MS
borked
broadcast/UDSMG
BTC/S
canonicalization
canonicalize/D
CentOS
CLI/MS
Expand Down
25 changes: 25 additions & 0 deletions xcm/src/v1/README.md
View file
Original file line number Diff line number Diff line change
@@ -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<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`.
46 changes: 45 additions & 1 deletion xcm/src/v1/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,51 @@
// You should have received a copy of the GNU General Public License
// along with Polkadot. If not, see <http://www.gnu.org/licenses/>.

//! 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<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`.

use super::{
v0::{Response as OldResponse, Xcm as OldXcm},
Expand Down

0 comments on commit fc6edde

Please sign in to comment.