@sip-protocol/sdk 0.7.3 → 0.7.4

package/src/proofs/browser.ts

@@ -44,17 +44,20 @@ import type { MobileDeviceInfo, MobileWASMCompatibility } from './browser-utils'
 // Import Noir JS (works in browser with WASM)
 import { Noir } from '@noir-lang/noir_js'
 import type { CompiledCircuit } from '@noir-lang/types'
-import { UltraHonkBackend } from '@aztec/bb.js'
+import { UltraHonkBackend, Barretenberg } from '@aztec/bb.js'
 import { secp256k1 } from '@noble/curves/secp256k1'
 
 // Import compiled circuit artifacts
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// Circuit JSON files are typed via CompiledCircuit assertion
 import fundingCircuitArtifact from './circuits/funding_proof.json'
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 import validityCircuitArtifact from './circuits/validity_proof.json'
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 import fulfillmentCircuitArtifact from './circuits/fulfillment_proof.json'
 
+// Type assertion for circuit artifacts (JSON modules)
+const fundingCircuit = fundingCircuitArtifact as unknown as CompiledCircuit
+const validityCircuit = validityCircuitArtifact as unknown as CompiledCircuit
+const fulfillmentCircuit = fulfillmentCircuitArtifact as unknown as CompiledCircuit
+
 /**
  * Public key coordinates for secp256k1
  */
@@ -117,6 +120,9 @@ export type ProofProgressCallback = (progress: {
   message: string
 }) => void
 
