Settlement Unit Contract
Settlement Ledger Unit (SLU) is used to keep custody math deterministic across online posting, append-only replay, and offline note settlement. One unit prevents interpretive drift.
Receiz/Economy/Settlement Standard
Settlement standard
This document is the normative contract for value handling in Receiz. It specifies what the system MUST do, where those guarantees are enforced in code, and where guarantee boundaries begin and end.
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.
Operator Surface Contract
End-users remain USD-first while integration payloads keep explicit SLU compatibility via stable `phi*` field names and rate tuples for deterministic reconciliation.
Document Control
Standard ID
receiz-settlement-standard-v1
Status
Normative
Revision ID
receiz-settlement-standard-v1-r1
Issuer
Receiz Settlement Standards Function
Approval Authority
Receiz Core Protocol Review
Supersedes Revision ID
none
Scope
Wallet settlement contract surface
Verification Version
wallet-ledger-v1
Revision Anchor
x-receiz-conformance-revision
Active Revision Value
loading revision...
Conformance Report Artifact
Schema: receiz-conformance-report-v1
Reference Instant (UTC)
2026-03-11 09:19:49Z·
Pulse Witness Artifact
Open Live Pulse Witness URLSchema: sigil-share-payload-v2
Revision authority is computed from source digests and returned on each report as the x-receiz-conformance-revision response header.
Normative Definitions
Account Presentation Amount
The USD value shown to the account holder. It SHALL be derived from persisted event fields and SHALL NOT overwrite custody state.
Custody State
The canonical settlement amount stored as Settlement Ledger Unit (SLU) micro-units (`phiMicro` field naming in protocol payloads).
Posting Reference Rate
`usdPerPhiMicrocents` derived from deterministic issuance logic at canonical pulse index and persisted with each event.
Pulse Index
Deterministic settlement-time index derived from genesis-anchored pulse math. Same reference instant SHALL resolve to the same pulse index across implementations (no authority drift). UTC input is reference-only for selecting current index and SHALL NOT be time authority.
Settlement Event
An append-only ledger record that includes value fields (`amountUsdCents`, `amountPhiMicro`, `usdPerPhiMicrocents`) and proof bundle references.
Sealed Note
A portable withdrawal note artifact that can be transferred offline and deposited later through verification + claim posting.
Normative Requirements
R-001
Account surfaces SHALL present user-facing balances and activity in USD.
R-002
Custody state SHALL be stored as integer Settlement Ledger Unit (SLU) micro values (`phiMicro` protocol field naming).
R-003
Rate derivation SHALL be deterministic (`quotePhiForUsd` + `DEFAULT_ISSUANCE_POLICY`) with pulse resolution recomputable to the same index for the same reference instant, and SHALL exclude manual override/fallback lanes.
R-004
Conversion SHALL use fixed denominator integer arithmetic with explicit half-up rounding.
R-005
Settlement events SHALL persist USD amount, SLU amount, and posting reference rate together.
R-006
Withdrawal note mint and note claim operations SHALL preserve deterministic replay and proof continuity.
R-007
Private and public ledger views SHALL preserve identical value/proof fields while differing only in identity visibility.
Rate Derivation Reference
export function walletUsdPerPhiMicrocents(): bigint {
const nowUtc = new Date(); // reference input only
const pulse = Math.floor(momentFromUTC(nowUtc).pulse); // canonical genesis-anchored pulse index
const quote = quotePhiForUsd({ meta, nowPulse: pulse, usd: 100 }, DEFAULT_ISSUANCE_POLICY);
return parseUsdPerPhiToMicrocents(quote.usdPerPhi.toFixed(8));
}Conversion Contract
const PHI_RATE_DENOM = 10n ** 12n;
usdCents = (phiMicro * usdPerPhiMicrocents + PHI_RATE_DENOM / 2n) / PHI_RATE_DENOM;
phiMicro = (usdCents * PHI_RATE_DENOM + usdPerPhiMicrocents / 2n) / usdPerPhiMicrocents;Claim-To-Code Traceability
| Req | Claim | Source Route / Function | Verification Method |
|---|---|---|---|
| R-001 | USD account presentation | app/wallet/WalletAccountExperience.tsx, app/v/[slug]/[code]/[pulse]/page.tsx, app/lib/wallet/server.ts | Wallet balance/activity labels and receipt/email amount lines are USD-first with SLU shown as support. |
| R-002 | Canonical SLU custody | app/lib/wallet/server.ts (wallet summary), app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Ledger payloads and account state fields include `amountPhiMicro`/`balancePhiMicro` integer custody values. |
| R-003 | Deterministic rate-only source | app/lib/wallet/amounts.ts::walletUsdPerPhiMicrocents | Rate is derived from deterministic quote function and issuance policy at resolved pulse, with stable pulse recomputation for identical reference instants. |
| R-004 | Integer conversion contract | app/lib/wallet/amounts.ts::{usdCentsFromPhiMicro, phiMicroFromUsdCents} | Both conversion directions use fixed denominator arithmetic and half-up rounding behavior. |
| R-005 | Event-level replay fields | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts, app/api/wallet/notes/mint/route.ts | Transfer and note events persist amount + rate tuple required for deterministic replay. |
| R-006 | Sealed note continuity | app/lib/wallet/kairosNoteArtifact.ts, app/api/wallet/notes/mint/route.ts, app/api/wallet/notes/claim/route.ts | Minted artifact carries claimable packet; claim route verifies and posts credit with preserved value fields. |
| R-007 | Private/public identity partition | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Public response pseudonymizes identity while preserving exact value and proof payload semantics. |
Guarantee Boundaries
| Guarantee | Condition | Failure Mode | Out-of-Scope |
|---|---|---|---|
| Deterministic replay of posted value | Event tuple (`amountUsdCents`, `amountPhiMicro`, `usdPerPhiMicrocents`) is present and unmodified. | If the tuple is missing or altered, replay outputs are non-authoritative and the event cannot be verified as deterministic. | External value systems that do not preserve the tuple fields are outside this contract. |
| Offline transfer continuity | Value is transferred via sealed note packet and later deposited through verification + claim. | If packet verification fails or claim state is invalid, deposit posting is rejected and continuity is not established. | Unverified file exchange and non-contract channels are outside continuity guarantees. |
| Identity-scoped privacy with public attestation | Data is read through private/public ledger routes defined by this contract. | If data is handled outside the defined ledger routes, identity partition guarantees do not apply. | Identity exposure policies outside these routes are not defined by this page. |
| Settlement contract completeness | Operation uses deposit, transfer, withdrawal note mint, or note claim routes. | Operations outside the contract route set (including bank withdrawal expectations) are unsupported by this standard. | No bank withdrawal endpoint is defined in this settlement contract surface. |
Conformance Controls
| Control | Verification Method | Evidence |
|---|---|---|
| Replay determinism | Recompute USD/SLU conversion from persisted tuple (`amountUsdCents`, `amountPhiMicro`, `usdPerPhiMicrocents`) and compare to stored outputs. | Ledger event payload + conversion function outputs. |
| Rate derivation integrity | Resolve canonical pulse index from genesis-anchored pulse function, then derive quote using canonical issuance policy path only; reject manual override paths. | Rate function output and route-level persisted `usdPerPhiMicrocents` values. |
| Proof continuity | Verify proof bundle hashes and version marker across private and public ledger outputs for the same event. | `proofBundle` fields, `capsuleHash`, `bundleHash`, and verification version. |
| Identity partition | Compare private vs public route payloads to confirm identity pseudonymization while value/proof payload remains exact. | Route responses from `/api/wallet/ledger` and `/api/wallet/ledger/public`. |
User Operating Edge
- Users read balances in USD while settlement records remain deterministic.
- Transfers and offline notes follow one contract with one audit trail.
- Every posted movement is reconcilable through statement and attestation records with explicit SLU custody units.
Developer Operating Edge
- Integrations can render USD directly from persisted amount fields.
- Replay logic can be implemented from integer SLU amount + rate tuple without heuristics.
- Verification tooling can consume proof bundles from both private and public ledger views.
Settlement Reference Surfaces
Settlement appendix and operational contracts are published as canonical references.
Deterministic rate authority
Value Source Appendix
Normative rate-derivation authority, replay inputs, and value-source boundary rules.
Canonical Settlement Reference
Deposit/transfer/claim flow
Transfer Runbook
Operational settlement sequence for deposit, transfer, and claim contract execution.
Canonical Settlement Reference
Append-only ledger surface
Ledger Contract
Private/public ledger route contract with proof continuity and identity-partition semantics.
Canonical Settlement Reference
Portable value instrument contract
Offline Settlement Notes
Offline note issuance, transfer continuity, and verification-backed redemption contract.
Canonical Settlement Reference