Struct RotateAffidavitKey

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

Operational context for affidavit key rotation.

This type represents the contextual information required to observe and commence rotation of the affidavit key, promoting the previously prepared next key to become the active affidavit key once the declaration effects are finalized.

Rotation is a sequential, retry-driven routine that executes as part of the looped offchain workflow. It is entered only after the declaration phase has submitted the declare-affidavit transaction successfully.

Notes

• This is not a transaction payload.
• This type is never submitted on-chain.
• It is used internally during:
  • observation of finalized declaration effects
  • validation of next-key availability
  • promotion of the next affidavit key to active
  • reset of inconsistent key state when rotation cannot proceed

Dependency: InitAffidavitKey, TryElection, and DeclareAffidavit

This routine depends on the prior initialization, election, and declaration phases. It assumes that:

• a active-tagged affidavit key-pair exists (guaranteed by InitAffidavitKey),
• election has either completed or been safely skipped (handled by TryElection),
• a declare-affidavit transaction has been submitted (by DeclareAffidavit).
• and a next-tagged affidavit key-pair exists,

Whenever these invariants are violated (e.g. missing affidavit keys, eligibility failure, or window violations), control is redirected to InitAffidavitKey to repair and re-validate storage and keystore consistency before retrying rotation observation.

Fork Awareness

• The at field captures the block number at which rotation observation begins.
• When executed via offchain workers, this context must tolerate forks, re-orgs, and speculative execution.
• Implementors must ensure idempotency and re-entrancy safety.

Rotation Flow

The routine verifies that the next affidavit key is referenced in offchain storage and locally available as pair in keystore, then determines whether rotation is currently eligible. If so, the next key is promoted to active and the previous state is cleaned up. If rotation cannot occur within the allowed session window, both active and next keys are reset to recover from inconsistent or stale state.

Failures or inconsistencies at any stage re-enter the initialization phase to re-validate offchain storage and keystore invariants.

loop {
    // --- Initialization Phase ---
    if !offchain_storage.has_active_affidavit_key()
        || !keystore.has_active_affidavit_key()
    {
        keystore.create_or_repair_active_key();
        offchain_storage.ensure_active_key_reference();
        continue;
    }

    // --- Election Phase (optimistic) ---
    if election_constraints_satisfied() {
        if submit_elect_authors_extrinsic().is_err() {
            continue; // repair + retry via initialization
        }
    }

    // --- Declaration Phase ---
    if !offchain_storage.has_next_affidavit_key()
        || !keystore.has_next_affidavit_key()
    {
        match keystore.create_or_repair_next_key() {
            Ok(_) => {
                offchain_storage.ensure_next_key_reference();
                continue;
            }
            Err(_) => continue, // fallback to initialization repair loop
        }
    }

    if !affidavit_constraints_satisfied() {
        continue; // retry via initialization phase
    }

    if submit_declare_affidavit_extrinsic().is_err() {
        continue; // declaration failed -> repair + retry
    }

    // --- Rotation Observation Phase ---
    if !offchain_storage.has_next_affidavit_key()
        || !keystore.has_next_affidavit_key()
    {
        continue;
    }

    if eligible_to_rotate() {
        promote_next_key_to_active();
        remove_next_key();
        break; // rotation completed
    }

    if within_current_session_window() {
        continue; // wait until rotation becomes eligible
                  // indicates declaration effects are not finalized
    }

    // Window expired -> reset inconsistent state
    remove_active_and_next_affidavit_keys();
    break;
}

Guarantee

The rotation phase has exactly three exit outcomes:

1. Rotation Success:

   • if the next affidavit key is finalized and present in the keystore, and
   • rotation eligibility constraints are satisfied, then the next key is promoted to become the active affidavit key.

2. Deferred Rotation (Same Session):

   • if the next affidavit key is finalized but not yet eligible to rotate, and
   • the current session window in which the affidavit was declared is still active, the routine keeps retrying until eligibility is satisfied and rotation succeeds.

3. Reset & Repair (Session Elapsed):

   • if rotation is still ineligible and the declaring session window has elapsed, both active and next affidavit keys are removed, signaling that the declaration phase effectively failed to converge. The global loop then re-enters the initialization phase to repair and re-establish a consistent state.

loop {

    if eligible_to_rotate() {
        promote_next_key_to_active();
        remove_next_affidavit_key();
        break;
    }
    if within_declaring_session_window() {
        continue;
        // keep retrying until eligibility becomes true
    } else {
        remove_active_and_next_affidavit_keys();
        break;
        // signal reset; initialization phase will repair state
    }
}

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

Timelines & Window Semantics

