Trait CompensateRoles

pub trait CompensateRoles<Candidate>: RoleManager<Candidate> {
    type Ratio: Percentage;

    // Required methods
    fn has_reward(who: &Candidate) -> DispatchResult;
    fn has_penalty(who: &Candidate) -> DispatchResult;
    fn get_hold(who: &Candidate) -> Result<Self::Asset, DispatchError>;
    fn get_rewards_of(
        who: &Candidate,
    ) -> Result<Vec<(Self::TimeStamp, Self::Asset)>, DispatchError>;
    fn get_rewards_on(
        time_stamp: Self::TimeStamp,
    ) -> Result<Vec<(Candidate, Self::Asset)>, DispatchError>;
    fn get_penalties_of(
        who: &Candidate,
    ) -> Result<Vec<(Self::TimeStamp, Self::Ratio)>, DispatchError>;
    fn get_penalties_on(
        time_stamp: Self::TimeStamp,
    ) -> Result<Vec<(Candidate, Self::Ratio)>, DispatchError>;
    fn set_hold(
        who: &Candidate,
        value: Self::Asset,
        precision: Precision,
        force: Fortitude,
    ) -> DispatchResult;
    fn reward(
        who: &Candidate,
        value: Self::Asset,
        precision: Precision,
    ) -> Result<Self::TimeStamp, DispatchError>;
    fn penalize(
        who: &Candidate,
        factor: Self::Ratio,
    ) -> Result<Self::TimeStamp, DispatchError>;
    fn forgive(
        who: &Candidate,
        from: Self::TimeStamp,
    ) -> Result<Self::Ratio, DispatchError>;
    fn reclaim(
        who: &Candidate,
        from: Self::TimeStamp,
    ) -> Result<Self::Asset, DispatchError>;

    // Provided methods
    fn on_reward(_who: &Candidate, _amount: Self::Asset, _at: Self::TimeStamp) { ... }
    fn on_penalize(_who: &Candidate, _factor: Self::Ratio, _at: Self::TimeStamp) { ... }
    fn on_forgive(_who: &Candidate, _factor: Self::Ratio) { ... }
    fn on_reclaim(_who: &Candidate, _amount: Self::Asset) { ... }
    fn on_set_hold(_who: &Candidate, _value: Self::Asset) { ... }
}

Extends RoleManager to introduce reward and penalty mechanics for role-based systems.

This trait manages economic incentives and behavioral enforcement for candidates, tracking rewards, penalties, and temporary holdings. Typical applications include (but not constrained to):

• Validators - rewards for block production, penalties for missed duties.
• Council members - incentives for active participation, slashing for misconduct.
• Oracle operators - rewards for accurate reporting, penalties for stale or incorrect data.

Concepts

• Hold: The total reservation of a candidate’s assets, includes rewards and other backings (collaterals, fundings, etc).
• Reward: An addition to a candidate’s assets for performing expected duties.
• Penalty: A fractional deduction (ratio) applied to assets for misbehavior or non-performance.
• Forgive: Reverses penalties, partially or fully, for rehabilitation or governance action.
• Reclaim: Withdraw previously rewarded assets for redistribution or correction.

All returned values (assets, rewards, penalties) are real-time, reflecting the candidate’s current effective state.

Example Implementations

Example 1: Validator Rewards and Penalties

In a blockchain validator system:

• Validators earn rewards for producing blocks, finalizing chains, or performing other expected duties.
• Misbehavior, missed blocks, or downtime results in penalties, which reduce the validator’s hold.
• Rewards and penalties are recorded with timestamps, allowing auditability and historical tracking.
• The system may forgive temporary penalties or reclaim rewards in case of protocol corrections.
• Real-time queries (get_rewards_of, get_penalties_of) reflect the current effective state of the validator.

Example 2: Council Member Performance Incentives

In a governance council:

• Council members receive rewards for attending sessions, voting, or completing assigned tasks.
• Failure to participate or violating rules triggers penalties, possibly reducing influence or rewards.
• Holds represent assets reserved for potential penalties or pending rewards.
• Forgiveness mechanisms allow partial reversal of penalties for rehabilitation or governance decisions.
• Reclaiming rewards may occur if a proposal is invalidated or performance is reversed.
• Real-time computations ensure all incentives and penalties are up-to-date when queried.

These examples illustrate how CompensateRoles can manage dynamic reward and penalty systems across different roles, ensuring fairness, accountability, and flexibility in role-based operations.

Invariants

• Total penalties cannot exceed the candidate’s current hold or collateral.
• Implementations should track timestamps accurately to maintain auditability.

