docs(website): Add dev-mode instructions (risc0#1033)

Closes risc0#434

---------

Co-authored-by: Erik Kaneda <[email protected]>

bonsai/ethereum/contracts/BonsaiTest.sol

@@ -61,7 +61,7 @@ abstract contract BonsaiTest is Test, BonsaiCheats {
         _;
     }
 
-    /// @notice Returns whether we are using the prover and verifier in dev mode, or fully verifying.
+    /// @notice Returns whether we are using the prover and verifier in dev-mode, or fully verifying.
     function devMode() internal returns (bool) {
         return vm.envOr("RISC0_DEV_MODE", true);
     }

examples/waldo/README.md

@@ -49,7 +49,7 @@ cargo run --release --bin verify -- -i waldo.webp -r receipt.bin
 Running the verifier proves that the contents of the [journal] were indeed constructed by the binary file associated with the expected [ImageID].
 
 [install Rust]: https://doc.rust-lang.org/cargo/getting-started/installation.html
-[journal]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/struct.Receipt.html#structfield.journal
+[journal]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/struct.Receipt.html#structfield.journal
 [ImageID]: https://dev.risczero.com/terminology#image-id
 
 ## Approach

risc0/zkvm/src/host/receipt.rs

@@ -186,6 +186,15 @@ pub enum InnerReceipt {
     Succinct(SuccinctReceipt),
 
     /// A fake receipt for testing and development.
+    ///
+    /// This receipt is not valid and will fail verification unless the
+    /// environment variable `RISC0_DEV_MODE` is set to `true`, in which case a
+    /// pass-through 'verification' will be performed, but it *does not*
+    /// represent any meaningful attestation of receipt's integrity.
+    ///
+    /// This type solely exists to improve development experience, for further
+    /// information about development-only mode see our [dev-mode
+    /// documentation](https://dev.risczero.com/zkvm/dev-mode).
     Fake,
 }
 

website/docs/reference-docs/about-finite-fields.md

@@ -55,4 +55,4 @@ More generally, multiplying by a 4th root of unity is a rotation of order 4.`
 - [A. Sutherland's notes on finite fields and integer arithmetic](https://math.mit.edu/classes/18.783/2017/LectureNotes3.pdf)
 - [Splitting $x^{n}-1$ over a finite field](https://math.stackexchange.com/questions/2511486/)
 
-[receipt]: https://docs.rs/risc0-zkvm/0.18/risc0_zkvm/struct.Receipt.html
+[receipt]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/struct.Receipt.html

website/docs/terminology.md

@@ -130,7 +130,7 @@ Generate a [receipt] that serves as [proof] of correct execution of a [guest pro
 
 [proven]: #prover
 [prover]: #prover
-[Prover documentation]: https://docs.rs/risc0-zkvm/0.18/risc0_zkvm/trait.Prover.html
+[Prover documentation]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/trait.Prover.html
 
 The portion of the [zkVM] that [executes] and [proves] a [guest program], thereby constructing a [receipt]. <br/>
 See also: [Prover documentation], [Executor]

website/docs/zkvm/dev-mode.md

@@ -0,0 +1,25 @@
+---
+slug: ./
+---
+
+# What is dev-mode, and how can you use it safely?
+
+We support a development-only mode for standalone risc0 projects in which code is executed but not proven. This adds efficiency to the development cycle during development stages where proving correct execution is not yet critical.
+
+A risc0 project, when run in dev-mode by setting the `RISC0_DEV_MODE` environment variable, supports ([fake](https://docs.rs/risc0-zkvm/0.19.0/risc0_zkvm/enum.InnerReceipt.html#variant.Fake)) receipt creation and pass-through (fake) 'verification' function, so that dev-mode may be switched on and off at runtime without impacting project workflows.
+In particular, receipts generated in dev-mode still include public outputs written to the [journal](https://dev.risczero.com/terminology#journal).
+
+However, because the proving process is bypassed, receipts generated when dev-mode is enabled will fail a standard receipt verification check. Only when the verifier is also run with dev-mode enabled will it perform pass-through 'verification' of the fake receipt.
+
+**To keep this mode out of production environments, we recommend building production-ready projects with the "disable-dev-mode" [feature flag](https://github.com/risc0/risc0/#feature-flags); it is absent by default.**
+
+Only projects built without this flag may run dev-mode. Enabling dev-mode requires also that the environment variable `RISC0_DEV_MODE` be set.
+
+As additional protection, if the dev-mode [environment variable](https://docs.rs/risc0-zkvm/*/risc0_zkvm/fn.is_dev_mode.html) is present alongside a project built with the "disable-dev-mode" feature flag, the project will panic.
+
+For further reference, take a look at the table below. To learn more about usage, see the [risc0 project README](https://github.com/risc0/risc0/#readme). For a closer look at implementation, take a look at the [dev-mode source](https://github.com/risc0/risc0/blob/v0.19.0-rc.1/risc0/zkvm/src/host/server/prove/dev_mode.rs).
+
+|                               | `disable-dev-mode` off   | `disable-dev-mode` on    |
+| ----------------------------- | ------------------------ | ------------------------ |
+| RISC0_DEV_MODE=true           | dev-mode activated       | Prover panic             |
+| RISCO_DEV_MODE={false, unset} | Default project behavior | Default project behavior |

website/docs/zkvm/developer-guide/guest-code-101.md

@@ -24,23 +24,23 @@ To support various use cases, there are a number of functions that can be called
 - **Reading inputs** <br/>
   [`env::read`], [`env::read_slice`], and [`env::stdin`]
 
-[`env::read`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.read.html
-[`env::read_slice`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.read_slice.html
-[`env::stdin`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.stdin.html
+[`env::read`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.read.html
+[`env::read_slice`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.read_slice.html
+[`env::stdin`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.stdin.html
 
 - **Writing private outputs to [host]**<br/>
   [`env::write`], [`env::write_slice`], [`env::stdout`], [`env::stderr`]
 
-[`env::write`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.write.html
-[`env::write_slice`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.write_slice.html
-[`env::stdout`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.stdout.html
-[`env::stderr`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.stderr.html
+[`env::write`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.write.html
+[`env::write_slice`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.write_slice.html
+[`env::stdout`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.stdout.html
+[`env::stderr`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.stderr.html
 
 - **Committing private outputs [journal]**<br/>
   `env::commit`, `env::commit_slice`
 
-[`env::commit`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.commit.html
-[`env::commit_slice`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.commit_slice.html
+[`env::commit`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.commit.html
+[`env::commit_slice`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.commit_slice.html
 
 ## Tools for Debugging & Optimization
 
@@ -52,8 +52,8 @@ There are also a number of functions available to support with debugging and per
 - **Print a debug message**<br/>
   [`env::log`]
 
-[`env::get_cycle_count`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.get_cycle_count.html
-[`env::log`]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/env/fn.log.html
+[`env::get_cycle_count`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.get_cycle_count.html
+[`env::log`]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/env/fn.log.html
 
 For more information on optimization & performance, see our pages on [Cryptography Acceleration](acceleration.md) and [Benchmarking](../benchmarks.md).
 
@@ -88,7 +88,7 @@ You can file an issue on [these docs] or the [examples], and we're happy to answ
 [zkVM Overview]: ../zkvm_overview.md
 [Hello World demo]: https://github.com/risc0/risc0/tree/main/examples/hello-world
 [risc0/examples]: https://github.com/risc0/risc0/tree/v0.18.0/examples
-[guest environment commands]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/guest/index.html
+[guest environment commands]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/guest/index.html
 [zkVM Application]: ../zkvm_overview.md
 [zkVM]: ../zkvm_overview.md
 [Bonsai]: ../../bonsai/bonsai-overview.md

website/docs/zkvm/developer-guide/host-code-101.md

@@ -90,7 +90,7 @@ You can file an issue on [these docs] or the [examples], and we're happy to answ
 [`risc0-zkvm` Rust crate]: https://docs.rs/risc0-zkvm
 [these docs]: https://github.com/risc0/website
 [verifies]: ../../terminology.md#verify
-[verifying receipts]: https://docs.rs/risc0-zkvm/0.18.0/risc0_zkvm/struct.Receipt.html#method.verify
+[verifying receipts]: https://docs.rs/risc0-zkvm/*/risc0_zkvm/struct.Receipt.html#method.verify
 [zkVM Quick Start]: ../quickstart.md
 [zkVM Overview]: ../zkvm_overview.md
 [zkVM Application]: ../zkvm_overview.md

website/docs/zkvm/quickstart.md

@@ -40,18 +40,39 @@ In the codebase for your new project, you'll find a handful of places marked `TO
 
 Don't worry -- each `TODO` comes with instructions for what you need to do, and the [Hello World tutorial] contains step-by-step instructions.
 
-## 4. Run your project, locally or remotely
+## 4. Quick Development: Leveraging Dev Mode
 
-The readme for your project includes instructions for how to run it, both locally or remotely.
-You can build your example and run the prover locally with:
+During the development of your project, you might find that running your code can take a long time due to the proof generation process. To address this issue and allow for faster iterations of your code, we suggest utilizing [dev-mode]. This mode bypasses the time-consuming proof generation process. To activate dev-mode, simply set the environment variable `RISC0_DEV_MODE=true` when executing your project (other acceptable values include `1` and `yes`).
+
+Example:
+
+```bash
+RISC0_DEV_MODE=true cargo run --release
+```
+
+For a deeper understanding of dev-mode and its safe usage, please refer to our page explaining [what is dev-mode]. Please note that dev-mode is only meant to be used during development and testing. It should **never** be used in production.
+
+## 5. Real Proof Generation
+
+Once you've reached a point where you're ready to generate real proofs, you can do so by unseting the `RISC0_DEV_MODE` environment variable (or setting it to `RISC0_DEV_MODE=false`). We recommend that you additionally specify the feature flag `disable-dev-mode`, which will ensure that dev-mode is not accidentally enabled. Please consult more information about `disable-dev-mode` in the [feature flags] table, and the [dev-mode] page for more information.
+
+Proceeding with the example above, generating proofs locally would be achieved by running:
 
 ```bash
-cargo run --release
+RISC0_DEV_MODE=false cargo run --release --features disable-dev-mode
 ```
 
-> **Congratulations!** <br/>_That's all it takes to build and run a minimal RISC Zero application._
+Note that `RISC0_DEV_MODE=false` is the default behavior, so you can also simply run:
+
+```bash
+cargo run --release --features disable-dev-mode
+```
 
-## Local & Remote Proving
+We would always recommend using `disable-dev-mode` in production, as it ensures that dev-mode is not accidentally enabled.
+
+Also, note that since now proofs are being generated, the execution time of your project will be significantly longer than when running in dev-mode. You might want to consider using [Bonsai] to generate proofs remotely, as it will likely be faster than running proofs locally.
+
+## 6. Local & Remote Proving
 
 You can build and run your zkVM applications using your own hardware, or you can upload your [guest program] to [Bonsai] and make requests for proof generation as needed.
 
@@ -69,6 +90,10 @@ Additional information is available in the [starter template](https://github.com
 
 Options such as GPU acceleration and skipping the proof generation are documented in the [feature flags].
 
+> **Congratulations!**
+>
+> _That's all it takes to build and run a minimal RISC Zero application._
+
 [zkVM]: ../zkvm/zkvm_overview.md
 [guest program]: ../terminology.md#guest-program
 [Bonsai]: ../bonsai/bonsai-overview.md
@@ -80,3 +105,5 @@ Options such as GPU acceleration and skipping the proof generation are documente
 [demo applications]: https://github.com/risc0/risc0/tree/v0.18.0/examples
 [Bonsai Quick Start]: ../bonsai/quickstart.md
 [request access]: https://bonsai.xyz/apply
+[dev-mode]: ./dev-mode.md
+[what is dev-mode]: ./dev-mode.md

website/sidebars.js

@@ -44,6 +44,11 @@ const sidebars = {
           label: "Quick Start",
           id: "zkvm/quickstart",
         },
+        {
+          type: "doc",
+          label: "Dev Mode",
+          id: "zkvm/dev-mode",
+        },
         {
           type: "link",
           label: "API Reference Docs",
@@ -123,7 +128,7 @@ const sidebars = {
         {
           type: "link",
           label: "Proof System Rust Crate",
-          href: "https://docs.rs/risc0-zkp/0.18/risc0_zkp/",
+          href: "https://docs.rs/risc0-zkp/*/risc0_zkp/",
         },
         {
           type: "link",