Struct cumulus_primitives_core::MultiLocation

pub struct MultiLocation {
    pub parents: u8,
    pub interior: Junctions,
}

Expand description

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 an integer number of parents specifying the number of times to “escape” upwards into the containing consensus system and then a number of junctions, each diving down and specifying some interior portion of state (which may be considered a “sub-consensus” system).

This specific MultiLocation implementation uses a Junctions datatype which is a Rust enum in order to make pattern matching easier. There are occasions where it is important to ensure that a value is strictly an interior location, in those cases, Junctions may be used.

The MultiLocation value of Null simply refers to the interpreting consensus system.

Fields§

§parents: u8

The number of parent junctions at the beginning of this MultiLocation.

§interior: Junctions

The interior (i.e. non-parent) junctions that this MultiLocation contains.

Implementations§

§

impl MultiLocation

pub fn new(parents: u8, interior: impl Into<Junctions>) -> MultiLocation

Creates a new MultiLocation with the given number of parents and interior junctions.

pub const fn into_versioned(self) -> VersionedMultiLocation

Consume self and return the equivalent VersionedMultiLocation value.

pub const fn here() -> MultiLocation

Creates a new MultiLocation with 0 parents and a Here interior.

The resulting MultiLocation can be interpreted as the “current consensus system”.

pub const fn parent() -> MultiLocation

Creates a new MultiLocation which evaluates to the parent context.

pub const fn grandparent() -> MultiLocation

Creates a new MultiLocation which evaluates to the grand parent context.

pub const fn ancestor(parents: u8) -> MultiLocation

Creates a new MultiLocation with parents and an empty (Here) interior.

pub const fn is_here(&self) -> bool

Whether the MultiLocation has no parents and has a Here interior.

pub fn remove_network_id(&mut self)

Remove the NetworkId value in any interior Junctions.

pub fn interior(&self) -> &Junctions

Return a reference to the interior field.

pub fn interior_mut(&mut self) -> &mut Junctions

Return a mutable reference to the interior field.

pub const fn parent_count(&self) -> u8

Returns the number of Parent junctions at the beginning of self.

pub const fn contains_parents_only(&self, count: u8) -> bool

Returns boolean indicating whether self contains only the specified amount of parents and no interior junctions.

pub const fn len(&self) -> usize

Returns the number of parents and junctions in self.

pub fn first_interior(&self) -> Option<&Junction>

Returns the first interior junction, or None if the location is empty or contains only parents.

pub fn last(&self) -> Option<&Junction>

Returns last junction, or None if the location is empty or contains only parents.

pub fn split_first_interior(self) -> (MultiLocation, Option<Junction>)

Splits off the first interior junction, returning the remaining suffix (first item in tuple) and the first element (second item in tuple) or None if it was empty.

pub fn split_last_interior(self) -> (MultiLocation, Option<Junction>)

Splits off the last interior junction, returning the remaining prefix (first item in tuple) and the last element (second item in tuple) or None if it was empty or if self only contains parents.

pub fn push_interior( &mut self, new: impl Into<Junction> ) -> Result<(), Junction>

Mutates self, suffixing its interior junctions with new. Returns Err with new in case of overflow.

pub fn push_front_interior( &mut self, new: impl Into<Junction> ) -> Result<(), Junction>

Mutates self, prefixing its interior junctions with new. Returns Err with new in case of overflow.

pub fn pushed_with_interior( self, new: impl Into<Junction> ) -> Result<MultiLocation, (MultiLocation, Junction)>

Consumes self and returns a MultiLocation suffixed with new, or an Err with theoriginal value of self in case of overflow.

pub fn pushed_front_with_interior( self, new: impl Into<Junction> ) -> Result<MultiLocation, (MultiLocation, Junction)>

Consumes self and returns a MultiLocation prefixed with new, or an Err with the original value of self in case of overflow.

pub fn at(&self, i: usize) -> Option<&Junction>

Returns the junction at index i, or None if the location is a parent or if the location does not contain that many elements.

pub fn at_mut(&mut self, i: usize) -> Option<&mut Junction>

Returns a mutable reference to the junction at index i, or None if the location is a parent or if it doesn’t contain that many elements.

pub fn dec_parent(&mut self)

Decrements the parent count by 1.

pub fn take_first_interior(&mut self) -> Option<Junction>

Removes the first interior junction from self, returning it (or None if it was empty or if self contains only parents).

pub fn take_last(&mut self) -> Option<Junction>

Removes the last element from interior, returning it (or None if it was empty or if self only contains parents).

pub fn match_and_split(&self, prefix: &MultiLocation) -> Option<&Junction>

Ensures that self has the same number of parents as prefix, its junctions begins with the junctions of prefix and that it has a single Junction item following. If so, returns a reference to this Junction item.

