@bsv/sdk 1.9.3 → 1.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/cjs/package.json +1 -1
  2. package/docs/fast-docs.png +0 -0
  3. package/docs/index.md +49 -44
  4. package/docs/swagger.png +0 -0
  5. package/package.json +1 -1
  6. package/docs/MARKDOWN_VALIDATION_GUIDE.md +0 -175
  7. package/docs/concepts/beef.md +0 -92
  8. package/docs/concepts/chain-tracking.md +0 -134
  9. package/docs/concepts/decentralized-identity.md +0 -221
  10. package/docs/concepts/fees.md +0 -249
  11. package/docs/concepts/identity-certificates.md +0 -307
  12. package/docs/concepts/index.md +0 -77
  13. package/docs/concepts/key-management.md +0 -185
  14. package/docs/concepts/script-templates.md +0 -176
  15. package/docs/concepts/sdk-philosophy.md +0 -80
  16. package/docs/concepts/signatures.md +0 -194
  17. package/docs/concepts/spv-verification.md +0 -118
  18. package/docs/concepts/transaction-encoding.md +0 -167
  19. package/docs/concepts/transaction-structure.md +0 -67
  20. package/docs/concepts/trust-model.md +0 -139
  21. package/docs/concepts/verification.md +0 -250
  22. package/docs/concepts/wallet-integration.md +0 -101
  23. package/docs/guides/development-wallet-setup.md +0 -374
  24. package/docs/guides/direct-transaction-creation.md +0 -147
  25. package/docs/guides/http-client-configuration.md +0 -488
  26. package/docs/guides/index.md +0 -138
  27. package/docs/guides/large-transactions.md +0 -448
  28. package/docs/guides/multisig-transactions.md +0 -792
  29. package/docs/guides/security-best-practices.md +0 -494
  30. package/docs/guides/transaction-batching.md +0 -132
  31. package/docs/guides/transaction-signing-methods.md +0 -419
  32. package/docs/reference/arc-config.md +0 -698
  33. package/docs/reference/brc-100.md +0 -33
  34. package/docs/reference/configuration.md +0 -835
  35. package/docs/reference/debugging.md +0 -705
  36. package/docs/reference/errors.md +0 -597
  37. package/docs/reference/index.md +0 -111
  38. package/docs/reference/network-config.md +0 -914
  39. package/docs/reference/op-codes.md +0 -325
  40. package/docs/reference/transaction-signatures.md +0 -95
  41. package/docs/tutorials/advanced-transaction.md +0 -572
  42. package/docs/tutorials/aes-encryption.md +0 -949
  43. package/docs/tutorials/authfetch-tutorial.md +0 -986
  44. package/docs/tutorials/ecdh-key-exchange.md +0 -549
  45. package/docs/tutorials/elliptic-curve-fundamentals.md +0 -606
  46. package/docs/tutorials/error-handling.md +0 -1216
  47. package/docs/tutorials/first-transaction-low-level.md +0 -205
  48. package/docs/tutorials/first-transaction.md +0 -275
  49. package/docs/tutorials/hashes-and-hmacs.md +0 -788
  50. package/docs/tutorials/identity-management.md +0 -729
  51. package/docs/tutorials/index.md +0 -219
  52. package/docs/tutorials/key-management.md +0 -538
  53. package/docs/tutorials/protowallet-development.md +0 -743
  54. package/docs/tutorials/script-construction.md +0 -690
  55. package/docs/tutorials/spv-merkle-proofs.md +0 -685
  56. package/docs/tutorials/testnet-transactions-low-level.md +0 -359
  57. package/docs/tutorials/transaction-broadcasting.md +0 -538
  58. package/docs/tutorials/transaction-types.md +0 -420
  59. package/docs/tutorials/type-42.md +0 -568
  60. package/docs/tutorials/uhrp-storage.md +0 -599
