Trait XpMutate

pub trait XpMutate
where
    Self: XpOwner + XpErrorHandler + XpSystem<Extension: XpMutateListener + XpSystemExtensions<Via = Self>>,
{
    // Required methods
    fn init_xp() -> Self::Points;
    fn new_xp(owner: &Self::Owner, key: &Self::XpKey);
    fn set_xp(key: &Self::XpKey, points: Self::Points) -> DispatchResult;
    fn quote_earn_xp(
        key: &Self::XpKey,
        points: Self::Points,
    ) -> Result<Self::Points, DispatchError>;

    // Provided methods
    fn create_xp(owner: &Self::Owner, key: &Self::XpKey) -> DispatchResult { ... }
    fn earn_xp(
        key: &Self::XpKey,
        points: Self::Points,
    ) -> Result<Self::Points, DispatchError> { ... }
    fn slash_xp(
        key: &Self::XpKey,
        points: Self::Points,
    ) -> Result<Self::Points, DispatchError> { ... }
    fn reset_xp(key: &Self::XpKey) -> Result<Self::Points, DispatchError> { ... }
    fn on_xp_create(key: &Self::XpKey, owner: &Self::Owner) { ... }
    fn on_xp_earn(key: &Self::XpKey, earned_points: Self::Points) { ... }
    fn on_xp_slash(key: &Self::XpKey, slashed_points: Self::Points) { ... }
    fn on_xp_update(key: &Self::XpKey, current_points: Self::Points) { ... }
}

Trait for mutating (modifying) XP entries and providing default support utilities.

This trait defines how XP is created, earned, set, reduced, and reset, and provides lifecycle hooks for reacting to XP changes.

XP mutation is non-transferable and always scoped to a specific XpKey.

Ownership, locking, and reserving are handled in separate traits.

If XpMutate is implemented, it typically implies that the runtime supports dynamic XP mutation via intents-either from trusted system actors or untrusted user inputs.

Additionally, this trait includes default support methods for common mutation patterns such as slashing and burning XP. These methods encapsulate reusable logic for safely reducing or resetting XP balances while handling edge cases.

Required Methods

fn init_xp() -> Self::Points

Returns the initial XP value for a newly created XP entry.

This defines the starting point assigned during create_xp.

fn new_xp(owner: &Self::Owner, key: &Self::XpKey)

Creates a new XP entry under the given key and owner.

Initializes the XP record in storage and associates it with the provided owner. This establishes the foundational XP entry that can then be mutated through other operations like earning or setting XP values.

This operation must be idempotent, meaning it is safe to retry with respect to already-initialized keys without causing errors or state corruption.

fn set_xp(key: &Self::XpKey, points: Self::Points) -> DispatchResult

Use with caution! Directly sets the liquid XP for the given key.

This function bypasses typical XP flow and permission checks, allowing direct manipulation of XP values. It is intended strictly for low-level runtime intents such as migrations, internal resets, or administrative operations.

This method must never be exposed to users or XP providers, as XP is meant to reflect earned value only through controlled mechanisms like XpMutate::earn_xp. Direct setting can undermine the integrity of the XP system’s earned-value principle.

Returns

• Ok(()) if the XP value is successfully set.
• Err(DispatchError) if the XP key does not exist or the operation fails.

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

Quotes the effective XP that would be earned for the given key.

This method applies runtime-specific constraints such as caps, rate limits, or validation rules, and returns the final amount that will be applied if Self::earn_xp is executed.

The implementation should handle overflow gracefully using saturating or checked arithmetic to prevent system instability. Runtime-specific constraints such as earning caps, rate limits, or validation rules should be enforced internally.

Note

This does not mutate state and serves as a pure computation step.

Returns

• Ok(Points) containing the adjusted XP to be earned.
• Err(DispatchError) if the XP key does not exist or validation fails.

Provided Methods

fn create_xp(owner: &Self::Owner, key: &Self::XpKey) -> DispatchResult

Creates and initializes a new XP entry under the given key and owner.

This is a high-level helper that:

• Initializes the XP entry via Self::new_xp
• Sets the initial XP using Self::init_xp and Self::set_xp
• Triggers the creation hook via Self::on_xp_create

Note

This is one of the recommended way to create XP entries (along with BeginXp::begin_xp), ensuring consistent initialization and lifecycle handling.

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

Increases the liquid XP associated with a given key by the specified number of points.

This is the primary mechanism for XP growth, designed for use in reward systems, leveling mechanics, achievement unlocks, and other scenarios where users earn XP through legitimate activities or contributions.

Returns

• Ok(Points) containing the actual XP earned after applying any internal adjustments.
• Err(DispatchError) if the XP key does not exist or the operation fails.

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

Reduces the liquid XP for the given key by the specified points.

This is the preferred method for applying penalties. It provides a safe, high-level abstraction over XP reduction.

This method attempts to slash the requested amount from the liquid XP balance. If sufficient liquid XP is available, the exact amount is slashed and returned. If available liquid XP is insufficient, all available liquid XP is burned instead and the actual burned amount is returned.

Returns

• Ok(Points) containing the actual points slashed or burned.
• Err(DispatchError) if the XP key does not exist or the operation fails.

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

Resets (burns) all liquid XP for the given key, returning the points burned.

This method completely resets the liquid XP balance to zero and returns the previous value. This is a destructive operation that cannot be undone and represents a total forfeiture of the liquid XP balance.

Burning is typically used for low-level runtime operations such as internal resets or state corrections.

Note

This is a low-level primitive. For penalty logic, prefer using Self::slash_xp, which provides a safer and intention-revealing abstraction.

Returns

• Ok(Points) containing the amount of XP that was burned.
• Err(DispatchError) if the XP key does not exist or the operation fails.

fn on_xp_create(key: &Self::XpKey, owner: &Self::Owner)

Hook invoked after a new XP identity is created.

This is called once during initialization and does not reflect subsequent balance updates.

This method is a no-op by default, but can be overridden to:

• Emit creation events
• Initialize metadata or indexes
• Trigger side effects tied to XP identity creation (optionally via listener XpMutateListener::xp_created)

fn on_xp_earn(key: &Self::XpKey, earned_points: Self::Points)

Hook invoked after XP is earned for a given key.

This reflects XP accumulation through valid actions.

This method is a no-op by default, but can be overridden to:

• Emit earning events
• Update metadata or statistics
• Trigger side effects related to XP accrual (optionally via listener XpMutateListener::xp_earned)

fn on_xp_slash(key: &Self::XpKey, slashed_points: Self::Points)

Hook invoked after XP is slashed for a given key.

This reflects a reduction in XP due to penalties or protocol actions.

This method is a no-op by default, but can be overridden to:

• Emit slashing events
• Update metadata or statistics
• Trigger side effects related to XP reduction (optionally via listener XpMutateListener::xp_slashed)

fn on_xp_update(key: &Self::XpKey, current_points: Self::Points)

Hook invoked after XP is updated for a given key without a specific intent.

This reflects a change in XP that is not explicitly categorized as earning, slashing, or resetting. It is typically used for internal adjustments, migrations, or state corrections where the cause is not semantically meaningful at the domain level.

The current_points parameter represents the latest liquid XP after the update.

This method is a no-op by default, but can be overridden to:

• Emit generic update events
• Synchronize external state or indexes
• Trigger side effects that depend on the current XP value (optionally via listener XpMutateListener::xp_updated)

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