openvm-org · Golovanov399 · Dec 15, 2024 · Dec 15, 2024 · Dec 15, 2024 · Dec 15, 2024
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -1,3 +1,15 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Summary](#summary)
+- [Getting Started](#getting-started)
+- [Writing Apps](#writing-apps)
+- [Using Extensions](#using-extensions)
+- [Advanced Usage](#advanced-usage)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Summary
 
 [Introduction](./introduction.md)

diff --git a/book/src/advanced-usage/overview.md b/book/src/advanced-usage/overview.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Overview](#overview)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Overview
diff --git a/book/src/advanced-usage/testing-program.md b/book/src/advanced-usage/testing-program.md
@@ -1,3 +1,16 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Testing the program](#testing-the-program)
+  - [Running on the host machine](#running-on-the-host-machine)
+  - [Running with the OpenVM runtime](#running-with-the-openvm-runtime)
+  - [Generating to prove](#generating-to-prove)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 
 ## Testing the program
 

diff --git a/book/src/getting-started/install.md b/book/src/getting-started/install.md
@@ -1,3 +1,13 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Install](#install)
+  - [Build from source](#build-from-source)
+  - [Toolchain](#toolchain)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Install
 
 TODO: how to install `cargo-openvm`.

diff --git a/book/src/getting-started/quickstart.md b/book/src/getting-started/quickstart.md
@@ -1,3 +1,13 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Quickstart](#quickstart)
+  - [Setup](#setup)
+  - [The fibonacci program](#the-fibonacci-program)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Quickstart
 
 In this section we will build and run a fibonacci program.

diff --git a/book/src/introduction.md b/book/src/introduction.md
@@ -1,3 +1,12 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Introduction](#introduction)
+- [In particular, Chapter 2 is for this, Chapter 3 is for that, et cetera.](#in-particular-chapter-2-is-for-this-chapter-3-is-for-that-et-cetera)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Introduction
 
 OpenVM is ...

diff --git a/book/src/using-extensions/customizable-extensions.md b/book/src/using-extensions/customizable-extensions.md
@@ -1,3 +1,17 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Using already existing extensions](#using-already-existing-extensions)
+  - [`openvm-algebra`](#openvm-algebra)
+    - [Available traits and methods](#available-traits-and-methods)
+    - [Modular arithmetic](#modular-arithmetic)
+    - [Complex field extension](#complex-field-extension)
+    - [A toy example of a guest program using `openvm-algebra` extension](#a-toy-example-of-a-guest-program-using-openvm-algebra-extension)
+  - [`openvm-ecc`](#openvm-ecc)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Using already existing extensions
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
@@ -6,6 +20,18 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor i
 
 This crate allows one to create and use structs for convenient modular arithmetic operations, and also for their complex extensions (for example, if $p$ is a prime number, `openvm-algebra` provides methods for modular arithmetic in the field $\mathbb{F}_p[x]/(x^2 + 1)$).
 
+### Available traits and methods
+
+- `IntMod` trait: contains type `Repr`, constants `MODULUS`, `NUM_LIMBS`, `ZERO`, `ONE`, and basic methods for constructing an object and arithmetic operations. `Repr` is usually `[u8; NUM_LIMBS]` and indicates the underlying representation of the number. `MODULUS: Repr` is the modulus of the struct, `ZERO` and `ONE` are the additive and multiplicative identities (both are of type `Repr`). To construct a struct, methods `from_repr`, `from_le_bytes`, `from_be_bytes`, `from_u8`, `from_u32`, `from_u64` are available.
+
+- `Field` trait: contains constants `ZERO` and `ONE`, and methods for basic arithmetic operations.
+
+<!-- TODO: FieldExtension trait -->
+
+<!-- TODO: exp_bytes is only intended for host? -->
+
+### Modular arithmetic
+
 To declare a modular arithmetic struct, one needs to use the `moduli_declare!` macro. A usage example is given below:
 
 ```rust
@@ -39,6 +65,86 @@ To summarize:
 - `setup_<i>()` sends a setup instruction for the $i$-th struct. Here, **$i$-th struct is the one that corresponds to the $i$-th modulus in `moduli_init!`**. The order of `moduli_declare!` invocations or the arguments in them does not matter.
 - `setup_all_moduli()` sends setup instructions for all the structs.
 
+### Complex field extension
+
+To declare a complex field extension struct, one needs to use the `complex_declare!` macro. A usage example is given below:
+
+```rust
+complex_declare! {
+    Bn254_Fp2 { mod_type = Bn254_Fp }
+}
+```
+
+This creates a struct `Bn254_Fp2`, which represents the complex field extension class. The `mod_type` parameter must be a struct that implements the `IntMod` trait.
+
+The arithmetic operations for these classes, when compiling for the `zkvm` target, are converted into RISC-V asm instructions which are distinguished by the `funct7` field. The corresponding "distinguishers assignment" is happening when another macro is called:
+
+```rust
+complex_init! {
+    Bn254_Fp2 { mod_idx = 0 },
+}
+```
+
+This macro **must be called exactly once** in the final executable program, and it must contain all the moduli that have ever been declared in the `complex_declare!` macros across all the compilation units. This macro must be called after `moduli_init!`, and `mod_idx` must be the index of the modulus in the `moduli_init!` macro (and is unrelated to the order of `moduli_declare!` invocations or the modular structs in them).
+
+When `complex_init!` is called, the structs in it are enumerated from `0`. For each chip that is used, the first instruction that this chip receives must be a `setup` instruction -- this adds a record to the trace that guarantees that the modulus this chip uses is exactly the one we `init`ed.
+
+To send a setup instruction for the $i$-th struct, one needs to call the `setup_complex_<i>()` function (for instance, `setup_complex_1()`). There is also a function `setup_all_complex_extensions()` that calls all the available `setup` functions.
+
+To summarize:
+
+- `complex_declare!` declares a struct for a complex field extension class. It can be called multiple times across the compilation units.
+- `complex_init!` initializes the data required for transpiling the program into the RISC-V assembly. **Every struct ever `declare`d in the program must be among the arguments of `complex_init!`**.
+- `setup_complex_<i>()` sends a setup instruction for the $i$-th struct. Here, **$i$-th struct is the one that corresponds to the $i$-th modulus in `complex_init!`**. The order of `complex_declare!` invocations or the arguments in them does not matter.
+- `setup_all_complex_extensions()` sends setup instructions for all the structs.
+
+### A toy example of a guest program using `openvm-algebra` extension
+
+```rust
+#![cfg_attr(not(feature = "std"), no_main)]
+#![cfg_attr(not(feature = "std"), no_std)]
+
+use openvm_algebra_guest::IntMod;
+
+openvm::entry!(main);
+
+// This macro will create two structs, `Mod1` and `Mod2`,
+// one for arithmetic modulo 998244353, and the other for arithmetic modulo 1000000007.
+openvm_algebra_moduli_setup::moduli_declare! {
+    Mod1 { modulus = "998244353" },
+    Mod2 { modulus = "1000000007" }
+}
+
+// This macro will initialize the moduli.
+// Now, `Mod1` is the "zeroth" modular struct, and `Mod2` is the "first" one.
+openvm_algebra_moduli_setup::moduli_init! {
+    "998244353", "1000000007"
+}
+
+// This macro will create two structs, `Complex1` and `Complex2`,
+// one for arithmetic in the field $\mathbb{F}_{998244353}[x]/(x^2 + 1)$,
+// and the other for arithmetic in the field $\mathbb{F}_{1000000007}[x]/(x^2 + 1)$.
+openvm_algebra_complex_macros::complex_declare! {
+    Complex1 { mod_type = Mod1 },
+    Complex2 { mod_type = Mod2 },
+}
+
+// The order of these structs does not matter,
+// given that we specify the `mod_idx` parameters properly.
+openvm_algebra_complex_macros::complex_init! {
+    Complex2 { mod_idx = 1 }, Complex1 { mod_idx = 0 },
+}
+
+pub fn main() {
+    setup_all_complex_extensions();
+    let a = Complex1::new(Mod1::ZERO, Mod1::from_u32(0x3b8) * Mod1::from_u32(0x100000)); // a = -i in the corresponding field
+    let b = Complex2::new(Mod2::ZERO, Mod2::from_u32(1000000006)); // b = -i in the corresponding field
+    assert_eq!(a.clone() * &a * &a * &a * &a, a); // a^5 = a
+    assert_eq!(b.clone() * &b * &b * &b * &b, b); // b^5 = b
+    // Note that these assertions would fail, have we provided the `mod_idx` parameters wrongly.
+}
+```
+
 ## `openvm-ecc`
 
 This crate allows one to create and use structs for elliptic curve cryptography. More specifically, it only supports curves where the defining equation is in short [Weierstrass curves](https://en.wikipedia.org/wiki/Weierstrass_form) (that is, `a = 0`).

diff --git a/book/src/writing-apps/compile.md b/book/src/writing-apps/compile.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Cross-Compilation](#cross-compilation)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Cross-Compilation
diff --git a/book/src/writing-apps/onchain-verify.md b/book/src/writing-apps/onchain-verify.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Onchain Verification](#onchain-verification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Onchain Verification
diff --git a/book/src/writing-apps/overview.md b/book/src/writing-apps/overview.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Overview of Basic Usage](#overview-of-basic-usage)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Overview of Basic Usage
diff --git a/book/src/writing-apps/prove.md b/book/src/writing-apps/prove.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Generating Proofs](#generating-proofs)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Generating Proofs
diff --git a/book/src/writing-apps/testing.md b/book/src/writing-apps/testing.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Testing](#testing)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Testing
diff --git a/book/src/writing-apps/verify.md b/book/src/writing-apps/verify.md
@@ -1 +1,9 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Onchain Verification](#onchain-verification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Onchain Verification
diff --git a/book/src/writing-apps/write-program.md b/book/src/writing-apps/write-program.md
@@ -1,3 +1,15 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Writing a Program](#writing-a-program)
+  - [Writing a guest program](#writing-a-guest-program)
+    - [no-std](#no-std)
+    - [Building and running](#building-and-running)
+  - [Handling I/O](#handling-io)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # Writing a Program
 
 ## Writing a guest program