[feat] polish declare/init macros (rename and move to one place etc)

Cargo.toml

@@ -41,7 +41,8 @@ members = [
     "extensions/algebra/circuit",
     "extensions/algebra/transpiler",
     "extensions/algebra/guest",
-    "extensions/algebra/moduli-setup",
+    "extensions/algebra/moduli-macros",
+    "extensions/algebra/complex-macros",
     "extensions/algebra/tests",
     "extensions/bigint/circuit",
     "extensions/bigint/transpiler",
@@ -58,7 +59,7 @@ members = [
     "extensions/ecc/circuit",
     "extensions/ecc/transpiler",
     "extensions/ecc/guest",
-    "extensions/ecc/sw-setup",
+    "extensions/ecc/sw-macros",
     "extensions/ecc/tests",
     "extensions/pairing/circuit",
     "extensions/pairing/transpiler",
@@ -153,12 +154,12 @@ openvm-bigint-guest = { path = "extensions/bigint/guest", default-features = fal
 openvm-algebra-circuit = { path = "extensions/algebra/circuit", default-features = false }
 openvm-algebra-transpiler = { path = "extensions/algebra/transpiler", default-features = false }
 openvm-algebra-guest = { path = "extensions/algebra/guest", default-features = false }
-openvm-algebra-moduli-setup = { path = "extensions/algebra/moduli-setup", default-features = false }
-openvm-algebra-complex-macros = { path = "extensions/algebra/guest/src/field/complex-macros", default-features = false }
+openvm-algebra-moduli-macros = { path = "extensions/algebra/moduli-macros", default-features = false }
+openvm-algebra-complex-macros = { path = "extensions/algebra/complex-macros", default-features = false }
 openvm-ecc-circuit = { path = "extensions/ecc/circuit", default-features = false }
 openvm-ecc-transpiler = { path = "extensions/ecc/transpiler", default-features = false }
 openvm-ecc-guest = { path = "extensions/ecc/guest", default-features = false }
-openvm-ecc-sw-setup = { path = "extensions/ecc/sw-setup", default-features = false }
+openvm-ecc-sw-macros = { path = "extensions/ecc/sw-macros", default-features = false }
 openvm-pairing-circuit = { path = "extensions/pairing/circuit", default-features = false }
 openvm-pairing-transpiler = { path = "extensions/pairing/transpiler", default-features = false }
 openvm-pairing-guest = { path = "extensions/pairing/guest", default-features = false }

benchmarks/programs/ecrecover/src/main.rs

@@ -21,11 +21,11 @@ use revm_precompile::{
 
 openvm::entry!(main);
 
-openvm_algebra_guest::moduli_setup::moduli_init! {
+openvm_algebra_guest::moduli_macros::moduli_init! {
     "0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE FFFFFC2F",
     "0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364141"
 }
-openvm_ecc_guest::sw_setup::sw_init! {
+openvm_ecc_guest::sw_macros::sw_init! {
     Secp256k1Point,
 }
 

benchmarks/src/bin/ecrecover.rs

@@ -93,7 +93,7 @@ fn main() -> Result<()> {
     let args = BenchmarkCli::parse();
 
     let elf = args.build_bench_program("ecrecover")?;
-    // TODO: update sw_setup macros and read it from elf.
+    // TODO: update sw_macros and read it from elf.
     let exe = VmExe::from_elf(
         elf,
         Transpiler::<BabyBear>::default()

book/src/custom-extensions/algebra.md

@@ -2,7 +2,7 @@
 
 The OpenVM Algebra extension 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)\\).
 
-The functional part is provided by the `openvm-algebra-guest` crate, which is a guest library that can be used in any OpenVM program. The macros for creating corresponding structs are in the `openvm-algebra-moduli-setup` and `openvm-algebra-complex-macros` crates.
+The functional part is provided by the `openvm-algebra-guest` crate, which is a guest library that can be used in any OpenVM program. The macros for creating corresponding structs are in the `openvm-algebra-moduli-macros` and `openvm-algebra-complex-macros` crates.
 
 ## Available traits and methods
 

docs/repo/layout.md

@@ -78,6 +78,12 @@ Command-line binary to compile, execute, and prove guest programs is in [`cli`](
 
 The toolchain, ISA, and VM are simultaneously extendable. All non-system functionality is implemented via extensions, which may be moved to standalone repositories in the future but are presently in this repository for maintainer convenience.
 
+#### Procedural macros for algebraic structs
+
+- [`openvm-algebra-moduli-macros`](../../extensions/algebra/moduli-macros): Procedural macros for use in guest program to generate modular arithmetic struct with custom intrinsics for compile-time modulus.
+- [`openvm-algebra-complex-macros`](../../extensions/algebra/complex-macros): Procedural macros for use in guest program to generate complex field struct with custom intrinsics for compile-time modulus.
+- [`openvm-ecc-sw-macros`](../../extensions/ecc/sw-macros): Procedural macros for use in guest program to generate short Weierstrass curve struct with custom intrinsics for compile-time curve.
+
 #### RV32IM
 
 - [`openvm-rv32im-circuit`](../../extensions/rv32im/circuit): Circuit extension for RV32IM instructions and IO instructions.
@@ -111,16 +117,13 @@ The toolchain, ISA, and VM are simultaneously extendable. All non-system functio
 - [`openvm-algebra-circuit`](../../extensions/algebra/circuit): Circuit extension for modular arithmetic for arbitrary compile-time modulus. Supports modular arithmetic and complex field extension operations.
 - [`openvm-algebra-transpiler`](../../extensions/algebra/transpiler): Transpiler extension for modular arithmetic for arbitrary compile-time modulus. Supports modular arithmetic and complex field extension operations.
 - [`openvm-algebra-guest`](../../extensions/algebra/guest): Guest library with traits for modular arithmetic and complex field extension operations.
-- [`openvm-algebra-moduli-setup`](../../extensions/algebra/moduli-setup): Procedural macros for use in guest program to generate modular arithmetic struct with custom intrinsics for compile-time modulus.
-- [`openvm-algebra-complex-macros`](../../extensions/algebra/guest/src/field/complex-macros): Procedural macros for use in guest program to generate complex field struct with custom intrinsics for compile-time modulus.
 - [`openvm-algebra-tests`](../../extensions/algebra/tests): Integration tests for the algebra extension.
 
 #### Elliptic Curve Cryptography
 
 - [`openvm-ecc-circuit`](../../extensions/ecc/circuit): Circuit extension for Weierstrass elliptic curve operations for arbitrary compile-time curve.
 - [`openvm-ecc-transpiler`](../../extensions/ecc/transpiler): Transpiler extension for Weierstrass elliptic curve operations for arbitrary compile-time curve.
 - [`openvm-ecc-guest`](../../extensions/ecc/guest): Guest library with traits for elliptic curve cryptography. Includes implementations of ECDSA and multi-scalar multiplication.
-- [`openvm-ecc-sw-setup`](../../extensions/ecc/sw-setup): Procedural macros for use in guest program to generate short Weierstrass curve struct with custom intrinsics for compile-time curve.
 - [`openvm-ecc-tests`](../../extensions/ecc/tests): Integration tests for the elliptic curve cryptography extension.
 
 #### Elliptic Curve Pairing

examples/algebra/src/main.rs

@@ -1,7 +1,7 @@
 #![cfg_attr(not(feature = "std"), no_main)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
-use openvm_algebra_guest::{moduli_setup::*, IntMod};
+use openvm_algebra_guest::{moduli_macros::*, IntMod};
 
 openvm::entry!(main);
 

examples/ecc/src/main.rs

@@ -11,12 +11,12 @@ use openvm_ecc_guest::{
 // ANCHOR_END: imports
 
 // ANCHOR: init
-openvm_algebra_guest::moduli_setup::moduli_init! {
+openvm_algebra_guest::moduli_macros::moduli_init! {
     "0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE FFFFFC2F",
     "0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364141"
 }
 
-openvm_ecc_guest::sw_setup::sw_init! {
+openvm_ecc_guest::sw_macros::sw_init! {
     Secp256k1Point,
 }
 // ANCHOR_END: init

examples/pairing/Cargo.toml

@@ -10,7 +10,7 @@ members = []
 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" }
+openvm-algebra-moduli-macros = { git = "https://github.com/openvm-org/openvm.git" }
 openvm-algebra-complex-macros = { git = "https://github.com/openvm-org/openvm.git" }
 openvm-ecc-guest = { git = "https://github.com/openvm-org/openvm.git" }
 openvm-pairing-guest = { git = "https://github.com/openvm-org/openvm.git", features = ["bls12_381"] }

examples/pairing/src/main.rs

@@ -14,7 +14,7 @@ use openvm_pairing_guest::{
 // ANCHOR_END: imports
 
 // ANCHOR: init
-openvm_algebra_moduli_setup::moduli_init! {
+openvm_algebra_moduli_macros::moduli_init! {
     "0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab",
     "0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001"
 }

extensions/algebra/complex-macros/README.md

@@ -0,0 +1,101 @@
+# `openvm-algebra-complex-macros`
+
+Procedural macros for use in guest program to generate modular arithmetic struct with custom intrinsics for compile-time modulus.
+
+The workflow of this macro is very similar to the [`openvm-algebra-moduli-macros`](../moduli-macros/README.md) crate. We recommend reading it first.
+
+## Example
+
+```rust
+openvm_algebra_moduli_macros::moduli_declare! {
+    Secp256k1Coord { modulus = "0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE FFFFFC2F" }
+}
+openvm_algebra_moduli_macros::moduli_init!(
+    "0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE FFFFFC2F"
+);
+
+openvm_algebra_complex_macros::complex_declare! {
+    Complex { mod_type = Secp256k1Coord }
+}
+
+openvm_algebra_complex_macros::complex_init! {
+    Complex { mod_idx = 0 },
+}
+
+pub fn main() {
+    setup_all_moduli();
+    setup_all_complex_extensions();
+    // ...
+}
+```
+
+## Full story
+
+Again, the principle is the same as in the [`openvm-algebra-moduli-macros`](../moduli-macros/README.md) crate. Here we emphasize the core differences.
+
+The crate provides two macros: `complex_declare!` and `complex_init!`. The signatures are:
+
+- `complex_declare!` receives comma-separated list of moduli classes descriptions. Each description looks like `ComplexStruct { mod_type = ModulusName }`. Here `ModulusName` is the name of any struct that implements `trait IntMod` -- in particular, the ones created by `moduli_declare!` do, and `ComplexStruct` is the name for the complex arithmetic struct to create.
+
+- `complex_init!` receives comma-separated list of struct descriptions. Each description looks like `ComplexStruct { mod_idx = idx }`. Here `ComplexStruct` is the name of the complex struct used in `complex_declare!`, and `idx` is the index of the modulus **in the `moduli_init!` macro**.
+
+What happens under the hood:
+
+1. `complex_declare!` macro creates a struct with two field `c0` and `c1` of type `mod_type`. In the example it would be
+
+```rust
+struct Complex {
+    c0: Secp256k1Coord,
+    c1: Secp256k1Coord,
+}
+```
+
+Similar to `moduli_declare!`, this macro also creates extern functions for arithmetic operations -- but in this case they are named after the complex type, not after any hexadecimal (since the macro has no way to obtain it from the name of the modulus type anyway):
+
+```rust
+extern "C" {
+    fn complex_add_extern_func_Complex(rd: usize, rs1: usize, rs2: usize);
+    fn complex_sub_extern_func_Complex(rd: usize, rs1: usize, rs2: usize);
+    fn complex_mul_extern_func_Complex(rd: usize, rs1: usize, rs2: usize);
+    fn complex_div_extern_func_Complex(rd: usize, rs1: usize, rs2: usize);
+}
+```
+
+2. Again, `complex_init!` macro implements these extern functions and defines the setup functions for the complex arithmetic struct.
+
+```rust
+#[cfg(target_os = "zkvm")]
+mod openvm_intrinsics_ffi_complex {
+    fn complex_add_extern_func_Complex(rd: usize, rs1: usize, rs2: usize) {
+        // send the instructions corresponding to the modulus with the provided `mod_idx`
+    }
+    // implement the other functions
+}
+pub fn setup_complex_0() {
+    // send the setup instructions
+}
+pub fn setup_all_complex_extensions() {
+    setup_complex_0();
+    // call all other setup_complex_* for all the items in the moduli_init! macro
+}
+```
+
+3. Obviously, `mod_idx` in the `complex_init!` must match the position of the corresponding modulus in the `moduli_init!` macro. The order of the items in `complex_init!` affects what `setup_complex_*` function will correspond to what complex class. Also, it **must match** the order of the moduli in the chip configuration -- more specifically, in the modular extension parameters (the order of numbers in `Fp2Extension::supported_modulus`, which is usually defined with the whole `app_vm_config` in the `openvm.toml` file). However, it again imposes the restriction that we only can invoke `complex_init!` once. Again analogous to the moduli setups, we must call `setup_complex_*` for each used complex extension before doing anything with entities of that class (or one can call `setup_all_complex_extensions` to setup all of them, if all are used).
+
+4. Note that, due to the nature of function names, the name of the struct used in `complex_init!` must be the same as in `complex_declare!`. To illustrate, the following code will **fail** to compile:
+
+```rust
+// moduli related macros...
+
+complex_declare! {
+    Bn254Fp2 { mod_type = Bn254Fp },
+}
+
+pub type Fp2 = Bn254Fp2;
+
+complex_init! {
+    Fp2 { mod_idx = 0 },
+}
+```
+
+The reason is that, for example, the function `complex_add_extern_func_Bn254Fp2` remains unimplemented, but we implement `complex_add_extern_func_Fp2` instead.

extensions/algebra/guest/Cargo.toml

@@ -10,7 +10,7 @@ repository.workspace = true
 [dependencies]
 openvm = { workspace = true }
 openvm-platform = { workspace = true }
-openvm-algebra-moduli-setup = { workspace = true }
+openvm-algebra-moduli-macros = { workspace = true }
 openvm-algebra-complex-macros = { workspace = true }
 serde = { workspace = true }
 serde-big-array = "0.5.1"

extensions/algebra/guest/src/lib.rs

@@ -53,7 +53,7 @@ pub use field::Field;
 #[cfg(not(target_os = "zkvm"))]
 use num_bigint::BigUint;
 pub use openvm_algebra_complex_macros as complex_macros;
-pub use openvm_algebra_moduli_setup as moduli_setup;
+pub use openvm_algebra_moduli_macros as moduli_macros;
 pub use serde_big_array::BigArray;
 use strum_macros::FromRepr;
 

extensions/algebra/moduli-setup/Cargo.toml → extensions/algebra/moduli-macros/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "openvm-algebra-moduli-setup"
+name = "openvm-algebra-moduli-macros"
 version = { workspace = true }
 edition = "2021"