Skip to main content

Module ledger

Module ledger 

Source
Expand description

ai.hyprstream.ledger.* — the cellular-ledger inventory lexicons (#924).

Three DAG-CBOR record types form the holder-controlled inventory: the signed entitlements, usage receipts, and ledger heads that live in a holder’s own atproto repo (its signed PDS commit is the only signature these records need — see crate::commit).

  • allocation::AllocationRecord (ai.hyprstream.ledger.allocation) — an issuer-signed grant: the held entitlement. References the UCAN grant CID, carries the issuer-named allocation::Unit, amount, epoch, issuer DID, holder (subject), and the grant allocation::GrantClass.
  • receipt::ReceiptRecord (ai.hyprstream.ledger.receipt) — a dual-signed usage record binding both principals (spender + host, the #681 two-principal vocabulary), the referenced allocation CID, the transfer id, and the quantum spent.
  • checkpoint::CheckpointRecord (ai.hyprstream.ledger.checkpoint) — a signed ledger head (seq, head hash, state roots) that references — never embeds — an external anchor.

§Pseudonymity constraints (the #928 charter — review-blockers)

These lexicons are the P0 target of the pseudonymity charter. The rules are enforced structurally — by the shape of the records, not by a runtime check that could be bypassed:

  1. No legal-identity field, anywhere. Every record has a frozen field set and decoding rejects unknown fields, so a legalName/kyc/… field is not representable: it fails to decode. Audit binds pseudonyms only.
  2. Pairwise per-cell subject identifiers. The holder/spender/host fields are validated by [validate_subject_id], which accepts a did:key / did:at9p or an opaque pairwise identifier — it never requires a DID, let alone a did:web. A cell-scoped pairwise ID drops straight in.
  3. The unit names its issuer. allocation::Unit bakes the issuer DID into the unit itself — there is no bare unit string. Credits are issuer liabilities (D8-1), never bearer tokens; allocation::AllocationRecord additionally requires the top-level issuer to equal unit.issuer.
  4. Grant class couples anonymity to spend mode. allocation::GrantClass::Prepaid is bearer-like, issuable to a bare did:key, and lease-mode-only; allocation::GrantClass::Underwritten is the only detect-mode-eligible class (see allocation::GrantClass::detect_mode_eligible).

§Encoding

Like the other hyprstream lexicons, every record is DAG-CBOR with canonical (pure-lexicographic) map-key order applied by the encoder, so callers construct fields in any order. Each record has a frozen field set: decoding rejects unknown fields. Optional fields are omitted from the encoded map when absent (never encoded as null). CID references are carried as format: "cid" strings (not DAG-CBOR links): the referenced blocks (UCAN grants, allocations, external ledger state) live outside this repo’s MST, so a tag-42 link would be a false claim of local containment — the same reasoning crate::record::ModelRecord::current_oid documents.

Re-exports§

pub use allocation::AllocationRecord;
pub use allocation::GrantClass;
pub use allocation::Unit;
pub use checkpoint::CheckpointRecord;
pub use checkpoint::StateRoot;
pub use receipt::ReceiptRecord;

Modules§

allocation
ai.hyprstream.ledger.allocation — an issuer-signed grant record (the held entitlement / inventory line).
checkpoint
ai.hyprstream.ledger.checkpoint — a signed ledger head (the anchorable object).
receipt
ai.hyprstream.ledger.receipt — a dual-signed usage record.