Struct TryElection

pub(crate) struct TryElection<T: Config> {
    pub by: T::Public,
    pub at: BlockNumberFor<T>,
}

Operational context for election transaction execution.

This type represents the contextual information required to attempt authors election using an affidavit key during the routine lifecycle.

Election attempts are optimistic, sequential routines that may execute repeatedly as part of a looped execution model (e.g. via offchain workers). Although election typically follows the affidavit declaration phase, explicit looping of sequential routines allows this phase to run earlier. The routine remains safe, as successful election is gated by retrievable storage state, election window constraints, and eligibility checks.

Notes

• This is not a transaction payload.
• This type is never submitted on-chain.
• It is used internally during:
  • fetching the active-tagged affidavit key (storage-reference + keystore-pair)
  • election payload signing using the affidavit key pair
  • submission of the elect extrinsic
  • retry-driven OCW election execution

Fork Awareness

• The at field captures the block number at which the election attempt begins.
• When executed via offchain workers, this context must tolerate forks, re-orgs, and speculative execution.
• Implementors are responsible for ensuring idempotency and re-entrancy safety.

Dependency: InitAffidavitKey

This routine depends on the affidavit key initialization phase. It assumes that a active-tagged (offchain storage referenced) affidavit key and its pair in crypto-store is available. Whenever this invariant is violated (e.g. missing key, failed signing, or inconsistent state), control is redirected to InitAffidavitKey to repair and re-validate the key before retrying the election attempt.

Election Flow

The routine fetches the active-tagged affidavit key-pair (referenced via offchain storage and retrieved through local keystore), then attempts author election. It short-circuits when outside the election window, when ineligible, or when already elected (to avoid redundancy). Failures or inconsistencies re-enter the affidavit initialization phase for re-validation and repair.

loop {
    // Ensure active-tagged affidavit key is available
    InitAffidavitKey::ensure_active_affidavit_key();

    // Fetch affidavit key pair (offchain storage reference + keystore-pair)
    let key_pair = fetch_affidavit_key_pair();

    if !within_election_window()
        || !eligible_to_elect()
        || already_elected()
    {
        break; // proceed to declaration phase (no election required)
    }

    let payload = Default::default();

    match sign_payload_with(key_pair)
        .and_then(|payload| submit_elect_authors_extrinsic(payload))
    {
        Ok(_) => break,     // elect-phase completed successfully
        Err(_) => continue, // retry via initialization phase again
    }
}

Guarantees

This routine proceeds to the affidavit declaration phase under exactly two conditions:

1. Initialization-only path: a active-tagged affidavit key-pair exists, but election constraints are not satisfied (outside window, ineligible, or already elected).

2. Election-complete path: a active-tagged affidavit key-pair exists, election constraints are satisfied, and the elect extrinsic is successfully submitted.

In all other cases, the routine retries by re-entering the affidavit key initialization phase to re-validate offchain storage and keystore consistency.

All behavior is supplied by trait implementations operating on this type.

FlowChart

Fields

by: T::Public

Public key authorized to sign election transactions.

at: BlockNumberFor<T>

Block number at which election execution is initiated.

Trait Implementations

impl<T: Clone + Config> Clone for TryElection<T>

where T::Public: Clone,

fn clone(&self) -> TryElection<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for TryElection<T>

where T: Debug + Config,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Config> Decode for TryElection<T>

where T::Public: Decode, BlockNumberFor<T>: Decode,

fn decode<__CodecInputEdqy: Input>( __codec_input_edqy: &mut __CodecInputEdqy, ) -> Result<Self, Error>

Attempt to deserialise the value from input.

fn decode_into<I>( input: &mut I, dst: &mut MaybeUninit<Self>, ) -> Result<DecodeFinished, Error>

where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory.

fn skip<I>(input: &mut I) -> Result<(), Error>

where I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl<T: Config> Encode for TryElection<T>

where T::Public: Encode, BlockNumberFor<T>: Encode,

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode_to<__CodecOutputEdqy: Output + ?Sized>( &self, __codec_dest_edqy: &mut __CodecOutputEdqy, )

Convert self to a slice and append it to the destination.

fn encode(&self) -> Vec<u8>

Convert self to an owned vector.

fn using_encoded<R, F>(&self, f: F) -> R

