Unverified Commit ec55686c authored by Sergey Pepyakin's avatar Sergey Pepyakin Committed by GitHub
Browse files

Add the XCM primitives crate. (#1760)



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

Co-authored-by: default avatarGavin Wood <gavin@parity.io>
parent db64485f
Pipeline #108855 passed with stages
in 17 minutes and 26 seconds
......@@ -4340,9 +4340,9 @@ dependencies = [
[[package]]
name = "parity-scale-codec"
version = "1.3.4"
version = "1.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "34d38aeaffc032ec69faa476b3caaca8d4dd7f3f798137ff30359e5c7869ceb6"
checksum = "7c740e5fbcb6847058b40ac7e5574766c6388f585e184d769910fe0d3a2ca861"
dependencies = [
"arrayvec 0.5.1",
"bitvec",
......@@ -4353,9 +4353,9 @@ dependencies = [
[[package]]
name = "parity-scale-codec-derive"
version = "1.2.1"
version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd20ff7e0399b274a5f5bb37b712fccb5b3a64b9128200d1c3cc40fe709cb073"
checksum = "198db82bb1c18fc00176004462dd809b2a6d851669550aa17af6dacd21ae0c14"
dependencies = [
"proc-macro-crate",
"proc-macro2 1.0.18",
......@@ -10016,6 +10016,13 @@ dependencies = [
"zeroize",
]
[[package]]
name = "xcm"
version = "0.8.22"
dependencies = [
"parity-scale-codec",
]
[[package]]
name = "yamux"
version = "0.8.0"
......
......@@ -40,6 +40,7 @@ members = [
"statement-table",
"service",
"validation",
"xcm",
"node/collation-generation",
"node/core/av-store",
......
[package]
name = "xcm"
version = "0.8.22"
authors = ["Parity Technologies x<admin@parity.io>"]
description = "The basic XCM datastructures."
edition = "2018"
[dependencies]
codec = { package = "parity-scale-codec", version = "1.3.5", default-features = false, features = [ "derive" ] }
// Copyright 2020 Parity Technologies (UK) Ltd.
// This file is part of Polkadot.
// Substrate is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Substrate is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Polkadot. If not, see <http://www.gnu.org/licenses/>.
//! Cross-Consensus Message format data structures.
// NOTE, this crate is meant to be used in many different environments, notably wasm, but not
// necessarily related to FRAME or even Substrate.
//
// Hence, `no_std` rather than sp-runtime.
#![no_std]
extern crate alloc;
use codec::{Encode, Decode};
pub mod v0;
/// A single XCM message, together with its version code.
#[derive(Clone, Eq, PartialEq, Encode, Decode, Debug)]
pub enum VersionedXcm {
V0(v0::Xcm),
}
/// A versioned multi-location, a relative location of a cross-consensus system identifier.
#[derive(Clone, Eq, PartialEq, Encode, Decode, Debug)]
pub enum VersionedMultiLocation {
V0(v0::MultiLocation),
}
/// A versioned multi-asset, an identifier for an asset within a consensus system.
#[derive(Clone, Eq, PartialEq, Encode, Decode, Debug)]
pub enum VersionedMultiAsset {
V0(v0::MultiAsset),
}
// Copyright 2020 Parity Technologies (UK) Ltd.
// This file is part of Cumulus.
// Substrate is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Substrate is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Cumulus. If not, see <http://www.gnu.org/licenses/>.
//! Support datastructures for `MultiLocation`, primarily the `Junction` datatype.
use alloc::vec::Vec;
use codec::{self, Encode, Decode};
/// A global identifier of an account-bearing consensus system.
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, Debug)]
pub enum NetworkId {
/// Unidentified/any.
Any,
/// Some named network.
Named(Vec<u8>),
/// The Polkadot Relay chain
Polkadot,
/// Kusama.
Kusama,
}
/// A single item in a path to describe the relative location of a consensus system.
///
/// Each item assumes a pre-existing location as its context and is defined in terms of it.
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, Debug)]
pub enum Junction {
/// The consensus system of which the context is a member and state-wise super-set.
///
/// NOTE: This item is *not* a sub-consensus item: a consensus system may not identify itself trustlessly as
/// a location that includes this junction.
Parent,
/// An indexed parachain belonging to and operated by the context.
///
/// Generally used when the context is a Polkadot Relay-chain.
Parachain { #[codec(compact)] id: u32 },
/// A 32-byte identifier for an account of a specific network that is respected as a sovereign endpoint within
/// the context.
///
/// Generally used when the context is a Substrate-based chain.
AccountId32 { network: NetworkId, id: [u8; 32] },
/// An 8-byte index for an account of a specific network that is respected as a sovereign endpoint within
/// the context.
///
/// May be used when the context is a Frame-based chain and includes e.g. an indices pallet.
AccountIndex64 { network: NetworkId, #[codec(compact)] index: u64 },
/// A 20-byte identifier for an account of a specific network that is respected as a sovereign endpoint within
/// the context.
///
/// May be used when the context is an Ethereum or Bitcoin chain or smart-contract.
AccountKey20 { network: NetworkId, key: [u8; 20] },
/// An instanced, indexed pallet that forms a constituent part of the context.
///
/// Generally used when the context is a Frame-based chain.
PalletInstance { id: u8 },
/// A non-descript index within the context location.
///
/// Usage will vary widely owing to its generality.
///
/// NOTE: Try to avoid using this and instead use a more specific item.
GeneralIndex { #[codec(compact)] id: u128 },
/// A nondescript datum acting as a key within the context location.
///
/// Usage will vary widely owing to its generality.
///
/// NOTE: Try to avoid using this and instead use a more specific item.
GeneralKey(Vec<u8>),
/// The unambiguous child.
///
/// Not currently used except as a fallback when deriving ancestry.
OnlyChild,
}
impl Junction {
pub fn is_sub_consensus(&self) -> bool {
match self {
Junction::Parent => false,
Junction::Parachain { .. } |
Junction::AccountId32 { .. } |
Junction::AccountIndex64 { .. } |
Junction::AccountKey20 { .. } |
Junction::PalletInstance { .. } |
Junction::GeneralIndex { .. } |
Junction::GeneralKey(..) |
Junction::OnlyChild => true,
}
}
}
// Copyright 2020 Parity Technologies (UK) Ltd.
// This file is part of Cumulus.
// Substrate is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Substrate is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Cumulus. If not, see <http://www.gnu.org/licenses/>.
//! Version 0 of the Cross-Consensus Message format data structures.
use core::{result, convert::TryFrom};
use alloc::{boxed::Box, vec::Vec};
use codec::{self, Encode, Decode};
use super::{VersionedXcm, VersionedMultiAsset};
mod junction;
mod multi_asset;
mod multi_location;
mod order;
mod traits;
pub use junction::{Junction, NetworkId};
pub use multi_asset::{MultiAsset, AssetInstance};
pub use multi_location::MultiLocation;
pub use order::Order;
pub use traits::{Error, Result, SendXcm, ExecuteXcm};
// TODO: Efficient encodings for Vec<MultiAsset>, Vec<Order>, using initial byte values 128+ to encode the number of
// items in the vector.
/// Basically just the XCM (more general) version of `ParachainDispatchOrigin`.
#[derive(Copy, Clone, Eq, PartialEq, Encode, Decode, Debug)]
pub enum OriginKind {
/// Origin should just be the native origin for the sender. For Cumulus/Frame chains this is
/// the `Parachain` origin.
Native,
/// Origin should just be the standard account-based origin with the sovereign account of
/// the sender. For Cumulus/Frame chains, this is the `Signed` origin.
SovereignAccount,
/// Origin should be the super-user. For Cumulus/Frame chains, this is the `Root` origin.
/// This will not usually be an available option.
Superuser,
}
/// Cross-Consensus Message: A message from one consensus system to another.
///
/// Consensus systems that may send and receive messages include blockchains and smart contracts.
///
/// All messages are delivered from a known *origin*, expressed as a `MultiLocation`.
///
/// This is the inner XCM format and is version-sensitive. Messages are typically passed using the outer
/// XCM format, known as `VersionedXcm`.
#[derive(Clone, Eq, PartialEq, Encode, Decode, Debug)]
pub enum Xcm {
/// Withdraw asset(s) (`assets`) from the ownership of `origin` and place them into `holding`. Execute the
/// orders (`effects`).
///
/// - `assets`: The asset(s) to be withdrawn into holding.
/// - `effects`: The order(s) to execute on the holding account.
///
/// Kind: *Instruction*.
///
/// Errors:
WithdrawAsset { assets: Vec<MultiAsset>, effects: Vec<Order> },
/// Asset(s) (`assets`) have been received into the ownership of this system on the `origin` system.
///
/// Some orders are given (`effects`) which should be executed once the corresponding derivative assets have
/// been placed into `holding`.
///
/// - `assets`: The asset(s) that are minted into holding.
/// - `effects`: The order(s) to execute on the holding account.
///
/// Safety: `origin` must be trusted to have received and be storing `assets` such that they may later be
/// withdrawn should this system send a corresponding message.
///
/// Kind: *Trusted Indication*.
///
/// Errors:
ReserveAssetDeposit { assets: Vec<MultiAsset>, effects: Vec<Order> },
/// Asset(s) (`assets`) have been destroyed on the `origin` system and equivalent assets should be
/// created on this system.
///
/// Some orders are given (`effects`) which should be executed once the corresponding derivative assets have
/// been placed into `holding`.
///
/// - `assets`: The asset(s) that are minted into holding.
/// - `effects`: The order(s) to execute on the holding account.
///
/// Safety: `origin` must be trusted to have irrevocably destroyed the `assets` prior as a consequence of
/// sending this message.
///
/// Kind: *Trusted Indication*.
///
/// Errors:
TeleportAsset { assets: Vec<MultiAsset>, effects: Vec<Order> },
/// Indication of the contents of the holding account corresponding to the `QueryHolding` order of `query_id`.
///
/// - `query_id`: The identifier of the query that resulted in this message being sent.
/// - `assets`: The message content.
///
/// Safety: No concerns.
///
/// Kind: *Information*.
///
/// Errors:
Balances { #[codec(compact)] query_id: u64, assets: Vec<MultiAsset> },
/// Apply the encoded transaction `call`, whose dispatch-origin should be `origin` as expressed by the kind
/// of origin `origin_type`.
///
/// - `origin_type`: The means of expressing the message origin as a dispatch origin.
/// - `call`: The encoded transaction to be applied.
///
/// Safety: No concerns.
///
/// Kind: *Instruction*.
///
/// Errors:
Transact { origin_type: OriginKind, call: Vec<u8> },
/// Relay an inner message (`inner`) to a locally reachable destination ID `dest`.
///
/// The message sent to the destination will be wrapped into a `RelayedFrom` message, with the
/// `superorigin` being this location.
///
/// - `dest: MultiLocation`: The location of the to be relayed into. This may never contain `Parent`, and
/// it must be immediately reachable from the interpreting context.
/// - `inner: VersionedXcm`: The message to be wrapped and relayed.
///
/// Safety: No concerns.
///
/// Kind: *Instruction*.
///
/// Errors:
RelayTo { dest: MultiLocation, inner: Box<VersionedXcm> },
/// A message (`inner`) was sent to `origin` from `superorigin` with the intention of being relayed.
///
/// - `superorigin`: The location of the `inner` message origin, **relative to `origin`**.
/// - `inner`: The message sent by the super origin.
///
/// Safety: `superorigin` must express a sub-consensus only; it may *NEVER* contain a `Parent` junction.
///
/// Kind: *Trusted Indication*.
///
/// Errors:
RelayedFrom { superorigin: MultiLocation, inner: Box<VersionedXcm> },
}
impl From<Xcm> for VersionedXcm {
fn from(x: Xcm) -> Self {
VersionedXcm::V0(x)
}
}
impl TryFrom<VersionedXcm> for Xcm {
type Error = ();
fn try_from(x: VersionedXcm) -> result::Result<Self, ()> {
match x {
VersionedXcm::V0(x) => Ok(x),
}
}
}
// Copyright 2020 Parity Technologies (UK) Ltd.
// This file is part of Cumulus.
// Substrate is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Substrate is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Cumulus. If not, see <http://www.gnu.org/licenses/>.
//! Cross-Consensus Message format data structures.
use core::{result, convert::TryFrom};
use alloc::vec::Vec;
use codec::{self, Encode, Decode};
use super::{MultiLocation, VersionedMultiAsset};
/// A general identifier for an instance of a non-fungible asset class.
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, Debug)]
pub enum AssetInstance {
/// Undefined - used if the NFA class has only one instance.
Undefined,
/// A compact index. Technically this could be greater than u128, but this implementation supports only
/// values up to `2**128 - 1`.
Index { #[codec(compact)] id: u128 },
/// A 4-byte fixed-length datum.
Array4([u8; 4]),
/// An 8-byte fixed-length datum.
Array8([u8; 8]),
/// A 16-byte fixed-length datum.
Array16([u8; 16]),
/// A 32-byte fixed-length datum.
Array32([u8; 32]),
/// An arbitrary piece of data. Use only when necessary.
Blob(Vec<u8>),
}
/// A single general identifier for an asset.
///
/// Represents both fungible and non-fungible assets. May only be used to represent a single asset class.
///
/// Wildcards may or may not be allowed by the interpreting context.
///
/// Assets classes may be identified in one of two ways: either an abstract identifier or a concrete identifier.
/// Implementations may support only one of these. A single asset may be referenced from multiple asset identifiers,
/// though will tend to have only a single *preferred* identifier.
///
/// ### Abstract identifiers
///
/// Abstract identifiers are absolute identifiers that represent a notional asset which can exist within multiple
/// consensus systems. These tend to be simpler to deal with since their broad meaning is unchanged regardless stay
/// of the consensus system in which it is interpreted.
///
/// However, in the attempt to provide uniformity across consensus systems, they may conflate different instantiations
/// of some notional asset (e.g. the reserve asset and a local reserve-backed derivative of it) under the same name,
/// leading to confusion. It also implies that one notional asset is accounted for locally in only one way. This may
/// not be the case, e.g. where there are multiple bridge instances each providing a bridged "BTC" token yet none
/// being fungible between the others.
///
/// Since they are meant to be absolute and universal, a global registry is needed to ensure that name collisions
/// do not occur.
///
/// An abstract identifier is represented as a simple variable-size byte string. As of writing, no global registry
/// exists and no proposals have been put forth for asset labeling.
///
/// ### Concrete identifiers
///
/// Concrete identifiers are *relative identifiers* that specifically identify a single asset through its location in
/// a consensus system relative to the context interpreting. Use of a `MultiLocation` ensures that similar but non
/// fungible variants of the same underlying asset can be properly distinguished, and obviates the need for any kind
/// of central registry.
///
/// The limitation is that the asset identifier cannot be trivially copied between consensus
/// systems and must instead be "re-anchored" whenever being moved to a new consensus system, using the two systems'
/// relative paths.
///
/// Throughout XCM, messages are authored such that *when interpreted from the receiver's point of view* they will
/// have the desired meaning/effect. This means that relative paths should always by constructed to be read from the
/// point of view of the receiving system, *which may be have a completely different meaning in the authoring system*.
///
/// Concrete identifiers are the preferred way of identifying an asset since they are entirely unambiguous.
///
/// A concrete identifier is represented by a `MultiLocation`. If a system has an unambiguous primary asset (such as
/// Bitcoin with BTC or Ethereum with ETH), then it will conventionally be identified as the chain itself. Alternative
/// and more specific ways of referring to an asset within a system include:
///
/// - `<chain>/PalletInstance(<id>)` for a Frame chain with a single-asset pallet instance (such as an instance of the
/// Balances pallet).
/// - `<chain>/PalletInstance(<id>)/GeneralIndex(<index>)` for a Frame chain with an indexed multi-asset pallet
/// instance (such as an instance of the Assets pallet).
/// - `<chain>/AccountId32` for an ERC-20-style single-asset smart-contract on a Frame-based contracts chain.
/// - `<chain>/AccountKey20` for an ERC-20-style single-asset smart-contract on an Ethereum-like chain.
///
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, Debug)]
pub enum MultiAsset {
/// No assets. Rarely used.
None,
/// All assets. Typically used for the subset of assets to be used for an `Order`, and in that context means
/// "all assets currently in holding".
All,
/// All fungible assets. Typically used for the subset of assets to be used for an `Order`, and in that context
/// means "all fungible assets currently in holding".
AllFungible,
/// All non-fungible assets. Typically used for the subset of assets to be used for an `Order`, and in that
/// context means "all non-fungible assets currently in holding".
AllNonFungible,
/// All fungible assets of a given abstract asset `id`entifier.
AllAbstractFungible { id: Vec<u8> },
/// All non-fungible assets of a given abstract asset `class`.
AllAbstractNonFungible { class: Vec<u8> },
/// All fungible assets of a given concrete asset `id`entifier.
AllConcreteFungible { id: MultiLocation },
/// All non-fungible assets of a given concrete asset `class`.
AllConcreteNonFungible { class: MultiLocation },
/// Some specific `amount` of the fungible asset identified by an abstract `id`.
AbstractFungible { id: Vec<u8>, #[codec(compact)] amount: u128 },
/// Some specific `instance` of the non-fungible asset whose `class` is identified abstractly.
AbstractNonFungible { class: Vec<u8>, instance: AssetInstance },
/// Some specific `amount` of the fungible asset identified by an concrete `id`.
ConcreteFungible { id: MultiLocation, #[codec(compact)] amount: u128 },
/// Some specific `instance` of the non-fungible asset whose `class` is identified concretely.
ConcreteNonFungible { class: MultiLocation, instance: AssetInstance },
}
impl From<MultiAsset> for VersionedMultiAsset {
fn from(x: MultiAsset) -> Self {
VersionedMultiAsset::V0(x)
}
}
impl TryFrom<VersionedMultiAsset> for MultiAsset {
type Error = ();
fn try_from(x: VersionedMultiAsset) -> result::Result<Self, ()> {
match x {
VersionedMultiAsset::V0(x) => Ok(x),
}
}
}
// Copyright 2020 Parity Technologies (UK) Ltd.
// This file is part of Cumulus.
// Substrate is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Substrate is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Cumulus. If not, see <http://www.gnu.org/licenses/>.
//! Cross-Consensus Message format data structures.
use core::{result, mem, convert::TryFrom};
use codec::{self, Encode, Decode};
use super::Junction;
use crate::VersionedMultiLocation;
/// A relative path between state-bearing consensus systems.
///
/// A location in a consensus system is defined as an *isolatable state machine* held within global consensus. The
/// location in question need not have a sophisticated consensus algorithm of its own; a single account within
/// Ethereum, for example, could be considered a location.
///
/// A very-much non-exhaustive list of types of location include:
/// - A (normal, layer-1) block chain, e.g. the Bitcoin mainnet or a parachain.
/// - A layer-0 super-chain, e.g. the Polkadot Relay chain.
/// - A layer-2 smart contract, e.g. an ERC-20 on Ethereum.
/// - A logical functional component of a chain, e.g. a single instance of a pallet on a Frame-based Substrate chain.
/// - An account.
///
/// A `MultiLocation` is a *relative identifier*, meaning that it can only be used to define the relative path
/// between two locations, and cannot generally be used to refer to a location universally. It is comprised of a
/// number of *junctions*, each morphing the previous location, either diving down into one of its internal locations,
/// called a *sub-consensus*, or going up into its parent location. Correct `MultiLocation` values must have all
/// `Parent` junctions as a prefix to all *sub-consensus* junctions.
///
/// This specific `MultiLocation` implementation uses a Rust `enum` in order to make pattern matching easier.
///
/// The `MultiLocation` value of `Null` simply refers to the interpreting consensus system.
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Encode, Decode, Debug)]
pub enum MultiLocation {
/// The interpreting consensus system.
Null,
/// A relative path comprising one junction.
X1(Junction),
/// A relative path comprising two junctions.
X2(Junction, Junction),
/// A relative path comprising three junctions.
X3(Junction, Junction, Junction),
/// A relative path comprising four junctions.
X4(Junction, Junction, Junction, Junction),
}
impl From<Junction> for MultiLocation {
fn from(x: Junction) -> Self {
MultiLocation::X1(x)
}
}
impl From<()> for MultiLocation {
fn from(_: ()) -> Self {
MultiLocation::Null
}
}
impl From<(Junction,)> for MultiLocation {
fn from(x: (Junction,)) -> Self {
MultiLocation::X1(x.0)
}
}
impl From<(Junction, Junction)> for MultiLocation {
fn from(x: (Junction, Junction)) -> Self {
MultiLocation::X2(x.0, x.1)
}
}
impl From<(Junction, Junction, Junction)> for MultiLocation {
fn from(x: (Junction, Junction, Junction)) -> Self {
MultiLocation::X3(x.0, x.1, x.2)