diff --git a/book/src/custom-extensions/algebra.md b/book/src/custom-extensions/algebra.md index 47585c97be..11eee7d389 100644 --- a/book/src/custom-extensions/algebra.md +++ b/book/src/custom-extensions/algebra.md @@ -7,20 +7,22 @@ The functional part is provided by the `openvm-algebra-guest` crate, which is a ## 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`. + 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. + Provides constants `ZERO` and `ONE` and methods for basic arithmetic operations within a field. ## Modular arithmetic To [leverage](./overview.md) 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" }, @@ -44,6 +46,7 @@ This step enumerates the declared moduli (e.g., `0` for the first one, `1` for t 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_()` (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_()`/`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. @@ -90,27 +93,42 @@ Here, `mod_idx` refers to the index of the underlying modulus as initialized by 3. **Setup**: Similar to moduli, call `setup_complex_()` or `setup_all_complex_extensions()` at runtime to secure the environment. +### Config parameters + +For the guest program to build successfully, all used moduli must be declared in the `.toml` config file in the following format: + +```toml +[app_vm_config.modular] +supported_modulus = ["115792089237316195423570985008687907853269984665640564039457584007908834671663"] + +[app_vm_config.fp2] +supported_modulus = ["115792089237316195423570985008687907853269984665640564039457584007908834671663"] +``` + +The `supported_modulus` parameter is a list of moduli that the guest program will use. They must be provided in decimal format in the `.toml` file. + ### 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; +use openvm_algebra_guest::{IntMod, moduli_setup::*}; 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! { +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! { +moduli_init! { "998244353", "1000000007" } @@ -141,16 +159,26 @@ pub fn main() { } ``` -### Config parameters +To have the correct imports for the above example, add the following to the `Cargo.toml` file: -For the guest program to build successfully, all used moduli must be declared in the `.toml` config file in the following format: +```toml +[dependencies] +openvm = { git = "https://github.com/openvm-org/openvm.git" } +openvm-platform = { git = "https://github.com/openvm-org/openvm.git" } +openvm-algebra-guest = { git = "https://github.com/openvm-org/openvm.git" } +openvm-algebra-complex-macros = { git = "https://github.com/openvm-org/openvm.git" } +serde = { version = "1.0.216", default-features = false } +``` + +Here is the full `openvm.toml` to accompany the above example: ```toml +[app_vm_config.rv32i] +[app_vm_config.rv32m] +[app_vm_config.io] [app_vm_config.modular] -supported_modulus = ["115792089237316195423570985008687907853269984665640564039457584007908834671663"] +supported_modulus = ["998244353","1000000007"] [app_vm_config.fp2] -supported_modulus = ["115792089237316195423570985008687907853269984665640564039457584007908834671663"] +supported_modulus = ["998244353","1000000007"] ``` - -The `supported_modulus` parameter is a list of moduli that the guest program will use. They must be provided in decimal format in the `.toml` file.