feat: update docs for SDK updates (#1990)

Closes INT-4553, INT-4750

---------

Co-authored-by: Jonathan Wang <[email protected]>

Author: yi-sun

docs/vocs/docs/pages/book/acceleration-using-extensions/overview.mdx

@@ -24,7 +24,7 @@ Our design for the configuration procedure above was inspired by the [EVMMAX pro
 
 The `openvm` crate provides an `init!` macro to automate the **init** step:
 1. Call `openvm::init!()` exactly once in the code of the final program binary.
-2. When [compiling the program](/book/writing-apps/compiling), `cargo openvm build` will read the [configuration file](#configuration) to automatically generate the correct init code and write it to `<INIT_FILE_NAME>`, which defaults to `openvm_init.rs` in the manifest directory.
+2. When [compiling the program](/book/writing-apps/compiling-a-program), `cargo openvm build` will read the [configuration file](#configuration) to automatically generate the correct init code and write it to `<INIT_FILE_NAME>`, which defaults to `openvm_init.rs` in the manifest directory.
 3. The `openvm::init!()` macro will include the `openvm_init.rs` file into the final binary to complete the init process. You can call `openvm::init!(INIT_FILE_NAME)` to include init code from a different file if needed.
 
 ## Configuration

docs/vocs/docs/pages/book/advanced-usage/sdk.mdx

@@ -23,9 +23,11 @@ The SDK provides lower-level control over the building and transpiling process.
 // [!include ~/snippets/examples_sdk/sdk_stark.rs:transpilation]
 ```
 
-### Using `SdkVmConfig`
+### Customizing the VM Configuration
 
-The `SdkVmConfig` struct allows you to specify the extensions and system configuration your VM will use. To customize your own configuration, you can use the `SdkVmConfig::builder()` method and set the extensions and system configuration you want.
+To use a custom VM configuration, you can construct your own `GenericSdk` object which includes the
+extensions and system configuration your VM will use. To do this, you can use the `SdkVmConfig::builder()`
+ method and set the desired extensions and system configuration as in the example below.
 
 ```rust
     let vm_config = SdkVmConfig::builder()
@@ -35,10 +37,20 @@ The `SdkVmConfig` struct allows you to specify the extensions and system configu
         .io(Default::default())
         .build()
         .optimize();
+    let sdk = Sdk::new(
+        AppConfig::new(FriParameters::standard_fast(), vm_config)
+    )?;
 ```
 
-> ℹ️
-> When using Rust to write the guest program, the VM system configuration should keep the default value `pointer_max_bits = 29` to match the hardcoded memory limit of the memory allocator. Otherwise, the guest program may fail due to out of bounds memory access in the VM.
+The following convenience methods are also available to construct a `GenericSdk` object:
+
+- `Sdk::riscv32()` returns a `GenericSdk` supporting the RV32IM extension.
+- `Sdk::standard()` returns a `GenericSdk` supporting all default OpenVM extensions, including RV32IM.
+- `Sdk::new(Sdk::from_toml(openvm.toml))` returns a `GenericSdk` from a custom OpenVM configuration specified in an `openvm.toml` file.
+
+:::info
+When using Rust to write the guest program, the VM system configuration should keep the default value `pointer_max_bits = 29` to match the hardcoded memory limit of the memory allocator. Otherwise, the guest program may fail due to out of bounds memory access in the VM.
+:::
 
 ## Running a Program
 
@@ -52,14 +64,17 @@ To run your program and see the public value output, you can do the following:
 
 The `StdIn` struct allows you to format any serializable type into a VM-readable format by passing in a reference to your struct into `StdIn::write` as above. You also have the option to pass in a `&[u8]` into `StdIn::write_bytes`, or a `&[F]` into `StdIn::write_field` where `F` is the `openvm_stark_sdk::p3_baby_bear::BabyBear` field type.
 
-> **Generating CLI Bytes**
-> To get the VM byte representation of a serializable struct `data` (i.e. for use in the CLI), you can print out the result of `openvm::serde::to_vec(data).unwrap()` in a Rust host program.
+:::info
+**Generating CLI Bytes**
+To get the VM byte representation of a serializable struct `data` (i.e. for use in the CLI), you can print out the result of `openvm::serde::to_vec(data).unwrap()` in a Rust host program.
+:::
 
 ## Generating and Verifying Proofs
 
-There are two types of proofs that you can generate, with the sections below continuing from this point.
+OpenVM supports generating three types of proofs. The sections below describe how to generate and verify each type of proof.
 
 - [App Proof](#app-proof): Generates STARK proof(s) of the guest program
+- [STARK Proof](#stark-proof): Generates a STARK proof that can be posted on-chain
 - [EVM Proof](#evm-proof): Generates a halo2 proof that can be posted on-chain
 
 ## App Proof
@@ -82,19 +97,44 @@ After generating a proof, you can verify it. To do so, you need your verifying k
 // [!include ~/snippets/examples_sdk/sdk_stark.rs:verification]
 ```
 
+## STARK Proof
+
+### Setup
+
+To generate a STARK proof, you first need to generate proving and verification keys for STARK aggregation using the following command:
+
+```bash
+cargo openvm setup
+```
+
+### STARK Proof Generation and Verification
+
+You can now run the aggregation keygen, proof, and verification functions for the STARK proof.
+
+```rust 
+// [!include ~/snippets/examples_sdk/sdk_stark.rs:proof_generation]
+```
+
+Once the proof is generated, you can verify it using the SDK as follows:
+
+```rust
+// [!include ~/snippets/examples_sdk/sdk_stark.rs:verification]
+```
+
 ## EVM Proof
 
 ### Setup
 
-To generate an EVM proof, you'll first need to ensure that you have followed the [CLI installation steps](/book/getting-started/install). get the appropriate KZG params by running the following command.
+To generate an EVM proof, you'll first need to ensure that you have followed the [CLI installation steps](/book/getting-started/install)
+to generate proving and verification keys for EVM proving.
 
 ```bash
 cargo openvm setup --evm
 ```
 
-> ⚠️ **WARNING**
->
-> `cargo openvm setup --evm` requires very large amounts of computation and memory (~200 GB).
+:::warning
+`cargo openvm setup --evm` requires a large amount of computation and memory (~70 GB).
+:::
 
 <details>
 <summary>Also note that there are additional dependencies for the EVM Proof flow. Click here to view.</summary>
@@ -115,7 +155,8 @@ You can now run the aggregation keygen, proof, and verification functions for th
 // [!include ~/snippets/examples_sdk/sdk_evm.rs:evm_verification]
 ```
 
-> ⚠️ **WARNING**
-> The aggregation proving key `agg_pk` above is large. Avoid cloning it if possible.
+:::warning
+The halo2 aggregation proving key `agg_halo2.pk` used in the above example is large. Avoid cloning it if possible.
+:::
 
 Note that `DEFAULT_PARAMS_DIR` is the directory where Halo2 parameters are stored by the `cargo openvm setup --evm` CLI command. For more information on the setup process, see the `EVM Level` section of the [verify](/book/writing-apps/verifying-proofs) doc.

docs/vocs/docs/pages/book/getting-started/install.mdx

@@ -52,6 +52,15 @@ rustup component add rust-src --toolchain nightly-2025-02-14
 # install build tools for Ubuntu
 sudo apt update
 sudo apt install -y build-essential   # gcc, g++, make, libc headers
+
+# install Solidity compiler, only needed for EVM proofs
+cargo install --version 0.5.7 svm-rs
+# Add the binary to your path
+export PATH="$HOME/.cargo/bin:$PATH"
+ 
+# Install solc 0.8.19
+svm install 0.8.19
+svm use 0.8.19
 ```
 
 ```bash [macOS]
@@ -66,4 +75,13 @@ rustup component add rust-src --toolchain nightly-2025-02-14
 # install build tools for macOS
 xcode-select --install
 brew install cmake git curl
+
+# install Solidity compiler, only needed for EVM proofs
+cargo install --version 0.5.7 svm-rs
+# Add the binary to your path
+export PATH="$HOME/.cargo/bin:$PATH"
+ 
+# Install solc 0.8.19
+svm install 0.8.19
+svm use 0.8.19
 ```

docs/vocs/docs/pages/book/getting-started/quickstart.mdx

@@ -49,11 +49,14 @@ To build the program, run:
 cargo openvm build
 ```
 
-This will output an OpenVM executable file to `./target/openvm/release/fibonacci.vmexe`.
+This will output:
+
+- an RV32IM ELF containing [custom OpenVM instructions](/specs/reference/riscv-custom-code) at `./target/riscv32im-risc0-zkvm-elf/release/fibonacci`
+- an OpenVM executable binary at `./target/openvm/release/fibonacci.vmexe`
 
 ## Keygen
 
-Before generating any proofs, we will also need to generate the proving and verification keys.
+Before generating proofs, we will also need to generate the proving and verification keys using:
 
 ```bash
 cargo openvm keygen
@@ -86,7 +89,7 @@ The process should exit with no errors.
 
 ## Runtime Execution
 
-If necessary, the executable can also be run _without_ proof generation. This can be useful for testing purposes.
+The OpenVM binary can also be executed without generating a proof, which can be useful for testing purposes.
 
 ```bash
 cargo openvm run --input "0x010A00000000000000"

docs/vocs/docs/pages/book/guest-libraries/verify-stark.mdx

@@ -28,11 +28,13 @@ Proofs are expected to be passed via the [hintable key-value store](https://gith
 
 The function will panic on failure. Successful STARK verification implies that the app execution was successful and terminated with exit code 0.
 
-> ⚠️ For Advanced Users
->
-> Note that if your guest program directly writes data to the native address space (address space 4), the `verify_stark` function will likely overwrite it. Any data the guest placed in the native address space should be persisted (or treated as corrupt) before invocations to `verify_stark`.
-> 
-> This is not a concern if you are writing vanilla rust with the default RV32 I and M extensions.
+:::warning
+**For Advanced Users**
+
+Note that if your guest program directly writes data to the native address space (address space 4), the `verify_stark` function will likely overwrite it. Any data the guest placed in the native address space should be persisted (or treated as corrupt) before invocations to `verify_stark`.
+ 
+This is not a concern if you are writing vanilla rust with the default RV32 I and M extensions.
+:::
 
 ## Host
 

docs/vocs/docs/pages/book/writing-apps/compiling.mdx renamed to docs/vocs/docs/pages/book/writing-apps/compiling-a-program.mdx

@@ -1,13 +1,43 @@
 # Compiling a Program
 
-First let's define some key terms used in cross-compilation:
+Once you have written a program to be proven by OpenVM, you need to compile it in a way
+which is compatible with OpenVM.  This will involve **cross-compiling** the program by
+building it for a machine architecture which differs from the machine performing the build.
 
-- **host** - the machine you're compiling and/or proving on. Note that one can compile and prove on different machines, but they are both called _host_ as they are traditional machine architectures.
-- **guest** - the executable to be run in a different VM architecture (e.g. the OpenVM runtime, or Android app).
+To explain how this works for OpenVM, we will use the following key terms:
 
-The command `cargo openvm build` compiles the program on host to an executable for guest target.
-It first compiles the program normally on your _host_ platform with RISC-V and then transpiles it to a different target. See here for some explanation of [cross-compilation](https://rust-lang.github.io/rustup/cross-compilation.html).
-Right now we use `riscv32im-risc0-zkvm-elf` target which is available in the [Rust toolchain](https://doc.rust-lang.org/rustc/platform-support/riscv32im-risc0-zkvm-elf.html), but we will contribute an OpenVM target to Rust in the future.
+- **Host**: The machine architecture being used for building and proving. Though building and proving can be done on different machine architectures, they are both called **host** architectures since they are not the architecture used to specify the program.
+- **Guest**: The machine architecture being used to express the program to be proven, which is the OpenVM runtime in this case. We refer to programs written to be proven by OpenVM as **guest programs**.
+
+## Building Guest Programs for OpenVM
+
+To prove a guest program in OpenVM, we must build it for a RISC-V guest target and then transpile
+it to a format natively supported by OpenVM.  We provide the following CLI command to do this:
+
+```bash
+cargo openvm build
+```
+
+The presently supported guest target is `riscv32im-risc0-zkvm-elf` due to its official support by
+the [Rust toolchain](https://doc.rust-lang.org/rustc/platform-support/riscv32im-risc0-zkvm-elf.html).
+We anticipate upstreaming an OpenVM-specific target to Rust in the future. More details about
+how cross-compilation works in Rust can be found in the [Rust docs](https://rust-lang.github.io/rustup/cross-compilation.html). 
+
+## Generating Commitments for Guest Programs
+
+Once you have built the guest program, you can extract commitments to the program binary and
+the VM configuration using the following CLI command:
+
+```bash
+cargo openvm commit
+```
+
+This will generate a `*.commit.json` file in `${target_dir}/openvm/release/` containing:
+
+- `app_exe_commit`: A commitment to the OpenVM program binary.
+- `app_vm_commit`: A commitment to the OpenVM configuration used for the program binary.
+
+These values will be used later when verifying proofs generated by OpenVM for this program. 
 
 ## Build Flags
 

docs/vocs/docs/pages/book/writing-apps/generating-proofs.mdx

@@ -3,17 +3,22 @@
 Generating a proof using the CLI is simple - first generate a key, then generate your proof. Using command defaults, this looks like:
 
 ```bash
-cargo openvm keygen
-cargo openvm prove [app | stark | evm]
+cargo openvm keygen         # generate proving and verification keys for app proofs
+cargo openvm prove app      # generate the app proof
+
+cargo openvm setup          # generate proving and verification keys for STARK aggregation
+cargo openvm prove stark    # generate the STARK proof
+
+cargo openvm setup --evm    # generate proving and verification keys for EVM proofs
+cargo openvm prove evm      # generate the EVM proof
 ```
 
-## Key Generation
+## Application Key Generation
 
 The `keygen` command generates both an application proving and verification key.
 
 ```bash
-cargo openvm keygen
-    --config <path_to_app_config>
+cargo openvm keygen --config <path_to_app_config>
 ```
 
 Similarly to `build`, `run`, and `prove`, options `--manifest-path`, `--target-dir`, and `--output-dir` are provided.
@@ -22,6 +27,70 @@ If `--config` is not specified, the command will search for `openvm.toml` in the
 
 The proving and verification key will be written to `${target_dir}/openvm/` (and `--output-dir` if specified).
 
+## STARK and EVM Key Generation
+
+The `setup` command generates proving and verification keys for STARK aggregation and EVM proofs.
+
+```bash
+cargo openvm setup [--evm]
+```
+
+If called without the `--evm` flag, it will generate keys for the leaf, internal, and root STARK
+verifiers as detailed in the [specs](/specs/architecture/continuations). If called with the `--evm`
+flag, it will also generate keys for the [static verifier wrapper](/specs/architecture/continuations#static-verifier-wrapper).
+
+### Details on EVM Verification
+
+In addition to generating EVM proving and verification keys, `cargo openvm setup --evm` also
+generates a smart contract verifier for EVM chains. Upon a successful run, the command will write the files
+
+- `agg_stark.pk`
+- `agg_stark.vk`
+- `agg_halo2.pk`
+- `halo2/src/[OPENVM_VERSION]/Halo2Verifier.sol`
+- `halo2/src/[OPENVM_VERSION]/OpenVmHalo2Verifier.sol`
+- `halo2/src/[OPENVM_VERSION]/interfaces/IOpenVmHalo2Verifier.sol`
+- `halo2/src/[OPENVM_VERSION]/verifier.bytecode.json`
+
+to `~/.openvm/`, where `~` is the directory specified by environment variable `$HOME` and 
+`OPENVM_VERSION` is the version of OpenVM. Every command that requires these files will 
+look for them in this directory. The smart contract verifier is also available via the
+[OpenVM Solidity SDK](/book/writing-apps/solidity-sdk) for released versions of OpenVM.
+
+The files `agg_stark.pk` and `agg_halo2.pk` are the STARK and Halo2 aggregation proving keys necessary to aggregate to a final EVM proof.
+The file `agg_stark.vk` is the STARK aggregation verification key.
+The `OpenVmHalo2Verifier.sol` file contains a Solidity contract to verify the final EVM proof. The contract is named `OpenVmHalo2Verifier` and it implements the `IOpenVmHalo2Verifier` interface.
+
+```solidity [IOpenVmHalo2Verifier.sol]
+interface IOpenVmHalo2Verifier {
+    function verify(bytes calldata publicValues, bytes calldata proofData, bytes32 appExeCommit, bytes32 appVmCommit)
+        external
+        view;
+}
+```
+
+In addition, the command outputs a JSON file `verifier.bytecode.json` of the form
+
+```json [verifier.bytecode.json]
+{
+    "sol_compiler_version": "0.8.19",
+    "sol_compiler_options": "",
+    "bytecode": "0x..."
+}
+```
+
+where `sol_compiler_version` is the Solidity compiler version used to compile the contract (currently `0.8.19`),
+`sol_compiler_options` are additional compiler options used, and
+`bytecode` is the compiled EVM bytecode as a hex string.
+
+:::note
+Note that `cargo openvm setup --evm` downloads auxiliary files for halo2 KZG parameters from an AWS S3 bucket into `~/.openvm/`.
+:::
+
+:::warning
+If the `$HOME` environment variable is not set, this command may fail. This command requires a large amount of compute and memory (~70 GB) and can take ~7mins on a `m6a.16xlarge` instance.
+:::
+
 ## Proof Generation
 
 The `prove` CLI command, at its core, uses the options below. `prove` gets access to all of the options that `run` has (see [Running a Program](/book/writing-apps/running-a-program) for more information).
@@ -42,21 +111,10 @@ If your program doesn't require inputs, you can (and should) omit the `--input`
 
 If `--proof` is not provided then the command will write the proof to `./${bin_name}.[app | stark | evm].proof` by default, where `bin_name` is the file stem of the executable run.
 
-The `app` subcommand generates an application-level proof, the `stark` command generates an aggregated root-level proof, while the `evm` command generates an end-to-end EVM proof. For more information on aggregation, see [this specification](https://github.com/openvm-org/openvm/blob/bf8df90b13f4e80bb76dbb71f255a12154c84838/docs/specs/continuations.md).
-
-> ⚠️ **WARNING**
-> In order to run the `evm` subcommand, you must have previously called the costly `cargo openvm setup --evm`, which requires very large amounts of computation and memory (~200 GB).
-
-See [EVM Proof Format](./verifying-proofs#evm-proof-json-format) for details on the output format for `cargo openvm prove evm`.
-
-## Commit Hashes
-
-To see the commit hash for an executable, you may run:
-
-```bash
-cargo openvm commit
-    --app-pk <path_to_app_pk>
-    --exe <path_to_transpiled_program>
-```
+The `app` subcommand generates an application-level proof, the `stark` command generates an aggregated root-level proof, while the `evm` command generates an end-to-end EVM proof. For more information on aggregation, see [this specification](https://github.com/openvm-org/openvm/blob/bf8df90b13f4e80bb76dbb71f255a12154c84838/docs/specs/continuations.md). See [EVM Proof Format](./verifying-proofs#evm-proof-json-format) for details on the output format for `cargo openvm prove evm`.
 
-The `commit` command has all the auxiliary options that `prove` does, and outputs Bn254 commits for both your executable and VM. Commits are written to `${target_dir}/openvm/` (and `--output-dir` if specified).
+:::warning
+The `stark` subcommand requires STARK aggregation key generation to have been run via
+`cargo openvm setup`, and the `evm` subcommand requires EVM key generation to have been run via
+`cargo openvm setup --evm`, which has a large compute and memory requirement (~70 GB).
+:::