docs(book): add docs on init! macro (#1837)

And update on support for both getrandom v0.2 and v0.3.

closes INT-4186

Author: jonathanpwang

book/src/custom-extensions/algebra.md

@@ -22,7 +22,7 @@ The functional part is provided by the `openvm-algebra-guest` crate, which is a
 
 ## Modular arithmetic
 
-To [leverage](./overview.md) compile-time known moduli for performance, you declare, initialize, and then set up the arithmetic structures:
+To [leverage](./overview.md) compile-time known moduli for performance, you declare and initialize 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:
 
@@ -37,10 +37,10 @@ This creates `Bls12_381Fp` and `Bn254Fp` structs, each implementing the `IntMod`
 Since both moduli are prime, both structs also implement the `Field` and `Sqrt` traits.
 The modulus parameter must be a string literal in decimal or hexadecimal format.
 
-2. **Init**: Use the `init!` macro exactly once in the final binary:
+2. **Init**: Use the [`openvm::init!` macro](./overview.md#automating-the-init-step) exactly once in the final binary:
 
 ```rust
-init!();
+openvm::init!();
 /* This expands to
 moduli_init! {
     "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab",
@@ -70,10 +70,10 @@ complex_declare! {
 
 This creates a `Bn254Fp2` struct, representing a complex extension field. The `mod_type` must implement `IntMod`.
 
-2. **Init**: After calling `complex_declare!`, the `init!` macro will now expand to the appropriate call to `complex_init!`.
+2. **Init**: After calling `complex_declare!`, the [`openvm::init!` macro](./overview.md#automating-the-init-step) will now expand to the appropriate call to `complex_init!`.
 
 ```rust
-init!();
+openvm::init!();
 /* This expands to:
 moduli_init! {
     "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab",
@@ -115,9 +115,7 @@ To have the correct imports for the above example, add the following to the `Car
 ```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 }
 ```
 

book/src/custom-extensions/ecc.md

@@ -43,10 +43,10 @@ sw_declare! {
 Each declared curve must specify the `mod_type` (implementing `IntMod`) and a constant `b` for the Weierstrass curve equation \\(y^2 = x^3 + ax + b\\). `a` is optional and defaults to 0 for short Weierstrass curves.
 This creates `Bls12_381G1Affine` and `P256Affine` structs which implement the `Group` and `WeierstrassPoint` traits. The underlying memory layout of the structs uses the memory layout of the `Bls12_381Fp` and `P256Coord` structs, respectively.
 
-2. **Init**: Called once, the `init!` macro produces a call to `sw_init!` that enumerates these curves and allows the compiler to produce optimized instructions:
+2. **Init**: Called once, the [`openvm::init!` macro](./overview.md#automating-the-init-step) produces a call to `sw_init!` that enumerates these curves and allows the compiler to produce optimized instructions:
 
 ```rust
-init!();
+openvm::init!();
 /* This expands to
 sw_init! {
     Bls12_381G1Affine, P256Affine,

book/src/custom-extensions/overview.md

@@ -11,16 +11,22 @@ OpenVM ships with a set of pre-built extensions maintained by the OpenVM team. B
 
 ## Optimizing Modular Arithmetic
 
-Some of these extensions—specifically `algebra`, `ecc`, and `pairing`—perform modular arithmetic, which can be significantly optimized when the modulus is known at compile time.  Therefore, these extensions provide 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:
+Some of these extensions—specifically `algebra`, `ecc`, and `pairing`—perform modular arithmetic, which can be significantly optimized when the modulus is known at compile time.  Therefore, these extensions provide a framework to inform the compiler about all the moduli and associated arithmetic structures we intend to use. To achieve this, two 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.
 
 Our design for the configuration procedure above was inspired by the [EVMMAX proposal](https://github.com/jwasinger/EIPs/blob/evmmax-2/EIPS/eip-6601.md).
 
+### Automating the `init!` step
+
+The `openvm` crate provides an `init!` macro to automate the **init** step:
+1. Call `openvm::init!()` exactly once in the code of the final program binary.
+2. When [compiling the program](../writing-apps/build.md), `cargo openvm build` will read the [configuration file](#configuration) to automatically generate the correct init code and write it to `<INIT_FILE_NAME>`, which defaults to `openvm_init.rs` in the manifest directory.
+3. The `openvm::init!()` macro will include the `openvm_init.rs` file into the final binary to complete the init process. You can call `openvm::init!(INIT_FILE_NAME)` to include init code from a different file if needed.
+
 ## Configuration
 
 To use these extensions, you must populate an `openvm.toml` in your package root directory (where the `Cargo.toml` file is located).

book/src/custom-extensions/pairing.md

@@ -19,3 +19,5 @@ This asserts that \\(e(p_0, q_0) e(p_1, q_1) = 1\\).
 Naturally, this can be extended to more points by adding more elements to the arrays.
 
 The pairing extension additionally provides field operations in \\(\mathbb{F_{p^{12}}}\\) for both BN254 and BLS12-381 curves where \\(\mathbb{F}\\) is the coordinate field.
+
+See the [pairing guest library](../guest-libs/pairing.md) for usage details.

book/src/guest-libs/pairing.md

@@ -1,4 +1,4 @@
-## Pairing
+# Elliptic Curve Pairing
 
 We'll be working with an example using the BLS12-381 elliptic curve. This is in addition to the setup that needs to be done in the [Writing a Program](../writing-apps/write-program.md) section.
 

book/src/writing-apps/write-program.md

@@ -126,8 +126,8 @@ See the [overview](./overview.md) on how to build and run the program.
 
 ## Using crates that depend on `getrandom`
 
-OpenVM is compatible with [getrandom](https://crates.io/crates/getrandom) `v0.3`. The `cargo openvm` CLI will always compile with the [custom](https://docs.rs/getrandom/latest/getrandom/#opt-in-backends) `getrandom` backend.
+OpenVM is compatible with [getrandom](https://crates.io/crates/getrandom) `v0.2` and `v0.3`. The `cargo openvm` CLI will always compile with the [custom](https://docs.rs/getrandom/0.3.3/getrandom/#opt-in-backends) `getrandom` backend.
 
 By default the `openvm` crate has a default feature `"getrandom-unsupported"` which exports a `__getrandom_v03_custom` function that always returns `Err(Error::UNSUPPORTED)`. This is enabled by default to allow compilation of guest programs that pull in dependencies which require `getrandom` but where the executed code does not actually use `getrandom` functions.
 
-To override the default behavior and provide a custom implementation, turn off the `"getrandom-unsupported"` feature in the `openvm` crate and supply your own `__getrandom_v03_custom` function as specified in the [getrandom docs](https://docs.rs/getrandom/latest/getrandom/#custom-backend).
+To override the default behavior and provide a custom implementation, turn off the `"getrandom-unsupported"` feature in the `openvm` crate and supply your own `__getrandom_v03_custom` function as specified in the [getrandom docs](https://docs.rs/getrandom/0.3.3/getrandom/#custom-backend). Similar customization options are available for `getrandom` `v0.2`.