apps/api is the QuantLayer backend. It is built on:
- Node.js 26 LTS and NestJS 12, with the Fastify adapter;
- PostgreSQL 18 through Prisma 7 (driver adapter, no query engine binary);
- Redis 8 and BullMQ 6;
- Zod 4, OpenAPI 3.1, Prometheus and OpenTelemetry.
The OpenAPI document is generated from the code and served at
GET /openapi.json. The data model explains how storage is separated.
1. One codebase, three roles
| Role | Command | Runs |
|---|---|---|
api | node dist/main.js | HTTP API |
worker | node dist/main.js worker | BullMQ proof jobs (delegated proving, verification); pruning of expired nonces and sessions |
indexer | node dist/main.js indexer | Transaction monitoring; QuantLayerCredentialRegistry event indexing |
Every role serves /health, /health/ready and /metrics.
All three roles run from the same image (infrastructure/docker/backend.Dockerfile). They
share the Prisma schema, the migrations and the crypto composition. A replica of any role can
be added or removed at any time:
- custody is stateless per operation (see §4);
- jobs and ticks are idempotent;
- rate limits live in Redis.
2. Modules
| Module | Endpoints (/v1/...) | Built on |
|---|---|---|
| DeveloperModule | auth/wallet/*, auth/session, developer/projects, …/api-keys, …/audit-events, developer/whoami, admin/projects/* | @quantlayer-protocol/evm (EIP-712, signer recovery) |
| IdentityModule | identities, identities/challenges, …/keys, …/keys/rotate, …/keys/revoke, …/accounts, …/deactivate, admin/identities/* | @quantlayer-protocol/identity IdentityService, classical and PQ verifiers, EIP-712 ownership |
| CredentialModule | credentials/issuers, …/credentials, …/revoke·suspend·reinstate, credentials/status-lists/:id, credentials/presentations/verify | @quantlayer-protocol/credentials (quantlayer.credential/2), custody-held ML-DSA/SLH-DSA issuer keys |
| PrivacyModule | privacy/trees, …/leaves, …/proofs/:index, …/publish, privacy/nullifiers/* | @quantlayer-protocol/privacy (Poseidon-BN254 Merkle trees), root registry, nullifier store |
| ProofModule | proofs/requests, proofs/jobs/prove, proofs/jobs/verify, proofs/jobs/:id | @quantlayer-protocol/zk-engine, @quantlayer-protocol/zk-noir (Noir 1.0, UltraHonk), BullMQ |
| QuantumModule | quantum/keys, …/rotate, …/versions/:v/revoke, …/sign, …/decapsulate, quantum/verify | @quantlayer-protocol/pqc-engine (FIPS 203/204/205 in Rust) |
| AuthorizationModule | authorization/policies, …/minimum-version, authorization/revocations, authorization/decisions | @quantlayer-protocol/authorization hybrid engine with Postgres-backed ports |
| BlockchainModule | blockchain/network, blockchain/transactions, blockchain/credential-status/* | JSON-RPC; event decoding for the FEAT-09 contracts |
No fake successes
Every cryptographic operation runs on the real packages. There are no stubs, and nothing returns success for work that wasn't done:
- A feature that can't run fails honestly. No chain RPC configured, or circuit artifacts
missing, returns
503 UNAVAILABLE. - An invalid proof is reported as invalid. It is a job with
verified: falseand the failed check. - A job that can't be proven is reported as failed. The job ends
failedwith the protocol reason, and is not retried. - No attestor endpoint exists. On-chain post-quantum attestation (FEAT-09) needs a
secp256k1 attestor key, and the backend holds none. Attestors run the engine themselves;
see
attestPostQuantumAuthorization.
3. Authentication and authorization
Three kinds of principal exist, all presented as Authorization: Bearer … (API keys may also
use x-api-key):
| Principal | Format | Obtained by | Used for |
|---|---|---|---|
| API key | quantlayer_sk_<id>_<secret> | A project owner, via POST /v1/developer/projects/:id/api-keys | Server-to-server integration. Scoped (16 scopes, listed per operation in OpenAPI as x-quantlayer-scopes). |
| Wallet session | quantlayer_ss_<token> | Wallet sign-in: POST /v1/auth/wallet/challenge, then EIP-712 QuantLayerSignIn signed with eth_signTypedData_v4, then POST /v1/auth/wallet/verify | Managing projects and keys. The session carries the wallet's DID when it is linked. |
| Administrator | quantlayer_admin_<secret> | QUANTLAYER_ADMIN_API_KEY (bootstrap) | Operator actions: activate, suspend or reinstate identities; suspend projects. |
How credentials are checked:
- Stored verifiers only. Secrets are compared through HMAC verifiers in constant time; the database never holds a secret.
- Wallet sign-in challenges. They are single-use (Redis
GETDEL), expire after five minutes, and bind the audience, account, nonce and validity window. Signatures must be low-S. - Revocation. Revoking an API key deletes its verifier. Suspending a project disables all of its keys.
Every route declares its authentication and scopes in a single @Endpoint(...), and the
global AuthGuard rejects any route without one. Resources are project-scoped: an identifier
from another project behaves exactly like an unknown one (404).
Identity mutations are additionally self-authorizing. The caller signs the canonical
statement for a fresh challenge, with a QuantLayer key (Ed25519, ES256K, ML-DSA, SLH-DSA) or a
linked EIP-712 wallet. @quantlayer-protocol/identity verifies the signature before it consumes the
challenge, so a bad signature doesn't burn the challenge and a replay is always detected.
4. Cryptography in the backend
Verification:
composeSignatureVerifierscombines@noble(Ed25519, ES256K) with the Rust ML-DSA and SLH-DSA verifier;- Poseidon-BN254 is used for commitments, Merkle trees and nullifiers;
- UltraHonk verification uses Barretenberg (native when available, WASM otherwise).
Custody (
CustodyService):- Where keys live. Issuer keys, project keys and the witness-sealing key are generated
inside
quantlayer-pqc. They are persisted only asProtectedKeyblobs sealed by Rust underHKDF(QUANTLAYER_KEK, "custody/<keyId>"). - How each operation runs. A fresh native store is opened and only the needed version is imported. The operation runs, then the version is destroyed, which wipes its secret.
- Source of truth. The public key ring in Postgres is authoritative.
- Concurrency. Mutations serialize on a per-key advisory lock.
- Algorithm changes. Rotation can migrate algorithms, for example ML-DSA-65 to ML-DSA-87, with a transition statement signed by both keys.
- Revocation. Revoking a version deletes its sealed blob.
- Where keys live. Issuer keys, project keys and the witness-sealing key are generated
inside
Credential issuers. Each issuer is a
did:quantlayeridentity whose assertion key is a custody key. The proof of possession for its creation is custody-signed. Credentials and status lists are signed in Rust.Delegated proving. A client that can't prove locally sends the witness to
proofs/jobs/prove:- The API encapsulates (ML-KEM-768) to the platform sealing key.
- It derives AES-256-GCM with HKDF-SHA256, salted and AAD-bound to the job id.
- Only ciphertext is enqueued.
- The worker decapsulates in custody, proves, and drops the plaintext.
- The job payload leaves Redis on completion or final failure.
Client-side proving remains preferable: the server sees the witness in memory.
5. Background jobs and status tracking
meta.proof_jobs records every job's status, which moves through
queued → active → (retrying →) succeeded | failed.
- Attempts. Jobs carry
attempts. Infrastructure errors retry with exponential backoff (PROOF_JOB_ATTEMPTS). Protocol errors (unsatisfiable witness, malformed proof) fail immediately with their reason. - Results.
- A verification job runs
request-expiry → binding → proof-system → proof → root → nullifier. A verified proof spends its nullifier exactly once (the primary key). - A proving job stores the public proof.
- A verification job runs
- Tracing. The trace context travels in the job, so the worker's span continues the HTTP request's trace.
6. Transaction monitoring and credential status indexing
The indexer role polls the chain every CHAIN_POLL_INTERVAL_MS.
Transaction monitoring. Every tracked transaction moves to:
confirming, thenconfirmedonce it hasCHAIN_CONFIRMATIONSconfirmations;failedif it reverted;droppedif it was never mined withinCHAIN_DROP_AFTER_BLOCKS.
A transaction whose block is reorganized away goes back to pending. Receipts are decoded
into QuantLayer events (registry, ProofVerified, Authorized).
Credential status indexing.
- Range.
QuantLayerCredentialRegistrylogs are indexed only up to the safe head (head −CHAIN_CONFIRMATIONS). - Idempotency. Indexing is idempotent per
(chain, tx, logIndex). - Status changes. They update
onchain_credential_statusand are appended tocredential_status_events(sourcechain), alongside the API's own status changes (sourceapi). - Roots.
RootPublishedandRootRevokedfeed the off-chain root registry that proof verification and the authorization engine consult. - Reorgs. The cursor keeps its block hash. If that hash is no longer canonical, the indexer rewinds and re-indexes.
The backend never signs chain transactions; clients submit them and ask the backend to track them.
7. Cross-cutting behaviour
Validation. Zod schemas on body, query and path are validated before the handler runs. Responses are parsed with their schema, which is also an allowlist, so undeclared fields can't leak. Validation errors list paths, never the rejected values.
Errors. One shape:
{ error: { code, message, reason?, details?, requestId } }.reasoncarries the fine-grained protocol reason. Server errors never expose messages or details.Rate limiting. Redis fixed windows per minute, shared across instances:
- per principal:
RATE_LIMIT_PER_MINUTE; - per IP, for sign-in:
RATE_LIMIT_AUTH_PER_MINUTE.
Responses carry
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. Over budget, the response is429 RATE_LIMITEDwithRetry-After.- per principal:
Logs. Structured pino JSON with
req.idandtraceId. Secrets and credential or witness fields are redacted.Metrics and tracing. See infrastructure/monitoring.
HTTP hardening.
- Security headers:
nosniff,DENYframing,default-src 'none'CSP,no-store. - A body size limit (
BODY_LIMIT_BYTES). - CORS only for
CORS_ORIGINS. TRUST_PROXYonly behind a proxy that setsX-Forwarded-For.
- Security headers:
8. Running and testing
pnpm --filter @quantlayer-protocol/api prisma:migrate # DATABASE_URL
pnpm --filter @quantlayer-protocol/api start # api; start:worker, start:indexer
pnpm --filter @quantlayer-protocol/api test # unit and integration tests
pnpm --filter @quantlayer-protocol/api openapi # regenerate docs/api/openapi.json
docker compose -f infrastructure/docker/compose.yaml up --buildIntegration tests (apps/api/test) boot the real application with Fastify inject, against:
- real PostgreSQL: embedded Postgres 18, or
TEST_DATABASE_URL(CI service container), migrated withprisma migrate deploy; - real Redis: redis-memory-server, or
TEST_REDIS_URL; - real cryptography;
- a real EVM (anvil 1.7.1), with
QuantLayerCredentialRegistrydeployed from the Foundry build.
| Area | What the tests cover |
|---|---|
| Developer | Health; request ids and W3C tracing; error shapes; metrics; OpenAPI; wallet sign-in (replay, tampering, wrong signer); scoped keys; revocation; project suspension; audit; rate limiting |
| Quantum | ML-DSA-65/87 signatures verified by @noble/post-quantum; noble ML-KEM-768 ciphertexts decapsulated in custody; dual-signed migration; revocation erasing the sealed secret; project isolation |
| Identity | Self-certifying did:quantlayer; ML-DSA proof of possession; a wallet-authorized migration from Ed25519 to ML-DSA-65; encrypted account links; account uniqueness; suspension rules |
| Credentials | ML-DSA-65 custody issuer; holder acceptance; selective disclosure; binding and trust failures; revocation through the signed status list; status history |
| Proofs | Poseidon tree; sealed witness (Redis inspected); Noir/UltraHonk proving in the worker; verification; nullifier spent once; tampering; unsatisfiable witness failing without retry |
| Authorization | Ed25519 and ML-DSA-65 decisions; replay; emergency revocation; policy retirement; project isolation; evidence-free decision log |
| Blockchain | Confirmations; reverts; drops; reorg re-opening; honest 503 without RPC; credential status and root indexing up to the safe head; idempotency |
| OpenAPI | Committed document equals the code; every route declared, summarized and secured |