Merge pull request #3216 from o1-labs/dw/add-help-for-build

plonk-wasm: add some documentation

Author: querolita

Makefile

@@ -242,16 +242,18 @@ ${O1VM_MIPS_BIN_DIR}/%.o: ${O1VM_MIPS_SOURCE_DIR}/%.asm
 fclean: clean ## Clean the tooling artefacts in addition to running clean
 		rm -rf ${RISCV32_TOOLCHAIN_PATH}
 
-build-nodejs:
+.PHONY: build-nodejs
+build-nodejs: ## Compile the Kimchi library into WebAssembly to be used in NodeJS
 		cargo +nightly xtask build-wasm \
 		--target nodejs \
 		--out-dir ${PLONK_WASM_NODEJS_OUTDIR} \
 		--rust-version ${NIGHTLY_RUST_VERSION}
 
-build-web:
+.PHONY: build-web
+build-web: ## Compile the Kimchi library into WebAssembly to be used in the browser
 		cargo +nightly xtask build-wasm \
 		--target web \
 		--out-dir ${PLONK_WASM_WEB_OUTDIR} \
 		--rust-version ${NIGHTLY_RUST_VERSION}
 
-.PHONY: all setup install-test-deps clean build release test-doc test-doc-with-coverage test test-with-coverage test-heavy test-heavy-with-coverage test-all test-all-with-coverage nextest nextest-with-coverage nextest-heavy nextest-heavy-with-coverage nextest-all nextest-all-with-coverage format lint generate-test-coverage-report generate-doc setup-riscv32-toolchain help fclean build-riscv32-programs build-mips-programs check-format build-web build-nodejs
+.PHONY: all setup install-test-deps clean build release test-doc test-doc-with-coverage test test-with-coverage test-heavy test-heavy-with-coverage test-all test-all-with-coverage nextest nextest-with-coverage nextest-heavy nextest-heavy-with-coverage nextest-all nextest-all-with-coverage format lint generate-test-coverage-report generate-doc setup-riscv32-toolchain help fclean build-riscv32-programs build-mips-programs check-format

kimchi-stubs/src/field_vector.rs

@@ -1,4 +1,5 @@
-//! We implement a custom type for field vectors in order to quickly build field vectors from the OCaml side and avoid large vector clones.
+//! We implement a custom type for field vectors in order to quickly build field
+//! vectors from the OCaml side and avoid large vector clones.
 
 use paste::paste;
 

plonk-wasm/README.md

@@ -1,34 +1,89 @@
-# Kimchi WASM
+# Kimchi compatibility layer for WebAssembly
 
