Instrument, not attachment
An offline settlement note is a sealed value instrument with deterministic fields and claim semantics, not a screenshot, message, or informal promise.
Receiz/Economy/Offline Settlement Notes
Offline settlement notes
Offline settlement notes package value as sealed instruments for portable transfer and deterministic account settlement. Credit posts only after claim verification succeeds.
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.
Offline continuity layer
The note can move across devices and channels without network dependency, then settle back to account state through verification + claim.
File-compatible surface
Users can send and receive standard file formats (PNG, PDF, JSON) while the underlying settlement contract preserves deterministic replay and proof continuity.
Executive summary
- Portable settlement instrument with strict redemption rules.
- File-native transfer path with cryptographic verification.
- Verification gates before credit posting; invalid or duplicate claims hard-fail.
- One append-only ledger trail across card deposits, transfers, note mint, and note claim.
Normative requirements
O-001
Offline note packets SHALL persist `amountUsdCents`, `amountPhiMicro`, and `usdPerPhiMicrocents` together.
O-002
Note mint handlers SHALL create sealed packets from posted account balance using deterministic quote snapshot fields.
O-003
Claim handlers SHALL verify packet authenticity and claim state before posting account credit.
O-004
Invalid, missing, or already-claimed note states SHALL hard-fail without ledger credit.
O-005
Posted note events SHALL remain replayable from persisted integer value fields and rate snapshot.
O-006
Private/public ledger surfaces SHALL preserve proof-compatible settlement semantics after note claim posting.
O-007
Claim arbitration SHALL be authoritative on server ledger acceptance order: first accepted claim for a note token wins globally.
O-008
When a note carries `claimRecipientUserId`, claim handlers SHALL enforce recipient lock and reject non-matching claimants.
O-009
`/ledger` claim-batch imports SHALL require an authenticated wallet session so claim credits post to the signed-in account.
Execution sequence
- User initiates withdrawal note mint from settlement account.
- System normalizes value fields and persists deterministic quote snapshot.
- System emits sealed note packet artifact (PNG/PDF/JSON).
- Note is transferred offline or through any file channel.
- Recipient uploads note packet for claim.
- Claim route verifies authenticity + claimability and posts account credit.
- Ledger records remain replayable and proof-attested across private/public views.
Packet contract 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 authority policy
- Server ledger acceptance order is authoritative for note claims, including offline-origin claim bundles.
- First accepted claim for a note token posts credit; later attempts fail as already claimed.
- Recipient-locked notes are claimable only by the locked account identity.
- On `/ledger`, claim-batch imports require sign-in; verified ledger proof-bundle imports remain public.
Claim-to-code traceability
| Req | Source Route / Function | Verification Method |
|---|---|---|
| O-001 | app/api/wallet/notes/mint/route.ts, app/lib/wallet/kairosNoteArtifact.ts | Minted packet includes amount and quote tuple fields required for deterministic replay. |
| O-002 | app/api/wallet/notes/mint/route.ts | Mint flow derives value from account context and persists posting snapshot fields. |
| O-003 | app/api/wallet/notes/claim/route.ts | Claim flow validates packet and claim state before any ledger write. |
| O-004 | app/api/wallet/notes/claim/route.ts | Invalid token or invalid claimability returns hard failure without posting credit. |
| O-005 | app/lib/wallet/amounts.ts, app/api/wallet/ledger/route.ts | Replay can recompute deterministic value outcomes from persisted integer fields + rate tuple. |
| O-006 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Identity visibility differs by route while value/proof semantics remain compatible. |
| O-007 | app/api/wallet/notes/claim/route.ts | Claim processing enforces first accepted server claim and returns `wallet_note_already_claimed` for later attempts. |
| O-008 | app/api/wallet/notes/mint/route.ts, app/api/wallet/notes/claim/route.ts | Mint supports optional `claimRecipientUserId`; claim route rejects non-matching accounts with `wallet_note_claim_restricted`. |
| O-009 | app/ledger/LedgerClient.tsx, app/api/wallet/me/route.ts | Ledger import gate requires sign-in before executing `receiz.ledger_claim_batch`; proof-bundle ledger imports remain available. |
Capability comparison
Portable transfer medium
Offline settlement note
Sealed file packet (PNG/PDF/JSON) with embedded settlement contract fields.
Legacy offline handoff
Payment message, screenshot, or reference code with no verifiable payload contract.
Redemption controls
Offline settlement note
Verification + claim state checks gate credit posting.
Legacy offline handoff
Manual interpretation and reconciliation across fragmented systems.
Deterministic replay
Offline settlement note
Ledger replay from persisted integer value tuple and rate snapshot.
Legacy offline handoff
Post-hoc reconstruction from inconsistent logs and mutable references.
Audit continuity
Offline settlement note
One append-only settlement trail from issuance to claim.
Legacy offline handoff
Split evidence across channels with continuity gaps.