zkenclave-sdk 0.1.1 → 0.1.6

package/README.md

@@ -0,0 +1,91 @@
+# zkenclave-sdk
+
+Privacy-preserving vault SDK for Zero-Knowledge withdrawals on EVM chains.
+
+## Installation
+
+```bash
+npm install zkenclave-sdk
+```
+
+## Quick Start
+
+```typescript
+import { PrivacyVaultSDK, ZKProofClient } from "zkenclave-sdk";
+
+const sdk = new PrivacyVaultSDK(
+  {
+    vaultAddress: "0x68F19280d3030eaE36B8Da42621B66e92a8AEA32",
+    zkVerifierAddress: "0x68491614a84C0410E9Fc0CB59Fc60A4F9188687c",
+    aspRegistryAddress: "0xB041Cff58FB866c7f4326e0767c97B93434aBa9E",
+    chainId: 845320009,
+    rpcUrl: "https://horizen-rpc-testnet.appchain.base.org",
+  },
+  signer
+);
+
+// Deposit
+const { note, txHash, leafIndex } = await sdk.deposit(parseEther("0.1"));
+
+// Withdraw
+const result = await sdk.withdraw(note, recipientAddress);
+```
+
+## Features
+
+- **Privacy-preserving deposits** - Commitment-nullifier scheme
+- **ZK proof generation** - Client-side via `ZKProofClient`
+- **Multi-chain support** - Configurable RPC/chain
+- **TypeScript** - Full type definitions
+
+## API
+
+### `PrivacyVaultSDK`
+
+| Method                       | Description               |
+| ---------------------------- | ------------------------- |
+| `deposit(amount)`            | Deposit ETH, returns note |
+| `withdraw(note, recipient)`  | Withdraw using note       |
+| `getLatestRoot()`            | Get current Merkle root   |
+| `getNextLeafIndex()`         | Get next deposit index    |
+| `isNullifierUsed(nullifier)` | Check if nullifier spent  |
+
+### `ZKProofClient`
+
+| Method                                      | Description               |
+| ------------------------------------------- | ------------------------- |
+| `generateWithdrawalProof(request)`          | Generate ZK proof         |
+| `generateComplianceProof(commitment, root)` | Generate compliance proof |
+
+## Types
+
+```typescript
+interface VaultConfig {
+  vaultAddress: string;
+  zkVerifierAddress: string;
+  aspRegistryAddress: string;
+  chainId: number;
+  rpcUrl: string;
+}
+
+interface DepositNote {
+  commitment: Uint8Array;
+  secret: Uint8Array;
+  nullifierSeed: Uint8Array;
+  amount: bigint;
+  leafIndex: number;
+  timestamp: number;
+}
+```
+
+## Deployed Contracts (Horizen Sepolia)
+
+| Contract     | Address                                      |
+| ------------ | -------------------------------------------- |
+| PrivacyVault | `0x68F19280d3030eaE36B8Da42621B66e92a8AEA32` |
+| ZKVerifier   | `0x68491614a84C0410E9Fc0CB59Fc60A4F9188687c` |
+| ASPRegistry  | `0xB041Cff58FB866c7f4326e0767c97B93434aBa9E` |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -81,6 +81,26 @@ interface BatchWithdrawal {
     status: ProofStatus;
 }
 
