Skip to main content

​
risc0-zkp

The risc0-zkp crate provides the core zero-knowledge proof system primitives used by RISC Zero, including field arithmetic, hash functions, and the FRI-based STARK protocol implementation.

​
Installation

[dependencies]
risc0-zkp = "1.3.0"

​
Overview

This is a low-level crate that implements the cryptographic foundations of the RISC Zero proof system. Most users should use the higher-level risc0-zkvm crate instead.

​
Feature Flags

​
prove
feature
Enables proof generation functionality.
  • Implies: std
  • Enables: Prover, HAL traits, and proof generation
​
cuda
feature
Enables CUDA GPU acceleration.
  • Implies: prove
  • Requirements: CUDA toolkit
​
metal
feature
Enables Metal GPU acceleration (macOS).
  • Implies: prove
​
std
feature
Enables Rust standard library support.
​
circuit_debug
feature
Enables circuit debugging features.

​
Core Modules

​
field

​
field
module
Finite field implementations.
pub mod field {
    pub mod baby_bear;
    pub mod goldilocks;
}
Baby Bear Field:
  • Prime: 2^31 - 2^27 + 1
  • 4-element extension field for FRI protocol

​
core::digest

​
Digest
struct
256-bit cryptographic digest.
pub struct Digest {
    pub words: [u32; 8],
}

impl Digest {
    pub const fn new(words: [u32; 8]) -> Self;
    pub fn from_bytes(bytes: [u8; 32]) -> Self;
    pub fn as_bytes(&self) -> [u8; 32];
    pub fn as_words(&self) -> &[u32; 8];
}
Constants:
  • DIGEST_WORDS: usize = 8
  • DIGEST_SHORTS: usize = 16
  • DIGEST_BYTES: usize = 32

​
hal

​
hal
module
Hardware Abstraction Layer for different compute backends.
pub trait Hal {
    type Elem: Elem;
    type ExtElem: ExtElem;
    type Buffer<T>: Buffer<T>;
    
    fn alloc_elem(&self, name: &str, size: usize) 
        -> Self::Buffer<Self::Elem>;
    // ... more methods
}
Implementations:
  • CPU (default)
  • CUDA (with cuda feature)
  • Metal (with metal feature)

​
Proof System Constants

​
MIN_CYCLES_PO2
const
Minimum power of 2 for cycle count.
pub const MIN_CYCLES_PO2: usize = 13;
pub const MIN_CYCLES: usize = 8192; // 2^13
​
MAX_CYCLES_PO2
const
Maximum power of 2 for cycle count.
pub const MAX_CYCLES_PO2: usize = 24;
pub const MAX_CYCLES: usize = 16777216; // 2^24
​
QUERIES
const
Number of FRI queries for security.
pub const QUERIES: usize = 50; // 97-bit conjectured security
​
INV_RATE
const
Inverse of Reed-Solomon expansion rate.
pub const INV_RATE: usize = 4;
​
FRI_FOLD
const
FRI folding factor.
pub const FRI_FOLD: usize = 16; // 2^4

​
Verification

​
VerificationError

​
VerificationError
enum
Errors that can occur during verification.
pub enum VerificationError {
    InvalidProof,
    ReceiptFormatError,
    ImageVerificationError,
    // ... more variants
}

​
verify

​
verify
module
Verification functions and traits.
pub mod verify {
    pub trait Verifier {
        fn verify_proof(
            &self,
            seal: &[u32],
            image_id: &Digest,
        ) -> Result<(), VerificationError>;
    }
}

​
Adapter

​
adapter
module
Circuit adapter traits and implementations.
pub trait CircuitCoreDef<F: Field> {
    const OUTPUT_SIZE: usize;
    const MIX_SIZE: usize;
}

pub trait TapsProvider {
    fn get_taps(&self) -> &'static TapSet<'static>;
}

​
Layout

​
layout
module
Memory layout definitions for proof generation.
pub mod layout {
    pub struct LayoutRegistry;
    
    impl LayoutRegistry {
        pub fn get_layout(po2: usize) -> &'static Layout;
    }
}

​
Prove

​
prove
module
Proof generation (available with prove feature).
pub mod prove {
    pub struct Prover<H: Hal> {
        // ...
    }
    
    impl<H: Hal> Prover<H> {
        pub fn prove(&self, ...) -> Result<Vec<u32>>;
    }
}

​
Taps

​
taps
module
Register tap definitions for constraint systems.
pub struct TapSet<'a> {
    pub taps: &'a [TapData],
    pub combo_count: usize,
}

pub struct TapData {
    pub offset: usize,
    pub back: usize,
    pub combo: usize,
    pub skip: usize,
}

​
Merkle

​
merkle
module
Merkle tree implementations.
pub struct MerkleTree {
    // ...
}

impl MerkleTree {
    pub fn new(leaves: &[Digest]) -> Self;
    pub fn root(&self) -> &Digest;
    pub fn prove(&self, idx: usize) -> MerkleProof;
}

​
Examples

​
Using Digest

use risc0_zkp::core::digest::Digest;

// Create from words
let digest = Digest::new([1, 2, 3, 4, 5, 6, 7, 8]);

// Convert to bytes
let bytes = digest.as_bytes();

// Parse from hex
let digest = Digest::from_hex(
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
)?;

​
Field Arithmetic

use risc0_zkp::field::baby_bear::{BabyBearElem, BabyBearExtElem};
use risc0_zkp::field::{Elem, ExtElem};

// Base field element
let a = BabyBearElem::new(42);
let b = BabyBearElem::new(17);
let c = a + b;

// Extension field element
let x = BabyBearExtElem::from_subelems([a, b, c, BabyBearElem::ZERO]);

​
HAL Usage

use risc0_zkp::hal::{Hal, cpu::CpuHal};
use risc0_zkp::field::baby_bear::BabyBearElem;

let hal = CpuHal::new();

// Allocate buffer
let buffer = hal.alloc_elem("test", 1024);

// Copy data
let data = vec![BabyBearElem::new(1); 1024];
let device_buf = hal.copy_from_elem("data", &data);

​
Performance

The risc0-zkp crate is optimized for performance:
  • CPU: Vectorized operations using AVX2/AVX512
  • GPU (CUDA): Parallel FFT and field operations
  • GPU (Metal): Optimized for Apple Silicon

​
Benchmarking

# Benchmark hash functions
cargo bench --features prove --bench hash

# Benchmark with GPU
cargo bench --features cuda --bench hash

​
Security

The RISC Zero proof system provides:
  • Conjectured Security: 97 bits (with 50 FRI queries)
  • Zero-Knowledge: Proofs reveal nothing about private inputs
  • Soundness: Unforgeable proofs assuming computational hardness

Build docs developers (and LLMs) love

Get started for freeTalk to us