@@ -1,914 +0,0 @@
1
- # Network Configuration Reference
2
-
3
- Complete reference for configuring network settings, chain trackers, and blockchain connectivity in the BSV TypeScript SDK.
4
-
5
- ## Network Configuration Interface
6
-
7
- ### NetworkConfig
8
-
9
- ```typescript
10
- interface NetworkConfig {
11
- name: string
12
- network: 'mainnet' | 'testnet' | 'regtest'
13
- chainTracker: ChainTrackerConfig
14
- feeModel: FeeModelConfig
15
- limits: NetworkLimits
16
- endpoints: NetworkEndpoints
17
- security: NetworkSecurity
18
- monitoring: NetworkMonitoring
19
- }
20
- ```
21
-
22
- ### ChainTrackerConfig
23
-
24
- ```typescript
25
- interface ChainTrackerConfig {
26
- provider: 'whatsonchain' | 'blockchair' | 'custom'
27
- url?: string
28
- apiKey?: string
29
- timeout: number
30
- retries: number
31
- retryDelay: number
32
- fallbacks: ChainTrackerFallback[]
33
- caching: ChainTrackerCaching
34
- spv: SPVConfig
35
- }
36
-
37
- interface ChainTrackerFallback {
38
- provider: string
39
- url: string
40
- apiKey?: string
41
- priority: number
42
- healthCheck: boolean
43
- }
44
-
45
- interface ChainTrackerCaching {
46
- enabled: boolean
47
- ttl: number // Time to live in milliseconds
48
- maxSize: number // Maximum cache entries
49
- storage: 'memory' | 'localStorage' | 'custom'
50
- }
51
-
52
- interface SPVConfig {
53
- enabled: boolean
54
- maxDepth: number
55
- requiredConfirmations: number
56
- merkleProofValidation: boolean
57
- headerValidation: boolean
58
- }
59
- ```
60
-
61
- ### NetworkEndpoints
62
-
63
- ```typescript
64
- interface NetworkEndpoints {
65
- // Block and transaction data
66
- blocks: string
67
- transactions: string
68
- utxos: string
69
- balance: string
70
- history: string
71
-
72
- // Mempool and broadcasting
73
- mempool: string
74
- broadcast: string
75
- fees: string
76
-
77
- // Chain information
78
- chainInfo: string
79
- blockHeight: string
80
- difficulty: string
81
-
82
- // WebSocket endpoints
83
- websocket?: {
84
- blocks: string
85
- transactions: string
86
- mempool: string
87
- }
88
- }
89
- ```
90
-
91
- ### NetworkLimits
92
-
93
- ```typescript
94
- interface NetworkLimits {
95
- maxBlockSize: number
96
- maxTransactionSize: number
97
- maxScriptSize: number
98
- maxInputs: number
99
- maxOutputs: number
100
- maxSigOps: number
101
- dustThreshold: number
102
-
103
- // Rate limiting
104
- requestsPerSecond: number
105
- requestsPerMinute: number
106
- requestsPerHour: number
107
-
108
- // Connection limits
109
- maxConcurrentRequests: number
110
- maxRetries: number
111
- backoffMultiplier: number
112
- }
113
- ```
114
-
115
- ### NetworkSecurity
116
-
117
- ```typescript
118
- interface NetworkSecurity {
119
- ssl: {
120
- enabled: boolean
121
- validateCertificates: boolean
122
- allowSelfSigned: boolean
123
- }
124
-
125
- authentication: {
126
- required: boolean
127
- type: 'apiKey' | 'bearer' | 'basic'
128
- credentials: Record<string, string>
129
- }
130
-
131
- rateLimit: {
132
- enabled: boolean
133
- windowMs: number
134
- maxRequests: number
135
- skipSuccessfulRequests: boolean
136
- }
137
-
138
- cors: {
139
- enabled: boolean
140
- origins: string[]
141
- methods: string[]
142
- headers: string[]
143
- }
144
- }
145
- ```
146
-
147
- ## Predefined Network Configurations
148
-
149
- ### Mainnet Configuration
150
-
151
- ```typescript
152
- const MAINNET_CONFIG: NetworkConfig = {
153
- name: 'Bitcoin SV Mainnet',
154
- network: 'mainnet',
155
- chainTracker: {
156
- provider: 'whatsonchain',
157
- url: 'https://api.whatsonchain.com/v1/bsv/main',
158
- timeout: 30000,
159
- retries: 3,
160
- retryDelay: 1000,
161
- fallbacks: [
162
- {
163
- provider: 'blockchair',
164
- url: 'https://api.blockchair.com/bitcoin-sv',
165
- priority: 1,
166
- healthCheck: true
167
- }
168
- ],
169
- caching: {
170
- enabled: true,
171
- ttl: 300000, // 5 minutes
172
- maxSize: 1000,
173
- storage: 'memory'
174
- },
175
- spv: {
176
- enabled: true,
177
- maxDepth: 6,
178
- requiredConfirmations: 6,
179
- merkleProofValidation: true,
180
- headerValidation: true
181
- }
182
- },
183
- feeModel: {
184
- standard: 0.5, // satoshis per byte
185
- data: 0.25,
186
- priority: 1.0
187
- },
188
- limits: {
189
- maxBlockSize: 4000000000, // 4GB
190
- maxTransactionSize: 100000000, // 100MB
191
- maxScriptSize: 10000,
192
- maxInputs: 100000,
193
- maxOutputs: 100000,
194
- maxSigOps: 4000000,
195
- dustThreshold: 546,
196
- requestsPerSecond: 10,
197
- requestsPerMinute: 600,
198
- requestsPerHour: 36000,
199
- maxConcurrentRequests: 5,
200
- maxRetries: 3,
201
- backoffMultiplier: 2
202
- },
203
- endpoints: {
204
- blocks: '/block',
205
- transactions: '/tx',
206
- utxos: '/address/{address}/unspent',
207
- balance: '/address/{address}/balance',
208
- history: '/address/{address}/history',
209
- mempool: '/mempool',
210
- broadcast: '/tx/raw',
211
- fees: '/fees',
212
- chainInfo: '/chain/info',
213
- blockHeight: '/chain/info',
214
- difficulty: '/chain/info'
215
- },
216
- security: {
217
- ssl: {
218
- enabled: true,
219
- validateCertificates: true,
220
- allowSelfSigned: false
221
- },
222
- authentication: {
223
- required: false,
224
- type: 'apiKey',
225
- credentials: {}
226
- },
227
- rateLimit: {
228
- enabled: true,
229
- windowMs: 60000,
230
- maxRequests: 100,
231
- skipSuccessfulRequests: false
232
- },
233
- cors: {
234
- enabled: false,
235
- origins: [],
236
- methods: ['GET', 'POST'],
237
- headers: ['Content-Type', 'Authorization']
238
- }
239
- },
240
- monitoring: {
241
- enabled: true,
242
- healthCheck: {
243
- interval: 60000,
244
- timeout: 10000,
245
- endpoints: ['chainInfo', 'fees']
246
- },
247
- metrics: {
248
- enabled: true,
249
- collectInterval: 30000,
250
- retentionPeriod: 86400000 // 24 hours
251
- }
252
- }
253
- }
254
- ```
255
-
256
- ### Testnet Configuration
257
-
258
- ```typescript
259
- const TESTNET_CONFIG: NetworkConfig = {
260
- name: 'Bitcoin SV Testnet',
261
- network: 'testnet',
262
- chainTracker: {
263
- provider: 'whatsonchain',
264
- url: 'https://api.whatsonchain.com/v1/bsv/test',
265
- timeout: 30000,
266
- retries: 3,
267
- retryDelay: 1000,
268
- fallbacks: [],
269
- caching: {
270
- enabled: true,
271
- ttl: 300000,
272
- maxSize: 500,
273
- storage: 'memory'
274
- },
275
- spv: {
276
- enabled: true,
277
- maxDepth: 3, // Shorter for testnet
278
- requiredConfirmations: 3,
279
- merkleProofValidation: true,
280
- headerValidation: true
281
- }
282
- },
283
- feeModel: {
284
- standard: 0.1, // Lower fees for testnet
285
- data: 0.05,
286
- priority: 0.2
287
- },
288
- limits: {
289
- maxBlockSize: 4000000000,
290
- maxTransactionSize: 100000000,
291
- maxScriptSize: 10000,
292
- maxInputs: 100000,
293
- maxOutputs: 100000,
294
- maxSigOps: 4000000,
295
- dustThreshold: 546,
296
- requestsPerSecond: 20, // Higher limits for testing
297
- requestsPerMinute: 1200,
298
- requestsPerHour: 72000,
299
- maxConcurrentRequests: 10,
300
- maxRetries: 5,
301
- backoffMultiplier: 1.5
302
- },
303
- endpoints: {
304
- blocks: '/block',
305
- transactions: '/tx',
306
- utxos: '/address/{address}/unspent',
307
- balance: '/address/{address}/balance',
308
- history: '/address/{address}/history',
309
- mempool: '/mempool',
310
- broadcast: '/tx/raw',
311
- fees: '/fees',
312
- chainInfo: '/chain/info',
313
- blockHeight: '/chain/info',
314
- difficulty: '/chain/info'
315
- },
316
- security: {
317
- ssl: {
318
- enabled: true,
319
- validateCertificates: true,
320
- allowSelfSigned: false
321
- },
322
- authentication: {
323
- required: false,
324
- type: 'apiKey',
325
- credentials: {}
326
- },
327
- rateLimit: {
328
- enabled: false, // Disabled for testing
329
- windowMs: 60000,
330
- maxRequests: 1000,
331
- skipSuccessfulRequests: true
332
- },
333
- cors: {
334
- enabled: true, // Enabled for development
335
- origins: ['*'],
336
- methods: ['GET', 'POST', 'OPTIONS'],
337
- headers: ['*']
338
- }
339
- },
340
- monitoring: {
341
- enabled: true,
342
- healthCheck: {
343
- interval: 30000,
344
- timeout: 5000,
345
- endpoints: ['chainInfo']
346
- },
347
- metrics: {
348
- enabled: true,
349
- collectInterval: 60000,
350
- retentionPeriod: 43200000 // 12 hours
351
- }
352
- }
353
- }
354
- ```
355
-
356
- ### RegTest Configuration
357
-
358
- ```typescript
359
- const REGTEST_CONFIG: NetworkConfig = {
360
- name: 'Bitcoin SV RegTest',
361
- network: 'regtest',
362
- chainTracker: {
363
- provider: 'custom',
364
- url: 'http://localhost:18332',
365
- timeout: 5000,
366
- retries: 1,
367
- retryDelay: 500,
368
- fallbacks: [],
369
- caching: {
370
- enabled: false, // Disabled for local testing
371
- ttl: 0,
372
- maxSize: 0,
373
- storage: 'memory'
374
- },
375
- spv: {
376
- enabled: false, // Disabled for regtest
377
- maxDepth: 1,
378
- requiredConfirmations: 1,
379
- merkleProofValidation: false,
380
- headerValidation: false
381
- }
382
- },
383
- feeModel: {
384
- standard: 0.01, // Minimal fees for regtest
385
- data: 0.01,
386
- priority: 0.01
387
- },
388
- limits: {
389
- maxBlockSize: 4000000000,
390
- maxTransactionSize: 100000000,
391
- maxScriptSize: 10000,
392
- maxInputs: 100000,
393
- maxOutputs: 100000,
394
- maxSigOps: 4000000,
395
- dustThreshold: 546,
396
- requestsPerSecond: 1000, // No limits for local testing
397
- requestsPerMinute: 60000,
398
- requestsPerHour: 3600000,
399
- maxConcurrentRequests: 100,
400
- maxRetries: 1,
401
- backoffMultiplier: 1
402
- },
403
- endpoints: {
404
- blocks: '/rest/block',
405
- transactions: '/rest/tx',
406
- utxos: '/rest/getutxos',
407
- balance: '/rest/balance',
408
- history: '/rest/history',
409
- mempool: '/rest/mempool',
410
- broadcast: '/rest/tx',
411
- fees: '/rest/fees',
412
- chainInfo: '/rest/chaininfo',
413
- blockHeight: '/rest/chaininfo',
414
- difficulty: '/rest/chaininfo'
415
- },
416
- security: {
417
- ssl: {
418
- enabled: false, // HTTP for local development
419
- validateCertificates: false,
420
- allowSelfSigned: true
421
- },
422
- authentication: {
423
- required: true,
424
- type: 'basic',
425
- credentials: {
426
- username: 'rpcuser',
427
- password: 'rpcpassword'
428
- }
429
- },
430
- rateLimit: {
431
- enabled: false,
432
- windowMs: 0,
433
- maxRequests: 0,
434
- skipSuccessfulRequests: true
435
- },
436
- cors: {
437
- enabled: true,
438
- origins: ['*'],
439
- methods: ['*'],
440
- headers: ['*']
441
- }
442
- },
443
- monitoring: {
444
- enabled: false, // Disabled for local testing
445
- healthCheck: {
446
- interval: 0,
447
- timeout: 0,
448
- endpoints: []
449
- },
450
- metrics: {
451
- enabled: false,
452
- collectInterval: 0,
453
- retentionPeriod: 0
454
- }
455
- }
456
- }
457
- ```
458
-
459
- ## Network Configuration Builder
460
-
461
- ### NetworkConfigBuilder Class
462
-
463
- ```typescript
464
- class NetworkConfigBuilder {
465
- private config: Partial<NetworkConfig> = {}
466
-
467
- name(name: string): NetworkConfigBuilder {
468
- this.config.name = name
469
- return this
470
- }
471
-
472
- network(network: 'mainnet' | 'testnet' | 'regtest'): NetworkConfigBuilder {
473
- this.config.network = network
474
- return this
475
- }
476
-
477
- chainTracker(config: Partial<ChainTrackerConfig>): NetworkConfigBuilder {
478
- this.config.chainTracker = { ...this.config.chainTracker, ...config }
479
- return this
480
- }
481
-
482
- feeModel(config: FeeModelConfig): NetworkConfigBuilder {
483
- this.config.feeModel = config
484
- return this
485
- }
486
-
487
- limits(config: Partial<NetworkLimits>): NetworkConfigBuilder {
488
- this.config.limits = { ...this.config.limits, ...config }
489
- return this
490
- }
491
-
492
- endpoints(config: Partial<NetworkEndpoints>): NetworkConfigBuilder {
493
- this.config.endpoints = { ...this.config.endpoints, ...config }
494
- return this
495
- }
496
-
497
- security(config: Partial<NetworkSecurity>): NetworkConfigBuilder {
498
- this.config.security = { ...this.config.security, ...config }
499
- return this
500
- }
501
-
502
- monitoring(config: Partial<NetworkMonitoring>): NetworkConfigBuilder {
503
- this.config.monitoring = { ...this.config.monitoring, ...config }
504
- return this
505
- }
506
-
507
- build(): NetworkConfig {
508
- // Apply defaults based on network type
509
- const defaults = this.getNetworkDefaults(this.config.network || 'mainnet')
510
-
511
- return {
512
- ...defaults,
513
- ...this.config,
514
- chainTracker: { ...defaults.chainTracker, ...this.config.chainTracker },
515
- limits: { ...defaults.limits, ...this.config.limits },
516
- endpoints: { ...defaults.endpoints, ...this.config.endpoints },
517
- security: { ...defaults.security, ...this.config.security },
518
- monitoring: { ...defaults.monitoring, ...this.config.monitoring }
519
- } as NetworkConfig
520
- }
521
-
522
- private getNetworkDefaults(network: string): NetworkConfig {
523
- switch (network) {
524
- case 'mainnet':
525
- return MAINNET_CONFIG
526
- case 'testnet':
527
- return TESTNET_CONFIG
528
- case 'regtest':
529
- return REGTEST_CONFIG
530
- default:
531
- return MAINNET_CONFIG
532
- }
533
- }
534
- }
535
- ```
536
-
537
- ### Usage Examples
538
-
539
- ```typescript
540
- // Basic network configuration
541
- const basicNetwork = new NetworkConfigBuilder()
542
- .name('Custom Mainnet')
543
- .network('mainnet')
544
- .chainTracker({
545
- provider: 'whatsonchain',
546
- timeout: 15000
547
- })
548
- .build()
549
-
550
- // Custom network with fallbacks
551
- const robustNetwork = new NetworkConfigBuilder()
552
- .name('Production Mainnet')
553
- .network('mainnet')
554
- .chainTracker({
555
- provider: 'whatsonchain',
556
- url: 'https://api.whatsonchain.com/v1/bsv/main',
557
- timeout: 30000,
558
- retries: 3,
559
- fallbacks: [
560
- {
561
- provider: 'blockchair',
562
- url: 'https://api.blockchair.com/bitcoin-sv',
563
- priority: 1,
564
- healthCheck: true
565
- },
566
- {
567
- provider: 'custom',
568
- url: 'https://custom-api.example.com',
569
- apiKey: 'your-api-key',
570
- priority: 2,
571
- healthCheck: true
572
- }
573
- ]
574
- })
575
- .security({
576
- ssl: { enabled: true, validateCertificates: true },
577
- rateLimit: { enabled: true, windowMs: 60000, maxRequests: 100 }
578
- })
579
- .monitoring({
580
- enabled: true,
581
- healthCheck: { interval: 30000, timeout: 5000 }
582
- })
583
- .build()
584
- ```
585
-
586
- ## Chain Tracker Management
587
-
588
- ### ChainTracker Interface
589
-
590
- ```typescript
591
- interface ChainTracker {
592
- config: ChainTrackerConfig
593
-
594
- // Block operations
595
- getBlock(hash: string): Promise<Block>
596
- getBlockHeader(hash: string): Promise<BlockHeader>
597
- getBlockHeight(): Promise<number>
598
-
599
- // Transaction operations
600
- getTransaction(txid: string): Promise<Transaction>
601
- getTransactionStatus(txid: string): Promise<TransactionStatus>
602
- getRawTransaction(txid: string): Promise<string>
603
-
604
- // UTXO operations
605
- getUTXOs(address: string): Promise<UTXO[]>
606
- getBalance(address: string): Promise<number>
607
- getHistory(address: string): Promise<TransactionHistory[]>
608
-
609
- // Broadcasting
610
- broadcast(rawTx: string): Promise<BroadcastResult>
611
-
612
- // Mempool
613
- getMempoolInfo(): Promise<MempoolInfo>
614
- getMempoolTransactions(): Promise<string[]>
615
-
616
- // Health and status
617
- getHealth(): Promise<HealthStatus>
618
- isConnected(): boolean
619
- }
620
- ```
621
-
622
- ### Multi-Provider Chain Tracker
623
-
624
- ```typescript
625
- class MultiProviderChainTracker implements ChainTracker {
626
- private providers: ChainTracker[]
627
- private currentProvider = 0
628
- private healthStatus = new Map<string, boolean>()
629
-
630
- constructor(
631
- public config: ChainTrackerConfig,
632
- providers: ChainTracker[]
633
- ) {
634
- this.providers = providers
635
- this.startHealthChecks()
636
- }
637
-
638
- async getTransaction(txid: string): Promise<Transaction> {
639
- const provider = this.selectProvider()
640
-
641
- try {
642
- return await provider.getTransaction(txid)
643
- } catch (error) {
644
- this.markProviderUnhealthy(provider)
645
-
646
- if (this.hasHealthyProviders()) {
647
- return this.getTransaction(txid) // Retry with different provider
648
- }
649
-
650
- throw error
651
- }
652
- }
653
-
654
- async broadcast(rawTx: string): Promise<BroadcastResult> {
655
- const errors: Error[] = []
656
-
657
- // Try all healthy providers for broadcasting
658
- for (const provider of this.getHealthyProviders()) {
659
- try {
660
- return await provider.broadcast(rawTx)
661
- } catch (error) {
662
- errors.push(error as Error)
663
- this.markProviderUnhealthy(provider)
664
- }
665
- }
666
-
667
- throw new Error(`Broadcast failed on all providers: ${errors.map(e => e.message).join(', ')}`)
668
- }
669
-
670
- private selectProvider(): ChainTracker {
671
- const healthyProviders = this.getHealthyProviders()
672
-
673
- if (healthyProviders.length === 0) {
674
- return this.providers[0] // Fallback to first provider
675
- }
676
-
677
- // Round-robin selection
678
- const provider = healthyProviders[this.currentProvider % healthyProviders.length]
679
- this.currentProvider++
680
- return provider
681
- }
682
-
683
- private getHealthyProviders(): ChainTracker[] {
684
- return this.providers.filter(provider =>
685
- this.healthStatus.get(this.getProviderId(provider)) !== false
686
- )
687
- }
688
-
689
- private markProviderUnhealthy(provider: ChainTracker): void {
690
- this.healthStatus.set(this.getProviderId(provider), false)
691
- }
692
-
693
- private getProviderId(provider: ChainTracker): string {
694
- return provider.config.url || provider.config.provider
695
- }
696
-
697
- private startHealthChecks(): void {
698
- setInterval(async () => {
699
- for (const provider of this.providers) {
700
- try {
701
- await provider.getHealth()
702
- this.healthStatus.set(this.getProviderId(provider), true)
703
- } catch (error) {
704
- this.healthStatus.set(this.getProviderId(provider), false)
705
- }
706
- }
707
- }, 60000) // Check every minute
708
- }
709
-
710
- // Implement other ChainTracker methods...
711
- async getBlock(hash: string): Promise<Block> {
712
- const provider = this.selectProvider()
713
- return provider.getBlock(hash)
714
- }
715
-
716
- async getUTXOs(address: string): Promise<UTXO[]> {
717
- const provider = this.selectProvider()
718
- return provider.getUTXOs(address)
719
- }
720
-
721
- async getHealth(): Promise<HealthStatus> {
722
- const healthyCount = this.getHealthyProviders().length
723
- const totalCount = this.providers.length
724
-
725
- return {
726
- status: healthyCount > 0 ? 'healthy' : 'unhealthy',
727
- providers: {
728
- healthy: healthyCount,
729
- total: totalCount,
730
- percentage: (healthyCount / totalCount) * 100
731
- },
732
- timestamp: Date.now()
733
- }
734
- }
735
-
736
- isConnected(): boolean {
737
- return this.getHealthyProviders().length > 0
738
- }
739
- }
740
- ```
741
-
742
- ## Environment-Based Network Configuration
743
-
744
- ### Environment Configuration Loader
745
-
746
- ```typescript
747
- class NetworkEnvironmentConfig {
748
- static fromEnvironment(): NetworkConfig {
749
- const network = (process.env.BSV_NETWORK || 'mainnet') as 'mainnet' | 'testnet' | 'regtest'
750
- const baseConfig = NetworkEnvironmentConfig.getBaseConfig(network)
751
-
752
- // Override with environment variables
753
- if (process.env.BSV_CHAIN_TRACKER_URL) {
754
- baseConfig.chainTracker.url = process.env.BSV_CHAIN_TRACKER_URL
755
- }
756
-
757
- if (process.env.BSV_CHAIN_TRACKER_API_KEY) {
758
- baseConfig.chainTracker.apiKey = process.env.BSV_CHAIN_TRACKER_API_KEY
759
- }
760
-
761
- if (process.env.BSV_CHAIN_TRACKER_TIMEOUT) {
762
- baseConfig.chainTracker.timeout = parseInt(process.env.BSV_CHAIN_TRACKER_TIMEOUT)
763
- }
764
-
765
- // Fee model overrides
766
- if (process.env.BSV_FEE_STANDARD) {
767
- baseConfig.feeModel.standard = parseFloat(process.env.BSV_FEE_STANDARD)
768
- }
769
-
770
- if (process.env.BSV_FEE_DATA) {
771
- baseConfig.feeModel.data = parseFloat(process.env.BSV_FEE_DATA)
772
- }
773
-
774
- // Security overrides
775
- if (process.env.BSV_SSL_ENABLED) {
776
- baseConfig.security.ssl.enabled = process.env.BSV_SSL_ENABLED === 'true'
777
- }
778
-
779
- if (process.env.BSV_RATE_LIMIT_ENABLED) {
780
- baseConfig.security.rateLimit.enabled = process.env.BSV_RATE_LIMIT_ENABLED === 'true'
781
- }
782
-
783
- return baseConfig
784
- }
785
-
786
- private static getBaseConfig(network: string): NetworkConfig {
787
- switch (network) {
788
- case 'mainnet':
789
- return { ...MAINNET_CONFIG }
790
- case 'testnet':
791
- return { ...TESTNET_CONFIG }
792
- case 'regtest':
793
- return { ...REGTEST_CONFIG }
794
- default:
795
- return { ...MAINNET_CONFIG }
796
- }
797
- }
798
-
799
- static validate(config: NetworkConfig): void {
800
- if (!config.name) {
801
- throw new Error('Network name is required')
802
- }
803
-
804
- if (!config.network) {
805
- throw new Error('Network type is required')
806
- }
807
-
808
- if (!config.chainTracker.url && config.chainTracker.provider === 'custom') {
809
- throw new Error('Chain tracker URL is required for custom provider')
810
- }
811
-
812
- if (config.chainTracker.timeout < 1000) {
813
- throw new Error('Chain tracker timeout must be at least 1000ms')
814
- }
815
-
816
- if (config.limits.maxTransactionSize > config.limits.maxBlockSize) {
817
- throw new Error('Max transaction size cannot exceed max block size')
818
- }
819
-
820
- if (config.security.ssl.enabled && !config.chainTracker.url?.startsWith('https')) {
821
- console.warn('SSL is enabled but chain tracker URL is not HTTPS')
822
- }
823
- }
824
- }
825
- ```
826
-
827
- ## Network Configuration Best Practices
828
-
829
- ### Production Configuration
830
-
831
- ```typescript
832
- const productionConfig = new NetworkConfigBuilder()
833
- .name('Production Mainnet')
834
- .network('mainnet')
835
- .chainTracker({
836
- provider: 'whatsonchain',
837
- timeout: 30000,
838
- retries: 3,
839
- retryDelay: 2000,
840
- fallbacks: [
841
- {
842
- provider: 'blockchair',
843
- url: 'https://api.blockchair.com/bitcoin-sv',
844
- priority: 1,
845
- healthCheck: true
846
- }
847
- ],
848
- caching: {
849
- enabled: true,
850
- ttl: 300000, // 5 minutes
851
- maxSize: 10000,
852
- storage: 'memory'
853
- }
854
- })
855
- .security({
856
- ssl: {
857
- enabled: true,
858
- validateCertificates: true,
859
- allowSelfSigned: false
860
- },
861
- rateLimit: {
862
- enabled: true,
863
- windowMs: 60000,
864
- maxRequests: 100
865
- }
866
- })
867
- .monitoring({
868
- enabled: true,
869
- healthCheck: {
870
- interval: 30000,
871
- timeout: 10000,
872
- endpoints: ['chainInfo', 'fees']
873
- },
874
- metrics: {
875
- enabled: true,
876
- collectInterval: 60000,
877
- retentionPeriod: 86400000
878
- }
879
- })
880
- .build()
881
- ```
882
-
883
- ### Development Configuration
884
-
885
- ```typescript
886
- const developmentConfig = new NetworkConfigBuilder()
887
- .name('Development Testnet')
888
- .network('testnet')
889
- .chainTracker({
890
- provider: 'whatsonchain',
891
- timeout: 15000,
892
- retries: 5,
893
- caching: {
894
- enabled: false // Disable caching for development
895
- }
896
- })
897
- .security({
898
- ssl: { enabled: true },
899
- rateLimit: { enabled: false }, // Disable rate limiting for development
900
- cors: {
901
- enabled: true,
902
- origins: ['*'],
903
- methods: ['*'],
904
- headers: ['*']
905
- }
906
- })
907
- .monitoring({
908
- enabled: true,
909
- healthCheck: { interval: 10000, timeout: 5000 }
910
- })
911
- .build()
912
- ```
913
-
914
- This comprehensive network configuration reference provides developers with all the tools needed to effectively configure and manage network connectivity in their BSV TypeScript SDK applications.