@orbinum/proof-generator 0.3.0

package/README.md

@@ -0,0 +1,170 @@
+# Orbinum Proof Generator
+
+> High-performance ZK-SNARK proof generator for Orbinum privacy protocol
+
+[![License: Dual](https://img.shields.io/badge/License-Apache%202.0%20%7C%20GPL%203.0-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Rust](https://img.shields.io/badge/rust-1.88.0-orange.svg)](https://www.rust-lang.org/)
+
+## What is it?
+
+A hybrid TypeScript/Rust/WASM library for generating compact ZK-SNARK proofs for privacy-preserving blockchain transactions. Combines **snarkjs** (witness calculation from WASM circuits) with **Rust/arkworks** (proof generation) to produce 128-byte compressed Groth16 proofs compatible with Substrate runtime.
+
+## Features
+
+- **Fast**: ~8.5s end-to-end proof generation
+- **Compact**: 128-byte compressed proofs (50% smaller than snarkjs)
+- **Privacy**: Unshield, Private Transfer, and Disclosure circuits
+- **Type-Safe**: Full TypeScript API with comprehensive types
+- **Production Ready**: 28/28 tests passing, pre-commit hooks
+- **Auto-Build**: Rust binary compiles automatically on `npm install`
+- **WASM Support**: Browser-compatible witness calculation via Circom WASM circuits
+
+## Quick Start
+
+```bash
+npm install @orbinum/proof-generator
+```
+
+```typescript
+import { generateProof, CircuitType } from '@orbinum/proof-generator';
+
+const { proof, publicSignals } = await generateProof(CircuitType.Unshield, circuitInputs);
+// proof: 0x... (128 bytes)
+// publicSignals: ['0x...', '0x...', ...] (5 elements)
+```
+
+See [installation](docs/installation.md) for detailed setup and [usage](docs/usage.md) for complete API reference.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  Circuit Inputs (JSON)                          │
+└────────────────┬────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────┐
+│  TypeScript (snarkjs + WASM)                    │
+│  • Witness calculation from Circom WASM circuit │
+│  • ~500ms, produces 11,808 elements             │
+└────────────────┬────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────┐
+│  Rust Binary (arkworks)                         │
+│  • Groth16 proof generation from .ark key       │
+│  • ~8s, produces compressed proof               │
+└────────────────┬────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────┐
+│  Output: 128-byte proof + public signals        │
+│  • Ready for Substrate runtime submission       │
+└─────────────────────────────────────────────────┘
+```
+
+### Why Hybrid?
+
+- **Compatibility**: snarkjs handles Circom WASM circuits correctly (browser/Node.js)
+- **Efficiency**: arkworks generates compact proofs required by runtime
+- **Performance**: Rust is 20-30% faster than pure JavaScript
+- **Maintainability**: Leverages best tools from both ecosystems
+- **Flexibility**: WASM witness calculation works in any environment
+
+## Supported Circuits
+
+| Circuit        | Public Signals | Description                                   |
+| -------------- | -------------- | --------------------------------------------- |
+| **Unshield**   | 5              | Withdraw from shielded pool to public address |
+| **Transfer**   | 5              | Private transfer (2-in-2-out UTXO model)      |
+| **Disclosure** | 4              | Selective revelation for compliance           |
+
+## Requirements
+
+- **Node.js**: ≥ 22.0.0
+- **Rust**: 1.88.0 (automatically managed via `rust-toolchain.toml`)
+- **RAM**: ~2GB for proof generation
+- **Circuits**: Circuit files downloaded automatically from [circuits releases](https://github.com/orbinum/circuits/releases) during `npm install`
+
+## Project Structure
+
+```
+proof-generator/
+├── src/              # TypeScript API
+│   ├── index.ts      # Main exports
+│   ├── circuits.ts   # Circuit configs
+│   └── proof-generator.ts  # Rust binary wrapper
+├── rust/             # Rust implementation (compiled to native binary)
+│   ├── src/
+│   │   ├── lib.rs    # Core library
+│   │   └── bin/      # CLI binary
+│   └── rust-toolchain.toml
+├── pkg/              # WASM output (generated by wasm-pack build)
+│   ├── orbinum_proof_generator.js
+│   ├── orbinum_proof_generator_bg.wasm
+│   └── orbinum_proof_generator.d.ts
+├── circuits/         # ZK circuits (auto-downloaded from circuits repo)
+│   ├── *.wasm        # Circom witness calculators (used by snarkjs)
+│   └── *_pk.ark      # Proving keys in arkworks format (used by Rust)
+├── tests/            # Jest tests (28 tests)
+└── docs/
+    ├── installation.md
+    ├── usage.md
+    ├── architecture.md
+    └── testing.md
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build everything (Rust + TypeScript)
+npm run build
+
+# Run tests
+npm test
+
+# Format code
+npm run format
+```
+
+### Circuit Artifacts
+
+Circuit artifacts are automatically downloaded from [orbinum/circuits releases](https://github.com/orbinum/circuits/releases) during `npm install`.
+
+**Required files per circuit:**
+
+- `{circuit}.wasm` - Witness calculator (used by snarkjs)
+- `{circuit}_pk.ark` - Proving key in arkworks format (used by Rust)
+
+**Note:** The `.zkey` files (snarkjs format) are NOT needed since this generator uses arkworks to create proofs.
+
+**Manual configuration:**
+
+```bash
+# Specify circuits version
+export CIRCUITS_VERSION=v0.2.0
+npm install
+
+# Or download manually
+node scripts/download-artifacts.js
+```
+
+## Links
+
+- **Documentation**: [docs.orbinum.network](https://docs.orbinum.network)
+- **Main Repository**: [github.com/orbinum/node](https://github.com/orbinum/node)
+- **Issues**: [github.com/orbinum/proof-generator/issues](https://github.com/orbinum/proof-generator/issues)
+- **Circuits**: [github.com/orbinum/circuits](https://github.com/orbinum/circuits)
+
+## License
+
+This project is dual-licensed under:
+
+- **Apache License 2.0** ([LICENSE-APACHE2](LICENSE-APACHE2))
+- **GNU General Public License v3.0** ([LICENSE-GPL3](LICENSE-GPL3))
+
+You may choose either license for your use case.

package/dist/circuits.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Circuit Configuration
+ *
+ * Defines paths and metadata for all supported circuits
+ */
+import { CircuitType, CircuitConfig } from './types';
+/** Circuit configurations */
+export declare const CIRCUIT_CONFIGS: Record<CircuitType, CircuitConfig>;
+/**
+ * Get circuit configuration
+ */
+export declare function getCircuitConfig(circuitType: CircuitType): CircuitConfig;
+/**
+ * Validate that circuit artifacts exist
+ */
+export declare function validateCircuitArtifacts(config: CircuitConfig): void;

package/dist/circuits.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Circuit Configuration
+ *
+ * Defines paths and metadata for all supported circuits
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CIRCUIT_CONFIGS = void 0;
+exports.getCircuitConfig = getCircuitConfig;
+exports.validateCircuitArtifacts = validateCircuitArtifacts;
+const path = __importStar(require("path"));
+const types_1 = require("./types");
+/** Base path to circuits directory (relative to this file) */
+const CIRCUITS_BASE = path.join(__dirname, '../circuits');
+/** Circuit configurations */
+exports.CIRCUIT_CONFIGS = {
+    [types_1.CircuitType.Unshield]: {
+        name: 'unshield',
+        wasmPath: path.join(CIRCUITS_BASE, 'unshield.wasm'),
+        provingKeyPath: path.join(CIRCUITS_BASE, 'unshield_pk.ark'),
+        expectedPublicSignals: 5, // merkle_root, nullifier, amount, recipient, asset_id
+    },
+    [types_1.CircuitType.Transfer]: {
+        name: 'transfer',
+        wasmPath: path.join(CIRCUITS_BASE, 'transfer.wasm'),
+        provingKeyPath: path.join(CIRCUITS_BASE, 'transfer_pk.ark'),
+        expectedPublicSignals: 5, // merkle_root, input_nullifiers(2), output_commitments(2)
+    },
+    [types_1.CircuitType.Disclosure]: {
+        name: 'disclosure',
+        wasmPath: path.join(CIRCUITS_BASE, 'disclosure.wasm'),
+        provingKeyPath: path.join(CIRCUITS_BASE, 'disclosure_pk.ark'),
+        expectedPublicSignals: 4, // commitment, vk_hash, mask, revealed_owner_hash
+    },
+};
+/**
+ * Get circuit configuration
+ */
+function getCircuitConfig(circuitType) {
+    return exports.CIRCUIT_CONFIGS[circuitType];
+}
+/**
+ * Validate that circuit artifacts exist
+ */
+function validateCircuitArtifacts(config) {
+    const fs = require('fs');
+    if (!fs.existsSync(config.wasmPath)) {
+        throw new Error(`WASM not found: ${config.wasmPath}`);
+    }
+    if (!fs.existsSync(config.provingKeyPath)) {
+        throw new Error(`Proving key not found: ${config.provingKeyPath}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Orbinum Proof Generator
+ *
+ * Main API for generating ZK-SNARK proofs for Orbinum circuits
+ */
+import { CircuitType, CircuitInputs, ProofResult } from './types';
+/**
+ * Generate a ZK-SNARK proof for an Orbinum circuit
+ *
+ * This is the main entry point for proof generation. It:
+ * 1. Validates inputs and circuit artifacts
+ * 2. Calculates witness using snarkjs
+ * 3. Generates proof using Rust/arkworks
+ * 4. Returns compressed 128-byte proof + public signals
+ *
+ * @param circuitType - Type of circuit (Unshield, Transfer, Disclosure)
+ * @param inputs - Circuit inputs (structure depends on circuit type)
+ * @param options - Optional configuration
+ * @returns Proof result with proof hex and public signals
+ *
+ * @example
+ * ```typescript
+ * const result = await generateProof(CircuitType.Unshield, {
+ *   merkle_root: '...',
+ *   nullifier: '...',
+ *   amount: '100',
+ *   recipient: '...',
+ *   asset_id: '0',
+ *   note_value: '100',
+ *   note_asset_id: '0',
+ *   note_owner: '...',
+ *   note_blinding: '...',
+ *   spending_key: '...',
+ *   path_elements: [...],
+ *   path_indices: [...]
+ * });
+ *
+ * console.log('Proof:', result.proof); // 0x... (128 bytes)
+ * console.log('Public signals:', result.publicSignals);
+ * ```
+ */
+export declare function generateProof(circuitType: CircuitType, inputs: CircuitInputs, options?: {
+    verbose?: boolean;
+    validateArtifacts?: boolean;
+}): Promise<ProofResult>;
+/**
+ * Quick check if proof generator is ready to use
+ */
+export declare function isReady(): boolean;
+export * from './types';
+export * from './circuits';
+export { calculateWitness, calculateWitnessToFile } from './witness';
+export { generateProofFromWitness, isBinaryBuilt, getBinaryPath } from './proof-generator';
+export * from './utils';

package/dist/index.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * Orbinum Proof Generator
+ *
+ * Main API for generating ZK-SNARK proofs for Orbinum circuits
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBinaryPath = exports.isBinaryBuilt = exports.generateProofFromWitness = exports.calculateWitnessToFile = exports.calculateWitness = void 0;
+exports.generateProof = generateProof;
+exports.isReady = isReady;
+const types_1 = require("./types");
+const circuits_1 = require("./circuits");
+const witness_1 = require("./witness");
+const proof_generator_1 = require("./proof-generator");
+const utils_1 = require("./utils");
+const wasm_loader_1 = require("./wasm-loader");
+// Auto-detect environment
+const USE_WASM = (0, wasm_loader_1.isBrowser)();
+/**
+ * Generate a ZK-SNARK proof for an Orbinum circuit
+ *
+ * This is the main entry point for proof generation. It:
+ * 1. Validates inputs and circuit artifacts
+ * 2. Calculates witness using snarkjs
+ * 3. Generates proof using Rust/arkworks
+ * 4. Returns compressed 128-byte proof + public signals
+ *
+ * @param circuitType - Type of circuit (Unshield, Transfer, Disclosure)
+ * @param inputs - Circuit inputs (structure depends on circuit type)
+ * @param options - Optional configuration
+ * @returns Proof result with proof hex and public signals
+ *
+ * @example
+ * ```typescript
+ * const result = await generateProof(CircuitType.Unshield, {
+ *   merkle_root: '...',
+ *   nullifier: '...',
+ *   amount: '100',
+ *   recipient: '...',
+ *   asset_id: '0',
+ *   note_value: '100',
+ *   note_asset_id: '0',
+ *   note_owner: '...',
+ *   note_blinding: '...',
+ *   spending_key: '...',
+ *   path_elements: [...],
+ *   path_indices: [...]
+ * });
+ *
+ * console.log('Proof:', result.proof); // 0x... (128 bytes)
+ * console.log('Public signals:', result.publicSignals);
+ * ```
+ */
+async function generateProof(circuitType, inputs, options = {}) {
+    const { verbose = false, validateArtifacts = true } = options;
+    // Step 0: Initialize WASM if in browser
+    if (USE_WASM) {
+        if (verbose) {
+            console.log('🌐 Browser detected: using WASM backend');
+        }
+        await (0, wasm_loader_1.initWasm)();
+    }
+    else {
+        // Check if binary is built (Node.js only)
+        if (!(0, proof_generator_1.isBinaryBuilt)()) {
+            throw new types_1.ProofGenerationError('Rust binary not built. Run: npm run build:rust');
+        }
+    }
+    // Step 1: Get circuit config
+    const config = (0, circuits_1.getCircuitConfig)(circuitType);
+    if (!config) {
+        throw new types_1.CircuitNotFoundError(circuitType);
+    }
+    if (verbose) {
+        console.log(`\n🔐 Generating proof for circuit: ${config.name}`);
+        console.log(`   WASM: ${config.wasmPath}`);
+        console.log(`   Proving key: ${config.provingKeyPath}`);
+    }
+    // Step 2: Validate inputs
+    try {
+        (0, utils_1.validateInputs)(inputs);
+    }
+    catch (error) {
+        throw new types_1.InvalidInputsError(error.message);
+    }
+    // Step 3: Validate artifacts (optional)
+    if (validateArtifacts) {
+        try {
+            (0, circuits_1.validateCircuitArtifacts)(config);
+        }
+        catch (error) {
+            throw new types_1.CircuitNotFoundError(circuitType);
+        }
+    }
+    // Step 4: Calculate witness with snarkjs
+    if (verbose) {
+        console.log('\n📊 Step 1: Calculating witness...');
+    }
+    let witnessData;
+    try {
+        witnessData = await (0, witness_1.calculateWitness)(inputs, config.wasmPath);
+        if (verbose) {
+            console.log(`   ✅ Witness calculated: ${witnessData.witness.length} elements`);
+        }
+    }
+    catch (error) {
+        throw new types_1.WitnessCalculationError(error.message);
+    }
+    // Step 5: Generate proof (WASM or Rust binary)
+    if (verbose) {
+        console.log(`\n🔐 Step 2: Generating proof with ${USE_WASM ? 'WASM' : 'Rust/arkworks'}...`);
+    }
+    let proofResult;
+    try {
+        if (USE_WASM) {
+            // Browser: Use WASM
+            const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+            const provingKeyBytes = await fs.readFile(config.provingKeyPath);
+            const output = await (0, wasm_loader_1.generateProofWasm)(circuitType.toLowerCase(), JSON.stringify(witnessData.witness), new Uint8Array(provingKeyBytes));
+            proofResult = {
+                proof: output.proof,
+                publicSignals: output.publicSignals,
+            };
+        }
+        else {
+            // Node.js: Use Rust binary
+            proofResult = await (0, proof_generator_1.generateProofFromWitness)(witnessData, config.provingKeyPath, config.expectedPublicSignals);
+        }
+        if (verbose) {
+            console.log(`   ✅ Proof generated: ${(0, utils_1.formatProofHex)(proofResult.proof, 32)}`);
+            console.log(`   ✅ Public signals: ${proofResult.publicSignals.length}`);
+        }
+    }
+    catch (error) {
+        throw new types_1.ProofGenerationError(error.message);
+    }
+    // Step 6: Validate public signals count
+    try {
+        (0, utils_1.validatePublicSignals)(proofResult.publicSignals, config.expectedPublicSignals);
+    }
+    catch (error) {
+        throw new types_1.ProofGenerationError(error.message);
+    }
+    if (verbose) {
+        console.log('\n✅ Proof generation completed successfully!\n');
+    }
+    return {
+        proof: proofResult.proof,
+        publicSignals: proofResult.publicSignals,
+        circuitType,
+    };
+}
+/**
+ * Quick check if proof generator is ready to use
+ */
+function isReady() {
+    try {
+        // In browser, check if WASM is available
+        if (USE_WASM) {
+            // WASM gets initialized on first use
+            return true;
+        }
+        // Node.js: Check if Rust binary is built
+        if (!(0, proof_generator_1.isBinaryBuilt)()) {
+            return false;
+        }
+        // Check if at least one circuit has artifacts
+        const unshieldConfig = (0, circuits_1.getCircuitConfig)(types_1.CircuitType.Unshield);
+        (0, circuits_1.validateCircuitArtifacts)(unshieldConfig);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Re-export types and utilities for convenience
+__exportStar(require("./types"), exports);
+__exportStar(require("./circuits"), exports);
+var witness_2 = require("./witness");
+Object.defineProperty(exports, "calculateWitness", { enumerable: true, get: function () { return witness_2.calculateWitness; } });
+Object.defineProperty(exports, "calculateWitnessToFile", { enumerable: true, get: function () { return witness_2.calculateWitnessToFile; } });
+var proof_generator_2 = require("./proof-generator");
+Object.defineProperty(exports, "generateProofFromWitness", { enumerable: true, get: function () { return proof_generator_2.generateProofFromWitness; } });
+Object.defineProperty(exports, "isBinaryBuilt", { enumerable: true, get: function () { return proof_generator_2.isBinaryBuilt; } });
+Object.defineProperty(exports, "getBinaryPath", { enumerable: true, get: function () { return proof_generator_2.getBinaryPath; } });
+__exportStar(require("./utils"), exports);

package/dist/proof-generator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Proof Generation Module
+ *
+ * Uses Rust binary to generate Groth16 proofs from witness
+ */
+import { WitnessData } from './types';
+/**
+ * Generate proof using Rust/arkworks
+ *
+ * @param witnessData - Witness data (hex-encoded)
+ * @param provingKeyPath - Path to .ark proving key
+ * @param numPublicSignals - Number of public signals (optional, defaults to 5)
+ * @returns Object with proof (hex) and public signals
+ */
+export declare function generateProofFromWitness(witnessData: WitnessData, provingKeyPath: string, numPublicSignals?: number): Promise<{
+    proof: string;
+    publicSignals: string[];
+}>;
+/**
+ * Check if Rust binary is built
+ */
+export declare function isBinaryBuilt(): boolean;
+/**
+ * Get binary path (for debugging)
+ */
+export declare function getBinaryPath(): string;

package/dist/proof-generator.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Proof Generation Module
+ *
+ * Uses Rust binary to generate Groth16 proofs from witness
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateProofFromWitness = generateProofFromWitness;
+exports.isBinaryBuilt = isBinaryBuilt;
+exports.getBinaryPath = getBinaryPath;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("./utils");
+/** Path to Rust binary */
+const BINARY_PATH = path.join(__dirname, '../rust/target/release/generate-proof-from-witness');
+/**
+ * Generate proof using Rust/arkworks
+ *
+ * @param witnessData - Witness data (hex-encoded)
+ * @param provingKeyPath - Path to .ark proving key
+ * @param numPublicSignals - Number of public signals (optional, defaults to 5)
+ * @returns Object with proof (hex) and public signals
+ */
+async function generateProofFromWitness(witnessData, provingKeyPath, numPublicSignals) {
+    // Check if binary exists
+    if (!fs.existsSync(BINARY_PATH)) {
+        throw new Error(`Rust binary not found at: ${BINARY_PATH}\n` +
+            'Run: cd orbinum-proof-generator && npm run build:rust');
+    }
+    // Write witness to temp file with num_public_signals
+    const witnessJsonPath = `/tmp/witness_${Date.now()}.json`;
+    try {
+        const witnessWithMeta = {
+            ...witnessData,
+            num_public_signals: numPublicSignals,
+        };
+        fs.writeFileSync(witnessJsonPath, JSON.stringify(witnessWithMeta, null, 2));
+        // Execute Rust binary (numPublicSignals can also be passed as CLI arg)
+        const result = (0, child_process_1.execSync)(`${BINARY_PATH} ${witnessJsonPath} ${provingKeyPath}`, {
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024, // 10 MB
+            stdio: ['pipe', 'pipe', 'ignore'], // Ignore stderr to reduce noise in tests
+        });
+        // Parse output
+        const output = JSON.parse(result);
+        // Validate proof size (should be 128 bytes)
+        (0, utils_1.validateProofSize)(output.proof);
+        return {
+            proof: output.proof,
+            publicSignals: output.public_signals,
+        };
+    }
+    finally {
+        // Cleanup temp file
+        if (fs.existsSync(witnessJsonPath)) {
+            fs.unlinkSync(witnessJsonPath);
+        }
+    }
+}
+/**
+ * Check if Rust binary is built
+ */
+function isBinaryBuilt() {
+    return fs.existsSync(BINARY_PATH);
+}
+/**
+ * Get binary path (for debugging)
+ */
+function getBinaryPath() {
+    return BINARY_PATH;
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Types for Orbinum Proof Generator
+ */
+/** Circuit types supported by Orbinum */
+export declare enum CircuitType {
+    Unshield = "unshield",
+    Transfer = "transfer",
+    Disclosure = "disclosure"
+}
+/** Circuit input: any key-value pairs (circuit-specific) */
+export type CircuitInputs = Record<string, string | string[] | number | number[]>;
+/** Proof generation result */
+export interface ProofResult {
+    /** Compressed proof bytes (128 bytes as hex string) */
+    proof: string;
+    /** Public signals (circuit outputs) */
+    publicSignals: string[];
+    /** Circuit type used */
+    circuitType: CircuitType;
+}
+/** Circuit configuration */
+export interface CircuitConfig {
+    /** Circuit name (e.g., 'unshield') */
+    name: string;
+    /** Path to WASM file */
+    wasmPath: string;
+    /** Path to .ark proving key */
+    provingKeyPath: string;
+    /** Expected number of public signals */
+    expectedPublicSignals: number;
+}
+/** Witness data (hex-encoded field elements) */
+export interface WitnessData {
+    /** Array of hex-encoded witness elements (little-endian) */
+    witness: string[];
+}
+/** Error types */
+export declare class ProofGeneratorError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class WitnessCalculationError extends ProofGeneratorError {
+    constructor(message: string);
+}
+export declare class ProofGenerationError extends ProofGeneratorError {
+    constructor(message: string);
+}
+export declare class CircuitNotFoundError extends ProofGeneratorError {
+    constructor(circuitType: CircuitType);
+}
+export declare class InvalidInputsError extends ProofGeneratorError {
+    constructor(message: string);
+}

package/dist/types.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Types for Orbinum Proof Generator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidInputsError = exports.CircuitNotFoundError = exports.ProofGenerationError = exports.WitnessCalculationError = exports.ProofGeneratorError = exports.CircuitType = void 0;
+/** Circuit types supported by Orbinum */
+var CircuitType;
+(function (CircuitType) {
+    CircuitType["Unshield"] = "unshield";
+    CircuitType["Transfer"] = "transfer";
+    CircuitType["Disclosure"] = "disclosure";
+})(CircuitType || (exports.CircuitType = CircuitType = {}));
+/** Error types */
+class ProofGeneratorError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'ProofGeneratorError';
+    }
+}
+exports.ProofGeneratorError = ProofGeneratorError;
+class WitnessCalculationError extends ProofGeneratorError {
+    constructor(message) {
+        super(message, 'WITNESS_CALCULATION_FAILED');
+    }
+}
+exports.WitnessCalculationError = WitnessCalculationError;
+class ProofGenerationError extends ProofGeneratorError {
+    constructor(message) {
+        super(message, 'PROOF_GENERATION_FAILED');
+    }
+}
+exports.ProofGenerationError = ProofGenerationError;
+class CircuitNotFoundError extends ProofGeneratorError {
+    constructor(circuitType) {
+        super(`Circuit not found: ${circuitType}`, 'CIRCUIT_NOT_FOUND');
+    }
+}
+exports.CircuitNotFoundError = CircuitNotFoundError;
+class InvalidInputsError extends ProofGeneratorError {
+    constructor(message) {
+        super(message, 'INVALID_INPUTS');
+    }
+}
+exports.InvalidInputsError = InvalidInputsError;

package/dist/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Utility functions for proof generation
+ */
+/**
+ * Convert bigint to hex string (little-endian, 32 bytes)
+ */
+export declare function bigIntToHexLE(value: bigint): string;
+/**
+ * Convert witness array to hex little-endian format
+ */
+export declare function witnessToHexLE(witness: bigint[]): string[];
+/**
+ * Validate circuit inputs structure
+ */
+export declare function validateInputs(inputs: Record<string, any>): void;
+/**
+ * Format proof hex for display (truncated)
+ */
+export declare function formatProofHex(proofHex: string, maxLength?: number): string;
+/**
+ * Convert hex string to bytes
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert bytes to hex string
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Validate proof size (should be 128 bytes)
+ */
+export declare function validateProofSize(proofHex: string): void;
+/**
+ * Validate public signals count
+ */
+export declare function validatePublicSignals(signals: string[], expected: number): void;

package/dist/utils.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Utility functions for proof generation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bigIntToHexLE = bigIntToHexLE;
+exports.witnessToHexLE = witnessToHexLE;
+exports.validateInputs = validateInputs;
+exports.formatProofHex = formatProofHex;
+exports.hexToBytes = hexToBytes;
+exports.bytesToHex = bytesToHex;
+exports.validateProofSize = validateProofSize;
+exports.validatePublicSignals = validatePublicSignals;
+/**
+ * Convert bigint to hex string (little-endian, 32 bytes)
+ */
+function bigIntToHexLE(value) {
+    // Convert to hex (big-endian)
+    let hex = value.toString(16).padStart(64, '0');
+    // Reverse byte order to little-endian
+    const bytes = [];
+    for (let i = hex.length - 2; i >= 0; i -= 2) {
+        bytes.push(hex.substr(i, 2));
+    }
+    return '0x' + bytes.join('');
+}
+/**
+ * Convert witness array to hex little-endian format
+ */
+function witnessToHexLE(witness) {
+    return witness.map(w => bigIntToHexLE(w));
+}
+/**
+ * Validate circuit inputs structure
+ */
+function validateInputs(inputs) {
+    if (!inputs || typeof inputs !== 'object') {
+        throw new Error('Inputs must be an object');
+    }
+    // Check for common issues
+    for (const [key, value] of Object.entries(inputs)) {
+        if (value === undefined || value === null) {
+            throw new Error(`Input "${key}" is undefined or null`);
+        }
+    }
+}
+/**
+ * Format proof hex for display (truncated)
+ */
+function formatProofHex(proofHex, maxLength = 32) {
+    if (proofHex.length <= maxLength) {
+        return proofHex;
+    }
+    const start = proofHex.slice(0, maxLength / 2);
+    const end = proofHex.slice(-maxLength / 2);
+    return `${start}...${end}`;
+}
+/**
+ * Convert hex string to bytes
+ */
+function hexToBytes(hex) {
+    // Remove 0x prefix if present
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Convert bytes to hex string
+ */
+function bytesToHex(bytes) {
+    return ('0x' +
+        Array.from(bytes)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join(''));
+}
+/**
+ * Validate proof size (should be 128 bytes)
+ */
+function validateProofSize(proofHex) {
+    const bytes = hexToBytes(proofHex);
+    if (bytes.length !== 128) {
+        throw new Error(`Invalid proof size: expected 128 bytes, got ${bytes.length} bytes`);
+    }
+}
+/**
+ * Validate public signals count
+ */
+function validatePublicSignals(signals, expected) {
+    if (signals.length !== expected) {
+        throw new Error(`Invalid public signals count: expected ${expected}, got ${signals.length}`);
+    }
+}

package/dist/wasm-loader.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WASM loader for browser environments
+ *
+ * This module provides a browser-compatible interface for proof generation
+ * using the WASM-compiled Rust backend.
+ */
+interface WasmProofOutput {
+    proof: string;
+    publicSignals: string[];
+}
+/**
+ * Initialize WASM module (browser only)
+ */
+export declare function initWasm(): Promise<void>;
+/**
+ * Generate proof using WASM (browser only)
+ */
+export declare function generateProofWasm(circuitType: 'unshield' | 'transfer' | 'disclosure', witnessJson: string, provingKeyBytes: Uint8Array): Promise<WasmProofOutput>;
+/**
+ * Check if running in browser environment
+ */
+export declare function isBrowser(): boolean;
+export {};

package/dist/wasm-loader.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * WASM loader for browser environments
+ *
+ * This module provides a browser-compatible interface for proof generation
+ * using the WASM-compiled Rust backend.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initWasm = initWasm;
+exports.generateProofWasm = generateProofWasm;
+exports.isBrowser = isBrowser;
+let wasmModule = null;
+/**
+ * Initialize WASM module (browser only)
+ */
+async function initWasm() {
+    if (typeof globalThis.window === 'undefined') {
+        throw new Error('WASM loader is for browser use only. Use Node.js bindings in Node environment.');
+    }
+    if (wasmModule) {
+        return; // Already initialized
+    }
+    try {
+        // Dynamic import to avoid bundler issues
+        // @ts-ignore - WASM module generated at build time
+        const wasm = await Promise.resolve().then(() => __importStar(require('../pkg/orbinum_proof_generator')));
+        await wasm.default(); // Initialize WASM
+        wasm.init_panic_hook(); // Set panic hook for better errors
+        wasmModule = wasm;
+    }
+    catch (error) {
+        throw new Error(`Failed to initialize WASM module: ${error}`);
+    }
+}
+/**
+ * Generate proof using WASM (browser only)
+ */
+async function generateProofWasm(circuitType, witnessJson, provingKeyBytes) {
+    if (!wasmModule) {
+        await initWasm();
+    }
+    try {
+        const resultJson = wasmModule.generate_proof_wasm(circuitType, witnessJson, provingKeyBytes);
+        return JSON.parse(resultJson);
+    }
+    catch (error) {
+        throw new Error(`WASM proof generation failed: ${error}`);
+    }
+}
+/**
+ * Check if running in browser environment
+ */
+function isBrowser() {
+    return (typeof globalThis.window !== 'undefined' &&
+        typeof globalThis.document !== 'undefined');
+}

package/dist/witness.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Witness Generation Module
+ *
+ * Uses snarkjs to calculate witness from circuit inputs
+ */
+import { CircuitInputs, WitnessData } from './types';
+/**
+ * Calculate witness using snarkjs
+ *
+ * @param inputs - Circuit inputs (key-value pairs)
+ * @param wasmPath - Path to circuit WASM file
+ * @returns Witness data as hex-encoded strings (little-endian)
+ */
+export declare function calculateWitness(inputs: CircuitInputs, wasmPath: string): Promise<WitnessData>;
+/**
+ * Calculate witness and save to file (for debugging)
+ *
+ * @param inputs - Circuit inputs
+ * @param wasmPath - Path to circuit WASM
+ * @param outputPath - Where to save witness JSON
+ */
+export declare function calculateWitnessToFile(inputs: CircuitInputs, wasmPath: string, outputPath: string): Promise<WitnessData>;

package/dist/witness.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Witness Generation Module
+ *
+ * Uses snarkjs to calculate witness from circuit inputs
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateWitness = calculateWitness;
+exports.calculateWitnessToFile = calculateWitnessToFile;
+const snarkjs = __importStar(require("snarkjs"));
+const fs = __importStar(require("fs"));
+const utils_1 = require("./utils");
+/**
+ * Calculate witness using snarkjs
+ *
+ * @param inputs - Circuit inputs (key-value pairs)
+ * @param wasmPath - Path to circuit WASM file
+ * @returns Witness data as hex-encoded strings (little-endian)
+ */
+async function calculateWitness(inputs, wasmPath) {
+    // Temporary path for witness file
+    const wtnsPath = `/tmp/witness_${Date.now()}.wtns`;
+    try {
+        // Step 1: Calculate witness using snarkjs
+        await snarkjs.wtns.calculate(inputs, wasmPath, wtnsPath);
+        // Step 2: Export witness to JSON
+        const witnessArray = await snarkjs.wtns.exportJson(wtnsPath);
+        // Step 3: Convert to hex little-endian format
+        const witnessHex = (0, utils_1.witnessToHexLE)(witnessArray.map((w) => BigInt(w)));
+        return {
+            witness: witnessHex,
+        };
+    }
+    finally {
+        // Cleanup temporary file
+        if (fs.existsSync(wtnsPath)) {
+            fs.unlinkSync(wtnsPath);
+        }
+    }
+}
+/**
+ * Calculate witness and save to file (for debugging)
+ *
+ * @param inputs - Circuit inputs
+ * @param wasmPath - Path to circuit WASM
+ * @param outputPath - Where to save witness JSON
+ */
+async function calculateWitnessToFile(inputs, wasmPath, outputPath) {
+    const witnessData = await calculateWitness(inputs, wasmPath);
+    fs.writeFileSync(outputPath, JSON.stringify(witnessData, null, 2));
+    return witnessData;
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@orbinum/proof-generator",
+  "version": "0.3.0",
+  "description": "High-performance ZK-SNARK proof generator for Orbinum privacy protocol. Hybrid TypeScript/Rust/WASM library combining snarkjs (witness calculation) with arkworks (proof generation) to produce 128-byte compressed Groth16 proofs compatible with Substrate runtime.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "browser": "pkg/orbinum_proof_generator.js",
+  "exports": {
+    ".": {
+      "node": "./dist/index.js",
+      "browser": "./pkg/orbinum_proof_generator.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "pkg",
+    "circuits",
+    "scripts/download-artifacts.js"
+  ],
+  "author": "Orbinum",
+  "license": "GPL-3.0-or-later OR Apache-2.0",
+  "repository": {
+    "url": "https://github.com/orbinum/proof-generator"
+  },
+  "scripts": {
+    "postinstall": "tsx scripts/download-artifacts.ts || true",
+    "build": "npm run build:rust && npm run build:wasm && npm run build:ts",
+    "build:rust": "cd rust && cargo build --release",
+    "build:wasm": "cd rust && wasm-pack build --target web --out-dir ../pkg --features wasm",
+    "build:ts": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:verbose": "jest --verbose",
+    "test:unshield": "jest unshield",
+    "test:transfer": "jest transfer",
+    "test:disclosure": "jest disclosure",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "lint": "tsc --noEmit",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build:ts && npm run lint && npm test",
+    "clean": "rm -rf dist pkg circuits node_modules && cd rust && cargo clean",
+    "release": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags"
+  },
+  "keywords": [
+    "zksnark",
+    "groth16",
+    "circom",
+    "snarkjs",
+    "arkworks",
+    "privacy",
+    "zk-proof",
+    "orbinum"
+  ],
+  "dependencies": {
+    "snarkjs": "0.7.5"
+  },
+  "devDependencies": {
+    "@types/circomlibjs": "0.1.6",
+    "@types/jest": "29.5.14",
+    "@types/node": "22.10.5",
+    "@types/snarkjs": "0.7.9",
+    "@types/tar": "6.1.13",
+    "circomlibjs": "0.1.7",
+    "husky": "9.1.7",
+    "jest": "29.7.0",
+    "lint-staged": "15.2.11",
+    "prettier": "3.4.2",
+    "ts-jest": "29.2.5",
+    "tsx": "^4.21.0",
+    "typescript": "5.7.3",
+    "wasm-pack": "0.14.0"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "prettier --write",
+      "tsc --noEmit"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}