JSPM

charms-wallet-js

1.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • 0
  • Score
    100M100P100Q26983F
  • License MIT

Professional Bitcoin wallet library for Charms ecosystem using @scure stack

Package Exports

  • charms-wallet-js
  • charms-wallet-js/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (charms-wallet-js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Charms Wallet JS

Professional Bitcoin wallet library built on the modern @scure cryptographic stack. Extracted from the Charms ecosystem to provide secure, modular wallet functionality for Bitcoin applications.

๐Ÿ”ฎ Features

  • Secure HD Wallet: BIP32/BIP39/BIP86 compliant hierarchical deterministic wallets
  • Taproot Support: Native P2TR (Pay-to-Taproot) address generation and validation
  • Modern Cryptography: Built on @scure stack for maximum security and performance
  • Transaction Building: Professional transaction construction with mining support
  • Multi-Network: Support for mainnet, testnet, and testnet4
  • TypeScript: Full type safety with comprehensive TypeScript definitions
  • Zero Dependencies: Minimal, secure dependencies focused on cryptography

๐Ÿ“ฆ Installation

npm install charms-wallet-js

๐Ÿš€ Quick Start

import { CharmsWallet } from 'charms-wallet-js';

// Create wallet instance
const wallet = new CharmsWallet({ network: 'testnet' });

// Generate mnemonic
const mnemonic = wallet.generateMnemonic();
console.log('Mnemonic:', mnemonic);

// Generate Taproot address
const address = await wallet.generateAddress(mnemonic);
console.log('Address:', address);

// Validate address
const validation = wallet.validateAddress(address);
console.log('Valid:', validation.valid);

๐Ÿ”ง Core Functionality

Wallet Creation and Management

import { CharmsWallet } from 'charms-wallet-js';

// Create wallet with custom configuration
const wallet = new CharmsWallet({
    network: 'mainnet',
    derivationPath: "m/86'/0'/0'", // BIP86 Taproot
    addressType: 'taproot'
});

// Generate secure mnemonic (12 or 24 words)
const mnemonic12 = wallet.generateMnemonic(12);
const mnemonic24 = wallet.generateMnemonic(24);

// Validate mnemonic
const validation = wallet.validateMnemonic(mnemonic12);
if (validation.valid) {
    console.log('Mnemonic is valid');
} else {
    console.error('Invalid mnemonic:', validation.error);
}

Address Generation

// Generate address for specific network and index (static method)
const address = await CharmsWallet.generateAddress(mnemonic, 'testnet', 0);

// Get private key for specific address index
const privateKey = await CharmsWallet.getPrivateKey(mnemonic, 'testnet', 0);

// Get complete address data (address + keys)
const addressData = await CharmsWallet.getAddressData(mnemonic, 'testnet', 0);
console.log('Address:', addressData.address);
console.log('Private Key:', addressData.privateKey);
console.log('Public Key:', addressData.publicKey);

// Create AddressWallet from private key (no mnemonic needed)
const addressWallet = CharmsWallet.fromPrivateKey(privateKey, 'testnet');
console.log('Address from private key:', addressWallet.getAddress());

Working with Individual Addresses

import { AddressWallet } from 'charms-wallet-js';

// Create AddressWallet from private key
const privateKey = await CharmsWallet.getPrivateKey(mnemonic, 'testnet', 0);
const addressWallet = new AddressWallet(privateKey, 'testnet');

// Get address information
console.log('Address:', addressWallet.getAddress());
console.log('Public Key:', addressWallet.getPublicKey());

// Sign transaction without exposing mnemonic
const signedTx = await addressWallet.signTransaction(psbtHex, utxo);
console.log('Signed TX:', signedTx.hex);

Address Validation

// Validate any Bitcoin address
const validation = wallet.validateAddress('tb1pe7gfqvmdj7xjhu3awnwt9q3edgyf24dhejx34sc8p7z7gpwv80tqslxpr6');

if (validation.valid) {
    console.log('Network:', validation.network); // 'testnet'
    console.log('Type:', validation.type);       // 'p2tr'
} else {
    console.error('Invalid address:', validation.error);
}

Transaction Building

import { TransactionBuilder } from 'charms-wallet-js';

const txBuilder = new TransactionBuilder('testnet');

// Create mining transaction with OP_RETURN data
const miningTx = await txBuilder.createMiningTransaction({
    utxo: {
        txid: 'abc123...',
        vout: 0,
        amount: 100000,
        address: 'tb1p...'
    },
    miningData: {
        hash: 'deadbeef...',
        nonce: 12345
    },
    changeAddress: 'tb1p...',
    feeRate: 10
});

// Create simple transaction
const simpleTx = await txBuilder.createSimpleTransaction({
    utxos: [{
        txid: 'abc123...',
        vout: 0,
        amount: 100000,
        address: 'tb1p...'
    }],
    outputs: [{
        address: 'tb1p...',
        amount: 50000
    }],
    changeAddress: 'tb1p...',
    feeRate: 10
});

Transaction Signing

import { TransactionSigner } from 'charms-wallet-js';

const signer = new TransactionSigner('testnet');

// Sign transaction with mnemonic
const signedTx = await signer.signTransaction(psbtHex, mnemonic);

console.log('Signed transaction:', signedTx.hex);
console.log('Transaction ID:', signedTx.txid);

๐ŸŒ Network Support

// Mainnet
const mainnetWallet = new CharmsWallet({ network: 'mainnet' });

// Testnet
const testnetWallet = new CharmsWallet({ network: 'testnet' });

// Testnet4
const testnet4Wallet = new CharmsWallet({ network: 'testnet4' });

๐Ÿ” Security Features

  • BIP39: Secure mnemonic generation and validation
  • BIP32: Hierarchical deterministic key derivation
  • BIP86: Taproot key derivation paths
  • @scure Stack: Modern, audited cryptographic primitives
  • No Key Storage: Library never stores private keys
  • Secure Random: Cryptographically secure random number generation

๐Ÿ”ง Advanced Usage

Note: For advanced transaction building, fee estimation, complex PSBT operations, or low-level cryptographic operations, use the @scure/btc-signer library directly. This wallet library provides high-level convenience functions, while @scure offers complete control over Bitcoin transaction construction and signing.

// For advanced operations, use @scure directly:
import * as btc from '@scure/btc-signer';

// Advanced transaction building
const tx = new btc.Transaction();
// ... complex transaction logic

// Advanced fee estimation
const feeRate = btc.estimateFee(/* parameters */);

// Complex PSBT operations
const psbt = btc.Transaction.fromPSBT(psbtBytes);
// ... advanced PSBT manipulation

๐Ÿ“‹ API Reference

CharmsWallet

Constructor

new CharmsWallet(config?: Partial<WalletConfig>)

Static Methods

  • generateAddress(mnemonic: string, network: Network, index?: number): Promise<string>
  • getPrivateKey(mnemonic: string, network: Network, index?: number): Promise<Uint8Array>
  • getAddressData(mnemonic: string, network: Network, index?: number): Promise<TaprootKeys>
  • fromPrivateKey(privateKey: Uint8Array, network: Network): AddressWallet

Instance Methods

  • generateMnemonic(wordCount?: number): string
  • validateMnemonic(mnemonic: string): ValidationResult
  • validateAddress(address: string): AddressValidation
  • deriveTaprootKeys(mnemonic: string, index?: number): Promise<TaprootKeys>

AddressWallet

Constructor

new AddressWallet(privateKey: Uint8Array, network: Network)

Methods

  • getAddress(): string
  • getPublicKey(): Uint8Array
  • getXOnlyPublicKey(): Uint8Array
  • signPSBT(psbtHex: string, utxo: UTXO): Promise<TransactionResult>
  • signTransaction(psbtHex: string, utxo: UTXO): Promise<SignedTransaction>

TransactionBuilder

Constructor

new TransactionBuilder(network?: Network)

Methods

  • createMiningTransaction(params: MiningTxParams): Promise<string>
  • createSimpleTransaction(params: SimpleTxParams): Promise<string>

TransactionSigner

Constructor

new TransactionSigner(network?: Network)

Methods

  • signTransaction(psbtHex: string, mnemonic: string): Promise<SignedTransaction>
  • signMiningTransaction(psbtHex: string, mnemonic: string): Promise<SignedTransaction>

๐Ÿ”ง Configuration

interface WalletConfig {
    network: 'mainnet' | 'testnet' | 'testnet4';
    derivationPath: string;
    addressType: 'taproot' | 'segwit' | 'legacy';
    storage: StorageOptions;
}

๐Ÿงช Testing

# Run all tests
npm test

# Run specific test suites
npm run test:basic
npm run test:wallet

# Build library
npm run build

# Development mode (watch)
npm run dev

Test Structure

The library includes comprehensive tests in the tests/ directory:

  • tests/basic.test.js - Basic wallet functionality tests
  • tests/wallet.test.js - Comprehensive wallet feature tests
  • tests/run-all.js - Test runner for all test suites

All tests are included in the NPM package and can be run by consumers to verify functionality.

๐Ÿ“„ License

MIT License - see LICENSE file for details.

๐Ÿค Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

โš ๏ธ Security Notice

This library handles sensitive cryptographic material. Always:

  • Use in secure environments
  • Never log or store private keys
  • Validate all inputs
  • Keep dependencies updated
  • Review code before production use

๐Ÿ“ž Support

For questions and support: