@nori-zk/proof-conversion-utils 0.5.0 → 0.5.1

package/README.md

@@ -14,6 +14,8 @@ This package provides utilities to assist witness creation and alpha-beta pairin
 
 ## TypeScript API
 
+--------------------------------------------------------------------------------------------
+
 ### Types
 
 #### `AffinePoint2d`
@@ -244,7 +246,6 @@ interface SnarkjsVK {
   vk_beta_2: [[string, string], [string, string], [string, string]];
   vk_gamma_2: [[string, string], [string, string], [string, string]];
   vk_delta_2: [[string, string], [string, string], [string, string]];
-  vk_alphabeta_12: [[string, string], [string, string], [string, string]];
   IC: Array<[string, string, string]>;
 }
 ```
@@ -305,74 +306,212 @@ export interface SP1ProofWithPublicValues {
 }
 ```
 
+--------------------------------------------------------------------------------------------
+
 ### Functions
 
-#### `compute_pairing(input: PairingInput): Field12`
+#### `compute_aux_witness`
 
-Computes a pairing for a verification key.
+```typescript
+export function compute_aux_witness(input: Field12): AuxWitness;
+```
+
+Computes the auxiliary witness from a Miller loop output.
+
+**What This Does**
+
+Takes a 12-element field value (the result of a Miller loop pairing computation)
+and computes the auxiliary witness needed for efficient verification.
+
+The Miller loop is the first step of pairing-based verification. Its output
+needs further processing (final exponentiation), which is expensive. The
+auxiliary witness provides precomputed hints that make this step efficient.
+
+**Input**
+
+A JS object matching `Field12` structure (12 string fields: g00-g21, h00-h21).
 
-Takes two curve points (alpha and beta from the trusted setup) and computes their pairing using the Miller loop algorithm. The result is a 12-element field value that gets stored in the verification key.
+**Output**
+
+Return a JS object matching `AuxWitness` structure containing:
+- `c`: A 12-element field value
+- `shift_power`: "0", "1", or "2"
+
+**Error**
+
+Throws a JsError if the input is not a valid Miller loop output (fails internal assertion).
+
+#### `compute_pairing`
 
 ```typescript
-const result = compute_pairing({
-  alpha: { x: '...', y: '...' },
-  beta: { x_c0: '...', x_c1: '...', y_c0: '...', y_c1: '...' }
-});
+export function compute_pairing(input: PairingInput): Field12;
 ```
 
-#### `compute_aux_witness(input: Field12): AuxWitness`
+Computes a pairing for a verification key.
 
-Computes the auxiliary witness from a Miller loop output.
+**What This Does**
+
+Takes two curve points (alpha and beta from the trusted setup) and computes
+their pairing using the Miller loop algorithm. The result is a 12-element
+field value that gets stored in the verification key.
+
+This pairing e(alpha, beta) is constant for a given verification key, so it's
+precomputed once and reused for all proof verifications.
+
+**Input**
+
+A JS object matching `PairingInput` structure:
+- `alpha`: An `AffinePoint2d` with `x` and `y` fields
+- `beta`: A `ComplexAffinePoint2d` with `x_c0`, `x_c1`, `y_c0`, `y_c1` fields
 
-Takes a 12-element field value (the result of a Miller loop pairing computation) and computes the auxiliary witness needed for efficient verification.
+**Output**
+
+Returns a JS object matching `Field12` structure (12 string fields: g00-g21, h00-h21).
+
+**Errors**
+
+Throws a JS error if input parsing or coordinate conversion fails.
+
+#### `convert_snarkjs_groth16_to_o1js`
 
 ```typescript
-const auxWitness = compute_aux_witness({
-  g00: '...', g01: '...', g10: '...', g11: '...', g20: '...', g21: '...',
-  h00: '...', h01: '...', h10: '...', h11: '...', h20: '...', h21: '...'
-});
+export function convert_snarkjs_groth16_to_o1js(proof: SnarkjsProof, public_inputs: string[], vk: SnarkjsVK): O1jsGroth16;
 ```
 
-#### `convert_snarkjs_groth16_to_o1js(proof: SnarkjsProof, public_inputs: string[], vk: SnarkjsVK): O1jsGroth16`
+Converts a snarkjs/circom Groth16 proof and verification key to o1js format.
 
-Converts a SnarkJS/Circom Groth16 proof and verification key to o1js format.
+This function takes Groth16 proofs generated by snarkjs (the JavaScript implementation
+of Groth16 commonly used with circom circuits) and converts them to o1js format for
+verification in Mina Protocol zkApps.
 
