minimal-xec-wallet 1.0.1

package/examples/key-management/validate-address.js

@@ -0,0 +1,214 @@
+/*
+  Validate XEC addresses for correctness.
+  This example shows how to check if an address is valid before sending funds.
+*/
+
+const MinimalXECWallet = require('../../index')
+
+// Get command line arguments
+const args = process.argv.slice(2)
+
+function showUsage () {
+  console.log('Usage: node validate-address.js <address1> [address2] [address3] ...')
+  console.log('')
+  console.log('Examples:')
+  console.log('  node validate-address.js ecash:qp1234567890abcdef1234567890abcdef12345678')
+  console.log('  node validate-address.js ecash:qr123... ecash:qp456... bitcoincash:qz789...')
+  console.log('')
+  console.log('Parameters:')
+  console.log('  addressN: XEC or other cryptocurrency addresses to validate')
+  console.log('')
+  console.log('Purpose:')
+  console.log('  • Verify address format and checksum')
+  console.log('  • Detect common address format errors')
+  console.log('  • Prevent sending funds to invalid addresses')
+}
+
+function validateSingleAddress (address) {
+  console.log(`\n🔍 Validating: ${address}`)
+  console.log('─'.repeat(60))
+
+  // Basic format checks
+  const checks = {
+    notEmpty: address && address.length > 0,
+    hasPrefix: address && address.includes(':'),
+    correctPrefix: address && address.startsWith('ecash:'),
+    correctLength: address && address.length >= 40 && address.length <= 60,
+    validCharacters: address && /^ecash:[a-z0-9]+$/.test(address)
+  }
+
+  // Show basic format analysis
+  console.log('📋 Basic Format Analysis:')
+  console.log(`   Length: ${address ? address.length : 0} characters`)
+  console.log(`   Prefix: ${address ? address.split(':')[0] : 'none'}`)
+  console.log(`   Body: ${address ? address.split(':')[1]?.substring(0, 10) + '...' : 'none'}`)
+
+  // Check against other cryptocurrency formats
+  const formatAnalysis = {
+    isXEC: address && address.startsWith('ecash:'),
+    isBCH: address && address.startsWith('bitcoincash:'),
+    isBTC: address && (/^[13][a-km-zA-HJ-NP-Z1-9]{25,34}$/.test(address) || /^bc1[a-z0-9]{39,59}$/.test(address)),
+    isETH: address && /^0x[a-fA-F0-9]{40}$/.test(address),
+    isLTC: address && (/^[LM3][a-km-zA-HJ-NP-Z1-9]{26,33}$/.test(address) || /^ltc1[a-z0-9]{39,59}$/.test(address))
+  }
+
+  console.log('\n🔍 Format Detection:')
+  if (formatAnalysis.isXEC) {
+    console.log('   ✅ Detected as XEC (eCash) address')
+  } else if (formatAnalysis.isBCH) {
+    console.log('   ⚠️  Detected as BCH (Bitcoin Cash) address')
+    console.log('       This is NOT compatible with XEC!')
+  } else if (formatAnalysis.isBTC) {
+    console.log('   ⚠️  Detected as BTC (Bitcoin) address')
+    console.log('       This is NOT compatible with XEC!')
+  } else if (formatAnalysis.isETH) {
+    console.log('   ⚠️  Detected as ETH (Ethereum) address')
+    console.log('       This is NOT compatible with XEC!')
+  } else if (formatAnalysis.isLTC) {
+    console.log('   ⚠️  Detected as LTC (Litecoin) address')
+    console.log('       This is NOT compatible with XEC!')
+  } else {
+    console.log('   ❓ Unknown or invalid address format')
+  }
+
+  // Attempt validation using wallet library
+  let isValid = false
+  let validationError = null
+
+  try {
+    const wallet = new MinimalXECWallet()
+    wallet._validateAddress(address)
+    isValid = true
+    console.log('\n✅ Validation Result: VALID XEC ADDRESS')
+  } catch (err) {
+    validationError = err.message
+    console.log('\n❌ Validation Result: INVALID')
+    console.log(`   Error: ${validationError}`)
+  }
+
+  // Detailed check results
+  console.log('\n📊 Detailed Checks:')
+  Object.entries(checks).forEach(([check, passed]) => {
+    const status = passed ? '✅' : '❌'
+    const checkName = check.replace(/([A-Z])/g, ' $1').toLowerCase()
+    console.log(`   ${status} ${checkName}`)
+  })
+
+  // Security warnings
+  if (!isValid) {
+    console.log('\n⚠️  Security Warnings:')
+
+    if (formatAnalysis.isBCH) {
+      console.log('   • This appears to be a Bitcoin Cash address')
+      console.log('   • Sending XEC to BCH addresses will result in LOSS OF FUNDS')
+      console.log('   • XEC and BCH are different cryptocurrencies')
+    } else if (formatAnalysis.isBTC) {
+      console.log('   • This appears to be a Bitcoin address')
+      console.log('   • Sending XEC to BTC addresses will result in LOSS OF FUNDS')
+    } else if (formatAnalysis.isETH) {
+      console.log('   • This appears to be an Ethereum address')
+      console.log('   • XEC cannot be sent to Ethereum addresses')
+    } else {
+      console.log('   • Address format is not recognized as valid XEC')
+      console.log('   • Double-check the address with the recipient')
+      console.log('   • Sending to invalid addresses may result in loss of funds')
+    }
+  }
+
+  // Usage recommendations
+  console.log('\n💡 Recommendations:')
+  if (isValid) {
+    console.log('   ✅ Safe to send XEC to this address')
+    console.log('   ✅ Address format and checksum are correct')
+    console.log('   ✅ Compatible with eCash network')
+  } else {
+    console.log('   ❌ DO NOT send XEC to this address')
+    console.log('   ❌ Verify the address with the recipient')
+    console.log('   ❌ Request a proper XEC address (starting with ecash:)')
+  }
+
+  return {
+    address,
+    isValid,
+    format: formatAnalysis,
+    error: validationError
+  }
+}
+
+async function validateAddresses () {
+  try {
+    console.log('🔍 XEC Address Validation Tool\n')
+
+    // Check arguments
+    if (args.length === 0) {
+      console.log('❌ No addresses provided')
+      showUsage()
+      return
+    }
+
+    console.log(`📋 Validating ${args.length} address(es):`)
+    console.log('═'.repeat(60))
+
+    const results = []
+
+    // Validate each address
+    for (const address of args) {
+      const result = validateSingleAddress(address)
+      results.push(result)
+    }
+
+    // Summary
+    console.log('\n📊 Validation Summary:')
+    console.log('═'.repeat(60))
+
+    const validCount = results.filter(r => r.isValid).length
+    const invalidCount = results.length - validCount
+
+    console.log(`Total addresses checked: ${results.length}`)
+    console.log(`Valid XEC addresses: ${validCount}`)
+    console.log(`Invalid addresses: ${invalidCount}`)
+
+    if (invalidCount > 0) {
+      console.log('\n⚠️  Invalid Addresses Found:')
+      results.filter(r => !r.isValid).forEach(result => {
+        console.log(`   ❌ ${result.address}`)
+        console.log(`      Error: ${result.error}`)
+      })
+    }
+
+    if (validCount > 0) {
+      console.log('\n✅ Valid XEC Addresses:')
+      results.filter(r => r.isValid).forEach(result => {
+        console.log(`   ✅ ${result.address}`)
+      })
+    }
+
+    // Best practices
+    console.log('\n💡 Best Practices:')
+    console.log('─'.repeat(60))
+    console.log('• Always validate addresses before sending funds')
+    console.log('• Double-check with recipients when in doubt')
+    console.log('• XEC addresses must start with "ecash:"')
+    console.log('• Never send XEC to Bitcoin, Ethereum, or other crypto addresses')
+    console.log('• Use small test amounts for first-time recipients')
+    console.log('• Copy addresses carefully to avoid typos')
+
+    console.log('\n🔗 Resources:')
+    console.log('─'.repeat(60))
+    console.log('• eCash Explorer: https://explorer.e.cash')
+    console.log('• Address format docs: https://e.cash/developers')
+    console.log('• CashAddr format: https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/cashaddr.md')
+  } catch (err) {
+    console.error('❌ Address validation failed:', err.message)
+    process.exit(1)
+  }
+}
+
+// Show usage if requested
+if (args.includes('--help') || args.includes('-h')) {
+  showUsage()
+  process.exit(0)
+}
+
+// Run the example
+validateAddresses()

