Build Big Circuits from Small Pieces (Templates and Components)

Why this matters

Circom circuits scale by composition. A template defines a parameterised circuit (e.g., 'a Merkle-path verifier for depth d'). Instantiating a template creates a component. Components can include other components. This is how circomlib gives you a Poseidon hash over any 2-element input, or a Merkle proof over any depth — by exposing templates parameterised on the relevant dimensions. Understanding the difference between templates and components, and how template parameters differ from signals, is the foundation of writing clean Circom.

Demo

A Multiplier template that's parameterised on N — the number of inputs. Instantiate with N=3 to multiply three numbers. N is a compile-time parameter (known when circom generates R1CS); signals are witness-time values.

pragma circom 2.1.6;
 
template NMultiplier(N) {
    signal input in[N];
    signal output out;
 
    signal acc[N];
    acc[0] <== in[0];
    for (var i = 1; i < N; i++) {
        acc[i] <== acc[i-1] * in[i];
    }
    out <== acc[N-1];
}
 
component main = NMultiplier(3);
// Witness: in = [2, 3, 5] → out = 30.

Try it yourself

1. Run the NMultiplier for N=3, 5, 10. Count constraints — expect N-1 (one per multiplication). Linear-in-N is the expected shape.
2. Try to use a signal (not a template parameter) for N: NMultiplier(n) where n is a signal. Compile fails: template parameters MUST be compile-time. This constraint is the most surprising to programmers from dynamic languages.
3. Replace the for-loop with a non-const bound (for (var i = 0; i < in[0]; i++)): compile fails. Circom's unrolling requires compile-time bounds.
4. Build a Poseidon hash of 3 inputs using circomlib's Poseidon template. Inspect the resulting constraint count (~210 for Poseidon-3). This is 30× cheaper than SHA-256 for the same security level in a SNARK context.
5. Read circomlib's sha256 template and note the massive expansion when it decomposes bytes into bits. Compare constraint count to Poseidon and understand why SNARK-friendly hash choice matters.

References

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