taceo-circom-lib

Circom library for TACEO ecosystem, structured like circomlib so it can be pulled into other repos as a dependency.

Usage

Add it to your project via pnpm (or npm/yarn):

pnpm add @taceo/circom-lib

circomlib is a peer dependency: some circuits (e.g. precomputations.circom, and compression.circom/babyjubjub.circom through it) include circomlib templates. pnpm 8+ and npm 7+ install it automatically; otherwise add it explicitly with pnpm add circomlib.

Include circuits by their package-qualified path and compile with a single -l node_modules:

include "@taceo/circom-lib/circuits/compression.circom";

component main = Compression(4, 4);

circom your_circuit.circom --r1cs --wasm -l node_modules

Within the library, circuits reference each other by bare filename (e.g. poseidon2.circom includes poseidon2_constants.circom), since circom resolves bare includes relative to the including file first. circomlib templates are referenced by package-qualified path (e.g. circomlib/circuits/bitify.circom), which is why circomlib must be installed for the -l node_modules root to resolve them.

Circuits

• poseidon2.circom: Poseidon2 permutation over the BN254 scalar field for state sizes t ∈ {2, 3, 4, 8, 12, 16}
• compression.circom: public input compression via hybrid compression: Poseidon2-based sponges (Poseidon2Sponge, Poseidon2SpongeWithDs), a universal hash function (UHF), and Compression combining both with a fixed domain separator
• precomputations.circom: TACEO_PRECOMPUTATION_* wrappers around Poseidon2 and circomlib primitives (Num2Bits, IsZero, AliasCheck), for MPC-proving
• babyjubjub.circom: BabyJubJub curve operations (curve/subgroup checks, scalar multiplication, ...)
• eddsa_poseidon2.circom: EdDSA signature verification using Poseidon2
• binary_merkle_root.circom: binary Merkle root from a membership proof (adapted from zk-kit, using Poseidon2 in compression mode), with dynamic depth up to MAX_DEPTH and enforcement that path bits beyond the depth are zero. There is no domain separation between tree layers; domain-separate leaves before passing them in (see the note in the circuit)

The poseidon2, eddsa_poseidon2, and babyjubjub circuits are pulled from the audited repository for TACEO:OPRF.

MPC-proving

precomputations.circom provides TACEO_PRECOMPUTATION_* wrappers around Poseidon2 and circomlib primitives (Num2Bits, IsZero, AliasCheck) for use with the TACEO MPC-proving stack.

Public input compression

compression.circom implements the in-circuit side of hybrid compression (Khovratovich, Vladimirov, Wagner: "Data Matching in Unequal Worlds and Applications to Smart Contracts"). Long statements are expensive as Groth16 public inputs, and hashing them is expensive either on-chain (Poseidon in gas) or in-circuit (Keccak/SHA-256 in constraints). Hybrid compression uses both worlds' cheap hash: the statement q moves into the witness, the contract computes alpha (Keccak256 of q, truncated to the scalar field), the circuit computes beta (Poseidon2 sponge of q), and both evaluate the universal hash gamma = UHF(alpha + beta, q). The verifier then only checks the proof against the three public inputs (alpha, beta, gamma); soundness reduces to the joint UHF hardness of the two hash functions.

Tests

pnpm install
pnpm test

Known-answer test vectors for the sponge, UHF, compression, and binary Merkle root circuits live in tests/kats/ and are generated by python3 scripts/generate_kats.py, which reimplements the primitives in pure Python and self-checks against the Poseidon2 permutation vectors before writing.