Circomkit-ffi NPM

This repository contains an all-in-one adapter for several backends, mainly to be used by existing Javascript code via FFI. It features prover backends via Lambdaworks Circom adapter for Groth16 over BLS12-381 and Arkworks Circom adapter for Groth16 over BN254. It also provides SnarkJS exports for both prover backends, to export proof objects and public signals.

Installation

The FFI libraries are exposed through an SDK, which is published on NPM.

npm install circomkit-ffi

The libraries are kept under this repository's releases. It supports the following platforms & architectures:

Linux amd64
Linux arm64
MacOS Intel (amd64)
MacoS Apple Silicon (arm64)

The library will be automatically downloaded when required by the SDK.

Usage

The SDK exposes two types of classes:

CircomkitFFIBun is exported at /circomkit-ffi/bun and uses bun:ffi and must be used within a Bun runtime.
CircomkitFFINode uses ffi-rs and can be used by both Bun and Node.

!NOTE
CircomkitFFINode has a peer dependency for ffi-rs as well:
npm install ffi-rs

Downloading the library

First you need to download the library suited to your machine. We provide some utilities for this:

import { downloadRelease, getLibPath } from "circomkit-ffi";
import { existsSync } from "fs";

// you can point to any directory for the library to be downloaded at:
const libDir = "~/path/to/somewhere";

// you can get the path to library with `getLibPath`, it will attach the machine information to the file,
// e.g.: on MacOS & Apple Silicon it will be:
//   ~/path/to/somewhere/libcircomkit_ffi-macOS-arm64.dylib
const libPath = getLibPath(libDir);

// now we can download if needed
if (!existsSync(libPath)) {
  console.info("Downloading FFI library.");
  await downloadRelease(libDir);
}

Preparing Node SDK

The Node SDK is exported from /node path, and requires ffi-rs as a peer dependency.

import { CircomkitFFINode } from "circomkit-ffi/node";
import { open, load, close } from "ffi-rs";

// assume library exists at path `libPath`
const lib = new CircomkitFFINode(libPath, open, close, load);

Preparing Bun SDK

The Bun SDK is exported from /bun path, and works only for Bun runtime; trying to import this within Node runtime will cause an error.

import { CircomkitFFIBun } from "circomkit-ffi/bun";

// assume library exists at path `libPath`
const lib = new CircomkitFFIBun(libPath);

Using the SDK

We are all set! We now have access to all the functions within our static library. For example, we can call arkworks_prove to generate a proof using Arkworks. We just have to provide the necessary paths to R1CS, witness file and the prover key.

We can use a Circomkit instance to get these paths, but they can be manually written as well:

const { proof, publicSignals } = circomkitFFI.arkworks_prove(
  circomkit.path.ofCircuitWithInput(circuitName, inputName, "wtns"),
  circomkit.path.ofCircuit(circuitName, "r1cs"),
  circomkit.path.ofCircuit(circuitName, "pkey")
);

!TIP
If for any reason you have to know whether you are in Bun or Node, you can use the isBun function exported by our SDK.

Development

Clone the repository:

git clone https://github.com/erhant/circomkit-ffi

Note that Arkworks requires a Tokio runtime, even if nothing has to be awaited.

Library

The library called by FFI is written in Rust. You can build the library (for your own machine) using:

cargo build

You can run the tests with:

cargo test

Before running tests:

you need to have installed SnarkJS globally, to verify that the FFI-generated proof is valid.
you need generated circuit files, which can be done with the command below.

# preparations (do only once)
cd example
bun install

# create circuit (e.g. multiplier_3) artifacts for tests
CIRCUIT=multiplier_3
bunx circomkit witness $CIRCUIT default
bunx circomkit prove $CIRCUIT default
bunx circomkit json wtns $CIRCUIT default
bunx circomkit json r1cs $CIRCUIT

!TIP
You can take the library directly from within /target/debug/libcircomkit_ffi.<your-extension> and use with the SDK, for easier debugging with the SDK tests.