@izi-noir/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Franco Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+# @izi-noir/sdk
+
+> Privacy for Solana in one SDK
+
+Write ZK circuits in JavaScript, generate proofs in the browser, verify on Solana. No cryptography PhD required.
+
+## Why IZI-NOIR?
+
+**Traditional ZK workflow (4+ tools, new language):**
+```
+Write .nr file → nargo compile → nargo execute → bb prove → bb write_verifier → Deploy manually
+```
+
+**IZI-NOIR workflow (one SDK, JavaScript):**
+```
+Write JS function → izi.createProof() → izi.proveForSolana() → builder.deploy() → Done
+```
+
+| Traditional Noir | IZI-NOIR |
+|-----------------|----------|
+| Learn a new language | Write JavaScript you know |
+| 4+ CLI tools | One SDK |
+| Manual deployment | Automated helpers |
+| Complex setup | `npm install` and go |
+
+## Installation
+
+```bash
+npm install @izi-noir/sdk
+```
+
+## Quick Start
+
+### 1. Write a Circuit in JavaScript
+
+```typescript
+import { IziNoir, Provider } from '@izi-noir/sdk';
+
+const izi = await IziNoir.init({ provider: Provider.Arkworks });
+
+// Write your circuit as a JavaScript function
+await izi.compile(`
+  fn main(secret: Field, expected: pub Field) {
+    assert(secret * secret == expected);
+  }
+`);
+
+// Or use the transpiler (JS → Noir → compile)
+const result = await createProof(
+  [100],           // public inputs (what everyone sees)
+  [10],            // private inputs (your secret)
+  ([expected], [secret]) => {
+    assert(secret * secret == expected);  // Prove you know the square root
+  }
+);
+
+console.log('Verified:', result.verified);
+```
+
+### 2. Generate Solana-Ready Proofs
+
+```typescript
+const solanaProof = await izi.proveForSolana({
+  secret: '10',
+  expected: '100'
+});
+
+// 256-byte proof ready for on-chain verification
+console.log('Proof size:', solanaProof.proof.bytes.length, 'bytes');
+console.log('Estimated rent:', solanaProof.estimatedRent, 'lamports');
+```
+
+### 3. Deploy and Verify On-Chain
+
+```typescript
+import { SolanaTransactionBuilder } from '@izi-noir/sdk';
+
+const builder = new SolanaTransactionBuilder({ computeUnits: 400_000 });
+
+// Build transactions for your wallet adapter
+const { initVk, verifyProof, computeBudget } = builder.buildInitAndVerifyInstructions(
+  solanaProof,
+  vkKeypair.publicKey.toBase58(),
+  wallet.publicKey.toBase58(),
+  wallet.publicKey.toBase58()
+);
+
+// Send with your preferred wallet adapter
+await sendTransaction([computeBudget, initVk, verifyProof]);
+```
+
+## Full Workflow Examples
+
+### Age Verification (Prove you're over 18 without revealing your age)
+
+```typescript
+import { IziNoir, Provider, CircuitRegistry, VkDeploymentManager } from '@izi-noir/sdk';
+
+// 1. Register your circuit
+const registry = new CircuitRegistry();
+registry.register({
+  name: 'age-check',
+  version: '1.0.0',
+  description: 'Proves age >= minimum without revealing actual age',
+  jsCircuit: ([minAge], [birthYear, currentYear]) => {
+    assert(currentYear - birthYear >= minAge);
+  },
+  publicInputs: [{ name: 'minAge', type: 'Field', description: 'Minimum age required' }],
+  privateInputs: [
+    { name: 'birthYear', type: 'Field', description: 'Year of birth' },
+    { name: 'currentYear', type: 'Field', description: 'Current year' }
+  ],
+});
+
+// 2. Create a proof
+const izi = await IziNoir.init({ provider: Provider.Arkworks });
+const circuit = registry.get('age-check');
+
+await izi.compile(`
+  fn main(minAge: pub Field, birthYear: Field, currentYear: Field) {
+    assert(currentYear - birthYear >= minAge);
+  }
+`);
+
+const proof = await izi.proveForSolana({
+  minAge: '18',
+  birthYear: '1990',
+  currentYear: '2024'
+});
+
+// 3. Deploy to Solana
+const deploymentManager = new VkDeploymentManager({
+  network: 'devnet',
+});
+
+const deployment = await deploymentManager.ensureDeployed({
+  circuitName: 'age-check',
+  solanaProofData: proof,
+  authority: wallet.publicKey.toBase58(),
+  payer: wallet.publicKey.toBase58(),
+  sendTransaction: async (instructions, signers) => {
+    // Your wallet adapter logic here
+    return txSignature;
+  },
+});
+
+console.log('VK deployed at:', deployment.vkAccount);
+```
+
+### Backend API Verification (Off-chain)
+
+```typescript
+import express from 'express';
+import { OffchainVerifier, createVerifierMiddleware } from '@izi-noir/sdk';
+
+const app = express();
+app.use(express.json());
+
+// Create verifier with your compiled circuit
+const verifier = new OffchainVerifier({
+  verifier: async (circuit, proof, publicInputs) => {
+    // Use your proving system's verify method
+    return await provingSystem.verify(circuit, proof, publicInputs);
+  }
+});
+
+// Register circuits
+await verifier.registerCircuit('api-auth', {
+  jsCircuit: ([apiKeyHash], [apiKey]) => {
+    // In real use, you'd hash the apiKey and compare
+    assert(apiKey == apiKeyHash);
+  }
+});
+
+// Add verification endpoint
+app.post('/verify', createVerifierMiddleware(verifier));
+
+// Client sends: { circuitName: 'api-auth', proof: '0x...', publicInputs: [12345] }
+// Server responds: { verified: true, verificationTimeMs: 42 }
+```
+
+## Proving Backends
+
+| Provider | Proof Size | Environment | Best For |
+|----------|------------|-------------|----------|
+| **Arkworks** | ~256 bytes | Browser + Node.js | Solana on-chain verification |
+| **Barretenberg** | ~16 KB | Browser + Node.js | Development, fast iteration |
+| **Sunspot** | ~324 bytes | Node.js only | Pre-compiled production circuits |
+
+### Arkworks (Recommended for Solana)
+
+Groth16 proofs that fit in a single Solana transaction.
+
+```typescript
+const izi = await IziNoir.init({ provider: Provider.Arkworks });
+const solanaProof = await izi.proveForSolana(inputs);
+// solanaProof.proof.bytes.length === 256
+```
+
+### Barretenberg (Development)
+
+Faster proving, larger proofs. Great for testing.
+
+```typescript
+const izi = await IziNoir.init({ provider: Provider.Barretenberg });
+const { proof, verified } = await izi.createProof(noirCode, inputs);
+```
+
+## New APIs
+
+### SolanaTransactionBuilder
+
+Build Solana transactions without Anchor dependency.
+
+```typescript
+import { SolanaTransactionBuilder } from '@izi-noir/sdk';
+
+const builder = new SolanaTransactionBuilder({
+  programId: 'EYhRED7EuMyyVjx57aDXUD9h6ArnEKng64qtz8999KrS', // optional
+  computeUnits: 400_000,
+  priorityFee: 1000, // microLamports per CU
+});
+
+// Build individual instructions
+const initInstruction = builder.buildInitVkInstruction(solanaProof, {
+  vkAccount: vkPubkey,
+  authority: authorityPubkey,
+  payer: payerPubkey,
+});
+
+const verifyInstruction = builder.buildVerifyProofInstruction(
+  solanaProof.proof.bytes,
+  solanaProof.publicInputs.bytes,
+  { vkAccount: vkPubkey }
+);
+
+// Or build everything at once
+const { initVk, verifyProof, computeBudget, rentLamports } =
+  builder.buildInitAndVerifyInstructions(
+    solanaProof,
+    vkPubkey,
+    authorityPubkey,
+    payerPubkey
+  );
+```
+
+### VkDeploymentManager
+
+Idempotent deployment with local persistence.
+
+```typescript
+import { VkDeploymentManager } from '@izi-noir/sdk';
+
+const manager = new VkDeploymentManager({
+  network: 'devnet',
+  configDir: './.izi-noir', // stores deployment state
+});
+
+// Won't redeploy if same circuit already deployed
+const result = await manager.ensureDeployed({
+  circuitName: 'my-circuit',
+  solanaProofData,
+  authority: wallet.publicKey.toBase58(),
+  payer: wallet.publicKey.toBase58(),
+  sendTransaction: myWalletSendFn,
+});
+
+if (result.deployed) {
+  console.log('Deployed new VK:', result.vkAccount);
+} else {
+  console.log('Using existing VK:', result.vkAccount);
+}
+
+// Save state for next time
+await manager.save();
+```
+
+### CircuitRegistry
+
+Name, version, and document your circuits.
+
+```typescript
+import { CircuitRegistry, defineCircuit } from '@izi-noir/sdk';
+
+const registry = new CircuitRegistry();
+
+// Full registration
+registry.register({
+  name: 'balance-proof',
+  version: '1.0.0',
+  description: 'Proves balance >= threshold',
+  jsCircuit: ([threshold], [balance]) => { assert(balance >= threshold); },
+  publicInputs: [{ name: 'threshold', type: 'Field' }],
+  privateInputs: [{ name: 'balance', type: 'Field' }],
+  tags: ['finance', 'defi'],
+  author: 'Your Name',
+});
+
+// Quick registration with defineCircuit
+const circuit = defineCircuit(
+  { name: 'quick-check', version: '1.0.0', publicInputs: [], privateInputs: [] },
+  ([], [secret]) => { assert(secret != 0); }
+);
+
+// Lookup
+const myCircuit = registry.get('balance-proof');
+const allVersions = registry.getVersions('balance-proof');
+const financeCircuits = registry.findByTag('finance');
+
+// Generate docs
+console.log(registry.generateDocs('balance-proof'));
+```
+
+### OffchainVerifier
+
+Verify proofs without blockchain transactions.
+
+```typescript
+import { OffchainVerifier, batchVerify } from '@izi-noir/sdk';
+
+const verifier = new OffchainVerifier({
+  compiler: async (jsCircuit) => { /* compile circuit */ },
+  verifier: async (circuit, proof, publicInputs) => { /* verify */ return true; },
+});
+
+// Single verification
+const result = await verifier.verify({
+  circuitName: 'my-circuit',
+  proof: proofBytes,
+  publicInputs: [123, 456],
+});
+
+// Batch verification
+const batchResult = await batchVerify(verifier, [
+  { circuitName: 'circuit-a', proof: proof1, publicInputs: [1] },
+  { circuitName: 'circuit-b', proof: proof2, publicInputs: [2] },
+]);
+
+console.log(`Verified: ${batchResult.verifiedCount}/${batchResult.results.length}`);
+```
+
+## Writing Circuit Functions
+
+### Function Signature
+
+```typescript
+([public1, public2, ...], [private1, private2, ...]) => {
+  // assertions here
+}
+```
+
+- **Public inputs**: Values everyone can see (e.g., minimum age requirement)
+- **Private inputs**: Your secret values (e.g., actual birth year)
+
+### Supported Operations
+
+| JavaScript | Noir | Notes |
+|------------|------|-------|
+| `assert(cond)` | `assert(cond)` | Core constraint |
+| `==` / `===` | `==` | Equality |
+| `+`, `-`, `*`, `/`, `%` | Same | Arithmetic |
+| `<`, `>`, `<=`, `>=` | Same | Comparison |
+| `let x = 5` | `let x: Field = 5` | Immutable |
+| `let mut_x = 5` | `let mut x: Field = 5` | Mutable (use `mut_` prefix) |
+| `if/else` | Same | Conditionals |
+| `for (let i=0; i<n; i++)` | Same | Fixed-bound loops |
+| `[a, b, c]` | `[Field; 3]` | Fixed-size arrays |
+
+### Examples
+
+**Simple equality:**
+```typescript
+([expected], [secret]) => { assert(secret == expected); }
+```
+
+**Range proof:**
+```typescript
+([min, max], [value]) => {
+  assert(value >= min);
+  assert(value <= max);
+}
+```
+
+**Sum verification:**
+```typescript
+([sum], [a, b, c]) => {
+  let arr = [a, b, c];
+  let mut_total = 0;
+  for (let i = 0; i < 3; i++) {
+    mut_total = mut_total + arr[i];
+  }
+  assert(mut_total == sum);
+}
+```
+
+## Browser Usage (Vite)
+
+```typescript
+import initNoirC from "@noir-lang/noirc_abi";
+import initACVM from "@noir-lang/acvm_js";
+import acvm from "@noir-lang/acvm_js/web/acvm_js_bg.wasm?url";
+import noirc from "@noir-lang/noirc_abi/web/noirc_abi_wasm_bg.wasm?url";
+import { IziNoir, Provider, markWasmInitialized } from "@izi-noir/sdk";
+
+// Initialize WASM first
+await Promise.all([initACVM(fetch(acvm)), initNoirC(fetch(noirc))]);
+markWasmInitialized();
+
+// Now use IziNoir
+const izi = await IziNoir.init({ provider: Provider.Arkworks });
+```
+
+## Type Reference
+
+### SolanaProofData
+
+```typescript
+interface SolanaProofData {
+  verifyingKey: {
+    base64: string;
+    bytes: Uint8Array;
+    nrPublicInputs: number;
+  };
+  proof: {
+    base64: string;
+    bytes: Uint8Array;  // Always 256 bytes
+  };
+  publicInputs: {
+    hex: string[];
+    bytes: Uint8Array[];  // 32-byte big-endian field elements
+  };
+  accountSize: number;
+  estimatedRent: number;  // Lamports for VK account
+}
+```
+
+### InstructionData
+
+```typescript
+interface InstructionData {
+  data: Uint8Array;
+  programId: string;
+  keys: Array<{
+    pubkey: string;
+    isSigner: boolean;
+    isWritable: boolean;
+  }>;
+}
+```
+
+## Requirements
+
+- Node.js 22.12.0+
+- For Solana deployment: Solana CLI + Anchor CLI
+
+## License
+
+MIT

