- Status: Accepted
- Date: 2026-11-13
Context
QuantLayer needs a production backend over the protocol packages built so far. It must expose
identities, credentials, privacy, zero-knowledge proofs, post-quantum cryptography,
authorization, chain monitoring and a developer platform. It must also keep private keys and
ZK witnesses out of ordinary storage. Earlier stages left a minimal NestJS/Express API and
three placeholder services (proof-worker, credential-worker, indexer) with no logic.
Decision
One backend codebase (
apps/api) with three process roles from one image:api,workerandindexer. They replace the placeholder services and share the Prisma schema, migrations and crypto composition, so a schema change can't drift between processes.The stack:
- NestJS 12 on Fastify;
- PostgreSQL with Prisma 7 (driver adapter, Rust-free client);
- Redis with BullMQ 6 for jobs, rate limits and single-use challenges;
- Zod 4 for every request and response.
OpenAPI 3.1 is generated from the same
@Endpointdeclarations, so validation, authorization, rate limiting and documentation share one source. A committeddocs/api/openapi.jsonis checked in tests.Three PostgreSQL schemas:
metafor public metadata,vaultfor sealed key material, andsensitivefor field-encrypted user data, blind indexes and verifiers. One root KEK derives every data key with HKDF and a purpose label.Stateless custody per operation. Keys stay inside the QuantLayer Quantum Rust module, so no replica holds long-lived secret state. Key rings in Postgres are the source of truth.
Delegated proving seals the witness (ML-KEM-768 + AES-256-GCM) at the API boundary. Queues and databases only ever see ciphertext and public outputs.
Authentication:
- scoped project API keys;
- EIP-712 wallet sign-in creating sessions;
- a bootstrap administrator key.
All of them are stored as HMAC verifiers only.
Fail honestly. Unconfigured or unavailable capabilities return
503, invalid cryptography is reported as such, and the backend never signs chain transactions or attestations it holds no key for.
Consequences
- Testing. Integration tests run against real PostgreSQL, Redis, cryptography and an anvil node. CI provides Postgres and Redis as service containers; locally they are embedded.
- Accepted limitations:
- Merkle trees are rebuilt from the leaves on each mutation (O(n) Poseidon hashes per insert). An incremental-tree cache is follow-up work for large trees.
- Fetching a Merkle path tells the server which leaf a holder is interested in.
- Delegated proving exposes the witness to the worker's memory; client-side proving remains the recommendation.
- Operations: run
migratebefore deployment, injectQUANTLAYER_KEKfrom a KMS, and keep Redis without shared persistence. - Production follow-up:
- a KMS-backed
KeyEncryptionKeyProvider; - KEK rotation tooling;
- separate database roles per schema;
- an attestor service for FEAT-09's attested modes.
- a KMS-backed