This repository serves as both a tutorial and a template project for creating an application based on the zkLLVM toolchain. Use it to learn about developing zk-enabled apps with zkLLVM step-by-step.
For this tutorial, ensure you have an amd64 machine equipped with Docker or Podman (Linux) or Docker Desktop (macOS). For Windows users, Docker in WSL is recommended. While Docker Desktop may work on Windows, it is not officially supported in this tutorial.
Table of Contents
- Introduction
- Getting started
- Part 1. Circuit development workflow
- Part 2. Application developer workflow
This tutorial is structured into sequential steps,
each executed as a command within the scripts/run.sh script.
For first-time users, we strongly recommend utilizing this script.
After completing the tutorial, you can revisit the steps by manually executing commands in the console.
Detailed explanations of commands, parameters, file formats, and more can be found
under the 🧰 [manual mode] sections in the collapsed blocks.
Begin by cloning the repository and its submodules:
git clone --recurse-submodules https://github.com/NilFoundation/zkllvm-template.git
cd zkllvm-templateIf you initially cloned without --recurse-submodules, update submodules explicitly:
git submodule update --init --recursivezkLLVM is distributed as a deb package, so you can install it using the following commands (Ubuntu 20.04):
echo 'deb [trusted=yes] http://deb.nil.foundation/ubuntu/ all main' >>/etc/apt/sources.list
apt update
apt install -y zkllvm proof-producerThe packages cmake and libboost-all-dev are required for building the template project:
apt install -y cmake libboost-all-devFor the additional installation options, check our docs.
In the first part of this tutorial, we'll walk through the development workflow of a circuit developer. Most operations will be done on a local machine, without using the Proof Market. We will build a circuit, pack it into a circuit statement, and then use it to build a proof for a particular input. Last thing, we'll post the statement on the Proof Market, so that zk application developers will be able to request proofs with this statement.
Code in ./src implements the logic of a storage proof on Ethereum by validating Merkle Tree path of the commited data.
It reuses algorithms and data structures from the the
Crypto3 C++ high efficiency cryptography library.
To check the versions of the tools that we will use, run the following commands:
assigner --version
clang-zkllvm --version
proof-generator-multi-threaded --version
proof-generator-single-threaded --versionbash scripts/run.shor run them manually:
In ./src/main.cpp, we have a function starting with [[circuit]].
This code definition is what we call the circuit itself.
We will use zkLLVM compiler to make a byte-code representation of this circuit.
Run the commands from the root of your project.
Configure the project with cmake:
cmake -G "Unix Makefiles" -B ${ZKLLVM_BUILD:-build} -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang-zkllvm .Compile the circuit:
make -C ${ZKLLVM_BUILD:-build} templateThis will create a template.ll file in the build/src directory. This file contains the compiled
circuit intermediate representation.
Next step is to make a compiled circuit and assignment table.
assigner -b build/src/template.ll \
-i src/public-input.json \
-p src/private-input.json \
--circuit template.crct \
--assignment-table template.tbl \
-e pallasOn this step, we run the assigner, giving it the circuit in LLVM IR format (template.ll)
and the input data (./src/public-input.json).
The assigner produces two following files:
- Circuit file
template.crctis the circuit in a binary format that is usable by theproof-generator. - Assignment table
template.tblis a representation of input data, prepared for proof computation with this particular circuit.
Now we have everything ready to produce our first proof.
As a circuit developer, we want to first build it locally, to check that our circuit is working.
We'll use the proof-generator-single-threaded CLI, which is a part of the =nil; toolchain.
proof-generator-single-threaded \
--circuit="template.crct" \
--assignment-table="template.tbl" \
--proof="proof.bin"Note the following lines in the build log:
Preprocessing public data...
Preprocessing private data...
Generating proof...
Proof generated
Proof is verified
...
In the first lines, proof-generator creates a proof, and in the last one it verifies the proof.
The resulting proof is in the file ./proof.bin.
Congratulations! You've produced a non-interactive zero-knowledge proof, or, formally speaking, a zero-knowledge succinct non-interactive argument of knowledge (zk-SNARK).
In this part, we will act as a developer of a zk application. Our task is to order a proof on the Proof Market:
- Find a circuit statement. We will be using one that has active proof producers, who will respond to our request.
- Post a request for a proof with given statement and particular input.
- Check that a request was matched and the proof is ready.
- Download the proof.
All commands in this section run in the container nilfoundation/proof-market-toolchain:
cd /opt/zkllvm-template
scripts/run.sh run_proof_market_toolchainFirst, let's see what statements are available on the Proof Market.
python3 scripts/statement_tools.py getIf you're on a live workshop by =nil;, use the statement with id 96079532.
It's built from the circuit code in this template, and accepts input from
./src/public-input.json.
python3 scripts/request_tools.py push \
--key 96079532 \
--cost 10 \
--file /opt/zkllvm-template/src/public-input.jsonThe output will look like the following, but with different key values.
Limit request: {
"_key": "99887766",
"statement_key": "96079532",
"cost": 10,
"sender": "zkdev",
"status": "created"
}
You can check the request status at any time:
python3 scripts/request_tools.py get --key 99887766You should see almost the same output as before.
Note the status field: it reflects whether the Proof Market has assigned
your request to a particular producer, and whether they have provided the proof.
Limit request: {
"_key": "99887766",
"statement_key": "96079532",
"cost": 10,
"sender": "zkdev",
"status": "created"
}
When the proof is ready, download it:
python3 scripts/proof_tools.py get \
--request_key 99887766 \
--file /tmp/example.proof
ls -l /tmp/example.proofNow the proof can be verified, both off-chain and on-chain. These steps will be added soon.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent