refactor(groth16-proofs): clean architecture, unified error type, shared prover core

.github/workflows/ci.yml

@@ -1,8 +1,6 @@
 name: CI
 
 on:
-  push:
-    branches: [main, develop]
   pull_request:
     branches: [main, develop]
 

CHANGELOG.md

@@ -5,6 +5,70 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0](https://github.com/orbinum/groth16-proofs/releases/tag/v3.0.0) - 2026-04-08
+
+### Added
+
+- `ProofError` — unified error enum replacing `String` errors throughout the crate.
+  Variants: `WitnessEmpty`, `WitnessConversion`, `ProvingKeyIo`, `ProvingKeyParse`,
+  `ProveGeneration`, `ProofSerialization`, `NumPublicSignals`, `WitnessJsonParse`,
+  `SnarkjsProofParse`.
+- `from_decimal_str::<F>()` — generic `PrimeField` parser for decimal strings,
+  replaces the `Bn254Fr`-only `decimal_to_field()` with a type-parameterized version
+  usable for any field (`Fr`, `Fq`, etc.).
+- `from_hex_le::<F>()` — generic `PrimeField` parser for little-endian hex strings,
+  replaces the `Bn254Fr`-only `hex_to_field()`.
+- `prove_from_witness()` — core prover function shared by the native and WASM paths.
+  Accepts already-loaded `pk_bytes` and a converted witness; eliminates code duplication
+  that existed between `proof.rs` and `wasm.rs`.
+- `compress_snarkjs_proof()` — native (non-WASM) snarkjs proof compression, available
+  for server-side Rust code (previously only exposed as `compress_snarkjs_proof_wasm`).
+- New `src/codec.rs` module: snarkjs JSON → arkworks compressed bytes, decoupled from
+  the `wasm` feature.
+- New `src/prover.rs` module: core Groth16 prove logic with input validation.
+- New `src/field.rs` module: generic field element parsers.
+- New `src/error.rs` module: `ProofError` type.
+- `decimal_to_field()` and `hex_to_field()` remain as backward-compat shims in
+  `src/utils.rs` (thin wrappers over the new generic functions).
+
+### Changed
+
+- **BREAKING**: `generate_proof_from_witness()` signature changed — now requires an
+  explicit `num_public_signals: usize` third argument.
+  ```rust
+  // Before (2.x)
+  generate_proof_from_witness(&witness_hex, "key.ark")
+  // After (3.0)
+  generate_proof_from_witness(&witness_hex, "key.ark", 5)
+  ```
+- **BREAKING**: `generate_proof_from_witness()` now returns `Result<Vec<u8>, ProofError>`
+  instead of `Result<Vec<u8>, String>`.
+- **BREAKING**: `prove_from_witness()` (new public function) also returns `ProofError`;
+  callers that previously matched on `String` errors must switch to `ProofError` variants.
+- `WitnessCircuit` struct: `num_public_signals` is now an explicit field instead of
+  being computed from a heuristic `(witness.len() / 100).clamp(1, 10)` — which produced
+  wrong public signal counts for `disclosure` (got 1, expected 4) and `transfer`
+  (got 10, expected 5).
+- `src/wasm.rs` rewritten as a thin wrapper using `prove_from_witness()`; no duplicated
+  prove logic.
+- `src/wasm/snarkjs_proof.rs` rewritten as a 9-line WASM binding delegating to
+  `codec::compress_snarkjs_proof()`.
+- `bench-groth16` binary: accepts optional `[num_public=5]` sixth argument.
+- `generate-proof-from-witness` binary: `num_public_signals` derived from CLI arg,
+  JSON field, or default — no longer heuristic.
+- Removed stale `#!/usr/bin/env rust` shebang from `generate-proof-from-witness` source.
+- Removed trivial tautological test (`assert_eq!(128, 128)`) in `proof.rs`.
+- Docs updated: `installation.md`, `usage.md`, `witness-formats.md` reflect new API,
+  `ProofError` variants, generic `from_decimal_str`/`from_hex_le`, and correct
+  `num_public_signals` semantics.
+
+### Fixed
+
+- **Bug**: `WitnessCircuit::generate_constraints` used `(witness.len() / 100).clamp(1,10)`
+  as a heuristic for `num_public_signals`. For `disclosure` (4 public signals, ~1171
+  witness elements) this produced 1; for `transfer` (5 public signals, ~11,808 elements)
+  this produced 10. Fixed by requiring callers to pass the exact value.
+
 ## [2.1.0](https://github.com/orbinum/groth16-proofs/releases/tag/v2.1.0) - 2026-04-07
 
 ### Added
@@ -73,7 +137,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Makefile with development commands
 - CHANGELOG following Keep a Changelog format
 
-[Unreleased]: https://github.com/orbinum/groth16-proofs/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/orbinum/groth16-proofs/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/orbinum/groth16-proofs/releases/tag/v3.0.0
+[2.1.0]: https://github.com/orbinum/groth16-proofs/releases/tag/v2.1.0
 [2.0.0]: https://github.com/orbinum/groth16-proofs/releases/tag/v2.0.0
 [1.0.0]: https://github.com/orbinum/groth16-proofs/releases/tag/v1.0.0
 [0.1.0]: https://github.com/orbinum/groth16-proofs/releases/tag/v0.1.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "groth16-proofs"
-version = "2.1.0"
+version = "3.0.0"
 edition = "2021"
 license = "Apache-2.0 OR GPL-3.0-or-later"
 description = "High-performance Groth16 proof generator using arkworks for Orbinum privacy protocol"

README.md

@@ -20,7 +20,7 @@ npm install @orbinum/groth16-proofs
 **Rust** (Native binary):
 ```toml
 [dependencies]
-groth16-proofs = "2.0"
+groth16-proofs = "2.2"
 ```
 
 ### Use
@@ -63,7 +63,7 @@ let proof = generate_proof_from_witness(&witness, "proving_key.ark")?;
 
 This crate generates **128-byte compressed Groth16 proofs** from witness data using the arkworks library. It supports:
 
-- **Performance**: ~5-8 seconds per proof
+- **Performance**: ~1.6–1.8s WASM (small circuits, post-warmup); native Rust faster
 - **Curves**: BN254 (Ethereum-compatible)
 - **Targets**: Native (Rust) + WebAssembly
 - **Circuits**: Unshield, Transfer, Disclosure
@@ -115,7 +115,7 @@ canonical compressed proof bytes (`0x...`, 128 bytes).
 ## Features
 
 ✅ **Multiple Targets**: Native + WASM  
-✅ **Fast**: 5-8 second proof generation  
+✅ **Fast**: ~1.6–1.8s WASM (post-warmup); native Rust faster  
 ✅ **WASM Decimal-Only API**: Direct snarkjs witness input  
 ✅ **Type-Safe**: Memory-safe cryptography  
 ✅ **Well-Tested**: 21+ tests included  
@@ -143,18 +143,6 @@ See [Makefile](./Makefile) for all available targets.
 - [**Witness Formats**](./docs/witness-formats.md) - Decimal witness flow and format notes
 - [**Release Process**](./docs/release.md) - How releases are managed
 
-## Performance
-
-| Metric | Value |
-|--------|-------|
-| Proof Size | 128 bytes (compressed) |
-| Generation Time | 5-8 seconds |
-| Curve | BN254 |
-| WASM Bundle | 3-5 MB |
-| Native Binary | 10-15 MB |
-
-**Native is 20-30% faster than WASM**. Choose based on your deployment target.
-
 ## Publishing
 
 This crate is published to both registries:

docs/installation.md

@@ -16,15 +16,15 @@ Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-groth16-proofs = "2.0"
+groth16-proofs = "3.0"
 ```
 
 Then import in your code:
 
 ```rust
 use groth16_proofs::generate_proof_from_witness;
 
-let proof = generate_proof_from_witness(&witness, "proving_key.ark")?;
+let proof = generate_proof_from_witness(&witness, "proving_key.ark", 5)?;;
 ```
 
 ### As a WASM Module
@@ -143,7 +143,7 @@ Once installed, see the **[Usage Guide](./usage.md)** for:
 ```rust
 // Rust — native proof generation
 use groth16_proofs::generate_proof_from_witness;
-let proof = generate_proof_from_witness(&witness_hex, "key.ark")?;
+let proof = generate_proof_from_witness(&witness_hex, "key.ark", 5)?;
 ```
 
 ```bash
@@ -169,12 +169,12 @@ The crate supports feature-based compilation:
 wasm = ["wasm-bindgen", "console_error_panic_hook"]
 ```
 
-**Build without WASM support**:
+**Build without WASM support** (default — `features = []`):
 ```bash
-cargo build --release --no-default-features
+cargo build --release
 ```
 
-**Build with WASM support** (default):
+**Build with WASM support**:
 ```bash
 cargo build --release --features wasm
 ```