Expand description
§hyprstream-ledger
The accounting plane of the cellular-ledger stack (epic #922, plan item 1.1): an embedded, single-writer, double-entry credit engine that deliberately mirrors TigerBeetle’s data model.
§The two invariants (D8)
- INV-1 — credits are issuer liabilities, not bearer tokens. Every unit
UnitIdnames its issuer; every account id bakes that unit in; issuance is the only supply-growing entry point and it debits the issuer’s own liability. There is no representation of value that omits the issuer. - INV-2 — no ledger tier on the inference hot path. This crate is
synchronous and knows nothing of admission; the enforcer’s
CreditGate(a later item) depends on the types here, never on a backend, and talks to the ledger only through an async actor facade in the service layer.
§What is in this crate (item 1.1)
types— the account model, units, transfers, outcomes (plan §2.0).errors— the deterministic error vocabulary.engine— the pure, backend-agnostic transfer state machine (plan §2b), shared verbatim by every backend so “same ops ⇒ same outcomes” holds by construction.journal— journal / checkpoint / outbox types and theCheckpointSignerinjection seam.backend::LedgerBackend— the load-bearing trait.mem::MemLedger— the complete in-memory reference implementation and proptest oracle; WASM-friendly (no tokio, no I/O, logical clock only).
RocksLedger, the persisted hash-chained journal + offline verify tool, the transactional-outbox emitter, and TigerBeetleLedger are later work items.
§Crate boundaries (D3)
No RPC / VFS / PDS / tokio dependencies. hyprstream-crypto (#920, WASM-safe)
is an unconditional dependency — signed checkpoints are load-bearing, so a
build that cannot verify them must not exist (no feature gate, ratified).
Re-exports§
pub use backend::LedgerBackend;pub use errors::LedgerError;pub use journal::balances_root;pub use journal::checkpoint_signing_input;pub use journal::pending_root;pub use journal::verify_checkpoint_signature;pub use journal::ChainHead;pub use journal::CheckpointSigner;pub use journal::JournalEntry;pub use journal::OutboxItem;pub use journal::OutboxKind;pub use journal::OutboxSeq;pub use journal::SignedCheckpoint;pub use journal::TickReport;pub use mem::MemLedger;pub use mint::mint_signing_input;pub use mint::MintAuthority;pub use mint::MintCapability;pub use types::Account;pub use types::AccountFlags;pub use types::AccountId;pub use types::AccountSpec;pub use types::BalanceView;pub use types::Cid;pub use types::Did;pub use types::IssueTransfer;pub use types::Outcome;pub use types::PendingReservation;pub use types::PendingState;pub use types::Purpose;pub use types::Transfer;pub use types::TransferId;pub use types::TransferResult;pub use types::UnitId;
Modules§
- backend
- The
LedgerBackendtrait — the load-bearing accounting-plane surface every backend (MemLedger now; RocksLedger, TigerBeetleLedger later) implements, and the enforcer builds on (plan §3.2). - engine
- The pure, backend-agnostic transfer state machine (plan §2a step 2, §2b).
- errors
- The ledger error vocabulary.
- journal
- Journal, checkpoint, and outbox types + the checkpoint signing seam (plan §2a, §2d, §2e).
- mem
MemLedger— the in-memory reference implementation.- mint
- Sealing the mint: issuance requires an unforgeable, key-bound capability.
- types
- Core data model for the accounting plane (plan §2.0).