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 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/
├── Cargo.toml             
├── 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 3.32s

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 to verify the output is correct before committing to a full proof:

bash

cargo-zisk run --release -i samples/example-input.bin

SHA-256('Hello World!') => 0x7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069

cargo-zisk run executes the guest in emulated mode and prints any output from inside the VM.

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/examples/hash/guest/target/elf/riscv64ima-zisk-zkvm-elf/release/hash-guest
INFO: Program name: hash-guest
INFO: Hash ID: 219ce6c86862fe56c557e2d5f473de7d73f4e11bc0b61ac3185443a494b488ce

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 146.968s, steps: 19692
INFO: Proof saved to proof.bin

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, 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:

Flag	Proof format
(none)	STARK proof. The default, suitable for off-chain verification.
--minimal	A smaller STARK proof, at the cost of longer proving time.
--plonk	A PLONK proof for on-chain verification via the EVM verifier. Requires the PLONK proving key — install it as described for Linux or macOS.

--minimal and --plonk are mutually exclusive. For example, to produce a PLONK proof:

bash

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

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: 23 milliseconds
INFO: ----------------------------

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.

Feature	Effect
asm	Use the native Assembly executor instead of the software emulator (Linux x86_64 only).
gpu	Offload witness generation to a CUDA-capable GPU.

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.