@sip-protocol/sdk 0.7.1 → 0.7.3

package/src/privacy-backends/registry.ts

@@ -0,0 +1,278 @@
+/**
+ * Privacy Backend Registry
+ *
+ * Manages registration and discovery of privacy backends.
+ *
+ * @example
+ * ```typescript
+ * const registry = new PrivacyBackendRegistry()
+ *
+ * // Register backends
+ * registry.register(new SIPNativeBackend())
+ * registry.register(new PrivacyCashBackend(), { priority: 10 })
+ *
+ * // Get backends
+ * const all = registry.getAll()
+ * const byName = registry.get('sip-native')
+ * const forChain = registry.getByChain('solana')
+ * const forType = registry.getByType('transaction')
+ * ```
+ */
+
+import type { ChainType } from '@sip-protocol/types'
+import type {
+  PrivacyBackend,
+  BackendType,
+  BackendRegistrationOptions,
+  RegisteredBackend,
+  TransferParams,
+  AvailabilityResult,
+} from './interface'
+
+/**
+ * Default priority for registered backends
+ */
+const DEFAULT_PRIORITY = 50
+
+/**
+ * Registry for managing privacy backends
+ *
+ * Provides a centralized way to register, discover, and manage
+ * different privacy backend implementations.
+ */
+export class PrivacyBackendRegistry {
+  private backends: Map<string, RegisteredBackend> = new Map()
+
+  /**
+   * Register a privacy backend
+   *
+   * @param backend - Backend instance to register
+   * @param options - Registration options
+   * @throws Error if backend with same name exists and override is false
+   *
+   * @example
+   * ```typescript
+   * registry.register(new SIPNativeBackend())
+   * registry.register(new PrivacyCashBackend(), { priority: 100 })
+   * ```
+   */
+  register(
+    backend: PrivacyBackend,
+    options: BackendRegistrationOptions = {}
+  ): void {
+    const { override = false, priority = DEFAULT_PRIORITY, enabled = true } = options
+
+    if (this.backends.has(backend.name) && !override) {
+      throw new Error(
+        `Backend '${backend.name}' is already registered. ` +
+        `Use { override: true } to replace it.`
+      )
+    }
+
+    this.backends.set(backend.name, {
+      backend,
+      priority,
+      enabled,
+      registeredAt: Date.now(),
+    })
+  }
+
+  /**
+   * Unregister a backend by name
+   *
+   * @param name - Backend name to unregister
+   * @returns true if backend was removed, false if not found
+   */
+  unregister(name: string): boolean {
+    return this.backends.delete(name)
+  }
+
+  /**
+   * Get a backend by name
+   *
+   * @param name - Backend name
+   * @returns Backend instance or undefined if not found
+   */
+  get(name: string): PrivacyBackend | undefined {
+    const entry = this.backends.get(name)
+    return entry?.enabled ? entry.backend : undefined
+  }
+
+  /**
+   * Check if a backend is registered
+   *
+   * @param name - Backend name
+   * @returns true if registered (regardless of enabled state)
+   */
+  has(name: string): boolean {
+    return this.backends.has(name)
+  }
+
+  /**
+   * Get all enabled backends sorted by priority
+   *
+   * @returns Array of backends (highest priority first)
+   */
+  getAll(): PrivacyBackend[] {
+    return Array.from(this.backends.values())
+      .filter(entry => entry.enabled)
+      .sort((a, b) => b.priority - a.priority)
+      .map(entry => entry.backend)
+  }
+
+  /**
+   * Get all registered entries (including disabled)
+   *
+   * @returns Array of registered backend entries
+   */
+  getAllEntries(): RegisteredBackend[] {
+    return Array.from(this.backends.values())
+      .sort((a, b) => b.priority - a.priority)
+  }
+
+  /**
+   * Get backends supporting a specific chain
+   *
+   * @param chain - Chain type to filter by
+   * @returns Array of backends supporting the chain
+   */
+  getByChain(chain: ChainType): PrivacyBackend[] {
+    return this.getAll().filter(backend =>
+      backend.chains.includes(chain)
+    )
+  }
+
+  /**
+   * Get backends of a specific type
+   *
+   * @param type - Backend type to filter by
+   * @returns Array of backends of the specified type
+   */
+  getByType(type: BackendType): PrivacyBackend[] {
+    return this.getAll().filter(backend =>
+      backend.type === type || backend.type === 'both'
+    )
+  }
+
+  /**
+   * Get backends that support compliance (viewing keys)
+   *
+   * @returns Array of compliance-supporting backends
+   */
+  getCompliant(): PrivacyBackend[] {
+    return this.getAll().filter(backend =>
+      backend.getCapabilities().complianceSupport
+    )
+  }
+
+  /**
+   * Find available backends for a transfer
+   *
+   * @param params - Transfer parameters
+   * @returns Array of available backends with availability info
+   */
+  async findAvailable(
+    params: TransferParams
+  ): Promise<Array<{ backend: PrivacyBackend; availability: AvailabilityResult }>> {
+    const chainBackends = this.getByChain(params.chain)
+    const results: Array<{ backend: PrivacyBackend; availability: AvailabilityResult }> = []
+
+    for (const backend of chainBackends) {
+      const availability = await backend.checkAvailability(params)
+      if (availability.available) {
+        results.push({ backend, availability })
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Enable a backend
+   *
+   * @param name - Backend name
+   * @returns true if backend was enabled, false if not found
+   */
+  enable(name: string): boolean {
+    const entry = this.backends.get(name)
+    if (entry) {
+      entry.enabled = true
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Disable a backend
+   *
+   * @param name - Backend name
+   * @returns true if backend was disabled, false if not found
+   */
+  disable(name: string): boolean {
+    const entry = this.backends.get(name)
+    if (entry) {
+      entry.enabled = false
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Set backend priority
+   *
+   * @param name - Backend name
+   * @param priority - New priority value
+   * @returns true if priority was set, false if not found
+   */
+  setPriority(name: string, priority: number): boolean {
+    const entry = this.backends.get(name)
+    if (entry) {
+      entry.priority = priority
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Get count of registered backends
+   *
+   * @param enabledOnly - If true, only count enabled backends
+   * @returns Number of backends
+   */
+  count(enabledOnly: boolean = false): number {
+    if (enabledOnly) {
+      return Array.from(this.backends.values()).filter(e => e.enabled).length
+    }
+    return this.backends.size
+  }
+
+  /**
+   * Clear all registered backends
+   */
+  clear(): void {
+    this.backends.clear()
+  }
+
+  /**
+   * Get backend names
+   *
+   * @param enabledOnly - If true, only return enabled backend names
+   * @returns Array of backend names
+   */
+  getNames(enabledOnly: boolean = false): string[] {
+    if (enabledOnly) {
+      return Array.from(this.backends.entries())
+        .filter(([, entry]) => entry.enabled)
+        .map(([name]) => name)
+    }
+    return Array.from(this.backends.keys())
+  }
+}
+
+/**
+ * Global default registry instance
+ *
+ * Use this for simple applications, or create your own instance
+ * for more control.
+ */
+export const defaultRegistry = new PrivacyBackendRegistry()

package/src/privacy-backends/router.ts

@@ -0,0 +1,346 @@
+/**
+ * SmartRouter - Privacy Backend Selection
+ *
+ * Automatically selects the optimal privacy backend based on:
+ * - User preferences (privacy, speed, cost, compliance)
+ * - Backend capabilities and availability
+ * - Transfer parameters
+ *
+ * @example
+ * ```typescript
+ * import { SmartRouter, PrivacyBackendRegistry, SIPNativeBackend } from '@sip-protocol/sdk'
+ *
+ * const registry = new PrivacyBackendRegistry()
+ * registry.register(new SIPNativeBackend())
+ *
+ * const router = new SmartRouter(registry)
+ *
+ * // Auto-select best backend
+ * const result = await router.execute(params, {
+ *   prioritize: 'compliance',
+ *   requireViewingKeys: true,
+ * })
+ *
+ * // Or just select without executing
+ * const selection = await router.selectBackend(params, config)
+ * console.log(`Selected: ${selection.backend.name}`)
+ * ```
+ */
+
+import type {
+  PrivacyBackend,
+  TransferParams,
+  TransactionResult,
+  SmartRouterConfig,
+  BackendSelectionResult,
+  AvailabilityResult,
+} from './interface'
+import { PrivacyBackendRegistry } from './registry'
+
+/**
+ * Default router configuration
+ */
+const DEFAULT_CONFIG: SmartRouterConfig = {
+  prioritize: 'privacy',
+  requireViewingKeys: false,
+  allowComputePrivacy: true,
+}
+
+/**
+ * Scoring weights for different priorities
+ */
+const PRIORITY_WEIGHTS = {
+  privacy: {
+    hiddenAmount: 25,
+    hiddenSender: 25,
+    hiddenRecipient: 25,
+    hiddenCompute: 10,
+    anonymitySet: 15,
+  },
+  speed: {
+    fast: 40,
+    medium: 25,
+    slow: 10,
+    setupRequired: -20,
+  },
+  cost: {
+    baseCost: 50,
+    estimatedCost: 50,
+  },
+  compliance: {
+    complianceSupport: 60,
+    hiddenAmount: 15,
+    hiddenSender: 15,
+    hiddenRecipient: 10,
+  },
+}
+
+/**
+ * SmartRouter for automatic backend selection
+ *
+ * Analyzes available backends and selects the optimal one
+ * based on user preferences and transfer requirements.
+ */
+export class SmartRouter {
+  private registry: PrivacyBackendRegistry
+
+  /**
+   * Create a new SmartRouter
+   *
+   * @param registry - Backend registry to use for selection
+   */
+  constructor(registry: PrivacyBackendRegistry) {
+    this.registry = registry
+  }
+
+  /**
+   * Select the best backend for a transfer
+   *
+   * @param params - Transfer parameters
+   * @param config - Router configuration
+   * @returns Selection result with backend and reasoning
+   * @throws Error if no suitable backend is found
+   */
+  async selectBackend(
+    params: TransferParams,
+    config: Partial<SmartRouterConfig> = {}
+  ): Promise<BackendSelectionResult> {
+    const fullConfig = { ...DEFAULT_CONFIG, ...config }
+
+    // Get backends for the chain
+    const chainBackends = this.registry.getByChain(params.chain)
+
+    if (chainBackends.length === 0) {
+      throw new Error(
+        `No backends available for chain '${params.chain}'. ` +
+        `Register a backend that supports this chain.`
+      )
+    }
+
+    // Filter and score backends
+    const scoredBackends: Array<{
+      backend: PrivacyBackend
+      availability: AvailabilityResult
+      score: number
+      reason: string
+    }> = []
+
+    for (const backend of chainBackends) {
+      // Check exclusions
+      if (fullConfig.excludeBackends?.includes(backend.name)) {
+        continue
+      }
+
+      // Check availability
+      const availability = await backend.checkAvailability(params)
+      if (!availability.available) {
+        continue
+      }
+
+      // Check hard requirements
+      const capabilities = backend.getCapabilities()
+
+      // Viewing key requirement
+      if (fullConfig.requireViewingKeys && !capabilities.complianceSupport) {
+        continue
+      }
+
+      // Anonymity set requirement
+      if (
+        fullConfig.minAnonymitySet &&
+        capabilities.anonymitySet !== undefined &&
+        capabilities.anonymitySet < fullConfig.minAnonymitySet
+      ) {
+        continue
+      }
+
+      // Compute privacy filter
+      if (!fullConfig.allowComputePrivacy && backend.type === 'compute') {
+        continue
+      }
+
+      // Cost limit
+      if (fullConfig.maxCost && availability.estimatedCost) {
+        if (availability.estimatedCost > fullConfig.maxCost) {
+          continue
+        }
+      }
+
+      // 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 backends meet the requirements for this transfer. ` +
+        `Check your router configuration and registered backends.`
+      )
+    }
+
+    // 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) {
+        // Move preferred to top if within 10 points of leader
+        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,
+    }
+  }
+
+  /**
+   * Execute a transfer using the best available backend
+   *
+   * @param params - Transfer parameters
+   * @param config - Router configuration
+   * @returns Transaction result
+   */
+  async execute(
+    params: TransferParams,
+    config: Partial<SmartRouterConfig> = {}
+  ): Promise<TransactionResult> {
+    const selection = await this.selectBackend(params, config)
+    return selection.backend.execute(params)
+  }
+
+  /**
+   * Get available backends for a transfer (without selecting)
+   *
+   * @param params - Transfer parameters
+   * @returns Array of available backends with scores
+   */
+  async getAvailableBackends(
+    params: TransferParams
+  ): Promise<Array<{ backend: PrivacyBackend; availability: AvailabilityResult }>> {
+    return this.registry.findAvailable(params)
+  }
+
+  /**
+   * Score a backend based on configuration priority
+   */
+  private scoreBackend(
+    backend: PrivacyBackend,
+    availability: AvailabilityResult,
+    config: SmartRouterConfig
+  ): { score: number; reason: string } {
+    const capabilities = backend.getCapabilities()
+    let score = 0
+    const reasons: string[] = []
+
+    switch (config.prioritize) {
+      case 'privacy':
+        if (capabilities.hiddenAmount) {
+          score += PRIORITY_WEIGHTS.privacy.hiddenAmount
+          reasons.push('hidden amounts')
+        }
+        if (capabilities.hiddenSender) {
+          score += PRIORITY_WEIGHTS.privacy.hiddenSender
+          reasons.push('hidden sender')
+        }
+        if (capabilities.hiddenRecipient) {
+          score += PRIORITY_WEIGHTS.privacy.hiddenRecipient
+          reasons.push('hidden recipient')
+        }
+        if (capabilities.hiddenCompute) {
+          score += PRIORITY_WEIGHTS.privacy.hiddenCompute
+          reasons.push('private compute')
+        }
+        if (capabilities.anonymitySet && capabilities.anonymitySet >= 100) {
+          score += PRIORITY_WEIGHTS.privacy.anonymitySet
+          reasons.push(`anonymity set: ${capabilities.anonymitySet}`)
+        }
+        break
+
+      case 'speed':
+        score += PRIORITY_WEIGHTS.speed[capabilities.latencyEstimate]
+        reasons.push(`${capabilities.latencyEstimate} latency`)
+        if (capabilities.setupRequired) {
+          score += PRIORITY_WEIGHTS.speed.setupRequired
+          reasons.push('setup required')
+        }
+        break
+
+      case 'cost':
+        // Lower cost = higher score (invert with log scale)
+        if (availability.estimatedCost !== undefined) {
+          // Use log scale to handle wide range of costs
+          // log10(100) ≈ 2, log10(100000) ≈ 5, log10(1000000) ≈ 6
+          const logCost = availability.estimatedCost > BigInt(0)
+            ? Math.log10(Number(availability.estimatedCost))
+            : 0
+          // Max cost assumed around 10^14 (log = 14), gives score 0
+          // Min cost around 10^2 (log = 2), gives score ~60
+          const costScore = Math.max(0, 70 - logCost * 5)
+          score += costScore
+          reasons.push(`low cost`)
+        }
+        break
+
+      case 'compliance':
+        if (capabilities.complianceSupport) {
+          score += PRIORITY_WEIGHTS.compliance.complianceSupport
+          reasons.push('viewing key support')
+        }
+        if (capabilities.hiddenAmount) {
+          score += PRIORITY_WEIGHTS.compliance.hiddenAmount
+        }
+        if (capabilities.hiddenSender) {
+          score += PRIORITY_WEIGHTS.compliance.hiddenSender
+        }
+        if (capabilities.hiddenRecipient) {
+          score += PRIORITY_WEIGHTS.compliance.hiddenRecipient
+        }
+        break
+    }
+
+    // Normalize score to 0-100
+    score = Math.min(100, Math.max(0, score))
+
+    return {
+      score,
+      reason: reasons.length > 0 ? reasons.join(', ') : 'default selection',
+    }
+  }
+}