risc0_zkvm/
lib.rs

1// Copyright 2025 RISC Zero, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![cfg_attr(not(feature = "std"), no_std)]
16#![deny(rustdoc::broken_intra_doc_links)]
17#![deny(missing_docs)]
18#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
19
20//! The RISC Zero zkVM is a RISC-V virtual machine that produces [zero-knowledge
21//! proofs] of code it executes. By using the zkVM, a cryptographic [receipt] is
22//! produced which anyone can [verify][receipt-verify] was produced by the
23//! zkVM's guest code. No additional information about the code execution (such
24//! as, for example, the inputs provided) is revealed by publishing the
25//! [receipt].
26//!
27//! Additional (non-reference) resources for using our zkVM that you may also
28//! find helpful, especially if you're new to the RISC Zero zkVM. These include:
29//!
30//! * Our [zkVM Tutorial], which walks you through writing your first zkVM
31//!   project.
32//! * The [`cargo risczero` tool]. It includes a `new` command which generates
33//!   code for building and launching a zkVM guest and guidance on where
34//!   projects most commonly modify host and guest code.
35//! * The [examples], which contains various examples using our zkVM.
36//! * [This clip][zkHack] from our presentation at ZK Hack III gives an overview
37//!   of the RISC Zero zkVM. [Our YouTube channel][YouTube] has many more videos
38//!   as well.
39//! * We track zkVM issues with known workarounds using the [rust guest
40//!   workarounds] GitHub tag. If you're having problems running your code in
41//!   the zkVM, you can see if there's a workaround, and if you're using a
42//!   workaround, you can track when it gets resolved to a permanent solution.
43//! * And more on [the RISC Zero developer website][dev-docs]!
44//!
45//! # Crate Feature Flags
46//!
47//! The following feature flags are supported.
48//!
49//! Note that in order to use `risc0-zkvm` in the guest, you must disable the
50//! default features by setting `default-features = false`.
51//!
52//! | Feature          | Target(s)         | Implies    | Description                                                                                                                                                  |
53//! | ---------------- | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
54//! | client           | all except rv32im | std        | Enables the client API.                                                                                                                                      |
55//! | cuda             |                   | prove, std | Enables CUDA GPU acceleration for the prover. Requires CUDA toolkit to be installed.                                                                         |
56//! | 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. |
57//! | metal            | macos             | prove, std | Deprecated - Metal GPU acceleration for the prover is now enabled by default on Apple Silicon.                                                               |
58//! | prove            | all except rv32im | std        | Enables the prover, incompatible within the zkvm guest.                                                                                                      |
59//! | std              | all               |            | Support for the Rust stdlib.                                                                                                                                 |
60//!
61//! [`cargo risczero` tool]: https://crates.io/crates/cargo-risczero
62//! [dev-docs]: https://dev.risczero.com
63//! [examples]: https://dev.risczero.com/api/zkvm/examples
64//! [receipt]: crate::receipt::Receipt
65//! [receipt-verify]: crate::receipt::Receipt::verify
66//! [rust guest workarounds]:
67//!     https://github.com/risc0/risc0/issues?q=is%3Aissue+is%3Aopen+label%3A%22rust+guest+workarounds%22
68//! [YouTube]: https://www.youtube.com/@risczero
69//! [zero-knowledge proofs]: https://en.wikipedia.org/wiki/Zero-knowledge_proof
70//! [zkHack]: https://youtu.be/cLqFvhmXiD0
71//! [zkVM Tutorial]: https://dev.risczero.com/api/zkvm/tutorials/hello-world
72
73extern crate alloc;
74
75pub mod guest;
76#[cfg(not(target_os = "zkvm"))]
77mod host;
78mod mmr;
79mod receipt;
80mod receipt_claim;
81pub mod serde;
82pub mod sha;
83
84pub use ::serde::de::DeserializeOwned;
85pub use anyhow::Result;
86pub use risc0_binfmt::{ExitCode, InvalidExitCodeError, SystemState};
87pub use risc0_zkp::core::digest::{digest, Digest};
88pub use risc0_zkvm_platform::{align_up, declare_syscall, memory::GUEST_MAX_MEM, PAGE_SIZE};
89
90#[cfg(not(target_os = "zkvm"))]
91#[cfg(any(feature = "client", feature = "prove"))]
92pub use bytes::Bytes;
93
94#[cfg(not(target_os = "zkvm"))]
95#[cfg(feature = "prove")]
96pub use {
97    self::host::{
98        api::server::Server as ApiServer,
99        client::prove::{local::LocalProver, local_executor},
100        recursion::{
101            self,
102            prove::{prove_registered_zkr, prove_zkr, register_zkr},
103            RECURSION_PO2,
104        },
105        server::{
106            exec::executor::ExecutorImpl,
107            prove::{get_prover_server, HalPair, ProverServer},
108            session::{
109                FileSegmentRef, NullSegmentRef, Segment, SegmentRef, Session, SessionEvents,
110                SimpleSegmentRef,
111            },
112        },
113    },
114    risc0_groth16::{
115        docker::stark_to_snark, to_json as seal_to_json, ProofJson as Groth16ProofJson,
116    },
117};
118
119#[cfg(not(target_os = "zkvm"))]
120#[cfg(feature = "bonsai")]
121pub use self::host::client::prove::bonsai::BonsaiProver;
122
123#[cfg(not(target_os = "zkvm"))]
124#[cfg(feature = "client")]
125pub use {
126    self::host::{
127        api::{
128            client::Client as ApiClient, Asset, AssetRequest, Connector, RedisParams, SegmentInfo,
129            SessionInfo,
130        },
131        client::{
132            env::{ExecutorEnv, ExecutorEnvBuilder},
133            prove::{
134                default_executor, default_prover, external::ExternalProver, Executor, Prover,
135                ProverOpts, ReceiptKind,
136            },
137        },
138    },
139    risc0_circuit_rv32im::trace::{TraceCallback, TraceEvent},
140};
141
142#[cfg(not(target_os = "zkvm"))]
143#[cfg(feature = "client")]
144#[cfg(feature = "unstable")]
145pub use self::host::client::env::{CoprocessorCallback, ProveKeccakRequest, ProveZkrRequest};
146
147#[cfg(not(target_os = "zkvm"))]
148pub use {
149    self::host::{
150        prove_info::{ProveInfo, SessionStats},
151        recursion::{ALLOWED_CONTROL_IDS, ALLOWED_CONTROL_ROOT},
152    },
153    risc0_binfmt::compute_image_id,
154    risc0_groth16::Seal as Groth16Seal,
155};
156
157pub use self::{
158    receipt::{
159        AssumptionReceipt, CompositeReceipt, CompositeReceiptVerifierParameters, FakeReceipt,
160        Groth16Receipt, Groth16ReceiptVerifierParameters, InnerAssumptionReceipt, InnerReceipt,
161        Journal, Receipt, ReceiptMetadata, SegmentReceipt, SegmentReceiptVerifierParameters,
162        SuccinctReceipt, SuccinctReceiptVerifierParameters, VerifierContext, DEFAULT_MAX_PO2,
163    },
164    receipt_claim::{
165        Assumption, Assumptions, Input, MaybePruned, Output, PrunedValueError, ReceiptClaim,
166        UnionClaim, Unknown,
167    },
168};
169
170use semver::Version;
171
172/// Reports the current version of this crate.
173pub const VERSION: &str = env!("CARGO_PKG_VERSION");
174
175/// Reports the current version of this crate as represented by a
176/// [semver::Version].
177pub fn get_version() -> Result<Version, semver::Error> {
178    Version::parse(VERSION)
179}
180
181/// Returns `true` if dev mode is enabled.
182#[cfg(feature = "std")]
183pub fn is_dev_mode() -> bool {
184    let is_env_set = std::env::var("RISC0_DEV_MODE")
185        .ok()
186        .map(|x| x.to_lowercase())
187        .filter(|x| x == "1" || x == "true" || x == "yes")
188        .is_some();
189
190    if cfg!(feature = "disable-dev-mode") && is_env_set {
191        panic!("zkVM: Inconsistent settings -- please resolve. \
192            The RISC0_DEV_MODE environment variable is set but dev mode has been disabled by feature flag.");
193    }
194
195    cfg!(not(feature = "disable-dev-mode")) && is_env_set
196}
197
198#[cfg(feature = "metal")]
199#[test]
200fn metal_implies_prove() {
201    // we should be able to access prove feature items when metal has been enabled
202    let _prover = get_prover_server(&ProverOpts::default());
203}
risc0_zkvm/lib.rs

risc0_zkvm/
lib.rs
