Using circomlib — Don't Roll Your Own

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

1. Clone circomlib. Browse the circuits/ directory: count templates (~60). Read the headers of 5 commonly-used ones.
2. Compile the MerklePath(20) circuit. Note the constraint count (~4000). Poseidon(2) is ~210 constraints × 20 levels ≈ 4200.
3. Replace Poseidon with Pedersen (also in circomlib). Measure constraint count. Poseidon is usually cheaper for SNARKs; Pedersen is sometimes preferred for specific properties.
4. 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.
5. 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.

References

• Circom 2 Documentation — Getting Started
• iden3 — snarkjs README
• 0xPARC — Circom Workshop (Ya-Wen Jeng)
• Vitalik — QAPs from Zero to Hero