pub trait LedgerBackend: Send {
Show 14 methods
// Required methods
fn open_account(
&mut self,
spec: AccountSpec,
) -> Result<Account, LedgerError>;
fn credit(&mut self, cap: MintCapability<'_>) -> Outcome;
fn authorize_mint<'a>(
&self,
t: &'a IssueTransfer,
sig: &[u8],
) -> Result<MintCapability<'a>, LedgerError>;
fn debit(&mut self, t: Transfer) -> Outcome;
fn reserve(&mut self, t: Transfer, timeout_s: u32) -> Outcome;
fn post(
&mut self,
id: TransferId,
pending: TransferId,
amount: Option<u128>,
) -> Outcome;
fn void(&mut self, id: TransferId, pending: TransferId) -> Outcome;
fn balance(&self, account: AccountId) -> Result<BalanceView, LedgerError>;
fn checkpoint(
&mut self,
signer: &dyn CheckpointSigner,
) -> Result<SignedCheckpoint, LedgerError>;
fn tick(
&mut self,
signer: &dyn CheckpointSigner,
) -> Result<TickReport, LedgerError>;
fn outbox_peek(&self, max: usize) -> Result<Vec<OutboxItem>, LedgerError>;
fn outbox_ack(&mut self, up_to: OutboxSeq) -> Result<(), LedgerError>;
fn journal_range(
&self,
from_seq: u64,
max: usize,
) -> Result<Vec<JournalEntry>, LedgerError>;
fn head(&self) -> ChainHead;
}Expand description
A single-writer double-entry ledger over one consistency domain (one cell).
§Idempotency contract (plan §2c)
Every mutating method carries a client-supplied TransferId. Replaying a
TransferId returns the original Outcome verbatim — including the
original error. This is a trait contract, property-tested against every
backend against the MemLedger oracle. (Backends may return
LedgerError::IdTooOld once the outcome row is pruned past the retention
horizon — a later work item; MemLedger keeps everything and never prunes.)
Required Methods§
Sourcefn open_account(&mut self, spec: AccountSpec) -> Result<Account, LedgerError>
fn open_account(&mut self, spec: AccountSpec) -> Result<Account, LedgerError>
Idempotent. Creates the account iff absent and returns it; if it already
exists the existing row is returned (its unit must match, else
LedgerError::AccountUnitConflict).
Sourcefn credit(&mut self, cap: MintCapability<'_>) -> Outcome
fn credit(&mut self, cap: MintCapability<'_>) -> Outcome
Single-phase issuance: issuer liability → destination. INV-1: the only
entry point that grows a unit’s supply; the debit side MUST be the
issuer’s IssuerLiability account for the unit (checked).
Sealed. This takes a MintCapability, which has no public
constructor — the only way to obtain one is Self::authorize_mint,
which verifies a hybrid-PQC signature bound to that exact transfer
against the MintAuthority this backend
was constructed with. Holding a backend is therefore not sufficient
to mint, and neither is holding a &mut to one: the authority is fixed
at construction and there is no setter. See crate::mint.
Verify an issuance authorization against this backend’s mint authority,
yielding the capability Self::credit requires.
sig must be a COSE composite signature over
crate::mint_signing_input for t. Verification is a concrete
in-crate check against fixed key material — there is no injectable
verifier to replace it with a permissive one, which is what makes this
the sole route to a MintCapability. A backend with no authority
refuses every authorization.
Sourcefn debit(&mut self, t: Transfer) -> Outcome
fn debit(&mut self, t: Transfer) -> Outcome
Single-phase spend. Overdraft-checked on the debit side (plan §2b.1).
Sourcefn reserve(&mut self, t: Transfer, timeout_s: u32) -> Outcome
fn reserve(&mut self, t: Transfer, timeout_s: u32) -> Outcome
Two-phase phase 1: places pending holds on both sides (plan §2b). The
transfer’s id is also the reservation id used by post/void.
Sourcefn post(
&mut self,
id: TransferId,
pending: TransferId,
amount: Option<u128>,
) -> Outcome
fn post( &mut self, id: TransferId, pending: TransferId, amount: Option<u128>, ) -> Outcome
Two-phase phase 2. amount: None = full post; Some(p) = partial, the
remainder released. At most one second phase succeeds per reservation.
Sourcefn void(&mut self, id: TransferId, pending: TransferId) -> Outcome
fn void(&mut self, id: TransferId, pending: TransferId) -> Outcome
Two-phase phase 2 cancel: releases the pending holds.
Sourcefn balance(&self, account: AccountId) -> Result<BalanceView, LedgerError>
fn balance(&self, account: AccountId) -> Result<BalanceView, LedgerError>
Read-only balance projection (served from a consistent snapshot; safe concurrent with the writer).
Sourcefn checkpoint(
&mut self,
signer: &dyn CheckpointSigner,
) -> Result<SignedCheckpoint, LedgerError>
fn checkpoint( &mut self, signer: &dyn CheckpointSigner, ) -> Result<SignedCheckpoint, LedgerError>
Force a signed checkpoint now and return it. Periodic checkpoints are the
backend’s own duty (driven from tick).
Sourcefn tick(
&mut self,
signer: &dyn CheckpointSigner,
) -> Result<TickReport, LedgerError>
fn tick( &mut self, signer: &dyn CheckpointSigner, ) -> Result<TickReport, LedgerError>
Housekeeping: expiry sweep (plan §2b.4), outcome pruning (plan §2c — later item), and scheduled checkpoints. Called by the actor on an interval.
Sourcefn outbox_peek(&self, max: usize) -> Result<Vec<OutboxItem>, LedgerError>
fn outbox_peek(&self, max: usize) -> Result<Vec<OutboxItem>, LedgerError>
Ordered peek at committed-but-unemitted proof-plane items (plan §2e).
Sourcefn outbox_ack(&mut self, up_to: OutboxSeq) -> Result<(), LedgerError>
fn outbox_ack(&mut self, up_to: OutboxSeq) -> Result<(), LedgerError>
Acknowledge (drop) drained outbox items up to and including up_to.
Sourcefn journal_range(
&self,
from_seq: u64,
max: usize,
) -> Result<Vec<JournalEntry>, LedgerError>
fn journal_range( &self, from_seq: u64, max: usize, ) -> Result<Vec<JournalEntry>, LedgerError>
Replay/inspection window into the journal (for verify tools and settlement framing).