@sip-protocol/sdk 0.7.2 → 0.7.3

package/src/privacy-backends/sip-native.ts

@@ -0,0 +1,253 @@
+/**
+ * SIP Native Privacy Backend
+ *
+ * Implements the PrivacyBackend interface using SIP's native privacy primitives:
+ * - Stealth addresses (EIP-5564 style)
+ * - Pedersen commitments (amount hiding)
+ * - Viewing keys (compliance support)
+ *
+ * @example
+ * ```typescript
+ * import { SIPNativeBackend, PrivacyBackendRegistry } from '@sip-protocol/sdk'
+ *
+ * const backend = new SIPNativeBackend()
+ * const registry = new PrivacyBackendRegistry()
+ * registry.register(backend)
+ *
+ * // Check capabilities
+ * const caps = backend.getCapabilities()
+ * console.log(caps.complianceSupport) // true
+ *
+ * // Execute transfer
+ * const result = await backend.execute({
+ *   chain: 'solana',
+ *   sender: 'sender-address',
+ *   recipient: 'stealth-address',
+ *   mint: 'token-mint',
+ *   amount: BigInt(1000000),
+ *   decimals: 6,
+ * })
+ * ```
+ */
+
+import type { ChainType } from '@sip-protocol/types'
+import type {
+  PrivacyBackend,
+  BackendType,
+  BackendCapabilities,
+  TransferParams,
+  TransactionResult,
+  AvailabilityResult,
+} from './interface'
+
+/**
+ * Supported chains for SIP Native backend
+ */
+const SUPPORTED_CHAINS: ChainType[] = [
+  'solana',
+  'ethereum',
+  'near',
+  'polygon',
+  'arbitrum',
+  'optimism',
+  'base',
+  'avalanche',
+  'bsc',
+]
+
+/**
+ * SIP Native backend capabilities
+ */
+const SIP_NATIVE_CAPABILITIES: BackendCapabilities = {
+  hiddenAmount: true,
+  hiddenSender: true,
+  hiddenRecipient: true,
+  hiddenCompute: false,
+  complianceSupport: true,
+  anonymitySet: undefined, // Not pool-based
+  setupRequired: false,
+  latencyEstimate: 'fast',
+  supportedTokens: 'all',
+  minAmount: undefined,
+  maxAmount: undefined,
+}
+
+/**
+ * Configuration options for SIP Native backend
+ */
+export interface SIPNativeBackendConfig {
+  /** Custom supported chains (overrides default) */
+  chains?: ChainType[]
+  /** Whether to require viewing keys for all transfers */
+  requireViewingKey?: boolean
+  /** Minimum amount for transfers (optional) */
+  minAmount?: bigint
+  /** Maximum amount for transfers (optional) */
+  maxAmount?: bigint
+}
+
+/**
+ * SIP Native Privacy Backend
+ *
+ * Uses stealth addresses and Pedersen commitments for transaction privacy,
+ * with viewing key support for regulatory compliance.
+ */
+export class SIPNativeBackend implements PrivacyBackend {
+  readonly name = 'sip-native'
+  readonly type: BackendType = 'transaction'
+  readonly chains: ChainType[]
+
+  private config: Required<SIPNativeBackendConfig>
+
+  /**
+   * Create a new SIP Native backend
+   *
+   * @param config - Backend configuration
+   */
+  constructor(config: SIPNativeBackendConfig = {}) {
+    this.chains = config.chains ?? SUPPORTED_CHAINS
+    this.config = {
+      chains: this.chains,
+      requireViewingKey: config.requireViewingKey ?? false,
+      minAmount: config.minAmount ?? BigInt(0),
+      maxAmount: config.maxAmount ?? BigInt(Number.MAX_SAFE_INTEGER),
+    }
+  }
+
+  /**
+   * Check if backend is available for given parameters
+   */
+  async checkAvailability(params: TransferParams): Promise<AvailabilityResult> {
+    // Check chain support
+    if (!this.chains.includes(params.chain)) {
+      return {
+        available: false,
+        reason: `Chain '${params.chain}' not supported by SIP Native backend`,
+      }
+    }
+
+    // Check viewing key requirement
+    if (this.config.requireViewingKey && !params.viewingKey) {
+      return {
+        available: false,
+        reason: 'Viewing key required for SIP Native backend',
+      }
+    }
+
+    // Check amount bounds
+    if (params.amount < this.config.minAmount) {
+      return {
+        available: false,
+        reason: `Amount ${params.amount} below minimum ${this.config.minAmount}`,
+      }
+    }
+
+    if (params.amount > this.config.maxAmount) {
+      return {
+        available: false,
+        reason: `Amount ${params.amount} above maximum ${this.config.maxAmount}`,
+      }
+    }
+
+    // Estimate cost based on chain
+    const estimatedCost = this.getEstimatedCostForChain(params.chain)
+
+    return {
+      available: true,
+      estimatedCost,
+      estimatedTime: 1000, // ~1 second for stealth address operations
+    }
+  }
+
+  /**
+   * Get backend capabilities
+   */
+  getCapabilities(): BackendCapabilities {
+    return {
+      ...SIP_NATIVE_CAPABILITIES,
+      minAmount: this.config.minAmount > BigInt(0) ? this.config.minAmount : undefined,
+      maxAmount: this.config.maxAmount < BigInt(Number.MAX_SAFE_INTEGER)
+        ? this.config.maxAmount
+        : undefined,
+    }
+  }
+
+  /**
+   * Execute a privacy-preserving transfer
+   *
+   * This creates a stealth address transfer with:
+   * - Ephemeral keypair generation
+   * - Stealth address derivation
+   * - Pedersen commitment for amount
+   * - Optional viewing key encryption
+   */
+  async execute(params: TransferParams): Promise<TransactionResult> {
+    // Validate availability first
+    const availability = await this.checkAvailability(params)
+    if (!availability.available) {
+      return {
+        success: false,
+        error: availability.reason,
+        backend: this.name,
+      }
+    }
+
+    try {
+      // In a real implementation, this would:
+      // 1. Generate ephemeral keypair
+      // 2. Derive stealth address from recipient's meta-address
+      // 3. Create Pedersen commitment for amount
+      // 4. Build and submit transaction
+      // 5. Optionally encrypt data for viewing key
+
+      // For now, return a simulated successful result
+      // Real implementation depends on chain-specific adapters
+      const simulatedSignature = `sim_${Date.now()}_${Math.random().toString(36).slice(2)}`
+
+      return {
+        success: true,
+        signature: simulatedSignature,
+        backend: this.name,
+        metadata: {
+          chain: params.chain,
+          amount: params.amount.toString(),
+          hasViewingKey: !!params.viewingKey,
+          timestamp: Date.now(),
+        },
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        backend: this.name,
+      }
+    }
+  }
+
+  /**
+   * Estimate cost for a transfer
+   */
+  async estimateCost(params: TransferParams): Promise<bigint> {
+    return this.getEstimatedCostForChain(params.chain)
+  }
+
+  /**
+   * Get estimated cost based on chain
+   */
+  private getEstimatedCostForChain(chain: ChainType): bigint {
+    // Estimated costs in smallest chain units
+    const costMap: Partial<Record<ChainType, bigint>> = {
+      solana: BigInt(5000), // ~0.000005 SOL
+      ethereum: BigInt('50000000000000'), // ~0.00005 ETH
+      near: BigInt('1000000000000000000000'), // ~0.001 NEAR
+      polygon: BigInt('50000000000000'), // ~0.00005 MATIC
+      arbitrum: BigInt('50000000000000'),
+      optimism: BigInt('50000000000000'),
+      base: BigInt('50000000000000'),
+      avalanche: BigInt('50000000000000'),
+      bsc: BigInt('50000000000000'),
+    }
+
+    return costMap[chain] ?? BigInt(0)
+  }
+}

