[feat] axvm-algebra-guest usage

book/book.toml

@@ -7,3 +7,6 @@ title = "OpenVM Book"
 
 [output.html]
 site-url = "https://book.openvm.dev/"
+additional-head = [
+    "<script async src=\"https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js\" id=\"MathJax-script\"></script>"
+]

book/src/SUMMARY.md

@@ -19,7 +19,7 @@
 
 # Using Extensions
 
-- [Customizable Extensions](./using-extensions/customizable-extensions.md)
+- [Customizable Extensions](./custom-extensions/customizable-extensions.md)
 
 # Advanced Usage
 

book/src/advanced-usage/overview.md

@@ -1 +1,19 @@
 # Overview
+
+# Using Existing Extensions
+
+Certain arithmetic operations, particularly modular arithmetic, can be optimized significantly when the modulus is known at compile time.  This approach requires a framework to inform the compiler about all the moduli and associated arithmetic structures we intend to use. To achieve this, three steps are involved:
+
+1. **Declare**: Introduce a modular arithmetic or related structure, along with its modulus and functionality. This can be done in any library or binary file.
+2. **Init**: Performed exactly once in the final binary. It aggregates all previously declared structures, assigns them stable indices, and sets up linkage so that they can be referenced in generated code.
+3. **Setup**: A one-time runtime procedure for security. This ensures that the compiled code matches the virtual machine’s expectations and that each instruction set is tied to the correct modulus or extension.
+
+These steps ensure both performance and security: performance because the modulus is known at compile time, and security because runtime checks confirm that the correct structures have been initialized.
+
+The list of existing extensions:
+
+- [`openvm-algebra`](./custom-extensions/algebra.md)
+- [`openvm-bigint`](./custom-extensions/bigint.md)
+- [`openvm-keccak`](./custom-extensions/keccak.md)
+- [`openvm-pairing`](./custom-extensions/pairing.md)
+- [`openvm-ecc`](./custom-extensions/ecc.md)

book/src/advanced-usage/testing-program.md

@@ -1,4 +1,3 @@
-
 ## Testing the program
 
 ### Running on the host machine

book/src/custom-extensions/algebra.md

