0012. Privacy primitives: Poseidon-BN254 and Circom

Design document, published from the repository at docs/adr/0012-privacy-primitives.md.

  • Status: Accepted
  • Date: 2026-11-13

Context

QuantLayer's zero-knowledge statements (anonymous membership, credential validity, balance thresholds) need commitments, nullifiers and Merkle membership that are computed identically in TypeScript (holders, verifiers, indexers) and inside circuits. A mismatch of even one encoding rule makes proofs unprovable, or worse, lets one value appear under two encodings. ADR-0007 deferred circuit-language and hash choices until this point.

Decision

  1. Circuit hash: Poseidon over the BN254 scalar field with the circomlib parameters (x⁵, RF = 8, circomlib partial rounds, Grain-LFSR constants). In TypeScript this is @noble/curves' audited permutation with regenerated constants, pinned by published circomlib known-answer vectors. It is registered as algorithm Poseidon-BN254 with the new kind field-hash, behind the FieldHasher port.
  2. Byte hash: SHA-256 for hash-to-field (drop the first digest byte to get 248 uniform bits), off-chain only.
  3. Circuit framework: Circom 2 (≥ 2.1.6) with circomlib 2.0.5 (exact pin), targeting Groth16/PLONK over BN254 via snarkjs. Shared templates live in circuits/lib/quantlayer.circom. The production membership circuit has depth 20.
  4. Constructions, all standard: the hash commitment H(tag, v, r); Semaphore-style identity commitments H(tag, s, t) and nullifiers H(tag, s, scope); and a fixed-depth incremental Merkle tree with an empty leaf of 0 and index-bit paths decomposed by Num2Bits.
  5. Domain separation: each field domain has a fixed arity of 2 and its tag as the first input. A tag is the ASCII label read big-endian, and every label carries a version.
  6. Canonical encoding: field elements are < p everywhere and never reduced silently. Wire format is 0x plus 64 hex digits; circuit format is canonical decimal.
  7. One vector file, two checkers: circuits/vectors/privacy-v1.json is generated by TypeScript, checked by @quantlayer-protocol/privacy tests, and checked by a Circom witness run in CI (circuits job). Static source drift tests run without circom.
  8. Fail-closed composition: createPrivacySuite verifies the injected hashers against known answers before use.

Consequences

  • TypeScript and circuits share a single specification (SECURITY_NOTES.md), with machine-checked vectors.
  • CI needs a circom toolchain, built from the pinned release tag and cached.
  • Poseidon is not NIST/IETF-standardized and nothing here is post-quantum. Constructions are versioned by label, so a future suite (Poseidon2, another field, a PQ proof system) is additive.
  • Verifier deployments must store nullifiers atomically per (scope, nullifier) and namespace scopes per application.
  • Trusted setup, proving backends and on-chain verifiers remain open (a later task).