@bsv/overlay-express 2.2.1 → 2.3.1

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 (53) hide show
  1. package/README.md +33 -0
  2. package/dist/cjs/mod.js +10 -1
  3. package/dist/cjs/mod.js.map +1 -1
  4. package/dist/cjs/package.json +12 -11
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  6. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  8. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  9. package/dist/cjs/src/OverlayExpress.js +375 -96
  10. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  11. package/dist/cjs/src/OverlayMonitor.js +464 -0
  12. package/dist/cjs/src/OverlayMonitor.js.map +1 -0
  13. package/dist/cjs/src/ReorgStream.js +193 -0
  14. package/dist/cjs/src/ReorgStream.js.map +1 -0
  15. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  16. package/dist/esm/mod.js +3 -0
  17. package/dist/esm/mod.js.map +1 -1
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  19. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  20. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  21. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  22. package/dist/esm/src/OverlayExpress.js +375 -94
  23. package/dist/esm/src/OverlayExpress.js.map +1 -1
  24. package/dist/esm/src/OverlayMonitor.js +458 -0
  25. package/dist/esm/src/OverlayMonitor.js.map +1 -0
  26. package/dist/esm/src/ReorgStream.js +190 -0
  27. package/dist/esm/src/ReorgStream.js.map +1 -0
  28. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  29. package/dist/types/mod.d.ts +4 -1
  30. package/dist/types/mod.d.ts.map +1 -1
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  32. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  34. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  35. package/dist/types/src/OverlayExpress.d.ts +82 -4
  36. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  37. package/dist/types/src/OverlayMonitor.d.ts +169 -0
  38. package/dist/types/src/OverlayMonitor.d.ts.map +1 -0
  39. package/dist/types/src/ReorgStream.d.ts +74 -0
  40. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  41. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  42. package/mod.ts +20 -1
  43. package/package.json +12 -11
  44. package/src/BanAwareDiscoveryStorage.ts +91 -0
  45. package/src/BanAwareTopicManager.ts +87 -0
  46. package/src/OverlayExpress.ts +461 -102
  47. package/src/OverlayMonitor.ts +657 -0
  48. package/src/ReorgStream.ts +221 -0
  49. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  50. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  51. package/src/__tests__/OverlayExpress.test.ts +86 -1
  52. package/src/__tests__/OverlayMonitor.test.ts +181 -0
  53. package/src/__tests__/ReorgStream.test.ts +66 -0
