RiscZero Tutorial

Introduction

Welcome to the RISC Zero documentation! RISC Zero is creating the infrastructure & tooling necessary for developers around the globe to build software that leverages ZK technology.

ZK technology is staged to re-shape the way we interact digitally. Historically, the only method for confirming the correct execution of a software application was through redundant computation. ZK introduces a new option: verifiable computation.

It's now possible to pair a program's output with a self-certifying receipt, allowing a skeptical third party to verify correct execution — and the verifier doesn't need to repeat the original computation or even see the inputs to the program!

Ready to start building? Check out our Getting Started page.

Installation

These instructions guide you through installing or updating RISC Zero tools to build your own RISC Zero zkVM projects.

Prerequisites: Install Rust

The RISC Zero zkVM requires Rust. If you don't already have Rust and rustup installed, start by installing Rust and rustup.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the onscreen instructions to complete the installation. If you're using Windows Subsystem for Linux (WSL), run the command above in your terminal.

Install RISC Zero Tools

Use rzup, the RISC Zero toolchain installer, to install the necessary tools:

curl -L https://risczero.com/install | bash

rzup install

This will install the latest version of the RISC Zero toolchain. For a specific version, use:

rzup install cargo-risczero <version>

Replace <version> with the desired release tag (e.g., v1.1.1).

Manual Installation

For manual installation or systems not supported by rzup (e.g., x86-64 macOS, arm64 Linux), follow these steps:

git clone https://github.com/risc0/risc0.git cd risc0 cargo install --path rzup rzup toolchain build rust

For x86-64 Linux and arm64 macOS, install the C++ toolchains by running:

rzup install cpp

Update Your Installation

To update your RISC Zero tools to the latest version, run:

rzup update

After updating, ensure your project's RISC Zero dependencies are also updated. Check the version with:

cargo risczero --version

As of March 18, 2025, the latest version is cargo-risczero 1.2.5. Always check for updates before use.

Example Output

After running curl -L https://risczero.com/install | bash, you should see:

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current Dload  Upload   Total   Spent    Left  Speed 100    15    0    15    0     0     57      0 --:--:-- --:--:-- --:--:--    57 100  5947  100  5947    0     0   3926      0  0:00:01  0:00:01 --:--:--  6980 → Starting rzup installation... → Downloading rzup... ######################################################################## 100.0% → Configuring shell... ✓ Updated shell profile ✓ Installation complete! rzup is installed in /home/zixine/.risc0/bin To get started: 1. Restart your shell or run: source '/home/zixine/.bashrc' 2. Verify the installation: rzup --help

Getting Started

To harness the power of ZK, you'll need to:

1. Write an application for the RISC Zero zkVM.
2. Generate proofs for your zkVM application.
3. Integrate your proofs into on-chain applications.

zkVM Quick Start

Welcome to the zkVM Quick Start page! Here are the steps to create your first proof:

1. Install the RISC Zero toolchain with rzup.
2. Create a new project using the cargo-risczero tool.
3. Familiarize yourself with the project's structure.
4. Run your project in dev-mode.
5. Run your project locally to generate a zk-proof.

Concept Break

The zkVM provides a zero-knowledge proof of the correct execution of Rust-based programs. The host is responsible for launching the zkVM (or a prover), and the guest is the program that runs inside the zkVM. A proof of execution is a receipt; it contains a public part (a journal) and an encryption part (a seal).

1. Install the RISC Zero Toolchain

Install rzup by running the following command:

curl -L https://risczero.com/install | bash

Run rzup to install the RISC Zero toolchain and cargo-risczero:

rzup install

2. Create a New Project

The cargo-risczero tool takes a --guest-name parameter, which is the guest program that the zkVM runs, to generate a proof of its execution:

cargo risczero new my_project --guest-name guest_code_for_zk_proof

There is a list of options in the feature flags.

3. Project Structure

The Hello World tutorial contains step-by-step instructions on how to:

• Share private data between the host and guest.
• Share the guest's results with the host publicly.
• Generate a receipt and read its journal contents.

4. Quick Development: Leveraging dev-mode

During development, running your code can take a long time due to the proof generation process. To address this issue and allow for faster iterations, use dev-mode. This mode bypasses the time-consuming proof generation process. To activate dev-mode, set the environment variable RISC0_DEV_MODE=1 when executing your project:

RISC0_DEV_MODE=1 cargo run --release

5. Real Proof Generation

Once you're ready to generate real proofs, set RISC0_DEV_MODE=0. Generating proofs locally can be done by running:

RISC0_DEV_MODE=0 cargo run --release

Note that generating proofs will take significantly longer than running in dev-mode. For optimal performance, we recommend at least 16 GB of RAM. Alternatively, consider using Bonsai to generate proofs remotely.

Executor Statistics

To gain insights into your application's performance, you can obtain executor statistics by setting the RUST_LOG environment variable to info:

RISC0_DEV_MODE=1 RUST_LOG=info RISC0_INFO=1 cargo run --release

The statistics include:

• Total Cycles
• Session Cycle
• Segments Count
• Execution Time

Feature Flags

The following feature flags are present in one or more of the crates listed above:

Congratulations!

That's all it takes to build and run a minimal RISC Zero application.

Use Cases

