Receiz/Transfer Runbook

Transfer runbook

This runbook describes how value moves in production routes, how writes stay idempotent, and how posted events remain replayable and verifiable.

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.

User Routes
POST /api/stripe/wallet/checkout
Session

Creates card-deposit checkout session. Completion posts credited settlement event.

POST /api/wallet/notes/mint
Session

Creates sealed withdrawal note from wallet balance with persisted quote snapshot fields.

POST /api/wallet/notes/claim
Session

Verifies note artifact and posts note claim credit.

GET /api/wallet/notes/:noteId/download
Session

Returns sealed PNG artifact with embedded packet and verification coordinates.

POST /api/wallet/sigils/claim
Session

Claims deterministic sigil-derived value into wallet ledger.

Developer Routes
GET /api/connect/wallet/me
Bearer (receiz:wallet.read)

Returns delegated wallet summary for authorized resource owner.

POST /api/connect/transfers
Bearer (receiz:wallet.transfer)

Performs delegated transfer with deterministic integer fields and persisted quote snapshot.

Normative Requirements
T-001

Transfer handlers SHALL normalize request value into integer settlement fields before posting.

T-002

Quote resolution SHALL use deterministic rate derivation and SHALL be captured per posted event.

T-003

Conversion SHALL follow fixed-denominator integer arithmetic with half-up rounding.

T-004

Write paths SHALL enforce idempotency so repeated client retries do not duplicate value movement.

T-005

Posted events SHALL persist value tuple and proof references for replay and verification.

T-006

Invalid amount, insufficient backing, and invalid note-claim states SHALL hard-fail without posting writes.

Claim-To-Code Traceability
ReqSource Route / FunctionVerification Method
T-001app/api/chat/conversations/[conversationId]/transfers/route.ts, app/api/wallet/notes/mint/route.tsHandlers parse client amount inputs into integer settlement units before write execution.
T-002app/lib/wallet/amounts.ts::walletUsdPerPhiMicrocents, app/api/wallet/notes/mint/route.tsPosting flow resolves deterministic rate snapshot and persists it in event payload fields.
T-003app/lib/wallet/amounts.ts::{usdCentsFromPhiMicro, phiMicroFromUsdCents}Counterpart value computation follows fixed denominator and half-up integer conversion.
T-004app/api/chat/conversations/[conversationId]/transfers/route.ts, app/api/wallet/notes/mint/route.tsIdempotency keys/nonces prevent duplicate posting under retry or replayed client submission.
T-005app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.tsTransfer and note-related entries persist value tuple plus proof bundle references for replay.
T-006app/api/chat/conversations/[conversationId]/transfers/route.ts, app/api/wallet/notes/claim/route.tsInvalid amount, insufficient backing, and invalid claim states return hard failure without posting.
Execution Sequence
  1. Normalize request amount into integer fields (`usdCents` and/or Settlement Ledger Unit micro field `phiMicro`).
  2. Resolve deterministic user quote snapshot from rate source.
  3. Compute counterpart amount with fixed-denominator integer conversion.
  4. Apply idempotency controls to suppress duplicate writes.
  5. Persist event with amount fields + quote snapshot + proof references.
  6. Return wallet summary and event identifiers for reconciliation.
Hard Guardrails
  • Reject invalid, non-numeric, or non-positive amounts.
  • Reject debit operations when settlement backing balance is insufficient.
  • Enforce membership constraints on conversation transfer paths.
  • Reject note-claim attempts for invalid, missing, or already-claimed note states.
  • Enforce payload size limits for JSON and multipart inputs.
User Action Mapping
  • Wallet button: Deposit funds -> card checkout route.
  • Wallet button: Send via Receiz -> transfer posting route.
  • Wallet button: Withdrawal note -> note mint route.
  • Wallet button: Deposit upload -> note claim route.
Transfer Response Shape
{
  "ok": true,
  "transfer": {
    "id": "...",
    "messageId": "...",
    "amountPhiMicro": "...",
    "amountUsdCents": "...",
    "usdPerPhiMicrocents": "...",
    "alreadyProcessed": false
  },
  "wallet": {
    "balancePhiMicro": "...",
    "balancePhi": "...",
    "balanceUsd": "...",
    "quote": {
      "usdPerPhi": 0,
      "phiPerUsd": 0,
      "usdPerPhiMicrocents": "..."
    }
  }
}
Settlement StandardPublic LedgerSettlement Value SourceSealed Money StandardLedger Contract