feat: mdbook docs (#191)

Co-authored-by: John Guibas <[email protected]>

.github/workflows/book.yml

@@ -0,0 +1,143 @@
+# Documentation and mdbook related jobs.
+# Reference: https://github.com/paradigmxyz/reth/blob/main/.github/workflows/book.yml
+
+name: book
+
+# on:
+#   push:
+#     branches: [main]
+#   pull_request:
+#     branches: [main]
+#   merge_group:
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  # test:
+  #   runs-on: ubuntu-latest
+  #   name: test
+  #   timeout-minutes: 60
+
+  #   steps:
+  #     - uses: actions/checkout@v4
+
+  #     - name: Install mdbook
+  #       run: |
+  #         mkdir mdbook
+  #         curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+  #         echo $(pwd)/mdbook >> $GITHUB_PATH
+
+  #     - name: Install mdbook-template
+  #       run: |
+  #         mkdir mdbook-template
+  #         curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+  #         echo $(pwd)/mdbook-template >> $GITHUB_PATH
+
+  #     - name: Run tests
+  #       run: mdbook test
+
+  lint:
+    runs-on: ubuntu-latest
+    name: lint
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdbook-linkcheck
+        run: |
+          mkdir mdbook-linkcheck
+          curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
+          unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
+          chmod +x $(pwd)/mdbook-linkcheck/mdbook-linkcheck
+          echo $(pwd)/mdbook-linkcheck >> $GITHUB_PATH
+
+      - name: Run linkcheck
+        run: mdbook-linkcheck --standalone
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - name: Install mdbook
+        run: |
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo $(pwd)/mdbook >> $GITHUB_PATH
+
+      - name: Install mdbook-template
+        run: |
+          mkdir mdbook-template
+          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+          echo $(pwd)/mdbook-template >> $GITHUB_PATH
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Build book
+        run: mdbook build
+
+      # - name: Build docs
+      #   run: cargo docs
+      #   env:
+      #     # Keep in sync with ./ci.yml:jobs.docs
+      #     RUSTDOCFLAGS:
+      #       --cfg docsrs --show-type-layout --generate-link-to-definition --enable-index-page
+      #       -Zunstable-options
+
+      # - name: Move docs to book folder
+      #   run: |
+      #     mv target/doc target/book/docs
+
+      - name: Archive artifact
+        shell: sh
+        run: |
+          chmod -c -R +rX "target/book" |
+          while read line; do
+             echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+          tar \
+            --dereference --hard-dereference \
+            --directory "target/book" \
+            -cvf "$RUNNER_TEMP/artifact.tar" \
+            --exclude=.git \
+            --exclude=.github \
+            .
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+
+  # deploy:
+  #   # Only deploy if a push to main
+  #   if: github.ref_name == 'main' && github.event_name == 'push'
+  #   runs-on: ubuntu-latest
+  #   needs: [lint, build]
+
+  #   # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+  #   permissions:
+  #     pages: write
+  #     id-token: write
+
+  #   environment:
+  #     name: github-pages
+  #     url: ${{ steps.deployment.outputs.page_url }}
+
+  #   timeout-minutes: 60
+
+  #   steps:
+  #     - name: Deploy to GitHub Pages
+  #       id: deployment
+  #       uses: actions/deploy-pages@v2

book.toml

@@ -0,0 +1,30 @@
+[book]
+authors = ["Curta Contributors"]
+language = "en"
+multilingual = false
+src = "book"
+title = "Curta Book"
+description = "A book on all things Reth"
+
+[output.html]
+theme = "book/theme"
+git-repository-url = "https://github.com/succinctlabs/vm"
+default-theme = "ayu"
+no-section-label = true
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+[build]
+build-dir = "target/book"
+
+[preprocessor.template]
+before = ["links"]
+
+[preprocessor.index]
+
+[preprocessor.links]

book/SUMMARY.md

@@ -0,0 +1,30 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+# Getting Started
+
+- [Install](./getting-started/install.md)
+
+- [Quickstart](./getting-started/quickstart.md)
+
+# Writing Programs
+
+- [Setup](./writing-programs/setup.md)
+
+- [Basics](./writing-programs/basics.md)
+
+- [Inputs & Outputs](./writing-programs/inputs-and-outputs.md)
+
+- [Precompiles](./writing-programs/precompiles.md)
+
+- [Patched Crates](./writing-programs/patched-crates.md)
+
+# Generating Proofs
+
+- [Setup](./generating-proofs/setup.md)
+
+- [Basics](./generating-proofs/basics.md)
+
+- [Advanced](./generating-proofs/advanced.md)
+

book/generating-proofs/advanced.md

@@ -0,0 +1,86 @@
+# Advanced Usage
+
+## Execution Only
+
+We recommend that during development of large programs (> 1 million cycles) that you do not generate proofs each time.
+Instead, you should have your script only execute the program with the RISC-V runtime and read `stdout`. Here is an example:
+
+```rust,noplayground
+use succinct_core::{SuccinctProver, SuccinctStdin, SuccinctVerifier};
+
+// The ELF file with the RISC-V bytecode of the program from above.
+const ELF: &[u8] = include_bytes!("../../program/elf/riscv32im-succinct-zkvm-elf");
+
+fn main() {
+    let mut stdin = SuccinctStdin::new(); 
+    let n = 5000u32;
+    stdin.write(&n); 
+    let mut stdout = SuccinctProver::execute(ELF, stdin).expect("execution failed");
+    let a = stdout.read::<u32>(); 
+    let b = stdout.read::<u32>();
+
+    // Print the program's outputs in our script.
+    println!("a: {}", a);
+    println!("b: {}", b);
+    println!("succesfully executed the program!")
+}
+```
+
+If execution of your program succeeds, then proof generation should succeed as well! (Unless there is a bug in our zkVM implementation.)
+
+
+## Performance
+
+For maximal performance, you should run proof generation with the following command and vary your `shard_size` depending on your program's number of cycles.
+
+```rust,noplayground
+SHARD_SIZE=4194304 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release
+```
+
+You can also use the `SAVE_DISK_THRESHOLD` env variable to control whether shards are saved to disk or not.
+This is useful for controlling memory usage.
+
+```rust,noplayground
+SAVE_DISK_THRESHOLD=64 SHARD_SIZE=2097152 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release
+```
+
+#### Blake3 on ARM machines
+
+Blake3 on ARM machines requires using the `neon` feature of `succinct-core`. For examples in the the succinct-core repo, you can use:
+
+```rust,noplayground
+SHARD_SIZE=2097152 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release --features neon
+```
+
+Otherwise, make sure to include the "neon" feature when importing `succinct-zkvm` in your `Cargo.toml`:
+
+```toml,noplayground
+succinct-core = { git = "ssh://[email protected]/succinctlabs/vm.git", features = [ "neon" ] }
+```
+
+## Logging and Tracing Information
+
+You can either use `utils::setup_logger()` or `utils::setup_tracer()` to enable logging and tracing information respectively. You should only use one or the other of these functions.
+
+**Tracing:**
+
+Tracing will show more detailed timing information. 
+
+```rust,noplayground
+utils::setup_tracer();
+```
+
+You must run your command with:
+```bash
+RUST_TRACER=info cargo run --release
+```
+
+**Logging:**
+```rust,noplayground
+utils::setup_logger();
+```
+
+You must run your command with:
+```bash
+RUST_LOG=info cargo run --release
+```

book/generating-proofs/basics.md

@@ -0,0 +1,15 @@
+# Generating Proofs: Basics
+
+An end-to-end flow of proving `f(x) = y` with the Curta zkVM looks like as follows:
+
+- Define `f` using normal rust code and compile it to a proving key `pk` and a verifying key `vk`.
+- Generate a proof `π` using the Curta zkVM that `f(x) = y` with `prove(pk, x)`.
+- Verify the proof `π` using `verify(vk, x, y, π)`.
+
+To make this more concrete, let's walk through a simple example of generate a proof for a Fiboancci program inside the zkVM.
+
+## Fibonacci
+
+```rust,noplayground
+{{#include ../../examples/fibonacci-io/src/main.rs}}
+```

book/generating-proofs/setup.md

@@ -0,0 +1,39 @@
+# Generating Proofs: Setup
+
+In this section, we will teach you how to setup a self-contained crate which can run ELFs that have been compiled with the curta toolchain inside the Curta zkVM.
+
+## CLI (Recommended)
+
+The recommended way to setup your first program to prove inside the zkVM is using the method described in [Quickstart](../getting-started/quickstart.md) which will create a script folder.
+
+```bash
+cargo prove new <name>
+cd script
+```
+
+
+## Manual
+
+You can also manually setup a project. First create a new cargo project:
+
+```bash
+cargo new script
+cd script
+```
+
+#### Cargo Manifest
+
+Inside this crate, add the `succinct-core` crate as a dependency. Your `Cargo.toml` should look like as follows:
+
+```rust,noplayground
+[workspace]
+[package]
+version = "0.1.0"
+name = "script"
+edition = "2021"
+
+[dependencies]
+succinct-core = { git = "https://github.com/succinctlabs/vm.git" }
+```
+
+The `succinct-core` crate includes necessary utilities to generate, save, and verify proofs.