@@ -0,0 +1,657 @@
1
+ import { Beef, Transaction } from '@bsv/sdk'
2
+
3
+ export interface OverlayMonitorLogger {
4
+ log: (...args: any[]) => void
5
+ warn: (...args: any[]) => void
6
+ error: (...args: any[]) => void
7
+ }
8
+
9
+ export interface OverlayLookupProbe {
10
+ name?: string
11
+ service: string
12
+ query: unknown
13
+ maxOutputs?: number
14
+ }
15
+
16
+ export interface OverlayAnchorProbe {
17
+ name?: string
18
+ topic: string
19
+ expectedTac?: string
20
+ expectedBlockHeight?: number
21
+ currentHeight?: number
22
+ maxTipLagBlocks?: number
23
+ }
24
+
25
+ export interface OverlayMonitorTarget {
26
+ name: string
27
+ baseUrl: string
28
+ probes: OverlayLookupProbe[]
29
+ anchorProbes?: OverlayAnchorProbe[]
30
+ headers?: Record<string, string>
31
+ }
32
+
33
+ export interface OverlayMonitorThresholds {
34
+ responseBytes?: number
35
+ beefBytes?: number
36
+ txsWithoutProof?: number
37
+ requireSubjectProof?: boolean
38
+ anchorTipLagBlocks?: number
39
+ expiredUnprovenCount?: number
40
+ }
41
+
42
+ export interface OverlayMonitorConfig {
43
+ targets: OverlayMonitorTarget[]
44
+ thresholds?: OverlayMonitorThresholds
45
+ intervalMs?: number
46
+ /** Per-probe request timeout in milliseconds. Defaults to 30000. */
47
+ timeoutMs?: number
48
+ fetchImpl?: typeof fetch
49
+ logger?: OverlayMonitorLogger
50
+ onReport?: (report: OverlayMonitorReport) => Promise<void> | void
51
+ now?: () => Date
52
+ }
53
+
54
+ export interface OverlayMonitorWarning {
55
+ code: 'response-bytes' | 'beef-bytes' | 'txs-without-proof' | 'subject-proof-missing' | 'anchor-tip-mismatch' | 'anchor-stale-height' | 'expired-unproven-state'
56
+ message: string
57
+ value: number | boolean
58
+ threshold?: number | boolean
59
+ outputIndex?: number
60
+ txid?: string
61
+ }
62
+
63
+ export interface OverlayLookupOutputSummary {
64
+ outputIndex: number
65
+ txid?: string
66
+ beefBytes: number
67
+ txCount?: number
68
+ proofCount?: number
69
+ txsWithoutProof?: number
70
+ subjectHasProof?: boolean
71
+ subjectRawTxBytes?: number
72
+ currentToSubjectRawRatio?: number
73
+ contextBytes?: number
74
+ error?: string
75
+ }
76
+
77
+ export interface OverlayLookupProbeResult {
78
+ target: string
79
+ url: string
80
+ probe: string
81
+ service: string
82
+ status: number
83
+ ok: boolean
84
+ responseBytes: number
85
+ outputCount: number
86
+ analyzedOutputCount: number
87
+ outputs: OverlayLookupOutputSummary[]
88
+ warnings: OverlayMonitorWarning[]
89
+ durationMs: number
90
+ error?: string
91
+ }
92
+
93
+ export interface OverlayAnchorProbeResult {
94
+ target: string
95
+ url: string
96
+ probe: string
97
+ topic: string
98
+ status: number
99
+ ok: boolean
100
+ responseBytes: number
101
+ blockHeight?: number
102
+ tac?: string
103
+ warnings: OverlayMonitorWarning[]
104
+ durationMs: number
105
+ error?: string
106
+ }
107
+
108
+ export interface OverlayMonitorReport {
109
+ startedAt: Date
110
+ completedAt: Date
111
+ durationMs: number
112
+ results: OverlayLookupProbeResult[]
113
+ anchorResults: OverlayAnchorProbeResult[]
114
+ summary: {
115
+ targetCount: number
116
+ probeCount: number
117
+ anchorProbeCount: number
118
+ failedProbeCount: number
119
+ responseBytes: number
120
+ outputCount: number
121
+ analyzedOutputCount: number
122
+ outputsMissingSubjectProof: number
123
+ warningCount: number
124
+ }
125
+ }
126
+
127
+ interface AnalyzeOptions {
128
+ target: string
129
+ url: string
130
+ probe: string
131
+ service: string
132
+ status: number
133
+ ok: boolean
134
+ responseBody: unknown
135
+ responseBytes: number
136
+ durationMs: number
137
+ thresholds?: OverlayMonitorThresholds
138
+ maxOutputs?: number
139
+ error?: string
140
+ }
141
+
142
+ const defaultThresholds: Required<OverlayMonitorThresholds> = {
143
+ responseBytes: 1024 * 1024,
144
+ beefBytes: 64 * 1024,
145
+ txsWithoutProof: 1,
146
+ requireSubjectProof: true,
147
+ anchorTipLagBlocks: 6,
148
+ expiredUnprovenCount: 0
149
+ }
150
+
151
+ /**
152
+ * OverlayMonitor runs generic Overlay Express /lookup probes and reports response
153
+ * size plus BEEF proof shape. It is intended for long-running monitor workers or
154
+ * scheduled jobs, analogous to a storage monitor but scoped to overlay health.
155
+ */
156
+ export class OverlayMonitor {
157
+ private readonly targets: OverlayMonitorTarget[]
158
+ private readonly thresholds: Required<OverlayMonitorThresholds>
159
+ private readonly fetchImpl: typeof fetch
160
+ private readonly logger: OverlayMonitorLogger
161
+ private readonly onReport?: (report: OverlayMonitorReport) => Promise<void> | void
162
+ private readonly now: () => Date
163
+ private readonly intervalMs?: number
164
+ private readonly timeoutMs: number
165
+ private timer?: ReturnType<typeof setInterval>
166
+ private running = false
167
+
168
+ constructor (config: OverlayMonitorConfig) {
169
+ this.targets = config.targets
170
+ this.thresholds = { ...defaultThresholds, ...config.thresholds }
171
+ // Bind to globalThis so calling through this.fetchImpl does not rebind `this`
172
+ // (browser fetch throws "Illegal invocation" when invoked as a method).
173
+ this.fetchImpl = config.fetchImpl ?? fetch.bind(globalThis)
174
+ this.logger = config.logger ?? console
175
+ this.onReport = config.onReport
176
+ this.now = config.now ?? (() => new Date())
177
+ this.intervalMs = config.intervalMs
178
+ this.timeoutMs = config.timeoutMs ?? 30000
179
+ }
180
+
181
+ async runOnce (): Promise<OverlayMonitorReport> {
182
+ const startedAt = this.now()
183
+ const results: OverlayLookupProbeResult[] = []
184
+ const anchorResults: OverlayAnchorProbeResult[] = []
185
+
186
+ for (const target of this.targets) {
187
+ for (const probe of target.probes) {
188
+ results.push(await this.runProbe(target, probe))
189
+ }
190
+ for (const probe of target.anchorProbes ?? []) {
191
+ anchorResults.push(await this.runAnchorProbe(target, probe))
192
+ }
193
+ }
194
+
195
+ const completedAt = this.now()
196
+ const report: OverlayMonitorReport = {
197
+ startedAt,
198
+ completedAt,
199
+ durationMs: completedAt.getTime() - startedAt.getTime(),
200
+ results,
201
+ anchorResults,
202
+ summary: summarize(results, anchorResults, this.targets.length)
203
+ }
204
+
205
+ await this.onReport?.(report)
206
+ return report
207
+ }
208
+
209
+ start (): void {
210
+ if (this.intervalMs === undefined) {
211
+ throw new Error('intervalMs is required to start OverlayMonitor')
212
+ }
213
+ if (this.timer !== undefined) return
214
+
215
+ this.timer = setInterval(() => {
216
+ if (this.running) return
217
+ this.running = true
218
+ this.runOnce()
219
+ .catch(error => {
220
+ this.logger.error('OverlayMonitor run failed', error)
221
+ })
222
+ .finally(() => {
223
+ this.running = false
224
+ })
225
+ }, this.intervalMs)
226
+ }
227
+
228
+ stop (): void {
229
+ if (this.timer !== undefined) {
230
+ clearInterval(this.timer)
231
+ this.timer = undefined
232
+ }
233
+ }
234
+
235
+ private async runProbe (target: OverlayMonitorTarget, probe: OverlayLookupProbe): Promise<OverlayLookupProbeResult> {
236
+ const startedAt = this.now()
237
+ const url = new URL('/lookup', target.baseUrl).toString()
238
+ const controller = new AbortController()
239
+ const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
240
+
241
+ try {
242
+ const response = await this.fetchImpl(url, {
243
+ method: 'POST',
244
+ headers: {
245
+ Accept: 'application/json',
246
+ 'Content-Type': 'application/json',
247
+ ...target.headers
248
+ },
249
+ body: JSON.stringify({ service: probe.service, query: probe.query }),
250
+ signal: controller.signal
251
+ })
252
+ const text = await response.text()
253
+ const responseBytes = new TextEncoder().encode(text).length
254
+ const completedAt = this.now()
255
+
256
+ let body: unknown
257
+ try {
258
+ body = text.length === 0 ? {} : JSON.parse(text)
259
+ } catch (error) {
260
+ return makeFailedResult({
261
+ target,
262
+ probe,
263
+ url,
264
+ status: response.status,
265
+ ok: response.ok,
266
+ responseBytes,
267
+ durationMs: completedAt.getTime() - startedAt.getTime(),
268
+ error: error instanceof Error ? error.message : 'Invalid JSON response'
269
+ })
270
+ }
271
+
272
+ return analyzeOverlayLookupResponse({
273
+ target: target.name,
274
+ url,
275
+ probe: probe.name ?? probe.service,
276
+ service: probe.service,
277
+ status: response.status,
278
+ ok: response.ok,
279
+ responseBody: body,
280
+ responseBytes,
281
+ durationMs: completedAt.getTime() - startedAt.getTime(),
282
+ thresholds: this.thresholds,
283
+ maxOutputs: probe.maxOutputs
284
+ })
285
+ } catch (error) {
286
+ const completedAt = this.now()
287
+ const fallbackMessage = error instanceof Error ? error.message : 'Lookup probe failed'
288
+ const message = controller.signal.aborted
289
+ ? `Lookup probe timed out after ${this.timeoutMs}ms`
290
+ : fallbackMessage
291
+ return makeFailedResult({
292
+ target,
293
+ probe,
294
+ url,
295
+ status: 0,
296
+ ok: false,
297
+ responseBytes: 0,
298
+ durationMs: completedAt.getTime() - startedAt.getTime(),
299
+ error: message
300
+ })
301
+ } finally {
302
+ clearTimeout(timeout)
303
+ }
304
+ }
305
+
306
+ private async runAnchorProbe(target: OverlayMonitorTarget, probe: OverlayAnchorProbe): Promise<OverlayAnchorProbeResult> {
307
+ const startedAt = this.now()
308
+ const url = new URL('/requestTopicAnchorTip', target.baseUrl).toString()
309
+ const controller = new AbortController()
310
+ const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
311
+
312
+ try {
313
+ const response = await this.fetchImpl(url, {
314
+ method: 'POST',
315
+ headers: {
316
+ Accept: 'application/json',
317
+ 'Content-Type': 'application/json',
318
+ 'x-bsv-topic': probe.topic,
319
+ ...target.headers
320
+ },
321
+ body: JSON.stringify({}),
322
+ signal: controller.signal
323
+ })
324
+ const text = await response.text()
325
+ const responseBytes = new TextEncoder().encode(text).length
326
+ const completedAt = this.now()
327
+ let body: Record<string, unknown>
328
+
329
+ try {
330
+ body = text.length === 0 ? {} : JSON.parse(text)
331
+ } catch (error) {
332
+ return makeFailedAnchorResult({
333
+ target,
334
+ probe,
335
+ url,
336
+ status: response.status,
337
+ ok: response.ok,
338
+ responseBytes,
339
+ durationMs: completedAt.getTime() - startedAt.getTime(),
340
+ error: error instanceof Error ? error.message : 'Invalid JSON response'
341
+ })
342
+ }
343
+
344
+ return analyzeOverlayAnchorTip({
345
+ target: target.name,
346
+ url,
347
+ probe: probe.name ?? probe.topic,
348
+ topic: probe.topic,
349
+ status: response.status,
350
+ ok: response.ok,
351
+ responseBody: body,
352
+ responseBytes,
353
+ durationMs: completedAt.getTime() - startedAt.getTime(),
354
+ thresholds: this.thresholds,
355
+ expectedTac: probe.expectedTac,
356
+ expectedBlockHeight: probe.expectedBlockHeight,
357
+ currentHeight: probe.currentHeight,
358
+ maxTipLagBlocks: probe.maxTipLagBlocks
359
+ })
360
+ } catch (error) {
361
+ const completedAt = this.now()
362
+ const fallbackMessage = error instanceof Error ? error.message : 'Anchor probe failed'
363
+ const message = controller.signal.aborted
364
+ ? `Anchor probe timed out after ${this.timeoutMs}ms`
365
+ : fallbackMessage
366
+ return makeFailedAnchorResult({
367
+ target,
368
+ probe,
369
+ url,
370
+ status: 0,
371
+ ok: false,
372
+ responseBytes: 0,
373
+ durationMs: completedAt.getTime() - startedAt.getTime(),
374
+ error: message
375
+ })
376
+ } finally {
377
+ clearTimeout(timeout)
378
+ }
379
+ }
380
+ }
381
+
382
+ export function analyzeOverlayAnchorTip(options: {
383
+ target: string
384
+ url: string
385
+ probe: string
386
+ topic: string
387
+ status: number
388
+ ok: boolean
389
+ responseBody: Record<string, unknown>
390
+ responseBytes: number
391
+ durationMs: number
392
+ thresholds?: OverlayMonitorThresholds
393
+ expectedTac?: string
394
+ expectedBlockHeight?: number
395
+ currentHeight?: number
396
+ maxTipLagBlocks?: number
397
+ }): OverlayAnchorProbeResult {
398
+ const thresholds = { ...defaultThresholds, ...options.thresholds }
399
+ const blockHeight = typeof options.responseBody.blockHeight === 'number' ? options.responseBody.blockHeight : undefined
400
+ const tac = typeof options.responseBody.tac === 'string' ? options.responseBody.tac : undefined
401
+ let expiredUnprovenCount: number | undefined
402
+ if (typeof options.responseBody.expiredUnprovenCount === 'number') {
403
+ expiredUnprovenCount = options.responseBody.expiredUnprovenCount
404
+ } else if (typeof options.responseBody.unprovenExpiredCount === 'number') {
405
+ expiredUnprovenCount = options.responseBody.unprovenExpiredCount
406
+ } else {
407
+ expiredUnprovenCount = undefined
408
+ }
409
+ const warnings: OverlayMonitorWarning[] = []
410
+
411
+ if (options.expectedTac !== undefined && tac !== undefined && tac !== options.expectedTac) {
412
+ warnings.push({
413
+ code: 'anchor-tip-mismatch',
414
+ message: 'Topic anchor TAC does not match expected value',
415
+ value: true,
416
+ threshold: false
417
+ })
418
+ }
419
+
420
+ const expectedHeight = options.expectedBlockHeight ?? options.currentHeight
421
+ const maxLag = options.maxTipLagBlocks ?? thresholds.anchorTipLagBlocks
422
+ if (expectedHeight !== undefined && blockHeight !== undefined && expectedHeight - blockHeight > maxLag) {
423
+ warnings.push({
424
+ code: 'anchor-stale-height',
425
+ message: `Topic anchor tip is ${expectedHeight - blockHeight} blocks behind`,
426
+ value: expectedHeight - blockHeight,
427
+ threshold: maxLag
428
+ })
429
+ }
430
+
431
+ if (expiredUnprovenCount !== undefined && expiredUnprovenCount > thresholds.expiredUnprovenCount) {
432
+ warnings.push({
433
+ code: 'expired-unproven-state',
434
+ message: `Overlay reports ${expiredUnprovenCount} expired unproven transactions`,
435
+ value: expiredUnprovenCount,
436
+ threshold: thresholds.expiredUnprovenCount
437
+ })
438
+ }
439
+
440
+ return {
441
+ target: options.target,
442
+ url: options.url,
443
+ probe: options.probe,
444
+ topic: options.topic,
445
+ status: options.status,
446
+ ok: options.ok,
447
+ responseBytes: options.responseBytes,
448
+ blockHeight,
449
+ tac,
450
+ warnings,
451
+ durationMs: options.durationMs
452
+ }
453
+ }
454
+
455
+ export function analyzeOverlayLookupResponse (options: AnalyzeOptions): OverlayLookupProbeResult {
456
+ const thresholds = { ...defaultThresholds, ...options.thresholds }
457
+ const outputs = extractOutputs(options.responseBody)
458
+ const maxOutputs = options.maxOutputs ?? outputs.length
459
+ const analyzedOutputs = outputs.slice(0, maxOutputs).map(analyzeOutput)
460
+ const warnings: OverlayMonitorWarning[] = []
461
+
462
+ if (options.responseBytes >= thresholds.responseBytes) {
463
+ warnings.push({
464
+ code: 'response-bytes',
465
+ message: `Lookup response is ${options.responseBytes} bytes`,
466
+ value: options.responseBytes,
467
+ threshold: thresholds.responseBytes
468
+ })
469
+ }
470
+
471
+ for (const output of analyzedOutputs) {
472
+ addOutputWarnings(warnings, output, thresholds)
473
+ }
474
+
475
+ return {
476
+ target: options.target,
477
+ url: options.url,
478
+ probe: options.probe,
479
+ service: options.service,
480
+ status: options.status,
481
+ ok: options.ok,
482
+ responseBytes: options.responseBytes,
483
+ outputCount: outputs.length,
484
+ analyzedOutputCount: analyzedOutputs.length,
485
+ outputs: analyzedOutputs,
486
+ warnings,
487
+ durationMs: options.durationMs,
488
+ error: options.error
489
+ }
490
+ }
491
+
492
+ function makeFailedResult (options: {
493
+ target: OverlayMonitorTarget
494
+ probe: OverlayLookupProbe
495
+ url: string
496
+ status: number
497
+ ok: boolean
498
+ responseBytes: number
499
+ durationMs: number
500
+ error: string
501
+ }): OverlayLookupProbeResult {
502
+ return {
503
+ target: options.target.name,
504
+ url: options.url,
505
+ probe: options.probe.name ?? options.probe.service,
506
+ service: options.probe.service,
507
+ status: options.status,
508
+ ok: options.ok,
509
+ responseBytes: options.responseBytes,
510
+ outputCount: 0,
511
+ analyzedOutputCount: 0,
512
+ outputs: [],
513
+ warnings: [],
514
+ durationMs: options.durationMs,
515
+ error: options.error
516
+ }
517
+ }
518
+
519
+ function makeFailedAnchorResult(options: {
520
+ target: OverlayMonitorTarget
521
+ probe: OverlayAnchorProbe
522
+ url: string
523
+ status: number
524
+ ok: boolean
525
+ responseBytes: number
526
+ durationMs: number
527
+ error: string
528
+ }): OverlayAnchorProbeResult {
529
+ return {
530
+ target: options.target.name,
531
+ url: options.url,
532
+ probe: options.probe.name ?? options.probe.topic,
533
+ topic: options.probe.topic,
534
+ status: options.status,
535
+ ok: options.ok,
536
+ responseBytes: options.responseBytes,
537
+ warnings: [],
538
+ durationMs: options.durationMs,
539
+ error: options.error
540
+ }
541
+ }
542
+
543
+ function summarize (results: OverlayLookupProbeResult[], anchorResults: OverlayAnchorProbeResult[], targetCount: number): OverlayMonitorReport['summary'] {
544
+ return {
545
+ targetCount,
546
+ probeCount: results.length,
547
+ anchorProbeCount: anchorResults.length,
548
+ failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length +
549
+ anchorResults.filter(result => !result.ok || result.error !== undefined).length,
550
+ responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0) +
551
+ anchorResults.reduce((sum, result) => sum + result.responseBytes, 0),
552
+ outputCount: results.reduce((sum, result) => sum + result.outputCount, 0),
553
+ analyzedOutputCount: results.reduce((sum, result) => sum + result.analyzedOutputCount, 0),
554
+ outputsMissingSubjectProof: results.reduce((sum, result) => {
555
+ return sum + result.outputs.filter(output => output.subjectHasProof === false).length
556
+ }, 0),
557
+ warningCount: results.reduce((sum, result) => sum + result.warnings.length, 0) +
558
+ anchorResults.reduce((sum, result) => sum + result.warnings.length, 0)
559
+ }
560
+ }
561
+
562
+ function extractOutputs (body: unknown): Array<Record<string, unknown>> {
563
+ if (typeof body !== 'object' || body === null || !('outputs' in body)) return []
564
+ const outputs = (body as { outputs?: unknown }).outputs
565
+ if (!Array.isArray(outputs)) return []
566
+ return outputs.filter((output): output is Record<string, unknown> => typeof output === 'object' && output !== null)
567
+ }
568
+
569
+ function analyzeOutput (output: Record<string, unknown>): OverlayLookupOutputSummary {
570
+ const outputIndex = typeof output.outputIndex === 'number' ? output.outputIndex : -1
571
+ const beef = readNumberArray(output.beef)
572
+ const context = readNumberArray(output.context)
573
+
574
+ if (beef === undefined) {
575
+ return {
576
+ outputIndex,
577
+ beefBytes: 0,
578
+ contextBytes: context?.length,
579
+ error: 'Output did not include numeric BEEF'
580
+ }
581
+ }
582
+
583
+ try {
584
+ const subjectTx = Transaction.fromBEEF(beef)
585
+ const txid = subjectTx.id('hex')
586
+ const parsedBeef = Beef.fromBinary(beef)
587
+ const subject = parsedBeef.findTxid(txid)
588
+ const subjectRawTxBytes = subject?.rawTx?.length ?? subjectTx.toBinary().length
589
+ const proofCount = parsedBeef.txs.filter(tx => tx.hasProof).length
590
+ const txsWithoutProof = parsedBeef.txs.filter(tx => !tx.hasProof && !tx.isTxidOnly).length
591
+
592
+ return {
593
+ outputIndex,
594
+ txid,
595
+ beefBytes: beef.length,
596
+ txCount: parsedBeef.txs.length,
597
+ proofCount,
598
+ txsWithoutProof,
599
+ subjectHasProof: subject?.hasProof ?? false,
600
+ subjectRawTxBytes,
601
+ currentToSubjectRawRatio: subjectRawTxBytes > 0 ? beef.length / subjectRawTxBytes : undefined,
602
+ contextBytes: context?.length
603
+ }
604
+ } catch (error) {
605
+ return {
606
+ outputIndex,
607
+ beefBytes: beef.length,
608
+ contextBytes: context?.length,
609
+ error: error instanceof Error ? error.message : 'Failed to parse BEEF'
610
+ }
611
+ }
612
+ }
613
+
614
+ function addOutputWarnings (
615
+ warnings: OverlayMonitorWarning[],
616
+ output: OverlayLookupOutputSummary,
617
+ thresholds: Required<OverlayMonitorThresholds>
618
+ ): void {
619
+ if (output.beefBytes >= thresholds.beefBytes) {
620
+ warnings.push({
621
+ code: 'beef-bytes',
622
+ message: `Output BEEF is ${output.beefBytes} bytes`,
623
+ value: output.beefBytes,
624
+ threshold: thresholds.beefBytes,
625
+ outputIndex: output.outputIndex,
626
+ txid: output.txid
627
+ })
628
+ }
629
+
630
+ if (typeof output.txsWithoutProof === 'number' && output.txsWithoutProof >= thresholds.txsWithoutProof) {
631
+ warnings.push({
632
+ code: 'txs-without-proof',
633
+ message: `Output BEEF has ${output.txsWithoutProof} transactions without direct proof`,
634
+ value: output.txsWithoutProof,
635
+ threshold: thresholds.txsWithoutProof,
636
+ outputIndex: output.outputIndex,
637
+ txid: output.txid
638
+ })
639
+ }
640
+
641
+ if (thresholds.requireSubjectProof && output.subjectHasProof === false) {
642
+ warnings.push({
643
+ code: 'subject-proof-missing',
644
+ message: 'Output subject transaction does not have a direct Merkle proof',
645
+ value: false,
646
+ threshold: true,
647
+ outputIndex: output.outputIndex,
648
+ txid: output.txid
649
+ })
650
+ }
651
+ }
652
+
653
+ function readNumberArray (value: unknown): number[] | undefined {
654
+ if (!Array.isArray(value)) return undefined
655
+ if (!value.every(item => Number.isInteger(item) && item >= 0 && item <= 255)) return undefined
656
+ return value
657
+ }