Struct DeclareAffidavit

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

Operational context for affidavit declaration and key rotation.

This type represents the contextual information required to declare an affidavit using the active affidavit key and rotate it to the next key during the routine lifecycle.

Declaration is a sequential, retry-driven routine that executes as part of the looped offchain workflow. It is entered only after the initialization phase guarantees that a active-tagged affidavit key-pair is available, and after the election phase has either completed successfully or been safely skipped due to unmet constraints.

Notes

• This is not a transaction payload.
• This type is never submitted on-chain.
• It is used internally during:
  • next affidavit key resolution
  • declaration payload composition (including next public key for rotation)
  • payload signing using the active affidavit key-pair
  • submission of the declare-affidavit extrinsic

Dependency: InitAffidavitKey and optimistic TryElection

This routine has a hard dependency on the initialization phase and a soft (optimistic) dependency on the election phase.

It requires that:

• a active-tagged affidavit key exists in offchain storage and the its key-pair in local keystore (guaranteed by InitAffidavitKey), and
• election has either completed successfully or has been safely skipped due to unmet constraints.

Election may execute before declaration as part of the global retry loop, but its outcome does not directly gate declaration correctness. However, failures during election invalidate system invariants and therefore redirect control back to InitAffidavitKey for repair and re-validation before declaration is retried.

Fork Awareness

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

Declaration Flow

The routine fetches the active-tagged affidavit key-pair, resolves the next affidavit key (mirroring the affidavit-key-initialization logic), verifies the declaration window and eligibility, composes the declaration payload along with the next affidavit public key, signs it with the active affidavit key-pair, and submits the declaration transaction to rotate the active affidavit key to next affidavit key.

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

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

    // Fetch affidavit key pair (offchain storage reference + keystore-pair)
    let key_pair = fetch_affidavit_key_pair();
    // Attempt election optimistically; failure requires repair + retry
    if TryElection::attempt_election_if_applicable().is_err() {
        continue; // re-enter initialization phase
    }

    // Resolve next affidavit key using the offchain-storage references +
    // keystore pair consistency guarantees as InitAffidavitKey
    if !offchain_storage.has_next_affidavit_key()
        || !keystore.has_next_affidavit_key()
    {
        keystore.create_or_repair_next_affidavit_key();
        offchain_storage.ensure_next_affidavit_key_reference();
        continue; // retry until next key reaches consistency
    }

    let next_key_to_rotate = fetch_next_affidavit_key();

    if !within_affidavit_window() || !eligible_to_declare() {
        continue; // retry via initialization phase
    }

    let payload = compose_declare_affidavit_payload(next_key_to_rotate);

    match sign_payload_with(key_pair)
        .and_then(|payload| submit_declare_affidavit_extrinsic(payload)) {
        Ok(_) => break,     // declaration + rotation completed
        Err(_) => continue, // retry via initialization phase
    }
}

Guarantee

This routine declares the affidavit and rotates the active key only when:

• a active-tagged affidavit key-pair is available,
• the next affidavit key is initiated and present in the local keystore,
• declaration window and eligibility constraints are satisfied,
• and the declaration transaction is successfully submitted.

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

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

FlowChart

Fields

by: T::Public

Raw application public key identifying the affidavit key-pair in the local keystore.

at: BlockNumberFor<T>

Block number at which the affidavit declaration process started.

Used exclusively for logging and diagnostic purposes.

Trait Implementations

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

where T::Public: Clone,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for DeclareAffidavit<T>

where T: Debug + Config,

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

Formats the value using the given formatter.

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

Finality-specific invariant errors for the next affidavit key.

These errors are emitted when semantic inconsistencies are detected between fork-aware and persistent storage layers.

Such conditions indicate partial or invalid state, and the storage layer automatically performs cleanup before returning these errors.

fn hanging_hash() -> Self::Error

Emitted when a speculative fork-aware hash exists without a corresponding persistent ledger entry.

fn hanging_value() -> Self::Error

Emitted when persistent storage contains no value corresponding to an existing speculative (fork-aware) hash.

type Error = Error<T>

Concrete error type chosen by the caller.

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

Finality evaluation policy for the next affidavit key.

This implementation reuses the finality parameters defined by InitAffidavitKey, ensuring that both the active and next affidavit keys are evaluated under identical confidence guarantees.

Design Rationale

Every routine that uses Finalized storage:

• must define exactly one finality policy, and
• that policy is scoped to the routine, not to the storage backend.

Since the next affidavit key participates in the same operational lifecycle as the active affidavit key (generation -> observation -> rotation), it is intentionally governed by the same time- and observation-based confidence thresholds.

Invariants

• Finalized storage is strictly constrained:
  • one logical value per routine,
  • one finality policy per value.
• Unlike ForkAware or Persistent storage backends, Finalized does not allow multiple independent values or heterogeneous policies.

Reusing the policy from InitAffidavitKey preserves these invariants while avoiding duplicated configuration and potential divergence.

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

Wall-clock delay required before confidence evaluation begins.

fn finality_ticks() -> BlockNumberFor<T>

Number of block-scoped observations required to reach strong confidence.

