minimal-xec-wallet

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


🎯 Features

$3

- 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

$3

- 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

$3

- 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

$3

- Instant Finality: ~3 second transaction confirmation via Avalanche consensus
- Optional Finality Wait: Choose between immediate broadcast or finalized confirmation
- Configurable Defaults: Set wallet-wide finality preferences
- All Methods Supported: sendXec, sendAllXec, sendOpReturn, sendETokens

$3

- 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

$3

- Smart Classification: Age, value, privacy, and health analysis
- Health Monitoring: Real-time wallet health assessment
- Dust Attack Detection: Automated threat identification and mitigation
- Intelligent Coin Selection: Multiple strategies (efficient, privacy, balanced)
- Optimization Recommendations: Automated consolidation and improvement suggestions
- Custom HD Paths: Support for different derivation paths (standard eCash, CashTab)

🚀 Quick Start

$3

``bash
npm install minimal-xec-wallet
`

$3

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

// Create new wallet with analytics enabled
const wallet = new MinimalXECWallet(null, {
utxoAnalytics: { enabled: true }
})
await wallet.initialize()

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

// Get wallet health report
const health = await wallet.utxos.getWalletHealthReport()
console.log(Health Score: ${health.summary.healthPercentage}%)

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

// Send XEC with Avalanche instant finality (~3 seconds)
const txid = await wallet.sendXec(
[{ address: 'ecash:qp3wjpa3tjlj042z2wv7hahsldgwhwy0rq9sywjpyy', amountSats: 10000 }],
{ awaitFinality: true }
)

// 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 }
])
`

$3

`html


`

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

📚 Documentation

$3

- Complete API Documentation - All methods with examples
- Examples Collection - 25+ working examples
- Browser Compatibility Guide - WebAssembly and fallback support

$3

- 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
- Analytics Examples - UTXO classification, health monitoring, smart selection

🧪 Testing

$3

`bash


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
`

$3

`bash


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

$3

- 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

$3

- HybridTokenManager: Unified SLP/ALP token operations
- RobustChronikRouter: Network failover and error handling
- ConsolidateUtxos: UTXO optimization engine
- KeyDerivation: HD wallet key management
- UtxoClassifier: Advanced UTXO classification and analysis
- UtxoHealthMonitor: Real-time health monitoring and threat detection

$3

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

🔧 Advanced Configuration

$3

`javascript
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
utxoAnalytics: { // Enable advanced analytics
enabled: true,
debug: false,
classificationConfig: {
ageThresholds: {
fresh: 6, // ~1 hour
recent: 144, // ~1 day
mature: 1008, // ~1 week
aged: 4032 // ~1 month
}
}
}
})
`

$3

`bash


Test mode

NODE_ENV=test npm test

Development mode

NODE_ENV=development npm start
`

🤝 Contributing

$3

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

$3

`bash


Linting

npm run lint

Build for browser

npm run build

Generate API docs

npm run docs
`

📊 Project Stats

- 509+ Unit Tests - Comprehensive coverage including analytics and Avalanche finality
- 35+ Integration Tests - Real network validation with analytics
- 30+ Examples - Working code for all use cases including analytics demos
- 6 Token Protocols - SLP Type 1, ALP Standard, auto-detection
- 7 Chronik Endpoints - Robust network failover
- 5 UTXO Classification Categories - Age, value, health, privacy analysis
- 4 Coin Selection Strategies - Efficient, privacy, balanced, conservative

🔗 Resources

$3

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

$3

- 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
- Analytics Examples: See ./examples/analytics for advanced features
- 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.