0011. Financial credentials: quantlayer.credential/2

Design document, published from the repository at docs/adr/0011-financial-credentials.md.

  • Status: Accepted
  • Date: 2026-11-13

Context

QuantLayer must issue financial credentials (balances, income, accreditation, KYC) that verifiers can trust, while revealing as little as possible: the holder should disclose only what a verifier needs, the issuer should not hoard financial data, and nothing sensitive should reach logs. ZK predicates are not yet available.

Decision

  1. New signed-document schema quantlayer.credential/2 alongside v1: subject commitment instead of DID; salted SHA-256 claim digests with decoys (SD-JWT-style selective disclosure); mandatory expiry; type + type version; revocation reference; issuer-defined disclosure policy; evidence of data origin; optional supersedes.
  2. Revocation via issuer-signed 2-bit status lists (W3C Bitstring Status List pattern) with random index allocation, sequence numbers and a validUntil freshness bound; verification fails closed.
  3. Holder binding by revealing the committed DID + salt and signing {credentialDigest, disclosed digests, holder, audience, nonce, createdAt} with the holder's current authentication key.
  4. Issuer authentication = active identity + current assertion key + accreditation in a TrustRegistry, checked at issuance and verification.
  5. Authenticated data only: @quantlayer-protocol/financial issues solely from signed attestations of registered data sources fetched by the issuer with its own nonce; the issuance request has no claim fields.
  6. Data minimisation: issuer records store digests and commitments only.
  7. Log safety: sensitive() (core) makes secrets render as [REDACTED]; logger redaction paths extended; errors never include values.
  8. Migration v1 → v2 is re-issuance by the original issuer with supersedes and v1-digest evidence; the v1 credential is revoked.
  9. New package @quantlayer-protocol/financial (types, schemas, attestations, issuer); the generic protocol stays in @quantlayer-protocol/credentials.
  10. Test-only adapters: domain packages may list crypto-classical as a devDependency to test with real cryptography; the layer check rejects any production import of it.

Consequences

  • Verifiers learn only disclosed claims plus the holder DID; presentations are linkable until ZK presentations land.
  • Interoperability is pinned by published test vectors.
  • Production adapters must provide atomic status-list/record persistence, status-list publication (HTTPS/CDN), single-use verifier nonces, and data source adapters with registered keys.