minimal-xec-wallet 1.0.1

package/examples/wallet-info/get-utxos.js

@@ -0,0 +1,145 @@
+/*
+  Get the UTXOs (Unspent Transaction Outputs) of your wallet.
+  This example shows how to view all spendable outputs in your wallet.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+async function getUtxos () {
+  try {
+    console.log('🔍 Getting wallet UTXOs...\n')
+
+    // Load wallet from file
+    const walletData = WalletHelper.loadWallet()
+    if (!walletData) {
+      console.log('   Run: node examples/wallet-creation/create-new-wallet.js')
+      return
+    }
+
+    // Create wallet instance from saved data
+    const wallet = new MinimalXECWallet(walletData.mnemonic || walletData.privateKey)
+    await wallet.walletInfoPromise
+
+    console.log('🔗 Fetching UTXOs from blockchain...')
+
+    // Get UTXOs for the wallet
+    const utxoData = await wallet.getUtxos()
+    const utxos = utxoData.utxos || []
+
+    console.log('\n📦 UTXO Information:')
+    console.log('═'.repeat(70))
+    console.log(`XEC Address: ${walletData.xecAddress}`)
+    console.log(`Total UTXOs: ${utxos.length}`)
+    console.log('═'.repeat(70))
+
+    if (utxos.length === 0) {
+      console.log('\n💸 No UTXOs found!')
+      console.log('   Your wallet has no spendable outputs.')
+      console.log('   This means either:')
+      console.log('   • Your wallet is empty')
+      console.log('   • All funds are in unconfirmed transactions')
+      console.log('   • The address has never received any XEC')
+      return
+    }
+
+    // Group UTXOs by confirmation status
+    const confirmedUtxos = utxos.filter(utxo => utxo.blockHeight !== -1)
+    const unconfirmedUtxos = utxos.filter(utxo => utxo.blockHeight === -1)
+
+    // Calculate totals - handle sats field properly
+    const 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
+    }
+
+    const totalConfirmed = confirmedUtxos.reduce((sum, utxo) => sum + getUtxoValue(utxo), 0)
+    const totalUnconfirmed = unconfirmedUtxos.reduce((sum, utxo) => sum + getUtxoValue(utxo), 0)
+    const totalValue = totalConfirmed + totalUnconfirmed
+
+    console.log('\n💰 Balance Summary:')
+    console.log(`Confirmed: ${(totalConfirmed / 100).toLocaleString()} XEC (${confirmedUtxos.length} UTXOs)`)
+    console.log(`Unconfirmed: ${(totalUnconfirmed / 100).toLocaleString()} XEC (${unconfirmedUtxos.length} UTXOs)`)
+    console.log(`Total: ${(totalValue / 100).toLocaleString()} XEC`)
+
+    // Show confirmed UTXOs
+    if (confirmedUtxos.length > 0) {
+      console.log('\n✅ Confirmed UTXOs:')
+      console.log('─'.repeat(70))
+      confirmedUtxos.forEach((utxo, index) => {
+        const satsValue = typeof utxo.sats === 'bigint' ? Number(utxo.sats) : parseInt(utxo.sats)
+        const xecValue = (satsValue / 100).toLocaleString()
+        const txidShort = `${utxo.outpoint.txid.substring(0, 8)}...${utxo.outpoint.txid.substring(56)}`
+        console.log(`${index + 1}. ${xecValue} XEC`)
+        console.log(`   TXID: ${txidShort}:${utxo.outpoint.outIdx}`)
+        console.log(`   Block: ${utxo.blockHeight}`)
+        console.log(`   Coinbase: ${utxo.isCoinbase ? 'Yes' : 'No'}`)
+        console.log()
+      })
+    }
+
+    // Show unconfirmed UTXOs
+    if (unconfirmedUtxos.length > 0) {
+      console.log('⏳ Unconfirmed UTXOs:')
+      console.log('─'.repeat(70))
+      unconfirmedUtxos.forEach((utxo, index) => {
+        const satsValue = typeof utxo.sats === 'bigint' ? Number(utxo.sats) : parseInt(utxo.sats)
+        const xecValue = (satsValue / 100).toLocaleString()
+        const txidShort = `${utxo.outpoint.txid.substring(0, 8)}...${utxo.outpoint.txid.substring(56)}`
+        console.log(`${index + 1}. ${xecValue} XEC (pending confirmation)`)
+        console.log(`   TXID: ${txidShort}:${utxo.outpoint.outIdx}`)
+        console.log()
+      })
+      console.log('📝 Note: Unconfirmed UTXOs cannot be spent until they are confirmed.')
+    }
+
+    // UTXO analysis
+    console.log('\n📊 UTXO Analysis:')
+    console.log('─'.repeat(70))
+
+    if (confirmedUtxos.length > 0) {
+      const values = confirmedUtxos.map(utxo => getUtxoValue(utxo) / 100)
+      const avgValue = values.reduce((a, b) => a + b, 0) / values.length
+      const maxValue = Math.max(...values)
+      const minValue = Math.min(...values)
+
+      console.log(`Average UTXO size: ${avgValue.toLocaleString()} XEC`)
+      console.log(`Largest UTXO: ${maxValue.toLocaleString()} XEC`)
+      console.log(`Smallest UTXO: ${minValue.toLocaleString()} XEC`)
+
+      // Dust analysis (UTXOs < 5.46 XEC are considered dust)
+      const dustUtxos = confirmedUtxos.filter(utxo => utxo.value < 546)
+      if (dustUtxos.length > 0) {
+        console.log(`Dust UTXOs: ${dustUtxos.length} (< 5.46 XEC)`)
+        console.log('💡 Consider consolidating dust UTXOs to reduce transaction fees')
+      }
+    }
+
+    // Suggest optimizations
+    if (confirmedUtxos.length > 20) {
+      console.log('\n⚡ Optimization Suggestion:')
+      console.log(`   You have ${confirmedUtxos.length} UTXOs, which might increase transaction fees.`)
+      console.log('   Consider running: node examples/advanced/optimize-utxos.js')
+    }
+  } catch (err) {
+    console.error('❌ Failed to get UTXOs:', err.message)
+
+    // Provide helpful error context
+    if (err.message.includes('network') || err.message.includes('connection')) {
+      console.log('\n🌐 Network Error:')
+      console.log('   • Check your internet connection')
+      console.log('   • Chronik indexer might be temporarily unavailable')
+      console.log('   • Try again in a few moments')
+    }
+
+    process.exit(1)
+  }
+}
+
+// Run the example
+getUtxos()

package/examples/wallet.json

@@ -0,0 +1,11 @@
+{
+  "description": "New XEC Wallet",
+  "created": "2025-08-15T04:08:15.166Z",
+  "mnemonic": "bubble leader travel summer unit fault nation error firm mad leisure urge",
+  "xecAddress": "ecash:qpg562clu3350dnk3z3lenvxgyexyt7j6vnz4qg606",
+  "privateKey": "efa59377256849360662d4af7b39851f658a188b93862889ddf37b45e88c5784",
+  "publicKey": "031d85d1053f528a80b3d44fbef5ba081a4f6a9ca65982565cbfa92165decf8319",
+  "hdPath": "m/44'/899'/0'/0/0",
+  "fee": 1.2,
+  "enableDonations": false
+}

package/lib/adapters/robust-chronik-router.js

@@ -0,0 +1,507 @@
+/*
+  Robust Chronik Router with intelligent failover, health monitoring, and connection pooling.
+  Based on Bitcoin-ABC chronik-client patterns with enhanced reliability features.
+*/
+
+const { ChronikClient } = require('chronik-client')
+
+// Connection error types for intelligent error handling
+const ConnectionErrorType = {
+  NETWORK_TIMEOUT: 'network_timeout',
+  SERVER_UNAVAILABLE: 'server_unavailable',
+  SERVER_INDEXING: 'server_indexing',
+  PROTOCOL_ERROR: 'protocol_error',
+  RATE_LIMITED: 'rate_limited',
+  CONNECTION_REFUSED: 'connection_refused'
+}
+
+// Connection strategies available
+const RobustConnectionStrategy = {
+  CLOSEST_FIRST: 'ClosestFirst',
+  ROUND_ROBIN: 'RoundRobin',
+  PRIORITY_BASED: 'PriorityBased',
+  LOAD_BALANCED: 'LoadBalanced'
+}
+
+class EndpointHealthMonitor {
+  constructor (config = {}) {
+    this.healthCheckInterval = config.healthCheckInterval || 30000 // 30 seconds
+    this.maxLatencyHistory = config.maxLatencyHistory || 10
+    this.healthCheckTimeout = config.healthCheckTimeout || 5000
+
+    // Health tracking data
+    this.healthScores = new Map()
+    this.latencyHistory = new Map()
+    this.failureCount = new Map()
+    this.lastHealthCheck = new Map()
+    this.isMonitoring = false
+    this.healthCheckTimer = null
+  }
+
+  async startMonitoring (endpoints) {
+    if (this.isMonitoring) return
+
+    this.isMonitoring = true
+
+    // Initialize health data for all endpoints
+    for (const endpoint of endpoints) {
+      this.initializeEndpointHealth(endpoint.url)
+    }
+
+    // Start periodic health checks
+    this.healthCheckTimer = setInterval(() => {
+      this._performHealthChecks(endpoints)
+    }, this.healthCheckInterval)
+
+    // Perform initial health check
+    await this._performHealthChecks(endpoints)
+  }
+
+  stopMonitoring () {
+    this.isMonitoring = false
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer)
+      this.healthCheckTimer = null
+    }
+  }
+
+  initializeEndpointHealth (url) {
+    this.healthScores.set(url, 100) // Start with perfect health
+    this.latencyHistory.set(url, [])
+    this.failureCount.set(url, 0)
+    this.lastHealthCheck.set(url, 0)
+  }
+
+  async _performHealthChecks (endpoints) {
+    const healthCheckPromises = endpoints.map(endpoint =>
+      this._checkSingleEndpoint(endpoint).catch(err => {
+        console.warn(`Health check failed for ${endpoint.url}:`, err.message)
+        return false
+      })
+    )
+
+    await Promise.allSettled(healthCheckPromises)
+  }
+
+  async _checkSingleEndpoint (endpoint) {
+    const startTime = Date.now()
+
+    try {
+      // Use chronik's blockchain info as a lightweight health check
+      const chronik = new ChronikClient(endpoint.url)
+      await Promise.race([
+        chronik.blockchainInfo(),
+        new Promise((resolve, reject) =>
+          setTimeout(() => reject(new Error('Health check timeout')), this.healthCheckTimeout)
+        )
+      ])
+
+      const latency = Date.now() - startTime
+      this._recordSuccess(endpoint.url, latency)
+      return true
+    } catch (err) {
+      this._recordFailure(endpoint.url)
+      return false
+    }
+  }
+
+  _recordSuccess (url, latency) {
+    // Update latency history
+    const history = this.latencyHistory.get(url) || []
+    history.push(latency)
+    if (history.length > this.maxLatencyHistory) {
+      history.shift()
+    }
+    this.latencyHistory.set(url, history)
+
+    // Reset failure count on success
+    this.failureCount.set(url, 0)
+
+    // Improve health score
+    const currentScore = this.healthScores.get(url) || 0
+    const newScore = Math.min(100, currentScore + 10)
+    this.healthScores.set(url, newScore)
+
+    this.lastHealthCheck.set(url, Date.now())
+  }
+
+  _recordFailure (url) {
+    const failures = (this.failureCount.get(url) || 0) + 1
+    this.failureCount.set(url, failures)
+
+    // Reduce health score based on consecutive failures
+    const currentScore = this.healthScores.get(url) || 100
+    const penalty = Math.min(30, failures * 10)
+    const newScore = Math.max(0, currentScore - penalty)
+    this.healthScores.set(url, newScore)
+
+    this.lastHealthCheck.set(url, Date.now())
+  }
+
+  getHealthScore (url) {
+    return this.healthScores.get(url) || 0
+  }
+
+  getAverageLatency (url) {
+    const history = this.latencyHistory.get(url) || []
+    if (history.length === 0) return Infinity
+
+    const sum = history.reduce((a, b) => a + b, 0)
+    return sum / history.length
+  }
+
+  getHealthiestEndpoints (endpoints) {
+    return endpoints
+      .filter(endpoint => this.getHealthScore(endpoint.url) > 20) // Only consider reasonably healthy endpoints
+      .sort((a, b) => {
+        const scoreA = this.getHealthScore(a.url)
+        const scoreB = this.getHealthScore(b.url)
+        const latencyA = this.getAverageLatency(a.url)
+        const latencyB = this.getAverageLatency(b.url)
+
+        // Prioritize health score, then latency
+        if (scoreA !== scoreB) {
+          return scoreB - scoreA // Higher score is better
+        }
+        return latencyA - latencyB // Lower latency is better
+      })
+  }
+
+  isEndpointHealthy (url, minScore = 30) {
+    const score = this.getHealthScore(url)
+    const failures = this.failureCount.get(url) || 0
+    return score >= minScore && failures < 3
+  }
+}
+
+class ConnectionErrorHandler {
+  constructor () {
+    this.maxRetries = 3
+    this.baseRetryDelay = 1000 // 1 second
+    this.maxRetryDelay = 30000 // 30 seconds
+  }
+
+  classifyError (error) {
+    const errorMsg = error.message?.toLowerCase() || ''
+    const errorCode = error.code?.toLowerCase() || ''
+
+    // Network-level errors
+    if (errorCode === 'econnrefused' || errorMsg.includes('connection refused')) {
+      return ConnectionErrorType.CONNECTION_REFUSED
+    }
+
+    if (errorCode === 'etimedout' || errorMsg.includes('timeout')) {
+      return ConnectionErrorType.NETWORK_TIMEOUT
+    }
+
+    // Server-level errors
+    if (errorMsg.includes('indexing') || errorMsg.includes('error state')) {
+      return ConnectionErrorType.SERVER_INDEXING
+    }
+
+    if (errorMsg.includes('rate limit') || errorMsg.includes('too many requests')) {
+      return ConnectionErrorType.RATE_LIMITED
+    }
+
+    if (errorMsg.includes('server unavailable') || errorMsg.includes('503')) {
+      return ConnectionErrorType.SERVER_UNAVAILABLE
+    }
+
+    // Default to protocol error for chronik-specific errors
+    return ConnectionErrorType.PROTOCOL_ERROR
+  }
+
+  shouldRetry (errorType, attemptNumber) {
+    if (attemptNumber >= this.maxRetries) return false
+
+    switch (errorType) {
+      case ConnectionErrorType.NETWORK_TIMEOUT:
+      case ConnectionErrorType.CONNECTION_REFUSED:
+      case ConnectionErrorType.SERVER_UNAVAILABLE:
+        return true
+      case ConnectionErrorType.SERVER_INDEXING:
+        return attemptNumber < 2 // Only retry once for indexing servers
+      case ConnectionErrorType.RATE_LIMITED:
+        return true
+      case ConnectionErrorType.PROTOCOL_ERROR:
+        return false // Don't retry protocol errors
+      default:
+        return false
+    }
+  }
+
+  getRetryDelay (attemptNumber, errorType) {
+    const baseDelay = this.baseRetryDelay
+
+    // Adjust base delay based on error type
+    let multiplier = 1
+    switch (errorType) {
+      case ConnectionErrorType.RATE_LIMITED:
+        multiplier = 3 // Longer delay for rate limiting
+        break
+      case ConnectionErrorType.SERVER_INDEXING:
+        multiplier = 5 // Much longer delay for indexing servers
+        break
+      case ConnectionErrorType.NETWORK_TIMEOUT:
+        multiplier = 2
+        break
+      default:
+        multiplier = 1
+    }
+
+    // Exponential backoff with jitter
+    const exponentialDelay = baseDelay * multiplier * Math.pow(2, attemptNumber - 1)
+    const jitter = Math.random() * 0.1 * exponentialDelay // 10% jitter
+    const finalDelay = Math.min(exponentialDelay + jitter, this.maxRetryDelay)
+
+    return Math.floor(finalDelay)
+  }
+}
+
+class RobustChronikRouter {
+  constructor (config = {}) {
+    this.strategy = config.strategy || RobustConnectionStrategy.CLOSEST_FIRST
+    this.endpoints = []
+    this.currentEndpointIndex = 0
+    this.healthMonitor = new EndpointHealthMonitor(config.healthMonitor || {})
+    this.errorHandler = new ConnectionErrorHandler()
+    this.connectionPool = new Map()
+    this.maxConnectionsPerEndpoint = config.maxConnectionsPerEndpoint || 3
+    this.connectionTimeout = config.connectionTimeout || 10000
+    this.isInitialized = false
+
+    // Statistics
+    this.stats = {
+      requestCount: 0,
+      failoverCount: 0,
+      totalLatency: 0,
+      errorsByType: new Map()
+    }
+  }
+
+  async initialize (urls, strategyOptions = {}) {
+    try {
+      if (this.isInitialized) {
+        await this.cleanup()
+      }
+
+      // Validate and prepare endpoints
+      this.endpoints = this._prepareEndpoints(urls)
+
+      // Initialize health monitoring
+      await this.healthMonitor.startMonitoring(this.endpoints)
+
+      // Try to establish initial connection using chosen strategy
+      await this._initializeWithStrategy(strategyOptions)
+
+      this.isInitialized = true
+      console.log(`RobustChronikRouter initialized with ${this.endpoints.length} endpoints using ${this.strategy} strategy`)
+    } catch (err) {
+      throw new Error(`Router initialization failed: ${err.message}`)
+    }
+  }
+
+  _prepareEndpoints (urls) {
+    const urlArray = Array.isArray(urls) ? urls : [urls]
+
+    if (urlArray.length === 0) {
+      throw new Error('At least one endpoint URL is required')
+    }
+
+    return urlArray.map((url, index) => ({
+      url: this._normalizeUrl(url),
+      priority: index, // Lower index = higher priority
+      isActive: true,
+      createdAt: Date.now()
+    }))
+  }
+
+  _normalizeUrl (url) {
+    if (!url || typeof url !== 'string') {
+      throw new Error('URL must be a non-empty string')
+    }
+
+    // Remove trailing slash
+    const cleanUrl = url.replace(/\/$/, '')
+
+    // Validate URL format
+    if (!cleanUrl.startsWith('http://') && !cleanUrl.startsWith('https://')) {
+      throw new Error(`Invalid URL format: ${url}`)
+    }
+
+    return cleanUrl
+  }
+
+  async _initializeWithStrategy (options) {
+    switch (this.strategy) {
+      case RobustConnectionStrategy.CLOSEST_FIRST:
+        await this._initializeClosestFirst()
+        break
+      case RobustConnectionStrategy.PRIORITY_BASED:
+        this._initializePriorityBased()
+        break
+      case RobustConnectionStrategy.ROUND_ROBIN:
+        this._initializeRoundRobin()
+        break
+      default:
+        this._initializePriorityBased() // Default fallback
+    }
+  }
+
+  async _initializeClosestFirst () {
+    // Wait for initial health checks to complete
+    await new Promise(resolve => setTimeout(resolve, 1000))
+
+    // Sort endpoints by health and latency
+    const healthyEndpoints = this.healthMonitor.getHealthiestEndpoints(this.endpoints)
+
+    if (healthyEndpoints.length > 0) {
+      this.currentEndpointIndex = this.endpoints.indexOf(healthyEndpoints[0])
+    } else {
+      console.warn('No healthy endpoints found, using first endpoint')
+      this.currentEndpointIndex = 0
+    }
+  }
+
+  _initializePriorityBased () {
+    // Sort by priority (lower number = higher priority)
+    this.endpoints.sort((a, b) => a.priority - b.priority)
+    this.currentEndpointIndex = 0
+  }
+
+  _initializeRoundRobin () {
+    this.currentEndpointIndex = 0
+  }
+
+  async executeWithFailover (operation, maxAttempts = null) {
+    const attempts = maxAttempts || this.endpoints.length * this.errorHandler.maxRetries
+    let lastError = null
+
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      const endpoint = this._getCurrentEndpoint()
+
+      try {
+        this.stats.requestCount++
+        const startTime = Date.now()
+
+        const result = await this._executeWithTimeout(operation, endpoint)
+
+        // Record success metrics
+        this.stats.totalLatency += Date.now() - startTime
+
+        return result
+      } catch (err) {
+        lastError = err
+        const errorType = this.errorHandler.classifyError(err)
+
+        // Update error statistics
+        const errorCount = this.stats.errorsByType.get(errorType) || 0
+        this.stats.errorsByType.set(errorType, errorCount + 1)
+
+        // Check if we should retry
+        if (!this.errorHandler.shouldRetry(errorType, attempt) || attempt === attempts) {
+          throw err
+        }
+
+        // Move to next endpoint
+        await this._rotateToNextHealthyEndpoint()
+        this.stats.failoverCount++
+
+        // Wait before retry
+        const retryDelay = this.errorHandler.getRetryDelay(attempt, errorType)
+        console.warn(`Endpoint ${endpoint.url} failed (${errorType}), retrying in ${retryDelay}ms...`)
+        await new Promise(resolve => setTimeout(resolve, retryDelay))
+      }
+    }
+
+    throw lastError || new Error('All failover attempts exhausted')
+  }
+
+  async _executeWithTimeout (operation, endpoint) {
+    const timeoutPromise = new Promise((resolve, reject) =>
+      setTimeout(() => reject(new Error('Operation timeout')), this.connectionTimeout)
+    )
+
+    return Promise.race([
+      operation(endpoint),
+      timeoutPromise
+    ])
+  }
+
+  _getCurrentEndpoint () {
+    if (this.currentEndpointIndex >= this.endpoints.length) {
+      this.currentEndpointIndex = 0
+    }
+    return this.endpoints[this.currentEndpointIndex]
+  }
+
+  async _rotateToNextHealthyEndpoint () {
+    const startIndex = this.currentEndpointIndex
+    let attempts = 0
+
+    do {
+      this.currentEndpointIndex = (this.currentEndpointIndex + 1) % this.endpoints.length
+      attempts++
+
+      const endpoint = this.endpoints[this.currentEndpointIndex]
+
+      // Check if this endpoint is healthy
+      if (this.healthMonitor.isEndpointHealthy(endpoint.url)) {
+        return
+      }
+    } while (this.currentEndpointIndex !== startIndex && attempts < this.endpoints.length)
+
+    // If no healthy endpoints found, use current anyway (last resort)
+    console.warn('No healthy endpoints available, continuing with current endpoint')
+  }
+
+  async getConnection () {
+    if (!this.isInitialized) {
+      throw new Error('Router not initialized. Call initialize() first.')
+    }
+
+    const endpoint = this._getCurrentEndpoint()
+
+    // Try to reuse existing connection from pool
+    const poolKey = endpoint.url
+    if (this.connectionPool.has(poolKey)) {
+      return this.connectionPool.get(poolKey)
+    }
+
+    // Create new connection
+    const chronik = new ChronikClient(endpoint.url)
+    this.connectionPool.set(poolKey, chronik)
+
+    return chronik
+  }
+
+  getStats () {
+    const avgLatency = this.stats.requestCount > 0
+      ? this.stats.totalLatency / this.stats.requestCount
+      : 0
+
+    return {
+      ...this.stats,
+      averageLatency: Math.round(avgLatency),
+      currentEndpoint: this._getCurrentEndpoint().url,
+      healthyEndpoints: this.endpoints.filter(ep =>
+        this.healthMonitor.isEndpointHealthy(ep.url)
+      ).length,
+      totalEndpoints: this.endpoints.length
+    }
+  }
+
+  async cleanup () {
+    this.healthMonitor.stopMonitoring()
+    this.connectionPool.clear()
+    this.isInitialized = false
+  }
+}
+
+module.exports = {
+  RobustChronikRouter,
+  EndpointHealthMonitor,
+  ConnectionErrorHandler,
+  RobustConnectionStrategy,
+  ConnectionErrorType
+}