ts-sdk

Configuration Reference

Complete reference for SDK configuration options, interfaces, and setup patterns in the BSV TypeScript SDK.

Core Configuration Interface

interface SDKConfig {
  network: NetworkType
  arc: ARCConfig
  fees: FeeConfig
  security: SecurityConfig
  wallet: WalletConfig
  chainTracker: ChainTrackerConfig
  logging: LoggingConfig
}

Network Configuration

NetworkType

type NetworkType = 'mainnet' | 'testnet' | 'regtest'

Network Parameters

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

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

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

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

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

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

interface ARCAuth {
  type: 'bearer' | 'api-key' | 'none'
  credentials: {
    token?: string
    apiKey?: string
    secret?: string
  }
}

Fee Configuration

FeeConfig Interface

interface FeeConfig {
  strategy: FeeStrategy
  rates: FeeRates
  limits: FeeLimits
  estimation: FeeEstimationConfig
}

Fee Strategy Types

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

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

interface FeeEstimationConfig {
  enabled: boolean
  source: 'arc' | 'chainTracker' | 'static'
  fallbackRate: number
  updateInterval: number
  cacheTimeout: number
}

Security Configuration

SecurityConfig Interface

interface SecurityConfig {
  keyGeneration: KeyGenerationConfig
  encryption: EncryptionConfig
  validation: ValidationConfig
  randomness: RandomnessConfig
}

Key Generation Configuration

interface KeyGenerationConfig {
  source: 'secure-random' | 'deterministic'
  entropy: {
    minBits: number
    sources: EntropySource[]
  }
  derivation: {
    hardened: boolean
    maxDepth: number
  }
}

type EntropySource = 'crypto' | 'mouse' | 'keyboard' | 'timing'

Encryption Configuration

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

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

interface WalletConfig {
  substrate: WalletSubstrate
  connection: ConnectionConfig
  authentication: AuthConfig
  permissions: PermissionConfig
}

Wallet Substrate Types

type WalletSubstrate = 
  | 'auto'
  | 'Cicada'
  | 'XDM'
  | 'window.CWI'
  | 'json-api'
  | 'react-native'
  | WalletInterface

Connection Configuration

interface ConnectionConfig {
  timeout: number
  retryAttempts: number
  retryDelay: number
  keepAlive: boolean
  autoReconnect: boolean
}

Authentication Configuration

interface AuthConfig {
  required: boolean
  timeout: number
  cacheCredentials: boolean
  refreshInterval: number
  originator: string
}

Default Wallet Configuration

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

interface ChainTrackerConfig {
  primary: ChainTrackerEndpoint
  fallbacks: ChainTrackerEndpoint[]
  failover: FailoverConfig
  caching: CacheConfig
}

Chain Tracker Endpoint

interface ChainTrackerEndpoint {
  url: string
  apiKey?: string
  timeout: number
  rateLimiting: RateLimitConfig
  capabilities: TrackerCapability[]
}

type TrackerCapability = 
  | 'getHeight'
  | 'getHeader'
  | 'getTransaction'
  | 'getMerkleProof'
  | 'broadcast'

Failover Configuration

interface FailoverConfig {
  enabled: boolean
  maxFailures: number
  failureWindow: number
  recoveryTime: number
  healthCheck: {
    enabled: boolean
    interval: number
    timeout: number
  }
}

Default Chain Tracker Configuration

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

interface LoggingConfig {
  level: LogLevel
  outputs: LogOutput[]
  format: LogFormat
  filters: LogFilter[]
  performance: PerformanceLoggingConfig
}

Log Levels and Outputs

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

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

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

import { SDKConfigBuilder } from '@bsv/sdk'

const config = new SDKConfigBuilder()
  .network('testnet')
  .fees({ strategy: 'priority' })
  .build()

Production Configuration

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

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

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

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.

This site is open source. Improve this page.