Add a README.md for each crate (#345)

* Make READMEs for each crate

* Fix cross-crate links

risc0/build/README.md

@@ -0,0 +1,56 @@
+
+Build RISC Zero zkVM guest code and provide handles to the host side.
+
+In order for the host to execute guest code in the [RISC Zero
+zkVM](risc0_zkvm), the host must be provided a compiled RISC-V ELF file and
+the corresponding ImageID. This crate
+contains the functions needed to take zkVM guest code, build a corresponding
+ELF file and ImageID, and make the ImageID and a path to the ELF file
+available for the host to use.
+
+## Using risc0-build to build guest methods
+
+Using this crate can be a bit delicate, so we encourage you to follow along
+in our [RISC Zero Rust Starter repository](https://github.com/risc0/risc0-rust-starter).
+In that repository, `risc0-build` is used in the
+[`methods` directory](https://github.com/risc0/risc0-rust-starter/tree/main/methods).
+
+Guest methods are embedded for the host to use by calling [embed_methods]
+(or [embed_methods_with_options]) in a [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html).
+An example `build.rs` file would look like
+```no_run
+fn main() {
+    risc0_build::embed_methods();
+}
+```
+
+This requires including `risc0-build` as a _build_ dependency. You will also
+need add a `[package.metadata.risc0]` section to your cargo file. In this
+section, put a `methods` field with a list of relative paths containing the
+guest code. For example, if your guest code is in the `guest` directory,
+then `Cargo.toml` might include
+```toml
+[build-dependencies]
+risc0-build = "0.12"
+
+[package.metadata.risc0]
+methods = ["guest"]
+```
+
+This builds a file `methods.rs` in your cargo output directory which you
+must then include for the host to use. For example, you might make a file
+`src/lib.rs` containing
+```text
+include!(concat!(env!("OUT_DIR"), "/methods.rs"));
+```
+
+This process will generate an image ID (`*_ID`) and the contents of an ELF
+file (`*_ELF`). The names will be derived from the name of the ELF
+binary, which will be converted to ALL_CAPS to comply with Rust naming
+conventions. Thus, if a method binary is named `multiply`, the image ID
+will be named `methods::MULTIPLY_ID` and the contents of the ELF file will
+be named `methods::MULTIPLY_ELF`. These are included at the beginning
+of the host-side code:
+```text
+use methods::{MULTIPLY_ELF, MULTIPLY_ID};
+```

risc0/build/src/lib.rs

@@ -12,62 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Build RISC Zero zkVM guest code and provide handles to the host side
-//!
-//! In order for the host to execute guest code in the [RISC Zero
-//! zkVM](risc0_zkvm), the host must be provided a compiled RISC-V ELF file and
-//! the corresponding ImageID. This crate
-//! contains the functions needed to take zkVM guest code, build a corresponding
-//! ELF file and ImageID, and make the ImageID and a path to the ELF file
-//! available for the host to use.
-//!
-//! ## Using risc0-build to build guest methods
-//!
-//! Using this crate can be a bit delicate, so we encourage you to follow along
-//! in our [RISC Zero Rust Starter repository](https://github.com/risc0/risc0-rust-starter).
-//! In that repository, `risc0-build` is used in the
-//! [`methods` directory](https://github.com/risc0/risc0-rust-starter/tree/main/methods).
-//!
-//! Guest methods are embedded for the host to use by calling [embed_methods]
-//! (or [embed_methods_with_options]) in a [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html).
-//! An example `build.rs` file would look like
-//! ```no_run
-//! fn main() {
-//!     risc0_build::embed_methods();
-//! }
-//! ```
-//!
-//! This requires including `risc0-build` as a _build_ dependency. You will also
-//! need add a `[package.metadata.risc0]` section to your cargo file. In this
-//! section, put a `methods` field with a list of relative paths containing the
-//! guest code. For example, if your guest code is in the `guest` directory,
-//! then `Cargo.toml` might include
-//! ```toml
-//! [build-dependencies]
-//! risc0-build = "0.12"
-//!
-//! [package.metadata.risc0]
-//! methods = ["guest"]
-//! ```
-//!
-//! This builds a file `methods.rs` in your cargo output directory which you
-//! must then include for the host to use. For example, you might make a file
-//! `src/lib.rs` containing
-//! ```text
-//! include!(concat!(env!("OUT_DIR"), "/methods.rs"));
-//! ```
-//!
-//! This process will generate an image ID (`*_ID`) and the contents of an ELF
-//! file (`*_ELF`). The names will be derived from the name of the ELF
-//! binary, which will be converted to ALL_CAPS to comply with Rust naming
-//! conventions. Thus, if a method binary is named `multiply`, the image ID
-//! will be named `methods::MULTIPLY_ID` and the contents of the ELF file will
-//! be named `methods::MULTIPLY_ELF`. These are included at the beginning
-//! of the host-side code:
-//! ```text
-//! use methods::{MULTIPLY_ELF, MULTIPLY_ID};
-//! ```
-
+#![doc = include_str!("../README.md")]
 #![deny(missing_docs)]
 #![deny(rustdoc::broken_intra_doc_links)]
 

risc0/circuit/rv32im/README.md

@@ -0,0 +1,2 @@
+
+The RISC Zero zkVM circuit

risc0/circuit/rv32im/src/lib.rs

@@ -12,8 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! The zkVM circuit
-
+#![doc = include_str!("../README.md")]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 #[cfg(feature = "prove")]

risc0/zeroio/README.md

@@ -0,0 +1,34 @@
+Zeroio provides utilities to communicate efficiently with the guest.
+
+This is similar to serde's "Serialize" and "Deserialize", but has
+different design targets:
+
+* Guest runtime performance is paramount.
+* It's a significant performance degradation for the guest to have to read a
+  value that's not aligned on a 32-bit boundary.
+* Space efficiency is nice, but less important than guest runtime
+   performance.
+* We want to conveniently be able to take cryptographic hashes of a
+  structure.
+
+In response, zeroio does these things differently than serde:
+
+* There is only one on-wire format; zeroio does not try to be as featureful
+  as serde.
+* Datatypes available are much more limited
+* We don't want to spend any cycles deserializing or copying, so we store
+  the data in a format that's easy to access without copying, similarly to
+  the `rkyv' crate.
+* In contrast to rkyv, we use slices instead of pointers to refer to
+  available serialized data.  This allows us to avoid unsafe code.
+* We store all data buffers as [u32] (as opposed to the more common [u8]).
+* There is one canonical format; any serialization of the same data will
+  construct the same structure.  To take a cryptographic hash, we simply
+  hash the [u32] slice.
+* We null-pad all data buffers up to the size of the hash block (with one
+  word remaining) to avoid copying when computing a hash.
+
+Note that for deserializing, while we guarantee sha(a) == sha(b)
+implies deserialize_from(a) == deserialize_from(b), we do not
+guarantee the converse, that deserialize_from(a) ==
+deserialize_from(b) implies a == b.

risc0/zeroio/src/lib.rs

@@ -12,41 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Zeroio provides utilities to communicate efficiently with the guest.
-//!
-//! This is similar to serde's "Serialize" and "Deserialize", but has
-//! different design targets:
-//!
-//! * Guest runtime performance is paramount.
-//! * It's a significant performance degradation for the guest to have to read a
-//!   value that's not aligned on a 32-bit boundary.
-//! * Space efficiency is nice, but less important than guest runtime
-//!   performance.
-//! * We want to conveniently be able to take cryptographic hashes of a
-//!   structure.
-//!
-//! In response, zeroio does these things differently than serde:
-//!
-//! * There is only one on-wire format; zeroio does not try to be as featureful
-//!   as serde.
-//! * Datatypes available are much more limited
-//! * We don't want to spend any cycles deserializing or copying, so we store
-//!   the data in a format that's easy to access without copying, similarly to
-//!   the `rkyv' crate.
-//! * In contrast to rkyv, we use slices instead of pointers to refer to
-//!   available serialized data.  This allows us to avoid unsafe code.
-//! * We store all data buffers as [u32] (as opposed to the more common [u8]).
-//! * There is one canonical format; any serialization of the same data will
-//!   construct the same structure.  To take a cryptographic hash, we simply
-//!   hash the [u32] slice.
-//! * We null-pad all data buffers up to the size of the hash block (with one
-//!   word remaining) to avoid copying when computing a hash.
-//!
-//! Note that for deserializing, while we guarantee sha(a) == sha(b)
-//! implies deserialize_from(a) == deserialize_from(b), we do not
-//! guarantee the converse, that deserialize_from(a) ==
-//! deserialize_from(b) implies a == b.
-
+#![doc = include_str!("../README.md")]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 extern crate alloc;

risc0/zeroio_derive/README.md

@@ -0,0 +1 @@
+Support crate for risc0_zeroio

risc0/zeroio_derive/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![doc = include_str!("../README.md")]
+
 use proc_macro2::TokenStream;
 use quote::{format_ident, quote, ToTokens};
 use syn::{

risc0/zkp/README.md

@@ -0,0 +1,10 @@
+RISC Zero's core Zero Knowledge Proof components for Rust.
+
+These are the core algorithms that prove and verify the execution of RISC Zero's
+RISC-V circuit. This includes utilities such as [core::sha] (which allows faster
+SHA-256 hashing than a naive RISC-V implementation). It is these latter
+utilities that are more commonly used directly from this crate: Developers
+looking to construct (or verify) a zero-knowledge proof with RISC Zero are
+advised to use the [risc0_zkvm] crate instead.
+
+[risc0_zkvm]: https://docs.rs/risc0-zkvm

risc0/zkp/src/adapter.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Interface between the circuit and prover/verifier
+
 use alloc::vec::Vec;
 
 use anyhow::Result;

risc0/zkp/src/lib.rs

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![doc = include_str!("../README.md")]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![deny(rustdoc::broken_intra_doc_links)]
 

risc0/zkp/src/prove/mod.rs

@@ -17,7 +17,7 @@
 //! This module is not typically used directly. Instead, we recommend the
 //! higher-level tools offered in [`risc0_zkvm::prove`].
 //!
-//! [`risc0_zkvm::prove`]: ../../risc0_zkvm/prove/index.html
+//! [`risc0_zkvm::prove`]: https://docs.rs/risc0-zkvm/latest/risc0_zkvm/prove/index.html
 
 mod accum;
 pub mod adapter;

risc0/zkp/src/verify/mod.rs

@@ -17,7 +17,7 @@
 //! This module is not typically used directly. Instead, we recommend calling
 //! [`Receipt::verify`].
 //!
-//! [`Receipt::verify`]: ../../risc0_zkvm/receipt/struct.Receipt.html#method.verify
+//! [`Receipt::verify`]: https://docs.rs/risc0-zkvm/latest/risc0_zkvm/receipt/struct.Receipt.html#method.verify
 
 pub mod adapter;
 mod fri;

risc0/zkvm/README.md

@@ -0,0 +1,25 @@
+The RISC Zero zkVM is a RISC-V virtual machine that produces
+[zero-knowledge proofs](https://en.wikipedia.org/wiki/Zero-knowledge_proof)
+of code it executes. By using the zkVM, a cryptographic
+[Receipt](Receipt) is produced which anyone can [verify](Receipt::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](Receipt).
+
+This is the reference documentation for the RISC Zero zkVM. We have
+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 [Hello Multiply!](https://www.risczero.com/docs/examples/hello_multiply)
+tutorial, which walks you through writing your first zkVM project.
+* A [zkVM Rust starter template](https://github.com/risc0/risc0-rust-starter),
+a template for starting zkVM projects. It includes code for building and
+launching a zkVM guest and guidance on where projects most commonly modify
+host and guest code.
+* The [zkVM Rust examples repository](https://github.com/risc0/risc0-rust-examples),
+which contains various examples using our zkVM.
+* [This clip](https://youtu.be/cLqFvhmXiD0) from our presentation at ZK Hack
+III gives an overview of the RISC Zero zkVM.
+[Our YouTube channel](https://www.youtube.com/@risczero) has many more
+videos as well.
+* And more on [the RISC Zero website](https://www.risczero.com/)!

risc0/zkvm/methods/README.md

@@ -0,0 +1 @@
+RISC Zero zkVM guest code used for testing and benchmarking.

risc0/zkvm/methods/src/lib.rs

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![doc = include_str!("../README.md")]
 #![no_std]
 
 pub mod bench;

risc0/zkvm/platform/README.md

@@ -0,0 +1,3 @@
+
+Platform definitions for the RISC Zero zkVM, including IO port addresses,
+memory regions, and low-level runtime functions.

risc0/zkvm/platform/src/lib.rs

@@ -12,9 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Platform definitions for ZKVM, including IO port addresses, memory
-//! regions, and low-level runtime functions.
-
+#![doc = include_str!("../README.md")]
 #![no_std]
 #![allow(unused_variables)]
 

risc0/zkvm/src/lib.rs

@@ -12,34 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! A virtual machine to produce ZK proofs of computation
-//!
-//! The RISC Zero zkVM is a RISC-V virtual machine that produces
-//! [zero-knowledge proofs](https://en.wikipedia.org/wiki/Zero-knowledge_proof)
-//! of code it executes. By using the zkVM, a cryptographic
-//! [Receipt](Receipt) is produced which anyone can [verify](Receipt::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](Receipt).
-//!
-//! This is the reference documentation for the RISC Zero zkVM. We have
-//! 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 [Hello Multiply!](https://www.risczero.com/docs/examples/hello_multiply)
-//! tutorial, which walks you through writing your first zkVM project.
-//! * A [zkVM Rust starter template](https://github.com/risc0/risc0-rust-starter),
-//! a template for starting zkVM projects. It includes code for building and
-//! launching a zkVM guest and guidance on where projects most commonly modify
-//! host and guest code.
-//! * The [zkVM Rust examples repository](https://github.com/risc0/risc0-rust-examples),
-//! which contains various examples using our zkVM.
-//! * [This clip](https://youtu.be/cLqFvhmXiD0) from our presentation at ZK Hack
-//! III gives an overview of the RISC Zero zkVM.
-//! [Our YouTube channel](https://www.youtube.com/@risczero) has many more
-//! videos as well.
-//! * And more on [the RISC Zero website](https://www.risczero.com/)!
-
+#![doc = include_str!("../README.md")]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(not(feature = "std"), feature(alloc_error_handler))]
 #![deny(rustdoc::broken_intra_doc_links)]