-This function takes Groth16 proofs generated by snarkjs (the JavaScript implementation of Groth16 commonly used with circom circuits) and converts them to o1js format for verification in Mina Protocol zkApps.
+**Conversion Details**
 
-**Key Conversions:**
-- The A point (`pi_a`) is negated for o1js compatibility
-- Points are converted from projective coordinates to affine form
-- The `alpha_beta` pairing e(α, β) is precomputed
-- Supports up to 6 public inputs
+**Proof Conversion**
+- The A point (`pi_a`) is **negated** for o1js compatibility. The o1js verification
+  equation uses `-A` rather than `A` in the pairing check.
+- Points are converted from projective coordinates (with z component) to affine form.
+- The B point is a G2 point with complex coordinates (x_c0, x_c1, y_c0, y_c1).
+- The C point is a G1 point with simple coordinates (x, y).
 
-```typescript
-import { convert_snarkjs_groth16_to_o1js } from '@nori-zk/proof-conversion-utils';
+**Verification Key Conversion**
+- All curve points are converted from projective to affine form.
+- The `alpha_beta` pairing e(α, β) is computed using arkworks `multi_miller_loop`.
+  This is a constant for each VK and is precomputed to save verification time.
+- A hardcoded `w27` (27th root of unity) is added for pairing optimizations.
+  See https://eprint.iacr.org/2024/640 for the optimization technique.
+- IC (input commitment) points are mapped to ic0-ic6 fields.
 
-const o1jsFormat = convert_snarkjs_groth16_to_o1js(
-  snarkjsProof,
-  ['123', '456'],  // Public inputs as strings
-  snarkjsVK
-);
-```
+**Validation**
+- The `nPublic` field in the VK must match the number of public inputs provided.
+- The IC array length must equal nPublic + 1 (ic0 is the constant term).
 
-#### `convert_sp1_groth16_to_o1js(sp1_proof: SP1ProofWithPublicValues): O1jsGroth16`
+**Input Format**
 
-Converts an SP1 Groth16 proof to o1js format.
+- `proof`: snarkjs proof JSON object with:
+  - `pi_a`: `[x, y, z]` - A point in G1 projective coordinates
+  - `pi_b`: `[[x_c0, x_c1], [y_c0, y_c1], [z_c0, z_c1]]` - B point in G2 projective
+  - `pi_c`: `[x, y, z]` - C point in G1 projective coordinates
 
