@bsv/sdk 1.9.2 → 1.9.4

package/docs/concepts/verification.md

@@ -1,250 +0,0 @@
-# Transaction Verification
-
-Understanding how to verify Bitcoin transactions using the BSV TypeScript SDK.
-
-## What is Transaction Verification?
-
-Transaction verification ensures that Bitcoin transactions are valid and can be trusted:
-
-```typescript
-import { Transaction } from '@bsv/sdk'
-
-// Verify a transaction
-const isValid = await transaction.verify(chainTracker, {
-  merkleProof: proof,
-  blockHeader: header
-})
-```
-
-## Verification Levels
-
-### Basic Validation
-
-Check transaction structure and format:
-
-- Valid input/output formats
-- Correct serialization
-- Proper script syntax
-- Signature format validation
-
-### Script Execution
-
-Verify that unlocking scripts satisfy locking scripts:
-
-- Execute Bitcoin script opcodes
-- Validate signature operations
-- Check script conditions
-- Ensure proper stack state
-
-### SPV Verification
-
-Confirm transaction inclusion in the blockchain:
-
-- Verify merkle proofs
-- Validate block headers
-- Check proof of work
-- Confirm transaction position
-
-## SDK Verification Methods
-
-### Transaction.verify()
-
-Complete transaction verification:
-
-```typescript
-const result = await transaction.verify(chainTracker, {
-  merkleProof: merkleProof,
-  blockHeader: blockHeader,
-  maxMemoryLimit: 100000000
-})
-```
-
-### Script Verification
-
-Verify individual scripts:
-
-```typescript
-const isValid = unlockingScript.verify(
-  lockingScript,
-  transaction,
-  inputIndex
-)
-```
-
-### Signature Verification
-
-Check digital signatures:
-
-```typescript
-const publicKey = PrivateKey.fromWif(wif).toPublicKey()
-const isValid = publicKey.verify(messageHash, signature)
-```
-
-## Verification Options
-
-### Memory Limits
-
-Control script execution memory usage:
-
-```typescript
-const options = {
-  maxMemoryLimit: 50000000 // 50MB limit
-}
-```
-
-### Scripts-Only Mode
-
-Skip SPV verification for performance:
-
-```typescript
-const options = {
-  scriptsOnly: true
-}
-```
-
-### Custom Chain Tracker
-
-Use specific data sources:
-
-```typescript
-const customTracker = new WhatsOnChain('testnet')
-const isValid = await transaction.verify(customTracker)
-```
-
-## BEEF Verification
-
-BEEF format includes verification data:
-
-```typescript
-// BEEF transactions include proofs
-const beefTx = Transaction.fromHexBEEF(beefData)
-
-// Verify using included proofs
-const isValid = await beefTx.verify(chainTracker)
-```
-
-## Error Handling
-
-Common verification failures:
-
-- Invalid signatures
-- Script execution errors
-- Missing merkle proofs
-- Network connectivity issues
-
-```typescript
-try {
-  const isValid = await transaction.verify(chainTracker)
-  if (!isValid) {
-    console.log('Transaction verification failed')
-  }
-} catch (error) {
-  console.error('Verification error:', error.message)
-}
-```
-
-## Performance Considerations
-
-### Batch Verification
-
-Verify multiple transactions efficiently:
-
-```typescript
-const results = await Promise.all(
-  transactions.map(tx => tx.verify(chainTracker))
-)
-```
-
-### Caching
-
-Cache verification results:
-
-```typescript
-const verificationCache = new Map()
-
-if (!verificationCache.has(txid)) {
-  const result = await transaction.verify(chainTracker)
-  verificationCache.set(txid, result)
-}
-```
-
-## Security Best Practices
-
-### Always Verify
-
-- Verify transactions before trusting them
-- Check both script execution and SPV proofs
-- Validate input data before verification
-
-### Multiple Sources
-
-- Use multiple chain trackers for redundancy
-- Cross-check verification results
-- Implement fallback mechanisms
-
-### Resource Limits
-
-- Set appropriate memory limits
-- Timeout long-running verifications
-- Monitor verification performance
-
-## Common Use Cases
-
-### Payment Verification
-
-```typescript
-// Verify received payment
-const payment = Transaction.fromHex(paymentHex)
-const isValid = await payment.verify(chainTracker)
-
-if (isValid) {
-  // Process confirmed payment
-}
-```
-
-### Historical Transaction Audit
-
-```typescript
-// Verify old transactions
-for (const txHex of historicalTransactions) {
-  const tx = Transaction.fromHex(txHex)
-  const result = await tx.verify(chainTracker)
-  console.log(`Transaction ${tx.id()}: ${result ? 'Valid' : 'Invalid'}`)
-}
-```
-
-## Integration Patterns
-
-### Wallet Integration
-
-```typescript
-// Wallets typically handle verification
-const wallet = new WalletClient()
-const action = await wallet.createAction({
-  outputs: [/* outputs */]
-})
-// Wallet verifies before broadcasting
-```
-
-### Application Verification
-
-```typescript
-// Applications verify received transactions
-async function processIncomingTransaction(txHex: string) {
-  const tx = Transaction.fromHex(txHex)
-  
-  if (await tx.verify(chainTracker)) {
-    // Process verified transaction
-    await handleValidTransaction(tx)
-  } else {
-    // Reject invalid transaction
-    throw new Error('Invalid transaction received')
-  }
-}
-```
-
-## Next Steps
-
-- Learn about [SPV Verification](./spv-verification.md) concepts
-- Understand [Digital Signatures](./signatures.md) validation
-- Explore [BEEF Format](./beef.md) for efficient verification

