- 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
- 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-BN254with the new kindfield-hash, behind theFieldHasherport. - Byte hash: SHA-256 for hash-to-field (drop the first digest byte to get 248 uniform bits), off-chain only.
- 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. - Constructions, all standard: the hash commitment
H(tag, v, r); Semaphore-style identity commitmentsH(tag, s, t)and nullifiersH(tag, s, scope); and a fixed-depth incremental Merkle tree with an empty leaf of 0 and index-bit paths decomposed byNum2Bits. - 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.
- Canonical encoding: field elements are
< peverywhere and never reduced silently. Wire format is 0x plus 64 hex digits; circuit format is canonical decimal. - One vector file, two checkers:
circuits/vectors/privacy-v1.jsonis generated by TypeScript, checked by@quantlayer-protocol/privacytests, and checked by a Circom witness run in CI (circuitsjob). Static source drift tests run without circom. - Fail-closed composition:
createPrivacySuiteverifies 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).