Struct Internals

pub(crate) struct Internals<T: Config>(PhantomData<T>);

Internal helper struct for implementing not-exposable blockchain trait operations.

Internals implements the blockchain low-level helper traits:

• RewardAuthors
• ElectAuthors
• PenalizeAuthors

Tuple Fields

0: PhantomData<T>

Trait Implementations

impl<T: Config> ElectAuthors<<T as Config>::AccountId, <<T as Config>::ElectionAdapter as ElectionManager<<T as Config>::AccountId>>::ElectionWeightOf> for Internals<T>

Implementation of the ElectAuthors trait for the pallet internal type (not exposable).

This implementation bridges the generic ElectAuthors abstraction with the pallet’s internal affidavit and role-management infrastructure, coordinating candidate selection, time-gated election execution, and result revelation for upcoming sessions.

Design Notes

• Elections are session-scoped and always target the upcoming session.
• Only authors who have successfully submitted affidavits are eligible.
• All election logic is time-gated and derived from session timing, affidavit windows, and election offsets.
• This layer is deterministic; it does not perform probabilistic or stateful election logic.

Implementation Notes

• This implementation does not execute the election algorithm itself.

• All ranking, scoring, and selection logic is delegated to the configured ElectionManager via the pallet’s Config::ElectionAdapter.

• This layer is responsible only for:

  • Validating election timing
  • Preparing candidate inputs
  • Revealing results from the election manager

type Candidates = <<T as Config>::ElectionAdapter as ElectionManager<<T as Config>::AccountId>>::Params

Type representing the prepared election candidates.

Typically a vector of author’s ID and their corresponding election weights.

type Elected = <<T as Config>::ElectionAdapter as ElectionManager<<T as Config>::AccountId>>::Elected

Type representing the final elected author set.

Typically a vector of author IDs.

fn prepare_authors(candidates: Self::Candidates) -> DispatchResult

Prepares election candidates via the configured election manager.

• Acts as a thin delegation layer to ElectionManager::prepare.
• Any failure here prevents election execution.
• Typically runs the election algorithm and stores the election result.
• Inconsistencies return explicit errors.

fn can_process_election(_runner: &Option<AuthorOf<T>>) -> DispatchResult

Checks whether the election can be processed at the current block.

Parameters

• runner: Optional executor of the election (runtime or author-driven). This is not validated here, but is assumed to be the entity responsible for executing the election, as permitted by the caller.

Validation

• Ensures the affidavit window is valid (start < end).
• Ensures the current block is within the affidavit window.
• Ensures the election window has started.
• Ensures the election has not yet ended (bounded by affidavit end).

Violations return explicit, user-facing errors.

fn prepare_candidates() -> Result<Self::Candidates, DispatchError>

Prepares the final list of candidates for election.

Overview

• Iterates all affidavits submitted for the upcoming session.
• Extracts and normalizes each author’s election weights.
• Produces a deterministic candidate list for the election manager.

Notes

• Only affidavit-submitting authors are included.
• This function performs no ranking or filtering.
• Ordering guarantees are provided by downstream election logic.

fn reveal() -> Option<Self::Elected>

Reveals the elected authors from the underlying election manager.

Acts as a thin delegation layer to ElectionManager::reveal.

Failure Semantics

This may return None if:

• The election was never executed
• Preparation failed
• Minimum candidate constraints were not met

Caller Responsibility

Callers must handle the None case gracefully, typically by retaining the previously elected author set.

fn on_elect_success(runner: &Option<AuthorOf<T>>)

Hook invoked after a successful election preparation.

Emits a Event::ElectedInstance event if Config::EmitEvents is true.

fn on_elect_fail(runner: &Option<AuthorOf<T>>, error: DispatchError)

Hook invoked when an election attempt fails.

Emits a Event::ElectionAttemptFailed event if Config::EmitEvents is true.

fn prepare_election(runner: &Option<Author>) -> Result<(), DispatchError>

High-level orchestration function for running the entire election flow.

impl<T: Config> PenalizeAuthors<<T as Config>::AccountId, <<T as Config>::RoleAdapter as CompensateRoles<<T as Config>::AccountId>>::Ratio> for Internals<T>

Implementation of the PenalizeAuthors trait for the pallet internal type (not-exposable).

This implementation bridges author offence signals with the protocol’s penalty and slashing mechanisms, enabling penalties to be scheduled and processed according to runtime-defined rules.

Penalties, like rewards, follow a deferred enforcement model. They are recorded and transformed first, then enforced later by downstream role and penalty management logic.

Design Notes

• Penalties are author-scoped and apply to active roles.
• Enforcement is scheduled, not immediate.
• Multiple penalties may be:
  • Aggregated
  • Scaled
  • Capped
  • Reverted prior to final enforcement.
• Penalty values are interpreted as inputs, not final amounts.
• Transformation and enforcement are governed by runtime-configured penalty models for flexibility and governance control.

Implementation Notes

• This layer does not detect offences or compute severity.
• It does not finalize or immediately apply penalties.
• All penalty logic is delegated to:
  • Config::PenaltyModel
  • CompensateRoles::penalize
• This implementation guarantees deterministic, auditable scheduling of penalties without side effects.

type PenaltyFor = Vec<(<T as Config>::AccountId, <<T as Config>::RoleAdapter as CompensateRoles<<T as Config>::AccountId>>::Ratio)>

