Skip to main content

Quickstart

This guide walks through running a ZisK guest program and generating a verified proof step by step, using a Hash computation as the example. It introduces the two ways to drive the pipeline: from the CLI and from a rust program.

Download the examples​

Every example referenced in these guides lives in the ZisK repository. Clone it once and move into the hash directory, the program we'll use throughout this quickstart:

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

The project structure looks like this:

hash/
├── README.md
├── common/ => Crate to define shared types and functionalities
│ ├── Cargo.toml between guest and host crates.
│ └── src/
| └── lib.rs
├── guest/ => The guest program is the one that is executed and
│ ├── Cargo.toml proven inside the zkVM.
│ ├── samples/
| | └── example-input.bin
│ └── src/
| └── main.rs
└── host/ => The host program is the one that drives execution
├── Cargo.toml and proving from outside the zkVM. It is not proven.
├── build.rs
└── src/
└──main.rs

The guest is the program whose execution will be proven. It reads a String from the input buffer, computes its hash, and commits the digest as a public output. The host is a normal Rust program that runs on your machine: it prepares the input, runs the guest, and handles proving. The common crate holds shared types between guest and host.

tip

Take a moment to open the guest and host crates and read through them to get a feel for how the project is structured. This guide focuses on the execution flow and tool verification rather than the code itself. A deeper explanation of each piece is in the Writing Programs and Proving Programs sections.


Run via CLI​

The cargo-zisk CLI exposes the full pipeline as subcommands. This is the fastest way to go from source code to a verified proof without writing any host code.

Build the guest program​

Compile the guest to a RISC-V ELF binary using the ZisK toolchain:

bash
cd guest
cargo-zisk build --release
Compiling hash-guest v0.1.0 ($HOME/zisk/examples/hash/guest)
Finished `release` profile [optimized] target(s) in 13.20s

The compiled binary lands at:

target/elf/riscv64ima-zisk-zkvm-elf/release/hash-guest

This ELF is the exact program the zkVM will execute. The elf/riscv64ima-zisk-zkvm-elf target in the path confirms it was compiled for ZisK's RISC-V environment rather than your host machine.

Run the guest program​

Run the guest in the emulator to verify the output is correct before committing to a full proof:

bash
cargo-zisk run --release -i samples/example-input.bin
Random seed: c7d766f0559a585f8d6123d4bbe5d13e94a361ee30e3432c612a8c084f53322f
sha256('Hello World!') => 0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069

cargo-zisk run executes the guest in emulated mode and prints any output from inside the VM. The first line is the host randomness seed of the run, printed so a failing run can be replayed with --random-seed.

Setup the guest program​

Before ZisK can generate a proof it needs a program setup key derived from your specific guest binary. This key encodes the structure of the program so the prover can efficiently commit to the correct execution trace. Generate it with:

bash
cargo-zisk setup --release
INFO: --- SETUP SUMMARY -------------
INFO: Setup completed for $HOME/zisk/examples/hash/guest/target/elf/riscv64ima-zisk-zkvm-elf/release/hash-guest
INFO: Program name: hash-guest
INFO: Hash ID: dadd6fd8db844c8ce81f7723ec0e0d28fc30f588d5ad9e333114a6bcdc24ee52

Prove the guest program​

With the proving key in place, run the prover. It re-executes the guest, generates arithmetic constraints over the execution trace, and produces a proof that the output is correct:

bash
cargo-zisk prove --release -i samples/example-input.bin -o proof.bin
INFO: --- PROVE SUMMARY -------------
INFO: Proof generated in 666.572s, steps: 6917
INFO: Random seed: c7d766f0559a585f8d6123d4bbe5d13e94a361ee30e3432c612a8c084f53322f
INFO: Proof saved to proof.bin

