https://github.com/zh/minimal-xec-wallet
A minimalist eCash (XEC) wallet npm library, for use in web apps. Supports eTokens.
https://github.com/zh/minimal-xec-wallet
Last synced: 10 months ago
JSON representation
A minimalist eCash (XEC) wallet npm library, for use in web apps. Supports eTokens.
- Host: GitHub
- URL: https://github.com/zh/minimal-xec-wallet
- Owner: zh
- License: mit
- Created: 2025-08-19T12:58:25.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-11T11:28:38.000Z (11 months ago)
- Last Synced: 2025-09-11T14:09:46.063Z (11 months ago)
- Language: JavaScript
- Size: 1.58 MB
- Stars: 3
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# minimal-xec-wallet
A minimalist eCash (XEC) wallet npm library for web applications with full SLP and ALP token support.
[](https://badge.fury.io/js/minimal-xec-wallet)
[](./test/)
[](https://opensource.org/licenses/MIT)
## 🎯 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
```bash
npm install minimal-xec-wallet
```
### Basic Usage
```javascript
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
```html
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
})
```
**Browser Compatibility**: Automatic WebAssembly loading with JavaScript fallbacks for older browsers. See [Browser Compatibility Guide](./docs/BROWSER_COMPATIBILITY.md) for details.
## 📚 Documentation
### API Reference
- **[Complete API Documentation](./WALLET_API.md)** - All methods with examples
- **[Examples Collection](./examples/README.md)** - 25+ working examples
- **[Development Docs](./docs/README.md)** - Architecture and implementation details
- **[Browser Compatibility Guide](./docs/BROWSER_COMPATIBILITY.md)** - WebAssembly and fallback support
### Quick Links
- **[Wallet Creation Examples](./examples/wallet-creation/)** - Create, restore, import wallets
- **[Transaction Examples](./examples/transactions/)** - Send XEC, multi-output, send-all
- **[Token Examples](./examples/tokens/)** - SLP/ALP token operations
- **[Advanced Examples](./examples/advanced/)** - OP_RETURN, optimization, price queries, compatibility testing
## 🧪 Testing
### Run Tests
```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
```
### Example Testing
```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
### 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
```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
})
```
### Environment Variables
```bash
# Test mode
NODE_ENV=test npm test
# Development mode
NODE_ENV=development npm start
```
## 🤝 Contributing
### Development Setup
```bash
git clone https://github.com/zh/minimal-xec-wallet
cd minimal-xec-wallet
npm install
npm run test:unit
```
### Code Quality
```bash
# 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](https://e.cash)** - Official eCash website
- **[CashTab Wallet](https://cashtab.com)** - Reference web wallet
- **[Block Explorer](https://explorer.e.cash)** - Transaction lookup
### Development
- **[Chronik Indexer](https://chronik.e.cash/)** - Blockchain API
- **[ecash-lib Documentation](https://www.npmjs.com/package/ecash-lib)** - Core library
- **[SLP and ALP tokens](https://github.com/Bitcoin-ABC/bitcoin-abc/tree/master/cashtab/src/token-protocols)** - CashTab token protocols
## 📄 License
MIT License - see [LICENSE](./LICENSE) file for details.
## 🤔 Support
- **Issues**: [GitHub Issues](https://github.com/your-repo/minimal-xec-wallet/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.