minimal-xec-wallet

A minimalist eCash (XEC) wallet npm library for web applications with full SLP and ALP token support.

🎯 Features

✅ Core Wallet Operations

• HD Wallets: BIP44 hierarchical deterministic key generation
• Import/Export: Support for mnemonic phrases, WIF, and hex private keys
• Address Management: XEC address generation and validation
• Balance Queries: Real-time XEC balance with confirmed/unconfirmed breakdown

✅ XEC Transactions

• Send XEC: Single and multi-output transactions
• Send All: Empty wallet functionality
• Fee Optimization: Intelligent UTXO selection and fee calculation
• UTXO Consolidation: Automatic optimization for better performance

✅ eToken Support (SLP + ALP)

• Protocol Auto-Detection: Automatic SLP/ALP protocol identification
• Token Operations: Send, burn, list tokens across both protocols
• Token Metadata: Automatic fetching of token info (name, symbol, decimals)
• Hybrid Management: Unified API for both SLP and ALP tokens

✅ Advanced Features

• OP_RETURN: Embed data in blockchain transactions
• Security: AES-256 mnemonic encryption, dust attack protection
• Network Resilience: Multiple Chronik endpoint failover
• Price Queries: Real-time XEC/USD pricing

🚀 Quick Start

Installation

npm install minimal-xec-wallet

Basic Usage

const MinimalXECWallet = require('minimal-xec-wallet')

// Create new wallet
const wallet = new MinimalXECWallet()
await wallet.initialize()

// Check balance
const balance = await wallet.getXecBalance()
console.log(`Balance: ${balance} XEC`)

// Send XEC
const txid = await wallet.sendXec([
  { address: 'ecash:qp3wjpa3tjlj042z2wv7hahsldgwhwy0rq9sywjpyy', amountSats: 10000 }
])

// List all tokens (SLP + ALP)
const tokens = await wallet.listETokens()
tokens.forEach(token => {
  console.log(`${token.ticker}: ${token.balance}`)
})

// Send tokens
await wallet.sendETokens('tokenId...', [
  { address: 'ecash:qp123...', amount: 100 }
])

Browser Usage

<script src="https://unpkg.com/minimal-xec-wallet/dist/minimal-xec-wallet.min.js"></script>
<script>
  const wallet = new MinimalXecWallet()

  // Initialize with automatic browser compatibility
  wallet.initialize().then(() => {
    console.log('Wallet ready for all browsers!')
    // Use same API as Node.js
  })
</script>

Browser Compatibility: Automatic WebAssembly loading with JavaScript fallbacks for older browsers. See Browser Compatibility Guide for details.

📚 Documentation

API Reference

• Complete API Documentation - All methods with examples
• Examples Collection - 25+ working examples
• Development Docs - Architecture and implementation details
• Browser Compatibility Guide - WebAssembly and fallback support

Quick Links

• Wallet Creation Examples - Create, restore, import wallets
• Transaction Examples - Send XEC, multi-output, send-all
• Token Examples - SLP/ALP token operations
• Advanced Examples - OP_RETURN, optimization, price queries, compatibility testing

🧪 Testing

Run Tests

# All tests (424 unit + 29 integration)
npm run test:all

# Unit tests only (fast)
npm run test:unit

# Integration tests (requires network)
npm run test:integration

# Test coverage report
npm run test:coverage

# Browser compatibility test
node examples/advanced/browser-compatibility-test.js

Example Testing

# Run all examples with guided testing
node examples/test-examples.js

# Test specific functionality
node examples/tokens/list-all-tokens.js
node examples/transactions/send-xec.js

# Test browser compatibility
node examples/advanced/browser-compatibility-test.js

🏗️ Architecture

Modern Design

• Modular Architecture: Clean separation of concerns
• Protocol Agnostic: Supports both SLP and ALP token standards
• Network Resilient: Multiple Chronik endpoint failover
• Security First: Built-in protections against common attacks

Core Components

• HybridTokenManager: Unified SLP/ALP token operations
• RobustChronikRouter: Network failover and error handling
• ConsolidateUtxos: UTXO optimization engine
• KeyDerivation: HD wallet key management

Dependencies

• chronik-client: eCash blockchain indexer
• ecash-lib: Core eCash transaction building
• @scure/bip39: Secure mnemonic generation
• crypto-js: AES encryption for mnemonics

🔧 Advanced Configuration

Custom Options

const wallet = new MinimalXECWallet(mnemonic, {
  hdPath: "m/44'/899'/0'/0/0",        // Custom derivation path
  fee: 2.0,                          // Fee rate in sats/byte
  chronikUrls: ['https://chronik.e.cash'], // Custom endpoints
  enableDonations: false,            // Privacy mode
  password: 'secure123'              // Mnemonic encryption
})

Environment Variables

# Test mode
NODE_ENV=test npm test

# Development mode
NODE_ENV=development npm start

🤝 Contributing

Development Setup

git clone https://github.com/zh/minimal-xec-wallet
cd minimal-xec-wallet
npm install
npm run test:unit

Code Quality

# Linting
npm run lint

# Build for browser
npm run build

# Generate API docs
npm run docs

📊 Project Stats

• 424 Unit Tests - Comprehensive coverage of all features
• 29 Integration Tests - Real network validation
• 25+ Examples - Working code for all use cases
• 6 Token Protocols - SLP Type 1, ALP Standard, auto-detection
• 7 Chronik Endpoints - Robust network failover

🔗 Resources

eCash Ecosystem

• eCash - Official eCash website
• CashTab Wallet - Reference web wallet
• Block Explorer - Transaction lookup

Development

• Chronik Indexer - Blockchain API
• ecash-lib Documentation - Core library
• SLP and ALP tokens - CashTab token protocols

📄 License

MIT License - see LICENSE file for details.

🤔 Support

• Issues: GitHub Issues
• Examples: See ./examples directory for working code
• API Docs: Run npm run docs for detailed API documentation
• Community: eCash developer channels

Security Notice: This library handles real cryptocurrency. Always test with small amounts first and keep your mnemonic phrases secure.