circkit¶

circkit is a small framework for defining, constructing and manipulating computational circuits. It aims to be very generic. circkit supports both low-level circuits such as bit-based operations, word-based operations, arithmetic circuits over a ring and high-level circuits made up by gates (nodes) which are customized non-primitive functions.

circkit provides 3 types of built-in circuits, including arithmetic circuit, boolean circuit and bitwise circuit. Additionally, it provides ISW transformer which is able to transform a boolean circuit into a new boolean circuit whose nodes are the shares as in the ISW scheme.

Specially, circkit allows users to define new circuit types in which nodes can be their customized operations or functions. It also allows to define a new transformer which provides the convenience of transforming a source circuit to a target circuit. See the tutorials for more details.

Installation¶

For arithmetic circuits working on finite fields, it needs to install Sagemath. For circuits working on decimal numbers, integers, boolean and bitwise, it is not necessary to install Sagemath.

Circuits with Sagemath¶

Install Sagemath.
Install circkit in Sagemath:

via PyPI:

sage -pip install circkit

or via setup.py:

sage -pip install .

Run your script with Sagemath:

sage -python script.py

Or you can open a notebook with Sagemath and build your circuit with the circkit framework:

sage -n

Circuits without Sagemath¶

Install circkit:

via PyPI:

pip3 install circkit

or via setup.py:

pip3 install .

Run your python script, for example:

python3 script.py

Using virtual environment¶

We can use a virtual enviroment to run both circuits with and without Sagemath.

Create a virtual environment of Sagemath:

sage -python -m venv --system-site-packages .venv

Then, go to the virtual enviroment:

source .venv/bin/activate

Install circkit in the virtual environment.

via PyPI:

pip install circkit

or via setup.py:

pip install .

Run your script on the virtual enviroment, for example:

python script.py

Or you can open a python notebook in this virtual enviroment and build your circuit.

Quick example¶

from circkit.arithmetic import ArithmeticCircuit

# Step 1: Initialize a new arithmetic circuit
C = ArithmeticCircuit()

# Step 2: Define the input nodes
a = C.add_input("a")
b = C.add_input("b")

# Step 3: Perform the computation
x = a + b + 5
y = 2 * a - 3

# Step 4: Define the output nodes
C.add_output(x)
C.add_output(y)
# To see the graph of the circuit
C.digraph().view()

# Step 5: Evaluate the circuit
# For example, a = 7, b = 9
inp = [7, 9]
out = C.evaluate(inp)
print("Circuit output:")
print(f"x = {out[0]}")
print(f"y = {out[1]}")

Circuit output:
x = 21
y = 11

# Verify
a = 7
b = 9
x = a + b + 5
y = 2 * a - 3
print("Verification:")
print(f"x = {x}")
print(f"y = {y}")

Verification:
x = 21
y = 11

Tutorials

Advanced examples

Framework vs DSL¶

There exist already several domain specific languages (DSL) for cryptographic primitives. We decided to develop a python framework instead of a DSL to exploit the full power of a mature programming language to create abstractions for designing and working with circuits. Furthermore, the ability to overload arithmetic operations makes the framework as expressive as a DSL could be.

Authors¶

Viet Sang Nguyen, Matthieu Rivain, Aleksei Udovenko and Junwei Wang.

License¶

circkit is available under the MIT license.