cargo-risczero

CLI tool for RISC Zero development

cargo-risczero

The cargo-risczero crate provides command-line tools for building, testing, and managing RISC Zero zkVM projects.

Installation

cargo install cargo-risczero
rzup install

Overview

The cargo risczero command provides:

• Project scaffolding: Create new zkVM projects
• Build management: Compile guest programs
• Toolchain management: Install RISC-V toolchains
• Testing utilities: Run and verify proofs

After installing, run rzup install to set up the required RISC-V toolchain.

Commands

new

cargo risczero new · command

Create a new RISC Zero project from a template.

cargo risczero new <project-name>

Options:

• --guest-name <NAME>: Name for the guest package (default: “method”)
• --template <TEMPLATE>: Template to use

Templates:

• default: Standard zkVM project structure
• minimal: Minimal project setup

Example:

cargo risczero new my-zkvm-project
cd my-zkvm-project
cargo build

Generated Structure:

my-zkvm-project/
├── Cargo.toml
├── host/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs
└── methods/
    ├── Cargo.toml
    ├── build.rs
    ├── guest/
    │   ├── Cargo.toml
    │   └── src/
    │       └── main.rs
    └── src/
        └── lib.rs

build

cargo risczero build · command

Build guest programs for the zkVM.

cargo risczero build [OPTIONS]

Options:

• --manifest-path <PATH>: Path to Cargo.toml
• --features <FEATURES>: Comma-separated list of features
• --release: Build in release mode

Example:

cargo risczero build --release

verify

cargo risczero verify · command

Verify a receipt file.

cargo risczero verify <receipt-file>

Example:

cargo risczero verify proof.receipt

install

cargo risczero install · command

Install RISC Zero toolchain components.

cargo risczero install [OPTIONS]

Options:

• rust: Install Rust toolchain
• cpp: Install C++ toolchain

Example:

cargo risczero install rust
cargo risczero install cpp

Feature Flags

default · feature

Includes r0vm feature.

r0vm · feature

Enables the r0vm runtime and utilities.

experimental · feature

Enables experimental features and commands.

cuda · feature

Enables CUDA GPU acceleration.

metal · feature

Enables Metal GPU acceleration (macOS).

docker · feature

Enables Docker-based guest building.

Environment Variables

RISC0_TOOLCHAIN_VERSION · env

Override the default toolchain version.

export RISC0_TOOLCHAIN_VERSION=r0.1.80.0

CARGO_RISCZERO_PATH · env

Custom path for cargo-risczero cache.

export CARGO_RISCZERO_PATH=~/.cache/cargo-risczero

r0vm Binary

The package also provides the r0vm binary for running and analyzing guest programs:

r0vm run

r0vm run · command

Execute a guest ELF file.

r0vm run --elf <elf-file> [OPTIONS]

Options:

• --elf <FILE>: Path to ELF file
• --env <FILE>: Environment file with input data
• --profile: Enable profiling
• --trace: Enable execution tracing

Example:

r0vm run --elf method.elf --env input.json

r0vm info

r0vm info · command

Display information about an ELF file.

r0vm info --elf <elf-file>

Shows:

• Image ID
• Entry point
• Program size
• Memory layout

Example:

r0vm info --elf method.elf

r0vm analyze

r0vm analyze · command

Analyze execution and count cycles.

r0vm analyze --elf <elf-file> --env <env-file>

Provides:

• Total cycle count
• Segment breakdown
• Syscall statistics
• Memory usage

Example:

r0vm analyze --elf method.elf --env input.json

Project Templates

When creating a new project, cargo risczero new generates:

Host Package

// host/src/main.rs
use risc0_zkvm::{default_prover, ExecutorEnv};
use methods::{METHOD_NAME_ELF, METHOD_NAME_ID};

fn main() {
    let env = ExecutorEnv::builder()
        .write(&input)
        .unwrap()
        .build()
        .unwrap();
        
    let prover = default_prover();
    let receipt = prover.prove(env, METHOD_NAME_ELF).unwrap();
    
    receipt.verify(METHOD_NAME_ID).unwrap();
}

Guest Package

// methods/guest/src/main.rs
#![no_main]
use risc0_zkvm::guest::env;

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

fn main() {
    let input: u32 = env::read();
    let result = input * 2;
    env::commit(&result);
}

Build Script

// methods/build.rs
fn main() {
    risc0_build::embed_methods();
}

Workflow

Typical development workflow:

# 1. Create new project
cargo risczero new my-project
cd my-project

# 2. Build guest programs
cargo build --release

# 3. Run the host program
cargo run --release

# 4. Analyze performance (optional)
r0vm analyze --elf target/riscv-guest/release/method \
    --env input.json

Docker Integration

With the docker feature, build guests reproducibly:

RISC0_USE_DOCKER=1 cargo build --release

Benefits:

• Reproducible builds
• Consistent cycle counts
• Cross-platform compatibility

GPU Support

Enable GPU acceleration in your project:

# Cargo.toml
[dependencies]
risc0-zkvm = { version = "5.0.0", features = ["cuda"] }

Or for Metal on macOS:

risc0-zkvm = { version = "5.0.0", features = ["metal"] }

Troubleshooting

Toolchain Issues

# Reinstall toolchain
rzup install rust --force

# Check installation
rzup toolchain list

Build Issues

# Clean build artifacts
cargo clean

# Rebuild with verbose output
cargo build --verbose

Environment Variables

# Enable debug logging
export RUST_LOG=debug

# Skip Docker
export RISC0_USE_DOCKER=0

Examples

Creating a Simple Project

# Create project
cargo risczero new calculator
cd calculator

# Build
cargo build --release

# Run
cargo run --release

Custom Guest Features

# Build with specific features
cargo risczero build --features "my-feature,another-feature"

Profiling

# Run with profiling
r0vm run --elf method.elf --env input.json --profile

# View profile data
open profile.json

Integration with IDEs

VS Code

Add to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Guest",
      "type": "shell",
      "command": "cargo",
      "args": ["risczero", "build"],
      "group": "build"
    }
  ]
}

Rust Analyzer

Add to .vscode/settings.json:

{
  "rust-analyzer.checkOnSave.allTargets": false,
  "rust-analyzer.cargo.target": "x86_64-unknown-linux-gnu"
}

Links

• docs.rs
• GitHub
• Crate
• rzup Documentation