+/** Default initialization timeout in milliseconds */
+const DEFAULT_INIT_TIMEOUT_MS = 30000
+
 /**
  * Browser-compatible Noir Proof Provider
  *
@@ -142,12 +148,17 @@ export type ProofProgressCallback = (progress: {
 export class BrowserNoirProvider implements ProofProvider {
   readonly framework: ProofFramework = 'noir'
   private _isReady = false
+  private _initPromise: Promise<void> | null = null
+  private _initError: Error | null = null
   private config: Required<BrowserNoirProviderConfig>
 
   // Mobile device info (cached)
   private deviceInfo: MobileDeviceInfo | null = null
   private wasmCompatibility: MobileWASMCompatibility | null = null
 
+  // Barretenberg instance (shared by all backends)
+  private barretenberg: Barretenberg | null = null
+
   // Circuit instances
   private fundingNoir: Noir | null = null
   private fundingBackend: UltraHonkBackend | null = null
@@ -347,10 +358,79 @@ export class BrowserNoirProvider implements ProofProvider {
    * @param onProgress - Optional progress callback
    */
   async initialize(onProgress?: ProofProgressCallback): Promise<void> {
+    // If already ready, return immediately
+    if (this._isReady) {
+      return
+    }
+
+    // If initialization is in progress, wait for it
+    if (this._initPromise) {
+      return this._initPromise
+    }
+
+    // If a previous initialization failed, rethrow the error
+    if (this._initError) {
+      throw this._initError
+    }
+
+    // Start initialization and track the promise
+    this._initPromise = this._doInitialize(onProgress)
+
+    try {
+      await this._initPromise
+    } catch (error) {
+      // Store error for future calls
+      this._initError = error instanceof Error ? error : new Error(String(error))
+      this._initPromise = null
+      throw error
+    }
+  }
+
+  /**
+   * Wait for the provider to be ready, with optional timeout
+   *
+   * This method blocks until initialization is complete or the timeout is reached.
+   * If initialization is already complete, resolves immediately.
+   * If initialization hasn't started, this method will start it.
+   *
+   * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)
+   * @throws ProofError if timeout is reached before ready
+   * @throws ProofError if initialization fails
+   */
+  async waitUntilReady(timeoutMs: number = DEFAULT_INIT_TIMEOUT_MS): Promise<void> {
     if (this._isReady) {
       return
     }
 
+    // If there was a previous error, throw it
+    if (this._initError) {
+      throw new ProofError(
+        `BrowserNoirProvider initialization failed: ${this._initError.message}`,
+        ErrorCode.PROOF_PROVIDER_NOT_READY,
+        { context: { error: this._initError } }
+      )
+    }
+
+    // Start initialization if not already started
+    const initPromise = this._initPromise ?? this.initialize()
+
+    // Race between initialization and timeout
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new ProofError(
+          `BrowserNoirProvider initialization timed out after ${timeoutMs}ms`,
+          ErrorCode.PROOF_PROVIDER_NOT_READY
+        ))
+      }, timeoutMs)
+    })
+
+    await Promise.race([initPromise, timeoutPromise])
+  }
+
+  /**
+   * Internal initialization logic
+   */
+  private async _doInitialize(onProgress?: ProofProgressCallback): Promise<void> {
     // Check mobile compatibility
     this.wasmCompatibility = checkMobileWASMCompatibility()
 
@@ -388,21 +468,26 @@ export class BrowserNoirProvider implements ProofProvider {
         console.log('[BrowserNoirProvider] Browser info:', getBrowserInfo())
       }
 
-      // Initialize circuits in parallel for faster loading
-      const fundingCircuit = fundingCircuitArtifact as unknown as CompiledCircuit
-      const validityCircuit = validityCircuitArtifact as unknown as CompiledCircuit
-      const fulfillmentCircuit = fulfillmentCircuitArtifact as unknown as CompiledCircuit
+      // Initialize circuits in parallel for faster loading (using module-level typed constants)
+      onProgress?.({
+        stage: 'initializing',
+        percent: 15,
+        message: 'Initializing Barretenberg...',
+      })
+
+      // Initialize Barretenberg (bb.js 3.x requires shared instance)
+      this.barretenberg = await Barretenberg.new()
 
       onProgress?.({
         stage: 'initializing',
-        percent: 20,
+        percent: 30,
         message: 'Creating proof backends...',
       })
 
-      // Create backends (this loads WASM)
-      this.fundingBackend = new UltraHonkBackend(fundingCircuit.bytecode)
-      this.validityBackend = new UltraHonkBackend(validityCircuit.bytecode)
-      this.fulfillmentBackend = new UltraHonkBackend(fulfillmentCircuit.bytecode)
+      // Create backends (bb.js 3.x requires Barretenberg instance)
+      this.fundingBackend = new UltraHonkBackend(fundingCircuit.bytecode, this.barretenberg)
+      this.validityBackend = new UltraHonkBackend(validityCircuit.bytecode, this.barretenberg)
+      this.fulfillmentBackend = new UltraHonkBackend(fulfillmentCircuit.bytecode, this.barretenberg)
 
       onProgress?.({
         stage: 'initializing',
@@ -960,25 +1045,28 @@ export class BrowserNoirProvider implements ProofProvider {
    * Destroy the provider and free resources
    */
   async destroy(): Promise<void> {
-    if (this.fundingBackend) {
-      await this.fundingBackend.destroy()
-      this.fundingBackend = null
-    }
-    if (this.validityBackend) {
-      await this.validityBackend.destroy()
-      this.validityBackend = null
-    }
-    if (this.fulfillmentBackend) {
-      await this.fulfillmentBackend.destroy()
-      this.fulfillmentBackend = null
-    }
+    // Clear backend references (bb.js 3.x backends don't have destroy method)
+    this.fundingBackend = null
+    this.validityBackend = null
+    this.fulfillmentBackend = null
+
+    // Terminate worker if running
     if (this.worker) {
       this.worker.terminate()
       this.worker = null
     }
+
+    // Clear Noir instances
     this.fundingNoir = null
     this.validityNoir = null
     this.fulfillmentNoir = null
+
+    // Destroy shared Barretenberg instance (bb.js 3.x)
+    if (this.barretenberg) {
+      await this.barretenberg.destroy()
+      this.barretenberg = null
+    }
+
     this._isReady = false
   }
 

package/src/proofs/cache/index.ts

@@ -0,0 +1,127 @@
+/**
+ * Proof Caching Layer Module
+ *
+ * @module proofs/cache
+ * @description Multi-tier caching for proofs and intermediate computation results
+ *
+ * M20-13: Implement proof caching layer (#313)
+ *
+ * ## Overview
+ *
+ * This module provides a comprehensive caching layer for ZK proofs:
+ *
+ * - **LRU Cache**: Fast in-memory caching with LRU eviction
+ * - **Persistent Cache**: IndexedDB (browser) or file-based (Node.js) storage
+ * - **Multi-Tier Cache**: Combines memory and persistent with read/write-through
+ * - **Cache Warming**: Predictive warming based on access patterns
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import {
+ *   createMultiTierCache,
+ *   cacheKeyGenerator,
+ * } from '@sip-protocol/sdk/proofs/cache'
+ *
+ * // Create a multi-tier cache
+ * const cache = createMultiTierCache({
+ *   memory: { maxEntries: 500, maxSizeBytes: 50 * 1024 * 1024 },
+ *   writeThrough: true,
+ *   readThrough: true,
+ * })
+ *
+ * // Generate a cache key from inputs
+ * const key = cacheKeyGenerator.generateFromInputs(
+ *   'noir',
+ *   'funding_proof',
+ *   { balance: 1000n },
+ *   { minRequired: 100n }
+ * )
+ *
+ * // Check cache before generating
+ * const cached = await cache.get(key)
+ * if (cached.hit) {
+ *   return cached.entry!.value
+ * }
+ *
+ * // Generate and cache
+ * const proof = await generateProof(...)
+ * await cache.set(key, proof)
+ * ```
+ */
+
+// ─── Types and Interfaces ────────────────────────────────────────────────────
+
+export type {
+  // Cache Key
+  CacheKeyComponents,
+  CacheKey,
+  // Cache Entry
+  CacheEntryMetadata,
+  CacheEntry,
+  CacheLookupResult,
+  // Configuration
+  LRUCacheConfig,
+  PersistentCacheConfig,
+  MultiTierCacheConfig,
+  // Statistics
+  ProofCacheStats,
+  // Events
+  CacheEventType,
+  CacheEvent,
+  CacheEventListener,
+  // Invalidation
+  InvalidationStrategy,
+  InvalidationRule,
+  // Warming
+  CacheWarmingConfig,
+  WarmingResult,
+  // Interfaces
+  ICacheKeyGenerator,
+  IProofCache,
+  ILRUCache,
+  IPersistentCache,
+  IMultiTierCache,
+  IVerificationKeyCache,
+  ICompiledCircuitCache,
+} from './interface'
+
+export {
+  DEFAULT_LRU_CONFIG,
+  DEFAULT_PERSISTENT_CONFIG,
+  DEFAULT_MULTI_TIER_CONFIG,
+  DEFAULT_WARMING_CONFIG,
+  INITIAL_PROOF_CACHE_STATS,
+} from './interface'
+
+// ─── Cache Key Generator ─────────────────────────────────────────────────────
+
+export {
+  CacheKeyGenerator,
+  createCacheKeyGenerator,
+  cacheKeyGenerator,
+} from './key-generator'
+
+// ─── LRU Cache ───────────────────────────────────────────────────────────────
+
+export {
+  LRUCache,
+  createLRUCache,
+} from './lru-cache'
+
+// ─── Persistent Cache ────────────────────────────────────────────────────────
+
+export {
+  IndexedDBCache,
+  FileCache,
+  createPersistentCache,
+  createIndexedDBCache,
+  createFileCache,
+} from './persistent-cache'
+
+// ─── Multi-Tier Cache ────────────────────────────────────────────────────────
+
+export {
+  MultiTierCache,
+  createMultiTierCache,
+} from './multi-tier-cache'