Verifiable computation is a game changer for the resilience and economics of operating the computing infrastructure we all rely on. It creates a number of emergent use cases which we are excited to enable. Key among these are:

• ZK Coprocessors: Enable blockchain applications to reduce gas costs by moving the expensive part of their application logic off-chain.
• Optimistic Rollups with ZK Fraud Proofs: Including our work with Optimism.

The RISC Zero zkVM can prove the correct execution of arbitrary code, allowing developers to build ZK applications in mature languages like Rust and C++.

Building zkVM Hello World

This tutorial will walk you through building your first zkVM application. By following the steps in this guide, you will learn how to:

1. Use the cargo-risczero tool to create a new project.
2. Send private data to the guest program.
3. Understand how the zkVM executes and generates a proof of a guest program.
4. Write public output from the guest program.

Step 1: Create a New Project

Firstly, visit the installation page for how to install the necessary software.

Once installed, clone the risc0 monorepo and change into the hello-world example directory:

git clone https://github.com/risc0/risc0 cd risc0/examples/hello-world

Next, check the version of cargo risczero installed:

cargo risczero --version

To match the example release version with your local installation, check out the corresponding branch of the example:

git checkout release-$MAJOR.$MINOR # e.g. release-1.2

Once on the correct release branch, run the example:

cargo run --release

Step 2 (Host): Share Private Data as Input with the Guest

The host code is located in hello-world/src/main.rs and hello-world/src/lib.rs. The host creates an executor environment ExecutorEnv before constructing a prover. This executor environment is responsible for managing guest-readable memory.

// hello-world/src/lib.rs
use risc0_zkvm::{default_prover, ExecutorEnv, Receipt};

pub fn multiply(a: u64, b: u64) -> (Receipt, u64) {
    let env = ExecutorEnv::builder()
        // Send a & b to the guest
        .write(&a)
        .unwrap()
        .write(&b)
        .unwrap()
        .build()
        .unwrap();
    
    // Obtain the default prover.
    let prover = default_prover();

    // Produce a receipt by proving the specified ELF binary.
    let receipt = prover.prove(env, MULTIPLY_ELF).unwrap().receipt;

    // Extract journal of receipt (i.e. output c, where c = a * b)
    let c: u64 = receipt.journal.decode().expect(
        "Journal output should deserialize into the same types (& order) that it was written",
    );

    // Report the product
    println!("I know the factors of {}, and I can prove it!", c);

    (receipt, c)
}

Step 3 (Guest): Read Input and Commit Output

The guest code is located in methods/guest/src/main.rs. This is the portion of the code that will be proven. The guest reads the two values a and b from the host and commits them to the journal portion of the receipt.

// hello-world/methods/guest/src/main.rs
use risc0_zkvm::guest::env;

risc0_zkvm::guest::entry!(main);

fn main() {
    // Load the first number from the host
    let a: u64 = env::read();
    // Load the second number from the host
    let b: u64 = env::read();
    // Verify that neither of them are 1 (i.e. nontrivial factors)
    if a == 1 || b == 1 {
        panic!("Trivial factors")
    }
    // Compute the product while being careful with integer overflow
    let product = a.checked_mul(b).expect("Integer overflow");
    env::commit(&product);
}

Step 4 (Host): Generate a Receipt and Read Its Journal Contents

The host generates a receipt and extracts the contents of the journal:

// hello-world/src/main.rs
use hello_world::multiply;
use hello_world_methods::MULTIPLY_ID;

fn main() {
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
        .init();

    // Pick two numbers
    let (receipt, _) = multiply(17, 23);

    // Verify receipt, panic if it's wrong
    receipt.verify(MULTIPLY_ID).expect(
        "Code you have proven should successfully verify; did you specify the correct image ID?",
    );
}

Step 5: Run the Hello World Example

To run this example locally, and see if proving completed successfully, run:

cargo run --release

If proving is successful, the line 'I know the factors of 391, and I can prove it!' is printed.

Error Handling

If you encounter errors during cloning or execution, try the following commands:

git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999 git config --global core.compression 0

If the issue persists, ensure you are on the correct release branch:

git checkout release-1.2 cargo clean cargo run --release

Additional Tests

You can add more tests to verify the functionality of the multiply function:

#[test]
fn test_multiply() {
    let a: i64 = 5;
    let b: i64 = 10;
    let (_, result) = multiply(a as u64, b as u64);
    assert_eq!(result, 50, "Multiply function failed");
}

#[test]
fn test_multiply_zero() {
    let a: i64 = 0;
    let b: i64 = 10;
    let (_, result) = multiply(a as u64, b as u64);
    assert_eq!(result, 0, "Multiply function failed with zero");
}

#[test]
fn test_multiply_two_negatives() {
    let a: i64 = -7;
    let b: i64 = -8;
    let (_, result) = multiply(a.unsigned_abs(), b.unsigned_abs());
    assert_eq!(result as i64, a * b, "Multiply function failed with two negatives");
}

#[test]
fn test_multiply_large_numbers() {
    let a: i64 = 100000;
    let b: i64 = 100000;
    let (_, result) = multiply(a as u64, b as u64);
    assert_eq!(result, 10000000000, "Multiply function failed with large numbers");
}

Notes

Here are some additional resources to help you get started with RISC Zero:

• Official Website: RISC Zero
• Documentation: RISC Zero Docs