package/examples/optimization/simple-consolidation-test.js

@@ -0,0 +1,79 @@
+/*
+  Simple UTXO consolidation test to debug wallet issues
+*/
+
+const MinimalXECWallet = require('../../index')
+const fs = require('fs')
+
+async function simpleTest () {
+  try {
+    console.log('🔧 Simple UTXO Consolidation Test...\n')
+
+    // Load wallet data directly
+    const walletData = JSON.parse(fs.readFileSync('./wallet.json'))
+    console.log('✅ Wallet loaded:')
+    console.log(`   Address: ${walletData.xecAddress}`)
+    console.log('')
+
+    // Initialize wallet
+    console.log('🔧 Initializing wallet...')
+    const wallet = new MinimalXECWallet(walletData.mnemonic)
+
+    await wallet.walletInfoPromise
+    console.log('✅ Wallet info ready')
+
+    await wallet.initialize()
+    console.log('✅ Wallet initialized')
+    console.log('')
+
+    // Check if wallet is properly initialized
+    console.log('🔍 Wallet State Check:')
+    console.log(`   isInitialized: ${wallet.isInitialized}`)
+    console.log(`   walletInfo exists: ${!!wallet.walletInfo}`)
+    console.log(`   utxos exists: ${!!wallet.utxos}`)
+    console.log(`   consolidateUtxos exists: ${!!wallet.consolidateUtxos}`)
+    console.log('')
+
+    // Try to get balance
+    console.log('💰 Getting balance...')
+    try {
+      const balance = await wallet.getXecBalance()
+      console.log(`   Balance: ${JSON.stringify(balance)}`)
+    } catch (err) {
+      console.log(`   Balance error: ${err.message}`)
+    }
+    console.log('')
+
+    // Try to get UTXOs
+    console.log('📦 Getting UTXOs...')
+    try {
+      const utxos = await wallet.getUtxos()
+      console.log(`   UTXOs count: ${utxos.length}`)
+      if (utxos.length > 0) {
+        console.log(`   First UTXO: ${JSON.stringify(utxos[0], null, 2)}`)
+      }
+    } catch (err) {
+      console.log(`   UTXOs error: ${err.message}`)
+    }
+    console.log('')
+
+    // Try consolidation analysis
+    console.log('🔍 Testing consolidation analysis...')
+    try {
+      const dryRunResult = await wallet.optimize(true)
+      console.log(`   Dry run success: ${dryRunResult.success}`)
+      console.log(`   Message: ${dryRunResult.message}`)
+      console.log(`   Transactions: ${dryRunResult.transactions.length}`)
+    } catch (err) {
+      console.log(`   Consolidation error: ${err.message}`)
+    }
+  } catch (err) {
+    console.error('\n❌ Test failed:', err.message)
+    console.log('\n🔧 Debugging info:')
+    console.log(`   Error type: ${err.constructor.name}`)
+    console.log(`   Stack: ${err.stack}`)
+  }
+}
+
+// Run test
+simpleTest()

