Struct cumulus_primitives_core::opaque::Location

pub struct Location {
    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 Location 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 Location 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 Location value of Null simply refers to the interpreting consensus system.

Fields§

§parents: u8

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

§interior: Junctions

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

Implementations§

§

impl Location

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

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

pub const fn into_versioned(self) -> VersionedLocation

Consume self and return the equivalent VersionedLocation value.

pub const fn here() -> Location

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

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

pub const fn parent() -> Location

Creates a new Location which evaluates to the parent context.

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

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

pub fn is_here(&self) -> bool

Whether the Location 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 fn unpack(&self) -> (u8, &[Junction])

Returns the parent count and the interior Junctions as a tuple.

To be used when pattern matching, for example:

fn get_parachain_id(loc: &Location) -> Option<u32> {
    match loc.unpack() {
        (0, [Parachain(id)]) => Some(*id),
        _ => None
    }
}

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 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) -> (Location, 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) -> (Location, 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<Location, (Location, Junction)>

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

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

Consumes self and returns a Location 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: &Location) -> 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 = Location::new(1, [PalletInstance(3), OnlyChild]);
assert_eq!(
    m.match_and_split(&Location::new(1, [PalletInstance(3)])),
    Some(&OnlyChild),
);
assert_eq!(m.match_and_split(&Location::new(1, Here)), None);

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

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

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: Location = (Parent, Parachain(21), 69u64).into();
assert_eq!(m.append_with((Parent, PalletInstance(3))), Ok(()));
assert_eq!(m, Location::new(1, [Parachain(21), PalletInstance(3)]));

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

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: Location = (Parent, Parachain(21), 69u64).into();
let r = m.appended_with((Parent, PalletInstance(3))).unwrap();
assert_eq!(r, Location::new(1, [Parachain(21), PalletInstance(3)]));

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

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: Location = (Parent, Parent, PalletInstance(3)).into();
assert_eq!(m.prepend_with((Parent, Parachain(21), OnlyChild)), Ok(()));
assert_eq!(m, Location::new(1, [PalletInstance(3)]));

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

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: Location = (Parent, Parent, PalletInstance(3)).into();
let r = m.prepended_with((Parent, Parachain(21), OnlyChild)).unwrap();
assert_eq!(r, Location::new(1, [PalletInstance(3)]));

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

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

pub fn chain_location(&self) -> Location

Return the Location subsection identifying the chain that self points to.

Trait Implementations§

§

impl Clone for Location

§

fn clone(&self) -> Location

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 Location

§

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

Formats the value using the given formatter. Read more

§

impl Decode for Location

§

fn decode<CodecInputEdqy>( codec_input_edqy: &mut CodecInputEdqy, ) -> Result<Location, 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 Location

§

fn default() -> Location

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

§

impl<'de> Deserialize<'de> for Location

§

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

Deserialize this value from the given Serde deserializer. Read more

§

impl Encode for Location

§

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> ⓘ

Convert self to an owned vector.

§

fn using_encoded<R, F>(&self, f: F) -> R
where 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

§