Skip to main content

LedgerBackend

Trait LedgerBackend 

Source
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§

Source

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).

Source

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.

Source

fn authorize_mint<'a>( &self, t: &'a IssueTransfer, sig: &[u8], ) -> Result<MintCapability<'a>, LedgerError>

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.

Source

fn debit(&mut self, t: Transfer) -> Outcome

Single-phase spend. Overdraft-checked on the debit side (plan §2b.1).

Source

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.

Source

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.

Source

fn void(&mut self, id: TransferId, pending: TransferId) -> Outcome

Two-phase phase 2 cancel: releases the pending holds.

Source

fn balance(&self, account: AccountId) -> Result<BalanceView, LedgerError>

Read-only balance projection (served from a consistent snapshot; safe concurrent with the writer).

Source

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).

Source

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.

Source

fn outbox_peek(&self, max: usize) -> Result<Vec<OutboxItem>, LedgerError>

Ordered peek at committed-but-unemitted proof-plane items (plan §2e).

Source

fn outbox_ack(&mut self, up_to: OutboxSeq) -> Result<(), LedgerError>

Acknowledge (drop) drained outbox items up to and including up_to.

Source

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).

Source

fn head(&self) -> ChainHead

The current head of the hash chain.

Implementors§