risc0-developer

RISC Zero Developer Skill

Purpose

This skill provides comprehensive guidance for developing zero-knowledge applications with RISC Zero, a zkSTARK-based verifiable computing platform built on the RISC-V microarchitecture. Enable developers to create zkVM projects, generate cryptographic proofs, verify computation, and integrate with blockchain systems.

RISC Zero allows proving correct execution of arbitrary Rust code, producing receipts that cryptographically verify computation without revealing private inputs. This skill covers the complete development lifecycle from project scaffolding to production deployment.

When to Use This Skill

Invoke this skill when working with:

• Project Creation: Scaffolding new RISC Zero zkVM applications
• Proof Generation: Setting up local proving workflows
• Proof Verification: Writing verifier code for receipts and journals
• Blockchain Integration: Deploying verifier contracts on Ethereum and other chains
• Performance Optimization: Tuning guest code and leveraging GPU acceleration

Core Concepts

Architecture Overview

RISC Zero applications separate concerns into two components:

Guest Program: The code executed inside the zkVM that gets proven. Compiles to a RISC-V ELF binary. Guest code is constrained (no file I/O, no OS features) and typically uses #![no_std] for performance optimization, focusing on computation that needs verification.

Host Program: The untrusted orchestrator that sets up the execution environment, provides inputs to the guest, invokes the prover, and handles the resulting receipt.

Receipt: The cryptographic proof of execution containing:

• Journal: Public outputs committed by the guest
• Seal: Encrypted proof data
• ImageID: Cryptographic hash of the guest ELF binary

Development Workflow

1. Write guest code defining the computation to prove
2. Write host code to execute the guest and generate proofs
3. Build the project (compiles guest to ELF, generates ImageID)
4. Run in dev mode for fast iteration without proof generation
5. Generate production proofs locally or remotely
6. Verify receipts independently using the ImageID

Getting Started

Installation and Version Management

This skill is trained for RISC Zero zkVM version 3.x. Before starting any work, perform version checks.

Step 1: Check if RISC Zero is Installed

# Check if cargo-risczero is available
cargo risczero --version

If not installed, install the toolchain:

# Install rzup (RISC Zero version manager)
curl -L https://risczero.com/install | bash

# Install RISC Zero toolchain
rzup install

Step 2: Check Installed and Available Versions

# Show installed versions
rzup show

# Check for available updates
rzup check

Step 3: Version Decision (Ask User)

Before proceeding, present version information to the user and ask which version to use:

1. If no version installed: "RISC Zero is not installed. This skill is trained for version 3.x. Would you like to install the latest 3.x version?"

2. If version 3.x installed: Proceed with current version. Optionally ask: "You have RISC Zero [version] installed. Would you like to update to the latest 3.x release?"

3. If version 2.x or older installed: "You have RISC Zero [version] installed, but this skill is trained for version 3.x. Would you like to upgrade to 3.x? Note: This may require code changes for existing projects."

4. If version 4.x or newer installed: "You have RISC Zero [version] installed. This skill is trained for version 3.x and version 4.x may have breaking changes. Would you like to: (a) Continue with version 4.x, (b) Install version 3.x alongside, or (c) Check the migration guide first?"

Step 4: Install or Update as Needed

# Install specific version
rzup install cargo-risczero 3.0.0
rzup install r0vm 3.0.0

# Or update to latest
rzup update

Creating a New Project

Pre-Creation Checks

Before creating a project, perform these checks:

Check if --no-git is supported:

cargo risczero new --help | grep -q "no-git"

If --no-git is NOT supported, check if inside a git repository:

# Check if current directory is in a git repo
git rev-parse --is-inside-work-tree 2>/dev/null

If inside a git repo without --no-git support:

1. Create the project in a temporary directory
2. Move files to the target location, preserving original git files
3. Handle potential conflicts carefully

# Create project in temp location
cargo risczero new /tmp/my_project

# Move files carefully, excluding git files from the new project
rsync -av --exclude='.git' --exclude='.gitignore' /tmp/my_project/ ./

