@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.
- package/README.md +33 -0
- package/dist/cjs/mod.js +10 -1
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +12 -11
- package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
- package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
- package/dist/cjs/src/BanAwareTopicManager.js +71 -0
- package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
- package/dist/cjs/src/OverlayExpress.js +375 -96
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/src/OverlayMonitor.js +464 -0
- package/dist/cjs/src/OverlayMonitor.js.map +1 -0
- package/dist/cjs/src/ReorgStream.js +193 -0
- package/dist/cjs/src/ReorgStream.js.map +1 -0
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js +3 -0
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
- package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
- package/dist/esm/src/BanAwareTopicManager.js +71 -0
- package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
- package/dist/esm/src/OverlayExpress.js +375 -94
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/src/OverlayMonitor.js +458 -0
- package/dist/esm/src/OverlayMonitor.js.map +1 -0
- package/dist/esm/src/ReorgStream.js +190 -0
- package/dist/esm/src/ReorgStream.js.map +1 -0
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +4 -1
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
- package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
- package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
- package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
- package/dist/types/src/OverlayExpress.d.ts +82 -4
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/src/OverlayMonitor.d.ts +169 -0
- package/dist/types/src/OverlayMonitor.d.ts.map +1 -0
- package/dist/types/src/ReorgStream.d.ts +74 -0
- package/dist/types/src/ReorgStream.d.ts.map +1 -0
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +20 -1
- package/package.json +12 -11
- package/src/BanAwareDiscoveryStorage.ts +91 -0
- package/src/BanAwareTopicManager.ts +87 -0
- package/src/OverlayExpress.ts +461 -102
- package/src/OverlayMonitor.ts +657 -0
- package/src/ReorgStream.ts +221 -0
- package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
- package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
- package/src/__tests__/OverlayExpress.test.ts +86 -1
- package/src/__tests__/OverlayMonitor.test.ts +181 -0
- 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
|
+
}
|