The global retry loop operates over session-scoped time windows that determine when election, declaration, and rotation are allowed.

Timeline within a single session:

|--------------------- Session N ---------------------|
       |--------- Affidavit Window ---------|
                |----- Election Window -----|

Session Start
    |- Affidavit window opens
         |- Election window opens (nested inside affidavit window)

Election window closes
    |- Election no longer allowed

Affidavit window closes
    |- Declaration and rotation eligibility must already be satisfied

Session ends -> Session N+1 begins
    |- Global loop continues with fresh window constraints

Properties:

• The election window is strictly nested within the affidavit window.
• When the affidavit window ends, the election window has already ended.
• Rotation eligibility is evaluated relative to the session in which the affidavit was declared.
• If rotation has not converged before the session window elapses, the routine resets keys and relies on the next session’s loop iteration to re-initialize and re-attempt the full lifecycle.

FlowChart

Fields

by: T::Public

Public key that is intended to become the new active affidavit key.

at: BlockNumberFor<T>

Block number at which key rotation is initiated.

Trait Implementations

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

where T::Public: Clone,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for RotateAffidavitKey<T>

where T: Debug + Config,

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

Formats the value using the given formatter.

impl<T: Config> Decode for RotateAffidavitKey<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 RotateAffidavitKey<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 RotateAffidavitKey<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 RotateAffidavitKey<T>

where T::Public: PartialEq,

fn eq(&self, other: &RotateAffidavitKey<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 RotateAffidavitKey<T>

Authorization layer for affidavit key rotation.

Resolves the finalized next affidavit key prepared by DeclareAffidavit and ensures it is locally usable for signing.

This enforces that rotation is performed only with a key that:

• has reached finality, and
• exists in the node’s keystore.

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

Determines the next affidavit public key authorized to finalize key rotation.

Semantics

• Resolves the next affidavit key previously prepared and finalized by the DeclareAffidavit routine.
• Requires the key to be in a Confidence::Safe state, ensuring it has survived fork re-orgs and met finality requirements.

Lifecycle position

Reaching this routine implies:

• The declare extrinsic has already been submitted, and
• The node is now waiting to observe whether that transaction has been accepted and reflected in runtime storage.

This routine therefore does not generate or mutate keys. It only:

• re-reads the finalized next affidavit key, and
• verifies that the corresponding key pair still exists in the local keystore.

Failure semantics

• Missing or non-finalized next affidavit key is treated as a hard stop.
• Storage inconsistencies indicate OCW coordination failure and halt execution.
• If the key exists in storage but not in the keystore, the node is considered misconfigured.

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

Offchain routine responsible for finalizing affidavit key rotation.

Completes the lifecycle by promoting the finalized next affidavit key to active status once the runtime reflects successful affidavit submission.

This routine:

• waits for on-chain confirmation of the rotated key,
• performs a safe transition from next -> active key,
• resets state on failure to avoid inconsistent lifecycle progression.

Designed to be idempotent and driven by repeated OCW execution.

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

Determines whether affidavit key rotation may be finalized.

Semantics

• Checks whether the next affidavit key has been successfully registered in runtime storage for the session after next (current_session + 2) (for which next election will be conducted).
• Presence of this key in AffidavitKeys is treated as confirmation that the declare extrinsic was accepted.

Waiting behavior

• If the key is not yet visible, the routine waits passively.
• While the affidavit window is still open, this is logged as an informational “awaiting status” condition.

Failure and recovery

If the affidavit window has closed and:

• the next affidavit key is still not registered, then
• the system assumes the affidavit transaction failed or was dropped.

In that case:

• All affidavit-related offchain state is cleared.
• Active validation is considered stopped.
• The node must restart the lifecycle via validate extrinsic in a later block.

This aggressive reset prevents the OCW from getting stuck in a half-rotated or inconsistent state.

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

Finalizes affidavit key rotation after successful affidavit acceptance.

Behavior

Once the runtime reflects the rotated affidavit key:

1. The next affidavit key is removed from finalized offchain storage.
2. The active affidavit key is updated to the rotated key.

This completes the affidavit lifecycle for the current session and enables subsequent OCW executions to:

• attempt elections via TryElection, and
• later begin a new affidavit cycle.

Guarantees

• Rotation is performed exactly once per successful affidavit.
• Any storage failure is treated as a coordination halt.

fn on_ran_service(&self)

Logs a info message on a successful RotateAffidavitKey routine.

impl<T> TypeInfo for RotateAffidavitKey<T>

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

type Identity = RotateAffidavitKey<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 RotateAffidavitKey<T>

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

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

where T::Public: Eq,

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