QuantLayer Financial Credentials — Protocol Specification

Design document, published from the repository at docs/protocol/FINANCIAL_CREDENTIALS.md.

Status: draft v2 (quantlayer.credential/2) · Audience: implementers of issuers, wallets and verifiers; security reviewers. Decision record: ADR-0011. Reference implementation: @quantlayer-protocol/credentials (generic protocol) and @quantlayer-protocol/financial (financial types).

The key words MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.

1. Roles

RoleHoldsResponsibility
Data sourceits signing keyAttests financial facts (bank core, custodian, payroll). Registered per credential type.
Issuerits identity key (HSM/KMS)Authenticates itself, obtains a fresh source attestation, issues and revokes credentials. Retains no claim values.
Holdercredential secrets, identity keyAccepts credentials, chooses what to disclose, binds each presentation to one request.
Verifiertrust policyRequests a presentation (audience + nonce) and verifies it.

The issuer and the holder are separate parties: the issuer never sees a presentation, and the holder cannot alter what the issuer signed.

2. Encodings

  • Canonical JSON — RFC 8785 profile: sorted keys, no whitespace, safe integers only, no undefined. All hashed or signed values use it.
  • Bytes — base64url without padding (strict, canonical).
  • Times — integer Unix epoch milliseconds.
  • Signing input — "QUANTLAYER-SIG-V1:" ‖ purpose ‖ "\n" ‖ canonicalJSON(value). Purposes: credential, status-list, credential-presentation, financial-attestation. Distinct purposes give domain separation.
  • Amounts — decimal strings of integer minor units (e.g. cents) with an ISO 4217 currency; floating point is never used.

3. Credential data model

3.1 Signed document (quantlayer.credential/2)

FieldMeaning
schema"quantlayer.credential/2" — signed-document schema version
idCredential URI (urn:uuid:…)
type, typeVersionCredential type (e.g. quantlayer:BalanceAttestation) and claim-schema version
issuerIssuer DID
subjectCommitmentSalted commitment to the holder DID (§4.2)
issuedAt, validFrom, expiresAtIssuance timestamp, start and mandatory expiry (≤ 5 years; financial types cap far lower)
digestAlgorithm"SHA-256"
claimDigestsSorted, unique digests of salted claims plus decoys (§4.1); 1–128 entries
revocation{ registry, index } — status list and position (§6)
disclosurePolicy{ required[], optional[] } claim names (§5)
evidence{ source, reference } — data source id and attestation digest (§7)
supersedesOptional id of the credential this one replaces (§9)

The document contains no claim values and no subject DID.

3.2 Proof

{ verificationMethod, algorithm, key: { keyId, version }, value } — the issuer's signature over signingInput("credential", document), naming the exact key version. Algorithms: any registered signature algorithm (Ed25519, ES256K today; ML-DSA via the post-quantum backend).

3.3 Holder artifacts

  • HolderCredential = signed credential + all disclosures + subjectSalt.
  • Disclosure = { salt, name, value } (salt: 16 CSPRNG bytes).
  • Presentation = signed credential + selected disclosures + holder DID + subjectSalt + binding (§8).

4. Commitments

4.1 Claim digests (selective disclosure)

digest = base64url(SHA-256("QUANTLAYER-SD-V1\n" ‖ canonicalJSON([salt, name, value])))

Each claim gets a fresh salt; revealing a disclosure lets anyone recompute one digest, and nothing else. The issuer adds decoys random 32-byte values (default 2) and sorts the list, hiding claim count and order.

4.2 Subject commitment

subjectCommitment = base64url(SHA-256("QUANTLAYER-SUBJECT-V1\n" ‖ canonicalJSON({did, salt})))

The holder proves they are the subject by revealing did and salt and signing the presentation with that DID's current authentication key.

5. Disclosure policy

Set by the issuer from the credential type. required claims MUST be disclosed in every presentation; optional claims MAY be. Every claim MUST be listed; names in both lists are invalid. Verifiers MUST reject presentations that omit a required claim or disclose an unlisted name.

6. Revocation and status

Issuers maintain status lists of 2-bit entries (00 active, 01 suspended, 10 revoked; 11 invalid), most significant bits first. Indices are drawn at random from unused positions. Capacity SHOULD be ≥ 131,072 for herd privacy. revoked is permanent.

A published snapshot is signed with purpose status-list: { schema: "quantlayer.status-list/1", id, issuer, sequence, issuedAt, validUntil, capacity, statuses }. sequence increases with every change. Verifiers MUST reject a credential if the snapshot is missing, belongs to another list or issuer, is outside [issuedAt, validUntil), fails signature verification, or marks the entry suspended or revoked — status failures fail closed.

7. Issuance

Issuers MUST NOT certify client-submitted financial claims. Claims MUST come from a registered data source, an authenticated upstream system, or an independently verifiable commitment, and that origin MUST be recorded as evidence.

  1. Holder requests { subject, type, source } (no claim fields exist). The API layer authenticates the holder as subject.
  2. Issuer authenticates itself: identity active, current assertion key, and accreditation for type in its trust registry.
  3. Issuer chooses a nonce and fetches an attestation from the source adapter. The attestation document { schema: "quantlayer.financial-attestation/1", source, type, typeVersion, subject, claims, observedAt, expiresAt, nonce } is signed by the source with purpose financial-attestation.
  4. Issuer verifies: source registered, active and authorised for type; matching subject, type and version; matching nonce (no replay); observedAt ≤ now < expiresAt; valid signature with the registered key.
  5. Claims are validated in full against the type's schema.
  6. Issuer allocates a status index, salts subject and claims, builds and validates the document, signs it, stores a claim-free record (credentialDigest, subjectCommitment, status) and returns the HolderCredential to the holder only.

