minimal-xec-wallet 1.0.1

package/examples/wallet-creation/create-new-wallet.js

@@ -0,0 +1,67 @@
+/*
+  Create a new XEC wallet with a randomly generated mnemonic.
+  This example shows how to create a new wallet and save it to wallet.json.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+async function createNewWallet () {
+  try {
+    console.log('🚀 Creating new XEC wallet...\n')
+
+    // Check if wallet already exists
+    if (WalletHelper.walletExists()) {
+      console.log('⚠️  Wallet already exists!')
+      console.log('   Delete existing wallet first or use restore-from-mnemonic.js')
+      console.log('   Existing wallet path:', WalletHelper.getWalletPath())
+
+      // Show existing wallet info
+      const existingWallet = WalletHelper.loadWallet()
+      if (existingWallet) {
+        WalletHelper.displayWalletInfo(existingWallet)
+      }
+      return
+    }
+
+    // Create new wallet (no parameters = new random mnemonic)
+    const wallet = new MinimalXECWallet()
+
+    // Wait for wallet creation to complete
+    await wallet.walletInfoPromise
+
+    console.log('✅ New wallet created successfully!\n')
+
+    // Display the wallet information
+    console.log('📋 New Wallet Details:')
+    console.log('═'.repeat(50))
+    console.log(`Mnemonic: ${wallet.walletInfo.mnemonic}`)
+    console.log(`XEC Address: ${wallet.walletInfo.xecAddress}`)
+    console.log(`HD Path: ${wallet.walletInfo.hdPath}`)
+    console.log('═'.repeat(50))
+
+    // Save to wallet.json file
+    const saved = WalletHelper.saveWallet(wallet.walletInfo, 'New XEC Wallet')
+
+    if (saved) {
+      console.log('\n🎉 Wallet ready for use!')
+      console.log('   You can now run other examples to interact with your wallet')
+      console.log('   Next steps:')
+      console.log('   • Fund your wallet by sending XEC to:', wallet.walletInfo.xecAddress)
+      console.log('   • Check balance: node examples/wallet-info/get-balance.js')
+      console.log('   • View transactions: node examples/wallet-info/get-transactions.js')
+    }
+
+    // Security reminder
+    console.log('\n🔐 SECURITY REMINDER:')
+    console.log('   • Keep your mnemonic phrase safe and private')
+    console.log('   • Anyone with your mnemonic can access your funds')
+    console.log('   • Consider backing up your wallet: the mnemonic is in wallet.json')
+  } catch (err) {
+    console.error('❌ Failed to create wallet:', err.message)
+    process.exit(1)
+  }
+}
+
+// Run the example
+createNewWallet()

package/examples/wallet-creation/import-from-wif.js

@@ -0,0 +1,135 @@
+/*
+  Import an XEC wallet from a WIF (Wallet Import Format) private key.
+  This example shows how to import a single private key and save it to wallet.json.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+// Get WIF from command line argument or prompt for input
+const readline = require('readline')
+
+async function getWifFromUser () {
+  // Check if WIF provided as command line argument
+  const args = process.argv.slice(2)
+  if (args.length === 1 && (args[0].length === 52 || args[0].length === 64)) {
+    return args[0]
+  }
+
+  // Prompt user for WIF
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  return new Promise((resolve) => {
+    rl.question('Enter your WIF private key (K/L/5 for mainnet, c/9 for testnet) or hex private key: ', (wif) => {
+      rl.close()
+      resolve(wif.trim())
+    })
+  })
+}
+
+async function importFromWif () {
+  try {
+    console.log('📥 Importing XEC wallet from private key...\n')
+
+    // Check if wallet already exists
+    if (WalletHelper.walletExists()) {
+      console.log('⚠️  Wallet already exists!')
+      console.log('   This will overwrite your existing wallet.')
+
+      // Create backup first
+      const backupPath = WalletHelper.backupWallet()
+      if (backupPath) {
+        console.log(`   Backup created: ${backupPath}`)
+      }
+    }
+
+    // Get WIF from user
+    const wif = await getWifFromUser()
+
+    if (!wif) {
+      console.error('❌ No private key provided.')
+      console.log('   Usage: node import-from-wif.js <WIF_OR_HEX_PRIVATE_KEY>')
+      console.log('   WIF example: L1234...abcd (52 characters starting with K or L)')
+      console.log('   Hex example: 1234567890abcdef... (64 hex characters)')
+      process.exit(1)
+    }
+
+    console.log('🔍 Validating private key...')
+
+    // Create a temporary wallet instance to validate WIF
+    const tempWallet = new MinimalXECWallet()
+    await tempWallet.walletInfoPromise
+
+    // Check if it's a valid WIF format
+    const isValidWIF = tempWallet.validateWIF(wif)
+    const isHex = wif.length === 64 && /^[a-fA-F0-9]+$/.test(wif)
+
+    if (!isValidWIF && !isHex) {
+      console.error('❌ Invalid private key format.')
+      console.log('   Expected formats:')
+      console.log('   • WIF: 51-52 characters (K/L/5 for mainnet, c/9 for testnet)')
+      console.log('   • Hex: 64 hexadecimal characters')
+      console.log(`   Provided: ${wif.length} characters`)
+      if (wif.length >= 50 && wif.length <= 53) {
+        console.log('   Note: This looks like a WIF but failed validation (invalid checksum?)')
+      }
+      process.exit(1)
+    }
+
+    // Create wallet from WIF/hex private key
+    const wallet = new MinimalXECWallet(wif)
+
+    // Wait for wallet creation to complete
+    await wallet.walletInfoPromise
+
+    console.log('✅ Wallet imported successfully!\n')
+
+    // Display the wallet information
+    console.log('📋 Imported Wallet Details:')
+    console.log('═'.repeat(50))
+    console.log(`XEC Address: ${wallet.walletInfo.xecAddress}`)
+    console.log(`Key Type: ${isValidWIF ? 'WIF' : 'Hex'} Private Key`)
+    console.log(`HD Path: ${wallet.walletInfo.hdPath || 'N/A (single key import)'}`)
+    if (isValidWIF) {
+      console.log(`Compression: ${wallet.walletInfo.isCompressed ? 'Compressed' : 'Uncompressed'}`)
+      console.log(`Original WIF: ${wallet.walletInfo.wif}`)
+    }
+    console.log('═'.repeat(50))
+
+    // Save to wallet.json file
+    const saved = WalletHelper.saveWallet(wallet.walletInfo, 'Imported XEC Wallet')
+
+    if (saved) {
+      console.log('\n🎉 Wallet imported and ready for use!')
+      console.log('   You can now run other examples to interact with your wallet')
+      console.log('   Next steps:')
+      console.log('   • Check balance: node examples/wallet-info/get-balance.js')
+      console.log('   • View UTXOs: node examples/wallet-info/get-utxos.js')
+      console.log('   • Send XEC: node examples/transactions/send-xec.js')
+    }
+
+    // Important note for imported keys
+    console.log('\n📝 IMPORTANT NOTE:')
+    if (!wallet.walletInfo.mnemonic) {
+      console.log('   • This wallet was imported from a single private key')
+      console.log('   • No mnemonic phrase available for recovery')
+      console.log('   • Make sure to backup your private key safely')
+      console.log('   • For HD wallet features, use restore-from-mnemonic.js instead')
+    }
+
+    // Security reminder
+    console.log('\n🔐 SECURITY REMINDER:')
+    console.log('   • Your private key is now stored in wallet.json')
+    console.log('   • Keep this file secure and private')
+    console.log('   • Anyone with your private key can access your funds')
+  } catch (err) {
+    console.error('❌ Failed to import wallet:', err.message)
+    process.exit(1)
+  }
+}
+
+// Run the example
+importFromWif()

package/examples/wallet-creation/restore-from-mnemonic.js

@@ -0,0 +1,100 @@
+/*
+  Restore an existing XEC wallet from a 12-word mnemonic phrase.
+  This example shows how to recover a wallet and save it to wallet.json.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+// Get mnemonic from command line argument or prompt for input
+const readline = require('readline')
+
+async function getMnemonicFromUser () {
+  // Check if mnemonic provided as command line argument
+  const args = process.argv.slice(2)
+  if (args.length >= 12) {
+    return args.join(' ')
+  }
+
+  // Prompt user for mnemonic
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  return new Promise((resolve) => {
+    rl.question('Enter your 12-word mnemonic phrase: ', (mnemonic) => {
+      rl.close()
+      resolve(mnemonic.trim())
+    })
+  })
+}
+
+async function restoreFromMnemonic () {
+  try {
+    console.log('🔄 Restoring XEC wallet from mnemonic...\n')
+
+    // Check if wallet already exists
+    if (WalletHelper.walletExists()) {
+      console.log('⚠️  Wallet already exists!')
+      console.log('   This will overwrite your existing wallet.')
+
+      // Create backup first
+      const backupPath = WalletHelper.backupWallet()
+      if (backupPath) {
+        console.log(`   Backup created: ${backupPath}`)
+      }
+    }
+
+    // Get mnemonic from user
+    const mnemonic = await getMnemonicFromUser()
+
+    if (!mnemonic || mnemonic.split(' ').length !== 12) {
+      console.error('❌ Invalid mnemonic. Please provide a 12-word mnemonic phrase.')
+      console.log('   Usage: node restore-from-mnemonic.js word1 word2 ... word12')
+      console.log('   Or run without arguments to be prompted for input')
+      process.exit(1)
+    }
+
+    console.log('🔍 Validating mnemonic...')
+
+    // Create wallet from mnemonic
+    const wallet = new MinimalXECWallet(mnemonic)
+
+    // Wait for wallet creation to complete
+    await wallet.walletInfoPromise
+
+    console.log('✅ Wallet restored successfully!\n')
+
+    // Display the wallet information
+    console.log('📋 Restored Wallet Details:')
+    console.log('═'.repeat(50))
+    console.log(`XEC Address: ${wallet.walletInfo.xecAddress}`)
+    console.log(`HD Path: ${wallet.walletInfo.hdPath}`)
+    console.log('═'.repeat(50))
+
+    // Save to wallet.json file
+    const saved = WalletHelper.saveWallet(wallet.walletInfo, 'Restored XEC Wallet')
+
+    if (saved) {
+      console.log('\n🎉 Wallet restored and ready for use!')
+      console.log('   You can now run other examples to interact with your wallet')
+      console.log('   Next steps:')
+      console.log('   • Check balance: node examples/wallet-info/get-balance.js')
+      console.log('   • View UTXOs: node examples/wallet-info/get-utxos.js')
+      console.log('   • View transactions: node examples/wallet-info/get-transactions.js')
+    }
+
+    // Security reminder
+    console.log('\n🔐 SECURITY REMINDER:')
+    console.log('   • Your mnemonic phrase is now stored in wallet.json')
+    console.log('   • Keep this file secure and private')
+    console.log('   • Consider encrypting sensitive data for production use')
+  } catch (err) {
+    console.error('❌ Failed to restore wallet:', err.message)
+    process.exit(1)
+  }
+}
+
+// Run the example
+restoreFromMnemonic()

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

@@ -0,0 +1,99 @@
+/*
+  Get the XEC balance of your wallet.
+  This example shows how to check your wallet's balance using the saved wallet.json.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+async function getBalance () {
+  try {
+    console.log('💰 Getting XEC wallet balance...\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 balance from blockchain...')
+
+    // Get detailed balance for the wallet
+    const detailedBalance = await wallet.getDetailedBalance()
+
+    console.log('\n📊 Balance Information:')
+    console.log('═'.repeat(50))
+    console.log(`XEC Address: ${walletData.xecAddress}`)
+    console.log(`Total Balance: ${detailedBalance.total.toLocaleString()} XEC`)
+    console.log(`  • Confirmed: ${detailedBalance.confirmed.toLocaleString()} XEC`)
+    console.log(`  • Unconfirmed: ${detailedBalance.unconfirmed.toLocaleString()} XEC`)
+    console.log(`Total Satoshis: ${detailedBalance.satoshis.total.toLocaleString()}`)
+
+    // Show confirmation status
+    if (detailedBalance.unconfirmed > 0) {
+      console.log(`⏳ ${detailedBalance.unconfirmed} XEC pending confirmation`)
+    }
+    if (detailedBalance.confirmed > 0) {
+      console.log(`✅ ${detailedBalance.confirmed} XEC confirmed`)
+    }
+    console.log('═'.repeat(50))
+
+    // Show balance in different formats
+    if (detailedBalance.total > 0) {
+      console.log('\n💵 Balance Breakdown:')
+      console.log(`• ${detailedBalance.total} XEC`)
+      console.log(`• ${detailedBalance.satoshis.total} satoshis`)
+      console.log(`• ${(detailedBalance.total / 1000000).toFixed(6)} Million XEC`)
+
+      // Approximate USD value (if price available)
+      try {
+        const xecUsdPrice = await wallet.getXecUsd()
+        if (xecUsdPrice > 0) {
+          const usdValue = detailedBalance.total * xecUsdPrice
+          console.log(`• ~$${usdValue.toFixed(6)} USD (at $${xecUsdPrice.toFixed(8)} per XEC)`)
+        }
+      } catch (err) {
+        console.log('• USD value unavailable (price API error)')
+      }
+    } else {
+      console.log('\n💸 Your wallet is empty!')
+      console.log('   To receive XEC, share your address:', walletData.xecAddress)
+      console.log('   You can fund your wallet from:')
+      console.log('   • A eCash exchange')
+      console.log('   • Another XEC wallet')
+      console.log('   • eCash faucets (for testnet)')
+    }
+
+    // Show additional info for empty wallets
+    if (detailedBalance.total === 0) {
+      console.log('\n🔗 Useful Links:')
+      console.log('   • Block Explorer: https://explorer.e.cash')
+      console.log('   • CashTab Wallet: https://cashtab.com')
+      console.log('   • eCash.org: https://e.cash')
+    }
+  } catch (err) {
+    console.error('❌ Failed to get balance:', 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')
+    } else if (err.message.includes('address')) {
+      console.log('\n📍 Address Error:')
+      console.log('   • Your wallet.json might be corrupted')
+      console.log('   • Try restoring from mnemonic')
+    }
+
+    process.exit(1)
+  }
+}
+
+// Run the example
+getBalance()

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

@@ -0,0 +1,157 @@
+/*
+  Get the transaction history of your wallet.
+  This example shows how to view all transactions associated with your wallet address.
+*/
+
+const MinimalXECWallet = require('../../index')
+const WalletHelper = require('../utils/wallet-helper')
+
+async function getTransactions () {
+  try {
+    console.log('📜 Getting wallet transaction history...\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 transaction history from blockchain...')
+
+    // Get transaction history (default: descending order - newest first)
+    const transactions = await wallet.getTransactions()
+
+    console.log('\n📋 Transaction History:')
+    console.log('═'.repeat(80))
+    console.log(`XEC Address: ${walletData.xecAddress}`)
+    console.log(`Total Transactions: ${transactions.length}`)
+    console.log('═'.repeat(80))
+
+    if (transactions.length === 0) {
+      console.log('\n📭 No transactions found!')
+      console.log('   Your wallet address has no transaction history.')
+      console.log('   This means:')
+      console.log('   • This is a new wallet that has never been used')
+      console.log('   • The address has never received or sent any XEC')
+      console.log('')
+      console.log('   To get started:')
+      console.log('   • Send some XEC to your address:', walletData.xecAddress)
+      console.log('   • Use a faucet (for testnet)')
+      console.log('   • Receive XEC from another wallet')
+      return
+    }
+
+    // Analyze transactions
+    let receivedCount = 0
+    let sentCount = 0
+    let totalReceived = 0
+    let totalSent = 0
+
+    console.log('\n📊 Transaction List (most recent first):')
+    console.log('─'.repeat(80))
+
+    transactions.slice(0, 10).forEach((tx, index) => {
+      const txidShort = `${tx.txid.substring(0, 12)}...${tx.txid.substring(52)}`
+      const isConfirmed = tx.block !== null
+      const status = isConfirmed ? '✅ Confirmed' : '⏳ Pending'
+
+      console.log(`${index + 1}. ${txidShort} - ${status}`)
+
+      if (isConfirmed) {
+        const date = new Date(tx.block.timestamp * 1000).toLocaleString()
+        console.log(`   Block: ${tx.block.height} | Time: ${date}`)
+      } else {
+        console.log('   Block: Unconfirmed | Time: Pending')
+      }
+
+      // Analyze inputs and outputs to determine if this was received or sent
+      let isReceived = false
+      let isSent = false
+      let netAmount = 0
+
+      // Check outputs for our address
+      tx.outputs.forEach(output => {
+        if (output.script && output.script.includes(walletData.xecAddress.replace('ecash:', ''))) {
+          isReceived = true
+          netAmount += parseInt(output.value)
+        }
+      })
+
+      // Check inputs for our address (indicates we sent this transaction)
+      tx.inputs.forEach(input => {
+        if (input.prevOut && input.prevOut.script &&
+            input.prevOut.script.includes(walletData.xecAddress.replace('ecash:', ''))) {
+          isSent = true
+          netAmount -= parseInt(input.prevOut.value)
+        }
+      })
+
+      if (isReceived && !isSent) {
+        console.log(`   📥 Received: ${(netAmount / 100).toLocaleString()} XEC`)
+        receivedCount++
+        totalReceived += netAmount
+      } else if (isSent && !isReceived) {
+        console.log(`   📤 Sent: ${(Math.abs(netAmount) / 100).toLocaleString()} XEC`)
+        sentCount++
+        totalSent += Math.abs(netAmount)
+      } else if (isSent && isReceived) {
+        const action = netAmount > 0 ? 'Net Received' : 'Net Sent'
+        console.log(`   🔄 ${action}: ${(Math.abs(netAmount) / 100).toLocaleString()} XEC`)
+      }
+
+      console.log(`   Inputs: ${tx.inputs.length} | Outputs: ${tx.outputs.length}`)
+      console.log()
+    })
+
+    if (transactions.length > 10) {
+      console.log(`... and ${transactions.length - 10} more transactions`)
+      console.log('💡 Use transaction explorer for full history')
+    }
+
+    // Transaction summary
+    console.log('\n📈 Transaction Summary:')
+    console.log('─'.repeat(80))
+    console.log(`Total Transactions: ${transactions.length}`)
+    console.log(`Received Transactions: ${receivedCount}`)
+    console.log(`Sent Transactions: ${sentCount}`)
+    console.log(`Total Received: ${(totalReceived / 100).toLocaleString()} XEC`)
+    console.log(`Total Sent: ${(totalSent / 100).toLocaleString()} XEC`)
+    console.log(`Net Balance: ${((totalReceived - totalSent) / 100).toLocaleString()} XEC`)
+
+    // Show pending transactions warning
+    const pendingTxs = transactions.filter(tx => tx.block === null)
+    if (pendingTxs.length > 0) {
+      console.log('\n⚠️  Pending Transactions:')
+      console.log(`   You have ${pendingTxs.length} unconfirmed transaction(s)`)
+      console.log('   These transactions are waiting to be included in a block')
+      console.log('   Confirmation usually takes 1-10 minutes')
+    }
+
+    // Explorer links
+    console.log('\n🔗 Explore More:')
+    console.log(`   Address Explorer: https://explorer.e.cash/address/${walletData.xecAddress}`)
+    if (transactions.length > 0) {
+      console.log(`   Latest TX: https://explorer.e.cash/tx/${transactions[0].txid}`)
+    }
+  } catch (err) {
+    console.error('❌ Failed to get transactions:', 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
+getTransactions()