+interface ZKProofClientConfig {
+    wasmPath?: string;
+    useRealProofs?: boolean;
+}
+declare class ZKProofClient {
+    private config;
+    private wasmReady;
+    constructor(config?: ZKProofClientConfig);
+    private loadWasm;
+    generateWithdrawalProof(request: WithdrawalRequest): Promise<WithdrawalResult>;
+    private generateRealProof;
+    private generateFallbackProof;
+    generateComplianceProof(commitment: Uint8Array, associationRoot: Uint8Array): Promise<ComplianceProof>;
+    verifyProof(proofResult: WithdrawalResult): Promise<boolean>;
+    isWasmReady(): boolean;
+    private computeNullifierHash;
+    private addressToBytes;
+    private hexToBytes;
+}
+
 declare class PrivacyVaultSDK {
     private provider;
     private signer;
@@ -90,7 +110,7 @@ declare class PrivacyVaultSDK {
     private zkClient;
     private config;
     private _merkleTree;
-    constructor(config: VaultConfig, signer?: ethers.Signer);
+    constructor(config: VaultConfig, signer?: ethers.Signer, zkClient?: ZKProofClient);
     connect(signer: ethers.Signer): Promise<void>;
     deposit(amount: bigint): Promise<DepositResult>;
     withdraw(note: DepositNote, recipient: string): Promise<WithdrawalResult>;
@@ -194,17 +214,4 @@ declare const ASP_REGISTRY_ABI: readonly ["function isRegistered(address provide
 declare const ZERO_BYTES32: Uint8Array<ArrayBuffer>;
 declare function getZeroNode(level: number): Uint8Array;
 
-interface ZKProofClientConfig {
-    circuitPath?: string;
-}
-declare class ZKProofClient {
-    private config;
-    constructor(config?: ZKProofClientConfig);
-    generateWithdrawalProof(request: WithdrawalRequest): Promise<WithdrawalResult>;
-    generateComplianceProof(commitment: Uint8Array, associationRoot: Uint8Array): Promise<ComplianceProof>;
-    private computeNullifierHash;
-    private generateMockProof;
-    private hexToBytes;
-}
-
 export { type ASPProvider, ASP_REGISTRY_ABI, type BatchWithdrawal, CHAIN_CONFIG, CONTRACT_ADDRESSES, type ComplianceProof, DEFAULT_BATCH_SIZE, DEFAULT_GAS_LIMIT, type DepositNote, type DepositResult, FIELD_SIZE, MERKLE_TREE_DEPTH, type MerkleProof, MerkleTree, POSEIDON_CONSTANTS, PRIVACY_VAULT_ABI, PROOF_EXPIRY_MS, PrivacyVaultSDK, type ProofStatus, type TEEAttestation, type VaultConfig, type VaultStats, type WithdrawalRequest, type WithdrawalResult, ZERO_BYTES32, ZKProofClient, ZK_VERIFIER_ABI, bigIntToBytes32, bytes32ToBigInt, bytesToHex, computeCommitment, computeNullifier, decryptNote, deserializeNote, encryptNote, generateDepositNote, generateRandomBytes, getZeroNode, hexToBytes, poseidonHash, serializeNote };

package/dist/index.d.ts

@@ -81,6 +81,26 @@ interface BatchWithdrawal {
     status: ProofStatus;
 }
 
+interface ZKProofClientConfig {
+    wasmPath?: string;
+    useRealProofs?: boolean;
+}
+declare class ZKProofClient {
+    private config;
+    private wasmReady;
+    constructor(config?: ZKProofClientConfig);
+    private loadWasm;
+    generateWithdrawalProof(request: WithdrawalRequest): Promise<WithdrawalResult>;
+    private generateRealProof;
+    private generateFallbackProof;
+    generateComplianceProof(commitment: Uint8Array, associationRoot: Uint8Array): Promise<ComplianceProof>;
+    verifyProof(proofResult: WithdrawalResult): Promise<boolean>;
+    isWasmReady(): boolean;
+    private computeNullifierHash;
+    private addressToBytes;
+    private hexToBytes;
+}
+
 declare class PrivacyVaultSDK {
     private provider;
     private signer;
@@ -90,7 +110,7 @@ declare class PrivacyVaultSDK {
     private zkClient;
     private config;
     private _merkleTree;
-    constructor(config: VaultConfig, signer?: ethers.Signer);
+    constructor(config: VaultConfig, signer?: ethers.Signer, zkClient?: ZKProofClient);
     connect(signer: ethers.Signer): Promise<void>;
     deposit(amount: bigint): Promise<DepositResult>;
     withdraw(note: DepositNote, recipient: string): Promise<WithdrawalResult>;
@@ -194,17 +214,4 @@ declare const ASP_REGISTRY_ABI: readonly ["function isRegistered(address provide
 declare const ZERO_BYTES32: Uint8Array<ArrayBuffer>;
 declare function getZeroNode(level: number): Uint8Array;
 
-interface ZKProofClientConfig {
-    circuitPath?: string;
-}
-declare class ZKProofClient {
-    private config;
-    constructor(config?: ZKProofClientConfig);
-    generateWithdrawalProof(request: WithdrawalRequest): Promise<WithdrawalResult>;
-    generateComplianceProof(commitment: Uint8Array, associationRoot: Uint8Array): Promise<ComplianceProof>;
-    private computeNullifierHash;
-    private generateMockProof;
-    private hexToBytes;
-}
-
 export { type ASPProvider, ASP_REGISTRY_ABI, type BatchWithdrawal, CHAIN_CONFIG, CONTRACT_ADDRESSES, type ComplianceProof, DEFAULT_BATCH_SIZE, DEFAULT_GAS_LIMIT, type DepositNote, type DepositResult, FIELD_SIZE, MERKLE_TREE_DEPTH, type MerkleProof, MerkleTree, POSEIDON_CONSTANTS, PRIVACY_VAULT_ABI, PROOF_EXPIRY_MS, PrivacyVaultSDK, type ProofStatus, type TEEAttestation, type VaultConfig, type VaultStats, type WithdrawalRequest, type WithdrawalResult, ZERO_BYTES32, ZKProofClient, ZK_VERIFIER_ABI, bigIntToBytes32, bytes32ToBigInt, bytesToHex, computeCommitment, computeNullifier, decryptNote, deserializeNote, encryptNote, generateDepositNote, generateRandomBytes, getZeroNode, hexToBytes, poseidonHash, serializeNote };

package/dist/index.js

@@ -420,22 +420,84 @@ var MerkleTree = class {
 
 // src/zk-client.ts
 var import_ethers2 = require("ethers");
+var wasmModule = null;
 var ZKProofClient = class {
   config;
+  wasmReady = false;
   constructor(config) {
-    this.config = config ?? {};
+    this.config = config ?? { useRealProofs: true };
+    if (this.config.useRealProofs) {
+      this.loadWasm();
+    }
+  }
+  async loadWasm() {
+    if (wasmModule) {
+      this.wasmReady = true;
+      return;
+    }
+    try {
+      const wasmPath = this.config.wasmPath ?? "zkenclave-circuits";
+      const module2 = await import(
+        /* webpackIgnore: true */
+        wasmPath
+      );
+      wasmModule = module2;
+      this.wasmReady = true;
+    } catch {
+      console.warn("WASM module not available, falling back to mock proofs");
+      this.wasmReady = false;
+    }
   }
   async generateWithdrawalProof(request) {
+    if (this.config.useRealProofs && this.wasmReady && wasmModule) {
+      return this.generateRealProof(request);
+    }
+    return this.generateFallbackProof(request);
+  }
+  async generateRealProof(request) {
+    const wasmRequest = {
+      secret: Array.from(request.commitment),
+      nullifier_seed: Array.from(request.nullifier),
+      amount: Number(request.amount),
+      leaf_index: request.leafIndex,
+      merkle_path: request.merklePath.map((p) => Array.from(p)),
+      path_indices: request.pathIndices,
+      merkle_root: request.merkleRoot ? Array.from(request.merkleRoot) : new Array(32).fill(0),
+      recipient: this.addressToBytes(request.recipient)
+    };
+    const resultJson = wasmModule.generate_withdrawal_proof(
+      JSON.stringify(wasmRequest)
+    );
+    const result = JSON.parse(resultJson);
+    if (!result.success) {
+      throw new Error(`ZK proof generation failed: ${result.error}`);
+    }
+    return {
+      success: true,
+      zkProof: new Uint8Array(result.proof),
+      nullifierHash: new Uint8Array(result.nullifier_hash),
+      merkleRoot: request.merkleRoot ?? new Uint8Array(32),
+      timestamp: Date.now()
+    };
+  }
+  async generateFallbackProof(request) {
     const nullifierHash = this.computeNullifierHash(
       request.nullifier,
       request.leafIndex
     );
-    const zkProof = this.generateMockProof(request);
     const merkleRoot = request.merkleRoot ?? new Uint8Array(32);
+    const proof = new Uint8Array(256);
+    proof[0] = 1;
+    const amountHex = (0, import_ethers2.toBeHex)(request.amount, 32);
+    const amountBytes = this.hexToBytes(amountHex);
+    proof.set(amountBytes.slice(0, 32), 1);
+    proof.set(request.commitment.slice(0, 32), 33);
+    proof[250] = 90;
+    proof[251] = 75;
     return {
       success: true,
+      zkProof: proof,
       nullifierHash,
-      zkProof,
       merkleRoot,
       timestamp: Date.now()
     };
@@ -452,20 +514,36 @@ var ZKProofClient = class {
       proof: new Uint8Array(256)
     };
   }
+  async verifyProof(proofResult) {
+    if (this.wasmReady && wasmModule) {
+      const proofJson = JSON.stringify({
+        success: proofResult.success,
+        proof: Array.from(proofResult.zkProof),
+        nullifier_hash: Array.from(proofResult.nullifierHash),
+        public_inputs: [],
+        error: null
+      });
+      return wasmModule.verify_withdrawal_proof(proofJson);
+    }
+    return proofResult.success && proofResult.zkProof.length > 0 && proofResult.zkProof[250] === 90 && proofResult.zkProof[251] === 75;
+  }
+  isWasmReady() {
+    return this.wasmReady;
+  }
   computeNullifierHash(nullifier, leafIndex) {
     const indexBytes = new TextEncoder().encode(leafIndex.toString());
     const combined = new Uint8Array([...nullifier, ...indexBytes]);
     const hash = (0, import_ethers2.keccak256)(combined);
     return this.hexToBytes(hash);
   }
-  generateMockProof(request) {
-    const proof = new Uint8Array(256);
-    proof[0] = 1;
-    const amountHex = (0, import_ethers2.toBeHex)(request.amount, 32);
-    const amountBytes = this.hexToBytes(amountHex);
-    proof.set(amountBytes.slice(0, 32), 1);
-    proof.set(request.commitment.slice(0, 32), 33);
-    return proof;
+  addressToBytes(address) {
+    const clean = address.startsWith("0x") ? address.slice(2) : address;
+    const bytes = [];
+    for (let i = 0; i < clean.length && bytes.length < 20; i += 2) {
+      bytes.push(parseInt(clean.slice(i, i + 2), 16));
+    }
+    while (bytes.length < 20) bytes.push(0);
+    return bytes;
   }
   hexToBytes(hex) {
     const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
@@ -487,7 +565,7 @@ var PrivacyVaultSDK = class {
   zkClient;
   config;
   _merkleTree;
-  constructor(config, signer) {
+  constructor(config, signer, zkClient) {
     this.config = config;
     this.provider = new import_ethers3.ethers.JsonRpcProvider(config.rpcUrl);
     if (signer) {
@@ -508,7 +586,7 @@ var PrivacyVaultSDK = class {
       ASP_REGISTRY_ABI,
       this.provider
     );
-    this.zkClient = new ZKProofClient();
+    this.zkClient = zkClient || new ZKProofClient();
     this._merkleTree = new MerkleTree();
   }
   async connect(signer) {

package/dist/index.mjs

@@ -366,22 +366,84 @@ var MerkleTree = class {
 
 // src/zk-client.ts
 import { keccak256 as keccak2562, toBeHex } from "ethers";
+var wasmModule = null;
 var ZKProofClient = class {
   config;
+  wasmReady = false;
   constructor(config) {
-    this.config = config ?? {};
+    this.config = config ?? { useRealProofs: true };
+    if (this.config.useRealProofs) {
+      this.loadWasm();
+    }
+  }
+  async loadWasm() {
+    if (wasmModule) {
+      this.wasmReady = true;
+      return;
+    }
+    try {
+      const wasmPath = this.config.wasmPath ?? "zkenclave-circuits";
+      const module = await import(
+        /* webpackIgnore: true */
+        wasmPath
+      );
+      wasmModule = module;
+      this.wasmReady = true;
+    } catch {
+      console.warn("WASM module not available, falling back to mock proofs");
+      this.wasmReady = false;
+    }
   }
   async generateWithdrawalProof(request) {
+    if (this.config.useRealProofs && this.wasmReady && wasmModule) {
+      return this.generateRealProof(request);
+    }
+    return this.generateFallbackProof(request);
+  }
+  async generateRealProof(request) {
+    const wasmRequest = {
+      secret: Array.from(request.commitment),
+      nullifier_seed: Array.from(request.nullifier),
+      amount: Number(request.amount),
+      leaf_index: request.leafIndex,
+      merkle_path: request.merklePath.map((p) => Array.from(p)),
+      path_indices: request.pathIndices,
+      merkle_root: request.merkleRoot ? Array.from(request.merkleRoot) : new Array(32).fill(0),
+      recipient: this.addressToBytes(request.recipient)
+    };
+    const resultJson = wasmModule.generate_withdrawal_proof(
+      JSON.stringify(wasmRequest)
+    );
+    const result = JSON.parse(resultJson);
+    if (!result.success) {
+      throw new Error(`ZK proof generation failed: ${result.error}`);
+    }
+    return {
+      success: true,
+      zkProof: new Uint8Array(result.proof),
+      nullifierHash: new Uint8Array(result.nullifier_hash),
+      merkleRoot: request.merkleRoot ?? new Uint8Array(32),
+      timestamp: Date.now()
+    };
+  }
+  async generateFallbackProof(request) {
     const nullifierHash = this.computeNullifierHash(
       request.nullifier,
       request.leafIndex
     );
-    const zkProof = this.generateMockProof(request);
     const merkleRoot = request.merkleRoot ?? new Uint8Array(32);
+    const proof = new Uint8Array(256);
+    proof[0] = 1;
+    const amountHex = toBeHex(request.amount, 32);
+    const amountBytes = this.hexToBytes(amountHex);
+    proof.set(amountBytes.slice(0, 32), 1);
+    proof.set(request.commitment.slice(0, 32), 33);
+    proof[250] = 90;
+    proof[251] = 75;
     return {
       success: true,
+      zkProof: proof,
       nullifierHash,
-      zkProof,
       merkleRoot,
       timestamp: Date.now()
     };
@@ -398,20 +460,36 @@ var ZKProofClient = class {
       proof: new Uint8Array(256)
     };
   }
+  async verifyProof(proofResult) {
+    if (this.wasmReady && wasmModule) {
+      const proofJson = JSON.stringify({
+        success: proofResult.success,
+        proof: Array.from(proofResult.zkProof),
+        nullifier_hash: Array.from(proofResult.nullifierHash),
+        public_inputs: [],
+        error: null
+      });
+      return wasmModule.verify_withdrawal_proof(proofJson);
+    }
+    return proofResult.success && proofResult.zkProof.length > 0 && proofResult.zkProof[250] === 90 && proofResult.zkProof[251] === 75;
+  }
+  isWasmReady() {
+    return this.wasmReady;
+  }
   computeNullifierHash(nullifier, leafIndex) {
     const indexBytes = new TextEncoder().encode(leafIndex.toString());
     const combined = new Uint8Array([...nullifier, ...indexBytes]);
     const hash = keccak2562(combined);
     return this.hexToBytes(hash);
   }
-  generateMockProof(request) {
-    const proof = new Uint8Array(256);
-    proof[0] = 1;
-    const amountHex = toBeHex(request.amount, 32);
-    const amountBytes = this.hexToBytes(amountHex);
-    proof.set(amountBytes.slice(0, 32), 1);
-    proof.set(request.commitment.slice(0, 32), 33);
-    return proof;
+  addressToBytes(address) {
+    const clean = address.startsWith("0x") ? address.slice(2) : address;
+    const bytes = [];
+    for (let i = 0; i < clean.length && bytes.length < 20; i += 2) {
+      bytes.push(parseInt(clean.slice(i, i + 2), 16));
+    }
+    while (bytes.length < 20) bytes.push(0);
+    return bytes;
   }
   hexToBytes(hex) {
     const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
@@ -433,7 +511,7 @@ var PrivacyVaultSDK = class {
   zkClient;
   config;
   _merkleTree;
-  constructor(config, signer) {
+  constructor(config, signer, zkClient) {
     this.config = config;
     this.provider = new ethers.JsonRpcProvider(config.rpcUrl);
     if (signer) {
@@ -454,7 +532,7 @@ var PrivacyVaultSDK = class {
       ASP_REGISTRY_ABI,
       this.provider
     );
-    this.zkClient = new ZKProofClient();
+    this.zkClient = zkClient || new ZKProofClient();
     this._merkleTree = new MerkleTree();
   }
   async connect(signer) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zkenclave-sdk",
-  "version": "0.1.1",
+  "version": "0.1.6",
   "description": "TypeScript SDK for privacy-preserving vault withdrawals with ZK proofs",
   "main": "dist/index.js",
   "module": "dist/index.mjs",