package/docs/concepts/wallet-integration.md

@@ -1,101 +0,0 @@
-# Wallet Integration
-
-How the BSV TypeScript SDK connects with Bitcoin wallets and manages user authentication.
-
-## Wallet Connection Model
-
-The SDK uses a standardized approach to connect with Bitcoin wallets:
-
-```typescript
-import { WalletClient } from '@bsv/sdk'
-
-// Connect to a wallet
-const wallet = new WalletClient('https://wallet-url')
-
-// Authenticate with the wallet
-await wallet.authenticate()
-```
-
-## BRC-100 Compliance
-
-The SDK follows the BRC-100 standard for wallet communication:
-
-- **Standardized APIs**: Consistent interface across different wallets
-- **Authentication**: Secure identity verification
-- **Transaction Signing**: Wallet handles private key operations
-- **UTXO Management**: Wallet manages available funds
-
-## Authentication Flow
-
-1. **Connection**: Establish connection to wallet service
-2. **Identity**: Wallet provides user identity information
-3. **Capabilities**: Discover what the wallet can do
-4. **Authorization**: User grants permission for specific operations
-
-## Transaction Creation
-
-The wallet handles sensitive operations:
-
-```typescript
-// Create a transaction action
-const action = await wallet.createAction({
-  description: 'Payment transaction',
-  outputs: [{
-    satoshis: 1000,
-    lockingScript: recipientScript
-  }]
-})
-
-// Wallet signs and broadcasts automatically
-```
-
-## Key Benefits
-
-### Security
-
-- Private keys never leave the wallet
-- User controls transaction approval
-- Secure authentication protocols
-
-### User Experience
-
-- Familiar wallet interface
-- Consistent across applications
-- Single sign-on capabilities
-
-### Developer Simplicity
-
-- No key management complexity
-- Standardized APIs
-- Automatic UTXO handling
-
-## Wallet Types
-
-The SDK works with various wallet implementations:
-
-- **Desktop Wallets**: Local applications with full control
-- **Web Wallets**: Browser-based wallet services
-- **Mobile Wallets**: Smartphone applications
-- **Hardware Wallets**: Secure hardware devices
-
-## Error Handling
-
-Common wallet integration scenarios:
-
-- Wallet not available or offline
-- User denies transaction approval
-- Insufficient funds in wallet
-- Network connectivity issues
-
-## Best Practices
-
-- Always handle wallet connection failures gracefully
-- Provide clear transaction descriptions to users
-- Implement retry logic for network issues
-- Cache wallet capabilities to improve performance
-
-## Next Steps
-
-- Learn about [Chain Tracking](./chain-tracking.md) for network data
-- Understand [Key Management](./key-management.md) concepts
-- Explore [Trust Model](./trust-model.md) considerations

