@bsv/sdk 1.9.3 → 1.9.4

package/docs/reference/configuration.md

@@ -1,835 +0,0 @@
-# Configuration Reference
-
-Complete reference for SDK configuration options, interfaces, and setup patterns in the BSV TypeScript SDK.
-
-## Core Configuration Interface
-
-```typescript
-interface SDKConfig {
-  network: NetworkType
-  arc: ARCConfig
-  fees: FeeConfig
-  security: SecurityConfig
-  wallet: WalletConfig
-  chainTracker: ChainTrackerConfig
-  logging: LoggingConfig
-}
-```
-
-## Network Configuration
-
-### NetworkType
-
-```typescript
-type NetworkType = 'mainnet' | 'testnet' | 'regtest'
-```
-
-### Network Parameters
-
-```typescript
-interface NetworkConfig {
-  name: NetworkType
-  chainParams: {
-    genesisHash: string
-    port: number
-    dnsSeeds: string[]
-    addressPrefix: {
-      pubKeyHash: number
-      scriptHash: number
-      privateKey: number
-    }
-  }
-  defaultEndpoints: {
-    arc: string[]
-    chainTracker: string[]
-    broadcast: string[]
-  }
-}
-```
-
-### Predefined Networks
-
-#### Mainnet Configuration
-
-```typescript
-const MAINNET_CONFIG: NetworkConfig = {
-  name: 'mainnet',
-  chainParams: {
-    genesisHash: '000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f',
-    port: 8333,
-    dnsSeeds: [
-      'seed.bitcoinsv.io',
-      'seed.cascharia.com',
-      'seed.satoshisvision.network'
-    ],
-    addressPrefix: {
-      pubKeyHash: 0x00,
-      scriptHash: 0x05,
-      privateKey: 0x80
-    }
-  },
-  defaultEndpoints: {
-    arc: ['https://arc.taal.com'],
-    chainTracker: ['https://api.whatsonchain.com/v1/bsv/main'],
-    broadcast: ['https://api.whatsonchain.com/v1/bsv/main/tx/raw']
-  }
-}
-```
-
-#### Testnet Configuration
-
-```typescript
-const TESTNET_CONFIG: NetworkConfig = {
-  name: 'testnet',
-  chainParams: {
-    genesisHash: '000000000933ea01ad0ee984209779baaec3ced90fa3f408719526f8d77f4943',
-    port: 18333,
-    dnsSeeds: [
-      'testnet-seed.bitcoinsv.io',
-      'testnet-seed.cascharia.com'
-    ],
-    addressPrefix: {
-      pubKeyHash: 0x6f,
-      scriptHash: 0xc4,
-      privateKey: 0xef
-    }
-  },
-  defaultEndpoints: {
-    arc: ['https://arc-testnet.taal.com'],
-    chainTracker: ['https://api.whatsonchain.com/v1/bsv/test'],
-    broadcast: ['https://api.whatsonchain.com/v1/bsv/test/tx/raw']
-  }
-}
-```
-
-#### Regtest Configuration
-
-```typescript
-const REGTEST_CONFIG: NetworkConfig = {
-  name: 'regtest',
-  chainParams: {
-    genesisHash: '0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206',
-    port: 18444,
-    dnsSeeds: [],
-    addressPrefix: {
-      pubKeyHash: 0x6f,
-      scriptHash: 0xc4,
-      privateKey: 0xef
-    }
-  },
-  defaultEndpoints: {
-    arc: ['http://localhost:9090'],
-    chainTracker: ['http://localhost:3001/v1/bsv/regtest'],
-    broadcast: ['http://localhost:3001/v1/bsv/regtest/tx/raw']
-  }
-}
-```
-
-## ARC Configuration
-
-### ARCConfig Interface
-
-```typescript
-interface ARCConfig {
-  apiUrl: string
-  apiKey?: string
-  timeout: number
-  retryAttempts: number
-  retryDelay: number
-  rateLimiting: {
-    requestsPerSecond: number
-    burstLimit: number
-  }
-  endpoints: {
-    submit: string
-    status: string
-    policy: string
-  }
-}
-```
-
-### Default ARC Configuration
-
-```typescript
-const DEFAULT_ARC_CONFIG: ARCConfig = {
-  apiUrl: 'https://arc.taal.com',
-  timeout: 30000, // 30 seconds
-  retryAttempts: 3,
-  retryDelay: 1000, // 1 second
-  rateLimiting: {
-    requestsPerSecond: 10,
-    burstLimit: 50
-  },
-  endpoints: {
-    submit: '/v1/tx',
-    status: '/v1/tx/{txid}',
-    policy: '/v1/policy'
-  }
-}
-```
-
-### ARC Authentication
-
-```typescript
-interface ARCAuth {
-  type: 'bearer' | 'api-key' | 'none'
-  credentials: {
-    token?: string
-    apiKey?: string
-    secret?: string
-  }
-}
-```
-
-## Fee Configuration
-
-### FeeConfig Interface
-
-```typescript
-interface FeeConfig {
-  strategy: FeeStrategy
-  rates: FeeRates
-  limits: FeeLimits
-  estimation: FeeEstimationConfig
-}
-```
-
-### Fee Strategy Types
-
-```typescript
-type FeeStrategy = 'fixed' | 'dynamic' | 'priority' | 'custom'
-
-interface FeeRates {
-  // Satoshis per byte
-  standard: number
-  priority: number
-  economy: number
-  custom?: number
-}
-
-interface FeeLimits {
-  minFeeRate: number // Minimum satoshis per byte
-  maxFeeRate: number // Maximum satoshis per byte
-  maxTotalFee: number // Maximum total fee in satoshis
-}
-```
-
-### Default Fee Configuration
-
-```typescript
-const DEFAULT_FEE_CONFIG: FeeConfig = {
-  strategy: 'standard',
-  rates: {
-    standard: 0.5,  // 0.5 sat/byte
-    priority: 1.0,  // 1.0 sat/byte
-    economy: 0.25   // 0.25 sat/byte
-  },
-  limits: {
-    minFeeRate: 0.25,
-    maxFeeRate: 10.0,
-    maxTotalFee: 100000 // 1000 sat maximum
-  },
-  estimation: {
-    enabled: true,
-    source: 'arc',
-    fallbackRate: 0.5,
-    updateInterval: 300000 // 5 minutes
-  }
-}
-```
-
-### Fee Estimation Configuration
-
-```typescript
-interface FeeEstimationConfig {
-  enabled: boolean
-  source: 'arc' | 'chainTracker' | 'static'
-  fallbackRate: number
-  updateInterval: number
-  cacheTimeout: number
-}
-```
-
-## Security Configuration
-
-### SecurityConfig Interface
-
-```typescript
-interface SecurityConfig {
-  keyGeneration: KeyGenerationConfig
-  encryption: EncryptionConfig
-  validation: ValidationConfig
-  randomness: RandomnessConfig
-}
-```
-
-### Key Generation Configuration
-
-```typescript
-interface KeyGenerationConfig {
-  source: 'secure-random' | 'deterministic'
-  entropy: {
-    minBits: number
-    sources: EntropySource[]
-  }
-  derivation: {
-    hardened: boolean
-    maxDepth: number
-  }
-}
-
-type EntropySource = 'crypto' | 'mouse' | 'keyboard' | 'timing'
-```
-
-### Encryption Configuration
-
-```typescript
-interface EncryptionConfig {
-  algorithm: 'AES-GCM' | 'AES-CBC'
-  keySize: 128 | 256
-  ivSize: number
-  tagSize: number
-  keyDerivation: {
-    algorithm: 'PBKDF2' | 'scrypt'
-    iterations: number
-    saltSize: number
-  }
-}
-```
-
-### Default Security Configuration
-
-```typescript
-const DEFAULT_SECURITY_CONFIG: SecurityConfig = {
-  keyGeneration: {
-    source: 'secure-random',
-    entropy: {
-      minBits: 256,
-      sources: ['crypto']
-    },
-    derivation: {
-      hardened: true,
-      maxDepth: 5
-    }
-  },
-  encryption: {
-    algorithm: 'AES-GCM',
-    keySize: 256,
-    ivSize: 12,
-    tagSize: 16,
-    keyDerivation: {
-      algorithm: 'PBKDF2',
-      iterations: 100000,
-      saltSize: 32
-    }
-  },
-  validation: {
-    strictMode: true,
-    checkSignatures: true,
-    validateScripts: true,
-    enforceMinimumFees: true
-  },
-  randomness: {
-    source: 'crypto.getRandomValues',
-    testRandomness: false,
-    fallbackToMath: false
-  }
-}
-```
-
-## Wallet Configuration
-
-### WalletConfig Interface
-
-```typescript
-interface WalletConfig {
-  substrate: WalletSubstrate
-  connection: ConnectionConfig
-  authentication: AuthConfig
-  permissions: PermissionConfig
-}
-```
-
-### Wallet Substrate Types
-
-```typescript
-type WalletSubstrate = 
-  | 'auto'
-  | 'Cicada'
-  | 'XDM'
-  | 'window.CWI'
-  | 'json-api'
-  | 'react-native'
-  | WalletInterface
-```
-
-### Connection Configuration
-
-```typescript
-interface ConnectionConfig {
-  timeout: number
-  retryAttempts: number
-  retryDelay: number
-  keepAlive: boolean
-  autoReconnect: boolean
-}
-```
-
-### Authentication Configuration
-
-```typescript
-interface AuthConfig {
-  required: boolean
-  timeout: number
-  cacheCredentials: boolean
-  refreshInterval: number
-  originator: string
-}
-```
-
-### Default Wallet Configuration
-
-```typescript
-const DEFAULT_WALLET_CONFIG: WalletConfig = {
-  substrate: 'auto',
-  connection: {
-    timeout: 10000,
-    retryAttempts: 3,
-    retryDelay: 1000,
-    keepAlive: true,
-    autoReconnect: true
-  },
-  authentication: {
-    required: true,
-    timeout: 30000,
-    cacheCredentials: false,
-    refreshInterval: 3600000, // 1 hour
-    originator: 'localhost'
-  },
-  permissions: {
-    createActions: true,
-    signTransactions: true,
-    accessKeys: false,
-    manageOutputs: true
-  }
-}
-```
-
-## Chain Tracker Configuration
-
-### ChainTrackerConfig Interface
-
-```typescript
-interface ChainTrackerConfig {
-  primary: ChainTrackerEndpoint
-  fallbacks: ChainTrackerEndpoint[]
-  failover: FailoverConfig
-  caching: CacheConfig
-}
-```
-
-### Chain Tracker Endpoint
-
-```typescript
-interface ChainTrackerEndpoint {
-  url: string
-  apiKey?: string
-  timeout: number
-  rateLimiting: RateLimitConfig
-  capabilities: TrackerCapability[]
-}
-
-type TrackerCapability = 
-  | 'getHeight'
-  | 'getHeader'
-  | 'getTransaction'
-  | 'getMerkleProof'
-  | 'broadcast'
-```
-
-### Failover Configuration
-
-```typescript
-interface FailoverConfig {
-  enabled: boolean
-  maxFailures: number
-  failureWindow: number
-  recoveryTime: number
-  healthCheck: {
-    enabled: boolean
-    interval: number
-    timeout: number
-  }
-}
-```
-
-### Default Chain Tracker Configuration
-
-```typescript
-const DEFAULT_CHAINTRACKER_CONFIG: ChainTrackerConfig = {
-  primary: {
-    url: 'https://api.whatsonchain.com/v1/bsv/main',
-    timeout: 10000,
-    rateLimiting: {
-      requestsPerSecond: 5,
-      burstLimit: 20
-    },
-    capabilities: ['getHeight', 'getHeader', 'getTransaction', 'getMerkleProof']
-  },
-  fallbacks: [
-    {
-      url: 'https://api.bitindex.network',
-      timeout: 15000,
-      rateLimiting: {
-        requestsPerSecond: 3,
-        burstLimit: 10
-      },
-      capabilities: ['getHeight', 'getTransaction']
-    }
-  ],
-  failover: {
-    enabled: true,
-    maxFailures: 3,
-    failureWindow: 300000, // 5 minutes
-    recoveryTime: 600000,  // 10 minutes
-    healthCheck: {
-      enabled: true,
-      interval: 60000,     // 1 minute
-      timeout: 5000
-    }
-  },
-  caching: {
-    enabled: true,
-    ttl: 30000,           // 30 seconds
-    maxSize: 1000,
-    strategy: 'lru'
-  }
-}
-```
-
-## Logging Configuration
-
-### LoggingConfig Interface
-
-```typescript
-interface LoggingConfig {
-  level: LogLevel
-  outputs: LogOutput[]
-  format: LogFormat
-  filters: LogFilter[]
-  performance: PerformanceLoggingConfig
-}
-```
-
-### Log Levels and Outputs
-
-```typescript
-type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace'
-
-interface LogOutput {
-  type: 'console' | 'file' | 'remote'
-  config: {
-    file?: string
-    url?: string
-    maxSize?: number
-    rotation?: boolean
-  }
-}
-
-interface LogFormat {
-  timestamp: boolean
-  level: boolean
-  component: boolean
-  structured: boolean
-  colors: boolean
-}
-```
-
-### Default Logging Configuration
-
-```typescript
-const DEFAULT_LOGGING_CONFIG: LoggingConfig = {
-  level: 'info',
-  outputs: [
-    {
-      type: 'console',
-      config: {}
-    }
-  ],
-  format: {
-    timestamp: true,
-    level: true,
-    component: true,
-    structured: false,
-    colors: true
-  },
-  filters: [],
-  performance: {
-    enabled: false,
-    threshold: 1000,
-    includeStackTrace: false
-  }
-}
-```
-
-## Configuration Loading and Management
-
-### Configuration Builder
-
-```typescript
-class SDKConfigBuilder {
-  private config: Partial<SDKConfig> = {}
-  
-  network(type: NetworkType): this {
-    this.config.network = type
-    return this
-  }
-  
-  arc(config: Partial<ARCConfig>): this {
-    this.config.arc = { ...DEFAULT_ARC_CONFIG, ...config }
-    return this
-  }
-  
-  fees(config: Partial<FeeConfig>): this {
-    this.config.fees = { ...DEFAULT_FEE_CONFIG, ...config }
-    return this
-  }
-  
-  security(config: Partial<SecurityConfig>): this {
-    this.config.security = { ...DEFAULT_SECURITY_CONFIG, ...config }
-    return this
-  }
-  
-  wallet(config: Partial<WalletConfig>): this {
-    this.config.wallet = { ...DEFAULT_WALLET_CONFIG, ...config }
-    return this
-  }
-  
-  chainTracker(config: Partial<ChainTrackerConfig>): this {
-    this.config.chainTracker = { ...DEFAULT_CHAINTRACKER_CONFIG, ...config }
-    return this
-  }
-  
-  logging(config: Partial<LoggingConfig>): this {
-    this.config.logging = { ...DEFAULT_LOGGING_CONFIG, ...config }
-    return this
-  }
-  
-  build(): SDKConfig {
-    return {
-      network: this.config.network || 'testnet',
-      arc: this.config.arc || DEFAULT_ARC_CONFIG,
-      fees: this.config.fees || DEFAULT_FEE_CONFIG,
-      security: this.config.security || DEFAULT_SECURITY_CONFIG,
-      wallet: this.config.wallet || DEFAULT_WALLET_CONFIG,
-      chainTracker: this.config.chainTracker || DEFAULT_CHAINTRACKER_CONFIG,
-      logging: this.config.logging || DEFAULT_LOGGING_CONFIG
-    }
-  }
-}
-```
-
-### Configuration Usage Examples
-
-#### Basic Configuration
-
-```typescript
-import { SDKConfigBuilder } from '@bsv/sdk'
-
-const config = new SDKConfigBuilder()
-  .network('testnet')
-  .fees({ strategy: 'priority' })
-  .build()
-```
-
-#### Production Configuration
-
-```typescript
-const productionConfig = new SDKConfigBuilder()
-  .network('mainnet')
-  .arc({
-    apiUrl: 'https://arc.taal.com',
-    apiKey: process.env.TAAL_API_KEY,
-    timeout: 30000
-  })
-  .fees({
-    strategy: 'dynamic',
-    rates: {
-      standard: 0.5,
-      priority: 1.0,
-      economy: 0.25
-    }
-  })
-  .security({
-    validation: {
-      strictMode: true,
-      checkSignatures: true,
-      validateScripts: true
-    }
-  })
-  .chainTracker({
-    primary: {
-      url: 'https://api.whatsonchain.com/v1/bsv/main',
-      timeout: 10000
-    },
-    failover: {
-      enabled: true,
-      maxFailures: 3
-    }
-  })
-  .logging({
-    level: 'warn',
-    outputs: [
-      { type: 'console', config: {} },
-      { type: 'file', config: { file: '/var/log/bsv-sdk.log' } }
-    ]
-  })
-  .build()
-```
-
-#### Development Configuration
-
-```typescript
-const devConfig = new SDKConfigBuilder()
-  .network('regtest')
-  .arc({
-    apiUrl: 'http://localhost:9090',
-    timeout: 5000
-  })
-  .fees({
-    strategy: 'fixed',
-    rates: { standard: 1.0 }
-  })
-  .chainTracker({
-    primary: {
-      url: 'http://localhost:3001/v1/bsv/regtest',
-      timeout: 5000
-    },
-    failover: { enabled: false }
-  })
-  .logging({
-    level: 'debug',
-    format: {
-      timestamp: true,
-      colors: true,
-      structured: true
-    }
-  })
-  .build()
-```
-
-## Environment-Based Configuration
-
-### Configuration from Environment Variables
-
-```typescript
-function loadConfigFromEnv(): SDKConfig {
-  return new SDKConfigBuilder()
-    .network((process.env.BSV_NETWORK as NetworkType) || 'testnet')
-    .arc({
-      apiUrl: process.env.ARC_API_URL || 'https://arc-testnet.taal.com',
-      apiKey: process.env.ARC_API_KEY,
-      timeout: parseInt(process.env.ARC_TIMEOUT || '30000')
-    })
-    .fees({
-      strategy: (process.env.FEE_STRATEGY as FeeStrategy) || 'standard',
-      rates: {
-        standard: parseFloat(process.env.FEE_RATE_STANDARD || '0.5'),
-        priority: parseFloat(process.env.FEE_RATE_PRIORITY || '1.0'),
-        economy: parseFloat(process.env.FEE_RATE_ECONOMY || '0.25')
-      }
-    })
-    .wallet({
-      substrate: (process.env.WALLET_SUBSTRATE as WalletSubstrate) || 'auto',
-      authentication: {
-        originator: process.env.WALLET_ORIGINATOR || 'localhost'
-      }
-    })
-    .logging({
-      level: (process.env.LOG_LEVEL as LogLevel) || 'info'
-    })
-    .build()
-}
-```
-
-### Configuration Validation
-
-```typescript
-function validateConfig(config: SDKConfig): string[] {
-  const errors: string[] = []
-  
-  // Validate network
-  if (!['mainnet', 'testnet', 'regtest'].includes(config.network)) {
-    errors.push('Invalid network type')
-  }
-  
-  // Validate ARC configuration
-  if (!config.arc.apiUrl) {
-    errors.push('ARC API URL is required')
-  }
-  
-  if (config.arc.timeout < 1000) {
-    errors.push('ARC timeout must be at least 1000ms')
-  }
-  
-  // Validate fee configuration
-  if (config.fees.rates.standard <= 0) {
-    errors.push('Standard fee rate must be positive')
-  }
-  
-  if (config.fees.limits.minFeeRate > config.fees.limits.maxFeeRate) {
-    errors.push('Minimum fee rate cannot exceed maximum fee rate')
-  }
-  
-  // Validate security configuration
-  if (config.security.encryption.keySize !== 128 && config.security.encryption.keySize !== 256) {
-    errors.push('Encryption key size must be 128 or 256 bits')
-  }
-  
-  return errors
-}
-```
-
-## Configuration Best Practices
-
-### Security Considerations
-
-1. **Never hardcode API keys** - Use environment variables or secure configuration management
-2. **Use HTTPS endpoints** - Ensure all external API calls use secure connections
-3. **Validate configuration** - Always validate configuration before using
-4. **Rotate credentials** - Regularly rotate API keys and authentication tokens
-5. **Limit permissions** - Use principle of least privilege for wallet permissions
-
-### Performance Optimization
-
-1. **Configure appropriate timeouts** - Balance responsiveness with reliability
-2. **Use connection pooling** - Reuse connections where possible
-3. **Enable caching** - Cache frequently accessed data with appropriate TTLs
-4. **Configure failover** - Use multiple endpoints for high availability
-5. **Monitor performance** - Enable performance logging in production
-
-### Environment-Specific Settings
-
-#### Development
-
-- Use testnet or regtest networks
-- Enable debug logging
-- Shorter timeouts for faster feedback
-- Disable strict validation for testing
-
-#### Staging
-
-- Mirror production configuration
-- Enable comprehensive logging
-- Use production-like endpoints
-- Enable all validation checks
-
-#### Production
-
-- Use mainnet network
-- Minimal logging (warn/error only)
-- Longer timeouts for reliability
-- Enable all security features
-- Use redundant endpoints
-
-This comprehensive configuration reference provides developers with all the tools needed to properly configure the BSV TypeScript SDK for any environment or use case.