Module routines

Best-effort execution framework for offchain routines with explicit logging and storage semantics.

In FRAME, most logic is executed via dispatchable extrinsics or inherents, both of which execute transactionally and revert on failure.

Offchain workers operate outside that model: they run asynchronously, without rollback, and with only best-effort guarantees.

This module introduces routines as a structured way to write such logic, where each routine is context-driven and multiple routines can be composed and executed under best-effort guarantees.

What routines provide

• A disciplined execution model via Routines
• Per-routine semantics, including authorization through RoutineOf and domain-specific error policies
• Composability, allowing multiple routines to run independently under best-effort guarantees

Unlike extrinsics, routines are not atomic. Failures are local and do not prevent other routines from executing.

Logging over rollback

In the absence of transactional guarantees, routines rely on Logging:

• errors are recorded and returned, not used to revert execution
• observability replaces rollback as the primary debugging mechanism

Storage as execution semantics

Routines can integrate with KeyValueStore abstractions backed by offchain storage models such as Persistent, ForkAware, and Finalized.

These make fork behavior explicit and allow safe state handling across re-orgs and repeated execution.

Summary

Routines provide a structured, context-aware model for offchain execution:

• best-effort instead of transactional
• logging-driven instead of rollback-driven
• explicit in both execution and storage semantics

Structs

Finalized

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

ForkAware

Marker type for fork-aware offchain storage, enabling re-org-sensitive, fork-scoped state with routine-defined error and logging semantics.

ForkLocalDepot

Fork-local storage scope for ForksHandler implementing ForkScopes.

Ledger

Persistent observation ledger used by Finalized storage.

Observation

Persistent observation record for a value managed by Finalized storage.

Persistent

Marker type for persistent offchain storage, providing fork-independent, non-reverting state with routine-defined error and logging semantics.

ValueHash

Stable, fork-independent identifier for values managed by Finalized storage.

Enums

Confidence

Confidence signal derived for a value evaluated by Finalized storage.

LogLevel

Represents log severity levels.

Traits

FinalizedOffchainStorageError

Defines caller-facing error signals specific to Finalized storage.

FinalizedPolicy

Defines a finality evaluation policy for values managed by Finalized storage.

KeyValueStore

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

Logging

Trait for structured logging in detached, asynchronous routines.

OffchainStorageError

Defines how offchain storage failures are reported to callers.

RoutineOf

Authorization interface for a Routines.

Routines

Structured execution interface for offchain routines.

SubstrateOffchainStorage

Marker trait for Substrate offchain storage kinds (backends).

Type Aliases

ConfidenceMap 🔒

LogFormatter

Defines the function signature that can be passed to the logging system to customize how log messages are formatted.

Moment

Wall-clock timestamp type used by Finalized storage.