package/docs/guides/development-wallet-setup.md

@@ -1,374 +0,0 @@
-# Setting up Development Wallets
-
-Learn how to set up and configure ProtoWallet for development, testing, and prototyping scenarios.
-
-## Problem
-
-You need a lightweight wallet solution for development and testing that doesn't require full blockchain integration but provides all necessary cryptographic operations.
-
-## Solution
-
-Use ProtoWallet for development environments with proper key management, signing capabilities, and testing workflows.
-
-### Basic Development Wallet Setup
-
-```typescript
-import { ProtoWallet, PrivateKey } from '@bsv/sdk'
-
-class DevelopmentWalletManager {
-  private wallets: Map<string, ProtoWallet> = new Map()
-  private walletKeys: Map<string, PrivateKey> = new Map()
-  
-  async createWallet(name: string, privateKey?: PrivateKey): Promise<ProtoWallet> {
-    const key = privateKey || PrivateKey.fromRandom()
-    const wallet = new ProtoWallet(key)
-    
-    this.wallets.set(name, wallet)
-    this.walletKeys.set(name, key)
-    
-    // Get identity public key for display
-    const { publicKey } = await wallet.getPublicKey({ identityKey: true })
-    console.log(`Created wallet "${name}" with public key: ${publicKey}`)
-    
-    return wallet
-  }
-  
-  getWallet(name: string): ProtoWallet | undefined {
-    return this.wallets.get(name)
-  }
-  
-  async listWallets(): Promise<Array<{ name: string; publicKey: string }>> {
-    const walletList = []
-    for (const [name, wallet] of this.wallets.entries()) {
-      const { publicKey } = await wallet.getPublicKey({ identityKey: true })
-      walletList.push({ name, publicKey })
-    }
-    return walletList
-  }
-  
-  exportWallet(name: string): string | null {
-    const privateKey = this.walletKeys.get(name)
-    if (!privateKey) return null
-    
-    return privateKey.toString()
-  }
-  
-  async importWallet(name: string, privateKeyString: string): Promise<ProtoWallet> {
-    const privateKey = PrivateKey.fromString(privateKeyString)
-    return await this.createWallet(name, privateKey)
-  }
-}
-```
-
-### Testing Wallet with Mock Transactions
-
-```typescript
-import { ProtoWallet, PrivateKey, P2PKH } from '@bsv/sdk'
-
-class TestingWallet {
-  private wallet: ProtoWallet
-  private privateKey: PrivateKey
-  private mockUTXOs: Array<{
-    txid: string
-    vout: number
-    satoshis: number
-    script: string
-  }> = []
-  
-  constructor(privateKey?: PrivateKey) {
-    this.privateKey = privateKey || PrivateKey.fromRandom()
-    this.wallet = new ProtoWallet(this.privateKey)
-  }
-  
-  // Add mock UTXOs for testing
-  async addMockUTXO(satoshis: number): Promise<void> {
-    const mockTxid = Array.from(crypto.getRandomValues(new Uint8Array(32)))
-      .map(b => b.toString(16).padStart(2, '0'))
-      .join('')
-    
-    // Create a simple P2PKH locking script using a mock address
-    // In a real implementation, you'd derive the proper address from the public key
-    const mockAddress = '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa' // Example Bitcoin address
-    const p2pkh = new P2PKH()
-    const lockingScript = p2pkh.lock(mockAddress)
-    
-    this.mockUTXOs.push({
-      txid: mockTxid,
-      vout: 0,
-      satoshis,
-      script: lockingScript.toHex()
-    })
-  }
-  
-  getMockBalance(): number {
-    return this.mockUTXOs.reduce((sum, utxo) => sum + utxo.satoshis, 0)
-  }
-  
-  async createMockTransaction(
-    recipientPublicKey: string,
-    amount: number
-  ): Promise<string> {
-    if (this.getMockBalance() < amount + 100) { // 100 sat fee
-      throw new Error('Insufficient mock balance')
-    }
-    
-    // For this demo, we'll create a simple transaction representation
-    // In a real implementation, you'd use the full Transaction class
-    let inputAmount = 0
-    const usedUTXOs: number[] = []
-    
-    for (let i = 0; i < this.mockUTXOs.length && inputAmount < amount + 100; i++) {
-      const utxo = this.mockUTXOs[i]
-      inputAmount += utxo.satoshis
-      usedUTXOs.push(i)
-    }
-    
-    // Calculate change
-    const change = inputAmount - amount - 100
-    
-    // Create transaction summary
-    const txSummary = {
-      inputs: usedUTXOs.length,
-      outputs: change > 0 ? 2 : 1,
-      amount,
-      change,
-      fee: 100,
-      recipient: recipientPublicKey
-    }
-    
-    // Remove used UTXOs
-    usedUTXOs.reverse().forEach(index => {
-      this.mockUTXOs.splice(index, 1)
-    })
-    
-    return JSON.stringify(txSummary, null, 2)
-  }
-  
-  async getPublicKey(): Promise<string> {
-    const { publicKey } = await this.wallet.getPublicKey({ identityKey: true })
-    return publicKey
-  }
-}
-```
-
-### Multi-Wallet Development Environment
-
-```typescript
-import { ProtoWallet, PrivateKey } from '@bsv/sdk'
-
-interface WalletConfig {
-  name: string
-  purpose: string
-  balance?: number
-  privateKey?: string
-}
-
-class DevelopmentEnvironment {
-  private wallets: Map<string, ProtoWallet> = new Map()
-  private walletConfigs: Map<string, WalletConfig> = new Map()
-  
-  async setupEnvironment(configs: WalletConfig[]): Promise<void> {
-    console.log('Setting up development environment...')
-    
-    for (const config of configs) {
-      const privateKey = config.privateKey 
-        ? PrivateKey.fromString(config.privateKey)
-        : PrivateKey.fromRandom()
-      
-      const wallet = new ProtoWallet(privateKey)
-      
-      this.wallets.set(config.name, wallet)
-      this.walletConfigs.set(config.name, config)
-      
-      // Get identity public key for display
-      const { publicKey } = await wallet.getPublicKey({ identityKey: true })
-      
-      console.log(`✓ Created ${config.name} wallet (${config.purpose})`)
-      console.log(`  Public Key: ${publicKey}`)
-      
-      if (config.balance) {
-        console.log(`  Mock Balance: ${config.balance} satoshis`)
-      }
-    }
-    
-    console.log('Development environment ready!')
-  }
-  
-  getWallet(name: string): ProtoWallet | undefined {
-    return this.wallets.get(name)
-  }
-  
-  async demonstrateSigningFlow(
-    signerName: string,
-    message: string
-  ): Promise<void> {
-    const wallet = this.wallets.get(signerName)
-    if (!wallet) {
-      throw new Error(`Wallet ${signerName} not found`)
-    }
-    
-    console.log(`\n--- Signing Demo with ${signerName} ---`)
-    console.log(`Message: "${message}"`)
-    
-    const messageBytes = new TextEncoder().encode(message)
-    
-    // Create signature using ProtoWallet API
-    const { signature } = await wallet.createSignature({
-      data: Array.from(messageBytes),
-      protocolID: [1, 'demo signing'],
-      keyID: 'message-key',
-      counterparty: 'self'
-    })
-    
-    console.log(`Signature created successfully`)
-    
-    // Verify signature
-    try {
-      const { valid } = await wallet.verifySignature({
-        data: Array.from(messageBytes),
-        signature,
-        protocolID: [1, 'demo signing'],
-        keyID: 'message-key',
-        counterparty: 'self'
-      })
-      console.log(`Verification: ${valid ? '✓ Valid' : '✗ Invalid'}`)
-    } catch (error: any) {
-      console.log(`Verification: ✓ Valid (signature verification successful)`)
-    }
-  }
-  
-  async demonstrateEncryption(
-    senderName: string,
-    recipientName: string,
-    message: string
-  ): Promise<void> {
-    const sender = this.wallets.get(senderName)
-    const recipient = this.wallets.get(recipientName)
-    
-    if (!sender || !recipient) {
-      throw new Error('Both wallets must exist for encryption demo')
-    }
-    
-    console.log(`\n--- Encryption Demo: ${senderName} → ${recipientName} ---`)
-    console.log(`Original message: "${message}"`)
-    
-    const messageBytes = new TextEncoder().encode(message)
-    
-    // Get recipient's public key for encryption
-    const { publicKey: recipientPubKey } = await recipient.getPublicKey({ identityKey: true })
-    
-    // Encrypt using ProtoWallet API
-    const { ciphertext } = await sender.encrypt({
-      plaintext: Array.from(messageBytes),
-      protocolID: [1, 'demo encryption'],
-      keyID: 'message-key',
-      counterparty: recipientPubKey
-    })
-    
-    console.log(`Encrypted successfully`)
-    
-    // Get sender's public key for decryption
-    const { publicKey: senderPubKey } = await sender.getPublicKey({ identityKey: true })
-    
-    // Decrypt
-    const { plaintext } = await recipient.decrypt({
-      ciphertext,
-      protocolID: [1, 'demo encryption'],
-      keyID: 'message-key',
-      counterparty: senderPubKey
-    })
-    
-    const decryptedMessage = new TextDecoder().decode(new Uint8Array(plaintext))
-    
-    console.log(`Decrypted: "${decryptedMessage}"`)
-    console.log(`Match: ${message === decryptedMessage ? '✓ Success' : '✗ Failed'}`)
-  }
-  
-  async exportEnvironment(): Promise<any> {
-    const exported: any = {}
-    
-    for (const [name, wallet] of this.wallets) {
-      const config = this.walletConfigs.get(name)!
-      const { publicKey } = await wallet.getPublicKey({ identityKey: true })
-      
-      exported[name] = {
-        ...config,
-        publicKey
-        // Note: Private key export would require additional security measures in production
-      }
-    }
-    
-    return exported
-  }
-  
-  async saveEnvironment(filename: string): Promise<void> {
-    const exported = await this.exportEnvironment()
-    const json = JSON.stringify(exported, null, 2)
-    
-    // In a real environment, you'd save to file
-    console.log(`Environment configuration:\n${json}`)
-  }
-}
-
-// Example usage
-async function setupDevelopmentEnvironment() {
-  const env = new DevelopmentEnvironment()
-  
-  await env.setupEnvironment([
-    {
-      name: 'alice',
-      purpose: 'Primary test user',
-      balance: 100000
-    },
-    {
-      name: 'bob',
-      purpose: 'Secondary test user',
-      balance: 50000
-    },
-    {
-      name: 'merchant',
-      purpose: 'Payment recipient',
-      balance: 10000
-    },
-    {
-      name: 'service',
-      purpose: 'API service wallet'
-    }
-  ])
-  
-  // Demonstrate functionality
-  await env.demonstrateSigningFlow('alice', 'Hello, BSV!')
-  await env.demonstrateEncryption('alice', 'bob', 'Secret message')
-  
-  await env.saveEnvironment('dev-environment.json')
-}
-
-```
-
-## Best Practices
-
-1. **Use deterministic keys** for reproducible testing environments
-2. **Implement proper key storage** for development wallets
-3. **Create wallet profiles** for different testing scenarios
-4. **Use mock UTXOs** for transaction testing without blockchain interaction
-5. **Document wallet purposes** and configurations
-
-## Common Issues
-
-- **Key management**: Use secure storage even in development
-- **Mock transaction validation**: Ensure realistic transaction structures
-- **Environment consistency**: Use configuration files for reproducible setups
-- **Testing isolation**: Separate development and production environments
-
-## Security Considerations
-
-- **Never use development keys** in production
-- **Secure development environments** appropriately
-- **Use separate networks** (testnet/regtest) for development
-- **Implement proper cleanup** of development data
-
-## Related
-
-- [ProtoWallet Tutorial](../tutorials/protowallet-development.md)
-- [Security Best Practices](./security-best-practices.md)
-- [Transaction Construction](./transaction-construction.md)