Introduction
WIP
Install
Requirements
⚠️ Currently, macOS is not supported for proof generation. A Linux x86_64 machine is required at this time. ⚠️
Ubuntu prerequisites
sudo apt-get install -y xz-utils jq curl git build-essential qemu-system libomp-dev libgmp-dev nlohmann-json3-dev protobuf-compiler uuid-dev libgrpc++-dev libsecp256k1-dev libsodium-dev libpqxx-dev nasm
Nix Flake
Alternatively, you can use Nix package manager to install all dependencies. First, follow the guide to install Nix on your OS.
Afterwards, use flake.nix in zisk repository to load the development environment with:
nix develop
# You can also use a custom shell:
nix develop -c zsh
This will start a new shell with correctly set PATH and LD_LIBRARY_PATH for dependencies necessary to build the project.
You can exit this shell with Ctrl+D.
OSX prerequisites
# Install brew first.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# A dependency for `cargo build`.
brew install protobuf
# A dependency of `ziskup`.
brew install libusb jq
nodejs
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source $HOME/.bashrc
nvm install 19
nvm use 19
Circom
https://docs.circom.io/getting-started/installation/
Option 1: Prebuilt Binaries (Recommended)
curl https://raw.githubusercontent.com/0xPolygonHermez/zisk/develop/ziskup/install.sh | bash
This will enable the ziskup command in your CLI. You need to restart your terminal to use it or run this command:
source $HOME/.bashrc
After completing these steps, you can execute ziskup to install the toolchain:
ziskup
To check the correct installation of the ZisK Rust toolchain which has support for the riscv64ima-polygon-ziskos-elf compilation target, you can run the next command
$ rustup toolchain list
stable-x86_64-unknown-linux-gnu
nightly-2024-01-25-x86_64-unknown-linux-gnu (default)
nightly-2024-03-05-x86_64-unknown-linux-gnu
nightly-2024-06-30-x86_64-unknown-linux-gnu
nightly-x86_64-unknown-linux-gnu
zisk
Quickstart
In this section, we will show you how to create a simple program using ZisK.
Create Project
The first step is to create a new project using the cargo-zisk sdk new <name> command. This command will create a new folder in your current directory.
cargo-zisk sdk new hello_world
cd hello_world
This will create a new project with the following structure:
.
├── build.rs
├── Cargo.lock
├── Cargo.toml
├── .gitignore
└── src
└── main.rs
2 directories, 8 files
For running the program in the native architecture:
$ cargo run --target x86_64-unknown-linux-gnu
Running `target/x86_64-unknown-linux-gnu/debug/sha_hasher`
n:20 [152, 33, 24, 130, 189, 19, 8, 155, 108, 207, 31, 202, 129, 247, 240, 228, 171, 246, 53, 42, 12, 57, 201, 177, 31, 20, 44, 172, 35, 63, 18, 128]
Run on ZisK emulator
cargo-zisk run --release
Compiling sha_hasher v0.1.0 (/home/edu/hello_world)
Finished `release` profile [optimized] target(s) in 0.20s
Running `ziskemu -i build/input.bin -e target/riscv64ima-polygon-ziskos-elf/release/sha_hasher`
n:20 [152, 33, 24, 130, 189, 19, 8, 155, 108, 207, 31, 202, 129, 247, 240, 228, 171, 246, 53, 42, 12, 57, 201, 177, 31, 20, 44, 172, 35, 63, 18, 128]
or
cargo-zisk build --release
ziskemu -i build/input.bin -x -e target/riscv64ima-polygon-ziskos-elf/release/sha_hasher
metrics
cargo-zisk run --release -m
Compiling sha_hasher v0.1.0 (/home/edu/hello_world)
Finished `release` profile [optimized] target(s) in 0.20s
Running `ziskemu -i build/input.bin -m -e target/riscv64ima-polygon-ziskos-elf/release/sha_hasher`
n:20 [152, 33, 24, 130, 189, 19, 8, 155, 108, 207, 31, 202, 129, 247, 240, 228, 171, 246, 53, 42, 12, 57, 201, 177, 31, 20, 44, 172, 35, 63, 18, 128]
process_rom() steps=99288 duration=0.0024 tp=40.9284 Msteps/s freq=2892.0000 70.6600 clocks/step
stats
cargo-zisk run --release --stats
Compiling sha_hasher v0.1.0 (/home/edu/hello_world)
Finished `release` profile [optimized] target(s) in 0.20s
Running `ziskemu -i build/input.bin -x -e target/riscv64ima-polygon-ziskos-elf/release/sha_hasher`
n:20 [152, 33, 24, 130, 189, 19, 8, 155, 108, 207, 31, 202, 129, 247, 240, 228, 171, 246, 53, 42, 12, 57, 201, 177, 31, 20, 44, 172, 35, 63, 18, 128]
Cost definitions:
AREA_PER_SEC: 1000000 steps
COST_MEMA_R1: 0.00002 sec
COST_MEMA_R2: 0.00004 sec
COST_MEMA_W1: 0.00004 sec
COST_MEMA_W2: 0.00008 sec
COST_USUAL: 0.000008 sec
COST_STEP: 0.00005 sec
Total Cost: 14.25 sec
Main Cost: 4.96 sec 99287 steps
Mem Cost: 2.54 sec 254054 steps
Mem Align: 0.06 sec 3130 steps
Opcodes: 6.63 sec 1335 steps (92652 ops)
Usual: 0.05 sec 6636 steps
Memory: 155262 a reads + 1846 na1 reads + 0 na2 reads + 96304 a writes + 642 na1 writes + 0 na2 writes = 157108 reads + 96946 writes = 254054 r/w
Registy: 147515 reads + 90588 writes = 238103 r/w
Opcodes:
flag: 0.00 sec (0 steps/op) (660 ops)
copyb: 0.00 sec (0 steps/op) (16521 ops)
add: 1.39 sec (77 steps/op) (18059 ops)
sub: 0.00 sec (77 steps/op) (10 ops)
ltu: 0.03 sec (77 steps/op) (412 ops)
eq: 0.02 sec (77 steps/op) (224 ops)
sll: 1.24 sec (109 steps/op) (11360 ops)
srl: 0.02 sec (109 steps/op) (216 ops)
add_w: 0.00 sec (77 steps/op) (52 ops)
sub_w: 0.00 sec (77 steps/op) (24 ops)
srl_w: 1.43 sec (109 steps/op) (13141 ops)
and: 0.40 sec (77 steps/op) (5168 ops)
or: 0.94 sec (77 steps/op) (12209 ops)
xor: 1.06 sec (77 steps/op) (13779 ops)
signextend_b: 0.03 sec (109 steps/op) (320 ops)
signextend_w: 0.05 sec (109 steps/op) (480 ops)
mul: 0.00 sec (97 steps/op) (17 ops)
Update zisk toolchain to latest version
ziskup
Prepare Your Setup
git clone https://github.com/0xPolygonHermez/zisk
git clone -b develop https://github.com/0xPolygonHermez/pil2-compiler.git
git clone -b 0.0.16 https://github.com/0xPolygonHermez/pil2-proofman.git
git clone -b 0.0.16 https://github.com/0xPolygonHermez/pil2-proofman-js
All following commands should be executed in the zisk folder.
cd zisk
Compile Zisk PIL
(cd ../pil2-compiler && npm i && cd ../zisk && node --max-old-space-size=65536 ../pil2-compiler/src/pil.js pil/zisk.pil -I pil,../pil2-proofman/pil2-components/lib/std/pil,state-machines -o pil/zisk.pilout)
Compile the PIl2 Stark C++ Library (run only once):
(cd ../pil2-proofman/pil2-stark && git submodule init && git submodule update && make clean && make -j starks_lib && make -j bctree) && export RUSTFLAGS=$RUSTFLAGS" -L native=$PWD/../pil2-proofman/pil2-stark/lib"
Generate PIL-Helpers Rust Code
Run this whenever the .pilout file changes:
(cd ../pil2-proofman; cargo run --bin proofman-cli pil-helpers --pilout ../zisk/pil/zisk.pilout --path ../zisk/pil/src/ -o)
Generate Setup Data
Run this whenever the .pilout file changes:
(cd ../pil2-proofman-js && npm i)
node --max-old-space-size=65536 ../pil2-proofman-js/src/main_setup.js -a pil/zisk.pilout -b build -t ../pil2-proofman/pil2-stark/build/bctree -r
Compile Witness Computation library (libzisk_witness.so)
cargo build --release
Generate a Proof
To generate the proof, the following command needs to be run.
(cd ../pil2-proofman; cargo run --release --bin proofman-cli prove --witness-lib ../zisk/target/release/libzisk_witness.so --rom ../hello_world/target/riscv64ima-polygon-ziskos-elf/release/sha_hasher -i ../hello_world/build/input.bin --proving-key ../zisk/build/provingKey --output-dir ../zisk/proofs -v -a)
Verify the Proof
node ../pil2-proofman-js/src/main_verify -k build/provingKey/ -p proofs -t vadcop_final
Ziskof
Riscof tests
The following test generates the riscof test files, converts the corresponding .elf files into ZisK ROMs, and executes them providing the output in stdout for comparison against a reference RISCV implementation. This process is not trivial and has been semi-automatized.
First, compile the ZisK Emulator:
$ cargo clean
$ cargo build --release
Second, download and run a docker image from the riscof repository to generate and run the riscof tests:
$ docker run --rm -v ./target/release/ziskemu:/program -v ./riscof/:/workspace/output/ -ti hermeznetwork/ziskof:latest
The test can take a few minutes to complete. Any error would be displayed in red.