risc0_zkvm/
lib.rs

1// Copyright 2024 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 receipt;
79mod receipt_claim;
80pub mod serde;
81pub mod sha;
82
83#[cfg(all(not(target_os = "zkvm"), feature = "prove"))]
84pub use host::recursion;
85
86pub use anyhow::Result;
87#[cfg(not(target_os = "zkvm"))]
88#[cfg(any(feature = "client", feature = "prove"))]
89pub use bytes::Bytes;
90pub use risc0_binfmt::{ExitCode, InvalidExitCodeError, SystemState};
91pub use risc0_zkvm_platform::{align_up, declare_syscall, memory::GUEST_MAX_MEM, PAGE_SIZE};
92
93pub use self::receipt_claim::{
94    Assumption, Assumptions, Input, MaybePruned, Output, PrunedValueError, ReceiptClaim, Unknown,
95};
96
97#[cfg(not(target_os = "zkvm"))]
98#[cfg(feature = "prove")]
99pub use {
100    self::host::{
101        api::server::Server as ApiServer,
102        client::prove::local::LocalProver,
103        recursion::{
104            prove::{prove_registered_zkr, prove_zkr, register_zkr},
105            RECURSION_PO2,
106        },
107        server::{
108            exec::executor::ExecutorImpl,
109            prove::{get_prover_server, HalPair, ProverServer},
110            session::{
111                FileSegmentRef, NullSegmentRef, Segment, SegmentRef, Session, SessionEvents,
112                SimpleSegmentRef,
113            },
114        },
115    },
116    risc0_circuit_rv32im::prove::engine::loader::Loader,
117    risc0_groth16::{
118        docker::stark_to_snark, to_json as seal_to_json, ProofJson as Groth16ProofJson,
119    },
120};
121
122#[cfg(not(target_os = "zkvm"))]
123#[cfg(feature = "bonsai")]
124pub use self::host::client::prove::bonsai::BonsaiProver;
125
126#[cfg(not(target_os = "zkvm"))]
127#[cfg(feature = "client")]
128pub use {
129    self::host::{
130        api::{
131            client::Client as ApiClient, Asset, AssetRequest, Connector, RedisParams, SegmentInfo,
132            SessionInfo,
133        },
134        client::{
135            env::{ExecutorEnv, ExecutorEnvBuilder},
136            prove::{
137                default_executor, default_prover, external::ExternalProver, Executor, Prover,
138                ProverOpts, ReceiptKind,
139            },
140        },
141    },
142    risc0_circuit_rv32im::trace::{TraceCallback, TraceEvent},
143};
144
145#[cfg(not(target_os = "zkvm"))]
146#[cfg(feature = "client")]
147#[cfg(feature = "unstable")]
148pub use self::host::client::env::{CoprocessorCallback, ProveKeccakRequest, ProveZkrRequest};
149
150#[cfg(not(target_os = "zkvm"))]
151#[cfg(feature = "prove")]
152#[cfg(feature = "unstable")]
153pub use self::host::server::prove::keccak::prove_keccak;
154
155#[cfg(not(target_os = "zkvm"))]
156pub use {
157    self::host::{
158        prove_info::{ProveInfo, SessionStats},
159        recursion::{ALLOWED_CONTROL_IDS, ALLOWED_CONTROL_ROOT},
160    },
161    risc0_binfmt::compute_image_id,
162    risc0_circuit_rv32im::control_id::POSEIDON2_CONTROL_IDS,
163    risc0_groth16::Seal as Groth16Seal,
164};
165
166pub use receipt::{
167    AssumptionReceipt, CompositeReceipt, CompositeReceiptVerifierParameters, FakeReceipt,
168    InnerAssumptionReceipt, InnerReceipt, Journal, Receipt, ReceiptMetadata, SegmentReceipt,
169    SegmentReceiptVerifierParameters, SuccinctReceipt, SuccinctReceiptVerifierParameters,
170    VerifierContext, DEFAULT_MAX_PO2,
171};
172//#[cfg(any(not(target_os = "zkvm"), feature = "std"))]
173pub use receipt::{Groth16Receipt, Groth16ReceiptVerifierParameters};
174
175use semver::Version;
176
177/// Reports the current version of this crate.
178pub const VERSION: &str = env!("CARGO_PKG_VERSION");
179
180/// Reports the current version of this crate as represented by a
181/// [semver::Version].
182pub fn get_version() -> Result<Version, semver::Error> {
183    Version::parse(VERSION)
184}
185
186/// Returns `true` if dev mode is enabled.
187#[cfg(feature = "std")]
188pub fn is_dev_mode() -> bool {
189    let is_env_set = std::env::var("RISC0_DEV_MODE")
190        .ok()
191        .map(|x| x.to_lowercase())
192        .filter(|x| x == "1" || x == "true" || x == "yes")
193        .is_some();
194
195    if cfg!(feature = "disable-dev-mode") && is_env_set {
196        panic!("zkVM: Inconsistent settings -- please resolve. \
197            The RISC0_DEV_MODE environment variable is set but dev mode has been disabled by feature flag.");
198    }
199
200    cfg!(not(feature = "disable-dev-mode")) && is_env_set
201}
202
203#[cfg(feature = "metal")]
204#[test]
205fn metal_implies_prove() {
206    // we should be able to access prove feature items when metal has been enabled
207    let _prover = get_prover_server(&ProverOpts::default());
208}
risc0_zkvm/lib.rs

risc0_zkvm/
lib.rs
