@sip-protocol/sdk 0.7.3 → 0.7.4

package/src/privacy-backends/router.ts

@@ -5,6 +5,13 @@
  * - User preferences (privacy, speed, cost, compliance)
  * - Backend capabilities and availability
  * - Transfer parameters
+ * - Backend health status (circuit breaker)
+ *
+ * ## Features
+ *
+ * - **Health-aware selection**: Skips backends with open circuit breakers
+ * - **Automatic fallback**: Tries alternatives when primary backend fails
+ * - **Metrics tracking**: Records success/failure for health monitoring
  *
  * @example
  * ```typescript
@@ -15,10 +22,11 @@
  *
  * const router = new SmartRouter(registry)
  *
- * // Auto-select best backend
+ * // Auto-select best backend with fallback
  * const result = await router.execute(params, {
  *   prioritize: 'compliance',
  *   requireViewingKeys: true,
+ *   enableFallback: true,
  * })
  *
  * // Or just select without executing
@@ -31,10 +39,13 @@ import type {
   PrivacyBackend,
   TransferParams,
   TransactionResult,
+  ComputationParams,
+  ComputationResult,
   SmartRouterConfig,
   BackendSelectionResult,
   AvailabilityResult,
 } from './interface'
+import { AllBackendsFailedError } from './interface'
 import { PrivacyBackendRegistry } from './registry'
 
 /**
@@ -44,6 +55,9 @@ const DEFAULT_CONFIG: SmartRouterConfig = {
   prioritize: 'privacy',
   requireViewingKeys: false,
   allowComputePrivacy: true,
+  enableFallback: true,
+  includeUnhealthy: false,
+  maxFallbackAttempts: 3,
 }
 
 /**
@@ -131,6 +145,11 @@ export class SmartRouter {
         continue
       }
 
+      // Check health status (circuit breaker)
+      if (!fullConfig.includeUnhealthy && !this.registry.isHealthy(backend.name)) {
+        continue
+      }
+
       // Check availability
       const availability = await backend.checkAvailability(params)
       if (!availability.available) {
@@ -233,16 +252,277 @@ export class SmartRouter {
   /**
    * Execute a transfer using the best available backend
    *
+   * Includes automatic fallback to alternatives if the primary backend fails
+   * (when enableFallback is true). Records success/failure for health tracking.
+   *
    * @param params - Transfer parameters
    * @param config - Router configuration
    * @returns Transaction result
+   * @throws AllBackendsFailedError if all backends fail
    */
   async execute(
     params: TransferParams,
     config: Partial<SmartRouterConfig> = {}
   ): Promise<TransactionResult> {
-    const selection = await this.selectBackend(params, config)
-    return selection.backend.execute(params)
+    const fullConfig = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      allowComputePrivacy: false, // Only transaction backends for execute()
+    }
+    const selection = await this.selectBackend(params, fullConfig)
+
+    // Try primary backend
+    const result = await this.executeOnBackend(selection.backend, params)
+
+    if (result.success) {
+      return result
+    }
+
+    // Primary failed, try fallback if enabled
+    if (!fullConfig.enableFallback || selection.alternatives.length === 0) {
+      return result
+    }
+
+    // Try alternatives
+    const attemptedBackends = [selection.backend.name]
+    const errors = new Map<string, string>()
+    errors.set(selection.backend.name, result.error || 'Unknown error')
+
+    const maxFallbackAttempts = fullConfig.maxFallbackAttempts ?? 3
+
+    // Iterate over all alternatives, but limit actual attempts
+    // Skipped backends (unhealthy/already attempted) don't count against the limit
+    let actualAttempts = 0
+    for (
+      let i = 0;
+      i < selection.alternatives.length && actualAttempts < maxFallbackAttempts;
+      i++
+    ) {
+      const alternative = selection.alternatives[i]
+
+      // Skip if already attempted (defensive - shouldn't happen with unique names)
+      if (attemptedBackends.includes(alternative.backend.name)) {
+        continue
+      }
+
+      // Skip unhealthy backends unless explicitly included
+      if (!fullConfig.includeUnhealthy && !this.registry.isHealthy(alternative.backend.name)) {
+        continue
+      }
+
+      // This counts as an actual attempt
+      actualAttempts++
+      attemptedBackends.push(alternative.backend.name)
+      const fallbackResult = await this.executeOnBackend(alternative.backend, params)
+
+      if (fallbackResult.success) {
+        // Add metadata about fallback
+        return {
+          ...fallbackResult,
+          metadata: {
+            ...fallbackResult.metadata,
+            fallbackFrom: selection.backend.name,
+            attemptedBackends,
+          },
+        }
+      }
+
+      errors.set(alternative.backend.name, fallbackResult.error || 'Unknown error')
+    }
+
+    // All attempts failed
+    throw new AllBackendsFailedError(attemptedBackends, errors, params)
+  }
+
+  /**
+   * Execute on a specific backend with health tracking
+   *
+   * @param backend - Backend to execute on
+   * @param params - Transfer parameters
+   * @returns Transaction result (never throws, returns error in result)
+   */
+  private async executeOnBackend(
+    backend: PrivacyBackend,
+    params: TransferParams
+  ): Promise<TransactionResult> {
+    const startTime = Date.now()
+
+    try {
+      const result = await backend.execute(params)
+      const latency = Date.now() - startTime
+
+      if (result.success) {
+        this.registry.recordSuccess(backend.name, latency)
+      } else {
+        this.registry.recordFailure(backend.name, result.error || 'Execution returned failure')
+      }
+
+      return result
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      this.registry.recordFailure(backend.name, errorMessage)
+
+      return {
+        success: false,
+        error: errorMessage,
+        backend: backend.name,
+      }
+    }
+  }
+
+  /**
+   * Execute a computation using the best available compute backend
+   *
+   * Selects from compute-type backends (Arcium, Inco) and executes
+   * the computation via MPC/FHE.
+   *
+   * @param params - Computation parameters
+   * @param config - Router configuration
+   * @returns Computation result
+   * @throws Error if no compute backend is available or supports the computation
+   *
+   * @example
+   * ```typescript
+   * const result = await router.executeComputation({
+   *   chain: 'solana',
+   *   circuitId: 'private-swap',
+   *   encryptedInputs: [encryptedAmount, encryptedPrice],
+   * })
+   * ```
+   */
+  async executeComputation(
+    params: ComputationParams,
+    config: Partial<SmartRouterConfig> = {}
+  ): Promise<ComputationResult> {
+    const selection = await this.selectComputeBackend(params, config)
+
+    if (!selection.backend.executeComputation) {
+      throw new Error(
+        `Backend '${selection.backend.name}' does not support compute operations. ` +
+        `This should not happen - please report this bug.`
+      )
+    }
+
+    return selection.backend.executeComputation(params)
+  }
+
+  /**
+   * Select the best compute backend for a computation
+   *
+   * @param params - Computation parameters
+   * @param config - Router configuration
+   * @returns Selection result with backend and reasoning
+   * @throws Error if no suitable compute backend is found
+   */
+  async selectComputeBackend(
+    params: ComputationParams,
+    config: Partial<SmartRouterConfig> = {}
+  ): Promise<BackendSelectionResult> {
+    const fullConfig = { ...DEFAULT_CONFIG, ...config }
+
+    // Get all backends for the chain
+    const chainBackends = this.registry.getByChain(params.chain)
+
+    // Filter to compute backends only
+    const computeBackends = chainBackends.filter(
+      b => b.type === 'compute' || b.type === 'both'
+    )
+
+    if (computeBackends.length === 0) {
+      throw new Error(
+        `No compute backends available for chain '${params.chain}'. ` +
+        `Register a compute backend (e.g., ArciumBackend) that supports this chain.`
+      )
+    }
+
+    // Filter and score backends
+    const scoredBackends: Array<{
+      backend: PrivacyBackend
+      availability: AvailabilityResult
+      score: number
+      reason: string
+    }> = []
+
+    for (const backend of computeBackends) {
+      // Check exclusions
+      if (fullConfig.excludeBackends?.includes(backend.name)) {
+        continue
+      }
+
+      // Check availability
+      const availability = await backend.checkAvailability(params)
+      if (!availability.available) {
+        continue
+      }
+
+      // Check cost limit
+      if (fullConfig.maxCost && availability.estimatedCost) {
+        if (availability.estimatedCost > fullConfig.maxCost) {
+          continue
+        }
+      }
+
+      // Check latency limit
+      if (fullConfig.maxLatency && availability.estimatedTime) {
+        if (availability.estimatedTime > fullConfig.maxLatency) {
+          continue
+        }
+      }
+
+      // Score this backend
+      const { score, reason } = this.scoreBackend(
+        backend,
+        availability,
+        fullConfig
+      )
+
+      scoredBackends.push({
+        backend,
+        availability,
+        score,
+        reason,
+      })
+    }
+
+    if (scoredBackends.length === 0) {
+      throw new Error(
+        `No compute backends meet the requirements for this computation. ` +
+        `Check that the circuit exists and the cluster is available.`
+      )
+    }
+
+    // Sort by score (descending)
+    scoredBackends.sort((a, b) => b.score - a.score)
+
+    // Preferred backend bonus
+    if (fullConfig.preferredBackend) {
+      const preferredIndex = scoredBackends.findIndex(
+        s => s.backend.name === fullConfig.preferredBackend
+      )
+      if (preferredIndex > 0) {
+        const preferred = scoredBackends[preferredIndex]
+        const leader = scoredBackends[0]
+        if (leader.score - preferred.score <= 10) {
+          scoredBackends.splice(preferredIndex, 1)
+          scoredBackends.unshift(preferred)
+          preferred.reason = `Preferred backend (within 10pts of optimal)`
+        }
+      }
+    }
+
+    const selected = scoredBackends[0]
+    const alternatives = scoredBackends.slice(1).map(s => ({
+      backend: s.backend,
+      score: s.score,
+      reason: s.reason,
+    }))
+
+    return {
+      backend: selected.backend,
+      reason: selected.reason,
+      alternatives,
+      score: selected.score,
+    }
   }
 
   /**