# For files that exist in both (like .gitignore), ask user:
# "The file .gitignore exists in both your repository and the new project.
#  Would you like to: (a) Keep yours, (b) Use the new one, (c) Merge both?"

Important: When merging into existing git repositories:

• Never overwrite .git/ directory
• Ask user before overwriting .gitignore, README.md, Cargo.toml if they exist
• Show diff of conflicting files and let user decide
• If uncertain about any file conflict, ask the user

Project Creation Commands

# Basic project (in new directory)
cargo risczero new my_project

# With custom guest name
cargo risczero new my_project --guest-name my_computation

# No-std guest (for embedded/minimal dependencies)
cargo risczero new my_project --no-std

# Skip git initialization (if supported)
cargo risczero new my_project --no-git

Project Structure

Generated projects follow this structure:

my_project/
├── Cargo.toml              # Workspace configuration
├── host/
│   ├── Cargo.toml         # Host dependencies
│   └── src/
│       └── main.rs        # Host program entry point
└── methods/
    ├── Cargo.toml         # Methods workspace
    ├── build.rs           # Build script (generates ELF and ImageID)
    ├── guest/
    │   ├── Cargo.toml     # Guest dependencies
    │   └── src/
    │       └── main.rs    # Guest program code
    └── src/
        └── lib.rs         # Generated METHOD_NAME_ELF and METHOD_NAME_ID

Build Process: The methods/build.rs script uses risc0-build to compile guest code to a RISC-V ELF binary and generate the ImageID. These are exposed as constants (e.g., MULTIPLY_ELF, MULTIPLY_ID) for use in the host.

Writing Guest Code

Guest programs execute inside the zkVM and must follow specific constraints:

Required Boilerplate

#![no_std]  // Recommended: excludes standard library for performance
#![no_main] // Not a standalone executable

risc0_zkvm_guest::entry!(main);

pub fn main() {
    // Guest code here
}

About #![no_std]: This attribute is a performance optimization that excludes the standard library to minimize cycle counts and binary size. Use when OS features (file I/O, threads, networking) are not needed. Heap allocation (Vec, HashMap) remains available via the alloc crate. Set default-features = false for risc0-zkvm in Cargo.toml when using no_std.

Using std in Guest Code: If guest code depends on crate libraries that require std, use standard library with regular Rust entry point:

// When using std: Remove all three attributes below
// NO #![no_std]
// NO #![no_main]
// NO risc0_zkvm_guest::entry!(main);

use risc0_zkvm::guest::env;

fn main() {
    // Standard Rust main function
    // Can use std-dependent crates
    let input: SomeType = env::read();
    // ... computation ...
    env::commit(&result);
}

Configure risc0-zkvm with default features (std is included by default):

# methods/guest/Cargo.toml
[dependencies]
risc0-zkvm = "3.0"  # Default features include std
some-std-crate = "1.0"  # Dependency requiring std

Important: The attributes #![no_std], #![no_main], and risc0_zkvm_guest::entry!(main); are always used together as a bundle for no_std guest programs. When using std, remove ALL three and use a standard Rust fn main() entry point instead.

When to use std vs no_std:

• Use no_std: For maximum performance, minimal cycle counts, and when all dependencies support no_std. Use all three attributes: #![no_std], #![no_main], and risc0_zkvm_guest::entry!(main);
• Use std: When dependencies require standard library features. Remove all three attributes and use regular fn main()

I/O Operations

Reading Inputs from the host:

use risc0_zkvm::guest::env;

// Read a single value
let input: u32 = env::read();

// Read a slice
let data: Vec<u8> = env::read();

// Read from stdin
let value: u32 = env::stdin().read();

Writing Private Output to the host (not part of proof):

// Private output
env::write(&result);
env::stdout().write(&data);

Committing Public Output to the journal (verified by proof):

// Public commitment (part of receipt)
env::commit(&public_result);
env::commit_slice(&public_data);

Key Distinction: Use commit for data that verifiers need to see and verify. Use write for private data only the host needs.

Debugging and Performance

