Skip to main content

Module engine

Module engine 

Source
Expand description

The pure, backend-agnostic transfer state machine (plan §2a step 2, §2b).

stage is a total, default-deny function of (current state, op) → (result, deltas). It performs no I/O and no mutation: it reads the current state through StateView and returns the deltas a backend must apply atomically inside its serialized commit. RocksLedger and MemLedger share this module verbatim, which is what makes “same op sequence ⇒ same outcomes” true by construction (backend-equivalence).

There are no TOCTOU races here: within one cell ledger there is a single writer, so every interleaving question reduces to an ordering question, and the ordering is fixed by the sequence in which ops reach stage.

Structs§

Staged
The output of stage: the business result plus the deltas to apply. On an error result deltas is usually empty, but not always — an on-touch expiry (plan §2b.4) both fails the second phase and releases the hold, so a failed post can carry the expiry delta.

Enums§

Delta
A single state mutation the commit loop must apply atomically.
Op
An op the engine can stage. The idempotency key (where present) is the carried TransferId; stage never dedups — that is the commit loop’s job (it checks the outcome index before calling stage).

Constants§

MAX_TIMEOUT_S
Maximum reservation timeout — day-plus holds are tranches, not reservations.
MIN_TIMEOUT_S
Minimum reservation timeout (plan §2b.6).

Traits§

StateView
Read-only view of ledger state the engine needs. Backends implement this over their own storage (a BTreeMap for MemLedger, RocksDB point-reads for RocksLedger).

Functions§

stage
Stage an op against the current state. Pure: no mutation, no I/O.