minimal-xec-wallet 1.0.1

package/examples/tokens/test-main-wallet-integration.js

@@ -0,0 +1,193 @@
+/*
+  Test Step 1 Main Wallet Integration with Real Tokens
+
+  This script validates that our Step 1 integration works correctly by:
+  1. Using the main MinimalXECWallet API (not low-level libraries)
+  2. Testing with real FLCT (SLP) and TGR (ALP) tokens
+  3. Validating core token operations work through main wallet interface
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+async function testMainWalletIntegration () {
+  try {
+    console.log('🧪 Testing Step 1: Main Wallet Integration')
+    console.log('═'.repeat(60))
+    console.log('Testing with real FLCT (SLP) and TGR (ALP) tokens...\n')
+
+    // Load wallet data
+    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(`   Using mnemonic: ${walletData.mnemonic ? 'Yes' : 'No'}`)
+    console.log('')
+
+    // Initialize main wallet using our Step 1 integration
+    console.log('🔧 Initializing MinimalXECWallet (Step 1 Integration)...')
+    const wallet = new MinimalXECWallet(walletData.mnemonic)
+
+    // Wait for wallet creation
+    await wallet.walletInfoPromise
+
+    // Initialize UTXO store
+    console.log('📦 Initializing wallet...')
+    await wallet.initialize()
+
+    console.log('✅ Main wallet initialized successfully!')
+    console.log('')
+
+    // Test 1: List all tokens using main wallet API
+    console.log('📋 Test 1: List all tokens (main wallet API)')
+    console.log('─'.repeat(50))
+
+    try {
+      const tokens = await wallet.listETokens()
+      console.log(`✅ Found ${tokens.length} token type(s):`)
+
+      for (const token of tokens) {
+        console.log(`   • ${token.ticker} (${token.protocol}): ${token.balance.display} ${token.ticker}`)
+        console.log(`     Name: ${token.name}`)
+        console.log(`     Token ID: ${token.tokenId}`)
+        console.log(`     UTXOs: ${token.utxoCount}`)
+      }
+
+      if (tokens.length === 0) {
+        console.log('ℹ️  No tokens found - this may be expected if testing with empty wallet')
+      }
+    } catch (err) {
+      console.log(`❌ Failed to list tokens: ${err.message}`)
+      throw err
+    }
+
+    console.log('')
+
+    // Test 2: Get specific token balances using main wallet API
+    console.log('💰 Test 2: Get specific token balances (main wallet API)')
+    console.log('─'.repeat(50))
+
+    // Test FLCT (SLP) balance
+    const FLCT_TOKEN_ID = '5e40dda12765d0b3819286f4bd50ec58a4bf8d7dbfd277152693ad9d34912135'
+    try {
+      console.log('Checking FLCT (SLP) balance...')
+      const flctBalance = await wallet.getETokenBalance({ tokenId: FLCT_TOKEN_ID })
+      console.log(`✅ FLCT Balance: ${flctBalance.balance.display} ${flctBalance.ticker}`)
+      console.log(`   Protocol: ${flctBalance.protocol}`)
+      console.log(`   Name: ${flctBalance.name}`)
+      console.log(`   UTXOs: ${flctBalance.utxoCount}`)
+    } catch (err) {
+      console.log(`ℹ️  FLCT not found or error: ${err.message}`)
+    }
+
+    // Test TGR (ALP) balance
+    const TGR_TOKEN_ID = '6887ab3749e0d5168a04838216895c95fce61f99237626b08d50db804fcb1801'
+    try {
+      console.log('Checking TGR (ALP) balance...')
+      const tgrBalance = await wallet.getETokenBalance({ tokenId: TGR_TOKEN_ID })
+      console.log(`✅ TGR Balance: ${tgrBalance.balance.display} ${tgrBalance.ticker}`)
+      console.log(`   Protocol: ${tgrBalance.protocol}`)
+      console.log(`   Name: ${tgrBalance.name}`)
+      console.log(`   UTXOs: ${tgrBalance.utxoCount}`)
+    } catch (err) {
+      console.log(`ℹ️  TGR not found or error: ${err.message}`)
+    }
+
+    console.log('')
+
+    // Test 3: Get token metadata using main wallet API
+    console.log('📄 Test 3: Get token metadata (main wallet API)')
+    console.log('─'.repeat(50))
+
+    try {
+      console.log('Getting FLCT metadata...')
+      const flctData = await wallet.getETokenData(FLCT_TOKEN_ID)
+      console.log('✅ FLCT Metadata:')
+      console.log(`   Ticker: ${flctData.ticker}`)
+      console.log(`   Name: ${flctData.name}`)
+      console.log(`   Protocol: ${flctData.protocol}`)
+      console.log(`   Type: ${flctData.type}`)
+      console.log(`   Decimals: ${flctData.decimals}`)
+      if (flctData.url) console.log(`   URL: ${flctData.url}`)
+    } catch (err) {
+      console.log(`ℹ️  FLCT metadata error: ${err.message}`)
+    }
+
+    try {
+      console.log('Getting TGR metadata...')
+      const tgrData = await wallet.getETokenData(TGR_TOKEN_ID)
+      console.log('✅ TGR Metadata:')
+      console.log(`   Ticker: ${tgrData.ticker}`)
+      console.log(`   Name: ${tgrData.name}`)
+      console.log(`   Protocol: ${tgrData.protocol}`)
+      console.log(`   Type: ${tgrData.type}`)
+      console.log(`   Decimals: ${tgrData.decimals}`)
+      if (tgrData.url) console.log(`   URL: ${tgrData.url}`)
+    } catch (err) {
+      console.log(`ℹ️  TGR metadata error: ${err.message}`)
+    }
+
+    console.log('')
+
+    // Test 4: Validate wallet state and integration
+    console.log('🔍 Test 4: Validate wallet state and integration')
+    console.log('─'.repeat(50))
+
+    try {
+      const xecBalance = await wallet.getXecBalance()
+      console.log(`✅ XEC Balance: ${xecBalance} XEC`)
+
+      const utxos = await wallet.getUtxos()
+      console.log(`✅ Total UTXOs: ${utxos.utxos.length}`)
+
+      // Check if wallet has proper hybrid token manager integration
+      console.log(`✅ HybridTokenManager: ${wallet.hybridTokens ? 'Integrated' : 'Missing'}`)
+      console.log(`✅ Wallet initialized: ${wallet.isInitialized}`)
+    } catch (err) {
+      console.log(`❌ Wallet state validation error: ${err.message}`)
+      throw err
+    }
+
+    console.log('')
+
+    // Summary
+    console.log('📊 INTEGRATION TEST SUMMARY')
+    console.log('═'.repeat(60))
+    console.log('✅ Main wallet initialization: PASSED')
+    console.log('✅ Token listing via main API: PASSED')
+    console.log('✅ Token balance via main API: PASSED')
+    console.log('✅ Token metadata via main API: PASSED')
+    console.log('✅ Wallet state validation: PASSED')
+    console.log('')
+    console.log('🎉 Step 1 Main Wallet Integration: VALIDATED!')
+    console.log('')
+    console.log('💡 Next Steps:')
+    console.log('   • Test real token sending: node examples/tokens/send-any-token.js')
+    console.log('   • Test token burning: node examples/tokens/burn-tokens.js')
+    console.log('   • Update all examples to use main wallet API')
+  } catch (err) {
+    console.error('\n❌ Integration test failed:', err.message)
+    console.error('\n📍 This indicates an issue with Step 1 integration')
+
+    if (err.stack) {
+      console.error('\nStack trace:')
+      console.error(err.stack)
+    }
+
+    console.log('\n🔧 Debugging suggestions:')
+    console.log('   • Check wallet initialization')
+    console.log('   • Verify HybridTokenManager integration')
+    console.log('   • Test with unit tests: npm test')
+    console.log('   • Check network connectivity')
+
+    process.exit(1)
+  }
+}
+
+// Run the integration test
+testMainWalletIntegration()

package/examples/transactions/send-all-xec.js

@@ -0,0 +1,205 @@
+/*
+  Send all available XEC to another address.
+  This example shows how to empty your wallet by sending all funds to a recipient.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+// Get command line arguments
+const args = process.argv.slice(2)
+
+function showUsage () {
+  console.log('Usage: node send-all-xec.js <recipient_address>')
+  console.log('')
+  console.log('Examples:')
+  console.log('  node send-all-xec.js ecash:qp1234...abc')
+  console.log('')
+  console.log('Parameters:')
+  console.log('  recipient_address: XEC address starting with ecash:')
+  console.log('')
+  console.log('Warning: This will send ALL XEC in your wallet to the recipient!')
+  console.log('         Transaction fees will be automatically deducted from the amount.')
+}
+
+async function sendAllXec () {
+  try {
+    console.log('💸 Sending ALL XEC from wallet...\n')
+
+    // Check arguments
+    if (args.length !== 1) {
+      console.log('❌ Invalid arguments')
+      showUsage()
+      return
+    }
+
+    const recipientAddress = args[0]
+
+    // Validate arguments
+    if (!recipientAddress || !recipientAddress.startsWith('ecash:')) {
+      console.log('❌ Invalid recipient address. Must start with "ecash:"')
+      showUsage()
+      return
+    }
+
+    // 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
+
+    // Initialize wallet
+    await wallet.initialize()
+
+    console.log('💰 Checking wallet balance...')
+    const balance = await wallet.getXecBalance()
+
+    if (balance === 0) {
+      console.log('\n💸 Wallet is already empty!')
+      console.log('   There is no XEC to send.')
+      console.log('   Fund your wallet first to use this function.')
+      return
+    }
+
+    console.log('\n📋 Send All Transaction Details:')
+    console.log('═'.repeat(60))
+    console.log(`From: ${walletData.xecAddress}`)
+    console.log(`To: ${recipientAddress}`)
+    console.log(`Available Balance: ${balance.toLocaleString()} XEC`)
+    console.log('═'.repeat(60))
+
+    // Show UTXOs for transparency
+    console.log('\n🔍 Analyzing wallet UTXOs...')
+    const utxoData = await wallet.getUtxos()
+    const utxos = utxoData.utxos || []
+    const spendableUtxos = utxos.filter(utxo => utxo.blockHeight !== -1)
+
+    console.log(`Total UTXOs: ${utxos.length}`)
+    console.log(`Spendable UTXOs: ${spendableUtxos.length}`)
+
+    if (spendableUtxos.length === 0) {
+      console.log('\n⏳ No spendable UTXOs found!')
+      console.log('   All your XEC might be in unconfirmed transactions.')
+      console.log('   Wait for confirmations before trying to send.')
+      return
+    }
+
+    // Estimate the transaction fee
+    const estimatedFeeRate = 1.2 // sats per byte
+    const estimatedTxSize = (spendableUtxos.length * 150) + (1 * 34) + 10 // Rough estimate
+    const estimatedFee = (estimatedTxSize * estimatedFeeRate) / 100 // Convert to XEC
+    const estimatedAmountToSend = balance - estimatedFee
+
+    console.log(`Estimated Fee: ~${estimatedFee.toFixed(4)} XEC`)
+    console.log(`Estimated Amount to Send: ~${estimatedAmountToSend.toLocaleString()} XEC`)
+
+    // Warning about emptying wallet
+    console.log('\n⚠️  WALLET EMPTYING WARNING')
+    console.log('   This transaction will send ALL your XEC to the recipient!')
+    console.log('   After this transaction:')
+    console.log('   • Your wallet balance will be 0 XEC')
+    console.log('   • You will need to fund the wallet again to make new transactions')
+    console.log('   • Make sure the recipient address is correct!')
+    console.log('')
+    console.log('   🔐 SECURITY CHECK:')
+    console.log('   • Are you migrating to a new wallet?')
+    console.log('   • Are you sending to your own address?')
+    console.log('   • Have you verified the recipient address?')
+
+    // Confirm transaction
+    const readline = require('readline')
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    })
+
+    console.log(`\n   Recipient: ${recipientAddress}`)
+    const confirmed = await new Promise((resolve) => {
+      rl.question('\nAre you ABSOLUTELY SURE you want to empty your wallet? (type "YES" to confirm): ', (answer) => {
+        rl.close()
+        resolve(answer === 'YES')
+      })
+    })
+
+    if (!confirmed) {
+      console.log('❌ Transaction cancelled by user')
+      console.log('   Your XEC is safe in your wallet.')
+      return
+    }
+
+    console.log('\n🚀 Broadcasting send-all transaction...')
+
+    // Send all XEC to the recipient
+    const txid = await wallet.sendAllXec(recipientAddress)
+
+    console.log('\n✅ Send-all transaction sent successfully!')
+    console.log('═'.repeat(60))
+    console.log(`Transaction ID: ${txid}`)
+    console.log(`Recipient: ${recipientAddress}`)
+    console.log('═'.repeat(60))
+
+    // Get updated balance
+    console.log('\n💰 Checking final balance...')
+    const newBalance = await wallet.getXecBalance()
+    const actualAmountSent = balance - newBalance
+
+    console.log('\n📊 Final Transaction Summary:')
+    console.log(`Previous Balance: ${balance.toLocaleString()} XEC`)
+    console.log(`Amount Sent: ${actualAmountSent.toLocaleString()} XEC`)
+    console.log(`Final Balance: ${newBalance.toLocaleString()} XEC`)
+
+    if (newBalance > 0) {
+      console.log(`\n💡 Note: ${newBalance.toLocaleString()} XEC remains (dust or unconfirmed)`)
+    } else {
+      console.log('\n🎉 Wallet successfully emptied!')
+    }
+
+    console.log('\n🔗 View Transaction:')
+    console.log(`   Explorer: https://explorer.e.cash/tx/${txid}`)
+    console.log('   Note: It may take a few minutes to appear in the explorer')
+
+    console.log('\n📝 What happens next:')
+    console.log('   • The transaction is now being processed by the network')
+    console.log('   • Confirmation usually takes 1-10 minutes')
+    console.log('   • Your wallet is now empty (balance: 0 XEC)')
+    console.log('   • To use this wallet again, send XEC to:', walletData.xecAddress)
+
+    // Suggest next steps
+    if (newBalance === 0) {
+      console.log('\n💡 Suggested next steps:')
+      console.log('   • If migrating: Import your wallet elsewhere using the mnemonic')
+      console.log('   • If consolidating: You can delete the wallet.json file')
+      console.log('   • If temporarily emptying: Keep the wallet.json for future use')
+    }
+  } catch (err) {
+    console.error('❌ Failed to send all XEC:', err.message)
+
+    // Provide helpful error context
+    if (err.message.includes('insufficient')) {
+      console.log('\n💸 Insufficient Funds:')
+      console.log('   • Your wallet might not have enough XEC to cover transaction fees')
+      console.log('   • Try waiting for unconfirmed transactions to confirm')
+      console.log('   • Check if you have any spendable UTXOs')
+    } else if (err.message.includes('address')) {
+      console.log('\n📍 Address Error:')
+      console.log('   • Check that the recipient address is valid')
+      console.log('   • Make sure it starts with "ecash:"')
+      console.log('   • Verify the address with the recipient')
+    } else if (err.message.includes('network')) {
+      console.log('\n🌐 Network Error:')
+      console.log('   • Check your internet connection')
+      console.log('   • The network might be temporarily unavailable')
+      console.log('   • Try again in a few moments')
+    }
+
+    process.exit(1)
+  }
+}
+
+// Run the example
+sendAllXec()

package/examples/transactions/send-to-multiple.js

@@ -0,0 +1,217 @@
+/*
+  Send XEC to multiple recipients in a single transaction.
+  This example shows how to create a transaction with multiple outputs.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+// Get command line arguments
+const args = process.argv.slice(2)
+
+function showUsage () {
+  console.log('Usage: node send-to-multiple.js <address1> <amount1> <address2> <amount2> [...]')
+  console.log('')
+  console.log('Examples:')
+  console.log('  node send-to-multiple.js ecash:qp1234...abc 50 ecash:qr5678...def 30')
+  console.log('  node send-to-multiple.js ecash:qa1111...111 100 ecash:qb2222...222 25.5 ecash:qc3333...333 75')
+  console.log('')
+  console.log('Parameters:')
+  console.log('  addressN: XEC address starting with ecash:')
+  console.log('  amountN: Amount in XEC (minimum 5.46 XEC per output due to dust limit)')
+  console.log('')
+  console.log('Note: You can send to up to 100 recipients in a single transaction')
+  console.log('      Transaction fee will be automatically calculated and deducted')
+}
+
+function parseRecipients (args) {
+  if (args.length < 4 || args.length % 2 !== 0) {
+    return null
+  }
+
+  const recipients = []
+  for (let i = 0; i < args.length; i += 2) {
+    const address = args[i]
+    const amount = parseFloat(args[i + 1])
+
+    if (!address || !address.startsWith('ecash:')) {
+      console.log(`❌ Invalid address at position ${i + 1}: ${address}`)
+      return null
+    }
+
+    if (isNaN(amount) || amount <= 0) {
+      console.log(`❌ Invalid amount at position ${i + 2}: ${args[i + 1]}`)
+      return null
+    }
+
+    if (amount < 5.46) {
+      console.log(`❌ Amount too small at position ${i + 2}: ${amount} XEC (minimum 5.46 XEC due to dust limit)`)
+      return null
+    }
+
+    recipients.push({ address, amount })
+  }
+
+  return recipients
+}
+
+async function sendToMultiple () {
+  try {
+    console.log('📤 Sending XEC to multiple recipients...\n')
+
+    // Check arguments
+    if (args.length < 4) {
+      console.log('❌ Not enough arguments')
+      showUsage()
+      return
+    }
+
+    // Parse recipients
+    const recipients = parseRecipients(args)
+    if (!recipients) {
+      showUsage()
+      return
+    }
+
+    // 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
+
+    // Initialize wallet
+    await wallet.initialize()
+
+    console.log('💰 Checking wallet balance...')
+    const balance = await wallet.getXecBalance()
+
+    // Calculate total amount to send
+    const totalAmount = recipients.reduce((sum, recipient) => sum + recipient.amount, 0)
+
+    console.log('\n📋 Multi-Output Transaction Details:')
+    console.log('═'.repeat(70))
+    console.log(`From: ${walletData.xecAddress}`)
+    console.log(`Recipients: ${recipients.length}`)
+    console.log(`Total Amount: ${totalAmount.toLocaleString()} XEC`)
+    console.log(`Current Balance: ${balance.toLocaleString()} XEC`)
+    console.log('═'.repeat(70))
+
+    // Show all recipients
+    console.log('\n📨 Recipients:')
+    recipients.forEach((recipient, index) => {
+      const addressShort = `${recipient.address.substring(0, 20)}...${recipient.address.substring(recipient.address.length - 8)}`
+      console.log(`${index + 1}. ${addressShort}: ${recipient.amount.toLocaleString()} XEC`)
+    })
+
+    // Check if we have enough balance (rough estimate)
+    const estimatedFee = recipients.length * 0.01 // Rough estimate: 0.01 XEC per output
+    if (balance < totalAmount + estimatedFee) {
+      console.log('\n❌ Insufficient balance!')
+      console.log(`   Required: ~${(totalAmount + estimatedFee).toLocaleString()} XEC (including estimated fee)`)
+      console.log(`   Available: ${balance.toLocaleString()} XEC`)
+      console.log('   Fund your wallet or reduce the amounts')
+      return
+    }
+
+    // Confirm transaction
+    console.log('\n⚠️  Transaction Confirmation Required')
+    console.log('   This will send real XEC from your wallet!')
+    console.log('   Make sure all recipient addresses are correct.')
+    console.log(`   Total recipients: ${recipients.length}`)
+    console.log(`   Total amount: ${totalAmount.toLocaleString()} XEC`)
+
+    const readline = require('readline')
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    })
+
+    const confirmed = await new Promise((resolve) => {
+      rl.question('\nDo you want to proceed? (yes/no): ', (answer) => {
+        rl.close()
+        resolve(answer.toLowerCase() === 'yes' || answer.toLowerCase() === 'y')
+      })
+    })
+
+    if (!confirmed) {
+      console.log('❌ Transaction cancelled by user')
+      return
+    }
+
+    console.log('\n🚀 Broadcasting multi-output transaction...')
+
+    // Prepare the outputs
+    const outputs = recipients.map(recipient => ({
+      address: recipient.address,
+      amountSat: Math.round(recipient.amount * 100) // Convert XEC to satoshis
+    }))
+
+    // Send the transaction
+    const txid = await wallet.sendXec(outputs)
+
+    console.log('\n✅ Multi-output transaction sent successfully!')
+    console.log('═'.repeat(70))
+    console.log(`Transaction ID: ${txid}`)
+    console.log(`Recipients: ${recipients.length}`)
+    console.log(`Total Amount: ${totalAmount.toLocaleString()} XEC`)
+    console.log('═'.repeat(70))
+
+    // Get updated balance
+    console.log('\n💰 Getting updated balance...')
+    const newBalance = await wallet.getXecBalance()
+    const totalCost = balance - newBalance
+    const feePaid = totalCost - totalAmount
+
+    console.log('\n📊 Transaction Summary:')
+    console.log(`Previous Balance: ${balance.toLocaleString()} XEC`)
+    console.log(`Total Sent: ${totalAmount.toLocaleString()} XEC`)
+    console.log(`Fee Paid: ${feePaid.toLocaleString()} XEC`)
+    console.log(`Total Cost: ${totalCost.toLocaleString()} XEC`)
+    console.log(`New Balance: ${newBalance.toLocaleString()} XEC`)
+
+    console.log('\n📨 Delivery Summary:')
+    recipients.forEach((recipient, index) => {
+      const addressShort = `${recipient.address.substring(0, 15)}...${recipient.address.substring(recipient.address.length - 6)}`
+      console.log(`${index + 1}. ${addressShort}: ${recipient.amount.toLocaleString()} XEC ✅`)
+    })
+
+    console.log('\n🔗 View Transaction:')
+    console.log(`   Explorer: https://explorer.e.cash/tx/${txid}`)
+    console.log('   Note: It may take a few minutes to appear in the explorer')
+
+    console.log('\n💡 Benefits of Multi-Output Transactions:')
+    console.log('   • Lower total fees compared to separate transactions')
+    console.log('   • Single confirmation for all recipients')
+    console.log('   • More efficient use of blockchain space')
+  } catch (err) {
+    console.error('❌ Failed to send multi-output transaction:', err.message)
+
+    // Provide helpful error context
+    if (err.message.includes('insufficient')) {
+      console.log('\n💸 Insufficient Funds:')
+      console.log('   • Your wallet does not have enough XEC for this transaction')
+      console.log('   • Multi-output transactions require higher fees')
+      console.log('   • Try reducing amounts or number of recipients')
+    } else if (err.message.includes('address')) {
+      console.log('\n📍 Address Error:')
+      console.log('   • Check that all recipient addresses are valid')
+      console.log('   • Make sure they all start with "ecash:"')
+      console.log('   • Verify addresses with recipients')
+    } else if (err.message.includes('network')) {
+      console.log('\n🌐 Network Error:')
+      console.log('   • Check your internet connection')
+      console.log('   • The network might be temporarily unavailable')
+      console.log('   • Try again in a few moments')
+    }
+
+    process.exit(1)
+  }
+}
+
+// Run the example
+sendToMultiple()