Circom¶

Overview¶

Circom is a Domain-Specific Language (DSL) for defining arithmetic circuits, specifically designed for generating zero-knowledge proofs. Developed by the iden3 team, it is a core tool for building zkSNARK applications.

Circom allows programmers to design circuits with custom constraints, and the compiler outputs R1CS (Rank-1 Constraint System) representations, which are a key format needed for generating zero-knowledge proofs.

Core Features¶

Modular Design: Circom's main feature is its modularity, allowing programmers to define parameterizable circuit templates that can be instantiated to form larger circuits.

Compilation Output: The Circom compiler, written in Rust, can generate: - R1CS files and associated constraint sets - Programs written in C++ or WebAssembly for efficiently computing valid assignments of all circuit wires

Flexible Compilation Targets: Supports compilation to multiple formats, including R1CS, C++, WASM (WebAssembly), and WAT.

Technical Principles¶

Constraint System: Circuits written in Circom define a set of constraint conditions that must be satisfied to generate valid zero-knowledge proofs.

Core Concepts:

Witness: The information that needs to be kept secret. If certain inputs to a circuit need to be confidential, they are part of the witness set. A zero-knowledge proof can prove that you know a set of signals (witness) that satisfy all constraints, without revealing any signals beyond public inputs and outputs.
R1CS (Rank-1 Constraint System): The circuit is compiled into R1CS format, representing all wires in the circuit so they can be checked to generate proofs. The R1CS protocol enables algebraic circuits to be represented as sets of vectors and matrices.
QAP (Quadratic Arithmetic Program): R1CS is further transformed into a collection of polynomials for the QAP protocol, which then feeds into the rest of the zkSNARK pipeline.

Ecosystem Tools¶

SnarkJS: A JavaScript library for generating and verifying ZK proofs from R1CS. Written in pure JavaScript and Pure WebAssembly.

Circomlib: A publicly available library containing hundreds of circuit templates, including: - Comparators - Hash Functions - Digital Signatures - Binary and decimal converters - Many more utility circuits

Security Analysis Tools: - Circomspect: A static analyzer and linter for detecting common vulnerabilities in Circom circuits, extending the checks performed by the circom --inspect flag - CIVER: A security verification tool - Ecne: A static analyzer - PICUS: A security verification static analyzer - ZKAP: A vulnerability detection tool

Development Tools: - Hardhat-zkit: A TypeScript environment for circom development - Circomkit: Testing and development environment

Workflow¶

Complete Development Flow:

Write Circuits: Define constraints and circuit logic using the Circom language
Compile Circuits: Use the Circom compiler to compile circuits into R1CS and witness generation programs
Generate Witness: Run the witness generation program with private and public inputs
Generate Proof: Use SnarkJS and the witness to generate a zkSNARK proof
Verify Proof: Verify the proof's validity using the verification key
On-Chain Verification (Optional): Deploy a Solidity verification contract to Ethereum for on-chain verification

Version Updates¶

Circom 2.0 (2022): Major update providing better performance and new features.

Circom 2.2.0 (October 2024): Introduced new features including Buses functionality.

Circom 2.2.2 (March 2025): Latest version, adding the new prime bls12377 and r1cs reader.

Notable Use Cases¶

Circom has been adopted by several well-known projects, proving its effectiveness and reliability:

Polygon Hermez: Uses Circom to build zkEVM circuits
Tornado Cash: Privacy transaction protocol uses Circom to implement mixing functionality
Dark Forest: On-chain game uses zero-knowledge proofs to hide player positions
Zkopru: Privacy Rollup solution on Ethereum
Polygon ID: Sovereign identity system implemented using the iden3 protocol and Circom 2.0

Polygon ID Integration¶

Polygon ID implements zk-SNARKs, leveraging the innovations of the iden3 sovereign identity protocol and the Circom 2.0 arithmetic circuit framework. The protocol uses the iden3 protocol and Circom ZK toolkit to provide a private identity solution for creating trusted interactions in Web3.

Security Considerations¶

May 2024 Security Audit: Trail of Bits conducted a security audit of iden3 circuits and published a report.

Common Vulnerabilities: Circomspect can detect various potential issues, including: - Security issues when using Circomlib's Num2Bits and Bits2Num to convert field elements - Only safe when input size is less than the prime size - Under-constraint issues due to insufficient constraints - Integer overflow risks

Learning Resources¶

English Tutorials: - Circom 2 Documentation - zkSNARK Crashcourse with Circom and SnarkJS - Circom language tutorial with circomlib walkthrough - RareSkills - R1CS Explainer - 0xPARC

Official Resources: - GitHub - iden3/circom - GitHub - iden3/circuits - iden3 Official Website - Iden3 Blog - Circom 2.0 Release

Advantages and Challenges¶

Advantages: - Modular design with reusable code - Rich libraries and templates (Circomlib) - Strong toolchain ecosystem - Validated by multiple production projects - Active community and continuous updates - Comprehensive security analysis tools

Challenges: - Steep learning curve - Requires understanding of constraint systems and zero-knowledge proof principles - Circuit optimization requires experience - High security requirements necessitate careful auditing

Future Development¶

Circom continues to evolve, with 2024-2025 updates showing the project is still under active development. As zero-knowledge proof applications grow, Circom's position as the preferred developer tool will continue to solidify.