@sip-protocol/sdk 0.7.2 → 0.7.3

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

package/src/surveillance/algorithms/temporal.ts

@@ -0,0 +1,337 @@
+/**
+ * Temporal Pattern Detection Algorithm
+ *
+ * Analyzes transaction timing patterns to detect:
+ * - Regular schedules (e.g., weekly DCA, monthly payments)
+ * - Timezone inference from activity hours
+ * - Activity bursts that might indicate specific events
+ *
+ * These patterns can be used to de-anonymize users.
+ *
+ * @packageDocumentation
+ */
+
+import type { AnalyzableTransaction, TemporalPatternResult } from '../types'
+
+/**
+ * Maximum score deduction for temporal patterns (out of 15)
+ */
+const MAX_DEDUCTION = 15
+
+/**
+ * Deduction per detected pattern
+ */
+const DEDUCTION_PER_PATTERN = 5
+
+/**
+ * Minimum transactions to detect patterns
+ */
+const MIN_TRANSACTIONS_FOR_PATTERN = 5
+
+/**
+ * Threshold for considering a day-of-week as "regular"
+ * (percentage of transactions on that day)
+ */
+const DAY_REGULARITY_THRESHOLD = 0.3
+
+/**
+ * Threshold for considering an hour as "regular"
+ */
+const HOUR_REGULARITY_THRESHOLD = 0.25
+
+/**
+ * Timezone offset possibilities (UTC offsets)
+ */
+const TIMEZONES: Record<string, number> = {
+  'UTC-12': -12,
+  'UTC-11': -11,
+  'HST': -10,
+  'AKST': -9,
+  'PST': -8,
+  'MST': -7,
+  'CST': -6,
+  'EST': -5,
+  'AST': -4,
+  'BRT': -3,
+  'UTC-2': -2,
+  'UTC-1': -1,
+  'UTC': 0,
+  'CET': 1,
+  'EET': 2,
+  'MSK': 3,
+  'GST': 4,
+  'PKT': 5,
+  'BST': 6,
+  'ICT': 7,
+  'CST_ASIA': 8,
+  'JST': 9,
+  'AEST': 10,
+  'AEDT': 11,
+  'NZST': 12,
+}
+
+/**
+ * Analyze temporal patterns in transaction history
+ *
+ * @param transactions - Transaction history to analyze
+ * @returns Temporal pattern analysis result
+ *
+ * @example
+ * ```typescript
+ * const result = analyzeTemporalPatterns(transactions)
+ * console.log(result.patterns[0].type) // 'regular-schedule'
+ * console.log(result.inferredTimezone) // 'EST'
+ * ```
+ */
+export function analyzeTemporalPatterns(
+  transactions: AnalyzableTransaction[]
+): TemporalPatternResult {
+  const patterns: TemporalPatternResult['patterns'] = []
+
+  if (transactions.length < MIN_TRANSACTIONS_FOR_PATTERN) {
+    return {
+      patterns: [],
+      scoreDeduction: 0,
+    }
+  }
+
+  // Extract timing data
+  const txTimes = transactions
+    .filter((tx) => tx.success && tx.timestamp > 0)
+    .map((tx) => new Date(tx.timestamp * 1000))
+
+  if (txTimes.length < MIN_TRANSACTIONS_FOR_PATTERN) {
+    return {
+      patterns: [],
+      scoreDeduction: 0,
+    }
+  }
+
+  // Analyze day-of-week distribution
+  const dayOfWeekPattern = analyzeDayOfWeekPattern(txTimes)
+  if (dayOfWeekPattern) {
+    patterns.push(dayOfWeekPattern)
+  }
+
+  // Analyze hour-of-day distribution
+  const hourPattern = analyzeHourPattern(txTimes)
+  if (hourPattern) {
+    patterns.push(hourPattern)
+  }
+
+  // Detect timezone from activity hours
+  const inferredTimezone = inferTimezone(txTimes)
+
+  // Detect activity bursts
+  const burstPattern = detectActivityBursts(transactions)
+  if (burstPattern) {
+    patterns.push(burstPattern)
+  }
+
+  // Calculate score deduction
+  const rawDeduction = patterns.length * DEDUCTION_PER_PATTERN
+  const scoreDeduction = Math.min(rawDeduction, MAX_DEDUCTION)
+
+  return {
+    patterns,
+    inferredTimezone,
+    scoreDeduction,
+  }
+}
+
+/**
+ * Analyze day-of-week transaction patterns
+ */
+function analyzeDayOfWeekPattern(
+  times: Date[]
+): TemporalPatternResult['patterns'][0] | null {
+  const dayCount = new Array(7).fill(0)
+
+  for (const time of times) {
+    dayCount[time.getUTCDay()]++
+  }
+
+  // Find dominant days
+  const total = times.length
+  const dominantDays: number[] = []
+
+  for (let day = 0; day < 7; day++) {
+    const percentage = dayCount[day] / total
+    if (percentage >= DAY_REGULARITY_THRESHOLD) {
+      dominantDays.push(day)
+    }
+  }
+
+  if (dominantDays.length === 0 || dominantDays.length > 3) {
+    return null // No clear pattern or too spread out
+  }
+
+  const dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+  const dominantDayNames = dominantDays.map((d) => dayNames[d]).join(', ')
+
+  return {
+    type: 'regular-schedule',
+    description: `Most transactions occur on ${dominantDayNames}`,
+    confidence: Math.max(...dominantDays.map((d) => dayCount[d] / total)),
+    evidence: {
+      dayOfWeek: dominantDays,
+    },
+  }
+}
+
+/**
+ * Analyze hour-of-day transaction patterns
+ */
+function analyzeHourPattern(
+  times: Date[]
+): TemporalPatternResult['patterns'][0] | null {
+  const hourCount = new Array(24).fill(0)
+
+  for (const time of times) {
+    hourCount[time.getUTCHours()]++
+  }
+
+  // Find active hours (group into 3-hour windows)
+  const total = times.length
+  const activeHours: number[] = []
+
+  for (let hour = 0; hour < 24; hour++) {
+    // Consider 3-hour windows
+    const windowCount =
+      hourCount[hour] +
+      hourCount[(hour + 1) % 24] +
+      hourCount[(hour + 2) % 24]
+    const windowPercentage = windowCount / total
+
+    if (windowPercentage >= HOUR_REGULARITY_THRESHOLD) {
+      if (!activeHours.includes(hour)) {
+        activeHours.push(hour)
+      }
+    }
+  }
+
+  if (activeHours.length === 0 || activeHours.length > 8) {
+    return null // No clear pattern
+  }
+
+  // Check if activity is concentrated (privacy risk)
+  const activeHourRange = Math.max(...activeHours) - Math.min(...activeHours)
+
+  if (activeHourRange <= 6) {
+    const startHour = Math.min(...activeHours)
+    const endHour = Math.max(...activeHours) + 2
+
+    return {
+      type: 'timezone-inference',
+      description: `Activity concentrated between ${startHour}:00-${endHour}:00 UTC`,
+      confidence: 0.7,
+      evidence: {
+        hourOfDay: activeHours,
+      },
+    }
+  }
+
+  return null
+}
+
+/**
+ * Infer timezone from activity patterns
+ * Assumes user is active during waking hours (8am-11pm local time)
+ */
+function inferTimezone(times: Date[]): string | undefined {
+  const hourCount = new Array(24).fill(0)
+
+  for (const time of times) {
+    hourCount[time.getUTCHours()]++
+  }
+
+  // Find the 8-hour window with most activity
+  let maxActivity = 0
+  let bestStartHour = 0
+
+  for (let start = 0; start < 24; start++) {
+    let windowActivity = 0
+    for (let i = 0; i < 8; i++) {
+      windowActivity += hourCount[(start + i) % 24]
+    }
+
+    if (windowActivity > maxActivity) {
+      maxActivity = windowActivity
+      bestStartHour = start
+    }
+  }
+
+  // If activity is concentrated, infer timezone
+  const totalActivity = times.length
+  if (maxActivity / totalActivity < 0.6) {
+    return undefined // Activity too spread out
+  }
+
+  // Assume peak activity is around 10am-6pm local time
+  // So if peak starts at hour X UTC, user is probably at UTC+(14-X) or similar
+  const assumedLocalNoon = 12
+  const peakMidpoint = (bestStartHour + 4) % 24
+  const inferredOffset = (assumedLocalNoon - peakMidpoint + 24) % 24
+
+  // Find closest timezone
+  const normalizedOffset = inferredOffset > 12 ? inferredOffset - 24 : inferredOffset
+
+  for (const [name, offset] of Object.entries(TIMEZONES)) {
+    if (Math.abs(offset - normalizedOffset) <= 1) {
+      return name
+    }
+  }
+
+  return `UTC${normalizedOffset >= 0 ? '+' : ''}${normalizedOffset}`
+}
+
+/**
+ * Detect unusual activity bursts
+ */
+function detectActivityBursts(
+  transactions: AnalyzableTransaction[]
+): TemporalPatternResult['patterns'][0] | null {
+  if (transactions.length < 10) {
+    return null
+  }
+
+  // Sort by timestamp
+  const sorted = [...transactions]
+    .filter((tx) => tx.timestamp > 0)
+    .sort((a, b) => a.timestamp - b.timestamp)
+
+  // Calculate gaps between transactions
+  const gaps: number[] = []
+  for (let i = 1; i < sorted.length; i++) {
+    gaps.push(sorted[i].timestamp - sorted[i - 1].timestamp)
+  }
+
+  // Calculate average gap
+  const avgGap = gaps.reduce((a, b) => a + b, 0) / gaps.length
+
+  // Find bursts (gaps < 10% of average)
+  const burstThreshold = avgGap * 0.1
+  let burstCount = 0
+
+  for (const gap of gaps) {
+    if (gap < burstThreshold && gap < 3600) {
+      // Less than 1 hour
+      burstCount++
+    }
+  }
+
+  const burstPercentage = burstCount / gaps.length
+
+  if (burstPercentage > 0.2) {
+    return {
+      type: 'activity-burst',
+      description: `${Math.round(burstPercentage * 100)}% of transactions occur in rapid succession`,
+      confidence: burstPercentage,
+      evidence: {
+        frequency: `${burstCount} bursts detected`,
+      },
+    }
+  }
+
+  return null
+}