Struct Finalized

pub struct Finalized<Context, Value, Routine, Handler>(PhantomData<(Value, Context, Routine, Handler)>)
where
    Context: Config,
    Value: Portable,
    Routine: Routines<BlockNumberFor<Context>>,
    Handler: ForksHandler<Context, ForkLocalDepot>;

Marker type for finality-aware offchain storage, combining fork-aware and persistent state to derive confidence-graded values via routine-defined policies and observations.

Intended for Substrate FRAME-based runtimes only.

The Finalized storage model:

• records values speculatively using fork-aware storage,
• tracks historical observations in persistent storage,
• and exposes values only after evaluating time and observation-based finality guarantees.

Finality is determined by:

• a wall-clock time window (see FinalizedPolicy),
• and repeated successful observations.

This marker is used to specialize KeyValueStore implementations that combine ForkAware and Persistent storage to provide confidence-graded values (see Confidence).

Behavioral contract

Any routine using Finalized storage must provide error policies for the exact internal storage forms used by this model via OffchainStorageError:

• ForkAware<Context, ValueHash, Routine>, which stores speculative fork-local identity using ValueHash, and
• Persistent<Context, Ledger<Context, Moment<Context>, Value>, Routine>, which stores the persistent observation ledger using Ledger and wall-clock Moment.

In addition, the routine must define:

• a FinalizedPolicy describing when a value becomes stable, and
• FinalizedOffchainStorageError values for finality-specific invariant violations.

Together, these requirements ensure that:

• fork-aware and persistent state remain consistent,
• semantic invariants are enforced at a single, centralized layer,
• and all failures are surfaced as caller-defined error signals and logged exactly once.

Value-first semantics

This storage model is value-first: confidence is tied to the observed value, not just the key. If the same value is inserted again for the same key, its accumulated confidence is reset, as the insertion is treated as a fresh observation sequence.

Callers are therefore responsible for deciding whether repeated insertions of the same value are semantically meaningful. To avoid unintended confidence resets, routines should refrain from inserting identical values multiple times unless a reset is explicitly desired.

Timestamp semantics

All logging and routine behavior associated with this storage model is explicitly bound to block numbers via [BlockNumberFor<Context>]. This type does not accept a generic timestamp parameter.

Wall-clock time, when required for finality evaluation, is obtained explicitly from [pallet_timestamp].

Type parameters

• Context: The active runtime type (i.e. a type implementing [frame_system::Config]). This binds the storage model to a specific runtime configuration.
• Value: The value type whose finality is being tracked.
• Routine: A routine type implementing Routines parameterized by [BlockNumberFor<Context>], allowing logging, error handling, policy evaluation, and invariant enforcement to be specialized at the type level.
• Handler: A type implementing ForksHandler using ForkLocalDepot that manages the fork graph and scope tracking for this storage backend.

This type is a marker only and carries no runtime data.

Tuple Fields

0: PhantomData<(Value, Context, Routine, Handler)>

Trait Implementations

impl<Context, Value, Routine, Handler> Clone for Finalized<Context, Value, Routine, Handler>

where Context: Config + Clone, Value: Portable + Clone, Routine: Routines<BlockNumberFor<Context>> + Clone, Handler: ForksHandler<Context, ForkLocalDepot> + Clone,

fn clone(&self) -> Finalized<Context, Value, Routine, Handler>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Context, Value, Routine, Handler> Debug for Finalized<Context, Value, Routine, Handler>

where Context: Config + Debug, Value: Portable + Debug, Routine: Routines<BlockNumberFor<Context>> + Debug, Handler: ForksHandler<Context, ForkLocalDepot> + Debug,

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

Formats the value using the given formatter.

impl<T, Value, Routine, Handler> KeyValueStore<Value, <<<T as Config>::Block as HeaderProvider>::HeaderT as Header>::Number> for Finalized<T, Value, Routine, Handler>

