Trait ElectAuthors

pub trait ElectAuthors<Author, ElectionWeight>
where
    Author: Keyed,
    ElectionWeight: Ord + Storable,
{
    type Candidates: Buffer<(Author, ElectionWeight)>;
    type Elected: Buffer<Author>;

    // Required methods
    fn can_process_election(_runner: &Option<Author>) -> DispatchResult;
    fn reveal() -> Option<Self::Elected>;
    fn prepare_candidates() -> Result<Self::Candidates, DispatchError>;
    fn prepare_authors(candidates: Self::Candidates) -> DispatchResult;

    // Provided methods
    fn prepare_election(runner: &Option<Author>) -> DispatchResult { ... }
    fn on_elect_success(_runner: &Option<Author>) { ... }
    fn on_elect_fail(_runner: &Option<Author>, _err: DispatchError) { ... }
}

Higher-Level Trait for performing election of authors (e.g., block producers, validators, etc) in a FRAME-based runtime.

This trait abstracts the process of candidate preparation, author selection, and election result handling in a generic, pluggable way.

The design allows different implementations to define their own election logic - such as weighted randomness, reputation-based scoring, or round-robin selection - while maintaining a consistent interface.

Type Parameters

• Author: The type representing an author or candidate
• ElectionWeight: The type representing each candidate’s election weight, score, or stake. Should be comparable Ord.

Runner Model

The election process can be executed in two modes:

• Global execution (None): The runtime itself triggers and executes the election (e.g., via inherent or root-driven logic).
• Author-driven execution (Some(Author)): A specific author acts as a runner, voluntarily or by assignment, to execute the election logic.

This enables flexible designs where:

• Elections can be decentralized and triggered by participants.
• A designated author (e.g., block producer, coordinator) can perform elections.
• The runtime can still retain full control when required.

Usage

A runtime pallet implementing this trait would typically:

1. Collect candidates via Self::prepare_candidates.
2. Elect authors via Self::prepare_authors.
3. Handle success or failure with Self::on_elect_success or Self::on_elect_fail, optionally using the runner.
4. Reveal the final elected authors with Self::reveal.

Required Associated Types

type Candidates: Buffer<(Author, ElectionWeight)>

Type representing all candidates in the election.

type Elected: Buffer<Author>

Type representing the set of successfully elected authors.

Required Methods

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

Determines whether the election process can currently be run.

Parameters

• runner: Optional executor of the election process.
  • None: runtime-driven execution.
  • Some(author): author-driven execution.

This is a pre-check to ensure that conditions are right for running an election. For example, a runtime may enforce:

• Minimum number of candidates.
• Required system state (e.g., epoch boundaries).
• Timing constraints or cooldown periods.
• Authorization or eligibility of the runner.

Returns Ok(()) if the election is allowed to proceed, DispatchError otherwise.

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

Returns the final set of recently elected authors.

Implementations may retrieve this from storage or memory. This is usually called after a successful Self::prepare_election run.

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

Prepares the set of candidates for the next election round.

Typically this would collect eligible authors, validators, or accounts from storage or an external data source, and attach their election weights.

Returns either the collection of candidates or an error if preparation fails.

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

Main entry point for the election process.

Takes a collection of candidates (with weights) and performs the author election logic - storing or returning the result as appropriate.

Returns Ok(()) if election succeeds, or Err(DispatchError) if election logic fails.

Provided Methods

fn prepare_election(runner: &Option<Author>) -> DispatchResult

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

Parameters

• runner: Optional executor of the election process.
  • None: election is executed by the runtime.
  • Some(author): a specific author executes the election.

Workflow

1. Calls Self::can_process_election to validate execution conditions.
2. Calls Self::prepare_candidates to collect all eligible candidates.
3. Passes them to Self::prepare_authors to perform the election.
4. Triggers Self::on_elect_success or Self::on_elect_fail with runner.

This ensures consistent election control flow, centralized error handling, and proper attribution of execution responsibility.

Returns DispatchError if any stage fails.

fn on_elect_success(_runner: &Option<Author>)

Hook called when an election completes successfully.

Parameters

• runner: Optional executor of the election.

To perform post-election actions such as:

• Persisting results to storage.
• Emitting pallet events.
• Updating system state or metrics.
• Attributing execution responsibility or rewards to the runner.

Default implementation is no-op

fn on_elect_fail(_runner: &Option<Author>, _err: DispatchError)

Hook called when an election fails.

Parameters

• runner: Optional executor of the election.
• err: The error that caused the failure.

Runtime implementations can override this to:

• Emit error events.
• Retry logic.
• Fallback to default authors.
• Attribute failure or responsibility to the runner.

The passed DispatchError provides detailed context on what went wrong. Default implementation 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