Re-name factors-->hello-world; move tutorial out of readme (#765)

---------

Co-authored-by: Tim Zerrell <tim.zerrell@risczero.com>
Co-authored-by: hans <hmrtn@pm.me>

examples/Cargo.toml

@@ -7,7 +7,7 @@ members = [
     "digital-signature",
     "digital-signature/core",
     "ecdsa",
-    "factors",
+    "hello-world",
     "json",
     "json/core",
     "password-checker",

examples/factors/Cargo.toml → examples/hello-world/Cargo.toml

@@ -1,10 +1,10 @@
 [package]
-name = "factors"
+name = "hello-world"
 version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-factors-methods = { path = "methods" }
+hello-world-methods = { path = "methods" }
 risc0-zkvm = { path = "../../risc0/zkvm" }
 serde = "1.0"
 

examples/hello-world/README.md

@@ -0,0 +1,69 @@
+# Hello World for the RISC Zero zkVM
+
+Welcome!
+
+This `hello-world` demo is a minimal application for the RISC Zero [zkVM], designed to help you get started building zkVM applications.
+
+For a step-by-step guide to building your first zkVM application, we recommend [this tutorial].
+
+## Quick Start
+First, [install Rust] if you don't already have it.
+Then, run the example with:
+```bash
+cargo run --release
+```
+
+Congratulations! You just constructed a zero-knowledge proof that you know the factors of 391.
+
+[install Rust]: https://doc.rust-lang.org/cargo/getting-started/installation.html
+
+## Use Cases
+
+Writing an application for the RISC Zero [zkVM] is the easiest way for software developers to produce zero-knowledge proofs.
+Whether or not you're [building for blockchains], RISC Zero offers the most flexible and mature ecosystem for developing applications that involve ZKPs.
+
+You can run the zkVM locally and your secrets will never leave your own machine, or you can upload your program & inputs to [Bonsai] for remote proving.
+
+## Project Organization
+zkVM applications are organized into a [host program] and a [guest program].
+The host program can be found in [`src/main.rs`](src/main.rs) and the guest program can be found in [`methods/guest/src/main.rs`](methods/guest/src/main.rs).
+
+The [host] first [executes] the guest program and then [proves the execution] to construct a [receipt].
+The receipt can be passed to a third party, who can examine the [journal] to check the program's outputs and can [verify] the [receipt] to ensure the integrity of the [guest program]'s execution.
+
+[`src/main.rs`]: /src/main.rs
+[`methods/guest/src/main.rs`]: methods/guest/src/main.rs
+[host]: https://dev.risczero.com/terminology#host
+[executes]: https://dev.risczero.com/terminology#execute
+[guest program]: https://dev.risczero.com/terminology#guest-program
+[host program]: https://dev.risczero.com/terminology#host-program
+[proves the execution]: https://dev.risczero.com/terminology#prove
+[receipt]: https://dev.risczero.com/terminology#receipt
+[verify]: https://dev.risczero.com/terminology#verify
+[journal]: https://dev.risczero.com/terminology#journal
+
+### What gets proven?
+The [receipt] proves that the [guest program] was executed correctly, and that the contents of `receipt.journal` match what was written by `env::commit()` during the execution of the guest program.
+
+By running the demo, Alice demonstrates that she knows two integers that multiply to give the number written in `receipt.journal`.
+Thus, Alice proves that the number written in `receipt.journal` is composite — and that she knows the factors — without revealing any further information.
+
+[receipt]: https://dev.risczero.com/terminology#receipt
+[journal]: https://dev.risczero.com/terminology#journal
+[guest program]: https://dev.risczero.com/terminology#guest-program
+[zkVM]: https://dev.risczero.com/zkvm
+[building for blockchains]: https://twitter.com/RiscZero/status/1677316664772132864
+[application]: https://dev.risczero.com/zkvm/developer-guide/zkvm-app-structure
+[Bonsai]: https://dev.bonsai.xyz
+
+## Tutorial: Building your first zkVM Application
+For a step-by-step guide to building first zkVM application, we recommend [this tutorial]. For more materials, check out the [developer docs].
+
+[RISC Zero]: https://risczero.com
+[this tutorial]: https://github.com/risc0/risc0/tree/main/examples/hello-world/tutorial.md
+[developer docs]: https://dev.risczero.com/zkvm
+
+
+
+
+

examples/factors/methods/Cargo.toml → examples/hello-world/methods/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "factors-methods"
+name = "hello-world-methods"
 version = "0.1.0"
 edition = "2021"
 

examples/factors/src/lib.rs → examples/hello-world/src/lib.rs

@@ -13,15 +13,20 @@
 // limitations under the License.
 
 #[doc = include_str!("../README.md")]
-use factors_methods::MULTIPLY_ELF;
+use hello_world_methods::MULTIPLY_ELF;
 use risc0_zkvm::{
     default_prover,
     serde::{from_slice, to_vec},
     ExecutorEnv, Receipt,
 };
 
-// Multiply them inside the ZKP
-pub fn multiply_factors(a: u64, b: u64) -> (Receipt, u64) {
+// This is a Hello World demo for the RISC Zero zkVM.
+// By running the demo, Alice can produce a receipt that proves that she knows
+// some numbers a and b, such that a*b == 391.
+// The factors a and b are kept secret.
+
+// Compute the product a*b inside the zkVM
+pub fn multiply(a: u64, b: u64) -> (Receipt, u64) {
     let env = ExecutorEnv::builder()
         // Send a & b to the guest
         .add_input(&to_vec(&a).unwrap())
@@ -51,10 +56,10 @@ mod tests {
     use super::*;
 
     #[test]
-    fn test_factors() {
+    fn test_hello_world() {
         const TEST_FACTOR_ONE: u64 = 17;
         const TEST_FACTOR_TWO: u64 = 23;
-        let (_, result) = multiply_factors(17, 23);
+        let (_, result) = multiply(17, 23);
         assert_eq!(
             result,
             TEST_FACTOR_ONE * TEST_FACTOR_TWO,

examples/factors/src/main.rs → examples/hello-world/src/main.rs

@@ -12,12 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use factors::multiply_factors;
-use factors_methods::MULTIPLY_ID;
+use hello_world::multiply;
+use hello_world_methods::MULTIPLY_ID;
 
 fn main() {
     // Pick two numbers
-    let (receipt, _) = multiply_factors(17, 23);
+    let (receipt, _) = multiply(17, 23);
 
     // Here is where one would send 'receipt' over the network...
 

examples/factors/README.md → examples/hello-world/tutorial.md

@@ -1,37 +1,26 @@
-# Factors
+# Tutorial: Building your first zkVM application
+Welcome!
 
-The _factors_ example is a minimalistic RISC Zero zkVM proof. The prover demonstrates that they know two nontrivial factors (i.e. both greater than 1) of a number, without revealing what those factors are. Thus, the prover demonstrates that a number is composite — and that they know the factors — without revealing any further information about the number.
+This tutorial will walk you through building your first [zkVM application].
+By following the steps in this guide, you will:
+- Use the [cargo risczero] tool to create a blank [starter template]
+- Make the handful of changes necessary to create a functional zkVM application
+- Finish the tutorial with an exact copy of the [host] and [guest] programs from the [hello-world] example.
 
-## Quick Start
-First, [install Rust] if you don't already have it.
-
-Next, install the `cargo-risczero` tool and install the toolchain with:
-
-```bash
-cargo install cargo-risczero
-cargo risczero install
-```
-
-Then, run the example with:
-```bash
-cargo run --release
-```
+For more resources for building zkVM applications, check out our [developer docs].
 
-Congratulations! You just constructed a zero-knowledge proof that you know the factors of 391.
-
-[install Rust]: https://doc.rust-lang.org/cargo/getting-started/installation.html
-
-# Tutorial
-
-## How to Recreate _Factors_
-
-This example is a good introduction for beginners new to RISC Zero; if you're looking to get started creating RISC Zero zkVM projects, you're in the right place!
-If you're looking for a higher level overview of the Factors example, check out the [Understanding Factors] explainer instead.
-We'll spend the rest of this README walking you through how to recreate the factors example for yourself, assuming no prior knowledge of RISC Zero.
+[zkVM application]: https://dev.risczero.com/zkvm
+[cargo risczero]: https://docs.rs/cargo-risczero/latest/cargo_risczero/
+[starter template]: https://github.com/risc0/risc0/tree/v0.16.0/templates/rust-starter
+[hello-world]: https://github.com/risc0/risc0/tree/v0.16.0/examples/hello-world
+[developer docs]: https://dev.risczero.com/zkvm
+[host]: https://dev.risczero.com/terminology#host-program
+[guest]: https://dev.risczero.com/terminology#guest-program
 
 ## Step 1: Create a new project
 
-First, [install Rust] if you don't already have it. Next you can create a RISC Zero zkVM project with boilerplate already filled out using our [`cargo risczero` tool]:
+First, [install Rust] if you don't already have it.
+Now, you can create a RISC Zero zkVM project from the command line:
 
 ```bash
 ## Install from crates.io
@@ -41,18 +30,21 @@ cargo risczero install
 # Navigate to where you want to create your project
 cd wherever/you/want
 
-# Create a project from our starter template
-cargo risczero new factors
+## Create a project from our starter template
+cargo risczero new hello-world
 ```
-This will create a project named `factors` in the directory where you ran the `cargo risczero new` command. Now we can enter our new project's directory and start working on it!
+This will create a project named `hello-world` in the directory where you ran the [`cargo risczero new`] command. Now we can enter our new project's directory and start working on it!
 ```bash
-cd factors
+cd hello-world
 ```
 
+[`cargo risczero new`]: https://docs.rs/cargo-risczero/latest/cargo_risczero/#new
+[install Rust]: https://www.rust-lang.org/tools/install
+
 ## Step 2: Give the methods package a name
 
-The methods package contains the program that executes on the guest zkVM as well as a few supporting libraries. Before we proceed, let's change its name in `methods/Cargo.toml` to match the name of our project, renaming `name = methods` to `name = factors-methods`.
-Also in `host/Cargo.toml`, rename `methods = { path = "../methods" }` to `factors-methods = { path = "../methods" }` in order to locate the renamed guest code.
+The methods package contains the program that executes on the guest zkVM as well as a few supporting libraries. Before we proceed, let's change its name in `methods/Cargo.toml` to match the name of our project, renaming `name = methods` to `name = hello-world-methods`.
+Also in `host/Cargo.toml`, rename `methods = { path = "../methods" }` to `hello-world-methods = { path = "../methods" }` in order to locate the renamed guest code.
 
 Parts of this package are included in the driver program `src/main.rs`, so change the line
 
@@ -63,12 +55,12 @@ use methods::{METHOD_NAME_ELF, METHOD_NAME_ID};
 to
 
 ```no_compile
-use factors_methods::{METHOD_NAME_ELF, METHOD_NAME_ID};
+use hello_world_methods::{METHOD_NAME_ELF, METHOD_NAME_ID};
 ```
 
 ## Step 3: Give the guest program and its packages a name
 
-Take a moment to look inside the methods package directory. The `factors` project will call a program that executes on the guest zkVM whose source is found in `methods/guest/src/main.rs`. Our next step will be to name this guest program.
+Take a moment to look inside the methods package directory. The `hello-world` project will call a program that executes on the guest zkVM whose source is found in `methods/guest/src/main.rs`. Our next step will be to name this guest program.
 
 
 Edit `methods/guest/Cargo.toml`, changing the line `name = "method_name"` to instead read `name = "multiply"`.
@@ -77,18 +69,18 @@ Edit `methods/guest/Cargo.toml`, changing the line `name = "method_name"` to ins
 In order to access guest code from the host driver program, the host program `host/src/main.rs` includes two guest methods: `METHOD_NAME_ELF` and `METHOD_NAME_ID`.
 
 ```no_compile
-use factors_methods::{METHOD_NAME_ELF, METHOD_NAME_ID};
+use hello_world_methods::{METHOD_NAME_ELF, METHOD_NAME_ID};
 
 ```
 
 Both of these must be changed to reflect the new guest program name:
 
 ```
-use factors_methods::{MULTIPLY_ELF, MULTIPLY_ID};
+use hello_world_methods::{MULTIPLY_ELF, MULTIPLY_ID};
 ```
 (As an aside, if you add more than one callable guest program to your next RISC Zero zkVM project, you'll need to include `ELF` and `ID` references once for each guest file.)
 
-While we're at it, let's update the references to `METHOD_NAME_ELF` and `METHOD_NAME_ID` in `factors/host/src/main.rs` to reflect our new program name. Don't worry about why these lines are included yet; for now, we're just being diligent not to leave dead references behind.
+While we're at it, let's update the references to `METHOD_NAME_ELF` and `METHOD_NAME_ID` in `hello-world/host/src/main.rs` to reflect our new program name. Don't worry about why these lines are included yet; for now, we're just being diligent not to leave dead references behind.
 
 Here are what the other two lines with `METHOD_NAME_ELF` and `METHOD_NAME_ID` should look like after updating:
 
@@ -108,12 +100,13 @@ Use this command any time you'd like to check your progress.
 
 ## Concept break: How do we run and prove the guest program?
 
-Our next objective is to provide the guest program with input. Before we implement this, let's take a closer look at how we run and prove the guest program in `factors/host/src/main.rs`.
+
+Our next objective is to provide the guest program with input. Before we implement this, let's take a closer look at how we run and prove the guest program in `hello-world/src/main.rs`.
 
 In the starter template project, our host driver program creates an executor environment before constructing a prover.  When `Prover::prove_elf()` is called, it will produce a receipt:
 
 ```rust
-    use factors_methods::{MULTIPLY_ELF, MULTIPLY_ID};
+    use hello_world_methods::{MULTIPLY_ELF, MULTIPLY_ID};
     use risc0_zkvm::{
       default_prover,
       serde::{from_slice, to_vec},
@@ -138,7 +131,7 @@ In the starter template project, our host driver program creates an executor env
 
 ## Step 5 (Host): Share two values with the guest
 
-In this step, we'll be continuing to modify `factors/host/src/main.rs`.
+In this step, we'll be continuing to modify `hello-world/src/main.rs`.
 Let's start by picking some aesthetically pleasing primes:
 ```
 fn main() {
@@ -152,7 +145,7 @@ We'd like the host to make the values of `a` and `b` available to the guest prio
  We need to add these values as inputs before the executor environment is built:
 
  ```rust
-    use factors_methods::{MULTIPLY_ELF, MULTIPLY_ID};
+    use hello_world_methods::{MULTIPLY_ELF, MULTIPLY_ID};
     use risc0_zkvm::{serde::to_vec, ExecutorEnv};
 
     let a: u64 = 17;
@@ -230,7 +223,7 @@ Once more, the program won't do anything, but it should run successfully and bui
 
 ## Step 7 (Host): Generate a receipt and read its journal contents
 
-For this step, we return to the main file for the host driver program at `factors/host/src/main.rs`, which currently has a placeholder comment asking to fill in with code for handling the [receipt]:
+For this step, we return to the main file for the host driver program at `hello-world/host/src/main.rs`, which currently has a placeholder comment asking to fill in with code for handling the [receipt]:
 
 ```no_compile
     // Run the prover to produce a receipt.
@@ -241,7 +234,7 @@ In a real-world scenario, we'd want to hand the [receipt] to someone else, but r
 So, let's extract the [journal]'s contents by replacing the "`TODO`" in the above code snippet with the following lines.
 
 ```rust
-    use factors_methods::{MULTIPLY_ELF, MULTIPLY_ID};
+    use hello_world_methods::{MULTIPLY_ELF, MULTIPLY_ID};
     use risc0_zkvm::{
       default_prover,
       ExecutorEnv,
@@ -276,12 +269,9 @@ Or, if you believe you've found a bug or other problem in our code, please open
 
 If you're ready to start building more complex projects, we recommend taking a look at the other examples in our [examples directory] and looking through our further [Getting Started resources] for more project ideas that use zero-knowledge proofs.
 
-[install Rust]: https://www.rust-lang.org/tools/install
-[`cargo risczero` tool]: https://crates.io/crates/cargo-risczero
-[examples directory]: https://github.com/risc0/risc0/tree/main/examples
-[Getting Started resources]: https://www.risczero.com/docs/
-[Discord]: https://discord.com/invite/risczero
+[examples directory]: https://github.com/risc0/risc0/tree/v0.16.3/examples
+[Getting Started resources]: https://dev.risczero.com/zkvm
+[Discord]: https://discord.gg/risczero
 [issue]: https://github.com/risc0/risc0/issues
-[receipt]: https://docs.rs/risc0-zkvm/latest/risc0_zkvm/receipt/struct.Receipt.html
-[journal]: https://docs.rs/risc0-zkvm/latest/risc0_zkvm/receipt/struct.Receipt.html#structfield.journal
-[Understanding Factors]: https://www.risczero.com/docs/examples/starter
+[receipt]: https:/dev.risczero.com/terminology#receipt
+[journal]: https:/dev.risczero.com/terminology#journal

risc0/zkvm/README.md

@@ -10,13 +10,13 @@ docs.rs](https://docs.rs/risc0-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 [Factors](https://github.com/risc0/risc0/tree/main/examples/factors#tutorial)
-tutorial, which walks you through writing your first zkVM project.
+* Our [Hello World](https://github.com/risc0/risc0/tree/main/examples/hello-world) demo -- a minimal zkVM application that works out-of-the-box.
+* Our [zkVM Tutorial](https://github.com/risc0/risc0/tree/main/examples/hello-world/tutorial.md), which walks you through writing your first zkVM project.
 * The [`cargo risczero` tool](https://crates.io/crates/cargo-risczero). 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 [zkVM Rust examples
-directory](https://github.com/risc0/risc0/tree/main/examples), which contains
+* The [examples
+folder](https://github.com/risc0/risc0/tree/main/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
@@ -26,7 +26,7 @@ channel](https://www.youtube.com/@risczero) has many more videos as well.
   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 website](https://www.risczero.com/)!
+* And more on [the RISC Zero developer website](https://dev.risczero.com/)!
 
 # Crate Feature Flags