0017. Backend architecture

Design document, published from the repository at docs/adr/0017-backend-architecture.md.

  • 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

  1. One backend codebase (apps/api) with three process roles from one image: api, worker and indexer. They replace the placeholder services and share the Prisma schema, migrations and crypto composition, so a schema change can't drift between processes.

  2. 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 @Endpoint declarations, so validation, authorization, rate limiting and documentation share one source. A committed docs/api/openapi.json is checked in tests.

  3. Three PostgreSQL schemas: meta for public metadata, vault for sealed key material, and sensitive for field-encrypted user data, blind indexes and verifiers. One root KEK derives every data key with HKDF and a purpose label.

  4. 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.

  5. 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.

  6. 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.

  7. 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 migrate before deployment, inject QUANTLAYER_KEK from 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.