J-Bitcoin

A comprehensive JavaScript/TypeScript cryptocurrency wallet library supporting both custodial and non-custodial wallets for Bitcoin (BTC), Bitcoin Cash (BCH), and Bitcoin SV (BSV).

🚀 Features

💼 Wallet Types

• Custodial Wallets - Traditional single-key wallets with HD derivation
• Non-Custodial Wallets - Advanced threshold signature schemes (TSS)

🔐 Cryptographic Standards

• BIP32 - Hierarchical Deterministic Wallets
• BIP39 - Mnemonic Seed Phrases (12-word)
• ECDSA - Standard Bitcoin signatures
• Schnorr - Modern signature scheme (BIP340)
• Threshold Signatures - Multi-party signature generation

🏠 Address Formats

• Legacy - P2PKH addresses (1...)
• SegWit - Bech32 addresses (bc1...)
• CashAddr - Bitcoin Cash format

🌐 Network Support

• Bitcoin (BTC) - Mainnet & Testnet
• Bitcoin Cash (BCH) - Mainnet & Testnet
• Bitcoin SV (BSV) - Mainnet & Testnet

📝 Developer Experience

• Full TypeScript Support - Complete type definitions with IntelliSense
• Comprehensive JSDoc - Rich inline documentation
• ES Modules - Modern JavaScript module support
• Tree Shaking - Import only what you need

📚 Documentation

JSDoc for J-Bitcoin

📦 Installation

npm install j-bitcoin

🎯 Quick Start

JavaScript

import { Custodial_Wallet } from 'j-bitcoin';

// Generate new wallet
const [mnemonic, wallet] = Custodial_Wallet.fromRandom('main');
console.log('Mnemonic:', mnemonic);
console.log('Address:', wallet.address);

// Sign a message
const [signature, recoveryId] = wallet.sign("Hello Bitcoin!");
console.log('Signature valid:', wallet.verify(signature, "Hello Bitcoin!"));

TypeScript

import { Custodial_Wallet, ECDSASignatureResult } from 'j-bitcoin';

// Generate new wallet with full type safety
const [mnemonic, wallet]: [string, Custodial_Wallet] = Custodial_Wallet.fromRandom('main');

// TypeScript knows the exact return types
const [signature, recoveryId]: ECDSASignatureResult = wallet.sign("Hello Bitcoin!");
const isValid: boolean = wallet.verify(signature, "Hello Bitcoin!");

Advanced Threshold Signatures

JavaScript:

import { Non_Custodial_Wallet } from 'j-bitcoin';

// Create 2-of-3 threshold wallet
const wallet = Non_Custodial_Wallet.fromRandom("main", 3, 2);

// Get shares for distribution
const shares = wallet._shares;
console.log('Distribute shares to participants:', shares);

// Generate threshold signature
const signature = wallet.sign("Multi-party transaction");
console.log('Threshold signature:', signature.serialized_sig);

TypeScript:

import { Non_Custodial_Wallet, ThresholdSignatureResult } from 'j-bitcoin';

// Create 2-of-3 threshold wallet
const wallet: Non_Custodial_Wallet = Non_Custodial_Wallet.fromRandom("main", 3, 2);

// Get shares for distribution
const shares: string[] = wallet._shares;
console.log('Distribute shares to participants:', shares);

// Generate threshold signature
const signature: ThresholdSignatureResult = wallet.sign("Multi-party transaction");
console.log('Threshold signature:', signature.serialized_sig);

Address Conversion

JavaScript:

import { BECH32, CASH_ADDR } from 'j-bitcoin';

const legacyAddress = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";

// Convert to SegWit
const segwitAddr = BECH32.to_P2WPKH(legacyAddress);
console.log('SegWit:', segwitAddr);
// Output: bc1qhkfq3zahaqkkzx5mjnamwjsfpw3tvke7v6aaph

// Convert to CashAddr
const cashAddr = CASH_ADDR.to_cashAddr(legacyAddress, "p2pkh");
console.log('CashAddr:', cashAddr);
// Output: bitcoincash:qztxx64w20kmy5y9sskjwtgxp3j8dc20ksvef26ssu

TypeScript:

import { BECH32, CASH_ADDR } from 'j-bitcoin';

const legacyAddress: string = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";

// Convert to SegWit
const segwitAddr: string = BECH32.to_P2WPKH(legacyAddress);
console.log('SegWit:', segwitAddr);
// Output: bc1qhkfq3zahaqkkzx5mjnamwjsfpw3tvke7v6aaph

