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
  • To enable GPU support in ZisK, you must have NVIDIA Driver version 525.60.13 or later installed.
  • If you use zisk-sdk crate, you must also have CUDA Toolkit version 12.9 or later installed.

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 gcc-riscv64-unknown-elf

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 riscv-tools

Installing ZisK

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

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

  2. During installation, ziskup will detect whether CUDA is available on your machine. If so, it will install ZisK binaries with GPU support. Otherwise, you will be prompted to choose between CPU binaries (default) or GPU binaries.

  3. Also 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 proving key (no constant tree files) – Install proving key but without constant tree files generation.
    3. Install verify key – Needed only if you want to verify proofs.
    4. None – Choose this if you only want to compile programs and execute them using the ZisK emulator.

  4. 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

  5. Verify the cargo-zisk CLI tool:

    cargo-zisk --version

    It should show cargo-zisk X.X.X [gpu] if the GPU version is installed, or cargo-zisk X.X.X [cpu] otherwise

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.

To install the PLONK proving key (provingKeySnark), run: bash ziskup setup_snark

Option 2: Building from Source

Build ZisK

  1. Clone the ZisK repository:

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

  2. Build ZisK tools:

    cargo build --release

    Note: The build process will automatically detect whether CUDA is available on your machine. If so, it will build the GPU-enabled binaries; otherwise, it will build the CPU version. To force the CPU version, use the --features cpu-only flag.

    Note: By default, the build process auto-detects the GPU architecture of the host machine. Use the CUDA_ARCHS environment variable to control which architectures are compiled:

    # Single architecture (faster build — e.g. Ada Lovelace sm_89 / RTX 4090)
CUDA_ARCHS="89" cargo build --release

# Multiple architectures (e.g. Ada + Hopper)
CUDA_ARCHS="89,90" cargo build --release

# All major architectures — portable binary for distribution
# (sm_80, sm_86, sm_89, sm_90, sm_100, sm_120 + PTX forward compatibility)
# Note: this takes significantly longer to compile
CUDA_ARCHS="major" cargo build --release

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

    mkdir -p $HOME/.zisk/bin
cp target/release/cargo-zisk target/release/ziskemu target/release/riscv2zisk target/release/zisk-coordinator target/release/zisk-worker target/release/libziskclib.a $HOME/.zisk/bin

  4. 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

  5. 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

  6. Install the ZisK Rust toolchain:

    cargo-zisk toolchain install

    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 toolchain build

  7. Verify the installation:

    rustup toolchain list

    Confirm that zisk appears in the list of installed toolchains.

  8. Verify the cargo-zisk CLI tool:

    cargo-zisk --version

    It should show cargo-zisk X.X.X [gpu] if the GPU version is built, or cargo-zisk X.X.X [cpu] otherwise.

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.

  1. 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

  2. Install packages:

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

  3. All subsequent commands must be executed from the zisk folder created in the previous section:

    cd zisk

  4. Generate fixed data:

    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

  5. Compile ZisK PIL:

    node --max-old-space-size=16384 ../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

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

    node --max-old-space-size=16384 --stack-size=8192 ../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 -s ./state-machines/starkstructs.json

    This command generates the build/provingKey directory.

    Additionally, to generate the snark wrapper:

    node  ../pil2-proofman-js/src/main_setup_snark.js -b build -t ../pil2-proofman/pil2-components/lib/std/pil -f -w ../powersOfTau28_hez_final_27.ptau -p ./state-machines/publics.json -n plonk

    It is stored under the build/provingKeySnark directory.

  7. Copy (or move) the build/provingKey directory to $HOME/.zisk directory:

    cp -R build/provingKey $HOME/.zisk

Uninstall Zisk

  1. Uninstall ZisK toolchain:

    rustup uninstall zisk

  2. Delete ZisK folder

    rm -rf $HOME/.zisk