Skip to content

Commit

Permalink
chore: add imports in book (#1099)
Browse files Browse the repository at this point in the history
* chore: add imports in book

* fix: bad fmt

* fix: fmt

* chore: save an import
  • Loading branch information
jonathanpwang authored Dec 16, 2024
1 parent 160cdac commit 31c5b18
Showing 1 changed file with 43 additions and 15 deletions.
58 changes: 43 additions & 15 deletions book/src/custom-extensions/algebra.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" },
Expand All @@ -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_<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.
Expand Down Expand Up @@ -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_<i>()` 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"
}

Expand Down Expand Up @@ -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.

0 comments on commit 31c5b18

Please sign in to comment.