Trait XpReap

pub trait XpReap
where
    Self: XpLock + XpSystem<Extension: XpReapListener + XpSystemExtensions<Via = Self>>,
{
    // Required methods
    fn is_reaped(key: &Self::XpKey) -> DispatchResult;
    fn reap_xp(key: &Self::XpKey) -> Result<Self::Points, DispatchError>;

    // Provided methods
    fn can_reap(key: &Self::XpKey) -> DispatchResult { ... }
    fn try_reap(key: &Self::XpKey) -> Result<Self::Points, DispatchError> { ... }
    fn on_xp_reap(key: &Self::XpKey) { ... }
}

Trait for XP lifecycle finalization (reaping) with built-in support utilities.

XpReap enables explicit deactivation or invalidation of XP entries that are no longer in use or have failed to exhibit expected runtime behavior.

This trait extends XP mutation and system capabilities to ensure full lifecycle control, including cleanup, guarded creation, and safe finalization.

XP entries marked as “reaped” are considered finalized and cannot be reinitialized.

Additionally, this trait includes default support methods for common reaping patterns, such as validating whether an XP entry can be safely reaped and performing safe, atomic reaping operations.

Example Use Cases

• Invalidated quests or tasks
• Expired onboarding flows
• Cleanup of abandoned or dead XP keys

Required Methods

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

Checks if the given XP key has been reaped (finalized).

This method serves as a guard against accidental recreation or mutation of finalized XP entries.

Returns

• Ok(()) if the XP key has been reaped.
• Err(DispatchError) if the XP key has not been reaped or does not exist.

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

Irreversibly marks the given XP key as reaped (finalized).

This operation permanently invalidates the XP entry, making it unusable for future operations. The method returns the total usable points from the XP entry, allowing the runtime to determine how to handle the recovered value.

Reaped XP cannot be recreated with the same key, ensuring that finalization is truly permanent. The recovered points can be redirected toward other purposes such as governance, treasury operations, or other runtime-controlled flows.

This is a destructive operation that should only be performed when an XP entry is confirmed to be no longer needed or valid according to system rules.

Returns

• Ok(Points) containing the total usable points from the reaped XP entry.
• Err(DispatchError) if the XP key does not exist or reaping fails.

Provided Methods

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

Checks whether the given XP key can be safely reaped (finalized).

This method enforces comprehensive safety conditions before allowing reaping:

• The XP entry must exist in storage
• The XP entry must not meet the minimum XP threshold (i.e., is “dead”)
• The XP entry must not have any active locks (prevents loss of locked value)
• The XP entry must not already be reaped (prevents double-finalization)

These conditions ensure that reaping only occurs when an XP entry is truly abandoned, expired, or no longer viable according to system rules.

Returns

• Ok(()) if all safety conditions are satisfied and reaping is allowed.
• Err(DispatchError) if any condition fails, with specific error indicating the failure reason.

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

Attempts to reap (finalize) the given XP entry if all conditions are met.

This method provides a safe, atomic approach to XP finalization by first validating all reaping conditions using can_reap, then proceeding with the irreversible reaping operation if validation passes.

This is the recommended way to perform XP reaping as it ensures all safety invariants are checked before the destructive operation occurs.

Returns

• Ok(Points) containing the total usable points from the reaped XP entry.
• Err(DispatchError) if any safety condition fails or the reaping operation encounters an error.

fn on_xp_reap(key: &Self::XpKey)

Hook invoked after an XP entry has been reaped.

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

• Emit reaping events
• Update related metadata
• Trigger side effects related to XP finalization

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