@@ -0,0 +1,122 @@
+# `openvm-algebra`
+
+The `openvm-algebra` crate provides tools to create and manipulate modular arithmetic structures and their complex extensions. For example, if $p$ is prime, `openvm-algebra` can handle modular arithmetic in $\mathbb{F}_p$​ and its quadratic extension fields $\mathbb{F}_p[x]/(x^2 + 1)$.
+
+## Available traits and methods
+
+- `IntMod` trait:
+    Defines the type `Repr` and constants `MODULUS`, `NUM_LIMBS`, `ZERO`, and `ONE`. It also provides basic methods for constructing a modular arithmetic object and performing arithmetic operations.
+    - `Repr` typically is `[u8; NUM_LIMBS]`, representing the number’s underlying storage.
+    - `MODULUS` is the compile-time known modulus.
+    - `ZERO` and `ONE` represent the additive and multiplicative identities, respectively.
+    - Constructors include `from_repr`, `from_le_bytes`, `from_be_bytes`, `from_u8`, `from_u32`, and `from_u64`.
+
+- `Field` trait:
+    Provides constants `ZERO` and `ONE` and methods for basic arithmetic operations within a field.
+
+## Modular arithmetic
+
+To leverage compile-time known moduli for performance, you declare, initialize, and then set up the arithmetic structures:
+
+1. **Declare**: Use the `moduli_declare!` macro to define a modular arithmetic struct. This can be done multiple times in various crates or modules:
+
+```rust
+moduli_declare! {
+    Bls12_381Fp { modulus = "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab" },
+    Bn254Fp { modulus = "21888242871839275222246405745257275088696311157297823662689037894645226208583" },
+}
+```
+
+This creates `Bls12381_Fp` and `Bn254_Fp` structs, each implementing `Add`, `Sub`, and other operations defined by `IntMod`. The modulus parameter must be a string literal in decimal or hexadecimal format.
+
+2. **Init**: Use the `moduli_init!` macro exactly once in the final binary:
+
+```rust
+moduli_init! {
+    "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab",
+    "21888242871839275222246405745257275088696311157297823662689037894645226208583"
+}
+```
+
+This step enumerates the declared moduli (e.g., `0` for the first one, `1` for the second one) and sets up internal linkage so the compiler can generate the appropriate RISC-V instructions associated with each modulus.
+
+3. **Setup**: At runtime, before performing arithmetic, a setup instruction must be sent to ensure security and correctness. For the $i$-th modulus, you call `setup_<i>()` (e.g., `setup_0()` or `setup_1()`). Alternatively, `setup_all_moduli()` can be used to handle all declared moduli.
+
+**Summary**:
+- `moduli_declare!`: Declares modular arithmetic structures and can be done multiple times.
+- `moduli_init!`: Called once in the final binary to assign and lock in the moduli.
+- `setup_<i>()`/`setup_all_moduli()`: Ensures at runtime that the correct modulus is in use, providing a security check and finalizing the environment for safe arithmetic operations.
+
+## Complex field extension
+
+Complex extensions, such as $\mathbb{F}_p[x]/(x^2 + 1)$, are defined similarly using `complex_declare!` and `complex_init!`:
+
+1. **Declare**:
+
+```rust
+complex_declare! {
+    Bn254_Fp2 { mod_type = Bn254_Fp }
+}
+```
+
+This creates a `Bn254_Fp2` struct, representing a complex extension field. The `mod_type` must implement `IntMod`.
+
+2. **Init**: Called once, after `moduli_init!`, to enumerate these extensions and generate corresponding instructions:
+
+```rust
+complex_init! {
+    Bn254_Fp2 { mod_idx = 0 },
+}
+```
+
+Here, `mod_idx` refers to the index of the underlying modulus as initialized by `moduli_init!`
+
+3. **Setup**: Similar to moduli, call `setup_complex_<i>()` or `setup_all_complex_extensions()` at runtime to secure the environment.
+
+### Example program
+
+Here is a toy example using both the modular arithmetic and complex field extension capabilities:
+```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.
+}
+```

book/src/custom-extensions/bigint.md

@@ -0,0 +1 @@
+# `openvm-bigint`

book/src/custom-extensions/ecc.md

@@ -0,0 +1,30 @@
+# `openvm-ecc`
+
+For elliptic curve cryptography, the `openvm-ecc` crate provides macros similar to those in [`openvm-algebra`](./algebra.md):
+
+1. **Declare**: Use `sw_declare!` to define elliptic curves over the previously declared moduli. For example:
+
+```rust
+sw_declare! {
+    Bls12_381G1Affine { mod_type = Bls12_381Fp, b = BLS12_381_B },
+    Bn254G1Affine { mod_type = Bn254Fp, b = BN254_B },
+}
+```
+
+Each declared curve must specify the `mod_type` (implementing `IntMod`) and a constant `b` for the Weierstrass curve equation $y^2 = x^3 + b$.
+
+2. **Init**: Called once, it enumerates these curves and allows the compiler to produce optimized instructions:
+
+```rust
+sw_init! {
+    Bls12_381Fp, Bn254Fp,
+}
+```
+
+3. **Setup**: Similar to the moduli and complex extensions, runtime setup instructions ensure that the correct curve parameters are being used, guaranteeing secure operation.
+
+**Summary**:
+
+- `sw_declare!`: Declares elliptic curve structures.
+- `sw_init!`: Initializes them once, linking them to the underlying moduli.
+- `setup_sw_<i>()`/`setup_all_curves()`: Secures runtime correctness.

book/src/custom-extensions/keccak.md

@@ -0,0 +1 @@
+# `openvm-keccak`

book/src/custom-extensions/pairing.md

@@ -0,0 +1 @@
+# `openvm-pairing`