package/examples/optimization/test-utxo-consolidation.js

@@ -0,0 +1,179 @@
+/*
+  Test UTXO consolidation functionality with real wallet
+  Demonstrates dry run analysis and actual consolidation capabilities
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+async function testUtxoConsolidation () {
+  try {
+    console.log('🔧 Testing UTXO Consolidation Functionality...\n')
+
+    // Load wallet
+    const walletData = WalletHelper.loadWallet()
+    if (!walletData) {
+      console.log('❌ No wallet found')
+      console.log('   Run: node examples/wallet-creation/create-new-wallet.js')
+      return
+    }
+
+    console.log('✅ Wallet loaded:')
+    console.log(`   Address: ${walletData.xecAddress}`)
+    console.log('')
+
+    // Initialize wallet
+    console.log('🔧 Initializing wallet...')
+    const wallet = new MinimalXECWallet(walletData.mnemonic)
+
+    await wallet.walletInfoPromise
+    await wallet.initialize()
+
+    console.log('✅ Wallet initialized successfully!')
+    console.log('')
+
+    // Get current wallet state
+    console.log('📊 Current Wallet State:')
+    const balance = await wallet.getXecBalance()
+    const utxos = await wallet.getUtxos()
+    console.log(`   XEC Balance: ${balance} XEC`)
+    console.log(`   Total UTXOs: ${utxos.length}`)
+    console.log('')
+
+    // Get UTXO distribution
+    console.log('📈 UTXO Distribution Analysis:')
+    const distribution = wallet.consolidateUtxos.getUtxoDistribution()
+    console.log(`   Total UTXOs: ${distribution.total}`)
+    console.log(`   Dust (< 1000 sats): ${distribution.dust}`)
+    console.log(`   Small (1000-10000 sats): ${distribution.small}`)
+    console.log(`   Medium (10000-100000 sats): ${distribution.medium}`)
+    console.log(`   Large (> 100000 sats): ${distribution.large}`)
+    console.log('')
+
+    // Get optimization savings estimate
+    console.log('💰 Optimization Savings Estimate:')
+    const savings = wallet.consolidateUtxos.estimateOptimizationSavings()
+    console.log(`   Current UTXOs: ${savings.currentUtxos}`)
+    if (savings.optimalUtxos) {
+      console.log(`   Optimal UTXOs: ${savings.optimalUtxos}`)
+      console.log(`   Current fee estimate: ${savings.currentEstimatedFee} satoshis`)
+      console.log(`   Optimized fee estimate: ${savings.optimizedEstimatedFee} satoshis`)
+      console.log(`   Potential savings: ${savings.savings} satoshis`)
+    } else {
+      console.log(`   Status: ${savings.reason}`)
+    }
+    console.log('')
+
+    // Perform dry run optimization analysis
+    console.log('🔍 Dry Run Optimization Analysis:')
+    const dryRunResult = await wallet.optimize(true) // Dry run mode
+
+    console.log(`   Success: ${dryRunResult.success}`)
+    console.log(`   Analysis: ${dryRunResult.message}`)
+    console.log(`   Planned transactions: ${dryRunResult.transactions.length}`)
+
+    if (dryRunResult.analysis) {
+      console.log('\n   📋 Detailed Analysis:')
+      console.log(`      Should consolidate: ${dryRunResult.analysis.shouldConsolidate}`)
+      console.log(`      UTXOs to consolidate: ${dryRunResult.analysis.totalUtxos || 'N/A'}`)
+      console.log(`      Output UTXOs: ${dryRunResult.analysis.outputUtxos || 'N/A'}`)
+      console.log(`      Total value: ${dryRunResult.analysis.totalValue || 'N/A'} satoshis`)
+      if (dryRunResult.analysis.consolidationFee) {
+        console.log(`      Consolidation fee: ${dryRunResult.analysis.consolidationFee} satoshis`)
+      }
+      if (dryRunResult.analysis.potentialSavings !== undefined) {
+        console.log(`      Net benefit: ${dryRunResult.analysis.potentialSavings} satoshis`)
+      }
+    }
+
+    // Show consolidation plans if any
+    if (dryRunResult.transactions.length > 0) {
+      console.log('\n   📝 Consolidation Plans:')
+      dryRunResult.transactions.forEach((plan, index) => {
+        console.log(`      Plan ${index + 1}:`)
+        console.log(`         Input UTXOs: ${plan.inputCount}`)
+        console.log(`         Input value: ${plan.totalInputValue} satoshis`)
+        console.log(`         Output value: ${plan.outputValue} satoshis`)
+        console.log(`         Estimated fee: ${plan.estimatedFee} satoshis`)
+        if (plan.savings) {
+          console.log(`         Future savings: ${plan.savings} satoshis`)
+        }
+      })
+    }
+
+    console.log('')
+
+    // User decision for live execution
+    if (dryRunResult.analysis && dryRunResult.analysis.shouldConsolidate) {
+      console.log('💡 Consolidation Recommendation:')
+      console.log('   ✅ UTXO consolidation would be beneficial!')
+      console.log('   📊 Benefits:')
+      console.log(`      • Reduce UTXOs from ${dryRunResult.analysis.totalUtxos} to ${dryRunResult.analysis.outputUtxos}`)
+      console.log(`      • Save ${dryRunResult.analysis.potentialSavings} satoshis in future transaction fees`)
+      console.log('      • Improve wallet performance and reduce transaction complexity')
+      console.log('')
+      console.log('⚠️  This is a test script - not executing live consolidation.')
+      console.log('   To execute live consolidation, run:')
+      console.log('   const result = await wallet.optimize(false) // Live mode')
+      console.log('')
+      console.log('🔧 Test Parameters:')
+      console.log(`   Fee rate: ${walletData.fee || '1.2'} sat/byte`)
+      console.log('   Dust limit: 200 satoshis')
+      console.log('   Max inputs per tx: 200')
+      console.log('   Consolidation threshold: 100,000 satoshis')
+    } else {
+      console.log('ℹ️  Consolidation Status:')
+      console.log('   No consolidation needed at this time.')
+      console.log('   Reasons:')
+      if (distribution.total < 5) {
+        console.log('   • Too few UTXOs (need at least 5)')
+      }
+      if (distribution.dust + distribution.small < 5) {
+        console.log('   • Not enough small UTXOs to consolidate')
+      }
+      if (dryRunResult.analysis && dryRunResult.analysis.potentialSavings <= 0) {
+        console.log('   • Consolidation would cost more than it saves')
+      }
+      console.log('')
+      console.log('💡 When consolidation becomes beneficial:')
+      console.log('   • When you have many small UTXOs (< 100,000 satoshis)')
+      console.log('   • When transaction fees are low')
+      console.log('   • When you frequently make transactions')
+    }
+
+    console.log('')
+    console.log('🎯 Test Results:')
+    console.log('   ✅ UTXO consolidation functionality working correctly')
+    console.log('   ✅ Dry run analysis completed successfully')
+    console.log('   ✅ Cost-benefit analysis functioning properly')
+    console.log('   ✅ Smart consolidation recommendations working')
+  } catch (err) {
+    console.error('\n❌ UTXO consolidation test failed:', err.message)
+
+    // Provide context-specific help
+    if (err.message.includes('wallet')) {
+      console.log('\n🔧 Wallet Issue:')
+      console.log('   • Check wallet is properly initialized')
+      console.log('   • Verify wallet has some XEC balance')
+      console.log('   • Try reinitializing the wallet')
+    } else if (err.message.includes('network') || err.message.includes('chronik')) {
+      console.log('\n🌐 Network Issue:')
+      console.log('   • Check internet connection')
+      console.log('   • Chronik API may be temporarily unavailable')
+      console.log('   • Try again in a few moments')
+    } else {
+      console.log('\n🔧 General Error:')
+      console.log('   • Check wallet has been properly funded')
+      console.log('   • Verify network connectivity')
+      console.log('   • Try with a fresh wallet initialization')
+    }
+
+    console.log('\nFor debugging, check:')
+    console.log('   node examples/wallet-info/wallet-details.js')
+
+    process.exit(1)
+  }
+}
+
+// Run the consolidation test
+testUtxoConsolidation()