Complete reference for SDK configuration options, interfaces, and setup patterns in the BSV TypeScript SDK.
interface SDKConfig {
network: NetworkType
arc: ARCConfig
fees: FeeConfig
security: SecurityConfig
wallet: WalletConfig
chainTracker: ChainTrackerConfig
logging: LoggingConfig
}
type NetworkType = 'mainnet' | 'testnet' | 'regtest'
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[]
}
}
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']
}
}
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']
}
}
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']
}
}
interface ARCConfig {
apiUrl: string
apiKey?: string
timeout: number
retryAttempts: number
retryDelay: number
rateLimiting: {
requestsPerSecond: number
burstLimit: number
}
endpoints: {
submit: string
status: string
policy: string
}
}
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'
}
}
interface ARCAuth {
type: 'bearer' | 'api-key' | 'none'
credentials: {
token?: string
apiKey?: string
secret?: string
}
}
interface FeeConfig {
strategy: FeeStrategy
rates: FeeRates
limits: FeeLimits
estimation: FeeEstimationConfig
}
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
}
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
}
}
interface FeeEstimationConfig {
enabled: boolean
source: 'arc' | 'chainTracker' | 'static'
fallbackRate: number
updateInterval: number
cacheTimeout: number
}
interface SecurityConfig {
keyGeneration: KeyGenerationConfig
encryption: EncryptionConfig
validation: ValidationConfig
randomness: RandomnessConfig
}
interface KeyGenerationConfig {
source: 'secure-random' | 'deterministic'
entropy: {
minBits: number
sources: EntropySource[]
}
derivation: {
hardened: boolean
maxDepth: number
}
}
type EntropySource = 'crypto' | 'mouse' | 'keyboard' | 'timing'
interface EncryptionConfig {
algorithm: 'AES-GCM' | 'AES-CBC'
keySize: 128 | 256
ivSize: number
tagSize: number
keyDerivation: {
algorithm: 'PBKDF2' | 'scrypt'
iterations: number
saltSize: number
}
}
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
}
}
interface WalletConfig {
substrate: WalletSubstrate
connection: ConnectionConfig
authentication: AuthConfig
permissions: PermissionConfig
}
type WalletSubstrate =
| 'auto'
| 'Cicada'
| 'XDM'
| 'window.CWI'
| 'json-api'
| 'react-native'
| WalletInterface
interface ConnectionConfig {
timeout: number
retryAttempts: number
retryDelay: number
keepAlive: boolean
autoReconnect: boolean
}
interface AuthConfig {
required: boolean
timeout: number
cacheCredentials: boolean
refreshInterval: number
originator: string
}
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
}
}
interface ChainTrackerConfig {
primary: ChainTrackerEndpoint
fallbacks: ChainTrackerEndpoint[]
failover: FailoverConfig
caching: CacheConfig
}
interface ChainTrackerEndpoint {
url: string
apiKey?: string
timeout: number
rateLimiting: RateLimitConfig
capabilities: TrackerCapability[]
}
type TrackerCapability =
| 'getHeight'
| 'getHeader'
| 'getTransaction'
| 'getMerkleProof'
| 'broadcast'
interface FailoverConfig {
enabled: boolean
maxFailures: number
failureWindow: number
recoveryTime: number
healthCheck: {
enabled: boolean
interval: number
timeout: number
}
}
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'
}
}
interface LoggingConfig {
level: LogLevel
outputs: LogOutput[]
format: LogFormat
filters: LogFilter[]
performance: PerformanceLoggingConfig
}
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
}
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
}
}
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
}
}
}
import { SDKConfigBuilder } from '@bsv/sdk'
const config = new SDKConfigBuilder()
.network('testnet')
.fees({ strategy: 'priority' })
.build()
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()
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()
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()
}
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
}
This comprehensive configuration reference provides developers with all the tools needed to properly configure the BSV TypeScript SDK for any environment or use case.