impl<T: Config> MaxEncodedLen for DeclareAffidavit<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: Config> OffchainStorageError<ForkAware<T, ValueHash, DeclareAffidavit<T>, Pallet<T>>> for DeclareAffidavit<T>

Error policy for fork-aware speculative storage of the next affidavit key.

This implementation defines how storage-layer failures originating from fork-aware offchain storage are surfaced as routine-specific DispatchError values.

These errors relate exclusively to the speculative identity (ValueHash) used to track the next affidavit key across forks.

Any failure reported here:

• is logged exactly once by the storage layer,
• and returned unchanged to the caller.

fn decode_failed() -> Self::Error

Returned when decoding the speculative hash fails.

Indicates corrupted or unexpected fork-local storage state.

fn concurrent_mutation() -> Self::Error

Returned when a concurrent mutation of the speculative hash is detected.

Indicates overlapping OCW executions or race conditions.

type Error = Error<T>

Caller-defined error type used for storage failures.

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

Error policy for persistent finalized storage of the next affidavit key.

This implementation defines error signaling for failures that occur while interacting with the persistent observation ledger backing the Finalized storage model.

These errors concern the finalized value and its observation history, not speculative fork-local state.

fn decode_failed() -> Self::Error

Returned when decoding the persistent ledger entry fails.

Indicates corrupted or incompatible persisted offchain data.

fn concurrent_mutation() -> Self::Error

Returned when a concurrent mutation of the persistent ledger is detected.

Indicates contention between multiple OCW executions.

type Error = Error<T>

Caller-defined error type used for storage failures.

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

where T::Public: PartialEq,

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

Declares the authorization requirements for the DeclareAffidavit routine.

This implementation specifies who is permitted to execute the routine at a given point in time.

The routine is restricted to the node’s active affidavit key. This ensures that affidavit declarations are signed only by the currently designated, rotated operational key, rather than by long-term authority or stash keys.

The returned T::Public value represents the concrete public key that must be used to sign the affidavit payload at the given block number.

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

Determines which public key is authorized to execute this routine.

Why this check exists

Affidavit declarations are security-sensitive operations. To reduce the blast radius of key compromise and to support regular key rotation, only the currently active affidavit key is permitted to authorize this routine.

The active affidavit key:

• is stored and ensured by Finalized offchain storage,
• is expected to have a corresponding key pair in the node’s keystore,
• and must be explicitly initialized before this routine can run.

Failure semantics

• Any storage inconsistency is treated as a hard error, since it indicates corrupted or unexpected node state.
• If no active affidavit key is configured, the caller is considered misconfigured and execution is refused.
• If the active affidavit key exists but the corresponding key pair is missing from the keystore, execution is refused.

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

Offchain routine responsible for affidavit declaration and preparing key rotation for the next election cycle.

What an affidavit represents

Declaring an affidavit signals that an author:

• is ready to participate in the upcoming election, and
• satisfies all protocol-defined requirements (e.g. backing, support).

An affidavit:

• is submitted via an unsigned extrinsic,
• is allowed only within a bounded affidavit window, and
• is restricted to valid authors holding the correct operational role.

Responsibilities of this routine

This OCW routine performs the offchain coordination required to:

1. Verify that affidavit submission is currently permitted.
2. Ensure a next affidavit key exists and is finalized.
3. Submit the declare extrinsic using the active affidavit key.
4. Attach the next affidavit key for rotation into the upcoming session.

Key separation and security

• Long-term authority / stash keys are never used here.
• All signing is performed using ephemeral affidavit keys managed via application crypto and rotated regularly.
• This minimizes the blast radius of key compromise and enables strict lifecycle enforcement.

Execution model

This routine is designed to be optimistic and non-blocking:

• It may be executed before the node has fully completed validation via validate extrinsic.
• Runtime-side checks ultimately decide whether the extrinsic succeeds.
• Failures are logged and retried automatically in later OCW executions.

This makes the routine safe to run repeatedly without risking inconsistent on-chain state.

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

Determines whether the affidavit declaration routine may proceed.

Semantics

• Ensures that a next affidavit key exists in finalized offchain storage, else initiates and finalizes one.
• Verifies that the current affidavit key is eligible to submit an affidavit in the runtime.

Key handling

• The active affidavit key (self.by) must already exist in the node’s keystore.
• Author primary keys are never consulted.

Optimistic execution

This function may be called before the author has successfully executed the on-chain validate.

That is safe because:

• Runtime-side checks enforce correctness.
• This routine merely prepares and submits the transaction.

If the author has not yet validated their affidavit key on-chain, the submission will be rejected harmlessly.

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

Submits the declare extrinsic.

Preconditions

• The active affidavit key is authorized and present in the keystore.
• The next affidavit key exists and has reached sufficient finality.

Behavior

• Signs the affidavit payload using the current affidavit key.
• Includes the next affidavit key for rotation.
• Submits the extrinsic to the transaction pool.

Important notes

• This routine does not apply any on-chain state changes itself.
• It only submits a transaction; actual effects occur later during block execution.
• Any failure is logged and retried in future OCW runs.

fn on_ran_service(&self)

Logs a info message on a successful DeclareAffidavit routine.

impl<T> TypeInfo for DeclareAffidavit<T>

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

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

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

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

where T::Public: Eq,

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