@sip-protocol/sdk 0.2.10 → 0.3.0

package/src/settlement/backends/zcash-native.ts

@@ -0,0 +1,516 @@
+/**
+ * Zcash Native Settlement Backend
+ *
+ * Settlement backend for direct Zcash-to-Zcash transactions.
+ * Uses ZcashSwapService for shielded transfers within the Zcash network.
+ *
+ * @example
+ * ```typescript
+ * const backend = new ZcashNativeBackend({
+ *   swapService: zcashSwapService,
+ * })
+ *
+ * const quote = await backend.getQuote({
+ *   fromChain: 'zcash',
+ *   toChain: 'zcash',
+ *   fromToken: 'ZEC',
+ *   toToken: 'ZEC',
+ *   amount: 100000000n, // 1 ZEC
+ *   privacyLevel: PrivacyLevel.SHIELDED,
+ * })
+ * ```
+ */
+
+import { PrivacyLevel, type ChainId } from '@sip-protocol/types'
+import {
+  type SettlementBackend,
+  type QuoteParams,
+  type Quote,
+  type SwapParams,
+  type SwapResult,
+  type SwapStatusResponse,
+  type BackendCapabilities,
+  SwapStatus,
+} from '../interface'
+import { ValidationError, ErrorCode } from '../../errors'
+import type { ZcashSwapService } from '../../zcash'
+
+// ─── Configuration Types ───────────────────────────────────────────────────
+
+/**
+ * Configuration for ZcashNativeBackend
+ */
+export interface ZcashNativeBackendConfig {
+  /** Zcash swap service instance */
+  swapService: ZcashSwapService
+  /** Default quote validity in seconds (default: 300 = 5 minutes) */
+  quoteValiditySeconds?: number
+  /** Network fee estimate in zatoshis (default: 10000 = 0.0001 ZEC) */
+  networkFeeZatoshis?: number
+}
+
+// ─── Backend Implementation ────────────────────────────────────────────────
+
+/**
+ * Zcash Native Settlement Backend
+ *
+ * Handles ZEC → ZEC transfers within the Zcash network.
+ * Supports both transparent (t-addr) and shielded (z-addr) addresses.
+ */
+export class ZcashNativeBackend implements SettlementBackend {
+  readonly name = 'zcash-native' as const
+  readonly capabilities: BackendCapabilities
+
+  private readonly swapService: ZcashSwapService
+  private readonly config: Required<Omit<ZcashNativeBackendConfig, 'swapService'>>
+  private readonly quotes = new Map<string, Quote>()
+  private readonly swaps = new Map<string, SwapResult>()
+
+  constructor(config: ZcashNativeBackendConfig) {
+    this.swapService = config.swapService
+    this.config = {
+      quoteValiditySeconds: config.quoteValiditySeconds ?? 300,
+      networkFeeZatoshis: config.networkFeeZatoshis ?? 10000,
+    }
+
+    this.capabilities = {
+      supportedSourceChains: ['zcash'],
+      supportedDestinationChains: ['zcash'],
+      supportedPrivacyLevels: [
+        PrivacyLevel.TRANSPARENT,
+        PrivacyLevel.SHIELDED,
+        PrivacyLevel.COMPLIANT,
+      ],
+      supportsCancellation: false,
+      supportsRefunds: false,
+      averageExecutionTime: 75, // ~75 seconds for Zcash block confirmation
+      features: [
+        'native-zcash',
+        'shielded-addresses',
+        'transparent-addresses',
+        'instant-quotes',
+      ],
+    }
+  }
+
+  // ─── Quote Methods ─────────────────────────────────────────────────────────
+
+  /**
+   * Get a quote for ZEC → ZEC transfer
+   */
+  async getQuote(params: QuoteParams): Promise<Quote> {
+    this.validateQuoteParams(params)
+
+    const { amount, recipientMetaAddress, senderAddress, privacyLevel } = params
+
+    // Generate quote ID
+    const quoteId = this.generateQuoteId()
+    const now = Math.floor(Date.now() / 1000)
+    const expiresAt = now + this.config.quoteValiditySeconds
+
+    // Calculate fees (simple network fee for ZEC transfers)
+    const networkFee = BigInt(this.config.networkFeeZatoshis)
+    const protocolFee = BigInt(0) // No protocol fee for native transfers
+    const totalFee = networkFee
+
+    // Calculate output amount (input - fees)
+    const amountOut = amount - totalFee
+    if (amountOut <= BigInt(0)) {
+      throw new ValidationError(
+        'Amount too small to cover network fees',
+        'amount',
+        { amount: amount.toString(), networkFee: networkFee.toString() },
+        ErrorCode.INVALID_AMOUNT,
+      )
+    }
+
+    // Minimum output (99% of expected, accounting for potential fee variations)
+    const minAmountOut = (amountOut * BigInt(99)) / BigInt(100)
+
+    // Generate deposit address based on privacy level
+    let depositAddress: string
+    let recipientAddress: string
+
+    if (privacyLevel === PrivacyLevel.SHIELDED || privacyLevel === PrivacyLevel.COMPLIANT) {
+      // For shielded transfers, we need z-addresses
+      if (typeof recipientMetaAddress === 'string') {
+        // Assume it's a z-address
+        recipientAddress = recipientMetaAddress
+      } else if (recipientMetaAddress) {
+        // Generate stealth address from meta-address (simplified for now)
+        recipientAddress = `zs1${this.randomHex(72)}` // Mock z-address
+      } else {
+        throw new ValidationError(
+          'Recipient address required for shielded transfers',
+          'recipientMetaAddress',
+          undefined,
+          ErrorCode.VALIDATION_FAILED,
+        )
+      }
+
+      // Generate a z-address for deposit
+      depositAddress = `zs1${this.randomHex(72)}`
+    } else {
+      // Transparent transfer
+      if (senderAddress) {
+        depositAddress = senderAddress
+      } else {
+        depositAddress = `t1${this.randomBase58(33)}` // Mock t-address
+      }
+
+      if (typeof recipientMetaAddress === 'string') {
+        recipientAddress = recipientMetaAddress
+      } else {
+        throw new ValidationError(
+          'Recipient address required',
+          'recipientMetaAddress',
+          undefined,
+          ErrorCode.VALIDATION_FAILED,
+        )
+      }
+    }
+
+    const quote: Quote = {
+      quoteId,
+      amountIn: amount.toString(),
+      amountOut: amountOut.toString(),
+      minAmountOut: minAmountOut.toString(),
+      fees: {
+        networkFee: networkFee.toString(),
+        protocolFee: protocolFee.toString(),
+      },
+      depositAddress,
+      recipientAddress,
+      expiresAt,
+      estimatedTime: this.capabilities.averageExecutionTime,
+      metadata: {
+        backend: this.name,
+        privacyLevel,
+        zcashNetwork: 'mainnet',
+      },
+    }
+
+    // Store quote
+    this.quotes.set(quoteId, quote)
+
+    return quote
+  }
+
+  /**
+   * Get a dry quote (preview without creating deposit address)
+   */
+  async getDryQuote(params: QuoteParams): Promise<Quote> {
+    // For Zcash native, dry quote is the same as regular quote
+    // since we don't need to reserve resources
+    return this.getQuote(params)
+  }
+
+  // ─── Swap Execution ────────────────────────────────────────────────────────
+
+  /**
+   * Execute a ZEC → ZEC swap/transfer
+   */
+  async executeSwap(params: SwapParams): Promise<SwapResult> {
+    const { quoteId, depositTxHash } = params
+
+    // Retrieve quote
+    const quote = this.quotes.get(quoteId)
+    if (!quote) {
+      throw new ValidationError(
+        'Quote not found or expired',
+        'quoteId',
+        { quoteId },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    // Check expiration
+    const now = Math.floor(Date.now() / 1000)
+    if (now > quote.expiresAt) {
+      throw new ValidationError(
+        'Quote has expired',
+        'quoteId',
+        { quoteId, expiresAt: quote.expiresAt, now },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    // Generate swap ID
+    const swapId = this.generateSwapId()
+
+    // Create swap result
+    const result: SwapResult = {
+      swapId,
+      status: depositTxHash ? SwapStatus.DEPOSIT_CONFIRMED : SwapStatus.PENDING_DEPOSIT,
+      quoteId,
+      depositAddress: quote.depositAddress,
+      depositTxHash,
+      metadata: {
+        backend: this.name,
+        recipientAddress: quote.recipientAddress,
+      },
+    }
+
+    // Store swap
+    this.swaps.set(swapId, result)
+
+    // If deposit TX is provided, simulate processing
+    if (depositTxHash) {
+      // In a real implementation, we would:
+      // 1. Verify the deposit transaction on Zcash blockchain
+      // 2. Wait for confirmations
+      // 3. Execute the transfer to recipient
+      // For now, we'll simulate immediate success
+      this.simulateSwapExecution(swapId, quote)
+    }
+
+    return result
+  }
+
+  // ─── Status Methods ────────────────────────────────────────────────────────
+
+  /**
+   * Get swap status
+   */
+  async getStatus(swapId: string): Promise<SwapStatusResponse> {
+    const swap = this.swaps.get(swapId)
+    if (!swap) {
+      throw new ValidationError(
+        'Swap not found',
+        'swapId',
+        { swapId },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    const quote = this.quotes.get(swap.quoteId)
+    if (!quote) {
+      throw new ValidationError(
+        'Quote not found for swap',
+        'quoteId',
+        { quoteId: swap.quoteId },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    const status: SwapStatusResponse = {
+      swapId: swap.swapId,
+      status: swap.status,
+      quoteId: swap.quoteId,
+      depositAddress: swap.depositAddress,
+      amountIn: quote.amountIn,
+      amountOut: quote.amountOut,
+      depositTxHash: swap.depositTxHash,
+      settlementTxHash: swap.settlementTxHash,
+      actualAmountOut: swap.actualAmountOut,
+      errorMessage: swap.errorMessage,
+      updatedAt: Math.floor(Date.now() / 1000),
+      metadata: swap.metadata,
+    }
+
+    return status
+  }
+
+  /**
+   * Wait for swap completion
+   */
+  async waitForCompletion(
+    swapId: string,
+    options?: {
+      interval?: number
+      timeout?: number
+      onStatusChange?: (status: SwapStatusResponse) => void
+    },
+  ): Promise<SwapStatusResponse> {
+    const interval = options?.interval ?? 5000
+    const timeout = options?.timeout ?? 600000 // 10 minutes default
+    const startTime = Date.now()
+
+    while (Date.now() - startTime < timeout) {
+      const status = await this.getStatus(swapId)
+
+      // Notify callback
+      if (options?.onStatusChange) {
+        options.onStatusChange(status)
+      }
+
+      // Check terminal states
+      if (status.status === SwapStatus.SUCCESS) {
+        return status
+      }
+
+      if (
+        status.status === SwapStatus.FAILED ||
+        status.status === SwapStatus.CANCELLED ||
+        status.status === SwapStatus.REFUNDED
+      ) {
+        return status
+      }
+
+      // Wait before next poll
+      await this.delay(interval)
+    }
+
+    // Timeout reached
+    const status = await this.getStatus(swapId)
+    return status
+  }
+
+  /**
+   * Notify backend of deposit
+   */
+  async notifyDeposit(
+    swapId: string,
+    txHash: string,
+    metadata?: Record<string, unknown>,
+  ): Promise<void> {
+    const swap = this.swaps.get(swapId)
+    if (!swap) {
+      throw new ValidationError(
+        'Swap not found',
+        'swapId',
+        { swapId },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    // Update swap with deposit info
+    swap.depositTxHash = txHash
+    swap.status = SwapStatus.DEPOSIT_CONFIRMED
+    if (metadata) {
+      swap.metadata = { ...swap.metadata, ...metadata }
+    }
+
+    this.swaps.set(swapId, swap)
+
+    // Trigger swap execution
+    const quote = this.quotes.get(swap.quoteId)
+    if (quote) {
+      this.simulateSwapExecution(swapId, quote)
+    }
+  }
+
+  // ─── Private Helpers ───────────────────────────────────────────────────────
+
+  private validateQuoteParams(params: QuoteParams): void {
+    // Validate chains
+    if (params.fromChain !== 'zcash') {
+      throw new ValidationError(
+        'Source chain must be zcash',
+        'fromChain',
+        { received: params.fromChain, expected: 'zcash' },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    if (params.toChain !== 'zcash') {
+      throw new ValidationError(
+        'Destination chain must be zcash',
+        'toChain',
+        { received: params.toChain, expected: 'zcash' },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    // Validate tokens
+    if (params.fromToken !== 'ZEC') {
+      throw new ValidationError(
+        'Source token must be ZEC',
+        'fromToken',
+        { received: params.fromToken, expected: 'ZEC' },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    if (params.toToken !== 'ZEC') {
+      throw new ValidationError(
+        'Destination token must be ZEC',
+        'toToken',
+        { received: params.toToken, expected: 'ZEC' },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+
+    // Validate amount
+    if (!params.amount || params.amount <= BigInt(0)) {
+      throw new ValidationError(
+        'Amount must be positive',
+        'amount',
+        { received: params.amount },
+        ErrorCode.INVALID_AMOUNT,
+      )
+    }
+
+    // Validate privacy level
+    if (!this.capabilities.supportedPrivacyLevels.includes(params.privacyLevel)) {
+      throw new ValidationError(
+        'Unsupported privacy level',
+        'privacyLevel',
+        { received: params.privacyLevel, supported: this.capabilities.supportedPrivacyLevels },
+        ErrorCode.VALIDATION_FAILED,
+      )
+    }
+  }
+
+  private simulateSwapExecution(swapId: string, quote: Quote): void {
+    // Simulate async execution
+    setTimeout(() => {
+      const swap = this.swaps.get(swapId)
+      if (!swap) return
+
+      // Update to in progress
+      swap.status = SwapStatus.IN_PROGRESS
+      this.swaps.set(swapId, swap)
+
+      // Simulate completion after delay
+      setTimeout(() => {
+        const finalSwap = this.swaps.get(swapId)
+        if (!finalSwap) return
+
+        finalSwap.status = SwapStatus.SUCCESS
+        finalSwap.settlementTxHash = this.randomHex(64)
+        finalSwap.actualAmountOut = quote.amountOut
+        this.swaps.set(swapId, finalSwap)
+      }, 2000)
+    }, 1000)
+  }
+
+  private generateQuoteId(): string {
+    return `zec_native_quote_${Date.now()}_${this.randomHex(8)}`
+  }
+
+  private generateSwapId(): string {
+    return `zec_native_swap_${Date.now()}_${this.randomHex(8)}`
+  }
+
+  private randomHex(length: number): string {
+    const chars = '0123456789abcdef'
+    let result = ''
+    for (let i = 0; i < length; i++) {
+      result += chars[Math.floor(Math.random() * chars.length)]
+    }
+    return result
+  }
+
+  private randomBase58(length: number): string {
+    const chars = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+    let result = ''
+    for (let i = 0; i < length; i++) {
+      result += chars[Math.floor(Math.random() * chars.length)]
+    }
+    return result
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}
+
+/**
+ * Create a Zcash Native backend instance
+ */
+export function createZcashNativeBackend(
+  config: ZcashNativeBackendConfig,
+): ZcashNativeBackend {
+  return new ZcashNativeBackend(config)
+}

package/src/settlement/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Settlement Backend Abstraction Layer
+ *
+ * Provides a unified interface for multiple settlement backends (NEAR Intents, Zcash, THORChain, etc.)
+ *
+ * @module settlement
+ */
+
+export {
+  SwapStatus,
+  type SettlementBackendName,
+  type QuoteParams,
+  type Quote,
+  type SwapRoute,
+  type SwapRouteStep,
+  type SwapParams,
+  type SwapResult,
+  type SwapStatusResponse,
+  type BackendCapabilities,
+  type SettlementBackend,
+  type SettlementBackendFactory,
+  type SettlementBackendRegistry,
+} from './interface'
+
+export {
+  SettlementRegistry,
+  SettlementRegistryError,
+  type Route,
+} from './registry'
+
+// Router
+export {
+  SmartRouter,
+  createSmartRouter,
+  type RouteWithQuote,
+  type QuoteComparison,
+  type FindBestRouteParams,
+} from './router'
+
+// Backends
+export {
+  NEARIntentsBackend,
+  createNEARIntentsBackend,
+  ZcashNativeBackend,
+  createZcashNativeBackend,
+  type ZcashNativeBackendConfig,
+} from './backends'