@sip-protocol/sdk 0.7.2 → 0.7.4

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,
+  }
+}

package/src/surveillance/algorithms/exchange.ts

@@ -0,0 +1,295 @@
+/**
+ * Exchange Exposure Detection Algorithm
+ *
+ * Detects interactions with known exchange addresses to identify
+ * KYC exposure points. Deposits to centralized exchanges are
+ * particularly privacy-degrading as they link on-chain activity
+ * to verified identities.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AnalyzableTransaction,
+  ExchangeExposureResult,
+  KnownExchange,
+} from '../types'
+
+/**
+ * Maximum score deduction for exchange exposure (out of 20)
+ */
+const MAX_DEDUCTION = 20
+
+/**
+ * Deduction per unique CEX (KYC required)
+ */
+const DEDUCTION_PER_CEX = 8
+
+/**
+ * Deduction per unique DEX (no KYC but still traceable)
+ */
+const DEDUCTION_PER_DEX = 2
+
+/**
+ * Known Solana exchange addresses
+ * Sources: Arkham Intelligence, public documentation
+ */
+export const KNOWN_EXCHANGES: KnownExchange[] = [
+  // Centralized Exchanges (KYC Required)
+  {
+    name: 'Binance',
+    addresses: [
+      '5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9',
+      '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+      'AC5RDfQFmDS1deWZos921JfqscXdByf8BKHs5ACWjtW2',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'Coinbase',
+    addresses: [
+      'H8sMJSCQxfKiFTCfDR3DUMLPwcRbM61LGFJ8N4dK3WjS',
+      '2ojv9BAiHUrvsm9gxDe7fJSzbNZSJcxZvf8dqmWGHG8S',
+      'GJRs4FwHtemZ5ZE9x3FNvJ8TMwitKTh21yxdRPqn7npE',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'Kraken',
+    addresses: [
+      'krakenmRKej41L9sX8N8Z2mhjZ8UpVHHBMzkKzfBh54',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'FTX (Defunct)',
+    addresses: [
+      'FTXkd8cjuYGRLzPVdvqxNxNNNYBfFPPjrF3vW2Yq8p7',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'KuCoin',
+    addresses: [
+      'BmFdpraQhkiDQE6SnfG5omcA1VwzqfXrwtNYBwWTymy6',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'OKX',
+    addresses: [
+      'GGztQqQ6pCPaJQnNpXBgELr5cs3WwDakRbh1iEMzjgSJ',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'Bybit',
+    addresses: [
+      'AC5RDfQFmDS1deWZos921JfqscXdByf8BKHs5ACWjtW3',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+  {
+    name: 'Gate.io',
+    addresses: [
+      'u6PJ8DtQuPFnfmwHbGFULQ4u4EgjDiyYKjVEsynXq2w',
+    ],
+    type: 'cex',
+    kycRequired: true,
+  },
+
+  // Decentralized Exchanges (No KYC but traceable)
+  {
+    name: 'Jupiter',
+    addresses: [
+      'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
+      'JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB',
+    ],
+    type: 'dex',
+    kycRequired: false,
+  },
+  {
+    name: 'Raydium',
+    addresses: [
+      '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8',
+      '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1',
+    ],
+    type: 'dex',
+    kycRequired: false,
+  },
+  {
+    name: 'Orca',
+    addresses: [
+      '9W959DqEETiGZocYWCQPaJ6sBmUzgfxXfqGeTEdp3aQP',
+      'whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc',
+    ],
+    type: 'dex',
+    kycRequired: false,
+  },
+  {
+    name: 'Marinade',
+    addresses: [
+      'MarBmsSgKXdrN1egZf5sqe1TMai9K1rChYNDJgjq7aD',
+    ],
+    type: 'dex',
+    kycRequired: false,
+  },
+  {
+    name: 'Phantom Swap',
+    addresses: [
+      'PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY',
+    ],
+    type: 'dex',
+    kycRequired: false,
+  },
+]
+
+/**
+ * Build address lookup map for efficient detection
+ */
+function buildExchangeLookup(
+  exchanges: KnownExchange[]
+): Map<string, KnownExchange> {
+  const lookup = new Map<string, KnownExchange>()
+
+  for (const exchange of exchanges) {
+    for (const address of exchange.addresses) {
+      lookup.set(address, exchange)
+    }
+  }
+
+  return lookup
+}
+
+/**
+ * Detect exchange interactions in transaction history
+ *
+ * @param transactions - Transaction history to analyze
+ * @param walletAddress - The wallet being analyzed
+ * @param customExchanges - Optional custom exchange list
+ * @returns Exchange exposure analysis result
+ *
+ * @example
+ * ```typescript
+ * const result = detectExchangeExposure(transactions, 'abc123...')
+ * console.log(result.exchangeCount) // 2
+ * console.log(result.exchanges[0].name) // 'Binance'
+ * ```
+ */
+export function detectExchangeExposure(
+  transactions: AnalyzableTransaction[],
+  walletAddress: string,
+  customExchanges?: KnownExchange[]
+): ExchangeExposureResult {
+  const exchanges = customExchanges
+    ? [...KNOWN_EXCHANGES, ...customExchanges]
+    : KNOWN_EXCHANGES
+
+  const lookup = buildExchangeLookup(exchanges)
+
+  // Track interactions per exchange
+  const exchangeStats = new Map<
+    string,
+    {
+      exchange: KnownExchange
+      deposits: number
+      withdrawals: number
+      firstInteraction: number
+      lastInteraction: number
+    }
+  >()
+
+  for (const tx of transactions) {
+    if (!tx.success) continue
+
+    // Check all involved addresses
+    for (const addr of tx.involvedAddresses) {
+      const exchange = lookup.get(addr)
+      if (!exchange) continue
+
+      // Initialize stats if first interaction
+      if (!exchangeStats.has(exchange.name)) {
+        exchangeStats.set(exchange.name, {
+          exchange,
+          deposits: 0,
+          withdrawals: 0,
+          firstInteraction: tx.timestamp,
+          lastInteraction: tx.timestamp,
+        })
+      }
+
+      const stats = exchangeStats.get(exchange.name)!
+
+      // Update timestamps
+      stats.firstInteraction = Math.min(stats.firstInteraction, tx.timestamp)
+      stats.lastInteraction = Math.max(stats.lastInteraction, tx.timestamp)
+
+      // Determine deposit vs withdrawal
+      if (tx.sender === walletAddress && tx.recipient === addr) {
+        // Wallet sent TO exchange = deposit
+        stats.deposits++
+      } else if (tx.sender === addr && tx.recipient === walletAddress) {
+        // Exchange sent TO wallet = withdrawal
+        stats.withdrawals++
+      } else if (tx.sender === walletAddress) {
+        // Wallet interacted with exchange (could be swap)
+        stats.deposits++
+      }
+    }
+  }
+
+  // Calculate totals
+  let totalDeposits = 0
+  let totalWithdrawals = 0
+  let cexCount = 0
+  let dexCount = 0
+
+  const exchangeResults: ExchangeExposureResult['exchanges'] = []
+
+  for (const [name, stats] of Array.from(exchangeStats.entries())) {
+    totalDeposits += stats.deposits
+    totalWithdrawals += stats.withdrawals
+
+    if (stats.exchange.type === 'cex') {
+      cexCount++
+    } else {
+      dexCount++
+    }
+
+    exchangeResults.push({
+      name,
+      type: stats.exchange.type,
+      kycRequired: stats.exchange.kycRequired,
+      deposits: stats.deposits,
+      withdrawals: stats.withdrawals,
+      firstInteraction: stats.firstInteraction,
+      lastInteraction: stats.lastInteraction,
+    })
+  }
+
+  // Sort by interaction count (most active first)
+  exchangeResults.sort(
+    (a, b) => b.deposits + b.withdrawals - (a.deposits + a.withdrawals)
+  )
+
+  // Calculate score deduction
+  const cexDeduction = cexCount * DEDUCTION_PER_CEX
+  const dexDeduction = dexCount * DEDUCTION_PER_DEX
+  const rawDeduction = cexDeduction + dexDeduction
+  const scoreDeduction = Math.min(rawDeduction, MAX_DEDUCTION)
+
+  return {
+    exchangeCount: exchangeStats.size,
+    depositCount: totalDeposits,
+    withdrawalCount: totalWithdrawals,
+    scoreDeduction,
+    exchanges: exchangeResults,
+  }
+}