Using circomlib — don't roll your own

hard

Learn with your AI

Open this lesson in your favourite AI. It'll walk you through the why, explain the demo, and quiz you on the try-it list.

Open in Claude Open in ChatGPT

Why this matters

circomlib is the iden3-maintained standard library of Circom primitives. It has Poseidon (SNARK-friendly hash), MiMC, SHA-256, Merkle trees, Edwards curve arithmetic, EdDSA signatures, and comparators. Every template in circomlib has been audited and used in production by Tornado Cash, Semaphore, Hermez, and many rollups. You should NEVER roll your own Poseidon or your own bit decomposition in a production circuit — the number of Circom bugs from custom implementations is staggering. This task is a tour of circomlib's structure.

Demo

A simple Merkle-path verifier using circomlib's Poseidon and MerkleTreeInclusionProof. Five lines of Circom + proper circomlib imports = a working membership proof for a 20-level tree (1M leaves).

pragma circom 2.1.6;
include "circomlib/circuits/poseidon.circom";
include "circomlib/circuits/mux1.circom";
 
template MerklePath(levels) {
    signal input leaf;
    signal input path_indices[levels];
    signal input path_elements[levels];
    signal output root;
 
    signal cur[levels+1];
    cur[0] <== leaf;
 
    component hashers[levels];
    component muxes[levels];
 
    for (var i = 0; i < levels; i++) {
        muxes[i] = Mux1();
        muxes[i].c[0] <== cur[i];
        muxes[i].c[1] <== path_elements[i];
        muxes[i].s    <== path_indices[i];
        // Left or right child depending on path_indices[i]
 
        hashers[i] = Poseidon(2);
        hashers[i].inputs[0] <== muxes[i].out;
        hashers[i].inputs[1] <== path_indices[i] * (path_elements[i] - cur[i]) + cur[i];
        cur[i+1] <== hashers[i].out;
    }
    root <== cur[levels];
}
 
component main { public [root] } = MerklePath(20);

Try it yourself

Clone circomlib. Browse the circuits/ directory: count templates (~60). Read the headers of 5 commonly-used ones.

Compile the MerklePath(20) circuit. Note the constraint count (~4000). Poseidon(2) is ~210 constraints × 20 levels ≈ 4200.

Replace Poseidon with Pedersen (also in circomlib). Measure constraint count. Poseidon is usually cheaper for SNARKs; Pedersen is sometimes preferred for specific properties.

Look at circomlib's eddsa.circom. Understand what's happening: curve point operations, signature verification, all expressed as R1CS constraints. ~4000 constraints per signature verification.

Use circomlib/templates/sha256/sha256.circom. Compare its constraint count to Poseidon for hashing the same 32 bytes. Expect ~30× difference. This is why SNARK circuits use Poseidon instead of SHA-256 when they can.

Prompt your AI

Use these three in order. Each builds on the one before.

1. Basics & terminology

In one paragraph, explain what circomlib is, why you should use its primitives rather than rolling your own, and what the five most-used templates are (Poseidon, IsZero, Mux, Num2Bits, MerkleProof).

2. Why it works (the mechanism)

Walk me through circomlib's Poseidon template: what are the round constants, what's the permutation, and why is this specifically designed to be SNARK-friendly (few multiplications, low degree)?

3. Advanced — application & what's next

I'm building a zk-identity protocol that needs: EdDSA signature verification, Merkle membership in a 2^30-leaf tree, and a nullifier. Walk me through the circomlib templates I'd chain together, the approximate constraint count, and where the bottleneck is.