// Measure computational cost
let start = env::cycle_count();
// ... computation ...
let end = env::cycle_count();
env::log(&format!("Cycles: {}", end - start));

// Debug logging
env::log("Debug message");

Writing Host Code

The host program sets up execution, runs the prover, and handles receipts:

Basic Prover Setup

use risc0_zkvm::{default_prover, ExecutorEnv};
use methods::{METHOD_NAME_ELF, METHOD_NAME_ID};

fn main() {
    // Build execution environment with inputs
    let input_data = 42u32;
    let env = ExecutorEnv::builder()
        .write(&input_data).unwrap()
        .build()
        .unwrap();

    // Run prover to generate receipt
    let prover = default_prover();
    let prove_info = prover.prove(env, METHOD_NAME_ELF).unwrap();
    let receipt = prove_info.receipt;

    // Extract journal (public outputs)
    let output: u32 = receipt.journal.decode().unwrap();
    println!("Verified output: {}", output);

    // Verify receipt
    receipt.verify(METHOD_NAME_ID).unwrap();
    println!("Proof verified successfully!");
}

Dev Mode for Fast Iteration

During development, bypass proof generation for faster testing:

# Run without generating proofs
RISC0_DEV_MODE=1 cargo run --release

# Enable detailed logging
RISC0_DEV_MODE=1 RUST_LOG=info RISC0_INFO=1 cargo run --release

Dev mode skips cryptographic proof generation, dramatically speeding up the development cycle. Always test with RISC0_DEV_MODE=0 before production deployment.

Generating Production Proofs

# Generate real proofs (requires ~16GB RAM for local proving)
RISC0_DEV_MODE=0 cargo run --release

Proof Generation Options

Local Proving

Generate proofs on your own hardware. Supports CPU and GPU acceleration.

Hardware Requirements:

• CPU: Any modern x86 or ARM processor
• RAM: Minimum 16GB recommended
• GPU (optional): NVIDIA GPU with CUDA support or Apple Silicon with Metal

GPU Acceleration significantly improves proving performance. See references/proof-generation.md for detailed setup instructions.

Verification

Receipts can be verified independently by any party with the ImageID:

use risc0_zkvm::Receipt;
use methods::METHOD_NAME_ID;

fn verify_receipt(receipt: &Receipt) -> Result<(), Error> {
    // Verify the receipt cryptographically
    receipt.verify(METHOD_NAME_ID)?;

    // Extract and use the journal data
    let output: MyOutputType = receipt.journal.decode()?;

    Ok(())
}

Separation of Concerns: The prover (host) generates receipts. Verifiers only need the receipt and ImageID—no access to inputs or the execution environment required.

Blockchain Integration

RISC Zero supports on-chain verification of proofs across multiple blockchain platforms.

Ethereum and EVM Chains

Deploy Solidity verifier contracts to verify RISC Zero proofs on-chain:

1. Generate a Groth16-wrapped receipt (smaller proof size for on-chain verification)
2. Deploy the RiscZeroVerifierRouter contract
3. Call the verifier contract from your smart contract

import {IRiscZeroVerifier} from "risc0/IRiscZeroVerifier.sol";
import {ImageID} from "./ImageID.sol"; // Generated ImageID

contract MyContract {
    IRiscZeroVerifier public verifier;

    function verifyProof(bytes calldata seal, bytes calldata journal) external {
        verifier.verify(seal, ImageID.METHOD_NAME_ID, journal);
        // Proof verified, proceed with on-chain logic
    }
}

Note: The STARK-to-SNARK wrapper reduces proof size from hundreds of kilobytes to hundreds of bytes, enabling cost-effective on-chain verification.

See references/blockchain-integration.md for detailed multi-chain integration patterns, deployment workflows, and production considerations.

Performance and Optimization

Monitoring Execution Metrics

Track cycle count and performance:

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

Metrics include:

• Total cycles: Computational cost of guest execution
• Session cycles: Cycles per execution session
• Segment count: Number of proof segments
• Execution duration: Wall-clock time

