From a26c3ded06f2ea3f478538c8d88abcd588050613 Mon Sep 17 00:00:00 2001
From: Lun-Kai Hsu <kaikaikai1219@gmail.com>
Date: Sun, 15 Dec 2024 12:55:31 -0800
Subject: [PATCH] [docs] update to writing program (#1049)

* update to writing program

* address comments

* add compile

* address comments
---
 book/src/SUMMARY.md                    |  1 +
 book/src/getting-started/quickstart.md |  2 +-
 book/src/writing-apps/compile.md       |  8 +++++
 book/src/writing-apps/write-program.md | 44 +++++++++++++++++++++++---
 4 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index b40ab41b87..f250675b66 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -24,3 +24,4 @@
 # Advanced Usage
 
 - [Overview](./advanced-usage/overview.md)
+- [Testing the program](./advanced-usage/testing-program.md)
diff --git a/book/src/getting-started/quickstart.md b/book/src/getting-started/quickstart.md
index 03825f536f..c40f274cd1 100644
--- a/book/src/getting-started/quickstart.md
+++ b/book/src/getting-started/quickstart.md
@@ -10,7 +10,7 @@ First, create a new Rust project.
 cargo init fibonacci
 ```
 
-Since we are using some nightly features, we need to specify the Rust version. Create a `rust-toolchain.toml` file with the following content:
+Since we are using some nightly features, we need to specify the Rust version. Run `rustup component add rust-src --toolchain nightly-2024-10-30` and create a `rust-toolchain.toml` file with the following content:
 
 ```toml
 [toolchain]
diff --git a/book/src/writing-apps/compile.md b/book/src/writing-apps/compile.md
index 9067cfda0f..f3b18f2570 100644
--- a/book/src/writing-apps/compile.md
+++ b/book/src/writing-apps/compile.md
@@ -1 +1,9 @@
 # Cross-Compilation
+
+First let's define some key terms used in cross-compilation:
+- **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).
+
+There are multiple things happening in the `cargo openvm build` command as in the section [here](./write-program.md). In short, this command compiles 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.
diff --git a/book/src/writing-apps/write-program.md b/book/src/writing-apps/write-program.md
index 66836a4ade..dd151de2c8 100644
--- a/book/src/writing-apps/write-program.md
+++ b/book/src/writing-apps/write-program.md
@@ -31,15 +31,51 @@ std = ["openvm/std"]
 
 *TODO*: point to CLI installation instructions
 
+First we need to build the program targeting the OpenVM runtime, and that requires some configuration. Put the following in `openvm.toml`:
+```toml
+[app_fri_params]
+log_blowup = 2
+num_queries = 42
+proof_of_work_bits = 16
+
+[app_vm_config.io]
+[app_vm_config.rv32i]
+[app_vm_config.rv32m]
+range_tuple_checker_sizes = [256, 2048]
+```
+
+And run the following command to build the program:
+
+```bash
+cargo openvm build --transpile --transpiler-config openvm.toml --transpile-to outputs/fibonacci.vmexe
+```
+
+Next we can keygen the generate the proving and verifying keys:
+
+```bash
+cargo openvm keygen --config app_config.toml --output outputs/pk --vk-output outputs/vk
+```
+
+Now, to prove the program some input is needed. The input parameter is either a hex string or a file path. So for example if we want to compute the 10th fibonacci number, we can run:
+
+```bash
+cargo openvm prove app --app-pk outputs/pk --exe outputs/fibonacci.vmexe --input "0x000000000000000A" --output outputs/proof
+cargo openvm verify app --app-vk outputs/vk --proof outputs/proof
+```
+
+No errors should be returned, and the proof should be correctly verified.
+
 ## Handling I/O
 
-`openvm::io` provides a few functions to read and write data.
+The program can take input from stdin, with some functions provided by `openvm::io`.
 
-`read` takes from stdin the next vec and deserialize it into a generic type `T`, so one should specify the type when calling it:
+`openvm::io::read` takes from stdin and deserializes it into a generic type `T`, so one should specify the type when calling it:
 ```rust
 let n: u64 = read();
 ```
 
-`read_vec` will just read a vector and return `Vec<u8>`.
+`openvm::io::read_vec` will just read a vector and return `Vec<u8>`.
+
+`openvm::io::reveal` sends public values to the final proof (to be read by the smart contract).
 
-`reveal`
+For debugging purposes, `openvm::io::print` and `openvm::io::println` can be used normally, but `println!` will only work if `std` is enabled.