Skip to main content

ADR-024: Custody model — partner banks hold funds, the Ledger is the record, no internal wallet

  • Status: Accepted (pending Legal counter-sign)
  • Date: 2026-06-18
  • Deciders: Principal Architect, Engineering Lead, Founder
  • Relates to: ADR-006, ADR-012, ADR-014

Context​

ADR-014 establishes DemozPay as a bank-to-bank orchestrator, not a custodian. As the platform grows toward more products (EWA, lending, equb, and eventually savings/cards), there is recurring pressure — in design discussions and even in our own architecture drafts — to introduce an "internal wallet" as a core money primitive. That framing is dangerous: it implies DemozPay holds stored value, which would make it a custodian and a regulated e-money issuer. This ADR hardens the custody position into an explicit, durable rule so the drift stops recurring.

Decision​

Customer funds are held by partner financial institutions. DemozPay never custodies money. The double-entry Ledger is DemozPay's internal record of what should be and what moved (ADR-006/012); it is continuously reconciled against partner-bank statements, which are the custody ground truth. Money movement happens through partner banking APIs (via the Bank Gateway, ADR-025).

  • There is no internal wallet holding value. The wallet:member:{tenantId}:{memberId} identifiers in the Equb path are ledger read-model keys, not stored balances — they name a position in immutable ledger entries, not money DemozPay holds.
  • "Wallet" as a product (stored value the user can hold/spend) is a future product, not a platform dependency. It would only be considered if/when stored value ever becomes the operating model — and that would itself require a custody/licensing decision and a superseding ADR.
  • Product docs and partner/regulator-facing material must state custody honestly; the Equb pool is a simulated internal-ledger pool until a real partner-bank escrow account exists (do not describe it as held custody).

Alternatives considered​

  • Introduce an internal wallet as a core primitive — rejected: makes DemozPay a custodian / e-money issuer, with the licensing, capital, and regulatory burden that entails — the opposite of the orchestrator thesis.
  • Leave custody implicit (rely on ADR-014 alone) — rejected: it kept getting re-litigated and wallet kept reappearing in designs; an explicit, hard rule is needed.

Consequences​

  • Positive: preserves the orchestrator (non-custodian) regulatory posture; one clear money model that every product reuses (post to the ledger, move via a partner bank); prevents the recurring wallet drift; protects partner/regulator trust.
  • Negative / accepted: no stored-value convenience features without a deliberate custody decision; every product's money flow must round-trip a partner bank rather than an internal balance.
  • Follow-ups: keep reconciliation (ledger ↔ bank statement) as a first-class control; audit product copy for any "held funds"/"wallet balance" language; gate any real Equb escrow on a partner-bank custody account.

Revisit when​

  • A product genuinely requires stored value AND a custody/e-money path is licensed → supersede this ADR with an explicit custody decision.