Required Associated Types

type Ratio: Percentage

The ratio type used to represent penalty factors applied to a candidate.

This type defines how much of a candidate’s assets should be deducted during a penalty event, expressed as a fractional percentage.

• Values should be within [0, 1] (0% to 100%)
• Example: 0.05 -> 5% penalty, 0.25 -> 25% penalty

Required Methods

fn has_reward(who: &Candidate) -> DispatchResult

Checks whether the candidate has any pending rewards.

fn has_penalty(who: &Candidate) -> DispatchResult

Checks whether the candidate has any pending penalties.

fn get_hold(who: &Candidate) -> Result<Self::Asset, DispatchError>

Returns the current hold amount of a candidate.

Holds are total reserved assets (may include rewards) that may be used for penalties or temporary constraints.

fn get_rewards_of( who: &Candidate, ) -> Result<Vec<(Self::TimeStamp, Self::Asset)>, DispatchError>

Returns all pending rewards for a candidate along with their timestamp of enforcement.

The list reflects real-time pending rewards, not historical logs.

fn get_rewards_on( time_stamp: Self::TimeStamp, ) -> Result<Vec<(Candidate, Self::Asset)>, DispatchError>

Returns all rewards of candidates issued at a specific timestamp.

• This is a snapshot query for the given timestamp; it does not mutate state.
• Returned values may reflect the rewards actually enforced or pending based on the given timestamp, which may be used for auditing, reporting, or batch processing.

fn get_penalties_of( who: &Candidate, ) -> Result<Vec<(Self::TimeStamp, Self::Ratio)>, DispatchError>

Returns all pending penalties for a candidate along with their timestamp of enforcement.

The list reflects real-time pending penalties, not historical logs.

fn get_penalties_on( time_stamp: Self::TimeStamp, ) -> Result<Vec<(Candidate, Self::Ratio)>, DispatchError>

Returns all penalties of candidates issued at a specific timestamp.

• This is a snapshot query for the given timestamp; it does not mutate state.
• Returned values may reflect the penalties actually enforced or pending based on the given timestamp, which may be used for auditing, reporting, or batch processing.

fn set_hold( who: &Candidate, value: Self::Asset, precision: Precision, force: Fortitude, ) -> DispatchResult

Updates the hold of a candidate to the specified amount.

This method is utilized to reward or penalize a Candidate’s hold which reflects on its individual backings.

fn reward( who: &Candidate, value: Self::Asset, precision: Precision, ) -> Result<Self::TimeStamp, DispatchError>

Issues a reward to a candidate, marks it as pending and returning the timestamp.

Once the reward is enforced during the timestamp, it is applied to the Candidate’s hold.

This is to ensure rewards reversal (regaining) if applied wrongly.

fn penalize( who: &Candidate, factor: Self::Ratio, ) -> Result<Self::TimeStamp, DispatchError>

Applies a penalty (fractional Ratio) to a candidate, marks it as pending and returning the timestamp.

Once the penalty is enforced during the timestamp, it is applied to the Candidate’s hold.

This is to ensure penalty reversal (forgiving) if applied wrongly.

fn forgive( who: &Candidate, from: Self::TimeStamp, ) -> Result<Self::Ratio, DispatchError>

Forgives a pending penalty, returning its factor.

Cannot be utilized for enforced penalties, only pending ones.

from specifies the timestamp of the penalty to forgive.

fn reclaim( who: &Candidate, from: Self::TimeStamp, ) -> Result<Self::Asset, DispatchError>

Reclaims a pending reward from a candidate, returning its reward value.

Cannot be utilized for enforced rewards, only pending ones.

from specifies the timestamp of the reward to reclaim.

Provided Methods

fn on_reward(_who: &Candidate, _amount: Self::Asset, _at: Self::TimeStamp)

Hook triggered when a reward is issued.

Default is no-op.

fn on_penalize(_who: &Candidate, _factor: Self::Ratio, _at: Self::TimeStamp)

Hook triggered when a penalty is applied.

Default is no-op.

fn on_forgive(_who: &Candidate, _factor: Self::Ratio)

Hook triggered when a penalty is forgiven.

Default is no-op.

fn on_reclaim(_who: &Candidate, _amount: Self::Asset)

Hook triggered when a reward is reclaimed.

Default is no-op.

fn on_set_hold(_who: &Candidate, _value: Self::Asset)

Hook triggered when an author’s total hold is updated.

Signals a mutation maybe due to rewards/penalties or internal changes enforced (finalized)

Default is no-op.

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