-This code allows us to compile parts of Kimchi into [Web Assembly (WASM)](https://webassembly.org/).
+This code allows us to compile parts of [Kimchi](./../kimchi) into [Web Assembly
+(WASM)](https://webassembly.org/), making the proof system available for use in
+Web and NodeJS applications.
+The WebAssembly module is also exposing all the methods and primitives that the
+OCaml Mina codebase requires.
 
-## Requirements
+The WebAssembly module will be used in particular to define frameworks like
+[o1js](https://github.com/o1-labs/o1js).
 
-For this to work, you will need to install the following dependencies:
+## Usage
 
-- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)
-- [wasm-bindgen-cli](https://rustwasm.github.io/docs/wasm-bindgen/reference/cli.html) (optional)
+Makefile targets are defined at the top-level of this repository.
+From that location, you can run
+```
+make build-nodejs # (for NodeJS environments)
+make build-web    # (for web browsers)
+```
+to compile the Kimchi library (and its dependencies) into a WebAssembly module
+ready to be run in NodeJS or in the browser.
 
-## Usage
+## Architecture and Inner Workings
 
-To build for nodejs:
+The plonk-wasm library serves as a bridge between the Rust-based Kimchi proof
+system and JavaScript environments. It consists of several key components:
 
-```console
-$ wasm-pack build --mode no-install --target nodejs --out-dir ./nodejs ./. -- --features nodejs
-```
+### 1. Core Components
 
-To build for web browsers:
+- **WebAssembly Bindings**: Uses
+  [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen) to expose Rust
+  functions and types to JavaScript.
+- **OCaml Compatibility**: Special serialization/deserialization layer
+  (`wasm_ocaml_serde`) that handles conversions between Rust structures and
+  JavaScript values following OCaml conventions.
 
-```console
-$ wasm-pack build --mode no-install --target web --out-dir ./web ./.
-```
+### 2. Exposed Functionality
+
+The library exposes several core components from the Kimchi proof system:
+
+- **Cryptographic primitives**: Field elements, elliptic curve operations, and
+  polynomial commitments, SRS
+- **Proof generation and verification**: Tools to generate and verify proofs
+  generated by the Kimchi system
+- **Poseidon hash**: Bindings to the Poseidon implementation used by the Kimchi
+  proof system
+
+The methods that will be exposed in the WebAssembly module are surrounded by the
+macro `#[wasm_bindgen]`.
+All Rust symbols used by the OCaml client of Mina are required to be exposed in
+the WebAssembly module, even if not directly desired in the user API.
+
+### 3. Build System
+
+The build process uses:
+
+- [wasm-pack](https://github.com/rustwasm/wasm-pack): For compiling and
+  packaging the Rust code into WebAssembly.
+- **Nightly Rust**. There is no apparent reasons to use nightly, but without
+  using nightly, users have encountered issues like
+  [DataCloneError](https://github.com/o1-labs/o1js/issues/1989)
+
+### 4. Memory Management
+
+The library provides:
+
+- Low-level pointer manipulation for efficient buffer management
+- Custom vector implementations for Rust/JavaScript interoperability
+- Support for handling large cryptographic structures efficiently
+
+### 5. Module Structure
+
+Key modules include:
 
-Note that optimized versions of these commands are available in:
+- `arkworks/`: WebAssembly wrappers around the arkworks library
+- `wasm_ocaml_serde/`: OCaml-compatible serialization
 
-- [/src/lib/crypto/kimchi_bindings/js/node_js/build.sh](/src/lib/crypto/kimchi_bindings/js/node_js/build.sh) (also called from the `dune` file in the same folder)
-- [/src/lib/crypto/kimchi_bindings/js/web/build.sh](/src/lib/crypto/kimchi_bindings/js/web/build.sh) (also called from the `dune` file in the same folder)
+- Cryptographic primitives:
+  - `circuit.rs`, `srs.rs`, `gate_vector.rs`, `oracle.rs`, `poly_comm.rs`,
+    `poseidon.rs`, `projective.rs`, `srs.rs`
+- Kimchi proof systems:
+- `pasta_fp_plonk_index.rs`, `pasta_fq_plonk_index.rs`, `plonk_proof.rs` and
+  `plonk_verifier_index.rs`.
 
 ## Resources
 
 - [Rust WASM book](https://rustwasm.github.io/docs/book/game-of-life/hello-world.html)
 - [WASM-bindgen book](https://rustwasm.github.io/docs/wasm-bindgen/)
+- [Kimchi Documentation](./../kimchi/README.md)

plonk-wasm/src/lib.rs

@@ -94,9 +94,6 @@ pub mod rayon;
 /// Arkworks types
 pub mod arkworks;
 
-/// Utils
-pub mod urs_utils; // TODO: move this logic to proof-systems
-
 /// Vectors
 pub mod gate_vector;
 

plonk-wasm/src/poseidon.rs

@@ -1,3 +1,13 @@
+//! This file defines wrapper for the Poseidon hash function that are used in
+//! the Mina codebase.
+//!
+//! It is a wrapper around the Poseidon implementation in the `mina_poseidon` crate.
+//! It is required as the native OCaml implementation of Mina does use the Rust
+//! implementation defined in the crate `mina_poseidon` instead of defining its
+//! own natively in OCaml for performance reasons. The bindings in OCaml can be
+//! found in `src/lib/crypto/kimchi_bindings/pasta_fp_poseidon` and
+//! `src/lib/crypto/kimchi_bindings/pasta_fq_poseidon` in the Mina codebase.
+
 use mina_curves::pasta::{Fp, Fq};
 use mina_poseidon::{constants::PlonkSpongeConstantsKimchi, permutation::poseidon_block_cipher};
 use wasm_bindgen::prelude::*;

plonk-wasm/src/rayon.rs

@@ -43,12 +43,14 @@ extern "C" {
     #[wasm_bindgen(js_name = startWorkers)]
     fn start_workers(module: JsValue, memory: JsValue, builder: PoolBuilder) -> Promise;
 }
+
 #[cfg(feature = "nodejs")]
 #[wasm_bindgen]
 extern "C" {
     #[wasm_bindgen(js_name = startWorkers)]
     fn start_workers(module: JsString, memory: JsValue, builder: PoolBuilder) -> Promise;
 }
+
 #[wasm_bindgen]
 extern "C" {
     #[wasm_bindgen(js_name = terminateWorkers)]

plonk-wasm/src/srs.rs

@@ -213,7 +213,7 @@ macro_rules! impl_srs {
                 crate::rayon::run_in_pool(|| {
                     let comms: Vec<_> = comms.into_iter().map(Into::into).collect();
                     let chals: Vec<_> = chals.into_iter().map(Into::into).collect();
-                    crate::urs_utils::batch_dlog_accumulator_check(&srs, &comms, &chals)
+                    poly_commitment::utils::batch_dlog_accumulator_check(&srs, &comms, &chals)
                 })
             }
 
@@ -223,7 +223,7 @@ macro_rules! impl_srs {
                 comms: i32,
                 chals: WasmFlatVector<$WasmF>,
             ) -> WasmVector<$WasmG> {
-                crate::urs_utils::batch_dlog_accumulator_generate::<$G>(
+                poly_commitment::utils::batch_dlog_accumulator_generate::<$G>(
                     &srs,
                     comms as usize,
                     &chals.into_iter().map(From::from).collect(),