Crate risc0_zkvm 

The RISC Zero zkVM is a RISC-V virtual machine that produces zero-knowledge proofs of code it executes. By using the zkVM, a cryptographic receipt is produced which anyone can verify was produced by the zkVM’s guest code. No additional information about the code execution (such as, for example, the inputs provided) is revealed by publishing the receipt.

Additional (non-reference) resources for using our zkVM that you may also find helpful, especially if you’re new to the RISC Zero zkVM. These include:

• Our zkVM Tutorial, which walks you through writing your first zkVM project.
• The cargo risczero tool. It includes a new command which generates code for building and launching a zkVM guest and guidance on where projects most commonly modify host and guest code.
• The examples, which contains various examples using our zkVM.
• This clip from our presentation at ZK Hack III gives an overview of the RISC Zero zkVM. Our YouTube channel has many more videos as well.
• We track zkVM issues with known workarounds using the rust guest workarounds GitHub tag. If you’re having problems running your code in the zkVM, you can see if there’s a workaround, and if you’re using a workaround, you can track when it gets resolved to a permanent solution.
• And more on the RISC Zero developer website!

Crate Feature Flags

The following feature flags are supported.

Note that in order to use risc0-zkvm in the guest, you must disable the default features by setting default-features = false.

Feature	Target(s)	Implies	Description
client	all except rv32im	std	Enables the client API.
cuda		prove, std	Enables CUDA GPU acceleration for the prover. Requires CUDA toolkit to be installed.
disable-dev-mode	all except rv32im		Disables dev mode so that proving and verifying may not be faked. Used to prevent a misplaced RISC0_DEV_MODE from breaking security in production systems.
metal	macos	prove, std	Deprecated - Metal GPU acceleration for the prover is now enabled by default on Apple Silicon.
prove	all except rv32im	std	Enables the prover, incompatible within the zkvm guest.
std	all		Support for the Rust stdlib.

Modules

guest

The RISC Zero zkVM’s guest-side RISC-V API.

recursionNon-target_os=zkvm and prove

Prover implementation for the recursion VM.

rpcNon-target_os=zkvm and client

TODO

serde

Serialization and deserialization tools for the RISC Zero zkVM

sha

SHA-256 hashing services

Macros

declare_syscall

Construct a SyscallName declaration at compile time.

digest

Macro for constructing a Digest from a hex string.

entry

Used for defining the guest’s entrypoint and main function.

Structs

ApiClientNon-target_os=zkvm and client

A client implementation for interacting with a zkVM server.

ApiServerNon-target_os=zkvm and prove

A server implementation for handling requests by clients of the zkVM.

Assumption

An assumption made in the course of proving program execution.

Assumptions

A list of assumptions, each a Digest or populated value of an Assumption.

BonsaiProverNon-target_os=zkvm and bonsai

An implementation of a Prover that runs proof workloads via Bonsai.

BytesNon-target_os=zkvm and (client or prove)

A cheaply cloneable and sliceable chunk of contiguous memory.

CompositeReceipt

A receipt composed of one or more SegmentReceipt structs proving a single execution with continuations, and zero or more InnerAssumptionReceipt structs proving any assumptions.

CompositeReceiptVerifierParameters

Verifier parameters for CompositeReceipt.

DefaultProverNon-target_os=zkvm and client

TODO

DevModeDelayNon-target_os=zkvm and prove

Configuration for simulated DevMode delay.

DevModeProverNon-target_os=zkvm and prove

An implementation of a ProverServer for development and testing purposes.

Digest

Digest represents the results of a hashing function. It is always 256 bits of storage although depending on the hash it may have additional structure (for example Poseidon’s output is actually composed of field elements). The storage is in u32’s in part to simplify alignment requirements, especially in the zkVM.

ExecutorEnvNon-target_os=zkvm and client

The Executor is configured from this object.

ExecutorEnvBuilderNon-target_os=zkvm and client

A builder pattern used to construct an ExecutorEnv.

ExecutorImplNon-target_os=zkvm and prove

The proving phase uses an execution trace generated by the Executor.

ExternalProverNon-target_os=zkvm and client

An implementation of a Prover that runs proof workloads via an external r0vm process.

FakeReceipt

A fake receipt for testing and development.

FileSegmentRefNon-target_os=zkvm and prove

A basic implementation of a SegmentRef that saves the segment to a file

Groth16Receipt

A receipt composed of a Groth16 over the BN_254 curve

Groth16ReceiptVerifierParameters

Verifier parameters used to verify a Groth16Receipt.

Groth16SealNon-target_os=zkvm

Groth16 seal object encoded in big endian.

HalPairNon-target_os=zkvm and prove

A pair of Hal and CircuitHal.

Input

Input field in the ReceiptClaim, committing to a public value accessible to the guest.

InvalidExitCodeError

Error returned when a (system, user) exit code pair is an invalid representation.

Journal

A record of the public commitments for a proven zkVM execution.

LocalProverNon-target_os=zkvm and prove

A Prover implementation that selects a ProverServer by calling get_prover_server.

NullSegmentRefNon-target_os=zkvm and prove

Implementation of a SegmentRef that does not save the segment.

Output

Output field in the ReceiptClaim, committing to a claimed journal and assumptions list.

PreflightResultsNon-target_os=zkvm and prove

The results of running preflight on a Segment.

ProveInfoNon-target_os=zkvm

Information returned by the prover including receipt as well as other information useful for debugging

ProveKeccakRequestNon-target_os=zkvm and client

A Keccak proof request.

ProverOptsNon-target_os=zkvm and client

Options to configure a Prover.

PrunedValueError

Error returned when the source value was pruned, and is not available.

Receipt

A receipt attesting to the execution of a guest program.

ReceiptClaim