Mapping of authors to their applied penalties (percentage typically).

type PenaltyContext = <T as Config>::PenaltyContext

Context provided to the penalty plugin model for transformation.

type PenaltyModel = <T as Config>::PenaltyModel

Plugin Model responsible for transforming raw penalties according to runtime-defined rules (e.g. caps, scaling, thresholds).

fn penalize(who: &AuthorOf<T>, penalty: PenaltyOf<T>) -> DispatchResult

Applies a penalty to the given author.

Acts as a thin delegation layer to CompensateRoles::penalize.

Semantics

• Penalties are scheduled, not applied immediately.
• Downstream logic may:
  • Aggregate multiple penalties
  • Scale or cap penalties
  • Delay or revert enforcement prior to finalization

Notes

• This function does not persist offence metadata.
• Offence detection and validation are the responsibility of the caller.

Errors

Returns a DispatchError if penalty scheduling fails.

fn on_penalty_success(who: &AuthorOf<T>, penalty: PenaltyOf<T>)

Hook invoked after a penalty is successfully applied to an author.

This hook emits the Penalized event, reflecting the penalty enforced against the author.

fn on_penalty_fail(who: &AuthorOf<T>, error: DispatchError)

Hook invoked when applying a penalty to an author fails.

This hook emits the PenaltyFailed event, reflecting the error that prevented the penalty from being applied.

fn penalize_authors(towards: Self::PenaltyFor)

Apply penalties to a list of authors.

fn transform_penalty(input: Self::PenaltyFor) -> Self::PenaltyFor

Transforms raw penalties using the Self::PenaltyModel plugin.

impl<T: Config> RewardAuthors<<T as Config>::AccountId, <<T as Config>::RoleAdapter as RoleManager<<T as Config>::AccountId>>::Asset, <T as Config>::Points> for Internals<T>

Implementation of the RewardAuthors trait for the pallet internal type (not exposable).

This implementation bridges abstract author points with the protocol’s reward and inflation mechanisms, translating session-scoped behavioural signals into scheduled economic rewards.

This layer does not mint, transfer, or finalize rewards directly. Instead, it provides deterministic inputs to downstream reward logic owned by the configured RoleManager adapters.

Design Notes

• Rewards are derived from session-scoped point accumulation.
• Points are interpreted as relative behavioural weights, not absolute reward amounts.
• The payout context is configurable and may be based on:
  • Total token issuance (inflation-based) or,
  • Total backing + collateral stake (stake-weighted)
• All reward operations must remain deterministic, auditable, and reversible until finalization.

Implementation Notes

• This implementation does not compute reward shares.
• Reward distribution logic is delegated to:
  • Config::InflationModel
  • Config::RewardModel
  • CompensateRoles
• This layer only exposes:
  • The payout context
  • The eligible payee set
  • A scheduling hook for rewards

type AuthorPointsAdapter = <T as Config>::PointsAdapter

Adapter used to query accumulated author points.

type PayoutFor = Vec<(<T as Config>::AccountId, <T as Config>::Points)>

Type representing authors eligible for payout and their points.

Typically a vector of author’s ID and their correspoinding points.

type PayoutContext = <T as Config>::InflationContext

Context used by the inflation plugin model.

type PayoutModel = <T as Config>::InflationModel

Inflation plugin model used to derive reward budgets.

type PayeeList = Vec<(<T as Config>::AccountId, <<T as Config>::RoleAdapter as RoleManager<<T as Config>::AccountId>>::Asset)>

Type representing the set of reward payees.

Typically a vector of author’s ID and their correspoinding reward asset amount.

type PayeeContext = <T as Config>::RewardContext

Context supplied to the reward plugin model.

type PayeeModel = <T as Config>::RewardModel

Reward plugin model used to translate points into payouts.

fn payout_via() -> AssetOf<T>

Returns the total asset context used to compute rewards.

Semantics

Depending on configuration, this returns:

• Total token issuance (supply-based inflation), or
• Total backing + collateral stake (stake-weighted inflation)

Notes

• This value represents the upper bound for reward calculation.
• It does not imply immediate minting or transfer.

fn reward(who: &AuthorOf<T>, value: AssetOf<T>) -> DispatchResult

Schedules a reward for the given author.

Acts as a thin delegation layer to CompensateRoles::reward.

Semantics

• This function does not finalize the reward.
• Rewards are scheduled with best-effort precision.
• Downstream logic may:
  • Aggregate
  • Adjust
  • Revert the scheduled reward before finalization.

Errors

Returns a DispatchError if reward scheduling fails.

fn payout_for() -> Self::PayoutFor

Returns the set of authors eligible for payout and their accumulated points for the current session.

Notes

• This function is expected to be called at session end.
• Calling it earlier may yield partial or unstable results.
• The returned data is treated as immutable for reward computation.

fn on_reward_success(who: &AuthorOf<T>, value: AssetOf<T>)

Hook invoked after a reward is successfully applied to an author.

This hook emits the Rewarded event, reflecting the distributed reward amount for the given author.

fn on_reward_fail(who: &AuthorOf<T>, error: DispatchError)

Hook invoked when applying a reward to an author fails.

This hook emits the RewardFailed event, reflecting the error that prevented the reward from being applied.

fn payout() -> Asset

Computes the final total payout for the current reward cycle.

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.