Struct InitAffidavitKey

pub(crate) struct InitAffidavitKey<T: Config> {
    pub at: BlockNumberFor<T>,
}

Operational context for affidavit key initialization.

This type represents the contextual information required to initialize or recover an affidavit key during the key lifecycle.

Affidavit keys are ephemeral, operational keys that are rotated independently of long-term authority, stash, or consensus keys. Initialization may execute sequentially multiple times as a looped routine (e.g. via offchain workers), and therefore requires an explicit, lightweight context object.

Notes

• This is not a transaction payload.
• This type is never submitted on-chain.
• It is used internally during:
  • affidavit key generation
  • key recovery
  • keystore initialization or repair

Fork Awareness

• The at field captures the block number at which the initialization process 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.

Initialization Flow

The process repeatedly attempts to resolve a affidavit key-pair. It self-heals by creating and inserting keys when missing, and retries on missing or error states until a consistent state is reached.

Pseudocode

loop {
    // Fetch the tagged active affidavit from offchain storage
    match offchain_storage.fetch_active_affidavit() {
        Ok(None) => {
            // No active-tagged affidavit-key exists -> create a new key-pair locally
            keystore.create_affidavit_key();

            // Publish the key reference to offchain storage
            offchain_storage.insert_affidavit_key();
            continue;
        }
        Ok(Some(affidavit)) => {
            // A active-tagged affidavit exists -> ensure the local key-pair is present
            match keystore.get_affidavit_key() {
                Some(key) => break key,
                None => {
                    // Storage provided public key, but its actual key-pair
                    // is missing locally -> repair
                    keystore.create_affidavit_key();
                    continue;
                }
            }
        }
        Ok(Some(_other_status)) => continue,
        Err(_storage_error) => continue, // transient storage error -> retry
    }
}

Guarantee

This process yields an active affidavit key only when its tagged/referenced via an offchain storage and its corresponding the key-pair exists in the local keystore. Otherwise, it creates/repairs the key and keeps retrying until the affidavit becomes tagged and the keystore is consistent.

loop {
    if offchain_storage.has_affidavit_key()
        && keystore.has_affidavit_key()
    {
        break;
    }

    keystore.create_or_repair_affidavit_key();
    offchain_storage.ensure_affidavit_key_reference();
    // retry until next key reaches consistency
}

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

FlowChart

Fields

at: BlockNumberFor<T>

Block number at which affidavit key initialization begins.

Used for logging, diagnostics, and fork-aware coordination.

Trait Implementations

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

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

where 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 InitAffidavitKey<T>

where 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<__CodecOutputReturn, __CodecUsingEncodedCallback: FnOnce(&[u8]) -> __CodecOutputReturn>( &self, f: __CodecUsingEncodedCallback, ) -> __CodecOutputReturn

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> FinalizedOffchainStorageError<T, <T as Config>::AccountId> for InitAffidavitKey<T>

Invariant enforcement for finalized offchain storage.

This implementation defines errors for high-level coordination failures between speculative and persistent storage layers.

Cleanups will be implicitly handled by the storage itself.

fn hanging_hash() -> Self::Error

A speculative hash must not exist without a corresponding persistent value.

fn hanging_value() -> Self::Error

A persistent value must not exist without holding its corresponding speculative hash’s value.

type Error = Error<T>

Concrete error type chosen by the caller.

impl<T: Config> FinalizedPolicy<T> for InitAffidavitKey<T>

This policy defines when a finalized offchain storage value is considered safe for irreversible side effects, such as:

• key promotion,
• state transitions,
• or cleanup of speculative storage.

The policy is consumed by the Finalized storage abstraction in conjunction with Confidence to determine optimal-finality.

fn finality_after() -> <T as Config>::Moment

Returns the wall-clock time after which a value is considered final.

fn finality_ticks() -> BlockNumberFor<T>

Returns the number of block confirmations required to reach finality after the wall-clock time reached.

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

where BlockNumberFor<T>: MaxEncodedLen,

fn max_encoded_len() -> usize

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

impl<T: Config> OffchainStorageError<ForkAware<T, ValueHash, InitAffidavitKey<T>, Pallet<T>>> for InitAffidavitKey<T>

Error mapping for fork-aware speculative storage access during affidavit key initialization.

This implementation provides pallet-specific error variants expected to be convertible into DispatchError.

Scope

• Applies to speculative, fork-aware storage keyed by a hash.
• Focuses on failures related to the speculative hash of the finalized affidavit key value.

fn decode_failed() -> Self::Error

Speculative hash decoding failed.

fn concurrent_mutation() -> Self::Error

Concurrent mutation detected while accessing fork-aware storage.

type Error = Error<T>

Caller-defined error type used for storage failures.

impl<T: Config> OffchainStorageError<Persistent<T, Ledger<T, <T as Config>::AccountId>, InitAffidavitKey<T>>> for InitAffidavitKey<T>

Error mapping for persistent finalized offchain storage during affidavit key initialization.

This implementation handles failures when interacting with the persistent ledger that stores finalized affidavit key values, wrapped in Confidence to reflect finality guarantees.

Scope

• Applies to persistent, non-speculative storage.
• Covers decoding and concurrent mutation failures.

fn decode_failed() -> Self::Error

Finalized value decoding failed.

fn concurrent_mutation() -> Self::Error

Concurrent mutation detected while accessing persistent storage.

type Error = Error<T>

Caller-defined error type used for storage failures.

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

fn eq(&self, other: &InitAffidavitKey<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> Routines<<<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for InitAffidavitKey<T>

An Offchain Worker (OCW) routine responsible for initializing the active affidavit key for the local node.

This routine bootstraps an affidavit application key per node, regardless of whether the node is acting as an author i.e., validator node.

The affidavit key is a rotated operational key used exclusively for affidavit-related signing. Only a single affidavit key is expected to be active at any given time, and the runtime relies on this invariant being upheld.

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

Determines whether the affidavit key initialization routine should run.

Initialization must not run if:

• an active affidavit key is already stored in the offchain storage, and
• the corresponding key pair exists in the node’s affidavit keystore (app crypto).

Any storage inconsistency (e.g. corrupted or undecodable data) is treated as a hard stop and causes the routine to refuse execution, since proceeding could violate runtime expectations.

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

Initializes a new affidavit key pair and marks it as the active affidavit key for the node.

This routine:

1. Generates a new affidavit application key pair in the local keystore.
2. Extracts the public key and derives its corresponding AffidavitId.
3. Stores the public identifier as the active affidavit key in the offchain storage.

Affidavit keys are rotated regularly (e.g. per session). The node’s long-term authority or author role i.e., stash key is never used directly for affidavit signing, reducing operational risk.

If storing the active affidavit key fails, the generated key pair becomes unreachable and is effectively discarded. The routine will retry on subsequent block OCW executions until initialization succeeds.

fn on_ran_service(&self)

Logs a info message on a successful InitAffidavitKey routine.

impl<T> TypeInfo for InitAffidavitKey<T>

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

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

where BlockNumberFor<T>: Encode,

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

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