This sample comes from a CPU-only run on macOS. Proving time depends heavily on the backend: on Linux the same proof took about 430 seconds with the emulator on the CPU, 355 seconds with --asm on the CPU, and 3.3 seconds on a GPU. A CPU proof has a peak working set of about 43 GB (more with --asm). On macOS it also runs with less RAM (memory is compressed and swapped, so it is slower); on Linux you need that much RAM or enough swap, otherwise the process is OOM-killed.

By default the prover runs the guest through the software emulator. On Linux x86_64 you can append --asm to switch to the native Assembly executor, which is significantly faster for larger programs:

bash
cargo-zisk prove --release -i samples/example-input.bin -o proof.bin --asm

If your machine has a CUDA-capable GPU and you installed the GPU build of cargo-zisk, append --gpu to offload proof generation to it for a substantial speedup:

bash
cargo-zisk prove --release -i samples/example-input.bin -o proof.bin --gpu

--asm and --gpu are independent and can be combined for the fastest configuration on supported hardware:

bash
cargo-zisk prove --release -i samples/example-input.bin -o proof.bin --asm --gpu

By default the prover emits an STARK proof, which is what you want for off-chain verification. Two flags select a different format instead:

FlagProof format
(none)STARK proof. The default, suitable for off-chain verification.
--minimalA smaller STARK proof, at the cost of longer proving time.
--pilfflonkA pilfflonk final SNARK proof for on-chain verification via the EVM verifier. Requires the SNARK proving key — install it as described in Install the SNARK proving key (Linux only).

--minimal and --pilfflonk are mutually exclusive (and both are exclusive with the advanced --plonk, see Choosing a proof format). For example, to produce a final SNARK proof:

bash
cargo-zisk prove --release -i samples/example-input.bin -o proof.bin --pilfflonk

Or a smaller STARK proof:

bash
cargo-zisk prove --release -i samples/example-input.bin -o proof.bin --minimal

Verify the proof​

Verification checks the mathematical structure of the proof without re-executing the program. To verify an existing proof independently at any time:

bash
cargo-zisk verify -p proof.bin
INFO: ✓ STARK proof was verified
INFO: --- VERIFICATION SUMMARY ---
INFO: time: 5 milliseconds
INFO: ----------------------------
Verifying a --pilfflonk proof

cargo-zisk verify checks a pilfflonk proof with a JavaScript verifier, so it needs Node.js 18 or later (with npm) on PATH.

Anyone with the verify key can run this command and be cryptographically certain that the committed output was produced by a correct execution of the guest.


Run via SDK​

The SDK lets you drive the full proving pipeline from a regular Rust program. The host crate in this example does exactly that. It compiles the guest, sets up the program, computes a proof, and verifies it, all in a few lines of Rust. This is the path you'd take when you need to prove computations programmatically rather than from a shell.

From the host crate, run it:

bash
cd ../host
cargo run --release
Proof was verified successfully.
sha256('Hello Zisk!') => 0xd3e33ed651e7c8d8d4e30ce9a3e4a40e9f089f22435e279a84ea5f8ae234eead

Changing the input​

The host program forwards any trailing CLI argument to the guest as the string to hash. Pass your own input after -- to hash something different:

bash
cargo run --release -- "My custom input"

Anything after -- goes to the host binary rather than to cargo, so this is the standard way to alter the input without recompiling.

Accelerating proof generation​

The host exposes two flags that switch the embedded prover's backend.

ArgumentEffect
--asmUse the native Assembly executor instead of the software emulator (Linux x86_64 only).
--gpuRun proving on a CUDA-capable GPU (needs a CUDA-enabled ZisK build).

The two flags are independent and can be combined. The fastest configuration on supported hardware is both at once:

bash
cargo run --release -- "My custom input" --gpu --asm

Summary​

You have tested that everything works and had a first look at the ZisK proving workflow: from compiling a guest program, running it in the emulator, generating a proof, and verifying it — both from the CLI and programmatically via the SDK.


Next steps​

  • Writing programs: learn how to write and optimize your own guest program from scratch.

  • Proving programs: learn how to execute the proving pipeline both programatically and via CLI.