@bsv/sdk 1.9.3 → 1.9.4

package/docs/reference/errors.md

@@ -1,597 +0,0 @@
-# Error Reference
-
-Complete reference for error codes, messages, and troubleshooting in the BSV TypeScript SDK.
-
-## Error Categories
-
-### Transaction Errors
-
-#### INSUFFICIENT_FUNDS
-
-**Code**: `INSUFFICIENT_FUNDS`  
-**Message**: "Insufficient funds to create transaction"  
-**Cause**: Wallet doesn't have enough UTXOs to cover transaction outputs and fees  
-**Solutions**:
-
-- Check wallet balance with `listOutputs()`
-- Reduce transaction amount
-- Wait for pending transactions to confirm
-- Use smaller fee rates
-
-#### INVALID_TRANSACTION
-
-**Code**: `INVALID_TRANSACTION`  
-**Message**: "Transaction validation failed"  
-**Cause**: Transaction structure or signatures are invalid  
-**Solutions**:
-
-- Verify all inputs are properly signed
-- Check script templates are correct
-- Ensure transaction format is valid
-- Validate all output amounts are positive
-
-#### TRANSACTION_TOO_LARGE
-
-**Code**: `TRANSACTION_TOO_LARGE`  
-**Message**: "Transaction exceeds maximum size limit"  
-**Cause**: Transaction size exceeds network limits  
-**Solutions**:
-
-- Reduce number of inputs/outputs
-- Use more efficient script templates
-- Split into multiple transactions
-- Optimize data storage methods
-
-#### INVALID_SCRIPT
-
-**Code**: `INVALID_SCRIPT`  
-**Message**: "Script execution failed"  
-**Cause**: Locking or unlocking script contains errors  
-**Solutions**:
-
-- Validate script syntax with `Script.fromASM()`
-- Check opcode usage and limits
-- Verify script template implementation
-- Test script execution in isolation
-
-### Wallet Errors
-
-#### WALLET_NOT_CONNECTED
-
-**Code**: `WALLET_NOT_CONNECTED`  
-**Message**: "Wallet connection not established"  
-**Cause**: WalletClient not connected to substrate  
-**Solutions**:
-
-- Call `await wallet.connectToSubstrate()`
-- Check wallet application is running
-- Verify network connectivity
-- Restart wallet application if needed
-
-#### AUTHENTICATION_FAILED
-
-**Code**: `AUTHENTICATION_FAILED`  
-**Message**: "Wallet authentication failed"  
-**Cause**: User denied access or authentication expired  
-**Solutions**:
-
-- Re-authenticate with wallet
-- Check originator domain permissions
-- Verify wallet trust settings
-- Clear cached authentication state
-
-#### WALLET_LOCKED
-
-**Code**: `WALLET_LOCKED`  
-**Message**: "Wallet is locked or requires password"  
-**Cause**: Wallet requires user authentication  
-**Solutions**:
-
-- Unlock wallet application
-- Enter wallet password
-- Check wallet auto-lock settings
-- Verify user session is active
-
-#### ACTION_REJECTED
-
-**Code**: `ACTION_REJECTED`  
-**Message**: "User rejected the transaction"  
-**Cause**: User declined transaction in wallet UI  
-**Solutions**:
-
-- Retry transaction with user consent
-- Adjust transaction parameters
-- Provide clearer transaction description
-- Check transaction amounts and fees
-
-### Network Errors
-
-#### NETWORK_ERROR
-
-**Code**: `NETWORK_ERROR`  
-**Message**: "Network request failed"  
-**Cause**: Connection issues with blockchain nodes  
-**Solutions**:
-
-- Check internet connectivity
-- Verify node endpoints are accessible
-- Try alternative chain trackers
-- Implement retry logic with exponential backoff
-
-#### NODE_UNAVAILABLE
-
-**Code**: `NODE_UNAVAILABLE`  
-**Message**: "Blockchain node is unavailable"  
-**Cause**: Target node is down or unreachable  
-**Solutions**:
-
-- Switch to backup node endpoints
-- Check node status and health
-- Use multiple chain tracker instances
-- Implement failover mechanisms
-
-#### BROADCAST_FAILED
-
-**Code**: `BROADCAST_FAILED`  
-**Message**: "Transaction broadcast failed"  
-**Cause**: Network rejected transaction or broadcast error  
-**Solutions**:
-
-- Verify transaction is valid
-- Check network fees are adequate
-- Retry broadcast after delay
-- Use alternative broadcast endpoints
-
-#### TIMEOUT_ERROR
-
-**Code**: `TIMEOUT_ERROR`  
-**Message**: "Request timeout exceeded"  
-**Cause**: Network request took too long  
-**Solutions**:
-
-- Increase timeout values
-- Check network latency
-- Use faster endpoints
-- Implement request cancellation
-
-### Cryptographic Errors
-
-#### INVALID_PRIVATE_KEY
-
-**Code**: `INVALID_PRIVATE_KEY`  
-**Message**: "Private key is invalid or out of range"  
-**Cause**: Private key doesn't meet secp256k1 requirements  
-**Solutions**:
-
-- Generate new key with `PrivateKey.fromRandom()`
-- Validate key is within curve order
-- Check key format and encoding
-- Use proper key derivation methods
-
-#### INVALID_PUBLIC_KEY
-
-**Code**: `INVALID_PUBLIC_KEY`  
-**Message**: "Public key is invalid or not on curve"  
-**Cause**: Public key point is invalid  
-**Solutions**:
-
-- Verify key derivation from private key
-- Check point coordinates are valid
-- Validate key format (compressed/uncompressed)
-- Use `PublicKey.fromPrivateKey()` for generation
-
-#### SIGNATURE_VERIFICATION_FAILED
-
-**Code**: `SIGNATURE_VERIFICATION_FAILED`  
-**Message**: "Digital signature verification failed"  
-**Cause**: Signature doesn't match message and public key  
-**Solutions**:
-
-- Verify message hash is correct
-- Check signature format (DER encoding)
-- Ensure correct public key is used
-- Validate signature components (r, s values)
-
-#### ENCRYPTION_FAILED
-
-**Code**: `ENCRYPTION_FAILED`  
-**Message**: "Symmetric encryption operation failed"  
-**Cause**: AES encryption/decryption error  
-**Solutions**:
-
-- Verify encryption key is valid
-- Check data format and encoding
-- Ensure proper IV/nonce usage
-- Validate authentication tags
-
-### SPV Verification Errors
-
-#### INVALID_MERKLE_PROOF
-
-**Code**: `INVALID_MERKLE_PROOF`  
-**Message**: "Merkle proof verification failed"  
-**Cause**: Merkle path doesn't lead to valid root  
-**Solutions**:
-
-- Verify merkle path structure
-- Check transaction hash calculation
-- Validate block header merkle root
-- Ensure proof completeness
-
-#### BLOCK_HEADER_INVALID
-
-**Code**: `BLOCK_HEADER_INVALID`  
-**Message**: "Block header validation failed"  
-**Cause**: Block header doesn't meet consensus rules  
-**Solutions**:
-
-- Verify header hash and difficulty
-- Check timestamp validity
-- Validate previous block hash
-- Ensure proper header format
-
-#### CHAIN_VALIDATION_FAILED
-
-**Code**: `CHAIN_VALIDATION_FAILED`  
-**Message**: "Blockchain validation failed"  
-**Cause**: Chain doesn't follow consensus rules  
-**Solutions**:
-
-- Verify chain continuity
-- Check difficulty adjustments
-- Validate block timestamps
-- Ensure proper chain selection
-
-### Configuration Errors
-
-#### INVALID_CONFIG
-
-**Code**: `INVALID_CONFIG`  
-**Message**: "SDK configuration is invalid"  
-**Cause**: Configuration parameters are incorrect  
-**Solutions**:
-
-- Validate configuration schema
-- Check required parameters are present
-- Verify network settings
-- Use default configuration as baseline
-
-#### UNSUPPORTED_NETWORK
-
-**Code**: `UNSUPPORTED_NETWORK`  
-**Message**: "Network type is not supported"  
-**Cause**: Invalid network specification  
-**Solutions**:
-
-- Use supported networks: mainnet, testnet, regtest
-- Check network configuration
-- Verify chain parameters
-- Update SDK to latest version
-
-## Error Interface
-
-All SDK errors implement the `WalletErrorObject` interface:
-
-```typescript
-interface WalletErrorObject {
-  code: string
-  description: string
-  stack?: string
-  context?: Record<string, any>
-}
-```
-
-## Error Handling Patterns
-
-### Basic Error Handling
-
-```typescript
-try {
-  const result = await wallet.createAction({
-    description: 'Test transaction',
-    outputs: [{
-      satoshis: 100,
-      lockingScript: Script.fromASM('OP_DUP OP_HASH160 ... OP_EQUALVERIFY OP_CHECKSIG').toHex()
-    }]
-  })
-} catch (error) {
-  if (error.code === 'INSUFFICIENT_FUNDS') {
-    console.log('Not enough funds available')
-    // Handle insufficient funds
-  } else if (error.code === 'WALLET_NOT_CONNECTED') {
-    console.log('Wallet connection required')
-    await wallet.connectToSubstrate()
-  } else {
-    console.error('Unexpected error:', error)
-  }
-}
-```
-
-### Retry Logic with Exponential Backoff
-
-```typescript
-async function retryOperation<T>(
-  operation: () => Promise<T>,
-  maxRetries: number = 3,
-  baseDelay: number = 1000
-): Promise<T> {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation()
-    } catch (error) {
-      if (attempt === maxRetries) throw error
-      
-      // Only retry on network errors
-      if (!['NETWORK_ERROR', 'TIMEOUT_ERROR', 'NODE_UNAVAILABLE'].includes(error.code)) {
-        throw error
-      }
-      
-      const delay = baseDelay * Math.pow(2, attempt)
-      await new Promise(resolve => setTimeout(resolve, delay))
-    }
-  }
-  throw new Error('Max retries exceeded')
-}
-```
-
-### Comprehensive Error Categorization
-
-```typescript
-function categorizeError(error: WalletErrorObject): 'user' | 'network' | 'system' | 'config' {
-  const userErrors = ['ACTION_REJECTED', 'AUTHENTICATION_FAILED', 'WALLET_LOCKED']
-  const networkErrors = ['NETWORK_ERROR', 'NODE_UNAVAILABLE', 'BROADCAST_FAILED', 'TIMEOUT_ERROR']
-  const systemErrors = ['INVALID_TRANSACTION', 'SIGNATURE_VERIFICATION_FAILED', 'ENCRYPTION_FAILED']
-  const configErrors = ['INVALID_CONFIG', 'UNSUPPORTED_NETWORK']
-  
-  if (userErrors.includes(error.code)) return 'user'
-  if (networkErrors.includes(error.code)) return 'network'
-  if (systemErrors.includes(error.code)) return 'system'
-  if (configErrors.includes(error.code)) return 'config'
-  
-  return 'system' // Default category
-}
-```
-
-## Troubleshooting Guide
-
-### Common Issues and Solutions
-
-#### "RPC Error: no header should have returned false"
-
-**Symptoms**: Error during `createAction` calls  
-**Cause**: Wallet input selection issues  
-**Solutions**:
-
-1. Restart wallet application
-2. Ensure wallet is fully synced
-3. Use slightly larger amounts (200-500 satoshis)
-4. Wait for wallet synchronization
-5. Check for sufficient confirmed UTXOs
-
-#### "Insufficient funds" with Available Balance
-
-**Symptoms**: Error despite wallet showing balance  
-**Cause**: UTXOs not properly selected by wallet  
-**Solutions**:
-
-1. Check UTXO status with `listOutputs()`
-2. Verify UTXOs are confirmed
-3. Restart wallet to refresh UTXO cache
-4. Use manual input selection if supported
-
-#### Transaction Broadcast Failures
-
-**Symptoms**: Valid transactions rejected by network  
-**Cause**: Various network or validation issues  
-**Solutions**:
-
-1. Verify transaction format and signatures
-2. Check fee rates are adequate
-3. Ensure inputs are unspent
-4. Try alternative broadcast endpoints
-
-#### Wallet Connection Issues
-
-**Symptoms**: Cannot connect to wallet substrate  
-**Cause**: Wallet not running or permission issues  
-**Solutions**:
-
-1. Ensure wallet application is running
-2. Check originator domain permissions
-3. Clear browser cache and cookies
-4. Verify wallet trust settings
-
-### Diagnostic Tools
-
-#### Transaction Validation
-
-```typescript
-function validateTransaction(tx: Transaction): string[] {
-  const errors: string[] = []
-  
-  if (tx.inputs.length === 0) {
-    errors.push('Transaction must have at least one input')
-  }
-  
-  if (tx.outputs.length === 0) {
-    errors.push('Transaction must have at least one output')
-  }
-  
-  const totalInput = tx.inputs.reduce((sum, input) => sum + input.satoshis, 0)
-  const totalOutput = tx.outputs.reduce((sum, output) => sum + output.satoshis, 0)
-  
-  if (totalInput <= totalOutput) {
-    errors.push('Insufficient input value to cover outputs and fees')
-  }
-  
-  return errors
-}
-```
-
-#### Network Connectivity Test
-
-```typescript
-async function testNetworkConnectivity(chainTracker: ChainTracker): Promise<boolean> {
-  try {
-    const height = await chainTracker.getHeight()
-    return height > 0
-  } catch (error) {
-    console.error('Network connectivity test failed:', error)
-    return false
-  }
-}
-```
-
-#### Wallet Health Check
-
-```typescript
-async function checkWalletHealth(wallet: WalletClient): Promise<{
-  connected: boolean
-  authenticated: boolean
-  balance: number
-  errors: string[]
-}> {
-  const result = {
-    connected: false,
-    authenticated: false,
-    balance: 0,
-    errors: [] as string[]
-  }
-  
-  try {
-    await wallet.connectToSubstrate()
-    result.connected = true
-  } catch (error) {
-    result.errors.push(`Connection failed: ${error.message}`)
-  }
-  
-  try {
-    const outputs = await wallet.listOutputs({ limit: 1 })
-    result.authenticated = true
-    result.balance = outputs.totalValue || 0
-  } catch (error) {
-    result.errors.push(`Authentication failed: ${error.message}`)
-  }
-  
-  return result
-}
-```
-
-## Error Recovery Strategies
-
-### Automatic Recovery
-
-```typescript
-class ErrorRecoveryManager {
-  private retryAttempts = new Map<string, number>()
-  private maxRetries = 3
-  
-  async executeWithRecovery<T>(
-    operation: () => Promise<T>,
-    operationId: string
-  ): Promise<T> {
-    try {
-      const result = await operation()
-      this.retryAttempts.delete(operationId)
-      return result
-    } catch (error) {
-      return this.handleError(error, operation, operationId)
-    }
-  }
-  
-  private async handleError<T>(
-    error: WalletErrorObject,
-    operation: () => Promise<T>,
-    operationId: string
-  ): Promise<T> {
-    const attempts = this.retryAttempts.get(operationId) || 0
-    
-    if (attempts >= this.maxRetries) {
-      this.retryAttempts.delete(operationId)
-      throw error
-    }
-    
-    // Implement recovery strategies based on error type
-    switch (error.code) {
-      case 'WALLET_NOT_CONNECTED':
-        await this.reconnectWallet()
-        break
-      case 'NETWORK_ERROR':
-        await this.switchToBackupNode()
-        break
-      case 'INSUFFICIENT_FUNDS':
-        await this.waitForConfirmations()
-        break
-      default:
-        throw error // No recovery strategy available
-    }
-    
-    this.retryAttempts.set(operationId, attempts + 1)
-    return this.executeWithRecovery(operation, operationId)
-  }
-  
-  private async reconnectWallet(): Promise<void> {
-    // Implement wallet reconnection logic
-  }
-  
-  private async switchToBackupNode(): Promise<void> {
-    // Implement node failover logic
-  }
-  
-  private async waitForConfirmations(): Promise<void> {
-    // Wait for pending transactions to confirm
-    await new Promise(resolve => setTimeout(resolve, 30000))
-  }
-}
-```
-
-## Best Practices
-
-### Error Logging
-
-```typescript
-class ErrorLogger {
-  static log(error: WalletErrorObject, context?: Record<string, any>): void {
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      code: error.code,
-      message: error.description,
-      context: { ...error.context, ...context },
-      stack: error.stack
-    }
-    
-    // Log to appropriate destination based on severity
-    if (this.isCriticalError(error.code)) {
-      console.error('CRITICAL ERROR:', logEntry)
-    } else {
-      console.warn('ERROR:', logEntry)
-    }
-  }
-  
-  private static isCriticalError(code: string): boolean {
-    return [
-      'INVALID_PRIVATE_KEY',
-      'SIGNATURE_VERIFICATION_FAILED',
-      'CHAIN_VALIDATION_FAILED'
-    ].includes(code)
-  }
-}
-```
-
-### User-Friendly Error Messages
-
-```typescript
-function getUserFriendlyMessage(error: WalletErrorObject): string {
-  const messages: Record<string, string> = {
-    'INSUFFICIENT_FUNDS': 'You don\'t have enough funds for this transaction.',
-    'ACTION_REJECTED': 'Transaction was cancelled.',
-    'WALLET_NOT_CONNECTED': 'Please connect your wallet to continue.',
-    'NETWORK_ERROR': 'Network connection issue. Please try again.',
-    'INVALID_TRANSACTION': 'Transaction format is invalid. Please check your inputs.'
-  }
-  
-  return messages[error.code] || 'An unexpected error occurred. Please try again.'
-}
-```
-
-This comprehensive error reference provides developers with the tools and knowledge needed to handle all types of errors that may occur when using the BSV TypeScript SDK.

