Circomkit

A simple-to-use & opinionated circuit development & testing toolkit.

Installation

Circomkit is an NPM package, which you can install via:

yarn add circomkit    # yarn
npm install circomkit # NPM

You will also need Circom, which can be installed following the instructions here.

Usage

Create an empty project, and install Circomkit. Then, you can setup the environment by simply executing:

npx circomkit init

This command creates the following:

• An example Multiplier circuit, under circuits folder.
• A circuit configuration file called circuits.json, with an example Multiplier circuit configuration.
• An example input JSON file for Multiplier, under inputs/multiplier folder.
• A test using Mocha, under tests folder.
• A Mocha configuration file.

Although Circomkit initializes with a Mocha test, uses Chai in the background so you could use anything that supports Chai.

Configuration

A circuit config within circuits.json looks like below, where the key is the circuit name to be used in commands, and the value is an object that describes the filename, template name, public signals and template parameters:

sudoku_9x9: {
  file:     'sudoku',
  template: 'Sudoku',
  pubs:     ['puzzle'],
  params:   [3], // sqrt(9)
},

You can omit pubs and params options, they default to [].

Command Line Interface

Actions that require a circuit name can be called as follows:

# Compile the circuit
npx circomkit compile circuit

# Create the main component
npx circomkit instantiate circuit

# Create a Solidity verifier contract
npx circomkit contract circuit

# Clean circuit artifacts
npx circomkit clean circuit

# Circuit-specific setup
npx circomkit setup circuit [ptau-path]

Circuit-specific setup optionally takes the path to a PTAU file as argument. If not provided, it will automatically decide the PTAU to use with respect to constraint count, and download it for you! This feature only works for bn128 curve.

Some actions such as generating a witness, generating a proof and verifying a proof require JSON inputs to provide the signal values. For that, we specifically create our input files under the inputs folder, and under the target circuit name there. For example, an input named foo for some circuit named bar would be at inputs/bar/foo.json.

# Generate a witness
npx circomkit witness circuit input

# Generate a proof
npx circomkit prove circuit input

# Verify a proof with public signals
npx circomkit verify circuit input

# Export Solidity calldata to console
npx circomkit calldata circuit input

File Structure

Circomkit follows an opinionated file structure, abstracting away the pathing and orientation behind the scenes. All of these can be customized by overriding the respective settings in circomkit.json.

Here is an example structure, where we have a generic Sudoku proof-of-solution circuit, and we instantiate it for a 9x9 board:

circomkit
├── circuits.json # circuit configs
├── circomkit.json # customizations
│
├── circuits
│   ├── main
│   │   └── sudoku_9x9.circom
│   └── sudoku.circom
│
├── inputs
│   └── sudoku_9x9
│       └── my_solution.json
│
├── ptau
│   └── powersOfTau28_hez_final_12.ptau
│
└── build
    └── sudoku_9x9
        │── sudoku_9x9_js
        │   │── generate_witness.js
        │   │── witness_calculator.js
        │   └── sudoku_9x9.wasm
        │
        │── my_solution
        │   │── proof.json
        │   │── public.json
        │   └── witness.wtns
        │
        │── sudoku_9x9.r1cs
        │── sudoku_9x9.sym
        │── prover_key.zkey
        └── verifier_key.json

Testing

To run tests do the following:

# test a specific circuit
yarn test <circuit-name>

# test all circuits
yarn test:all

You can test both witness calculations and proof generation & verification. We describe both in their respective sections, going over an example of "Multiplication" circuit.

Styling

Circomkit uses Google TypeScript Style Guide.

# check the formatting
yarn format

# lint everything
yarn lint

# do both at once
yarn style