// Convert to CashAddr
const cashAddr: string = CASH_ADDR.to_cashAddr(legacyAddress, "p2pkh");
console.log('CashAddr:', cashAddr);
// Output: bitcoincash:qztxx64w20kmy5y9sskjwtgxp3j8dc20ksvef26ssu

Schnorr Signatures

JavaScript:

import { schnorr_sig } from 'j-bitcoin';

const privateKey = "L1vHfV6GUbMJSvFaqjnButzwq5x4ThdFaotpUgsfScwMNKjdGVuS";
const message = "Hello Schnorr!";

// Sign with Schnorr
const signature = schnorr_sig.sign(privateKey, message);

// Get public key
const publicKey = schnorr_sig.retrieve_public_key(privateKey);

// Verify signature
const isValid = schnorr_sig.verify(signature, message, publicKey);
console.log('Schnorr signature valid:', isValid);

TypeScript:

import { schnorr_sig } from 'j-bitcoin';

const privateKey: string = "L1vHfV6GUbMJSvFaqjnButzwq5x4ThdFaotpUgsfScwMNKjdGVuS";
const message: string = "Hello Schnorr!";

// Sign with Schnorr
const signature: Uint8Array = schnorr_sig.sign(privateKey, message);

// Get public key
const publicKey: Uint8Array = schnorr_sig.retrieve_public_key(privateKey);

// Verify signature
const isValid: boolean = schnorr_sig.verify(signature, message, publicKey);
console.log('Schnorr signature valid:', isValid);

📖 API Documentation

TypeScript Support

J-Bitcoin provides complete TypeScript definitions with:

// Full IntelliSense support
import type { 
  Custodial_Wallet, 
  Non_Custodial_Wallet,
  ECDSASignatureResult,
  ThresholdSignatureResult,
  HDKeys,
  KeyPair,
  NetworkType 
} from 'j-bitcoin';

// Type-safe network specification
const network: NetworkType = 'main'; // 'main' | 'test'

// Strongly typed wallet creation
const wallet: Custodial_Wallet = Custodial_Wallet.fromRandom(network);

// Comprehensive interface definitions
interface ThresholdSignatureResult {
  sig: { r: bigint; s: bigint; };
  serialized_sig: string;
  msgHash: Buffer;
  recovery_id: number;
}

Custodial_Wallet

Method	Description
fromRandom(net, passphrase?)	Generate new random wallet
fromMnemonic(net, mnemonic, passphrase?)	Import from mnemonic
fromSeed(net, seed)	Create from hex seed
derive(path, keyType)	Derive child keys
sign(message)	Sign with ECDSA
verify(sig, message)	Verify signature

Non_Custodial_Wallet

Method	Description
fromRandom(net, groupSize, threshold)	Create threshold wallet
fromShares(net, shares, threshold)	Reconstruct from shares
sign(message)	Generate threshold signature
verify(sig, msgHash)	Verify threshold signature
_shares	Get secret shares
_privateKey	Get reconstructed private key

Address Utilities

Function	Description
BECH32.to_P2WPKH(address)	Convert to SegWit
BECH32.data_to_bech32(prefix, data, encoding)	Custom Bech32 encoding
CASH_ADDR.to_cashAddr(address, type?)	Convert to CashAddr

🔗 BIP32 Key Derivation

JavaScript:

// Standard BIP44 paths
wallet.derive("m/44'/0'/0'/0/0");    // Bitcoin account 0, address 0
wallet.derive("m/44'/145'/0'/0/0");  // Bitcoin Cash account 0
wallet.derive("m/44'/236'/0'/0/0");  // Bitcoin SV account 0

// Custom derivation
wallet.derive("m/0'/1'/2");          // Hardened path
wallet.derive("m/0/1/2");            // Non-hardened path

TypeScript:

import { Custodial_Wallet, KeyType } from 'j-bitcoin';

// Standard BIP44 paths with type safety
wallet.derive("m/44'/0'/0'/0/0", 'pri' as KeyType);    // Bitcoin account 0, address 0
wallet.derive("m/44'/145'/0'/0/0", 'pri' as KeyType);  // Bitcoin Cash account 0
wallet.derive("m/44'/236'/0'/0/0", 'pri' as KeyType);  // Bitcoin SV account 0

// Custom derivation with type checking
wallet.derive("m/0'/1'/2", 'pri' as KeyType);          // Hardened path
wallet.derive("m/0/1/2", 'pub' as KeyType);            // Non-hardened path (public key derivation)