Public claims about a zkVM guest execution, such as the journal committed to by the guest.

ReceiptMetadata

Metadata providing context on the receipt.

RedisParamsNon-target_os=zkvm and client

Determines the parameters for AssetRequest::Redis

SegmentNon-target_os=zkvm and prove

The execution trace of a portion of a program.

SegmentInfoNon-target_os=zkvm and client

Provides information about a segment of execution.

SegmentReceipt

A receipt attesting to the execution of a Segment.

SegmentReceiptVerifierParameters

Verifier parameters used to verify a SegmentReceipt.

SessionNon-target_os=zkvm and prove

The execution trace of a program.

SessionInfoNon-target_os=zkvm and client

Provides information about the result of execution.

SessionStatsNon-target_os=zkvm

Struct containing information about a prover’s cycle count after running the guest program

SimpleSegmentRefNon-target_os=zkvm and prove

A very basic implementation of a SegmentRef.

SuccinctReceipt

A succinct receipt, produced via recursion, proving the execution of the zkVM with a STARK.

SuccinctReceiptVerifierParameters

Verifier parameters used to verify a SuccinctReceipt.

SystemState

Represents the public state of a segment, needed for continuations and receipt verification.

UnionClaim

Each UnionClaim can be used as an inner node in a Merkle mountain accumulator, the root of which commits to a set of claims.

VerifierContext

Context available to the verification process.

Work

A compact representation of completed work within Proof of Verifiable Work (PoVW).

WorkClaim

A wrapper around the underlying claim that additionally includes the amount of verifiable work completed, and the nonces used, in the process of proving the claim.

Enums

AssetNon-target_os=zkvm and client

Determines the format of an asset.

AssetRequestNon-target_os=zkvm and client

Determines the format of an asset request.

AssumptionReceipt

An assumption attached to a guest execution as a result of calling env::verify or env::verify_integrity.

ExitCode

Exit condition indicated by the zkVM at the end of the guest execution.

GenericReceipt

A receipt that can hold different types of cryptographic proofs for a given claim.

InnerAssumptionReceipt

An enumeration of receipt types similar to InnerReceipt, but for use in AssumptionReceipt. Instead of proving only RISC-V execution with ReceiptClaim, this type can prove any claim implemented by one of its inner types.

InnerReceipt

A lower level receipt, containing the cryptographic seal (i.e. zero-knowledge proof) and verification logic for a specific proof system and circuit. All inner receipt types are zero-knowledge proofs of execution for a RISC-V zkVM.

MaybePruned

Either a source value or a hash Digest of the source value.

ReceiptKindNon-target_os=zkvm and client

An enumeration of receipt kinds that can be requested to be generated.

TraceEventNon-target_os=zkvm and client

An event traced from the running VM.

Unknown

A receipt (e.g. SuccinctReceipt) may have an unknown claim type when only the digest of the claim is needed, and the full claim value cannot be determined by the compiler. This allows for a collection of receipts to be created even when the underlying claims are of heterogeneous types (e.g. Vec<SuccinctReceipt<Unknown>>).

Constants

ALLOWED_CONTROL_IDSNon-target_os=zkvm

Control IDs allowed in the default set of recursion programs. Includes control IDs for the base set of recursion programs, and each power-of-two of the rv32im circuit, using Poseidon2.

ALLOWED_CONTROL_ROOTNon-target_os=zkvm

Root of the Merkle tree constructed from ALLOWED_CONTROL_IDS, using Poseidon2.

DEFAULT_MAX_PO2

Maximum segment size, as a power of two (po2) that the default verifier parameters will accept.

GUEST_MAX_MEM

PAGE_SIZE

Size of a zkVM memory page.

RECURSION_PO2Non-target_os=zkvm and prove

Number of rows to use for the recursion circuit witness as a power of 2.

VERSION

Reports the current version of this crate.

Traits

ConnectorNon-target_os=zkvm and client

Connects a zkVM client and server

CoprocessorCallbackNon-target_os=zkvm and client

A trait that supports the ability to be notified of proof requests on-demand.

DeserializeOwned

A data structure that can be deserialized without borrowing any data from the deserializer.

ExecutorNon-target_os=zkvm and client

An Executor can execute a given ELF binary.

ProverNon-target_os=zkvm and client

A Prover can execute a given ELF binary and produce a Receipt that can be used to verify correct computation.

ProverServerNon-target_os=zkvm and prove

A ProverServer can execute a given ELF binary and produce a ProveInfo which contains a Receipt that can be used to verify correct computation.

SegmentRefNon-target_os=zkvm and prove

A reference to a Segment.

SessionEventsNon-target_os=zkvm and prove

The Events of Session

TraceCallbackNon-target_os=zkvm and client

A callback used to collect TraceEvents.

Functions

align_up

Align address upwards.

compute_image_idNon-target_os=zkvm

Compute and return the ImageID of the specified combined user ELF + kernel ELF binary.

default_executorNon-target_os=zkvm and client

Return a default Executor based on environment variables and feature flags.

default_proverNon-target_os=zkvm and client

Return a default Prover based on environment variables and feature flags.

get_prover_serverNon-target_os=zkvm and prove

Select a ProverServer based on the specified ProverOpts.

get_version

Reports the current version of this crate as represented by a semver::Version.

is_dev_modeDeprecatedstd

Returns true if dev mode is enabled.

local_executorNon-target_os=zkvm and prove

Return a local Executor.

prove_registered_zkrNon-target_os=zkvm and prove

Prove the specified program identified by the control_id using the specified input.

prove_zkrNon-target_os=zkvm and prove

Prove the specified program identified by the control_id using the specified input.

register_zkrNon-target_os=zkvm and prove

Registers a function to retrieve a recursion program (zkr) based on a control id.

Type Aliases

Result

Result<T, Error>