@bsv/sdk 1.6.12 → 1.6.14

package/docs/guides/security-best-practices.md

@@ -0,0 +1,494 @@
+# Security Best Practices
+
+This comprehensive guide covers essential security practices when developing Bitcoin applications with the BSV TypeScript SDK. Following these guidelines will help you build secure, production-ready applications that protect user funds and data.
+
+## Prerequisites
+
+- Understanding of Bitcoin cryptography fundamentals
+- Familiarity with the BSV TypeScript SDK
+- Basic knowledge of secure coding practices
+- Understanding of common attack vectors in cryptocurrency applications
+
+> **📚 Related Concepts**: This guide builds on [Key Management](../concepts/key-management.md), [Trust Model](../concepts/trust-model.md), [Digital Signatures](../concepts/signatures.md), and [Transaction Verification](../concepts/verification.md) concepts.
+
+## Key Security Principles
+
+### 1. Private Key Management
+
+#### Never Expose Private Keys
+
+```typescript
+// ❌ NEVER do this - exposing private key in logs or UI
+console.log('Private key:', privateKey.toWif())
+alert(`Your key: ${privateKey.toWif()}`)
+
+// ✅ Proper handling - keep private keys secure
+const privateKey = PrivateKey.fromRandom()
+// Use the key for operations without exposing it
+const publicKey = privateKey.toPublicKey()
+```
+
+#### Secure Key Generation
+
+```typescript
+import { PrivateKey } from '@bsv/sdk'
+
+// ✅ Use cryptographically secure random generation
+const secureKey = PrivateKey.fromRandom()
+
+// ❌ Never use predictable sources
+// const weakKey = PrivateKey.fromString('1') // Predictable
+// const timeKey = PrivateKey.fromString(Date.now().toString()) // Predictable
+```
+
+#### Key Storage Best Practices
+
+```typescript
+// ✅ For production applications, use secure storage
+class SecureKeyManager {
+  private encryptionKey: SymmetricKey
+  
+  constructor() {
+    // Derive encryption key from user password or hardware security module
+    this.encryptionKey = SymmetricKey.fromRandom()
+  }
+  
+  async storePrivateKey(privateKey: PrivateKey, identifier: string): Promise<void> {
+    const keyData = privateKey.toWif()
+    const encrypted = this.encryptionKey.encrypt(keyData)
+    
+    // Store encrypted key in secure storage (not localStorage for production)
+    await this.secureStorage.set(identifier, Buffer.from(encrypted).toString('base64'))
+  }
+  
+  async retrievePrivateKey(identifier: string): Promise<PrivateKey> {
+    const encryptedData = await this.secureStorage.get(identifier)
+    const encryptedBuffer = Buffer.from(encryptedData, 'base64')
+    const decrypted = this.encryptionKey.decrypt(Array.from(encryptedBuffer), 'utf8')
+    return PrivateKey.fromWif(decrypted as string)
+  }
+}
+```
+
+### 2. Transaction Security
+
+#### Input Validation and Sanitization
+
+```typescript
+import { Transaction, PrivateKey, P2PKH } from '@bsv/sdk'
+
+class SecureTransactionBuilder {
+  static validateAmount(satoshis: number): void {
+    if (!Number.isInteger(satoshis)) {
+      throw new Error('Amount must be an integer')
+    }
+    if (satoshis <= 0) {
+      throw new Error('Amount must be positive')
+    }
+    if (satoshis > 21000000 * 100000000) {
+      throw new Error('Amount exceeds maximum possible Bitcoin supply')
+    }
+  }
+  
+  static validateAddress(address: string): void {
+    try {
+      // Validate address format
+      P2PKH.unlock('', 'all', {
+        publicKey: address, // This will throw if invalid
+        signature: { inputIndex: 0, outputs: [], inputScript: '' }
+      })
+    } catch (error) {
+      throw new Error('Invalid Bitcoin address format')
+    }
+  }
+  
+  static async createSecureTransaction(
+    privateKey: PrivateKey,
+    recipientAddress: string,
+    amount: number
+  ): Promise<Transaction> {
+    // Validate all inputs
+    this.validateAmount(amount)
+    this.validateAddress(recipientAddress)
+    
+    // Create transaction with validated inputs
+    const tx = new Transaction()
+    // ... transaction construction logic
+    
+    return tx
+  }
+}
+```
+
+#### Fee Calculation Security
+
+```typescript
+// ✅ Always validate fee calculations to prevent fee attacks
+class SecureFeeCalculator {
+  private static readonly MIN_FEE_RATE = 0.5 // satoshis per byte
+  private static readonly MAX_FEE_RATE = 1000 // satoshis per byte
+  
+  static calculateFee(transactionSize: number, feeRate: number): number {
+    // Validate fee rate is within reasonable bounds
+    if (feeRate < this.MIN_FEE_RATE || feeRate > this.MAX_FEE_RATE) {
+      throw new Error(`Fee rate must be between ${this.MIN_FEE_RATE} and ${this.MAX_FEE_RATE} sat/byte`)
+    }
+    
+    const fee = Math.ceil(transactionSize * feeRate)
+    
+    // Additional validation to prevent excessive fees
+    if (fee > 100000) { // 0.001 BSV maximum fee
+      throw new Error('Calculated fee is unreasonably high')
+    }
+    
+    return fee
+  }
+}
+```
+
+### 3. Cryptographic Operations Security
+
+#### Secure Random Number Generation
+
+```typescript
+import { PrivateKey, SymmetricKey } from '@bsv/sdk'
+
+// ✅ Always use the SDK's secure random generation
+const securePrivateKey = PrivateKey.fromRandom()
+const secureSymmetricKey = SymmetricKey.fromRandom()
+
+// ❌ Never use Math.random() for cryptographic purposes
+// const insecureKey = PrivateKey.fromString(Math.random().toString())
+```
+
+#### ECDH Key Exchange Security
+
+```typescript
+import { PrivateKey, PublicKey } from '@bsv/sdk'
+
+class SecureECDH {
+  static performKeyExchange(
+    myPrivateKey: PrivateKey,
+    theirPublicKey: PublicKey
+  ): Buffer {
+    try {
+      // The SDK automatically validates the public key and prevents twist attacks
+      const sharedSecret = myPrivateKey.deriveSharedSecret(theirPublicKey)
+      
+      // ✅ Always derive keys from the shared secret, never use it directly
+      if (!sharedSecret.x) {
+        throw new Error('Invalid shared secret')
+      }
+      const sharedSecretBuffer = Buffer.from(sharedSecret.x.toArray())
+      const contextBuffer = Buffer.from('application-specific-context', 'utf8')
+      const combinedBuffer = Buffer.concat([sharedSecretBuffer, contextBuffer])
+      const derivedKey = Hash.sha256(Array.from(combinedBuffer))
+      
+      return Buffer.from(derivedKey)
+    } catch (error) {
+      throw new Error('Key exchange failed: Invalid public key')
+    }
+  }
+}
+```
+
+#### AES Encryption Security
+
+```typescript
+import { SymmetricKey, Hash } from '@bsv/sdk'
+
+class SecureEncryption {
+  // ✅ Proper key derivation from passwords
+  static deriveKeyFromPassword(password: string, salt: Buffer): SymmetricKey {
+    if (password.length < 12) {
+      throw new Error('Password must be at least 12 characters')
+    }
+    
+    // Use multiple rounds of hashing for key derivation
+    let derived = Array.from(Buffer.concat([Buffer.from(password, 'utf8'), salt]))
+    for (let i = 0; i < 10000; i++) {
+      derived = Hash.sha256(derived)
+    }
+    
+    return new SymmetricKey(derived)
+  }
+  
+  // ✅ Secure encryption with proper error handling
+  static encryptData(data: string, key: SymmetricKey): string {
+    try {
+      const encrypted = key.encrypt(data)
+      return Buffer.from(encrypted).toString('base64')
+    } catch (error) {
+      // Don't expose internal error details
+      throw new Error('Encryption failed')
+    }
+  }
+  
+  // ✅ Secure decryption with validation
+  static decryptData(encryptedData: string, key: SymmetricKey): string {
+    try {
+      const encrypted = Buffer.from(encryptedData, 'base64')
+      const decrypted = key.decrypt(Array.from(encrypted), 'utf8')
+      return decrypted as string
+    } catch (error) {
+      throw new Error('Decryption failed: Invalid data or key')
+    }
+  }
+}
+```
+
+### 4. Wallet Integration Security
+
+#### Secure WalletClient Usage
+
+```typescript
+import { WalletClient } from '@bsv/sdk'
+
+class SecureWalletManager {
+  private wallet: WalletClient | null = null
+  private connectionAttempts = 0
+  private readonly MAX_CONNECTION_ATTEMPTS = 3
+  
+  async connectWallet(): Promise<void> {
+    if (this.connectionAttempts >= this.MAX_CONNECTION_ATTEMPTS) {
+      throw new Error('Maximum connection attempts exceeded')
+    }
+    
+    try {
+      this.wallet = new WalletClient('auto', 'localhost')
+      // Connection is established during construction
+      this.connectionAttempts = 0 // Reset on successful connection
+    } catch (error) {
+      this.connectionAttempts++
+      throw new Error('Wallet connection failed')
+    }
+  }
+  
+  async createSecureTransaction(outputs: any[]): Promise<any> {
+    if (!this.wallet) {
+      throw new Error('Wallet not connected')
+    }
+    
+    // Validate all outputs before creating transaction
+    for (const output of outputs) {
+      if (!output.satoshis || output.satoshis <= 0) {
+        throw new Error('Invalid output amount')
+      }
+      if (!output.lockingScript) {
+        throw new Error('Missing locking script')
+      }
+    }
+    
+    try {
+      return await this.wallet.createAction({
+        description: 'Secure transaction',
+        outputs,
+        // ✅ Always include proper error handling options
+        options: {
+          acceptDelayedBroadcast: false, // Ensure immediate feedback
+          randomizeOutputs: true // Enhance privacy
+        }
+      })
+    } catch (error) {
+      // Log error securely without exposing sensitive data
+      console.error('Transaction creation failed:', error.message)
+      throw new Error('Transaction creation failed')
+    }
+  }
+}
+```
+
+When using the `WalletClient` interface, follow these security practices:
+
+### Secure `WalletClient` Usage
+
+The `WalletClient` provides built-in security features, but proper usage is essential:
+
+### `WalletClient` Connection Management
+
+When working with `WalletClient` connections:
+
+### 5. Network Security
+
+#### Secure Chain Tracker Usage
+
+```typescript
+import { ChainTracker, WhatsOnChain } from '@bsv/sdk'
+
+class SecureChainTracker {
+  private trackers: ChainTracker[]
+  private currentTrackerIndex = 0
+  
+  constructor() {
+    // ✅ Use multiple chain trackers for redundancy
+    this.trackers = [
+      new WhatsOnChain('main'),
+      // Add additional trackers for failover
+    ]
+  }
+  
+  async getTransactionWithRetry(txid: string): Promise<any> {
+    let lastError: Error | null = null
+    
+    // Try each tracker
+    for (let i = 0; i < this.trackers.length; i++) {
+      try {
+        const tracker = this.trackers[this.currentTrackerIndex]
+        const result = await tracker.getTransaction(txid)
+        
+        // Validate the response
+        if (!result || !result.id) {
+          throw new Error('Invalid transaction response')
+        }
+        
+        return result
+      } catch (error) {
+        lastError = error as Error
+        this.currentTrackerIndex = (this.currentTrackerIndex + 1) % this.trackers.length
+      }
+    }
+    
+    throw new Error(`All chain trackers failed: ${lastError?.message}`)
+  }
+}
+```
+
+### 6. SPV Verification Security
+
+#### Secure Merkle Proof Verification
+
+```typescript
+import { Transaction, MerklePath } from '@bsv/sdk'
+
+class SecureSPVVerifier {
+  static async verifyTransaction(
+    transaction: Transaction,
+    merklePath: MerklePath,
+    blockHeader: any
+  ): Promise<boolean> {
+    try {
+      // ✅ Always verify the merkle proof
+      const txid = Buffer.from(transaction.id()).toString('hex')
+      const computedRoot = merklePath.computeRoot(txid)
+      
+      if (computedRoot !== blockHeader.merkleRoot) {
+        throw new Error('Merkle proof verification failed')
+      }
+      
+      // ✅ Verify the transaction itself
+      const isValid = await transaction.verify()
+      if (!isValid) {
+        throw new Error('Transaction verification failed')
+      }
+      
+      return true
+    } catch (error) {
+      console.error('SPV verification failed:', error.message)
+      return false
+    }
+  }
+}
+```
+
+### 7. Error Handling Security
+
+#### Secure Error Reporting
+
+```typescript
+class SecureErrorHandler {
+  // ✅ Sanitize error messages to prevent information leakage
+  static sanitizeError(error: Error): string {
+    const sensitivePatterns = [
+      /private.*key/i,
+      /seed/i,
+      /mnemonic/i,
+      /password/i,
+      /secret/i
+    ]
+    
+    let message = error.message
+    
+    for (const pattern of sensitivePatterns) {
+      message = message.replace(pattern, '[REDACTED]')
+    }
+    
+    return message
+  }
+  
+  // ✅ Secure error logging
+  static logError(error: Error, context: string): void {
+    const sanitizedMessage = this.sanitizeError(error)
+    console.error(`[${context}] ${sanitizedMessage}`)
+    
+    // In production, send to secure logging service
+    // Never log sensitive information
+  }
+}
+```
+
+## Common Security Vulnerabilities
+
+### 1. Private Key Exposure
+
+```typescript
+// ❌ Common mistakes that expose private keys
+class InsecureExamples {
+  // Never store keys in plain text
+  private userKey = 'L1234567890abcdef...' // Exposed in source code
+  
+  // Never log private keys
+  debugTransaction(privateKey: PrivateKey) {
+    console.log('Signing with key:', privateKey.toWif()) // Logged
+  }
+  
+  // Never send keys over insecure channels
+  async sendKeyToServer(key: PrivateKey) {
+    await fetch('http://api.example.com/keys', { // HTTP not HTTPS
+      method: 'POST',
+      body: JSON.stringify({ key: key.toWif() })
+    })
+  }
+}
+```
+
+### 2. Insufficient Input Validation
+
+```typescript
+// ❌ Vulnerable to various attacks
+class VulnerableTransaction {
+  async createTransaction(amount: string, address: string) {
+    // No validation - vulnerable to injection and overflow
+    const tx = new Transaction()
+    tx.addOutput({
+      satoshis: parseInt(amount), // No validation
+      lockingScript: address // No validation
+    })
+    return tx
+  }
+}
+```
+
+### 3. Weak Random Number Generation
+
+```typescript
+// ❌ Predictable and insecure
+class WeakRandomness {
+  generatePrivateKey(): PrivateKey {
+    // Predictable seed
+    const seed = Date.now().toString() + Math.random().toString()
+    return PrivateKey.fromString(seed)
+  }
+}
+```
+
+## Security Resources
+
+### Additional Reading
+
+- [Bitcoin Security Best Practices](https://en.bitcoin.it/wiki/Securing_your_wallet)
+- [Cryptographic Best Practices](https://cryptography.io/en/latest/faq/)
+- [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html)
+
+## Conclusion
+
+Security in Bitcoin applications requires constant vigilance and adherence to best practices. The BSV TypeScript SDK provides many security features out of the box, but proper implementation and configuration are crucial for maintaining security.

package/docs/guides/transaction-batching.md

@@ -0,0 +1,132 @@
+# Implementing Transaction Batching
+
+This guide demonstrates how to efficiently batch multiple payments into single transactions using the BSV TypeScript SDK, optimizing for fees, network efficiency, and throughput.
+
+## Overview
+
+Transaction batching combines multiple payments into a single transaction, reducing fees and network load. This guide covers various batching strategies from simple multi-output transactions to advanced batch processing systems.
+
+## Basic Multi-Output Batching
+
+### Simple Batch Payment
+
+The most straightforward batching approach combines multiple payments into one transaction:
+
+```typescript
+import { WalletClient } from '@bsv/sdk'
+
+async function createBatchPayment() {
+  const wallet = new WalletClient('auto', 'localhost')
+
+  // Define multiple recipients with proper P2PKH locking scripts
+  const recipients = [
+    { lockingScript: '76a914389ffce9cd9ae88dcc0631e88a821ffdbe9bfe2688ac', amount: 100, description: 'Payment 1' },
+    { lockingScript: '76a91477bde5cfd66c6d1c83b0008b8a6e3579a6e5c6b988ac', amount: 150, description: 'Payment 2' },
+    { lockingScript: '76a914c42e7ef92fdb603af844d064faad95db9f7f1e9588ac', amount: 200, description: 'Payment 3' }
+  ]
+
+  // Create batch transaction
+  const actionResult = await wallet.createAction({
+    description: 'Batch payment to multiple recipients',
+    outputs: recipients.map(recipient => ({
+      satoshis: recipient.amount,
+      lockingScript: recipient.lockingScript,
+      outputDescription: recipient.description
+    })),
+  })
+
+  console.log('Batch transaction created:', actionResult.txid)
+  return actionResult
+}
+```
+
+### Batch with Data Outputs
+
+Combine payments with data storage in a single transaction:
+
+```typescript
+async function createBatchWithData() {
+  const wallet = new WalletClient('auto', 'localhost')
+
+  const outputs = [
+    // Payment outputs
+    {
+      satoshis: 100,
+      lockingScript: '76a914389ffce9cd9ae88dcc0631e88a821ffdbe9bfe2688ac',
+      outputDescription: 'Payment 1'
+    },
+    {
+      satoshis: 150,
+      lockingScript: '76a91477bde5cfd66c6d1c83b0008b8a6e3579a6e5c6b988ac',
+      outputDescription: 'Payment 2'
+    },
+    // Data outputs (OP_RETURN outputs use 1 satoshi)
+    {
+      satoshis: 1,
+      lockingScript: '006a0c48656c6c6f20576f726c64', // OP_RETURN "Hello World"
+      outputDescription: 'Batch metadata'
+    },
+    {
+      satoshis: 1,
+      lockingScript: '006a0a42617463682044617461', // OP_RETURN "Batch Data"
+      outputDescription: 'Batch identifier'
+    }
+  ]
+
+  const actionResult = await wallet.createAction({
+    description: 'Batch payment with metadata',
+    outputs,
+  })
+
+  return actionResult
+}
+```
+
+### UTXO Consolidation Batching
+
+Combine payments with UTXO consolidation for better wallet health:
+
+```typescript
+async function createConsolidationBatch() {
+  const wallet = new WalletClient('auto', 'localhost')
+
+  // Note: This example demonstrates the concept but uses simulated data
+  // In practice, you would get UTXOs from wallet.listOutputs() with appropriate basket
+  console.log('Creating consolidation batch with simulated UTXO data')
+
+  // Create batch with payments only (consolidation would require actual UTXOs)
+  const outputs = [
+    // Regular payments
+    {
+      satoshis: 100,
+      lockingScript: '76a914389ffce9cd9ae88dcc0631e88a821ffdbe9bfe2688ac',
+      outputDescription: 'Batch payment 1'
+    },
+    {
+      satoshis: 150,
+      lockingScript: '76a91477bde5cfd66c6d1c83b0008b8a6e3579a6e5c6b988ac',
+      outputDescription: 'Batch payment 2'
+    },
+    // Change output (simulating consolidation)
+    {
+      satoshis: 500,
+      lockingScript: '76a914c42e7ef92fdb603af844d064faad95db9f7f1e9588ac',
+      outputDescription: 'Change output'
+    }
+  ]
+
+  // Let wallet automatically select inputs (no manual input specification)
+  const actionResult = await wallet.createAction({
+    description: 'Batch payment with change output',
+    outputs,
+  })
+
+  return actionResult
+}
+```
+
+## Conclusion
+
+Transaction batching is a powerful technique for optimizing Bitcoin applications.
+
+Understanding of `WalletClient` usage is essential for implementing these strategies effectively. While the `WalletClient` provides convenient single-transaction creation, batching multiple operations into fewer transactions can significantly improve efficiency and reduce costs. Integration with `WalletClient` is straightforward, and the benefits of batching can be substantial.