Skip to main content

Crate hyprstream_ledger

Crate hyprstream_ledger 

Source
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 UnitId names 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 the CheckpointSigner injection 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 LedgerBackend trait — 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).