minimal-xec-wallet 1.0.1

package/lib/token-protocol-detector.js

@@ -0,0 +1,307 @@
+/*
+  Token Protocol Detection for hybrid SLP + ALP support.
+  Categorizes UTXOs by protocol and provides detection utilities.
+*/
+
+class TokenProtocolDetector {
+  /**
+   * Detect the protocol of a token from a UTXO
+   * @param {Object} utxo - UTXO object from chronik
+   * @returns {string} - 'XEC', 'SLP', or 'ALP'
+   */
+  static detectProtocol (utxo) {
+    if (!utxo || !utxo.token) {
+      return 'XEC'
+    }
+
+    const protocol = utxo.token.tokenType?.protocol
+    switch (protocol) {
+      case 'SLP':
+        return 'SLP'
+      case 'ALP':
+        return 'ALP'
+      default:
+        throw new Error(`Unknown token protocol: ${protocol}`)
+    }
+  }
+
+  /**
+   * Detect token protocol from token metadata
+   * @param {Object} tokenInfo - Token info from chronik.token()
+   * @returns {string} - 'SLP' or 'ALP'
+   */
+  static detectProtocolFromMetadata (tokenInfo) {
+    if (!tokenInfo || !tokenInfo.tokenType) {
+      throw new Error('Invalid token metadata')
+    }
+
+    const protocol = tokenInfo.tokenType.protocol
+    switch (protocol) {
+      case 'SLP':
+        return 'SLP'
+      case 'ALP':
+        return 'ALP'
+      default:
+        throw new Error(`Unknown token protocol: ${protocol}`)
+    }
+  }
+
+  /**
+   * Categorize UTXOs by protocol type
+   * @param {Array} utxos - Array of UTXO objects
+   * @returns {Object} - Categorized UTXOs by protocol
+   */
+  static categorizeUtxos (utxos) {
+    const result = {
+      xecUtxos: [],
+      slpUtxos: [],
+      alpUtxos: [],
+      tokenUtxosByProtocol: new Map(), // protocol -> UTXOs[]
+      tokenUtxosById: new Map(), // tokenId -> UTXOs[]
+      protocolSummary: {
+        xec: { count: 0, totalSats: 0 },
+        slp: { count: 0, tokenTypes: new Set() },
+        alp: { count: 0, tokenTypes: new Set() }
+      }
+    }
+
+    for (const utxo of utxos) {
+      if (!utxo) continue
+      try {
+        const protocol = this.detectProtocol(utxo)
+
+        switch (protocol) {
+          case 'XEC':
+            result.xecUtxos.push(utxo)
+            this._addToProtocolMap(result.tokenUtxosByProtocol, 'XEC', utxo)
+            result.protocolSummary.xec.count++
+            result.protocolSummary.xec.totalSats += this._extractSats(utxo)
+            break
+
+          case 'SLP':
+            result.slpUtxos.push(utxo)
+            this._addToProtocolMap(result.tokenUtxosByProtocol, 'SLP', utxo)
+            this._addToTokenMap(result.tokenUtxosById, utxo.token.tokenId, utxo)
+            result.protocolSummary.slp.count++
+            result.protocolSummary.slp.tokenTypes.add(utxo.token.tokenId)
+            break
+
+          case 'ALP':
+            result.alpUtxos.push(utxo)
+            this._addToProtocolMap(result.tokenUtxosByProtocol, 'ALP', utxo)
+            this._addToTokenMap(result.tokenUtxosById, utxo.token.tokenId, utxo)
+            result.protocolSummary.alp.count++
+            result.protocolSummary.alp.tokenTypes.add(utxo.token.tokenId)
+            break
+        }
+      } catch (err) {
+        console.warn(`Skipping invalid UTXO: ${err.message}`, utxo)
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Filter UTXOs for a specific token ID
+   * @param {Array} utxos - Array of UTXO objects
+   * @param {string} tokenId - Token ID to filter for
+   * @returns {Object} - XEC and token UTXOs for the specific token
+   */
+  static filterUtxosForToken (utxos, tokenId) {
+    const categorized = this.categorizeUtxos(utxos)
+    const tokenUtxos = categorized.tokenUtxosById.get(tokenId) || []
+
+    // Get other UTXOs (not matching the requested tokenId) - includes other tokens AND XEC UTXOs
+    const otherUtxos = [...categorized.xecUtxos]
+    for (const [id, utxoList] of categorized.tokenUtxosById.entries()) {
+      if (id !== tokenId) {
+        otherUtxos.push(...utxoList)
+      }
+    }
+
+    if (tokenUtxos.length === 0) {
+      return {
+        xecUtxos: categorized.xecUtxos,
+        tokenUtxos: [],
+        otherUtxos,
+        protocol: null,
+        tokenSummary: { totalAtoms: 0n, utxoCount: 0 }
+      }
+    }
+
+    // Detect protocol from first token UTXO
+    const protocol = this.detectProtocol(tokenUtxos[0])
+
+    // Calculate token summary
+    const tokenSummary = this._calculateTokenSummary(tokenUtxos, protocol)
+
+    return {
+      xecUtxos: categorized.xecUtxos,
+      tokenUtxos,
+      otherUtxos,
+      protocol,
+      tokenSummary
+    }
+  }
+
+  /**
+   * Get all unique token IDs in wallet with their protocols
+   * @param {Array} utxos - Array of UTXO objects
+   * @returns {Array} - Array of {tokenId, protocol} objects
+   */
+  static getTokenInventory (utxos) {
+    const tokenMap = new Map()
+
+    for (const utxo of utxos) {
+      if (utxo && utxo.token && utxo.token.tokenId) {
+        const tokenId = utxo.token.tokenId
+        if (!tokenMap.has(tokenId)) {
+          try {
+            const protocol = this.detectProtocol(utxo)
+            tokenMap.set(tokenId, {
+              tokenId,
+              protocol,
+              utxoCount: 1,
+              totalAtoms: BigInt(utxo.token.atoms || 0),
+              firstSeen: utxo.blockHeight || -1
+            })
+          } catch (err) {
+            console.warn(`Invalid token UTXO: ${err.message}`)
+          }
+        } else {
+          const entry = tokenMap.get(tokenId)
+          entry.utxoCount++
+          entry.totalAtoms += BigInt(utxo.token.atoms || 0)
+        }
+      }
+    }
+
+    return Array.from(tokenMap.values())
+  }
+
+  /**
+   * Validate token protocol compatibility
+   * @param {string} expectedProtocol - Expected protocol (SLP or ALP)
+   * @param {Object} utxo - UTXO to validate
+   * @returns {boolean} - True if compatible
+   */
+  static validateProtocolCompatibility (expectedProtocol, utxo) {
+    try {
+      const actualProtocol = this.detectProtocol(utxo)
+      return actualProtocol === expectedProtocol
+    } catch (err) {
+      return false
+    }
+  }
+
+  // Private helper methods
+
+  static _addToProtocolMap (protocolMap, protocol, utxo) {
+    if (!protocolMap.has(protocol)) {
+      protocolMap.set(protocol, [])
+    }
+    protocolMap.get(protocol).push(utxo)
+  }
+
+  static _addToTokenMap (tokenMap, tokenId, utxo) {
+    if (!tokenMap.has(tokenId)) {
+      tokenMap.set(tokenId, [])
+    }
+    tokenMap.get(tokenId).push(utxo)
+  }
+
+  static _extractSats (utxo) {
+    if (!utxo || typeof utxo !== 'object') {
+      return 0
+    }
+
+    if (utxo.sats !== undefined) {
+      if (typeof utxo.sats === 'bigint') {
+        return Number(utxo.sats)
+      }
+      if (typeof utxo.sats === 'number') {
+        return utxo.sats
+      }
+      const parsed = parseInt(utxo.sats)
+      return isNaN(parsed) ? 0 : parsed
+    }
+
+    return 0
+  }
+
+  static _calculateTokenSummary (tokenUtxos, protocol) {
+    let totalAtoms = 0n
+    const utxoCount = tokenUtxos.length
+
+    for (const utxo of tokenUtxos) {
+      if (utxo.token && utxo.token.atoms) {
+        totalAtoms += BigInt(utxo.token.atoms)
+      }
+    }
+
+    return {
+      totalAtoms,
+      utxoCount,
+      protocol
+    }
+  }
+
+  /**
+   * Check if wallet contains any tokens
+   * @param {Array} utxos - Array of UTXO objects
+   * @returns {boolean} - True if any tokens found
+   */
+  static hasTokens (utxos) {
+    return utxos.some(utxo => utxo && utxo.token && utxo.token.tokenId)
+  }
+
+  /**
+   * Check if wallet contains specific protocol tokens
+   * @param {Array} utxos - Array of UTXO objects
+   * @param {string} protocol - Protocol to check for ('SLP' or 'ALP')
+   * @returns {boolean} - True if protocol tokens found
+   */
+  static hasProtocolTokens (utxos, protocol) {
+    return utxos.some(utxo => {
+      if (!utxo) return false
+      try {
+        return this.detectProtocol(utxo) === protocol
+      } catch (err) {
+        return false
+      }
+    })
+  }
+
+  /**
+   * Get protocol statistics for wallet
+   * @param {Array} utxos - Array of UTXO objects
+   * @returns {Object} - Protocol statistics
+   */
+  static getProtocolStats (utxos) {
+    const categorized = this.categorizeUtxos(utxos)
+
+    // Build protocols array from active protocols
+    const protocols = []
+    if (categorized.protocolSummary.slp.count > 0) protocols.push('SLP')
+    if (categorized.protocolSummary.alp.count > 0) protocols.push('ALP')
+
+    // Calculate total XEC sats from ALL UTXOs (including dust from token UTXOs)
+    const totalXecSats = utxos.reduce((sum, utxo) => sum + this._extractSats(utxo), 0)
+
+    return {
+      totalUtxos: utxos.length,
+      xecUtxos: categorized.protocolSummary.xec.count,
+      slpTokens: categorized.protocolSummary.slp.tokenTypes.size,
+      slpUtxos: categorized.protocolSummary.slp.count,
+      alpTokens: categorized.protocolSummary.alp.tokenTypes.size,
+      alpUtxos: categorized.protocolSummary.alp.count,
+      totalXecSats,
+      hasTokens: this.hasTokens(utxos),
+      protocols,
+      hasMultipleProtocols: protocols.length > 1
+    }
+  }
+}
+
+module.exports = TokenProtocolDetector

package/lib/utxos.js

@@ -0,0 +1,303 @@
+/*
+  Simplified UTXO management for minimal XEC wallet
+
+  Core functionality only:
+  - Fetch UTXOs from chronik
+  - Basic validation and filtering
+  - Simple caching
+  - Essential security checks
+*/
+
+const SecurityValidator = require('./security')
+
+class Utxos {
+  constructor (localConfig = {}) {
+    this.chronik = localConfig.chronik
+    this.ar = localConfig.ar
+
+    if (!this.ar) {
+      throw new Error('AdapterRouter instance required for UTXO management')
+    }
+
+    // Simple UTXO store
+    this.utxoStore = {
+      xecUtxos: [],
+      lastUpdated: null,
+      cacheKey: null
+    }
+
+    // Security validator
+    this.security = new SecurityValidator(localConfig.security)
+
+    // Simple configuration
+    this.maxRetries = localConfig.maxRetries || 3
+    this.retryDelay = localConfig.retryDelay || 1000
+    this.cacheTimeout = localConfig.cacheTimeout || 30000 // 30 seconds
+
+    // Performance tracking (basic)
+    this.performanceMetrics = {
+      totalRequests: 0,
+      cacheHits: 0,
+      lastRefreshTime: null,
+      totalResponseTime: 0,
+      averageResponseTime: 0
+    }
+  }
+
+  /**
+   * Initialize UTXO store for an address
+   * @param {string} addr - XEC address
+   * @param {boolean} forceRefresh - Force refresh cache
+   * @returns {boolean} - Success status
+   */
+  async initUtxoStore (addr, forceRefresh = false) {
+    try {
+      this.performanceMetrics.totalRequests++
+
+      // Check cache validity
+      if (!forceRefresh && this._isCacheValid(addr)) {
+        this.performanceMetrics.cacheHits++
+        return true
+      }
+
+      // Fetch fresh UTXO data
+      const utxosResult = await this._fetchUtxosWithRetry(addr)
+
+      // Process and store UTXOs
+      this._processUtxos(utxosResult, addr)
+
+      return true
+    } catch (err) {
+      throw new Error(`UTXO initialization failed: ${err.message}`)
+    }
+  }
+
+  /**
+   * Get spendable XEC UTXOs with basic filtering
+   * @param {Object} options - Filtering options
+   * @returns {Array} - Filtered UTXOs
+   */
+  getSpendableXecUtxos (options = {}) {
+    const {
+      includeUnconfirmed = false,
+      excludeDustAttack = true
+    } = options
+
+    // Use security validator for filtering
+    return this.security.filterSecureUtxos(this.utxoStore.xecUtxos, {
+      includeUnconfirmed,
+      excludeDustAttack
+    })
+  }
+
+  /**
+   * Simple UTXO selection (largest first)
+   * @param {number} targetAmount - Target amount in satoshis
+   * @param {Object} options - Selection options
+   * @returns {Object} - Selection result
+   */
+  selectOptimalUtxos (targetAmount, options = {}) {
+    const spendableUtxos = this.getSpendableXecUtxos(options)
+
+    if (spendableUtxos.length === 0) {
+      throw new Error('No spendable UTXOs available')
+    }
+
+    // Sort by value descending (largest first)
+    const sortedUtxos = spendableUtxos.sort((a, b) => {
+      const aValue = this._getUtxoValue(a)
+      const bValue = this._getUtxoValue(b)
+      return bValue - aValue
+    })
+
+    // Simple greedy selection
+    const selectedUtxos = []
+    let totalAmount = 0
+    const inputCost = 148 // P2PKH input size in bytes
+
+    for (const utxo of sortedUtxos) {
+      const utxoValue = this._getUtxoValue(utxo)
+      selectedUtxos.push(utxo)
+      totalAmount += utxoValue
+
+      // Estimate fee
+      const estimatedFee = selectedUtxos.length * inputCost + 34 + 10 // inputs + output + overhead
+
+      if (totalAmount >= targetAmount + estimatedFee) {
+        break
+      }
+    }
+
+    // Check if we have enough
+    const finalFee = selectedUtxos.length * inputCost + 34 + 10
+    if (totalAmount < targetAmount + finalFee) {
+      throw new Error('Insufficient funds')
+    }
+
+    return {
+      selectedUtxos,
+      totalAmount,
+      estimatedFee: finalFee,
+      change: totalAmount - targetAmount - finalFee
+    }
+  }
+
+  /**
+   * Get current balance
+   * @returns {Object} - Balance information
+   */
+  getBalance () {
+    const utxos = this.utxoStore.xecUtxos
+    let confirmed = 0
+    let unconfirmed = 0
+
+    utxos.forEach(utxo => {
+      const value = this._getUtxoValue(utxo)
+      if (utxo.blockHeight === -1) {
+        unconfirmed += value
+      } else {
+        confirmed += value
+      }
+    })
+
+    return {
+      confirmed,
+      unconfirmed,
+      total: confirmed + unconfirmed
+    }
+  }
+
+  /**
+   * Get performance metrics
+   * @returns {Object} - Performance data
+   */
+  getPerformanceMetrics () {
+    const cacheHitRate = this.performanceMetrics.totalRequests > 0
+      ? (this.performanceMetrics.cacheHits / this.performanceMetrics.totalRequests) * 100
+      : 0
+
+    return {
+      cacheHitRate: Math.round(cacheHitRate * 100) / 100,
+      totalRequests: this.performanceMetrics.totalRequests,
+      cacheHits: this.performanceMetrics.cacheHits,
+      averageResponseTime: this.performanceMetrics.averageResponseTime,
+      lastRefreshTime: this.performanceMetrics.lastRefreshTime,
+      utxoCount: this.utxoStore.xecUtxos.length
+    }
+  }
+
+  /**
+   * Clear cache
+   */
+  clearCache () {
+    this.utxoStore = {
+      xecUtxos: [],
+      lastUpdated: null,
+      cacheKey: null
+    }
+  }
+
+  /**
+   * Get spendable eToken UTXOs (Phase 2 - not implemented)
+   * @returns {Array} - Empty array for Phase 1
+   */
+  getSpendableETokenUtxos () {
+    return []
+  }
+
+  /**
+   * Refresh cache for address
+   * @param {string} addr - Address to refresh
+   * @returns {boolean} - Success status
+   */
+  async refreshCache (addr) {
+    return await this.initUtxoStore(addr, true)
+  }
+
+  /**
+   * Filter dust UTXOs (legacy method)
+   * @param {Array} utxos - UTXOs to filter
+   * @returns {Array} - Non-dust UTXOs
+   */
+  _filterDustUtxos (utxos) {
+    return utxos.filter(utxo => this._getUtxoValue(utxo) >= 1000)
+  }
+
+  /**
+   * Sort UTXOs by value (legacy method)
+   * @param {Array} utxos - UTXOs to sort
+   * @param {string} order - 'asc' or 'desc'
+   * @returns {Array} - Sorted UTXOs
+   */
+  _sortUtxosByValue (utxos, order = 'desc') {
+    return [...utxos].sort((a, b) => {
+      const aValue = this._getUtxoValue(a)
+      const bValue = this._getUtxoValue(b)
+      return order === 'desc' ? bValue - aValue : aValue - bValue
+    })
+  }
+
+  // Private methods
+
+  async _fetchUtxosWithRetry (addr, maxRetries = null) {
+    const retryLimit = maxRetries || this.maxRetries
+    let attempt = 1
+
+    while (attempt <= retryLimit) {
+      try {
+        const utxosResult = await this.ar.getUtxos(addr)
+        return utxosResult
+      } catch (err) {
+        if (attempt === retryLimit) {
+          throw new Error(`Failed to fetch UTXOs after ${retryLimit} attempts: ${err.message}`)
+        }
+
+        await this._delay(this.retryDelay * attempt)
+        attempt++
+      }
+    }
+  }
+
+  _processUtxos (utxosResult, addr) {
+    if (!utxosResult || !Array.isArray(utxosResult.utxos)) {
+      throw new Error('Invalid UTXO response format')
+    }
+
+    // Filter and validate UTXOs
+    const validUtxos = utxosResult.utxos.filter(utxo => this._isValidUtxo(utxo))
+
+    // Store UTXOs
+    this.utxoStore.xecUtxos = validUtxos
+    this.utxoStore.lastUpdated = Date.now()
+    this.utxoStore.cacheKey = addr
+    this.performanceMetrics.lastRefreshTime = Date.now()
+  }
+
+  _isValidUtxo (utxo) {
+    return this.security.isValidUtxoStructure(utxo) && this._getUtxoValue(utxo) > 0
+  }
+
+  _getUtxoValue (utxo) {
+    if (utxo.sats !== undefined) {
+      return typeof utxo.sats === 'bigint' ? Number(utxo.sats) : parseInt(utxo.sats)
+    }
+    if (utxo.value !== undefined) {
+      return typeof utxo.value === 'bigint' ? Number(utxo.value) : parseInt(utxo.value)
+    }
+    return 0
+  }
+
+  _isCacheValid (addr) {
+    return (
+      this.utxoStore.cacheKey === addr &&
+      this.utxoStore.lastUpdated &&
+      (Date.now() - this.utxoStore.lastUpdated) < this.cacheTimeout
+    )
+  }
+
+  _delay (ms) {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}
+
+module.exports = Utxos