Lower cycle counts = faster and cheaper proving. Optimize guest code to minimize cycles.

Best Practices

• Minimize guest code complexity: Keep computation in the guest focused and efficient
• Choose std vs no_std appropriately:
  • Use no_std for maximum performance when all dependencies support it. Requires all three: #![no_std], #![no_main], and risc0_zkvm_guest::entry!(main);. Benefits: minimizes cycle counts by 10-30%, reduces binary size, still supports heap allocation via alloc crate
  • Use std when dependencies require standard library. Remove all three attributes and use regular fn main(). Use default risc0-zkvm = "3.0" (std included by default)
• Profile with dev mode: Identify bottlenecks before generating expensive proofs
• Batch operations: Process multiple inputs in a single proof when possible
• Leverage GPU acceleration: For local proving, GPU is 10-100x faster than CPU
• Use cryptographic precompiles: Hardware-accelerated cryptographic operations (SHA-256, ECDSA, EdDSA, Keccak) provide 25-50x cycle reduction. Apply Cargo patches for sha2, k256, curve25519-dalek, and other crypto crates to automatically use precompiles

See references/guest-optimization.md for comprehensive guest code optimization techniques including cycle reduction strategies, memory optimization, profiling methods, and zkVM-specific performance patterns. See references/advanced-patterns.md for production deployment patterns.

Additional Resources

Reference Files

For detailed information beyond core concepts:

• references/proof-generation.md - Comprehensive proving workflows, GPU setup, hardware optimization, and performance tuning
• references/blockchain-integration.md - Multi-chain integration patterns, Solidity verifier contracts, deployment strategies for Ethereum, Base, and other blockchains
• references/guest-optimization.md - Guest code optimization techniques, cycle reduction strategies, memory optimization, profiling methods, operation costs, and zkVM-specific performance patterns
• references/cryptographic-precompiles.md - Hardware-accelerated cryptographic operations, patched crate setup, performance benefits, security considerations for SHA-256, ECDSA, EdDSA, Keccak, and other crypto primitives
• references/advanced-patterns.md - Production best practices, debugging strategies, security considerations, and CI/CD integration

Example Files

Working code examples in examples/:

• guest-basic.rs - Basic guest program with I/O operations
• host-basic.rs - Host program with prover setup and verification
• proof-verification.rs - Standalone proof verification example

Utility Scripts

Helper scripts in scripts/:

• setup-project.sh - Automated project scaffolding with common configurations
• benchmark-proof.sh - Performance benchmarking for guest execution and proving
• verify-receipt.sh - Receipt verification testing utility

Quick Reference

Common Commands

# Install/update RISC Zero
curl -L https://risczero.com/install | bash
rzup install
rzup update

# Create new project
cargo risczero new my_project

# Build project
cargo build --release

# Run in dev mode (fast iteration)
RISC0_DEV_MODE=1 cargo run --release

# Generate production proof
RISC0_DEV_MODE=0 cargo run --release

# Performance profiling
RISC0_DEV_MODE=1 RUST_LOG=info RISC0_INFO=1 cargo run --release

Development Workflow

1. Setup: Install rzup and cargo-risczero
2. Create: Scaffold project with cargo risczero new
3. Write: Implement guest logic (computation to prove)
4. Write: Implement host logic (prover orchestration)
5. Iterate: Use dev mode for rapid testing
6. Profile: Measure cycle counts and optimize
7. Prove: Generate production proofs (local or remote)
8. Verify: Test receipt verification
9. Deploy: Integrate with applications or blockchains

Community and Support

• Documentation: https://dev.risczero.com/api/
• GitHub: https://github.com/risc0/risc0
• Discord: Community support and discussion
• Stack Overflow: Tag questions with risc0

Notes

• RISC Zero uses zkSTARKs (not zkSNARKs by default), providing post-quantum security
• Guest programs must be deterministic for proof generation
• Receipts are portable and can be verified anywhere with the ImageID
• Local proving requires significant RAM (16GB+) and benefits from GPU acceleration
• Groth16 wrapping enables efficient on-chain verification but requires trusted setup