where F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl<T: Config> MaxEncodedLen for TryElection<T>

where T::Public: MaxEncodedLen, BlockNumberFor<T>: MaxEncodedLen,

fn max_encoded_len() -> usize

Upper bound, in bytes, of the maximum encoded size of this item.

impl<T: PartialEq + Config> PartialEq for TryElection<T>

where T::Public: PartialEq,

fn eq(&self, other: &TryElection<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Config> RoutineOf<<T as SigningTypes>::Public, <<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for TryElection<T>

Authorization layer for the election execution routine.

This implementation resolves the affidavit public key authorized to run the election flow. It deliberately reuses the key-resolution logic from DeclareAffidavit to enforce strict lifecycle ordering:

Affidavit Declaration -> Key Rotation -> Election

By delegating authorization instead of duplicating it, this layer guarantees that elections are executed only by authors who have successfully completed the affidavit and key-rotation process.

fn who(at: &BlockNumberFor<T>) -> Result<T::Public, Self::Logger>

Determines the affidavit public key authorized to run the election routine.

Semantics

• Reuses the currently active affidavit key resolved by DeclareAffidavit.
• Ensures that election execution is authorized by the same operational key that is eligible for affidavit declaration.

Rationale

Elections are permitted only after a successful affidavit declaration and key-rotation cycle. By delegating to DeclareAffidavit::who, this routine enforces a strict lifecycle ordering without duplicating key-resolution logic.

Key Resolution Note

Although this appears syntactically as the active affidavit key, it semantically represents the recently rotated next affidavit key that was promoted to active status by the previous OCW execution’s final routine (RotateAffidavitKey).

impl<T: Config> Routines<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for TryElection<T>

Offchain routine responsible for opportunistic election execution.

This routine attempts to submit the elect extrinsic for the upcoming session using the currently active affidavit key.

It is intentionally designed to be:

• Non-blocking: exits silently when prerequisites are unmet.
• Idempotent: safe to run repeatedly across blocks and forks.
• Pre-emptive: elections may be attempted before the OCW pipeline fully converges, succeeding in later executions.

The routine participates in the OCW execution pipeline:

InitAffidavitKey -> TryElection -> DeclareAffidavit -> RotateAffidavitKey

and relies on repeated OCW invocations to eventually satisfy all temporal and state-dependent constraints.

fn can_run(&self) -> Result<(), Self::Logger>

Checks whether an election can be processed in the current block.

Semantics

• Delegates election window validation to ElectAuthors::can_process_election.
• Does not treat an unavailable election window as an error.

Behavior

• If the election window is not open, the routine exits early with an informational log.
• Hard failures (e.g. invalid configuration) are surfaced as logged errors.

This design allows the OCW orchestrator to continue executing subsequent routines (e.g. affidavit declaration) in the same block.

fn run_service(&self) -> Result<(), Self::Logger>

Attempts to submit the election transaction for the upcoming session.

Execution Strategy

This routine is opportunistic and non-blocking:

• If the election window is not open, execution passes silently to next routine.
• If the author is not eligible, execution exits silently.
• If the author already acted as the election runner, execution exits silently.

This behavior is intentional and allows the OCW pipeline to be orchestrated in the following order:

InitAffidavitKey -> TryElection -> DeclareAffidavit -> RotateAffidavitKey

Elections are therefore attempted pre-emptively and may succeed in a later OCW invocation once all prerequisites converge.

Semantics

• Uses the currently active affidavit key to authorize the election.
• Submits an unsigned elect extrinsic signed offchain.
• Ensures that each author runs the election at most once per session.

Failure Handling

• All signing or submission failures are logged as errors.
• No retries are attempted in the same block.
• Subsequent OCW executions may retry automatically.

fn on_ran_service(&self)

Logs a info message on a successful TryElection routine.

impl<T> TypeInfo for TryElection<T>

where T::Public: TypeInfo + 'static, BlockNumberFor<T>: TypeInfo + 'static, T: Config + 'static,

type Identity = TryElection<T>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl<T: Config> EncodeLike for TryElection<T>

where T::Public: Encode, BlockNumberFor<T>: Encode,

impl<T: Eq + Config> Eq for TryElection<T>

where T::Public: Eq,

impl<T: Config> StructuralPartialEq for TryElection<T>