Trait RewardAuthors

pub trait RewardAuthors<Author, Asset, Points>
where
    Author: Keyed,
    Asset: Asset,
    Points: Countable,
{
    type AuthorPointsAdapter: AuthorPoints<Author, Points>;
    type PayoutFor: Buffer<(Author, Points)>;
    type PayeeList: Buffer<(Author, Asset)>;
    type PayoutModel: PurePluginModel<Asset, <Self::PayoutContext as ModelContext>::Context, Asset> + Default;
    type PayoutContext: ModelContext;
    type PayeeModel: PurePluginModel<(Asset, Self::PayoutFor), <Self::PayeeContext as ModelContext>::Context, Self::PayeeList> + Default;
    type PayeeContext: ModelContext;

    // Required methods
    fn payout_via() -> Asset;
    fn payout_for() -> Self::PayoutFor;
    fn reward(who: &Author, value: Asset) -> DispatchResult;

    // Provided methods
    fn payout() -> Asset { ... }
    fn payout_process(input: Asset) -> Asset { ... }
    fn payee_process(input: (Asset, Self::PayoutFor)) -> Self::PayeeList { ... }
    fn reward_authors() { ... }
    fn on_reward_success(_who: &Author, _value: Asset) { ... }
    fn on_reward_fail(_who: &Author, _err: DispatchError) { ... }
}

Provides a plugin-driven reward system for authors, connecting ephemeral points to actual asset payouts.

This trait is designed for modular, flexible, and runtime-configurable reward logic in Substrate pallets.

Points should reflect temporary contributions (e.g., block production, validation) and are cleared after each reward cycle.

Core Responsibilities

1. Track author points using Self::AuthorPointsAdapter.
2. Compute the total payout using a runtime-configurable Self::PayoutModel.
3. Generate a per-author payout list using Self::PayeeModel.
4. Execute rewards safely, with callbacks for success or failure.

Type Parameters

• Author: Entity receiving rewards.
• Asset: Type of reward (e.g., token balance).
• Points: Type representing ephemeral points .

Required Associated Types

type AuthorPointsAdapter: AuthorPoints<Author, Points>

Adapter connecting author points with the reward logic.

This associated type provides the bridge between ephemeral points assigned to authors and the current reward computation system.

• Defined as an associated type because points may be tracked externally or come from non-local sources.
• Responsible for capturing all point contributions relevant to rewarding, ensuring accurate reward calculations.

type PayoutFor: Buffer<(Author, Points)>

Collection of authors and their ephemeral points for the current reward cycle.

This type represents the input to the Self::PayeeModel plugin, which determines how the total payout is distributed among authors based on their points.

type PayeeList: Buffer<(Author, Asset)>

Collection of authors and their final reward amounts for the current cycle.

This type represents the output of the Self::PayeeModel plugin, which maps author points and the total payout into actual rewards (Asset).

type PayoutModel: PurePluginModel<Asset, <Self::PayoutContext as ModelContext>::Context, Asset> + Default

Plugin model for computing the total reward pool.

This model determines how the raw total payout is transformed into the final total reward.

This plugin allows runtime-configurable logic to adjust the raw total payout (Asset) before distributing it to authors.

Input

• Asset: The raw total reward amount for the current cycle.

Output

• Asset: The optimized total reward after applying payout logic (e.g., capping, scaling, or applying curves).

type PayoutContext: ModelContext

Provides optional runtime parameters for the payout plugin Self::PayoutModel.

Enables dynamic configuration, such as thresholds, multipliers, or other runtime-adjustable settings.

type PayeeModel: PurePluginModel<(Asset, Self::PayoutFor), <Self::PayeeContext as ModelContext>::Context, Self::PayeeList> + Default

Plugin model for computing per-author payouts from total payout and points.

This plugin model responsible for distributing the total payout among authors according to their points.

• Input: Tuple (total_payout, Self::PayoutFor).
• Output: Self::PayeeList.

Computes the mapping from (Author, Points) to (Author, Asset).

type PayeeContext: ModelContext

Provides optional runtime parameters for the payee plugin Self::PayeeModel computation.

Enables dynamic configuration, such as thresholds, multipliers, or other runtime-adjustable settings.

Required Methods

fn payout_via() -> Asset

Returns the raw, unprocessed total payout for the current reward cycle.

This is the low-level deterministic total reward amount before any adjustments:

• May reflect a global metric (e.g., total stake, contributions, or available funds).
• Can be modified by the Self::PayoutModel plugin to produce the final payout via Self::payout.
• May be very large or very small depending on the cycle conditions.

fn payout_for() -> Self::PayoutFor

Returns the authors and their accumulated points for the current reward cycle.

• Serves as the input for the Self::PayeeModel plugin to compute per-author payouts.
• Represents ephemeral contributions, which are cleared after reward distribution.
• Can include multiple roles or activities that contribute points for rewards.

fn reward(who: &Author, value: Asset) -> DispatchResult

Distributes a reward value to a specific author who.

Requirements

• Must be implemented by the pallet using this trait.
• Example implementations: token transfer, minting, or crediting balances.

Provided Methods

fn payout() -> Asset

Computes the final total payout for the current reward cycle.

• Uses the Self::PayoutModel plugin via Self::payout_process to adjust the raw payout (Self::payout_via).
• Can apply reward curves, scaling, caps, or other runtime-configurable rules.
• Represents the high-level payout that will be distributed to authors.

fn payout_process(input: Asset) -> Asset

Self::PayoutModel plugin output function. Utilizes the plugin model’s context Self::PayoutContext

fn payee_process(input: (Asset, Self::PayoutFor)) -> Self::PayeeList

Self::PayeeModel plugin output function. Utilizes the plugin model’s context Self::PayeeContext

fn reward_authors()

Distributes rewards to authors based on their points and available payout.

Workflow

1. Compute total payout using Self::payout.
2. If payout is zero, skip distribution.
3. Generate per-author payout list via the Self::PayeeModel plugin function Self::payee_process.
4. Distribute rewards using Self::reward for each author.
5. Call Self::on_reward_success or Self::on_reward_fail callbacks for each author.
6. Clear ephemeral points via Self::AuthorPointsAdapter.

Notes

• Ensure that enough points are supplied; otherwise, a few authors may receive disproportionately high rewards.
• Individual failures are handled gracefully and do not abort the reward cycle.

fn on_reward_success(_who: &Author, _value: Asset)

Callback invoked after a successful individual reward.

Useful for logging, metrics collection, or triggering side-effects.

Default is no-op

fn on_reward_fail(_who: &Author, _err: DispatchError)

Callback invoked when an individual reward fails.

Useful for logging, alerting, or implementing retry logic.

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