package/docs/reference/index.md

@@ -1,111 +0,0 @@
-# Reference Documentation
-
-Complete technical specifications and API documentation for the BSV TypeScript SDK.
-
-## Standards and Interfaces
-
-### [BRC-100 Wallet Interface](./brc-100.md)
-
-- Unified wallet-to-application interface standard
-- WalletClient implementation details
-- JSON API specifications
-
-## Core Classes
-
-### [Transaction Class](./transaction.md)
-
-- Constructor options and methods
-- Input/output management
-- Serialization formats
-
-### [PrivateKey/PublicKey Classes](./primitives.md)
-
-- Key generation methods
-- Import/export formats
-- Cryptographic operations
-
-### [Transaction Signatures Reference](./transaction-signatures.md)
-
-- ECDSA signature components
-- DER encoding format
-- Signature hash types (SIGHASH flags)
-
-### [Script Classes](./script.md)
-
-- Script construction utilities
-- Standard script templates
-- Custom script patterns
-
-### [OP Codes Reference](./op-codes.md)
-
-- Complete opcode listing and descriptions
-- Opcode categories and usage patterns
-- Script execution examples
-
-## Module Reference
-
-### [Primitives Module](./primitives.md)
-
-- Cryptographic primitives
-- Hash functions
-- Security implementation notes
-
-### [Transaction Module](./transaction.md)
-
-- Transaction lifecycle
-- Fee calculation details
-- Broadcasting options
-- SPV verification
-
-### [Wallet Module](./wallet.md)
-
-- Wallet architecture patterns
-- Integration guidelines
-- BRC-100 compliance notes
-
-## Configuration Reference
-
-### [SDK Configuration Options](./configuration.md)
-
-```typescript
-interface SDKConfig {
-  network: 'mainnet' | 'testnet' | 'regtest'
-  arc: ARCConfig
-  fees: FeeConfig
-  security: SecurityConfig
-}
-```
-
-### [ARC Configuration](./arc-config.md)
-
-- Endpoint configuration
-- Authentication methods
-- Rate limiting options
-- Failover settings
-
-### [Network Configuration](./network-config.md)
-
-- Mainnet vs testnet settings
-- Custom network parameters
-- Node endpoint configurations
-
-## Error Reference
-
-### [Error Codes and Messages](./errors.md)
-
-- Transaction validation errors
-- Network connectivity errors
-- Cryptographic operation errors
-- Troubleshooting steps
-
-### [Debugging Guide](./debugging.md)
-
-- SDK logging configuration
-- Debug mode activation
-- Transaction inspection tools
-
-## Swagger
-
-[BRC-100](https://brc.dev/100) defines a Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface which is implemented in this library within the WalletClient class. The API is laid out here as a swagger openapi document to offer a fast-track to understanding the interface which is implemented across multiple substrates. The JSON api is generally considered a developer friendly introduction to the WalletClient, where an binary equivalent ABI may be preferred for production use cases.
-
-- [Wallet JSON API Swagger](../swagger)