package/src/proofs/noir.ts

@@ -801,7 +801,7 @@ export class NoirProofProvider implements ProofProvider {
       // Verify the proof
       const isValid = await backend.verifyProof({
         proof: proofBytes,
-        publicInputs: proof.publicInputs.map(input =>
+        publicInputs: proof.publicInputs.map((input: string) =>
           input.startsWith('0x') ? input.slice(2) : input
         ),
       })

package/src/surveillance/algorithms/address-reuse.ts

@@ -0,0 +1,143 @@
+/**
+ * Address Reuse Detection Algorithm
+ *
+ * Detects when the same address is used multiple times for receiving
+ * or sending transactions, which degrades privacy by creating linkability.
+ *
+ * @packageDocumentation
+ */
+
+import type { AnalyzableTransaction, AddressReuseResult } from '../types'
+
+/**
+ * Maximum score deduction for address reuse (out of 25)
+ */
+const MAX_DEDUCTION = 25
+
+/**
+ * Deduction per reuse instance
+ */
+const DEDUCTION_PER_REUSE = 2
+
+/**
+ * Threshold before counting as reuse (first use is free)
+ */
+const REUSE_THRESHOLD = 1
+
+/**
+ * Analyze address reuse patterns in transaction history
+ *
+ * @param transactions - Transaction history to analyze
+ * @param walletAddress - The wallet being analyzed
+ * @returns Address reuse analysis result
+ *
+ * @example
+ * ```typescript
+ * const result = analyzeAddressReuse(transactions, 'abc123...')
+ * console.log(result.totalReuseCount) // 12
+ * console.log(result.scoreDeduction)  // 24 (capped at 25)
+ * ```
+ */
+export function analyzeAddressReuse(
+  transactions: AnalyzableTransaction[],
+  walletAddress: string
+): AddressReuseResult {
+  // Track address usage counts
+  const receiveAddresses = new Map<string, number>()
+  const sendAddresses = new Map<string, number>()
+
+  for (const tx of transactions) {
+    if (!tx.success) continue
+
+    // Count receives (wallet is recipient)
+    if (tx.recipient === walletAddress) {
+      const count = receiveAddresses.get(walletAddress) ?? 0
+      receiveAddresses.set(walletAddress, count + 1)
+    }
+
+    // Count sends (wallet is sender)
+    if (tx.sender === walletAddress) {
+      const count = sendAddresses.get(walletAddress) ?? 0
+      sendAddresses.set(walletAddress, count + 1)
+    }
+
+    // Also track any other addresses the wallet has used
+    // (e.g., associated token accounts, derived addresses)
+    for (const addr of tx.involvedAddresses) {
+      if (addr === walletAddress) continue
+
+      // If this address appears multiple times with the wallet,
+      // it might indicate reuse of derived addresses
+      if (tx.sender === walletAddress) {
+        const count = sendAddresses.get(addr) ?? 0
+        sendAddresses.set(addr, count + 1)
+      }
+      if (tx.recipient === walletAddress) {
+        const count = receiveAddresses.get(addr) ?? 0
+        receiveAddresses.set(addr, count + 1)
+      }
+    }
+  }
+
+  // Calculate reuse counts
+  let receiveReuseCount = 0
+  let sendReuseCount = 0
+  const reusedAddresses: AddressReuseResult['reusedAddresses'] = []
+
+  // Process receive addresses
+  for (const [address, count] of Array.from(receiveAddresses.entries())) {
+    if (count > REUSE_THRESHOLD) {
+      const reuseCount = count - REUSE_THRESHOLD
+      receiveReuseCount += reuseCount
+
+      const existing = reusedAddresses.find((r) => r.address === address)
+      if (existing) {
+        existing.useCount = Math.max(existing.useCount, count)
+        existing.type = 'both'
+      } else {
+        reusedAddresses.push({
+          address,
+          useCount: count,
+          type: 'receive',
+        })
+      }
+    }
+  }
+
+  // Process send addresses
+  for (const [address, count] of Array.from(sendAddresses.entries())) {
+    if (count > REUSE_THRESHOLD) {
+      const reuseCount = count - REUSE_THRESHOLD
+      sendReuseCount += reuseCount
+
+      const existing = reusedAddresses.find((r) => r.address === address)
+      if (existing) {
+        existing.useCount = Math.max(existing.useCount, count)
+        existing.type = 'both'
+      } else {
+        reusedAddresses.push({
+          address,
+          useCount: count,
+          type: 'send',
+        })
+      }
+    }
+  }
+
+  const totalReuseCount = receiveReuseCount + sendReuseCount
+
+  // Calculate score deduction
+  const rawDeduction = totalReuseCount * DEDUCTION_PER_REUSE
+  const scoreDeduction = Math.min(rawDeduction, MAX_DEDUCTION)
+
+  // Sort reused addresses by use count (most reused first)
+  reusedAddresses.sort((a, b) => b.useCount - a.useCount)
+
+  return {
+    receiveReuseCount,
+    sendReuseCount,
+    totalReuseCount,
+    scoreDeduction,
+    reusedAddresses: reusedAddresses.slice(0, 10), // Top 10 most reused
+  }
+}

package/src/surveillance/algorithms/cluster.ts

@@ -0,0 +1,247 @@
+/**
+ * Cluster Detection Algorithm (Common Input Ownership Heuristic)
+ *
+ * Identifies addresses that are likely owned by the same entity
+ * by analyzing transaction patterns:
+ *
+ * 1. Common Input Heuristic: Multiple inputs in same tx = same owner
+ * 2. Change Address Detection: Change outputs likely go to owner
+ * 3. Consolidation Patterns: Merging funds indicates ownership
+ *
+ * @packageDocumentation
+ */
+
+import type { AnalyzableTransaction, ClusterResult } from '../types'
+
+/**
+ * Maximum score deduction for cluster exposure (out of 25)
+ */
+const MAX_DEDUCTION = 25
+
+/**
+ * Deduction per linked address
+ */
+const DEDUCTION_PER_LINK = 3
+
+/**
+ * Minimum transactions between addresses to consider linked
+ */
+const MIN_LINK_THRESHOLD = 2
+
+/**
+ * Union-Find data structure for efficient cluster management
+ */
+class UnionFind {
+  private parent: Map<string, string>
+  private rank: Map<string, number>
+
+  constructor() {
+    this.parent = new Map()
+    this.rank = new Map()
+  }
+
+  find(x: string): string {
+    if (!this.parent.has(x)) {
+      this.parent.set(x, x)
+      this.rank.set(x, 0)
+    }
+
+    if (this.parent.get(x) !== x) {
+      this.parent.set(x, this.find(this.parent.get(x)!))
+    }
+
+    return this.parent.get(x)!
+  }
+
+  union(x: string, y: string): void {
+    const rootX = this.find(x)
+    const rootY = this.find(y)
+
+    if (rootX === rootY) return
+
+    const rankX = this.rank.get(rootX) ?? 0
+    const rankY = this.rank.get(rootY) ?? 0
+
+    if (rankX < rankY) {
+      this.parent.set(rootX, rootY)
+    } else if (rankX > rankY) {
+      this.parent.set(rootY, rootX)
+    } else {
+      this.parent.set(rootY, rootX)
+      this.rank.set(rootX, rankX + 1)
+    }
+  }
+
+  getClusters(): Map<string, string[]> {
+    const clusters = new Map<string, string[]>()
+
+    for (const addr of Array.from(this.parent.keys())) {
+      const root = this.find(addr)
+      if (!clusters.has(root)) {
+        clusters.set(root, [])
+      }
+      clusters.get(root)!.push(addr)
+    }
+
+    return clusters
+  }
+}
+
+/**
+ * Detect address clusters using Common Input Ownership Heuristic
+ *
+ * @param transactions - Transaction history to analyze
+ * @param walletAddress - The wallet being analyzed
+ * @returns Cluster detection result
+ *
+ * @example
+ * ```typescript
+ * const result = detectClusters(transactions, 'abc123...')
+ * console.log(result.linkedAddressCount) // 5
+ * console.log(result.clusters[0].linkType) // 'common-input'
+ * ```
+ */
+export function detectClusters(
+  transactions: AnalyzableTransaction[],
+  walletAddress: string
+): ClusterResult {
+  const uf = new UnionFind()
+  const linkCounts = new Map<string, number>()
+  const linkTypes = new Map<string, 'common-input' | 'change-address' | 'consolidation'>()
+  const txCountPerPair = new Map<string, number>()
+
+  // Always include the wallet address
+  uf.find(walletAddress)
+
+  for (const tx of transactions) {
+    if (!tx.success) continue
+
+    const involvedWithWallet = tx.involvedAddresses.filter(
+      (addr) => addr !== walletAddress
+    )
+
+    // Common Input Heuristic: If wallet sends with other inputs,
+    // those inputs are likely controlled by same entity
+    if (tx.sender === walletAddress && involvedWithWallet.length > 0) {
+      for (const addr of involvedWithWallet) {
+        // Count how many times we see this relationship
+        const pairKey = [walletAddress, addr].sort().join(':')
+        const count = (txCountPerPair.get(pairKey) ?? 0) + 1
+        txCountPerPair.set(pairKey, count)
+
+        if (count >= MIN_LINK_THRESHOLD) {
+          uf.union(walletAddress, addr)
+          linkCounts.set(addr, count)
+          linkTypes.set(addr, 'common-input')
+        }
+      }
+    }
+
+    // Change Address Detection: Small outputs after a large tx
+    // often go to change addresses owned by the sender
+    if (tx.sender === walletAddress && tx.recipient !== walletAddress) {
+      // Look for other outputs in the same transaction to the wallet
+      // This is a simplified heuristic
+      const otherRecipients = involvedWithWallet.filter(
+        (addr) => addr !== tx.recipient
+      )
+
+      for (const addr of otherRecipients) {
+        const pairKey = [walletAddress, addr].sort().join(':')
+        const count = (txCountPerPair.get(pairKey) ?? 0) + 1
+        txCountPerPair.set(pairKey, count)
+
+        if (count >= MIN_LINK_THRESHOLD) {
+          uf.union(walletAddress, addr)
+          if (!linkTypes.has(addr)) {
+            linkTypes.set(addr, 'change-address')
+          }
+          linkCounts.set(addr, count)
+        }
+      }
+    }
+
+    // Consolidation Pattern: Multiple inputs merged into one output
+    // All inputs likely owned by same entity
+    if (tx.recipient === walletAddress && involvedWithWallet.length > 1) {
+      // Multiple addresses sent to this wallet in same tx = consolidation
+      for (let i = 0; i < involvedWithWallet.length; i++) {
+        for (let j = i + 1; j < involvedWithWallet.length; j++) {
+          const addr1 = involvedWithWallet[i]
+          const addr2 = involvedWithWallet[j]
+          const pairKey = [addr1, addr2].sort().join(':')
+          const count = (txCountPerPair.get(pairKey) ?? 0) + 1
+          txCountPerPair.set(pairKey, count)
+
+          if (count >= MIN_LINK_THRESHOLD) {
+            uf.union(addr1, addr2)
+            linkTypes.set(addr1, 'consolidation')
+            linkTypes.set(addr2, 'consolidation')
+          }
+        }
+
+        // Also link to wallet
+        const pairKey = [walletAddress, involvedWithWallet[i]].sort().join(':')
+        const count = (txCountPerPair.get(pairKey) ?? 0) + 1
+        txCountPerPair.set(pairKey, count)
+
+        if (count >= MIN_LINK_THRESHOLD) {
+          uf.union(walletAddress, involvedWithWallet[i])
+          linkCounts.set(involvedWithWallet[i], count)
+        }
+      }
+    }
+  }
+
+  // Get clusters containing the wallet
+  const allClusters = uf.getClusters()
+  const walletRoot = uf.find(walletAddress)
+  const walletCluster = allClusters.get(walletRoot) ?? [walletAddress]
+
+  // Count linked addresses (excluding the wallet itself)
+  const linkedAddresses = walletCluster.filter((addr) => addr !== walletAddress)
+  const linkedAddressCount = linkedAddresses.length
+
+  // Calculate confidence based on transaction counts
+  const totalLinkTxs = Array.from(linkCounts.values()).reduce((a, b) => a + b, 0)
+  const confidence = Math.min(totalLinkTxs / (linkedAddressCount * 5), 1)
+
+  // Calculate score deduction
+  const rawDeduction = linkedAddressCount * DEDUCTION_PER_LINK
+  const scoreDeduction = Math.min(rawDeduction, MAX_DEDUCTION)
+
+  // Build cluster details
+  const clusters: ClusterResult['clusters'] = []
+
+  if (linkedAddressCount > 0) {
+    // Group by link type
+    const byType = new Map<string, string[]>()
+    for (const addr of linkedAddresses) {
+      const type = linkTypes.get(addr) ?? 'common-input'
+      if (!byType.has(type)) {
+        byType.set(type, [])
+      }
+      byType.get(type)!.push(addr)
+    }
+
+    for (const [type, addresses] of Array.from(byType.entries())) {
+      const txCount = addresses.reduce(
+        (sum, addr) => sum + (linkCounts.get(addr) ?? 0),
+        0
+      )
+
+      clusters.push({
+        addresses: [walletAddress, ...addresses],
+        linkType: type as 'common-input' | 'change-address' | 'consolidation',
+        transactionCount: txCount,
+      })
+    }
+  }
+
+  return {
+    linkedAddressCount,
+    confidence,
+    scoreDeduction,
+    clusters,
+  }
+}