-This function takes Groth16 proofs generated by SP1 (Succinct's zkVM) and converts them to o1js format for verification in Mina Protocol zkApps. SP1 uses gnark's Groth16 implementation internally.
+- `public_inputs`: Array of public input strings as decimal numbers, e.g., `["123", "456"]`.
+  Maximum 6 public inputs are supported.
 
-**Key Features:**
-- Automatically decompresses gnark-formatted proof bytes
-- Uses the embedded SP1 v5.0.0 verification key (all SP1 Groth16 proofs use the same VK)
-- Negates the A point for o1js compatibility
-- SP1 Groth16 proofs always have exactly 2 public inputs (vkey_hash and public_values_hash)
+- `vk`: snarkjs verification key JSON object with:
+  - `nPublic`: Number of public inputs
+  - `vk_alpha_1`: Alpha point (G1 projective)
+  - `vk_beta_2`: Beta point (G2 projective)
+  - `vk_gamma_2`: Gamma point (G2 projective)
+  - `vk_delta_2`: Delta point (G2 projective)
+  - `IC`: Array of IC points (G1 projective), length = nPublic + 1
 
-```typescript
-import { convert_sp1_groth16_to_o1js } from '@nori-zk/proof-conversion-utils';
+**Output Format**
+
+Returns a JS object matching `O1jsGroth16` containing:
+
+- `proof`: o1js-formatted proof with:
+  - `negA`: Negated A point `{x, y}` as decimal strings
+  - `B`: B point `{x_c0, x_c1, y_c0, y_c1}` as decimal strings
+  - `C`: C point `{x, y}` as decimal strings
+  - `pi1` through `pi6`: Public inputs (only present if provided)
+
+- `vk`: o1js-formatted verification key with:
+  - `alpha`, `beta`, `gamma`, `delta`: Curve points
+  - `alpha_beta`: Precomputed pairing as 12-element Fq12 field
+  - `w27`: 27th root of unity as 12-element Fq12 field
+  - `ic0` through `ic6`: Input commitment points (only present if in VK)
+
+**Errors**
 
-const o1jsFormat = convert_sp1_groth16_to_o1js(sp1Proof);
+Throws a JsError error if:
+- Input JSON parsing fails (invalid structure or types)
+- VK validation fails (`nPublic` doesn't match public inputs count, wrong IC length)
+- Point coordinate parsing fails (invalid field element strings)
+- More than 6 public inputs are provided
+
+#### `convert_sp1_groth16_to_o1js`
+
+```typescript
+export function convert_sp1_groth16_to_o1js(sp1_proof: SP1ProofWithPublicValues): O1jsGroth16;
 ```
 
+Converts an SP1 Groth16 proof to o1js format.
+
+This function takes Groth16 proofs generated by SP1 (Succinct's zkVM) and converts
+them to o1js format for verification in Mina Protocol zkApps. SP1 uses gnark's
+Groth16 implementation internally, which produces proofs in a compressed format
+that must be decompressed before conversion.
+
+**Conversion Details**
+
+**Proof Extraction & Decompression**
+- The `encoded_proof` field contains hex-encoded gnark proof bytes.
+- The first 4 bytes of the proof are a vkey hash prefix (skipped during parsing).
+- gnark uses a compressed point format that differs from arkworks. This function
+  decompresses G1 and G2 points using endianness conversion and flag translation.
+- The decompression follows the gnark → arkworks conversion from sp1-sui.
+
+**Proof Conversion**
+- The A point is **negated** for o1js compatibility. The o1js verification
+  equation uses `-A` rather than `A` in the pairing check.
+- SP1 Groth16 proofs have exactly 2 public inputs (vkey_hash and public_values_hash).
+
+**Verification Key**
+- All SP1 v5.0.0 Groth16 proofs use the **same verification key**. This VK is
+  embedded in the library (`GROTH16_VK_5_0_0_BYTES`) and loaded automatically.
+- The VK is decompressed from gnark format to arkworks format.
+- The `alpha_beta` pairing e(α, β) is computed and included in the output.
+- The hardcoded `w27` (27th root of unity) is added for pairing optimizations.
+
+**Input Format**
+
+- `sp1_proof`: SP1ProofWithPublicValues JSON shim object representation
+- FIXME write an example here!
+
+**Output Format**
+
+Returns a JS object `O1jsGroth16` containing:
+
+- `proof`: o1js-formatted proof with:
+  - `negA`: Negated A point `{x, y}` as decimal strings
+  - `B`: B point `{x_c0, x_c1, y_c0, y_c1}` as decimal strings
+  - `C`: C point `{x, y}` as decimal strings
+  - `pi1`: First public input (vkey_hash)
+  - `pi2`: Second public input (public_values_hash)
+
+- `vk`: o1js-formatted SP1 v5.0.0 verification key with:
+  - `alpha`, `beta`, `gamma`, `delta`: Curve points
+  - `alpha_beta`: Precomputed pairing as 12-element Fq12 field
+  - `w27`: 27th root of unity as 12-element Fq12 field
+  - `ic0`, `ic1`, `ic2`: Input commitment points (SP1 VK has 3 IC points)
+
+**Errors**
+
+Throws a JsError error if:
+- Input JSON parsing fails (invalid structure or types)
+- Proof is not the `Groth16` variant (e.g., it's a PLONK proof)
+- Proof is empty (mock proof - not supported)
+- Hex decoding of `encoded_proof` fails
+- gnark point decompression fails (invalid curve points)
+
 ## Usage Examples
 
 ### Converting SnarkJS Proof

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@nori-zk/proof-conversion-utils",
     "type": "module",
-    "version": "0.5.0",
+    "version": "0.5.1",
     "license": "Apache-2.0",
     "publishConfig": {
       "registry": "https://registry.npmjs.org/",

package/pairing_utils.d.ts

@@ -297,9 +297,9 @@ export interface SP1PublicValues {
  * - `c`: A 12-element field value
  * - `shift_power`: "0", "1", or "2"
  *
- * # Panics
+ * # Error
  *
- * Panics if the input is not a valid Miller loop output (fails internal assertion).
+ * Returns a JsError if the input is not a valid Miller loop output (fails internal assertion).
  */
 export function compute_aux_witness(input: Field12): AuxWitness;
 

package/pairing_utils_bg.js

@@ -20,9 +20,9 @@
  * - `c`: A 12-element field value
  * - `shift_power`: "0", "1", or "2"
  *
- * # Panics
+ * # Error
  *
- * Panics if the input is not a valid Miller loop output (fails internal assertion).
+ * Returns a JsError if the input is not a valid Miller loop output (fails internal assertion).
  * @param {Field12} input
  * @returns {AuxWitness}
  */