frame_suite::xp

Trait XpSystem

Source 
pub trait XpSystem {
    type Xp: Delimited;
    type Points: Asset;
    type XpKey: Keyed;
    type TimeStamp: Time;
    type Extension: XpSystemExtensions<Via = Self>;

    // Required methods
    fn xp_exists(key: &Self::XpKey) -> DispatchResult;
    fn has_minimum_xp(key: &Self::XpKey) -> DispatchResult;
    fn get_xp(key: &Self::XpKey) -> Result<Self::Xp, DispatchError>;
    fn get_liquid_xp(key: &Self::XpKey) -> Result<Self::Points, DispatchError>;
    fn get_usable_xp(key: &Self::XpKey) -> Result<Self::Points, DispatchError>;
}
Expand description

Core trait for querying XP state and metadata.

This trait defines the foundational interface for accessing XP data in a read-only manner. It does not provide mutation logic.

If this is the only trait implemented, then it is assumed that the implementer manually provides an XP state, for which the runtime only supports querying.

Required Associated Types§

Source

type Xp: Delimited

Represents the full XP structure, which may include metadata or flags.

Typically modeled as a struct when supporting features like locking or reserving, enabling high-level state queries.

For simpler implementations, it can be aliased to XpSystem::Points if only a scalar value is needed.

Source

type Points: Asset

Scalar unsigned value representing the numerical XP points.

Source

type XpKey: Keyed

A unique key identifying each XP entry, distinct from the owner.

Allows a single owner to hold multiple XP records. This can be a hash, UUID, or runtime-specific ID.

For 1:1 mappings, XpKey may be aliased to XpOwner::Owner, allowing owner-specific fields to be omitted.

Source

type TimeStamp: Time

Represents the lifecycle or context dependent timestamps for an XP entry.

Source

type Extension: XpSystemExtensions<Via = Self>

An optional extension for external triggers to react, extend, modify XP implementations

If implementor chooses to avoid extensions, no op Ignore<Self> can be used

ⓘ
type Extension = Ignore<Self>;

Required Methods§

Source

fn xp_exists(key: &Self::XpKey) -> DispatchResult

Checks if an XP entry exists for the given key.

This is the standard guard function for XP querying logic and serves as a prerequisite check before calling any methods that assume a given XP key exists in storage.

§Returns
  • Ok(()) if the XP entry exists for the given key.
  • Err(DispatchError) if the XP entry does not exist.
Source

fn has_minimum_xp(key: &Self::XpKey) -> DispatchResult

Validates if the XP entry meets the minimum domain-defined threshold.

Often used for XP reaping and lifecycle management to determine entry validity. This check is not limited to a numeric value, but may include custom conditions that determine whether an XP entry remains valid within the system.

§Returns
  • Ok(()) if the XP entry meets the minimum threshold requirements.
  • Err(DispatchError) if the XP entry falls below the minimum threshold.
Source

fn get_xp(key: &Self::XpKey) -> Result<Self::Xp, DispatchError>

Retrieves the complete XP structure associated with the key.

Returns the full XP data including any metadata, flags, or extended information beyond just the point value for comprehensive XP state inspection.

§Returns
  • Ok(Xp) containing the complete XP structure if the key exists.
  • Err(DispatchError) if the XP key does not exist.
Source

fn get_liquid_xp(key: &Self::XpKey) -> Result<Self::Points, DispatchError>

Retrieves the liquid (free or accessible) XP for the given key.

This excludes XP currently locked or reserved, and represents what is immediately usable.

§Returns
  • Ok(Points) containing the liquid XP amount if the key exists.
  • Err(DispatchError) if the XP key does not exist.
Source

fn get_usable_xp(key: &Self::XpKey) -> Result<Self::Points, DispatchError>

Retrieves the total usable XP for the given key.

This is the sum of liquid XP and XP held in reserves, representing the complete pool of XP that could potentially be accessed or utilized by the key owner.

It is functionally the same as XpSystem::get_liquid_xp if there is no reserve implementation.

§Returns
  • Ok(Points) containing the total usable XP amount if the key exists.
  • Err(DispatchError) if the XP key does not exist.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§