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
| Role | Holds | Responsibility |
|---|---|---|
| Data source | its signing key | Attests financial facts (bank core, custodian, payroll). Registered per credential type. |
| Issuer | its identity key (HSM/KMS) | Authenticates itself, obtains a fresh source attestation, issues and revokes credentials. Retains no claim values. |
| Holder | credential secrets, identity key | Accepts credentials, chooses what to disclose, binds each presentation to one request. |
| Verifier | trust policy | Requests 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)
| Field | Meaning |
|---|---|
schema | "quantlayer.credential/2" — signed-document schema version |
id | Credential URI (urn:uuid:…) |
type, typeVersion | Credential type (e.g. quantlayer:BalanceAttestation) and claim-schema version |
issuer | Issuer DID |
subjectCommitment | Salted commitment to the holder DID (§4.2) |
issuedAt, validFrom, expiresAt | Issuance timestamp, start and mandatory expiry (≤ 5 years; financial types cap far lower) |
digestAlgorithm | "SHA-256" |
claimDigests | Sorted, 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) |
supersedes | Optional 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 +
holderDID +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.
- Holder requests
{ subject, type, source }(no claim fields exist). The API layer authenticates the holder assubject. - Issuer authenticates itself: identity
active, currentassertionkey, and accreditation fortypein its trust registry. - 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 purposefinancial-attestation. - 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. - Claims are validated in full against the type's schema.
- 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:
| # | Check | Failure reasons |
|---|---|---|
| 1 | structure — supported schema, document validation, holder DID | UNSUPPORTED_SCHEMA_VERSION, INVALID_VALUE |
| 2 | issuer-trust — issuer accredited for type now | ISSUER_NOT_TRUSTED |
| 3 | issuer-key — issuer active; named key version exists, serves assertion, is not revoked/expired, matches algorithm | IDENTITY_*, KEY_NOT_FOUND, KEY_NOT_USABLE, ALGORITHM_MISMATCH |
| 4 | signature — issuer signature over the document | SIGNATURE_INVALID |
| 5 | validity-period — validFrom ≤ now < expiresAt | NOT_YET_VALID, EXPIRED |
| 6 | revocation — authenticated, fresh status (§6) | STATUS_UNAVAILABLE, CREDENTIAL_REVOKED, CREDENTIAL_SUSPENDED, SIGNATURE_INVALID |
| 7 | subject-binding — commitment matches holder + subjectSalt | SUBJECT_BINDING_INVALID |
| 8 | holder-binding — audience and nonce match; now − 5 min ≤ createdAt ≤ now; holder active; current authentication key; valid signature over §8 | HOLDER_BINDING_INVALID, KEY_NOT_USABLE, IDENTITY_NOT_ACTIVE |
| 9 | disclosures — each digest ∈ claimDigests; no duplicates | DISCLOSURE_INVALID |
| 10 | disclosure-policy — §5 | DISCLOSURE_POLICY_VIOLATION |
| 11 | claims-schema — disclosed claims valid for type/typeVersion | INVALID_VALUE |
Retired issuer key versions still verify (credentials survive key rotation); revoked versions never do. Verifiers MUST keep nonces single-use.
10. Serialization
| Codec | Type | Size limit |
|---|---|---|
| HolderCredential | quantlayer.holder-credential v1 | 64 KiB |
| Presentation | quantlayer.presentation v1 | 64 KiB |
| Status list snapshot | quantlayer.status-list-snapshot v1 | 400 KiB |
| Issuer record | quantlayer.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.stringifyandutil.inspectrender them as"[REDACTED]"; the runtime logger also redactsclaims,disclosures,saltandsubjectSaltpaths. - Errors name fields and claims, never values.
12. Version migration
- Signed documents cannot be rewritten without breaking signatures, so
quantlayer.credential/1→/2is 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 withsupersedes = v1.idandevidence = { source: "quantlayer.credential/1", reference: SHA-256(v1 signing input) }, and the v1 credential is revoked assuperseded. - 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.identityv1 → v2 for an example).
13. Financial credential types (v1)
| Type | Required | Optional | Max validity |
|---|---|---|---|
quantlayer:BalanceAttestation | currency, asOf | balanceMinor, accountType | 30 days |
quantlayer:BalanceThreshold | currency, thresholdMinor, meetsThreshold, asOf | — | 30 days |
quantlayer:IncomeAttestation | currency, asOf | annualIncomeMinor, employmentStatus | 365 days |
quantlayer:AccreditedInvestor | jurisdiction, accredited, asOf | basis | 365 days |
quantlayer:KycVerification | level, sanctionsScreened, verifiedAt | jurisdiction | 365 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.