Installation Guide

ZisK can be installed from prebuilt binaries (recommended) or by building the ZisK tools, toolchain and setup files from source.

System Requirements

ZisK currently supports Linux x86_64 and macOS platforms (see note below).

Note: On macOS, proof generation is not yet optimized, so some proofs may take longer to generate.

Required Tools

Ensure the following tools are installed:

Rust
Git

Installing Dependencies

Ubuntu

Ubuntu 22.04 or higher is required.

Install all required dependencies with:

sudo apt-get install -y xz-utils jq curl build-essential qemu-system libomp-dev libgmp-dev nlohmann-json3-dev protobuf-compiler uuid-dev libgrpc++-dev libsecp256k1-dev libsodium-dev libpqxx-dev nasm libopenmpi-dev openmpi-bin openmpi-common libclang-dev clang

ZisK uses shared memory to exchange data between processes. The system must be configured to allow enough locked memory per process:

$ ulimit -l
unlimited

A way to achieve it is to edit the file /etc/systemd/system.conf and add the line DefaultLimitMEMLOCK=infinity. Reboot for changes to take effect.

macOS

macOS 14 or higher is required.

You must have Homebrew and Xcode installed.

Install all required dependencies with:

brew reinstall jq curl libomp protobuf openssl nasm pkgconf open-mpi libffi nlohmann-json libsodium

Installing ZisK

Option 1: Prebuilt Binaries (Recommended)

To install ZisK using ziskup, run the following command in your terminal:

curl https://raw.githubusercontent.com/0xPolygonHermez/zisk/main/ziskup/install.sh  | bash

During the installation, you will be prompted to select a setup option. You can choose from the following:
1. Install proving key (default) – Required for generating and verifying proofs.
2. Install verify key – Needed only if you want to verify proofs.
3. None – Choose this if you only want to compile programs and execute them using the ZisK emulator.
Verify the Rust toolchain: (which includes support for the riscv64ima-zisk-zkvm compilation target):
```
rustup toolchain list
```
The output should include an entry for zisk, similar to this:
```
stable-x86_64-unknown-linux-gnu (default)
nightly-x86_64-unknown-linux-gnu
zisk
```
Verify the cargo-zisk CLI tool:
```
cargo-zisk --version
```

Updating ZisK

To update ZisK to the latest version, simply run: bash ziskup

You can use the flags --provingkey, --verifykey or --nokey to specify the installation setup and skip the selection prompt.

Option 2: Building from Source

Build ZisK

Clone the ZisK repository:

git clone https://github.com/0xPolygonHermez/zisk.git
cd zisk

Build ZisK tools:

cargo build --release

Note: If you encounter the following error during compilation on Ubuntu:

--- stderr
/usr/lib/x86_64-linux-gnu/openmpi/include/mpi.h:237:10: fatal error: 'stddef.h' file not found

Follow these steps to resolve it:

Locate the stddef.h file:
```
find /usr -name "stddef.h"
```

Set the environment variables to include the directory where stddef.h is located (e.g.):

export C_INCLUDE_PATH=/usr/lib/gcc/x86_64-linux-gnu/13/include
export CPLUS_INCLUDE_PATH=$C_INCLUDE_PATH

Try building again

Copy the tools to ~/.zisk/bin directory:

mkdir -p $HOME/.zisk/bin
LIB_EXT=$([[ "$(uname)" == "Darwin" ]] && echo "dylib" || echo "so")
cp target/release/cargo-zisk target/release/ziskemu target/release/riscv2zisk target/release/libzisk_witness.$LIB_EXT target/release/libziskclib.a $HOME/.zisk/bin

Copy required files for assembly rom setup:

Note: This is only needed on Linux x86_64, since assembly execution is not supported on macOS

mkdir -p $HOME/.zisk/zisk/emulator-asm
cp -r ./emulator-asm/src $HOME/.zisk/zisk/emulator-asm
cp ./emulator-asm/Makefile $HOME/.zisk/zisk/emulator-asm
cp -r ./lib-c $HOME/.zisk/zisk

Add ~/.zisk/bin to your system PATH:

If you are using bash or zsh:

PROFILE=$([[ "$(uname)" == "Darwin" ]] && echo ".zshenv" || echo ".bashrc")
echo >>$HOME/$PROFILE && echo "export PATH=\"\$PATH:$HOME/.zisk/bin\"" >> $HOME/$PROFILE
source $HOME/$PROFILE

Install the ZisK Rust toolchain:
```
cargo-zisk sdk install-toolchain
```
Note: This command installs the ZisK Rust toolchain from prebuilt binaries. If you prefer to build the toolchain from source, follow these steps:
1. Ensure all dependencies required to build the Rust toolchain from source are installed.
2. Build and install the Rust ZisK toolchain:
```
cargo-zisk sdk build-toolchain
```
Verify the installation:
```
rustup toolchain list
```
Confirm that zisk appears in the list of installed toolchains.

Build Setup

Please note that the process can be long, taking approximately 45-60 minutes depending on the machine used.

NodeJS version 20.x or higher is required to build the setup files.

Clone the following repositories in the parent folder of the zisk folder created in the previous section:

git clone https://github.com/0xPolygonHermez/pil2-compiler.git
git clone https://github.com/0xPolygonHermez/pil2-proofman.git
git clone https://github.com/0xPolygonHermez/pil2-proofman-js

Install packages:

(cd pil2-compiler && npm i)
(cd pil2-proofman-js && npm i)

All subsequent commands must be executed from the zisk folder created in the previous section:
```
cd zisk
```

Generate fixed data:

cargo run --release --bin keccakf_fixed_gen
cargo run --release --bin arith_frops_fixed_gen
cargo run --release --bin binary_basic_frops_fixed_gen
cargo run --release --bin binary_extension_frops_fixed_gen

Compile ZisK PIL:

node ../pil2-compiler/src/pil.js pil/zisk.pil -I pil,../pil2-proofman/pil2-components/lib/std/pil,state-machines,precompiles -o pil/zisk.pilout -u tmp/fixed -O fixed-to-file

This command will create the pil/zisk.pilout file

Generate setup data: (this step may take 30-45 minutes):

node ../pil2-proofman-js/src/main_setup.js -a ./pil/zisk.pilout -b build -t ../pil2-proofman/pil2-components/lib/std/pil -u tmp/fixed -r

This command generates the build/provingKey directory.

Copy (or move) the build/provingKey directory to $HOME/.zisk directory:
```
cp -R build/provingKey $HOME/.zisk
```
Generate constant tree files:
```
cargo-zisk check-setup -a
```

Uninstall Zisk

Uninstall ZisK toolchain:
```
rustup uninstall zisk
```
Delete ZisK folder
```
rm -rf $HOME/.zisk
```

ZisK Documentation