This crate provides a fast witness generator for Circom circuits, serving as a drop-in replacement for Circom's witness generator. It was created in response to the slow performance of Circom's WASM generator for larger circuits, which also necessitates a WASM runtime, often a cumbersome requirement. Although the native C++ generator is faster, it requires embedding itself into a compiled binary, which is not always desirable. The idea is to have a universal library that can calculate the witness for any Circom circuit without the need for a WASM runtime or embedding a C++ binary.

circom-witnesscalc comes with two executables:

1. build-circuit command to build a Circom circuit. As a result, you will get a binary file of graph operations to calculate the witness for a circuit.
2. calc-witness command uses the generated binary file and circuit inputs to generate a witness. This functionality is also availabe as a Rust or C library API.

The project originally inspired by circom-witness-rs.

This project also includes an alternative witness calculation method using the Circom Virtual Machine (CVM). The CVM approach provides a different compilation pipeline for witness generation.

Note: The CVM feature is not production ready and is currently in active development. Users are welcome to file bug reports if they encounter circuits where it does not work correctly.

For detailed documentation on using the CVM-based witness calculator, including:

• Building and using the cvm-compile tool
• Single-step vs two-step compilation modes
• Testing with the test_circuits_vm2.sh script
• Integration with the circom_cvm fork

See cvm.md for complete instructions.

There are some Circom features that are not yet implemented. If you need these features, please open an issue with the Circom circuit that doesn't work. In the near future, we plan to add support for using input signals in the loop condition to accommodate circuits that uses the long_div function from the zk-email project.

To create a circuit graph file from a Circom 2 program, run the following command:

# Using compiled binary
./build-circuit <path_to_circuit.circom> <path_to_circuit_graph.bin> [-l <path_to_circom_libs/>]* [-i <inputs_file.json>]
# Or using `cargo` from the root of the repository
cargo run --package circom-witnesscalc --bin build-circuit <path_to_circuit.circom> <path_to_circuit_graph.bin> [-l <path_to_circom_libs/>]* [-i <inputs_file.json>]

Run ./build-circuit --help to see the available options.

To build on Ubuntu you need to install clang-19 and protobuf-compiler packages.

To generate a witness file from a circuit graph and inputs, run the following command.

# Using compiled binary
./calc-witness <path_to_circuit_graph.bin> <path_to_inputs.json> <path_to_output_witness.wtns>
# Or using `cargo` from the root of the repository
cargo run --package circom-witnesscalc --bin calc-witness <path_to_circuit_graph.bin> <path_to_inputs.json> <path_to_output_witness.wtns>

To run circuits tests, we need to make some manual setup

# Update the git submodules to checkout all required dependencies
git submodule update --init --recursive
# Install dependencies for iden3 authV2 circuits
pushd test_deps/iden3-circuits-authV2
npm install
popd
# Install dependencies for master branch of iden3 circuits
pushd test_deps/iden3-circuits-master
npm install
popd

Also, you need to have the following commands installed: circom, snarkjs, curl, cargo, node and cmp.

Now run the test_circuits.sh script.

./test_circuits.sh

To verify that circuits work with the older graph format (v1), you need to test against the build-circuit from version v0.1.1.

1. Clone and build the v0.1.1 version:

git clone --branch build-circuit/v0.1.1 https://github.com/iden3/circom-witnesscalc.git ~/src/circom-witnesscalc-build-circuit-v0.1.1
cd ~/src/circom-witnesscalc-build-circuit-v0.1.1
cargo build --release -p build-circuit

2. Run tests with the old build-circuit and the graph_v1 tag:

./test_circuits.sh -b ~/src/circom-witnesscalc-build-circuit-v0.1.1/target/release/build-circuit -t graph_v1

Circuits not compatible with graph_v1 (tagged with !graph_v1) will be skipped.

cargo build --target aarch64-apple-ios --release
cargo build --target aarch64-apple-ios-sim --release
install_name_tool -id @rpath/libcircom_witnesscalc.dylib $PWD/target/aarch64-apple-ios/release/libcircom_witnesscalc.dylib
install_name_tool -id @rpath/libcircom_witnesscalc.dylib $PWD/target/aarch64-apple-ios-sim/release/libcircom_witnesscalc.dylib

You should have ANDROID_NDK_ROOT environment variable set to the path to the Android NDK. It may be somewhere like ~/Library/Android/sdk/ndk/26.2.11394342.

CC=${ANDROID_NDK_ROOT}/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android29-clang \
CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=${CC} \
CLANG_PATH=${CC} \
cargo build --target aarch64-linux-android --release

CC=${ANDROID_NDK_ROOT}/toolchains/llvm/prebuilt/darwin-x86_64/bin/x86_64-linux-android29-clang \
CARGO_TARGET_X86_64_LINUX_ANDROID_LINKER=${CC} \
CLANG_PATH=${CC} \
cargo build --target x86_64-linux-android --release

If you have cargo-ndk installed, you can build the project, for example, with the following command:

cargo ndk --target aarch64-linux-android build --release