S-001
Custody state SHALL be persisted as integer Settlement Ledger Unit (SLU) micro values (`phiMicro` protocol field naming).
Receiz/Sealed Money Standard
Sealed money implementation
This standard defines how offline-transferable value is encoded, verified, and posted back to account state, while account surfaces remain readable in USD.
Settlement Ledger Unit (SLU): Settlement Ledger Unit (SLU) is the canonical non-USD settlement custody unit used to keep online ledger replay and offline note settlement deterministic. For protocol compatibility, SLU micro-values are persisted in `phi*` field names (for example `amountPhiMicro` and `balancePhiMicro`).
Institutional core: one deterministic custody unit across ledger posting, replay, and offline note settlement. Approachable edge: USD-first account UX with explicit field-level SLU compatibility for integrators.
Implemented Invariants
- Custody state is maintained as Settlement Ledger Unit (SLU) micro integers (`phiMicro` protocol field naming).
- Conversion uses fixed denominator arithmetic (`1e12`) with half-up rounding.
- Each event stores amount fields and quote snapshot for deterministic replay.
- Withdrawal note artifacts can be transferred offline and later deposited by verification + claim.
- Proof bundle fields are preserved for machine validation across private and public views.
Normative Requirements
S-002
Conversion SHALL use fixed-denominator integer arithmetic with explicit half-up rounding.
S-003
Withdrawal note packets SHALL persist `amountUsdCents`, `amountPhiMicro`, and `usdPerPhiMicrocents` together.
S-004
Note claims SHALL validate packet authenticity and claim state before posting credit.
S-005
Private and public ledger outputs SHALL preserve compatible proof bundle semantics for verification continuity.
Conversion Rule
const PHI_RATE_DENOM = 10n ** 12n;
usdCents = (phiMicro * usdPerPhiMicrocents + PHI_RATE_DENOM / 2n) / PHI_RATE_DENOM;
phiMicro = (usdCents * PHI_RATE_DENOM + usdPerPhiMicrocents / 2n) / usdPerPhiMicrocents;Withdrawal Note Packet Shape
{
"kind": "kairos_note_packet_v2",
"noteId": "...",
"noteToken": "...",
"amountPhiMicro": "...",
"amountUsdCents": "...",
"usdPerPhiMicrocents": "...",
"source": "receiz_wallet_settlement_account",
"noteState": "available_to_claim",
"provenance": "wallet_settlement_account"
}Claim-To-Code Traceability
| Req | Source Route / Function | Verification Method |
|---|---|---|
| S-001 | app/lib/wallet/server.ts, app/api/wallet/ledger/route.ts | Wallet summary and ledger event payloads expose integer `balancePhiMicro`/`amountPhiMicro` fields. |
| S-002 | app/lib/wallet/amounts.ts::{usdCentsFromPhiMicro, phiMicroFromUsdCents} | Bidirectional conversion uses fixed denominator and half-up rounding with integer arithmetic. |
| S-003 | app/api/wallet/notes/mint/route.ts, app/lib/wallet/kairosNoteArtifact.ts | Minted packet payload includes USD amount, SLU amount, and posting rate snapshot fields. |
| S-004 | app/api/wallet/notes/claim/route.ts | Claim route validates note packet authenticity and claimability before posting credit entries. |
| S-005 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Private and public ledger outputs carry compatible proof bundle structures for external verification. |
Capability Matrix
This matrix distinguishes what is explicitly implemented in the sealed settlement contract from what legacy rails provide by default.
Portable offline transfer artifact
Receiz sealed settlement
Implemented as sealed withdrawal note packet + note claim route.
Legacy cash
Physical handoff has no packet metadata or claim-route verification in this contract.
Legacy card rails
Card authorization records do not produce transferable sealed note artifacts.
Deterministic value replay
Receiz sealed settlement
Implemented through persisted integer amount fields and quote snapshot per event.
Legacy cash
Physical exchange does not carry deterministic replay fields in software form.
Legacy card rails
Card network records do not preserve Receiz quote snapshot fields for replay.
Verification coordinates
Receiz sealed settlement
Implemented through note payload verification and ledger proof bundle fields.
Legacy cash
No built-in cryptographic verification coordinates in this model.
Legacy card rails
Card rails validate payment authorization, not note/capsule proof coordinates.
Private history + public attestation
Receiz sealed settlement
Implemented with private account ledger and public pseudonymous attestation route.
Legacy cash
No linked private/public continuity route in this contract.
Legacy card rails
Card settlement does not publish Receiz-style proof-attested continuity.
Private Transfer, Public Proof
Private ledger route
`GET /api/wallet/ledger` is session-gated and returns account-scoped history with private actor context.
Public ledger route
`GET /api/wallet/ledger/public` returns pseudonymous actor continuity with exact value/proof fields.
Shared proof contract
Both surfaces carry compatible proof bundle fields so verification logic remains stable across visibility modes.