🛡️ Security Features

• Secure Random Generation - Uses Node.js crypto.randomBytes()
• Mnemonic Validation - BIP39 checksum verification
• Threshold Security - Distributed key management
• Multiple Signature Schemes - ECDSA, Schnorr, TSS
• Address Validation - Built-in format checking

🎛️ Advanced Examples

TypeScript Multi-Signature Escrow

JavaScript:

import { Non_Custodial_Wallet } from 'j-bitcoin';

// 2-of-3 escrow: buyer, seller, arbiter
const escrow = Non_Custodial_Wallet.fromRandom("main", 3, 2);
const [buyerShare, sellerShare, arbiterShare] = escrow._shares;

// Buyer + Seller can release funds
const release = Non_Custodial_Wallet.fromShares("main", 
  [buyerShare, sellerShare], 2);

// Disputes require arbiter
const dispute = Non_Custodial_Wallet.fromShares("main",
  [buyerShare, arbiterShare], 2);

TypeScript:

import { Non_Custodial_Wallet } from 'j-bitcoin';

// 2-of-3 escrow: buyer, seller, arbiter
const escrow: Non_Custodial_Wallet = Non_Custodial_Wallet.fromRandom("main", 3, 2);
const [buyerShare, sellerShare, arbiterShare]: string[] = escrow._shares;

// Buyer + Seller can release funds
const release: Non_Custodial_Wallet = Non_Custodial_Wallet.fromShares("main", 
  [buyerShare, sellerShare], 2);

// Disputes require arbiter
const dispute: Non_Custodial_Wallet = Non_Custodial_Wallet.fromShares("main",
  [buyerShare, arbiterShare], 2);

Corporate Treasury

JavaScript:

import { Non_Custodial_Wallet } from 'j-bitcoin';

// 3-of-5 corporate signature
const treasury = Non_Custodial_Wallet.fromRandom("main", 5, 3);
const executiveShares = treasury._shares;

// Any 3 executives can authorize
const authorization = Non_Custodial_Wallet.fromShares("main",
  [executiveShares[0], executiveShares[2], executiveShares[4]], 3);

// Generate authorization signature
const authSignature = authorization.sign("Transfer $1M to operations");

TypeScript:

import { Non_Custodial_Wallet, ThresholdSignatureResult } from 'j-bitcoin';

// 3-of-5 corporate signature
const treasury: Non_Custodial_Wallet = Non_Custodial_Wallet.fromRandom("main", 5, 3);
const executiveShares: string[] = treasury._shares;

// Any 3 executives can authorize
const authorization: Non_Custodial_Wallet = Non_Custodial_Wallet.fromShares("main",
  [executiveShares[0], executiveShares[2], executiveShares[4]], 3);

// Type-safe signature generation
const authSignature: ThresholdSignatureResult = authorization.sign("Transfer $1M to operations");

Cross-Platform Wallet

JavaScript:

import { Custodial_Wallet } from 'j-bitcoin';

// Generate with passphrase
const [mnemonic, wallet] = Custodial_Wallet.fromRandom('main', 'secure-pass');

// Reconstruct anywhere
const restored = Custodial_Wallet.fromMnemonic('main', mnemonic, 'secure-pass');

// Derive for different coins
restored.derive("m/44'/0'/0'/0/0");   // Bitcoin
restored.derive("m/44'/145'/0'/0/0"); // Bitcoin Cash
restored.derive("m/44'/236'/0'/0/0"); // Bitcoin SV

TypeScript:

import { Custodial_Wallet, NetworkType } from 'j-bitcoin';

// Type-safe network specification
const network: NetworkType = 'main';

// Generate with passphrase
const [mnemonic, wallet]: [string, Custodial_Wallet] = 
  Custodial_Wallet.fromRandom(network, 'secure-pass');

// Reconstruct anywhere with type safety
const restored: Custodial_Wallet = 
  Custodial_Wallet.fromMnemonic(network, mnemonic, 'secure-pass');

// Derive for different coins
restored.derive("m/44'/0'/0'/0/0");   // Bitcoin
restored.derive("m/44'/145'/0'/0/0"); // Bitcoin Cash
restored.derive("m/44'/236'/0'/0/0"); // Bitcoin SV

📊 Feature Matrix

