Trait XpOwner

pub trait XpOwner
where
    Self: XpSystem<Extension: XpOwnerListener + XpSystemExtensions<Via = Self>>,
{
    type Owner: Keyed;

    // Required methods
    fn is_owner(owner: &Self::Owner, key: &Self::XpKey) -> DispatchResult;
    fn xp_of_owner(
        owner: &Self::Owner,
    ) -> Result<Vec<Self::XpKey>, DispatchError>;
    fn xp_key_gen(
        owner: &Self::Owner,
        xp: &Self::Xp,
    ) -> Result<Self::XpKey, DispatchError>;
    fn set_owner(
        current_owner: &Self::Owner,
        key: &Self::XpKey,
        new_owner: &Self::Owner,
    ) -> DispatchResult;

    // Provided methods
    fn transfer_owner(
        owner: &Self::Owner,
        key: &Self::XpKey,
        new_owner: &Self::Owner,
    ) -> DispatchResult { ... }
    fn on_xp_transfer(key: &Self::XpKey, new_owner: &Self::Owner) { ... }
}

Trait for XP ownership and access control.

This trait defines the relationship between an Owner and their associated XP keys, enabling access control and transfer semantics for XP entries.

Required Associated Types

type Owner: Keyed

Represents the unique identifier for the owner of an XP entry.

Typically used to associate XP records with accounts or verifiable entities in the system.

Required Methods

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

Checks whether the given owner controls the specified XP key.

This is the primary access control check used by mutation and permission logic throughout the XP system. All ownership-sensitive operations should use this method to verify authorization before proceeding.

Returns

• Ok(()) if the owner controls the specified XP key.
• Err(DispatchError) if the owner does not control the XP key.

fn xp_of_owner(owner: &Self::Owner) -> Result<Vec<Self::XpKey>, DispatchError>

Returns all XP keys currently owned by the given owner.

This method enables enumeration and inspection of an owner’s XP portfolio, useful for performing bulk operations, displaying user assets, or implementing ownership-based queries and analytics.

Returns

• Ok(Vec<XpKey>) containing all XP keys owned by the specified owner.
• Err(DispatchError) if the owner lookup fails.

fn xp_key_gen( owner: &Self::Owner, xp: &Self::Xp, ) -> Result<Self::XpKey, DispatchError>

Generates a deterministic XP key from the given owner and XP metadata.

Abstracts the process of deriving a unique, reproducible XP key for a specific owner and XP record.

Typically leverages crate::keys::KeyGenFor or a similar deterministic key derivation utility, combining the owner identifier, XP struct (or metadata), and a generated salt value.

Guarantees that each XP key is unique for every distinct combination of owner, XP metadata, and salt. This enables support for namespaced, context-specific, or multi-record XP systems, allowing a single owner to possess multiple XP entries differentiated by context or purpose.

Returns

• Ok(XpKey) containing the generated deterministic key.
• Err(DispatchError) if key generation fails or cannot be deterministically derived.

fn set_owner( current_owner: &Self::Owner, key: &Self::XpKey, new_owner: &Self::Owner, ) -> DispatchResult

Sets the owner of the given XP key.

This updates the ownership mapping from the current owner to the new owner.

Note

This is a low-level primitive that directly mutates ownership without performing access control checks.

This method enforces that an XP key cannot exist without an owner by requiring both the current and new owner during the update.

Prefer using transfer_owner for safe ownership changes.

Returns

• Ok(()) if the owner is successfully updated.
• Err(DispatchError) if the operation fails.

Provided Methods

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

Transfers ownership of the given XP key from the current owner to a new owner.

This function updates the ownership mapping to associate the XP key with the new owner. The transfer is immediate and permanent, removing all access rights from the previous owner and granting full control to the new owner.

Note

This is a high-level operation that enforces access control via Self::is_owner. The underlying ownership update is performed by Self::set_owner, which acts as the low-level primitive.

Returns

• Ok(()) if the ownership transfer completes successfully.
• Err(DispatchError) if the transfer fails due to access control or system errors.

fn on_xp_transfer(key: &Self::XpKey, new_owner: &Self::Owner)

Hook invoked after a successful XP ownership transfer.

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

• Emit transfer events
• Update metadata or access rights tied to the XP key
• Trigger side effects related to ownership changes (optionally via listener XpOwnerListener::xp_transferred)

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