Example

let mut m = MultiLocation::new(1, X2(PalletInstance(3), OnlyChild));
assert_eq!(
    m.match_and_split(&MultiLocation::new(1, X1(PalletInstance(3)))),
    Some(&OnlyChild),
);
assert_eq!(m.match_and_split(&MultiLocation::new(1, Here)), None);

pub fn starts_with(&self, prefix: &MultiLocation) -> bool

pub fn append_with( &mut self, suffix: impl Into<MultiLocation> ) -> Result<(), MultiLocation>

Mutate self so that it is suffixed with suffix.

Does not modify self and returns Err with suffix in case of overflow.

Example

let mut m: MultiLocation = (Parent, Parachain(21), 69u64).into();
assert_eq!(m.append_with((Parent, PalletInstance(3))), Ok(()));
assert_eq!(m, MultiLocation::new(1, X2(Parachain(21), PalletInstance(3))));

pub fn appended_with( self, suffix: impl Into<MultiLocation> ) -> Result<MultiLocation, (MultiLocation, MultiLocation)>

Consume self and return its value suffixed with suffix.

Returns Err with the original value of self and suffix in case of overflow.

Example

let mut m: MultiLocation = (Parent, Parachain(21), 69u64).into();
let r = m.appended_with((Parent, PalletInstance(3))).unwrap();
assert_eq!(r, MultiLocation::new(1, X2(Parachain(21), PalletInstance(3))));

pub fn prepend_with( &mut self, prefix: impl Into<MultiLocation> ) -> Result<(), MultiLocation>

Mutate self so that it is prefixed with prefix.

Does not modify self and returns Err with prefix in case of overflow.

Example

let mut m: MultiLocation = (Parent, Parent, PalletInstance(3)).into();
assert_eq!(m.prepend_with((Parent, Parachain(21), OnlyChild)), Ok(()));
assert_eq!(m, MultiLocation::new(1, X1(PalletInstance(3))));

pub fn prepended_with( self, prefix: impl Into<MultiLocation> ) -> Result<MultiLocation, (MultiLocation, MultiLocation)>

Consume self and return its value prefixed with prefix.

Returns Err with the original value of self and prefix in case of overflow.

Example

let m: MultiLocation = (Parent, Parent, PalletInstance(3)).into();
let r = m.prepended_with((Parent, Parachain(21), OnlyChild)).unwrap();
assert_eq!(r, MultiLocation::new(1, X1(PalletInstance(3))));

pub fn reanchor( &mut self, target: &MultiLocation, context: Junctions ) -> Result<(), ()>

Mutate self so that it represents the same location from the point of view of target. The context of self is provided as context.

Does not modify self in case of overflow.

pub fn reanchored( self, target: &MultiLocation, context: Junctions ) -> Result<MultiLocation, MultiLocation>

Consume self and return a new value representing the same location from the point of view of target. The context of self is provided as context.

Returns the original self in case of overflow.

pub fn simplify(&mut self, context: &Junctions)

Remove any unneeded parents/junctions in self based on the given context it will be interpreted in.

Trait Implementations§

§

impl Clone for MultiLocation

§

fn clone(&self) -> MultiLocation

Returns a copy of the value. Read more

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

§

impl Debug for MultiLocation

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

§

impl Decode for MultiLocation

§

fn decode<CodecInputEdqy>( codec_input_edqy: &mut CodecInputEdqy ) -> Result<MultiLocation, Error>where CodecInputEdqy: Input,

Attempt to deserialise the value from input.

§

fn decode_into( input: &mut I, dst: &mut MaybeUninit<Self> ) -> Result<DecodeFinished, Error>where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory. Read more

§

fn skip(input: &mut I) -> Result<(), Error>where I: Input,

Attempt to skip the encoded value from input. Read more

§

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type. Read more

§

impl Default for MultiLocation

§

fn default() -> MultiLocation

Returns the “default value” for a type. Read more

§

impl<'de> Deserialize<'de> for MultiLocation

§

fn deserialize<D>( deserializer: D ) -> Result<MultiLocation, <D as Deserializer<'de>>::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more

§

impl Encode for MultiLocation

§

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding. Read more

§

fn encode_to<CodecOutputEdqy>( &self, codec_dest_edqy: &mut CodecOutputEdqy )where CodecOutputEdqy: Output + ?Sized,

Convert self to a slice and append it to the destination.

§

fn encode(&self) -> Vec<u8, Global> ⓘ

Convert self to an owned vector.

§

fn using_encoded<R, F>(&self, f: F) -> Rwhere F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

§

fn encoded_size(&self) -> usize

Calculates the encoded size. Read more

§