Feature	Support	TypeScript
Hierarchical Deterministic	✅	✅ Full types
Threshold Signatures	✅	✅ Complete interfaces
ECDSA Signatures	✅	✅ Type-safe returns
Schnorr Signatures	✅	✅ BIP340 types
P2PKH Addresses	✅	✅ Network types
P2WPKH (SegWit)	✅	✅ Bech32 types
CashAddr Format	✅	✅ Format types
P2SH Addresses	❌	🔄 Planned
P2WSH (SegWit v1)	❌	🔄 Planned
Transaction Building	❌	🔄 Planned
SPV Validation	❌	🔄 Planned

🔧 Dependencies

{
  "@noble/curves": "^1.9.1",
  "base58-js": "^1.0.4", 
  "bigint-conversion": "^2.4.0",
  "bn.js": "^5.2.1"
}

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

📝 Documentation

TypeScript IntelliSense

Experience world-class developer productivity:

// VS Code, WebStorm, and other IDEs provide:
// ✅ Complete autocomplete for all methods
// ✅ Inline parameter documentation
// ✅ Return type information
// ✅ Error detection at compile time

const wallet = Custodial_Wallet.fromRandom('main');
//    ^-- IDE shows: [string, Custodial_Wallet]

wallet.derive("m/44'/0'/0'/0/0", 'pri');
//     ^-- IDE shows available parameters and types

Generate API Documentation

npm install -g jsdoc
npm run docs

View comprehensive documentation in docs/index.html with:

• Complete API reference with examples
• TypeScript integration guide
• Security best practices
• Advanced usage patterns

🔒 Security Best Practices

Key Management

• Secure Backup: Store mnemonic phrases in secure, offline locations
• Share Distribution: Use encrypted channels for threshold share distribution
• Access Control: Implement proper authentication for wallet operations
• Regular Rotation: Consider periodic key rotation for long-term security

Development

• Input Validation: Always validate addresses and amounts before operations
• Error Handling: Implement comprehensive error handling for all operations
• Testing: Test thoroughly on testnet before mainnet deployment
• Auditing: Maintain audit trails for all cryptographic operations

Production Deployment

• Environment Separation: Keep development and production environments isolated
• Monitoring: Implement monitoring for wallet operations and security events
• Backup Procedures: Establish reliable backup and recovery procedures
• Incident Response: Have plans for handling security incidents

🤝 Contributing

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

Development Setup

# Clone and install dependencies
git clone https://github.com/yfbsei/J-Bitcoin.git
cd J-Bitcoin
npm install

# Run development commands
npm run lint          # Check code style
npm run format        # Format code
npm run test          # Run tests
npm run docs          # Generate documentation

📜 License

ISC License - see LICENSE file for details.

🙏 Acknowledgments

• BIP Authors - For Bitcoin Improvement Proposals
• Bitcoin Core - Reference implementation
• Noble Crypto - Excellent secp256k1 library
• Bitcoin Community - Continuous innovation

📞 Support

• Issues: GitHub Issues
• Documentation: API Docs
• Examples: Examples Directory

🔮 Roadmap

Short Term (Q2 2025)

• [ ] P2SH and P2WSH address support with TypeScript definitions
• [ ] Enhanced error handling and validation
• [ ] Performance optimizations for threshold operations
• [ ] Additional test coverage for edge cases

Medium Term (Q3-Q4 2025)

• [ ] Transaction building and broadcasting with type-safe interfaces
• [ ] SPV wallet implementation with comprehensive types
• [ ] Hardware wallet integration with device-specific types
• [ ] Advanced script templates with template types

Long Term (2026+)

• [ ] Lightning Network support with protocol types
• [ ] React/Vue component library with prop types
• [ ] WebAssembly optimization with typed bindings
• [ ] Cross-chain interoperability features

🏆 Why Choose J-Bitcoin?

For Developers

• TypeScript First: Built with TypeScript developers in mind
• Modern Architecture: ES modules, tree shaking, and modern JavaScript
• Comprehensive Documentation: Every function documented with examples
• Developer Experience: IntelliSense, autocomplete, and type safety

For Enterprises

• Threshold Security: Advanced multi-party control for corporate treasuries
• Compliance Ready: Audit trails and multi-signature requirements
• Battle Tested: Based on proven cryptographic standards
• Professional Support: Enterprise-grade reliability and support

For Researchers

• Academic Standards: Implements latest cryptographic research
• Extensible Design: Easy to extend with new algorithms
• Reference Implementation: Well-documented algorithms for study
• Open Source: Transparent implementation for peer review

---

⚠️ Security Notice: This library handles private keys and should be used with appropriate security measures. Always verify implementations in test environments before production use.

Built with ❤️ for the Bitcoin ecosystem and TypeScript developers