Update docs for 0.18 (#868)

Updates the docs.rs docs for the upcoming 0.18 release. This has three
main parts:
* Updating the introduction to the `guest` module
* Porting the receipts documentation to live on the `Receipt` object, so
it is not hidden after the module restructure.
* Porting the prover documentation to live on the `Prover` object, so it
is not hidden after the module restructure.

I also revised during these ports, in particular expanding the Prover
example code.

risc0/zkvm/src/guest/mod.rs

@@ -12,16 +12,30 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! The RISC Zero ZKVM's guest-side RISC-V API.
+//! The RISC Zero zkVM's guest-side RISC-V API.
 //!
 //! Code that is validated by the [RISC Zero zkVM](crate) is run inside the
 //! guest. In the minimal case, an entrypoint (the guest's "`main`" function)
 //! must be provided by using the [entry! macro](entry). In almost all
-//! practical cases, the guest will want to read private input data using
-//! [env::read] and commit public output data using [env::commit]; additional
-//! I/O functionality is also available in [mod@env].
+//! practical cases, the guest will want to read private input data from the
+//! host and write public data to the journal. In the simplest case, this can be
+//! done with [env::read] and [env::commit], respectively; additional I/O
+//! functionality is also available in [mod@env].
 //!
-//! For example[^starter-ex], the following guest code proves a number is
+//! ## Installation
+//!
+//! To build and run RISC Zero zkVM code, you will need to install the RISC Zero
+//! toolchain, which can be done using the
+//! [`cargo-risczero`](https://crates.io/crates/cargo-risczero) tool:
+//!
+//! ```sh
+//! cargo install cargo-risczero
+//! cargo risczero install
+//! ```
+//!
+//! ## Example
+//!
+//! The following guest code[^starter-ex] proves a number is
 //! composite by multiplying two unsigned integers, and panicking if either is
 //! `1` or if the multiplication overflows:
 //! ```ignore
@@ -52,7 +66,7 @@
 //! [rust guest workarounds](https://github.com/risc0/risc0/issues?q=is%3Aissue+is%3Aopen+label%3A%22rust+guest+workarounds%22)
 //! tag on GitHub.
 //!
-//! [^starter-ex]: The example is based on the [RISC Zero Rust Starter repository](https://github.com/risc0/risc0-rust-starter).
+//! [^starter-ex]: The example is based on the [Factors example](https://github.com/risc0/risc0/tree/main/examples/factors).
 
 #![deny(missing_docs)]
 

risc0/zkvm/src/host/client/prove/mod.rs

@@ -27,8 +27,52 @@ use serde::{Deserialize, Serialize};
 use self::{bonsai::BonsaiProver, external::ExternalProver};
 use crate::{is_dev_mode, ExecutorEnv, Receipt, VerifierContext};
 
-/// A Prover can execute a given [MemoryImage] and produce a [Receipt] that can
-/// be used to verify correct computation.
+/// A Prover can execute a given [MemoryImage] or ELF file and produce a
+/// [Receipt] that can be used to verify correct computation.
+///
+/// # Usage
+/// To produce a proof, you must minimally provide an [ExecutorEnv] and either
+/// an ELF file or a [MemoryImage]. See the
+/// [risc0_build](https://docs.rs/risc0-build/latest/risc0_build/) crate for
+/// more information on producing ELF files from Rust source code.
+///
+/// ```rust
+/// use risc0_zkvm::{
+///     default_prover,
+///     ExecutorEnv,
+///     MEM_SIZE,
+///     MemoryImage,
+///     PAGE_SIZE,
+///     Program,
+///     ProverOpts,
+///     VerifierContext,
+/// };
+/// use risc0_zkvm_methods::FIB_ELF;
+///
+/// # #[cfg(not(feature = "cuda"))]
+/// # {
+/// // A straightforward case with an ELF file
+/// let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
+/// let receipt = default_prover().prove_elf(env, FIB_ELF).unwrap();
+///
+/// // Or you can specify a context and options
+/// // (Using the defaults as we do here is equivalent to the above code.)
+/// let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
+/// let ctx = VerifierContext::default();
+/// let opts = ProverOpts::default();
+/// let receipt = default_prover().prove_elf_with_ctx(env, &ctx, FIB_ELF, &opts).unwrap();
+///
+/// // Or you can prove from a `MemoryImage`
+/// // (generating a `MemoryImage` from an ELF file in this way is equivalent
+/// // to the above code.)
+/// let program = Program::load_elf(FIB_ELF, MEM_SIZE as u32).unwrap();
+/// let image = MemoryImage::new(&program, PAGE_SIZE as u32).unwrap();
+/// let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
+/// let ctx = VerifierContext::default();
+/// let opts = ProverOpts::default();
+/// let receipt = default_prover().prove(env, &ctx, &opts, image).unwrap();
+/// # }
+/// ```
 pub trait Prover {
     /// Return a name for this [Prover].
     fn get_name(&self) -> String;

risc0/zkvm/src/host/receipt.rs

@@ -13,67 +13,6 @@
 // limitations under the License.
 
 //! Manages the output and cryptographic data for a proven computation.
-//!
-//! Receipts are zero-knowledge proofs of computation. They attest that specific
-//! code was executed to generate the information contained in the receipt. The
-//! prover can provide a receipt to an untrusting party to convince them that
-//! the results contained within the receipt came from running specific code.
-//! Conversely, a verify can inspect a receipt to confirm that its results must
-//! have been generated from the expected code, even when this code was run by
-//! an untrusted source.
-//!
-//! There are two types of receipt, a [Receipt] proving the execution
-//! of a [crate::Session], and a [SegmentReceipt] proving the execution of a
-//! [crate::Segment].
-//!
-//! Because [crate::Session]s are user-determined, whereas
-//! [crate::Segment]s are automatically generated, typical use cases will handle
-//! [Receipt]s directly and [SegmentReceipt]s only indirectly as part
-//! of the [Receipt]s that contain them (for instance, by calling
-//! [Receipt::verify], which will itself call
-//! [InnerReceipt::verify] for the interior [InnerReceipt]).
-//!
-//! # Example
-//!
-//! ```rust
-//! # #[cfg(feature = "prove")]
-//! use risc0_zkvm::{default_prover, ExecutorEnv};
-//! use risc0_zkvm_methods::FIB_ELF;
-//!
-//! # #[cfg(not(feature = "cuda"))]
-//! # #[cfg(feature = "prove")]
-//! # {
-//! let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
-//! let receipt = default_prover().prove_elf(env, FIB_ELF).unwrap();
-//! # }
-//! ```
-//!
-//! To confirm that a [Receipt] was honestly generated, use
-//! [Receipt::verify] and supply the ImageID of the code that should
-//! have been executed as a parameter. (See
-//! [risc0_build](https://docs.rs/risc0-build/latest/risc0_build/) for more
-//! information about how ImageIDs are generated.)
-//! ```rust
-//! use risc0_zkvm::Receipt;
-//!
-//! # #[cfg(feature = "prove")]
-//! # use risc0_zkvm::{default_prover, ExecutorEnv};
-//! # use risc0_zkvm_methods::{FIB_ELF, FIB_ID};
-//!
-//! # #[cfg(not(feature = "cuda"))]
-//! # #[cfg(feature = "prove")]
-//! # {
-//! # let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
-//! # let receipt = default_prover().prove_elf(env, FIB_ELF).unwrap();
-//! receipt.verify(FIB_ID).unwrap();
-//! # }
-//! ```
-//!
-//! The public outputs of the [Receipt] are contained in the
-//! [Receipt::journal]. We provide serialization tools in the zkVM
-//! [serde](crate::serde) module, which can be used to read data from the
-//! journal as the same type it was written to the journal. If you prefer, you
-//! can also directly access the [Receipt::journal] as a `Vec<u8>`.
 
 use alloc::{collections::BTreeMap, string::String, vec::Vec};
 use core::fmt::Debug;
@@ -143,10 +82,59 @@ pub struct ReceiptMetadata {
 
 /// A receipt attesting to the execution of a Session.
 ///
-/// A Receipt attests that the `journal` was produced by executing a
-/// [crate::Session] based on a specified memory image. This image is _not_
-/// included in the receipt and must be provided by the verifier when calling
-/// [Receipt::verify].
+/// A Receipt is a zero-knowledge proof of computation. It attests that the
+/// [Receipt::journal] was produced by executing a [crate::Session] based on a
+/// specified memory image. This image is _not_ included in the receipt and must
+/// be provided by the verifier when calling [Receipt::verify].
+///
+/// A prover can provide a Receipt to an untrusting party to convince them that
+/// the results contained within the Receipt (in the [Receipt::journal]) came
+/// from running specific code. Conversely, a verifier can inspect a receipt to
+/// confirm that its results must have been generated from the expected code,
+/// even when this code was run by an untrusted source.
+/// # Example
+///
+/// To create a [Receipt] attesting to the faithful execution of your code, run
+/// one of the `prove` functions from a [crate::Prover].
+///
+/// ```rust
+/// # #[cfg(feature = "prove")]
+/// use risc0_zkvm::{default_prover, ExecutorEnv};
+/// use risc0_zkvm_methods::FIB_ELF;
+///
+/// # #[cfg(not(feature = "cuda"))]
+/// # #[cfg(feature = "prove")]
+/// # {
+/// let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
+/// let receipt = default_prover().prove_elf(env, FIB_ELF).unwrap();
+/// # }
+/// ```
+///
+/// To confirm that a [Receipt] was honestly generated, use
+/// [Receipt::verify] and supply the ImageID of the code that should
+/// have been executed as a parameter. (See
+/// [risc0_build](https://docs.rs/risc0-build/latest/risc0_build/) for more
+/// information about how ImageIDs are generated.)
+/// ```rust
+/// use risc0_zkvm::Receipt;
+/// # #[cfg(feature = "prove")]
+/// # use risc0_zkvm::{default_prover, ExecutorEnv};
+/// # use risc0_zkvm_methods::{FIB_ELF, FIB_ID};
+///
+/// # #[cfg(not(feature = "cuda"))]
+/// # #[cfg(feature = "prove")]
+/// # {
+/// # let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
+/// # let receipt = default_prover().prove_elf(env, FIB_ELF).unwrap();
+/// receipt.verify(FIB_ID).unwrap();
+/// # }
+/// ```
+///
+/// The public outputs of the [Receipt] are contained in the
+/// [Receipt::journal]. We provide serialization tools in the zkVM
+/// [serde](crate::serde) module, which can be used to read data from the
+/// journal as the same type it was written to the journal. If you prefer, you
+/// can also directly access the [Receipt::journal] as a `Vec<u8>`.
 #[derive(Debug, Deserialize, Serialize, PartialEq)]
 pub struct Receipt {
     /// The polymorphic [InnerReceipt].
@@ -159,7 +147,7 @@ pub struct Receipt {
     pub journal: Vec<u8>,
 }
 
-/// An inner receipt can take the form of a collection of [SegmentReceipts] or a
+/// An inner receipt can take the form of a [SegmentReceipts] collection or a
 /// [SuccinctReceipt].
 #[derive(Debug, Deserialize, Serialize, PartialEq)]
 pub enum InnerReceipt {

risc0/zkvm/src/host/server/prove/mod.rs

@@ -13,22 +13,6 @@
 // limitations under the License.
 
 //! Run the zkVM guest and prove its results.
-//!
-//! # Usage
-//! The primary use of this module is to provably run a zkVM guest by use of a
-//! [Session]. See the [Session] documentation for more detailed usage
-//! information.
-//!
-//! ```rust
-//! use risc0_zkvm::{default_prover, ExecutorEnv};
-//! use risc0_zkvm_methods::FIB_ELF;
-//!
-//! # #[cfg(not(feature = "cuda"))]
-//! # {
-//! let env = ExecutorEnv::builder().add_input(&[20]).build().unwrap();
-//! let receipt = default_prover().prove_elf(env, FIB_ELF).unwrap();
-//! # }
-//! ```
 
 mod dev_mode;
 mod exec;

risc0/zkvm/src/host/server/prove/prover_impl.rs

@@ -31,7 +31,7 @@ use crate::{
     InnerReceipt, Loader, Receipt, Segment, SegmentReceipt, Session, VerifierContext,
 };
 
-/// An implementation of a [Prover] that runs locally.
+/// An implementation of a Prover that runs locally.
 pub struct ProverImpl<H, C>
 where
     H: Hal<Field = BabyBear, Elem = Elem, ExtElem = ExtElem>,

risc0/zkvm/src/lib.rs

@@ -70,7 +70,10 @@ pub use self::host::{
 #[cfg(not(target_os = "zkvm"))]
 pub use self::host::{
     control_id::POSEIDON_CONTROL_ID,
-    receipt::{ExitCode, InnerReceipt, Receipt, ReceiptMetadata, SegmentReceipt, VerifierContext},
+    receipt::{
+        ExitCode, InnerReceipt, Receipt, ReceiptMetadata, SegmentReceipt, SegmentReceipts,
+        VerifierContext,
+    },
     recursion::ALLOWED_IDS_ROOT,
 };