minimal-xec-wallet 1.0.1

package/examples/README.md

@@ -0,0 +1,380 @@
+# Minimal XEC Wallet - Examples
+
+This directory contains comprehensive examples demonstrating how to use the minimal-xec-wallet library for eCash (XEC) blockchain operations.
+
+## 📁 Directory Structure
+
+```
+examples/
+├── wallet-creation/          # Create, restore, import wallets
+├── wallet-info/             # Check balance, UTXOs, transactions
+├── transactions/            # Send XEC, multi-output, send-all
+├── advanced/                # OP_RETURN, optimization, price checking
+├── key-management/          # Address derivation, validation
+├── utils/                   # Helper utilities (QR codes, wallet helper)
+├── test-examples.js         # End-to-end testing script
+└── README.md               # This file
+```
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Create Your First Wallet
+
+```bash
+cd examples
+node wallet-creation/create-new-wallet.js
+```
+
+This creates a `wallet.json` file that all other examples will use.
+
+### 3. Fund Your Wallet
+
+Your wallet needs XEC for transaction examples:
+
+```bash
+# Show your address with QR code for easy funding
+node utils/show-qr.js $(node -e "console.log(require('./wallet.json').xecAddress)")
+```
+
+Send XEC to the displayed address using:
+- [CashTab Wallet](https://cashtab.com)
+- Cryptocurrency exchanges (Binance, KuCoin, Gate.io)
+- Another XEC wallet
+
+### 4. Check Balance
+
+```bash
+node wallet-info/get-balance.js
+```
+
+### 5. Run All Examples
+
+```bash
+# Automated test suite with funding break
+node test-examples.js
+```
+
+## 📚 Example Categories
+
+### 🔑 Wallet Creation (`wallet-creation/`)
+
+| Example | Description | Requirements |
+|---------|-------------|--------------|
+| `create-new-wallet.js` | Generate new wallet with random mnemonic | None |
+| `restore-from-mnemonic.js` | Restore wallet from 12-word phrase | Mnemonic phrase |
+| `import-from-wif.js` | Import wallet from private key | WIF or hex private key |
+
+**Usage:**
+```bash
+# Create new wallet
+node wallet-creation/create-new-wallet.js
+
+# Restore from mnemonic (interactive or command line)
+node wallet-creation/restore-from-mnemonic.js
+node wallet-creation/restore-from-mnemonic.js word1 word2 ... word12
+
+# Import from private key (supports all WIF formats)
+node wallet-creation/import-from-wif.js L1234...abcd    # Mainnet compressed
+node wallet-creation/import-from-wif.js 51234...abcd    # Mainnet uncompressed
+node wallet-creation/import-from-wif.js c1234...abcd    # Testnet compressed
+node wallet-creation/import-from-wif.js 1234567890abcdef...  # Hex private key
+```
+
+### 💰 Wallet Information (`wallet-info/`)
+
+| Example | Description | Requirements |
+|---------|-------------|--------------|
+| `get-balance.js` | Display XEC balance and USD value | Wallet |
+| `get-utxos.js` | List all UTXOs with analysis | Wallet |
+| `get-transactions.js` | Show transaction history | Wallet |
+
+**Usage:**
+```bash
+node wallet-info/get-balance.js
+node wallet-info/get-utxos.js
+node wallet-info/get-transactions.js
+```
+
+### 💸 Transactions (`transactions/`)
+
+| Example | Description | Requirements |
+|---------|-------------|--------------|
+| `send-xec.js` | Send XEC to single recipient | Funded wallet |
+| `send-to-multiple.js` | Send XEC to multiple recipients | Funded wallet |
+| `send-all-xec.js` | Send all XEC (empty wallet) | Funded wallet |
+
+**Usage:**
+```bash
+# Send 100 XEC to an address
+node transactions/send-xec.js ecash:qp1234...abc 100
+
+# Send to multiple recipients
+node transactions/send-to-multiple.js ecash:qp123...abc 50 ecash:qr456...def 30
+
+# Send all XEC (empty wallet)
+node transactions/send-all-xec.js ecash:qp1234...abc
+```
+
+### ⚡ Advanced Features (`advanced/`)
+
+| Example | Description | Requirements |
+|---------|-------------|--------------|
+| `send-op-return.js` | Embed data in blockchain | Funded wallet |
+| `optimize-utxos.js` | Consolidate UTXOs for efficiency | Multiple UTXOs |
+| `get-xec-price.js` | Get current XEC/USD price | Internet connection |
+| `browser-compatibility-test.js` | Test browser WebAssembly compatibility | None |
+
+**Usage:**
+```bash
+# Embed message in blockchain
+node advanced/send-op-return.js "Hello XEC blockchain!"
+
+# UTXO optimization (preview)
+node advanced/optimize-utxos.js --dry-run
+node advanced/optimize-utxos.js
+
+# Get current XEC price
+node advanced/get-xec-price.js
+
+# Test browser compatibility (WebAssembly support)
+node advanced/browser-compatibility-test.js
+open browser-test.html  # Interactive browser test
+```
+
+### 🔐 Key Management (`key-management/`)
+
+| Example | Description | Requirements |
+|---------|-------------|--------------|
+| `derive-addresses.js` | Generate multiple addresses | HD wallet (mnemonic) |
+| `validate-address.js` | Validate XEC address format | None |
+| `export-to-wif.js` | Export private key to WIF format | Existing wallet |
+
+**Usage:**
+```bash
+# Generate 10 addresses from mnemonic
+node key-management/derive-addresses.js 10
+
+# Validate address format
+node key-management/validate-address.js ecash:qp1234...abc
+
+# Export private key to WIF (all formats)
+node key-management/export-to-wif.js
+```
+
+### 🪙 Token Operations (`tokens/`)
+
+| Example | Description | Requirements |
+|---------|-------------|--------------|
+| `list-all-tokens.js` | List all SLP and ALP tokens in wallet | Wallet with tokens |
+| `get-token-balance.js` | Get balance for specific token ID | Token ID |
+| `get-token-info.js` | Get comprehensive token metadata | Token ID |
+| `send-any-token.js` | Send SLP or ALP tokens to recipients | Funded wallet, tokens |
+| `burn-tokens.js` | Burn specific amount of tokens | Tokens to burn |
+| `test-main-wallet-integration.js` | Integration test for token API | Test tokens |
+
+**Usage:**
+```bash
+# List all tokens (auto-detects SLP and ALP)
+node tokens/list-all-tokens.js
+
+# Get balance for specific token
+node tokens/get-token-balance.js abc123def456...
+
+# Send tokens (works with both SLP and ALP)
+node tokens/send-any-token.js tokenId recipientAddress amount
+
+# Get token information
+node tokens/get-token-info.js abc123def456...
+
+# Burn tokens permanently
+node tokens/burn-tokens.js tokenId amount
+```
+
+### 🛠️ Utilities (`utils/`)
+
+| Utility | Description | Requirements |
+|---------|-------------|--------------|
+| `wallet-helper.js` | Wallet persistence library | Used by all examples |
+| `show-qr.js` | Display QR code for address | Valid XEC address |
+
+**Usage:**
+```bash
+# Show QR code for easy mobile scanning
+node utils/show-qr.js ecash:qp1234567890abcdef1234567890abcdef1234567890
+```
+
+## 🧪 Testing Examples
+
+### Automated Testing
+
+The `test-examples.js` script runs all examples in sequence with proper funding workflow:
+
+```bash
+node test-examples.js
+```
+
+**Test Flow:**
+1. **Phase 1: Wallet Creation** - Creates and validates wallet
+2. **Funding Break** - Shows QR code, waits for funding
+3. **Phase 2: Utilities** - Tests non-transaction features
+4. **Phase 3: Transactions** - Tests real XEC transactions (with confirmation)
+5. **Phase 4: Token Operations** - Tests SLP/ALP token functionality
+
+### Manual Testing
+
+Test individual examples:
+
+```bash
+# Test wallet creation
+node wallet-creation/create-new-wallet.js
+
+# Test balance checking
+node wallet-info/get-balance.js
+
+# Test transactions (requires funding)
+node transactions/send-xec.js ecash:qp3wjpa3tjlj042z2wv7hahsldgwhwy0rq9sywjpyy 1
+```
+
+## 💡 Best Practices
+
+### Security
+
+- **Never commit wallet.json** - Contains private keys
+- **Keep mnemonic phrases secure** - Anyone with your mnemonic can access funds
+- **Test with small amounts first** - Verify addresses before large transactions
+- **Backup your wallet** - Save mnemonic phrase safely
+
+### Development Workflow
+
+1. **Start with wallet creation examples**
+2. **Fund wallet for transaction testing**
+3. **Use dry-run modes when available**
+4. **Validate addresses before sending**
+5. **Monitor transactions with block explorer**
+
+### Error Handling
+
+- **Insufficient funds** - Check balance, fund wallet
+- **Invalid addresses** - Use address validation utility
+- **Network errors** - Check internet connection, try again
+- **Transaction failures** - Check fees, UTXOs, network status
+
+## 🔗 Useful Resources
+
+### XEC Network
+- **Block Explorer**: https://explorer.e.cash
+- **CashTab Wallet**: https://cashtab.com
+- **eCash.org**: https://e.cash
+
+### Exchanges (to buy XEC)
+- **Binance**: XEC/USDT, XEC/BTC
+- **KuCoin**: XEC/USDT
+- **Gate.io**: XEC/USDT
+
+### Development
+- **Library Source**: https://github.com/your-repo/minimal-xec-wallet
+- **API Documentation**: ../docs/
+- **Test Coverage**: Run `npm test`
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**1. "No wallet.json file found"**
+```bash
+# Solution: Create a wallet first
+node wallet-creation/create-new-wallet.js
+```
+
+**2. "Insufficient funds"**
+```bash
+# Solution: Fund your wallet
+node utils/show-qr.js $(node -e "console.log(require('./wallet.json').xecAddress)")
+# Then send XEC to the displayed address
+```
+
+**3. "Invalid address format"**
+```bash
+# Solution: Validate the address
+node key-management/validate-address.js YOUR_ADDRESS
+```
+
+**4. "Network connection error"**
+- Check internet connection
+- Try again in a few moments
+- Chronik indexer might be temporarily unavailable
+
+**5. "Transaction failed"**
+- Check wallet balance
+- Verify recipient address
+- Ensure sufficient fee coverage
+
+### Getting Help
+
+1. **Check error messages** - They usually explain the issue
+2. **Validate inputs** - Use validation utilities
+3. **Test with small amounts** - Before large transactions
+4. **Check network status** - Via block explorer
+5. **Review documentation** - This README and source code
+
+## 📝 Example Output
+
+### Successful Wallet Creation
+```
+🚀 Creating new XEC wallet...
+
+✅ New wallet created successfully!
+
+📋 New Wallet Details:
+══════════════════════════════════════════════════════
+Mnemonic: abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
+XEC Address: ecash:qrdczda80g7red03zqd02uuxjhfqxrthdywrq8cx3a
+HD Path: m/44'/899'/0'/0/0
+══════════════════════════════════════════════════════
+
+✅ Wallet saved to: /path/to/examples/wallet.json
+📍 XEC Address: ecash:qrdczda80g7red03zqd02uuxjhfqxrthdywrq8cx3a
+```
+
+### Successful Transaction
+```
+💸 Sending XEC transaction...
+
+📋 Transaction Details:
+════════════════════════════════════════════════════════════
+From: ecash:qrdczda80g7red03zqd02uuxjhfqxrthdywrq8cx3a
+To: ecash:qp3wjpa3tjlj042z2wv7hahsldgwhwy0rq9sywjpyy
+Amount: 100 XEC
+Current Balance: 1,000 XEC
+════════════════════════════════════════════════════════════
+
+✅ Transaction sent successfully!
+════════════════════════════════════════════════════════════
+Transaction ID: abc123def456...
+Amount Sent: 100 XEC
+Fee Paid: 0.01 XEC
+New Balance: 899.99 XEC
+════════════════════════════════════════════════════════════
+```
+
+## 🎯 Next Steps
+
+After running the examples:
+
+1. **Explore the source code** - Learn how each feature works
+2. **Build your own application** - Use these examples as templates
+3. **Work with eTokens** - SLP and ALP token operations
+4. **Contribute improvements** - Submit PRs for enhancements
+5. **Join the community** - eCash developer channels
+
+---
+
+**⚠️ Important**: These examples use real XEC on the mainnet. Always test with small amounts first!
+
+**🔐 Security Reminder**: Keep your mnemonic phrase secure. Anyone with access to it can control your funds.

package/examples/advanced/browser-compatibility-test.js

@@ -0,0 +1,263 @@
+/*
+  Browser Compatibility Test - WebAssembly Loading
+
+  Tests various WASM loading strategies for browser compatibility.
+  Demonstrates fallback mechanisms for older browsers.
+*/
+
+/* global WebAssembly, Worker, navigator, crypto */
+
+const MinimalXECWallet = require('../../index')
+
+// Browser compatibility detection utility
+function detectBrowserCapabilities () {
+  const capabilities = {
+    webAssembly: false,
+    webAssemblyCompile: false,
+    webAssemblyInstantiate: false,
+    webWorkers: false,
+    cryptoSubtle: false,
+    userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'Node.js'
+  }
+
+  try {
+    // WebAssembly support
+    if (typeof WebAssembly !== 'undefined') {
+      capabilities.webAssembly = true
+
+      if (typeof WebAssembly.compile === 'function') {
+        capabilities.webAssemblyCompile = true
+      }
+
+      if (typeof WebAssembly.instantiate === 'function') {
+        capabilities.webAssemblyInstantiate = true
+      }
+    }
+
+    // Web Worker support
+    if (typeof Worker !== 'undefined') {
+      capabilities.webWorkers = true
+    }
+
+    // Crypto.subtle support
+    if (typeof crypto !== 'undefined' && crypto.subtle) {
+      capabilities.cryptoSubtle = true
+    }
+  } catch (err) {
+    console.warn('Error detecting browser capabilities:', err.message)
+  }
+
+  return capabilities
+}
+
+// Test WebAssembly loading strategies
+async function testWASMStrategies () {
+  console.log('🧪 Testing WebAssembly Loading Strategies...\n')
+
+  const capabilities = detectBrowserCapabilities()
+
+  console.log('📊 Browser Capabilities:')
+  console.log('═══════════════════════════════════════════════')
+  console.log(`WebAssembly Support: ${capabilities.webAssembly ? '✅' : '❌'}`)
+  console.log(`WebAssembly.compile: ${capabilities.webAssemblyCompile ? '✅' : '❌'}`)
+  console.log(`WebAssembly.instantiate: ${capabilities.webAssemblyInstantiate ? '✅' : '❌'}`)
+  console.log(`Web Workers: ${capabilities.webWorkers ? '✅' : '❌'}`)
+  console.log(`Crypto.subtle: ${capabilities.cryptoSubtle ? '✅' : '❌'}`)
+  console.log(`User Agent: ${capabilities.userAgent}`)
+  console.log('═══════════════════════════════════════════════\n')
+
+  // Test different loading strategies
+  const strategies = [
+    {
+      name: 'Async Compilation',
+      available: capabilities.webAssemblyCompile,
+      description: 'Modern async WebAssembly.compile() method'
+    },
+    {
+      name: 'Web Worker Compilation',
+      available: capabilities.webWorkers && capabilities.webAssembly,
+      description: 'Compile WASM in worker thread (bypasses main thread restrictions)'
+    },
+    {
+      name: 'Chunked Loading',
+      available: capabilities.webAssembly,
+      description: 'Split large WASM into smaller chunks'
+    },
+    {
+      name: 'JavaScript Fallbacks',
+      available: true,
+      description: 'Pure JavaScript crypto implementations (always available)'
+    }
+  ]
+
+  console.log('⚙️ Available Loading Strategies:')
+  console.log('═══════════════════════════════════════════════')
+  strategies.forEach((strategy, index) => {
+    const status = strategy.available ? '✅ Available' : '❌ Not Available'
+    console.log(`${index + 1}. ${strategy.name}: ${status}`)
+    console.log(`   ${strategy.description}`)
+  })
+  console.log('═══════════════════════════════════════════════\n')
+
+  return capabilities
+}
+
+// Test wallet initialization with WASM compatibility
+async function testWalletCompatibility () {
+  console.log('🏦 Testing Wallet Initialization...\n')
+
+  try {
+    console.log('Creating wallet instance...')
+    const startTime = Date.now()
+
+    // Create wallet (this will trigger WASM initialization)
+    const wallet = new MinimalXECWallet()
+
+    console.log('Waiting for wallet creation...')
+    await wallet.walletInfoPromise
+
+    console.log('Waiting for WASM initialization...')
+    const wasmResult = await wallet.wasmInitPromise
+
+    console.log('Initializing wallet services...')
+    await wallet.initialize()
+
+    const endTime = Date.now()
+    const initTime = endTime - startTime
+
+    console.log('✅ Wallet initialization completed!')
+    console.log('═══════════════════════════════════════════════')
+    console.log(`Initialization Time: ${initTime}ms`)
+    console.log(`WASM Initialized: ${wasmResult ? '✅' : '❌ (using fallbacks)'}`)
+    console.log(`Wallet Address: ${wallet.walletInfo.xecAddress}`)
+    console.log(`Wallet Created: ${wallet.walletInfoCreated ? '✅' : '❌'}`)
+    console.log(`Services Initialized: ${wallet.isInitialized ? '✅' : '❌'}`)
+    console.log('═══════════════════════════════════════════════\n')
+
+    return {
+      success: true,
+      initTime,
+      wasmResult,
+      address: wallet.walletInfo.xecAddress
+    }
+  } catch (err) {
+    console.error('❌ Wallet initialization failed:')
+    console.error('═══════════════════════════════════════════════')
+    console.error(`Error: ${err.message}`)
+    console.error('═══════════════════════════════════════════════\n')
+
+    return {
+      success: false,
+      error: err.message
+    }
+  }
+}
+
+// Test basic wallet operations
+async function testBasicOperations () {
+  console.log('🔧 Testing Basic Wallet Operations...\n')
+
+  try {
+    const wallet = new MinimalXECWallet()
+    await wallet.walletInfoPromise
+    await wallet.wasmInitPromise
+    await wallet.initialize()
+
+    console.log('Testing wallet operations...')
+
+    // Test address validation
+    const isValidAddress = wallet._validateAddress(wallet.walletInfo.xecAddress)
+    console.log(`Address validation: ${isValidAddress ? '✅' : '❌'}`)
+
+    // Test key derivation
+    const keyPair = await wallet.getKeyPair(0)
+    console.log(`Key derivation: ${keyPair && keyPair.xecAddress ? '✅' : '❌'}`)
+
+    // Test WIF operations
+    const wif = wallet.exportPrivateKeyAsWIF()
+    const isValidWIF = wallet.validateWIF(wif)
+    console.log(`WIF operations: ${isValidWIF ? '✅' : '❌'}`)
+
+    // Test balance query (will fail without funds, but should not crash)
+    try {
+      await wallet.getXecBalance()
+      console.log('Balance query: ✅')
+    } catch (err) {
+      console.log(`Balance query: ⚠️ (${err.message})`)
+    }
+
+    console.log('\n✅ Basic operations test completed!')
+    return true
+  } catch (err) {
+    console.error(`❌ Basic operations failed: ${err.message}`)
+    return false
+  }
+}
+
+// Main test function
+async function runCompatibilityTests () {
+  console.log('🚀 Minimal XEC Wallet - Browser Compatibility Test\n')
+  console.log('This test checks WebAssembly loading and fallback mechanisms.\n')
+
+  const results = {
+    capabilities: null,
+    walletInit: null,
+    basicOps: null
+  }
+
+  try {
+    // Test 1: Browser capabilities
+    results.capabilities = await testWASMStrategies()
+
+    // Test 2: Wallet initialization
+    results.walletInit = await testWalletCompatibility()
+
+    // Test 3: Basic operations (only if wallet init succeeded)
+    if (results.walletInit.success) {
+      results.basicOps = await testBasicOperations()
+    }
+
+    // Final report
+    console.log('\n📋 Compatibility Test Summary:')
+    console.log('═══════════════════════════════════════════════')
+    console.log(`Browser Support: ${results.capabilities.webAssembly ? 'Modern' : 'Legacy'}`)
+    console.log(`Wallet Initialization: ${results.walletInit.success ? '✅' : '❌'}`)
+    console.log(`Basic Operations: ${results.basicOps ? '✅' : results.walletInit.success ? 'Skipped' : '❌'}`)
+
+    if (results.walletInit.success) {
+      console.log(`Initialization Time: ${results.walletInit.initTime}ms`)
+      console.log(`WASM Status: ${results.walletInit.wasmResult ? 'Active' : 'Fallback'}`)
+    }
+
+    console.log('═══════════════════════════════════════════════')
+
+    if (results.walletInit.success) {
+      console.log('\n🎉 SUCCESS: Wallet is compatible with this browser!')
+      console.log('You can use all wallet features normally.')
+    } else {
+      console.log('\n⚠️  WARNING: Wallet initialization failed in this browser.')
+      console.log('Please check browser console for detailed error messages.')
+    }
+
+    console.log('\n📚 For more info: https://github.com/your-repo/minimal-xec-wallet#browser-compatibility')
+  } catch (err) {
+    console.error('\n💥 Compatibility test crashed:', err.message)
+    console.error('Please report this issue with your browser details.')
+  }
+}
+
+// Run tests if this file is executed directly
+if (require.main === module) {
+  runCompatibilityTests().catch(err => {
+    console.error('Test execution failed:', err)
+    process.exit(1)
+  })
+}
+
+module.exports = {
+  detectBrowserCapabilities,
+  testWASMStrategies,
+  testWalletCompatibility,
+  testBasicOperations,
+  runCompatibilityTests
+}