package/dist/IProvingSystem-D9TnEig0.d.ts

@@ -0,0 +1,140 @@
+import { CompiledCircuit, InputMap } from '@noir-lang/types';
+import { P as ProofData } from './types-CaaigonG.js';
+
+/**
+ * Chain types for multi-chain proof formatting
+ */
+/**
+ * Supported blockchain targets for proof verification
+ */
+type ChainId = 'solana' | 'ethereum';
+/**
+ * Chain enum for IziNoir initialization.
+ * Use undefined (don't pass chain) for offchain mode.
+ */
+declare enum Chain {
+    /** Solana blockchain - uses Groth16 proofs with gnark format VK */
+    Solana = "solana",
+    /** Ethereum blockchain - uses Groth16 proofs (future support) */
+    Ethereum = "ethereum"
+}
+/**
+ * Metadata about the compiled circuit
+ */
+interface CircuitMetadata {
+    /** Number of public inputs in the circuit */
+    numPublicInputs: number;
+    /** Optional circuit name for identification */
+    circuitName?: string;
+}
+/**
+ * Base interface for chain-specific metadata
+ */
+interface ChainMetadata {
+    chainId: ChainId;
+}
+/**
+ * Solana-specific metadata for VK account sizing and rent
+ */
+interface SolanaChainMetadata extends ChainMetadata {
+    chainId: 'solana';
+    /** Size of the VK account in bytes */
+    accountSize: number;
+    /** Estimated rent-exempt balance in lamports */
+    estimatedRent: number;
+}
+/**
+ * Ethereum-specific metadata (future)
+ */
+interface EthereumChainMetadata extends ChainMetadata {
+    chainId: 'ethereum';
+    /** Estimated gas for verification */
+    estimatedGas: bigint;
+}
+/**
+ * Type helper to get chain-specific metadata
+ */
+type ChainMetadataFor<T extends ChainId> = T extends 'solana' ? SolanaChainMetadata : T extends 'ethereum' ? EthereumChainMetadata : ChainMetadata;
+
+/**
+ * Available proving system providers
+ */
+declare enum Provider {
+    /** Barretenberg backend - browser compatible, UltraHonk proofs (~16KB) */
+    Barretenberg = "barretenberg",
+    /** Arkworks WASM backend - browser compatible, Groth16 proofs (~256 bytes) */
+    Arkworks = "arkworks",
+    /** Sunspot CLI backend - Node.js only, Groth16 proofs (~256 bytes) */
+    Sunspot = "sunspot"
+}
+/**
+ * Configuration for circuit paths (required for Sunspot)
+ */
+interface CircuitPaths {
+    /** Path to the proving key file */
+    pkPath: string;
+    /** Path to the verification key file */
+    vkPath: string;
+    /** Path to the compiled circuit JSON file */
+    circuitPath: string;
+}
+/**
+ * Configuration for IziNoir initialization
+ */
+interface IziNoirConfig {
+    /** The proving system provider to use */
+    provider: Provider;
+    /**
+     * Target blockchain for proof formatting.
+     * If omitted, operates in offchain mode (raw proofs, no chain formatting).
+     */
+    chain?: Chain;
+    /** Circuit paths - required for Sunspot provider */
+    circuitPaths?: CircuitPaths;
+}
+
+interface ICompiler {
+    compile(noirCode: string): Promise<CompiledCircuit>;
+}
+
+/**
+ * Interface for generating zero-knowledge proofs
+ */
+interface IProver {
+    /**
+     * Generate a proof for the given circuit and inputs
+     *
+     * @param circuit - The compiled circuit to prove
+     * @param inputs - The inputs (both public and private) for the circuit
+     * @returns The proof data including proof bytes and public inputs
+     */
+    generateProof(circuit: CompiledCircuit, inputs: InputMap): Promise<ProofData>;
+}
+
+/**
+ * Interface for verifying zero-knowledge proofs
+ */
+interface IVerifier {
+    /**
+     * Verify a proof against a compiled circuit
+     *
+     * @param circuit - The compiled circuit used to generate the proof
+     * @param proof - The proof bytes to verify
+     * @param publicInputs - The public inputs that were used
+     * @returns true if the proof is valid, false otherwise
+     */
+    verifyProof(circuit: CompiledCircuit, proof: Uint8Array, publicInputs: string[]): Promise<boolean>;
+}
+
+/**
+ * Unified interface for a complete proving system.
+ * Combines compilation, proof generation, and verification into a single abstraction.
+ *
+ * Implementations:
+ * - Barretenberg: WASM-based (browser compatible), UltraHonk proofs
+ * - Sunspot: CLI-based (Node.js only), Groth16 proofs for Solana
+ */
+interface IProvingSystem extends ICompiler, IProver, IVerifier {
+}
+
+export { type ChainId as C, type EthereumChainMetadata as E, type IziNoirConfig as I, Provider as P, type SolanaChainMetadata as S, type CircuitMetadata as a, type ChainMetadataFor as b, Chain as c, type IProvingSystem as d, type CircuitPaths as e, type ChainMetadata as f, type ICompiler as g, type IProver as h, type IVerifier as i };