hyprstream_ledger/lib.rs
1//! # hyprstream-ledger
2//!
3//! The **accounting plane** of the cellular-ledger stack (epic #922, plan item
4//! 1.1): an embedded, single-writer, double-entry credit engine that
5//! deliberately mirrors TigerBeetle's data model.
6//!
7//! ## The two invariants (D8)
8//!
9//! - **INV-1 — credits are issuer liabilities, not bearer tokens.** Every unit
10//! [`UnitId`] names its issuer; every account id bakes that unit in; issuance is
11//! the only supply-growing entry point and it debits the issuer's own liability.
12//! There is no representation of value that omits the issuer.
13//! - **INV-2 — no ledger tier on the inference hot path.** This crate is
14//! synchronous and knows nothing of admission; the enforcer's `CreditGate`
15//! (a later item) depends on the *types* here, never on a backend, and talks to
16//! the ledger only through an async actor facade in the service layer.
17//!
18//! ## What is in this crate (item 1.1)
19//!
20//! - [`types`] — the account model, units, transfers, outcomes (plan §2.0).
21//! - [`errors`] — the deterministic error vocabulary.
22//! - [`engine`] — the pure, backend-agnostic transfer state machine (plan §2b),
23//! shared verbatim by every backend so "same ops ⇒ same outcomes" holds by
24//! construction.
25//! - [`journal`] — journal / checkpoint / outbox types and the
26//! [`CheckpointSigner`](journal::CheckpointSigner) injection seam.
27//! - [`backend::LedgerBackend`] — the load-bearing trait.
28//! - [`mem::MemLedger`] — the complete in-memory reference implementation and
29//! proptest oracle; WASM-friendly (no tokio, no I/O, logical clock only).
30//!
31//! RocksLedger, the persisted hash-chained journal + offline verify tool, the
32//! transactional-outbox emitter, and TigerBeetleLedger are later work items.
33//!
34//! ## Crate boundaries (D3)
35//!
36//! No RPC / VFS / PDS / tokio dependencies. `hyprstream-crypto` (#920, WASM-safe)
37//! is an **unconditional** dependency — signed checkpoints are load-bearing, so a
38//! build that cannot verify them must not exist (no feature gate, ratified).
39
40pub mod backend;
41pub mod engine;
42pub mod errors;
43pub mod journal;
44pub mod mem;
45pub mod mint;
46#[cfg(feature = "postgres")]
47pub mod postgres;
48pub mod types;
49
50pub use backend::LedgerBackend;
51pub use errors::LedgerError;
52pub use journal::{
53 balances_root, checkpoint_signing_input, pending_root, verify_checkpoint_signature, ChainHead,
54 CheckpointSigner, JournalEntry, OutboxItem, OutboxKind, OutboxSeq, SignedCheckpoint,
55 TickReport,
56};
57pub use mem::MemLedger;
58pub use mint::{mint_signing_input, MintAuthority, MintCapability};
59pub use types::{
60 Account, AccountFlags, AccountId, AccountSpec, BalanceView, Cid, Did, IssueTransfer, Outcome,
61 PendingReservation, PendingState, Purpose, Transfer, TransferId, TransferResult, UnitId,
62};