where T: Config, Value: Portable, Routine: FinalizedOffchainStorageError<T, Value> + FinalizedPolicy<T> + OffchainStorageError<Persistent<T, Ledger<T, Value>, Routine>> + OffchainStorageError<ForkAware<T, ValueHash, Routine, Handler>> + Routines<BlockNumberFor<T>>, Handler: ForksHandler<T, ForkLocalDepot> + Logging<BlockNumberFor<T>, Level = LogLevel, Logger = DispatchError>,

KeyValueStore implementation for Finalized storage semantics.

This implementation materializes the behavioral contract defined by Finalized by combining:

• fork-aware storage for speculative state,
• persistent storage for observation history,
• and routine-defined policies for finality evaluation and error signaling.

The required bounds ensure that the routine:

• defines when a value becomes stable (FinalizedPolicy),
• provides caller-defined error signals for finality invariants (FinalizedOffchainStorageError),
• and supplies OffchainStorageError error policies for the exact storage forms used internally by this model for:
  • [ForkAware<.., ValueHash, ..>] using ValueHash, and
  • [Persistent<.., Ledger<...>, ..>] using Ledger.

This guarantees that all storage failures and semantic violations are surfaced consistently as caller-defined errors and are logged exactly once at the correct abstraction layer.

type Key = [u8]

Keys are raw byte slices; allows flexible usage for any encoded identifier.

type Value = Confidence<Value>

Return value type used when querying a key.

The value is wrapped in Confidence, representing a confidence signal derived from the Finalized storage model rather than a definitive truth or on-chain finality.

fn insert( key: &Self::Key, value: &Value, target: Option<&str>, fmt: Option<LogFormatter<BlockNumberFor<T>, Self::Level>>, ) -> Result<(), Self::Logger>

Inserts a value speculatively under finality-aware semantics.

This operation:

• computes a stable ValueHash for fork-independent identity,
• records the hash in fork-aware storage (speculative marker),
• and inserts or updates an Observation in the persistent ledger.

No confidence is implied by insertion alone; this operation only records existence and initializes observation tracking.

fn get( key: &Self::Key, target: Option<&str>, fmt: Option<LogFormatter<BlockNumberFor<T>, Self::Level>>, ) -> Result<Option<Confidence<Value>>, Self::Logger>

Reads the value associated with the current fork and derives the value wrapped in a Confidence signal.

Returned signals:

• Confidence::Unsafe - finality window not elapsed.
• Confidence::Risky - time elapsed, insufficient block observations.
• Confidence::Safe - time and observation thresholds satisfied.

Any detected invariant violation (for example, a fork-aware hash without a ledger entry) is logged and cleaned up automatically.

fn remove( key: &Self::Key, target: Option<&str>, fmt: Option<LogFormatter<BlockNumberFor<T>, Self::Level>>, ) -> Result<Option<Value>, Self::Logger>

Removes the value associated with the current fork.

Removal semantics:

• The fork-aware marker is always removed first.
• The corresponding persistent ledger entry is removed next.
• The ledger itself is deleted if it becomes empty.

This ensures no semantic or historical state is left behind once the value is no longer relevant.

fn mutate<F>( key: &Self::Key, f: F, target: Option<&str>, fmt: Option<LogFormatter<BlockNumberFor<T>, Self::Level>>, ) -> Result<(), Self::Logger>

where F: FnOnce(Result<Option<Value>, Self::Logger>) -> Result<Value, Self::Logger>,

Mutates the value associated with a key under finality-aware semantics.

The closure f receives the current value, if any, and must return a new value to replace it.

Replacing a value resets all finality observations: the new value is treated as freshly observed and must re-accumulate confidence.

The update is scoped to the current fork and preserves all storage invariants. Any detected invariant violation is logged once and cleaned up automatically before the error is returned.

impl<Context, Value, Routine, Handler> Copy for Finalized<Context, Value, Routine, Handler>

where Context: Config + Copy, Value: Portable + Copy, Routine: Routines<BlockNumberFor<Context>> + Copy, Handler: ForksHandler<Context, ForkLocalDepot> + Copy,