feat(convert-vk): add VK JSON → arkworks binary converter

.github/workflows/release.yml

@@ -29,10 +29,8 @@ jobs:
               with:
                   cache-directories: target
 
-            - name: Install wasm-pack and cargo-release
-              run: |
-                  cargo install wasm-pack
-                  cargo install cargo-release
+            - name: Install wasm-pack
+              run: cargo install wasm-pack
 
             - name: Extract version from Cargo.toml
               id: version
@@ -53,28 +51,16 @@ jobs:
                     echo "✅ Tag v${{ steps.version.outputs.version }} does not exist, proceeding"
                   fi
 
-            - name: Configure git for cargo-release
+            - name: Configure git for tagging
               if: steps.check_tag.outputs.exists == 'false'
               run: |
                   git config user.name "github-actions[bot]"
                   git config user.email "github-actions[bot]@users.noreply.github.com"
 
-            - name: Update CHANGELOG with cargo-release
-              if: steps.check_tag.outputs.exists == 'false'
-              run: |
-                  # cargo-release will update CHANGELOG, commit, and tag
-                  cargo release ${{ steps.version.outputs.version }} \
-                    --execute \
-                    --no-confirm \
-                    --no-publish \
-                    --no-push
-              env:
-                  CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-
-            - name: Push changes and tags
+            - name: Create and push tag
               if: steps.check_tag.outputs.exists == 'false'
               run: |
-                  git push origin main
+                  git tag v${{ steps.version.outputs.version }}
                   git push origin v${{ steps.version.outputs.version }}
 
             - name: Build WASM for release

CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [2.1.0](https://github.com/orbinum/groth16-proofs/releases/tag/v2.1.0) - 2026-04-07
+
+### Added
+- `convert-vk` binary: converts a snarkjs `verification_key_*.json` to a
+  ~424-byte arkworks compressed binary (via `CanonicalSerialize::serialize_compressed`).
+  Required for on-chain VK registration — the runtime `ArkVK::deserialize_compressed()`
+  expects binary format, not raw JSON bytes.
+
+### Changed
+- `Makefile` `build` target now builds both `generate-proof-from-witness` and `convert-vk`.
+- Docs updated (`installation.md`, `usage.md`, `witness-formats.md`) to document the
+  current proof flows: CDN WASM init, snarkjs → `compress_snarkjs_proof_wasm` primary
+  path, and `convert-vk` VK registration workflow.
+- CHANGELOG is now maintained manually; removed `cargo-release` from the release workflow.
+
 ## [2.0.0](https://github.com/orbinum/groth16-proofs/releases/tag/v2.0.0) - 2026-02-16
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "groth16-proofs"
-version = "2.0.0"
+version = "2.1.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"
@@ -20,6 +20,14 @@ wasm-opt = true
 name = "generate-proof-from-witness"
 path = "src/bin/generate-proof-from-witness.rs"
 
+[[bin]]
+name = "bench-groth16"
+path = "src/bin/bench_groth16.rs"
+
+[[bin]]
+name = "convert-vk"
+path = "src/bin/convert_vk.rs"
+
 [dependencies]
 # Arkworks dependencies
 ark-bn254 = "0.5.0"

Makefile

@@ -53,9 +53,10 @@ check: fmt-check lint ## Check code quality (fmt + clippy)
 
 # Build native binary
 build: ## Build native binary (release)
-	@echo "$(BLUE)Building native binary...$(NC)"
+	@echo "$(BLUE)Building native binaries...$(NC)"
 	cargo build --release
-	@echo "$(GREEN)✓ Binary: ./target/release/generate-proof-from-witness$(NC)"
+	@echo "$(GREEN)✓ generate-proof-from-witness: ./target/release/generate-proof-from-witness$(NC)"
+	@echo "$(GREEN)✓ convert-vk:                  ./target/release/convert-vk$(NC)"
 
 build-debug: ## Build native binary (debug)
 	@echo "$(BLUE)Building native binary (debug)...$(NC)"

docs/installation.md

@@ -35,22 +35,19 @@ Install from npm:
 npm install @orbinum/groth16-proofs
 ```
 
-You can also download precompiled binaries from [GitHub Releases](https://github.com/orbinum/groth16-proofs/releases).
-
-1. Download `orb-groth16-proof.tar.gz` from the latest release (optional)
-2. Extract to your project (optional):
-```bash
-tar -xzf orb-groth16-proof.tar.gz -C ./wasm
-```
-
-3. Import in TypeScript/JavaScript:
+Import in TypeScript/JavaScript:
 
 ```typescript
-import { generate_proof_from_decimal_wasm } from './wasm/groth16_proofs.js';
+import init, { compress_snarkjs_proof_wasm } from '@orbinum/groth16-proofs';
+import groth16pkg from '@orbinum/groth16-proofs/package.json';
+
+// Initialize WASM from CDN (recommended — no bundling required)
+const WASM_CDN = `https://unpkg.com/@orbinum/groth16-proofs@${groth16pkg.version}/groth16_proofs_bg.wasm`;
+await init(WASM_CDN);
 
-// numPublicSignals depends on your circuit (check your circuit definition)
-const numPublicSignals = 5;
-const result = generate_proof_from_decimal_wasm(numPublicSignals, witnessJson, provingKeyBytes);
+// Convert snarkjs proof to on-chain arkworks format (128 bytes)
+const compressed = compress_snarkjs_proof_wasm(JSON.stringify(snarkjsProof));
+// compressed => "0x..." (128 bytes)
 ```
 
 ### Development Installation
@@ -72,11 +69,13 @@ wasm-pack --version
 
 ## Building from Source
 
-### Native Binary
+### Native Binaries
 
 ```bash
 make build
-# Output: ./target/release/generate-proof-from-witness
+# Outputs:
+#   ./target/release/generate-proof-from-witness  (Rust-native proof generation)
+#   ./target/release/convert-vk                   (VK JSON → arkworks binary)
 ```
 
 ### WASM Module
@@ -100,14 +99,17 @@ make build-all
 
 ```bash
 cargo build --release
+# Proof generation
 ./target/release/generate-proof-from-witness witness.json proving_key.ark
+# VK format conversion (snarkjs JSON → on-chain arkworks binary)
+./target/release/convert-vk verification_key_unshield.json verification_key_unshield.bin
 ```
 
 **Advantages**:
 - ✅ Fastest proof generation (5-8 seconds)
 - ✅ Direct file I/O access
 - ✅ Deterministic randomness (testable)
-- ✅ Minimal dependencies
+- ✅ `convert-vk` produces 424-byte arkworks binary required by on-chain verifier
 
 ### WASM
 
@@ -139,15 +141,21 @@ Once installed, see the **[Usage Guide](./usage.md)** for:
 **Minimal example**:
 
 ```rust
-// Rust
+// Rust — native proof generation
 use groth16_proofs::generate_proof_from_witness;
-let proof = generate_proof_from_witness(&witness, "key.ark")?;
+let proof = generate_proof_from_witness(&witness_hex, "key.ark")?;
+```
+
+```bash
+# CLI — convert VK for on-chain registration
+./target/release/convert-vk verification_key_unshield.json verification_key_unshield.bin
 ```
 
 ```typescript
-// WASM
-import { generate_proof_from_decimal_wasm } from './wasm/groth16_proofs.js';
-const result = generate_proof_from_decimal_wasm(numPublicSignals, witnessJson, keyBytes);
+// WASM — compress snarkjs proof to on-chain format
+import init, { compress_snarkjs_proof_wasm } from '@orbinum/groth16-proofs';
+await init(WASM_CDN);
+const compressed = compress_snarkjs_proof_wasm(JSON.stringify(snarkjsProof));
 ```
 
 ## Configuration
@@ -182,10 +190,13 @@ make install-tools
 
 ### WASM bundle too large
 
-The WASM module is ~3-5 MB (compressed ~1 MB). Consider:
-- Serving over gzip/brotli compression
-- Using code splitting for lazy loading
-- Pre-generating proofs server-side (native)
+The WASM module is ~3-5 MB (compressed ~1 MB). Load from CDN instead of bundling:
+
+```typescript
+import groth16pkg from '@orbinum/groth16-proofs/package.json';
+const WASM_CDN = `https://unpkg.com/@orbinum/groth16-proofs@${groth16pkg.version}/groth16_proofs_bg.wasm`;
+await init(WASM_CDN); // does not bundle the .wasm into your JS bundle
+```
 
 ### Proof generation is slow