Trait KeyValueStore

pub trait KeyValueStore<Value, TimeStamp>: Logging<TimeStamp>
where
    TimeStamp: Time,
{
    type Key: Probe + ?Sized;
    type Value: Portable;

    // Required methods
    fn insert(
        key: &Self::Key,
        value: &Value,
        target: Option<&str>,
        fmt: Option<LogFormatter<TimeStamp, Self::Level>>,
    ) -> Result<(), Self::Logger>;
    fn get(
        key: &Self::Key,
        target: Option<&str>,
        fmt: Option<LogFormatter<TimeStamp, Self::Level>>,
    ) -> Result<Option<Self::Value>, Self::Logger>;
    fn remove(
        key: &Self::Key,
        target: Option<&str>,
        fmt: Option<LogFormatter<TimeStamp, Self::Level>>,
    ) -> Result<Option<Value>, Self::Logger>;
    fn mutate<F>(
        key: &Self::Key,
        f: F,
        target: Option<&str>,
        fmt: Option<LogFormatter<TimeStamp, Self::Level>>,
    ) -> Result<(), Self::Logger>
       where F: FnOnce(Result<Option<Value>, Self::Logger>) -> Result<Value, Self::Logger>;
}

Trait for a simple key-value storage with integrated logging.

This trait extends Logging to ensure that any storage operation (insert or get) automatically logs errors in a standardized way.

This is generic over TimeStamp so logs can carry either a block number, system timestamp, or any other type that implements Debug.

Required Associated Types

type Key: Probe + ?Sized

Type of the key, maybe a slice instead of a bounded array.

type Value: Portable

Value of the key.

Required Methods

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

Inserts a value into the store for a given key.

Parameters

• key: The key under which to insert the value.
• value: The value to store.
• target: Optional log target (e.g., "runtime::storage::balances").
• fmt: Optional custom log formatter. If None, the default log format is used.

Returns

• Ok(()) on success.
• Err(Logger) if an error occurs; already logged.

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

Retrieves a value from the store for a given key.

Parameters

• key: The key to look up.
• target: Optional log target (e.g., "runtime::storage::balances").
• fmt: Optional custom log formatter. If None, the default log format is used.

Returns

• Ok(Some(value)) if key exists.
• Ok(None) if key does not exist.
• Err(Logger) if retrieval fails; already logged.

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

Removes the value associated with the given key.

If the key exists, the stored value is removed and returned. If the key does not exist, Ok(None) is returned.

Parameters

• key: The key whose associated value should be removed.
• target: Optional log target (e.g., "runtime::storage::offchain").
• fmt: Optional custom log formatter. If None, the default log format is used.

Returns

• Ok(Some(value)) if the key existed and the value was removed.
• Ok(None) if the key did not exist.
• Err(Logger) if removal fails; already logged.

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

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

Mutates the value associated with the given key.

The mutation closure is invoked with the current value state:

• Ok(Some(value)) if the key exists and the value was successfully read.
• Ok(None) if the key does not exist, allowing the caller to initialize it.
• Err(Self::Logger) if reading or decoding the existing value fails (this error is already logged).

The closure must return a value to be written back to storage. Removal is not supported via this method; use Self::remove explicitly if deletion is required.

Any error returned by the closure (Logging::Logger) must not be logged by the caller. This function will automatically log all errors returned from the closure, ensuring consistent logging behavior.

Parameters

• key: The key whose associated value should be mutated.
• f: A closure that receives the current value state and returns the new value to store, or a domain-level error.
• target: Optional log target for storage-related logs.
• fmt: Optional custom log formatter.

Returns

• Ok(()) if the mutation succeeds.
• Err(Logger) if mutation fails; already logged.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

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

where T: Config, Value: Portable, Routine: OffchainStorageError<Self> + Routines<BlockNumberFor<T>>,

Peristent Offchain Storage Kind/Backend Default KeyValueStore Implementation.

Intended for Substrate FRAME-based runtimes only.

The timestamp type is the runtime’s block number ([BlockNumberFor]), ensuring that all logs are tagged with the block context in which the operation occurred.

type Key = [u8]

type Value = Value

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]

type Value = Confidence<Value>

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

where T: Config, Value: Portable, Routine: OffchainStorageError<Self> + Routines<BlockNumberFor<T>>, Handler: ForksHandler<T, ForkLocalDepot> + Logging<BlockNumberFor<T>, Level = LogLevel, Logger = DispatchError>,

Fork-Aware Offchain Storage Kind/Backend Default KeyValueStore Implementation.

Intended for Substrate FRAME-based runtimes only.

This implementation is backed by fork-aware offchain storage ([StorageValueRef::local]).

The timestamp type is the runtime’s block number ([BlockNumberFor]), ensuring that all logs are tagged with the block context in which the operation occurred.

type Key = [u8]

type Value = Value