evidence.reference = base64url(SHA-256(signingInput("financial-attestation", attestation))).

8. Presentation and holder binding

The verifier issues { audience, nonce }. The holder discloses all required claims plus chosen optional ones and signs, with purpose credential-presentation:

{ credentialDigest, disclosed: sorted digests of revealed disclosures,
  holder, audience, nonce, createdAt }

credentialDigest = base64url(SHA-256(signingInput("credential", document))).

9. Verification algorithm

Verifiers MUST run these checks in order, stop at the first failure and release claims only when all pass:

#CheckFailure reasons
1structure — supported schema, document validation, holder DIDUNSUPPORTED_SCHEMA_VERSION, INVALID_VALUE
2issuer-trust — issuer accredited for type nowISSUER_NOT_TRUSTED
3issuer-key — issuer active; named key version exists, serves assertion, is not revoked/expired, matches algorithmIDENTITY_*, KEY_NOT_FOUND, KEY_NOT_USABLE, ALGORITHM_MISMATCH
4signature — issuer signature over the documentSIGNATURE_INVALID
5validity-period — validFrom ≤ now < expiresAtNOT_YET_VALID, EXPIRED
6revocation — authenticated, fresh status (§6)STATUS_UNAVAILABLE, CREDENTIAL_REVOKED, CREDENTIAL_SUSPENDED, SIGNATURE_INVALID
7subject-binding — commitment matches holder + subjectSaltSUBJECT_BINDING_INVALID
8holder-binding — audience and nonce match; now − 5 min ≤ createdAt ≤ now; holder active; current authentication key; valid signature over §8HOLDER_BINDING_INVALID, KEY_NOT_USABLE, IDENTITY_NOT_ACTIVE
9disclosures — each digest ∈ claimDigests; no duplicatesDISCLOSURE_INVALID
10disclosure-policy — §5DISCLOSURE_POLICY_VIOLATION
11claims-schema — disclosed claims valid for type/typeVersionINVALID_VALUE

Retired issuer key versions still verify (credentials survive key rotation); revoked versions never do. Verifiers MUST keep nonces single-use.

10. Serialization

CodecTypeSize limit
HolderCredentialquantlayer.holder-credential v164 KiB
Presentationquantlayer.presentation v164 KiB
Status list snapshotquantlayer.status-list-snapshot v1400 KiB
Issuer recordquantlayer.issued-credential v1—

Envelopes are { type, version, payload } in canonical JSON. Decoders MUST reject oversized input before parsing, unknown fields, invalid base64url, and documents failing §3 validation. Decoded secrets are marked sensitive (§11).

11. Confidentiality and logging

  • Issuer records contain no claim values and no subject DID.
  • Claim values, disclosures and salts are sensitive: JSON.stringify and util.inspect render them as "[REDACTED]"; the runtime logger also redacts claims, disclosures, salt and subjectSalt paths.
  • Errors name fields and claims, never values.

12. Version migration

  • Signed documents cannot be rewritten without breaking signatures, so quantlayer.credential/1 → /2 is a re-issuance by the original issuer: the v1 credential is verified, its claims (authenticated by the issuer's own v1 signature) are re-issued with supersedes = v1.id and evidence = { source: "quantlayer.credential/1", reference: SHA-256(v1 signing input) }, and the v1 credential is revoked as superseded.
  • Claim schemas are versioned per type (typeVersion); old versions stay registered so existing credentials keep validating.
  • Wire formats are versioned per codec with migration chains (see quantlayer.identity v1 → v2 for an example).

13. Financial credential types (v1)

TypeRequiredOptionalMax validity
quantlayer:BalanceAttestationcurrency, asOfbalanceMinor, accountType30 days
quantlayer:BalanceThresholdcurrency, thresholdMinor, meetsThreshold, asOf—30 days
quantlayer:IncomeAttestationcurrency, asOfannualIncomeMinor, employmentStatus365 days
quantlayer:AccreditedInvestorjurisdiction, accredited, asOfbasis365 days
quantlayer:KycVerificationlevel, sanctionsScreened, verifiedAtjurisdiction365 days

BalanceThreshold lets a holder prove "balance ≥ X" without revealing the balance, until zero-knowledge predicates are available.

14. Security considerations

  • Unlinkability: presentations reveal the holder DID and the same signature/digests each time, so colluding verifiers can link them. ZK presentations (@quantlayer-protocol/zk-engine) are the planned remedy.
  • Status privacy: fetching a status list reveals interest in the list, not the entry; use large lists and caching/CDNs.
  • Freshness: verifiers depend on snapshot validUntil; issuers SHOULD publish well before expiry.
  • Issuer compromise: revoke the issuer key version (credentials it signed stop verifying) and remove accreditation from trust registries.
  • Atomicity: issuers MUST persist the status-list allocation and record atomically in production; a failure in between only leaks an unused index.

15. Test vectors

packages/credentials/src/sd/__vectors__/quantlayer-credential-v2.json fixes inputs (RFC 8032 Ed25519 test keys, a counter-based random stream, fixed time) and the resulting disclosure digests, subject commitment, signing inputs, credential digest and Ed25519 signatures for the credential, presentation and status list. vectors.test.ts checks them against the documented formulas.