Trait ElectionAffidavits

pub trait ElectionAffidavits<Author, ElectionWeight>
where
    Author: Keyed,
    ElectionWeight: Ord + Storable,
{
    // Required methods
    fn can_submit_affidavit(who: &Author) -> DispatchResult;
    fn affidavit_exists(who: &Author) -> DispatchResult;
    fn get_affidavit(who: &Author) -> Result<ElectionWeight, DispatchError>;
    fn gen_affidavit(who: &Author) -> Result<ElectionWeight, DispatchError>;
    fn submit_affidavit(
        who: &Author,
        affidavit: &ElectionWeight,
    ) -> DispatchResult;
    fn remove_affidavit(who: &Author) -> DispatchResult;
    fn clear_affidavits();

    // Provided methods
    fn process_affidavit(who: &Author) -> DispatchResult { ... }
    fn on_submit_affidavit(_who: &Author, _affidavit: &ElectionWeight) { ... }
}

Defines the behavior for author affidavits - self-declared affirmations of election weights during a given cycle.

Concept

Affidavits represent an author’s own self-declaration of their election weight (e.g., performance, stake, or participation value) for the current election cycle. They are not requested or enforced by the system; instead, they are voluntarily submitted by the authors themselves.

These affidavits are ephemeral:

• Stored temporarily for the next (upcoming) election cycle.
• Must be cleared once the cycle ends or after all have been processed.
• Can later be used by external modules (e.g., SessionManager) to inform election outcomes or validations.

Responsibilities

This trait defines:

• Submission and validation of author affidavits.
• Storage and retrieval of ephemeral affidavit data.
• Lifecycle management (generation, existence check, removal, clearing).

Type Parameters

• Author: Entity submitting the affidavit (e.g., validator, collator, consortium-roles, etc).
• ElectionWeight: The numeric or structured weight being affirmed. Requires Ord.

Required Methods

fn can_submit_affidavit(who: &Author) -> DispatchResult

Determines whether an author is eligible to submit an affidavit for the next election cycle.

Implementations should define conditions such as:

• Whether the author can be part of the next election round.
• Whether the submission window is still open.
• Whether the author already submitted.

fn affidavit_exists(who: &Author) -> DispatchResult

Checks whether an affidavit currently exists for the given author.

Returns

• Ok(()) if exists.
• Err(DispatchError) if not or on query failure.

fn get_affidavit(who: &Author) -> Result<ElectionWeight, DispatchError>

Retrieves the stored affidavit for a given author.

Used only for external queries to fetch the most recent submitted affidavit.

Should not be used internally during submission or processing of a single affidavit.

fn gen_affidavit(who: &Author) -> Result<ElectionWeight, DispatchError>

Generates a new affidavit (i.e., computes or constructs an election weight) for the given author.

Typically derived from the author’s participation or other context-dependent metrics in the current cycle.

Note: This may produce a different value than any previously submitted affidavit.

Returns

• Ok(ElectionWeight) if generation is successful.
• Err(DispatchError) if generation fails.

fn submit_affidavit(who: &Author, affidavit: &ElectionWeight) -> DispatchResult

Submits an affidavit for the author for the next election cycle.

Parameters

• who: Author submitting the affidavit.
• affidavit: The generated election weight for submission.

fn remove_affidavit(who: &Author) -> DispatchResult

Removes a stored affidavit for the given author.

Typically invoked by external modules to remove an affidavit before processing the collected affidavits for a cycle.

Pre- or post-processing removal is allowed, as appropriate.

fn clear_affidavits()

Clears all affidavits for the current election cycle.

Should be called once all affidavits have been processed or validated, ensuring that new cycles start with a clean state.

Provided Methods

fn process_affidavit(who: &Author) -> DispatchResult

Processes the full lifecycle of an affidavit submission for a given author for the next election cycle.

This is the entry point for submitting an affidavit.
Workflow:

1. Check if the author can submit (Self::can_submit_affidavit).
2. Generate the author’s affidavit (Self::gen_affidavit).
3. Submit the affidavit (Self::submit_affidavit) with the generated weight.
4. Trigger optional post-submission hook (Self::on_submit_affidavit).

fn on_submit_affidavit(_who: &Author, _affidavit: &ElectionWeight)

Hook triggered after a successful affidavit submission.

Allows external logic, e.g., logging, reward triggers, or cross-pallet coordination.

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