Trait RoleManager

Source

pub trait RoleManager<Candidate> {
    type Status: RuntimeEnum + Delimited + VariantCount;
    type Meta: Delimited;
    type Asset: Asset;
    type TimeStamp: Time;

Show 18 methods    // Required methods
    fn role_exists(who: &Candidate) -> DispatchResult;
    fn can_enroll(who: &Candidate, collateral: Self::Asset) -> DispatchResult;
    fn can_resign(who: &Candidate) -> DispatchResult;
    fn is_available(who: &Candidate) -> DispatchResult;
    fn get_meta(who: &Candidate) -> Result<Self::Meta, DispatchError>;
    fn get_collateral(who: &Candidate) -> Result<Self::Asset, DispatchError>;
    fn total_collateral() -> Self::Asset;
    fn enroll_since(who: &Candidate) -> Result<Self::TimeStamp, DispatchError>;
    fn get_status(who: &Candidate) -> Result<Self::Status, DispatchError>;
    fn status_since(who: &Candidate) -> Result<Self::TimeStamp, DispatchError>;
    fn set_status(who: &Candidate, status: Self::Status) -> DispatchResult;
    fn enroll(
        who: &Candidate,
        collateral: Self::Asset,
        force: Fortitude,
    ) -> Result<Self::Asset, DispatchError>;
    fn resign(who: &Candidate) -> Result<Self::Asset, DispatchError>;
    fn add_collateral(
        who: &Candidate,
        collateral: Self::Asset,
        force: Fortitude,
    ) -> Result<Self::Asset, DispatchError>;

    // Provided methods
    fn on_enroll(_who: &Candidate, _collateral: Self::Asset) { ... }
    fn on_resign(_who: &Candidate, _released: Self::Asset) { ... }
    fn on_status_update(_who: &Candidate, _status: &Self::Status) { ... }
    fn on_add_collateral(_who: &Candidate, _raised: Self::Asset) { ... }
}

Expand description

A universal abstraction for managing roles within a runtime context.

This trait defines the full lifecycle of a role-bearing entity - from enrollment and collateral management to status transitions and resignation.

It is intended to be the foundational interface for any module that wishes to assign and track roles such as:

Validators - entities providing consensus participation and staking collateral.
Council Members / Governance Actors - accounts participating in decision-making.
Oracle Operators - off-chain data feeders bonded with collateral.
Bounty Curators / Auditors / Relayers - specialized economic actors.

By providing a unified API for checking role existence, managing enrollment conditions, and handling collateral and lifecycle events, this trait enables role composability and modular runtime design.

§Type Parameters

Candidate: The identifier type representing an account or entity that can assume a role. Typically this is an AccountId, but it can also be a multi-entity struct or hash ID.

§Invariants

Collateral associated with a Candidate must remain locked while the role is active.
Status transitions must be atomic and consistent - i.e.,
once Self::set_status succeeds, Self::get_status should immediately reflect the new state.

§Example Implementations

§Example 1: Validator Role

A validator role might involve participants who are responsible for block production. In this context:

Status could include Pending, Active, Slashed, or Resigned.
Candidates are required to provide a minimum collateral to enroll.
The system checks whether a candidate is already enrolled before allowing enrollment.
The trait implementation manages enrollment, resignation, collateral tracking, and status updates.

§Example 2: Governance Council Member

A council member role represents participants in a governance body:

Status could include Candidate, Active, Expelled, or Retired.
Enrollment may not require collateral but must still enforce eligibility rules.
Resignation or removal is validated against membership in the council.
The trait implementation allows tracking of active members, status changes, and role lifecycle events.

These examples illustrate how the RoleManager trait can be applied to different kinds of roles, demonstrating the flexibility of the trait without tying it to a specific runtime storage or pallet.

§Usage

This trait is not tied to a specific module/pallet. It can be implemented by multiple role-managing pallets (e.g. pallet_validators, pallet_council, etc.).
Generic logic (e.g. in governance or reputation systems) can rely on RoleManager to interact with roles abstractly without hardcoding pallet internals.

Required Associated Types§

Source

type Status: RuntimeEnum + Delimited + VariantCount

Represents the discrete state (status) of the role (e.g. Active, Pending, Resigned, etc).
Must implement [VariantCount] for easy introspection of status variants.

Source

type Meta: Delimited

Represents the metadata of the candidate.

Could include valuable information pertaining to the role-activity of the candidate.

Source

type Asset: Asset

Represents the collateral or balance type associated with the role.

Source

type TimeStamp: Time

Represents a timestamp or block number used to track temporal data like enrollment or status changes.

Required Methods§

Source

fn role_exists(who: &Candidate) -> DispatchResult

Checks whether a given Candidate currently has a registered role in the system.

Returns Ok(()) if the role exists, otherwise DispatchError.

Source

fn can_enroll(who: &Candidate, collateral: Self::Asset) -> DispatchResult

Validates whether the Candidate is eligible to enroll for a role, given a specific collateral amount.

This function only performs validation and not mutates state.

Returns Ok(()) if the candidate can enroll, or a DispatchError if not.

Source

fn can_resign(who: &Candidate) -> DispatchResult

Verifies whether the Candidate can safely resign their role.

This typically ensures there are no pending obligations or locked collateral.

Source

fn is_available(who: &Candidate) -> DispatchResult

Returns Ok(()) if the Candidate is considered not defaulted i.e., available.

A defaulted state represents a breach of expected behavior such as under-collateralization, missed performance targets, or protocol violations.

Depending on implementation, a defaulted candidate may be:

Temporarily suspended - can later recover or be reinstated once obligations are met.
Permanently defaulted - considered resigned, fired, or barred from reactivation.

Source