QuantLayer backend

Design document, published from the repository at docs/backend/BACKEND.md.

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

RoleCommandRuns
apinode dist/main.jsHTTP API
workernode dist/main.js workerBullMQ proof jobs (delegated proving, verification); pruning of expired nonces and sessions
indexernode dist/main.js indexerTransaction 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

ModuleEndpoints (/v1/...)Built on
DeveloperModuleauth/wallet/*, auth/session, developer/projects, …/api-keys, …/audit-events, developer/whoami, admin/projects/*@quantlayer-protocol/evm (EIP-712, signer recovery)
IdentityModuleidentities, identities/challenges, …/keys, …/keys/rotate, …/keys/revoke, …/accounts, …/deactivate, admin/identities/*@quantlayer-protocol/identity IdentityService, classical and PQ verifiers, EIP-712 ownership
CredentialModulecredentials/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
PrivacyModuleprivacy/trees, …/leaves, …/proofs/:index, …/publish, privacy/nullifiers/*@quantlayer-protocol/privacy (Poseidon-BN254 Merkle trees), root registry, nullifier store
ProofModuleproofs/requests, proofs/jobs/prove, proofs/jobs/verify, proofs/jobs/:id@quantlayer-protocol/zk-engine, @quantlayer-protocol/zk-noir (Noir 1.0, UltraHonk), BullMQ
QuantumModulequantum/keys, …/rotate, …/versions/:v/revoke, …/sign, …/decapsulate, quantum/verify@quantlayer-protocol/pqc-engine (FIPS 203/204/205 in Rust)
AuthorizationModuleauthorization/policies, …/minimum-version, authorization/revocations, authorization/decisions@quantlayer-protocol/authorization hybrid engine with Postgres-backed ports
BlockchainModuleblockchain/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: false and the failed check.
  • A job that can't be proven is reported as failed. The job ends failed with 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):

PrincipalFormatObtained byUsed for
API keyquantlayer_sk_<id>_<secret>A project owner, via POST /v1/developer/projects/:id/api-keysServer-to-server integration. Scoped (16 scopes, listed per operation in OpenAPI as x-quantlayer-scopes).
Wallet sessionquantlayer_ss_<token>Wallet sign-in: POST /v1/auth/wallet/challenge, then EIP-712 QuantLayerSignIn signed with eth_signTypedData_v4, then POST /v1/auth/wallet/verifyManaging projects and keys. The session carries the wallet's DID when it is linked.
Administratorquantlayer_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:

    • composeSignatureVerifiers combines @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 as ProtectedKey blobs sealed by Rust under HKDF(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.
  • Credential issuers. Each issuer is a did:quantlayer identity 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:

    1. The API encapsulates (ML-KEM-768) to the platform sealing key.
    2. It derives AES-256-GCM with HKDF-SHA256, salted and AAD-bound to the job id.
    3. Only ciphertext is enqueued.
    4. The worker decapsulates in custody, proves, and drops the plaintext.
    5. 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.
  • 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, then confirmed once it has CHAIN_CONFIRMATIONS confirmations;
  • failed if it reverted;
  • dropped if it was never mined within CHAIN_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. QuantLayerCredentialRegistry logs 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_status and are appended to credential_status_events (source chain), alongside the API's own status changes (source api).
  • Roots. RootPublished and RootRevoked feed 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 } }. reason carries 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-Remaining and RateLimit-Reset. Over budget, the response is 429 RATE_LIMITED with Retry-After.

  • Logs. Structured pino JSON with req.id and traceId. Secrets and credential or witness fields are redacted.

  • Metrics and tracing. See infrastructure/monitoring.

  • HTTP hardening.

    • Security headers: nosniff, DENY framing, default-src 'none' CSP, no-store.
    • A body size limit (BODY_LIMIT_BYTES).
    • CORS only for CORS_ORIGINS.
    • TRUST_PROXY only behind a proxy that sets X-Forwarded-For.

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 --build

Integration 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 with prisma migrate deploy;
  • real Redis: redis-memory-server, or TEST_REDIS_URL;
  • real cryptography;
  • a real EVM (anvil 1.7.1), with QuantLayerCredentialRegistry deployed from the Foundry build.
AreaWhat the tests cover
DeveloperHealth; request ids and W3C tracing; error shapes; metrics; OpenAPI; wallet sign-in (replay, tampering, wrong signer); scoped keys; revocation; project suspension; audit; rate limiting
QuantumML-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
IdentitySelf-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
CredentialsML-DSA-65 custody issuer; holder acceptance; selective disclosure; binding and trust failures; revocation through the signed status list; status history
ProofsPoseidon tree; sealed witness (Redis inspected); Noir/UltraHonk proving in the worker; verification; nullifier spent once; tampering; unsatisfiable witness failing without retry
AuthorizationEd25519 and ML-DSA-65 decisions; replay; emergency revocation; policy retirement; project isolation; evidence-free decision log
BlockchainConfirmations; reverts; drops; reorg re-opening; honest 503 without RPC; credential status and root indexing up to the safe head; idempotency
OpenAPICommitted document equals the code; every route declared, summarized and secured