Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: add imports in book #1099

Merged
merged 4 commits into from
Dec 16, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 41 additions & 12 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,9 +93,24 @@ 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)]
Expand Down Expand Up @@ -141,16 +159,27 @@ 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-moduli-setup = { git = "https://github.com/openvm-org/openvm.git" }
jonathanpwang marked this conversation as resolved.
Show resolved Hide resolved
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.