@bsv/overlay-express 2.4.0 → 2.4.2

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 (56) hide show
  1. package/README.md +122 -3
  2. package/dist/cjs/mod.js +8 -1
  3. package/dist/cjs/mod.js.map +1 -1
  4. package/dist/cjs/package.json +19 -19
  5. package/dist/cjs/src/ArcadeProvider.js +196 -0
  6. package/dist/cjs/src/ArcadeProvider.js.map +1 -0
  7. package/dist/cjs/src/ChaintracksProvider.js +65 -0
  8. package/dist/cjs/src/ChaintracksProvider.js.map +1 -0
  9. package/dist/cjs/src/OverlayExpress.js +270 -28
  10. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  11. package/dist/cjs/src/OverlayMonitor.js +117 -3
  12. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  13. package/dist/cjs/src/ProviderChainBroadcaster.js +91 -0
  14. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -0
  15. package/dist/cjs/src/generalGuide.md.js +1 -1
  16. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  17. package/dist/esm/mod.js +3 -0
  18. package/dist/esm/mod.js.map +1 -1
  19. package/dist/esm/src/ArcadeProvider.js +189 -0
  20. package/dist/esm/src/ArcadeProvider.js.map +1 -0
  21. package/dist/esm/src/ChaintracksProvider.js +62 -0
  22. package/dist/esm/src/ChaintracksProvider.js.map +1 -0
  23. package/dist/esm/src/OverlayExpress.js +265 -28
  24. package/dist/esm/src/OverlayExpress.js.map +1 -1
  25. package/dist/esm/src/OverlayMonitor.js +117 -3
  26. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  27. package/dist/esm/src/ProviderChainBroadcaster.js +88 -0
  28. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -0
  29. package/dist/esm/src/generalGuide.md.js +1 -1
  30. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  31. package/dist/types/mod.d.ts +3 -0
  32. package/dist/types/mod.d.ts.map +1 -1
  33. package/dist/types/src/ArcadeProvider.d.ts +37 -0
  34. package/dist/types/src/ArcadeProvider.d.ts.map +1 -0
  35. package/dist/types/src/ChaintracksProvider.d.ts +29 -0
  36. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -0
  37. package/dist/types/src/OverlayExpress.d.ts +38 -1
  38. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  39. package/dist/types/src/OverlayMonitor.d.ts +28 -0
  40. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  41. package/dist/types/src/ProviderChainBroadcaster.d.ts +18 -0
  42. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -0
  43. package/dist/types/src/generalGuide.md.d.ts +1 -1
  44. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  45. package/mod.ts +15 -0
  46. package/package.json +19 -19
  47. package/src/ArcadeProvider.ts +232 -0
  48. package/src/ChaintracksProvider.ts +79 -0
  49. package/src/OverlayExpress.ts +299 -28
  50. package/src/OverlayMonitor.ts +163 -3
  51. package/src/ProviderChainBroadcaster.ts +108 -0
  52. package/src/__tests__/OverlayExpress.test.ts +196 -4
  53. package/src/__tests__/OverlayMonitor.test.ts +74 -0
  54. package/src/__tests__/OverlayProviders.live.test.ts +43 -0
  55. package/src/__tests__/OverlayProviders.test.ts +123 -0
  56. package/src/generalGuide.md.ts +1 -1
@@ -22,11 +22,23 @@ export interface OverlayAnchorProbe {
22
22
  maxTipLagBlocks?: number
23
23
  }
24
24
 
25
+ export interface OverlayMaintenanceConfig {
26
+ adminToken?: string
27
+ headers?: Record<string, string>
28
+ maintainUnproven?: boolean | {
29
+ topics?: string[]
30
+ thresholdBlocks?: number
31
+ }
32
+ startBASMSync?: boolean
33
+ janitor?: boolean
34
+ }
35
+
25
36
  export interface OverlayMonitorTarget {
26
37
  name: string
27
38
  baseUrl: string
28
39
  probes: OverlayLookupProbe[]
29
40
  anchorProbes?: OverlayAnchorProbe[]
41
+ maintenance?: OverlayMaintenanceConfig
30
42
  headers?: Record<string, string>
31
43
  }
32
44
 
@@ -105,17 +117,33 @@ export interface OverlayAnchorProbeResult {
105
117
  error?: string
106
118
  }
107
119
 
120
+ export interface OverlayMaintenanceResult {
121
+ target: string
122
+ url: string
123
+ operation: 'maintain-unproven' | 'start-basm-sync' | 'janitor'
124
+ topic?: string
125
+ status: number
126
+ ok: boolean
127
+ responseBytes: number
128
+ durationMs: number
129
+ data?: unknown
130
+ error?: string
131
+ }
132
+
108
133
  export interface OverlayMonitorReport {
109
134
  startedAt: Date
110
135
  completedAt: Date
111
136
  durationMs: number
112
137
  results: OverlayLookupProbeResult[]
113
138
  anchorResults: OverlayAnchorProbeResult[]
139
+ maintenanceResults: OverlayMaintenanceResult[]
114
140
  summary: {
115
141
  targetCount: number
116
142
  probeCount: number
117
143
  anchorProbeCount: number
144
+ maintenanceActionCount: number
118
145
  failedProbeCount: number
146
+ failedMaintenanceActionCount: number
119
147
  responseBytes: number
120
148
  outputCount: number
121
149
  analyzedOutputCount: number
@@ -182,6 +210,7 @@ export class OverlayMonitor {
182
210
  const startedAt = this.now()
183
211
  const results: OverlayLookupProbeResult[] = []
184
212
  const anchorResults: OverlayAnchorProbeResult[] = []
213
+ const maintenanceResults: OverlayMaintenanceResult[] = []
185
214
 
186
215
  for (const target of this.targets) {
187
216
  for (const probe of target.probes) {
@@ -190,6 +219,7 @@ export class OverlayMonitor {
190
219
  for (const probe of target.anchorProbes ?? []) {
191
220
  anchorResults.push(await this.runAnchorProbe(target, probe))
192
221
  }
222
+ maintenanceResults.push(...await this.runMaintenance(target))
193
223
  }
194
224
 
195
225
  const completedAt = this.now()
@@ -199,7 +229,8 @@ export class OverlayMonitor {
199
229
  durationMs: completedAt.getTime() - startedAt.getTime(),
200
230
  results,
201
231
  anchorResults,
202
- summary: summarize(results, anchorResults, this.targets.length)
232
+ maintenanceResults,
233
+ summary: summarize(results, anchorResults, maintenanceResults, this.targets.length)
203
234
  }
204
235
 
205
236
  await this.onReport?.(report)
@@ -377,6 +408,117 @@ export class OverlayMonitor {
377
408
  clearTimeout(timeout)
378
409
  }
379
410
  }
411
+
412
+ private async runMaintenance(target: OverlayMonitorTarget): Promise<OverlayMaintenanceResult[]> {
413
+ const maintenance = target.maintenance
414
+ if (maintenance === undefined) return []
415
+
416
+ const results: OverlayMaintenanceResult[] = []
417
+ if (maintenance.startBASMSync === true) {
418
+ results.push(await this.runMaintenanceRequest(target, maintenance, 'start-basm-sync', '/admin/startBASMSync', {}))
419
+ }
420
+ if (maintenance.maintainUnproven !== undefined && maintenance.maintainUnproven !== false) {
421
+ const config = maintenance.maintainUnproven === true ? {} : maintenance.maintainUnproven
422
+ const topics = config.topics !== undefined && config.topics.length > 0 ? config.topics : [undefined]
423
+ for (const topic of topics) {
424
+ results.push(await this.runMaintenanceRequest(
425
+ target,
426
+ maintenance,
427
+ 'maintain-unproven',
428
+ '/admin/maintainUnproven',
429
+ {
430
+ topic,
431
+ thresholdBlocks: config.thresholdBlocks
432
+ }
433
+ ))
434
+ }
435
+ }
436
+ if (maintenance.janitor === true) {
437
+ results.push(await this.runMaintenanceRequest(target, maintenance, 'janitor', '/admin/janitor', {}))
438
+ }
439
+ return results
440
+ }
441
+
442
+ private async runMaintenanceRequest(
443
+ target: OverlayMonitorTarget,
444
+ maintenance: OverlayMaintenanceConfig,
445
+ operation: OverlayMaintenanceResult['operation'],
446
+ path: string,
447
+ body: { topic?: string, thresholdBlocks?: number }
448
+ ): Promise<OverlayMaintenanceResult> {
449
+ const startedAt = this.now()
450
+ const url = new URL(path, target.baseUrl).toString()
451
+ const controller = new AbortController()
452
+ const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
453
+
454
+ try {
455
+ const headers: Record<string, string> = {
456
+ Accept: 'application/json',
457
+ 'Content-Type': 'application/json',
458
+ ...target.headers,
459
+ ...maintenance.headers
460
+ }
461
+ if (maintenance.adminToken !== undefined && maintenance.adminToken !== '') {
462
+ headers.Authorization = `Bearer ${maintenance.adminToken}`
463
+ }
464
+ const response = await this.fetchImpl(url, {
465
+ method: 'POST',
466
+ headers,
467
+ body: JSON.stringify(stripUndefined(body)),
468
+ signal: controller.signal
469
+ })
470
+ const text = await response.text()
471
+ const responseBytes = new TextEncoder().encode(text).length
472
+ const completedAt = this.now()
473
+ let parsed: unknown
474
+ try {
475
+ parsed = text.length === 0 ? {} : JSON.parse(text)
476
+ } catch (error) {
477
+ return {
478
+ target: target.name,
479
+ url,
480
+ operation,
481
+ topic: body.topic,
482
+ status: response.status,
483
+ ok: false,
484
+ responseBytes,
485
+ durationMs: completedAt.getTime() - startedAt.getTime(),
486
+ error: error instanceof Error ? error.message : 'Invalid JSON response'
487
+ }
488
+ }
489
+ return {
490
+ target: target.name,
491
+ url,
492
+ operation,
493
+ topic: body.topic,
494
+ status: response.status,
495
+ ok: response.ok,
496
+ responseBytes,
497
+ durationMs: completedAt.getTime() - startedAt.getTime(),
498
+ data: parsed,
499
+ error: response.ok ? undefined : readErrorMessage(parsed)
500
+ }
501
+ } catch (error) {
502
+ const completedAt = this.now()
503
+ const fallbackMessage = error instanceof Error ? error.message : 'Maintenance request failed'
504
+ const message = controller.signal.aborted
505
+ ? `Maintenance request timed out after ${this.timeoutMs}ms`
506
+ : fallbackMessage
507
+ return {
508
+ target: target.name,
509
+ url,
510
+ operation,
511
+ topic: body.topic,
512
+ status: 0,
513
+ ok: false,
514
+ responseBytes: 0,
515
+ durationMs: completedAt.getTime() - startedAt.getTime(),
516
+ error: message
517
+ }
518
+ } finally {
519
+ clearTimeout(timeout)
520
+ }
521
+ }
380
522
  }
381
523
 
382
524
  export function analyzeOverlayAnchorTip(options: {
@@ -540,15 +682,23 @@ function makeFailedAnchorResult(options: {
540
682
  }
541
683
  }
542
684
 
543
- function summarize (results: OverlayLookupProbeResult[], anchorResults: OverlayAnchorProbeResult[], targetCount: number): OverlayMonitorReport['summary'] {
685
+ function summarize (
686
+ results: OverlayLookupProbeResult[],
687
+ anchorResults: OverlayAnchorProbeResult[],
688
+ maintenanceResults: OverlayMaintenanceResult[],
689
+ targetCount: number
690
+ ): OverlayMonitorReport['summary'] {
544
691
  return {
545
692
  targetCount,
546
693
  probeCount: results.length,
547
694
  anchorProbeCount: anchorResults.length,
695
+ maintenanceActionCount: maintenanceResults.length,
548
696
  failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length +
549
697
  anchorResults.filter(result => !result.ok || result.error !== undefined).length,
698
+ failedMaintenanceActionCount: maintenanceResults.filter(result => !result.ok || result.error !== undefined).length,
550
699
  responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0) +
551
- anchorResults.reduce((sum, result) => sum + result.responseBytes, 0),
700
+ anchorResults.reduce((sum, result) => sum + result.responseBytes, 0) +
701
+ maintenanceResults.reduce((sum, result) => sum + result.responseBytes, 0),
552
702
  outputCount: results.reduce((sum, result) => sum + result.outputCount, 0),
553
703
  analyzedOutputCount: results.reduce((sum, result) => sum + result.analyzedOutputCount, 0),
554
704
  outputsMissingSubjectProof: results.reduce((sum, result) => {
@@ -559,6 +709,16 @@ function summarize (results: OverlayLookupProbeResult[], anchorResults: OverlayA
559
709
  }
560
710
  }
561
711
 
712
+ function stripUndefined<T extends Record<string, unknown>>(value: T): Record<string, unknown> {
713
+ return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined))
714
+ }
715
+
716
+ function readErrorMessage(body: unknown): string | undefined {
717
+ if (typeof body !== 'object' || body === null) return undefined
718
+ const message = (body as { message?: unknown }).message
719
+ return typeof message === 'string' ? message : undefined
720
+ }
721
+
562
722
  function extractOutputs (body: unknown): Array<Record<string, unknown>> {
563
723
  if (typeof body !== 'object' || body === null || !('outputs' in body)) return []
564
724
  const outputs = (body as { outputs?: unknown }).outputs
@@ -0,0 +1,108 @@
1
+ import {
2
+ BroadcastFailure,
3
+ Broadcaster,
4
+ BroadcastResponse,
5
+ Transaction
6
+ } from '@bsv/sdk'
7
+
8
+ export interface NamedBroadcaster {
9
+ name: string
10
+ broadcaster: Broadcaster
11
+ }
12
+
13
+ const TERMINAL_CODES = new Set([
14
+ '400',
15
+ '460',
16
+ '463',
17
+ '464',
18
+ 'DOUBLE_SPEND_ATTEMPTED',
19
+ 'REJECTED',
20
+ 'INVALID',
21
+ 'MALFORMED',
22
+ 'MINED_IN_STALE_BLOCK'
23
+ ])
24
+
25
+ function isTerminalBroadcastFailure (failure: BroadcastFailure): boolean {
26
+ const code = failure.code.toUpperCase()
27
+ const description = failure.description.toUpperCase()
28
+ if (TERMINAL_CODES.has(code)) return true
29
+ if (code.includes('ORPHAN') || description.includes('ORPHAN')) return true
30
+ if (
31
+ typeof failure.more === 'object' &&
32
+ failure.more !== null &&
33
+ 'terminal' in failure.more &&
34
+ failure.more.terminal === true
35
+ ) {
36
+ return true
37
+ }
38
+ return false
39
+ }
40
+
41
+ /**
42
+ * Tries transaction propagation providers in priority order.
43
+ *
44
+ * Transient provider failures fall through to the next provider. Terminal
45
+ * validation states, including double spends, stop immediately so a conflicting
46
+ * transaction is not retried against a second propagation surface.
47
+ */
48
+ export class ProviderChainBroadcaster implements Broadcaster {
49
+ constructor (private readonly providers: NamedBroadcaster[]) {
50
+ if (providers.length === 0) {
51
+ throw new TypeError('ProviderChainBroadcaster requires at least one provider')
52
+ }
53
+ }
54
+
55
+ async broadcast (tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
56
+ const failures: Array<{ provider: string, failure: BroadcastFailure }> = []
57
+
58
+ for (const provider of this.providers) {
59
+ let response: BroadcastResponse | BroadcastFailure
60
+ try {
61
+ response = await provider.broadcaster.broadcast(tx)
62
+ } catch (error: unknown) {
63
+ response = {
64
+ status: 'error',
65
+ code: '500',
66
+ description: error instanceof Error ? error.message : 'Internal Server Error',
67
+ more: { provider: provider.name, terminal: false }
68
+ }
69
+ }
70
+
71
+ if (response.status === 'success') {
72
+ return {
73
+ ...response,
74
+ message: `[${provider.name}] ${response.message}`
75
+ }
76
+ }
77
+
78
+ failures.push({ provider: provider.name, failure: response })
79
+ if (isTerminalBroadcastFailure(response)) {
80
+ return annotateFailure(response, provider.name, failures)
81
+ }
82
+ }
83
+
84
+ const last = failures[failures.length - 1]
85
+ return annotateFailure(last.failure, last.provider, failures)
86
+ }
87
+ }
88
+
89
+ function annotateFailure (
90
+ failure: BroadcastFailure,
91
+ provider: string,
92
+ failures: Array<{ provider: string, failure: BroadcastFailure }>
93
+ ): BroadcastFailure {
94
+ return {
95
+ ...failure,
96
+ more: {
97
+ ...(typeof failure.more === 'object' && failure.more !== null ? failure.more : {}),
98
+ provider,
99
+ providerFailures: failures.map(item => ({
100
+ provider: item.provider,
101
+ code: item.failure.code,
102
+ description: item.failure.description,
103
+ txid: item.failure.txid,
104
+ more: item.failure.more
105
+ }))
106
+ }
107
+ }
108
+ }
@@ -4,6 +4,7 @@ import Knex from 'knex'
4
4
  import { MongoClient } from 'mongodb'
5
5
  import { TopicManager, LookupService } from '@bsv/overlay'
6
6
  import { ChainTracker } from '@bsv/sdk'
7
+ import * as DiscoveryServices from '@bsv/overlay-discovery-services'
7
8
 
8
9
  // Mock dependencies
9
10
  jest.mock('knex')
@@ -503,6 +504,43 @@ describe('OverlayExpress', () => {
503
504
  expect(overlayExpress.services.ls_slap).toBeDefined()
504
505
  })
505
506
 
507
+ it('should initialize SHIP/SLAP indexes before completing engine configuration', async () => {
508
+ const shipEnsureIndexes = jest.fn<any>().mockResolvedValue(undefined)
509
+ const slapEnsureIndexes = jest.fn<any>().mockResolvedValue(undefined)
510
+ ;(DiscoveryServices.SHIPStorage as any).mockImplementationOnce(() => ({
511
+ ensureIndexes: shipEnsureIndexes
512
+ }))
513
+ ;(DiscoveryServices.SLAPStorage as any).mockImplementationOnce(() => ({
514
+ ensureIndexes: slapEnsureIndexes
515
+ }))
516
+
517
+ await overlayExpress.configureEngine(true)
518
+
519
+ expect(shipEnsureIndexes).toHaveBeenCalledTimes(1)
520
+ expect(slapEnsureIndexes).toHaveBeenCalledTimes(1)
521
+ expect(overlayExpress.engine).toBeDefined()
522
+ })
523
+
524
+ it('should fail engine configuration when discovery index initialization fails', async () => {
525
+ const indexError = new Error('discovery index migration failed')
526
+ const shipEnsureIndexes = jest.fn<any>().mockRejectedValue(indexError)
527
+ const slapEnsureIndexes = jest.fn<any>().mockResolvedValue(undefined)
528
+ ;(DiscoveryServices.SHIPStorage as any).mockImplementationOnce(() => ({
529
+ ensureIndexes: shipEnsureIndexes
530
+ }))
531
+ ;(DiscoveryServices.SLAPStorage as any).mockImplementationOnce(() => ({
532
+ ensureIndexes: slapEnsureIndexes
533
+ }))
534
+
535
+ await expect(overlayExpress.configureEngine(true)).rejects.toThrow(indexError)
536
+
537
+ expect(shipEnsureIndexes).toHaveBeenCalledTimes(1)
538
+ expect(slapEnsureIndexes).not.toHaveBeenCalled()
539
+ expect(overlayExpress.engine).toBeUndefined()
540
+ expect(overlayExpress.services.ls_ship).toBeUndefined()
541
+ expect(overlayExpress.services.ls_slap).toBeUndefined()
542
+ })
543
+
506
544
  it('should configure engine without auto SHIP/SLAP', async () => {
507
545
  await overlayExpress.configureEngine(false)
508
546
 
@@ -672,6 +710,12 @@ describe('OverlayExpress', () => {
672
710
  syncAdvertisements: jest.fn().mockResolvedValue(undefined),
673
711
  // @ts-expect-error - Mock return values
674
712
  startGASPSync: jest.fn().mockResolvedValue(undefined),
713
+ // @ts-expect-error - Mock return values
714
+ refreshUnprovenTransactionProofs: jest.fn().mockResolvedValue({}),
715
+ // @ts-expect-error - Mock return values
716
+ maintainUnprovenTransactions: jest.fn().mockResolvedValue({}),
717
+ // @ts-expect-error - Mock return values
718
+ evictAppliedTransaction: jest.fn().mockResolvedValue({ evictedTransactions: 1, evictedOutputs: 1 }),
675
719
  lookupServices: {},
676
720
  advertiser: {
677
721
  // @ts-expect-error - Mock return values
@@ -740,6 +784,125 @@ describe('OverlayExpress', () => {
740
784
  expect(listenSpy).toHaveBeenCalledWith(3000, expect.any(Function))
741
785
  })
742
786
 
787
+ it('accepts canonical and legacy X-Topics formats on /submit', async () => {
788
+ const postSpy = jest.spyOn(instance.app, 'post')
789
+ jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
790
+ callback()
791
+ return {} as any
792
+ })
793
+ await instance.start()
794
+
795
+ const route = postSpy.mock.calls.find(call => call[0] === '/submit')
796
+ const handler: any = route === undefined ? undefined : route[route.length - 1]
797
+ expect(handler).toBeDefined()
798
+
799
+ for (const topicsHeader of ['tm_foo,tm_bar', '["tm_foo","tm_bar"]']) {
800
+ const res: any = {
801
+ status: jest.fn().mockReturnThis(),
802
+ json: jest.fn().mockReturnThis()
803
+ }
804
+ handler?.({
805
+ headers: { 'x-topics': topicsHeader },
806
+ body: Buffer.from([1, 2, 3])
807
+ }, res)
808
+ await new Promise(resolve => setImmediate(resolve))
809
+ }
810
+
811
+ expect(mockEngine.submit).toHaveBeenCalledTimes(2)
812
+ for (const call of mockEngine.submit.mock.calls) {
813
+ expect(call[0]).toEqual({
814
+ beef: [1, 2, 3],
815
+ topics: ['tm_foo', 'tm_bar'],
816
+ offChainValues: undefined
817
+ })
818
+ }
819
+ })
820
+
821
+ it('returns a clean 400 for an empty /submit body', async () => {
822
+ const postSpy = jest.spyOn(instance.app, 'post')
823
+ jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
824
+ callback()
825
+ return {} as any
826
+ })
827
+ const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
828
+ await instance.start()
829
+
830
+ const route = postSpy.mock.calls.find(call => call[0] === '/submit')
831
+ const handler: any = route === undefined ? undefined : route[route.length - 1]
832
+ const res: any = {
833
+ status: jest.fn().mockReturnThis(),
834
+ json: jest.fn().mockReturnThis()
835
+ }
836
+ handler?.({ headers: { 'x-topics': 'tm_foo' }, body: undefined }, res)
837
+ await new Promise(resolve => setImmediate(resolve))
838
+
839
+ expect(res.status).toHaveBeenCalledWith(400)
840
+ expect(res.json).toHaveBeenCalledWith({
841
+ status: 'error',
842
+ message: 'Missing or empty BEEF body'
843
+ })
844
+ expect(mockEngine.submit).not.toHaveBeenCalled()
845
+ consoleError.mockRestore()
846
+ })
847
+
848
+ it.each([
849
+ ['', 'an empty comma-separated list'],
850
+ ['tm_foo,', 'an empty comma-separated topic'],
851
+ ['["tm_foo",42]', 'a JSON array containing a non-string topic']
852
+ ])('returns a clean 400 when X-Topics is %s (%s)', async (topicsHeader) => {
853
+ const postSpy = jest.spyOn(instance.app, 'post')
854
+ jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
855
+ callback()
856
+ return {} as any
857
+ })
858
+ const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
859
+ await instance.start()
860
+
861
+ const route = postSpy.mock.calls.find(call => call[0] === '/submit')
862
+ const handler: any = route === undefined ? undefined : route[route.length - 1]
863
+ const res: any = {
864
+ status: jest.fn().mockReturnThis(),
865
+ json: jest.fn().mockReturnThis()
866
+ }
867
+ handler?.({
868
+ headers: { 'x-topics': topicsHeader },
869
+ body: Buffer.from([1, 2, 3])
870
+ }, res)
871
+ await new Promise(resolve => setImmediate(resolve))
872
+
873
+ expect(res.status).toHaveBeenCalledWith(400)
874
+ expect(res.json).toHaveBeenCalledWith({
875
+ status: 'error',
876
+ message: 'Invalid x-topics header: expected a comma-separated list or JSON string array'
877
+ })
878
+ expect(mockEngine.submit).not.toHaveBeenCalled()
879
+ consoleError.mockRestore()
880
+ })
881
+
882
+ it('returns a clean 400 when /admin/health-check has no body', async () => {
883
+ const postSpy = jest.spyOn(instance.app, 'post')
884
+ jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
885
+ callback()
886
+ return {} as any
887
+ })
888
+ await instance.start()
889
+
890
+ const route = postSpy.mock.calls.find(call => call[0] === '/admin/health-check')
891
+ const handler: any = route === undefined ? undefined : route[route.length - 1]
892
+ const res: any = {
893
+ status: jest.fn().mockReturnThis(),
894
+ json: jest.fn().mockReturnThis()
895
+ }
896
+ handler?.({ body: undefined }, res)
897
+ await new Promise(resolve => setImmediate(resolve))
898
+
899
+ expect(res.status).toHaveBeenCalledWith(400)
900
+ expect(res.json).toHaveBeenCalledWith({
901
+ status: 'error',
902
+ message: 'url is required'
903
+ })
904
+ })
905
+
743
906
  it('should set up CORS middleware', async () => {
744
907
  const useSpy = jest.spyOn(instance.app, 'use')
745
908
  jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
@@ -881,6 +1044,11 @@ describe('OverlayExpress', () => {
881
1044
  }
882
1045
  // Flush the async IIFE inside the /arc-ingest handler.
883
1046
  const flush = async (): Promise<void> => { await new Promise(resolve => setImmediate(resolve)) }
1047
+ const proofCallbackBody = {
1048
+ txid: '11'.repeat(32),
1049
+ merklePath: '00',
1050
+ blockHeight: 800000
1051
+ }
884
1052
 
885
1053
  const captureArcIngestHandler = async (): Promise<any> => {
886
1054
  const postSpy = jest.spyOn(instance.app, 'post')
@@ -924,7 +1092,7 @@ describe('OverlayExpress', () => {
924
1092
  const handler = await captureArcIngestHandler()
925
1093
  const res = mockRes()
926
1094
 
927
- handler({ headers: { authorization: 'Bearer secret-token' }, body: {} }, res)
1095
+ handler({ headers: { authorization: 'Bearer secret-token' }, body: proofCallbackBody }, res)
928
1096
  await flush()
929
1097
 
930
1098
  expect(res.status).not.toHaveBeenCalledWith(401)
@@ -937,7 +1105,7 @@ describe('OverlayExpress', () => {
937
1105
  const handler = await captureArcIngestHandler()
938
1106
  const res = mockRes()
939
1107
 
940
- handler({ headers: { 'x-callback-token': 'secret-token' }, body: {} }, res)
1108
+ handler({ headers: { 'x-callback-token': 'secret-token' }, body: proofCallbackBody }, res)
941
1109
  await flush()
942
1110
 
943
1111
  expect(res.status).not.toHaveBeenCalledWith(401)
@@ -949,12 +1117,35 @@ describe('OverlayExpress', () => {
949
1117
  const handler = await captureArcIngestHandler()
950
1118
  const res = mockRes()
951
1119
 
952
- handler({ headers: {}, body: {} }, res)
1120
+ handler({ headers: {}, body: proofCallbackBody }, res)
953
1121
  await flush()
954
1122
 
955
1123
  expect(res.status).not.toHaveBeenCalledWith(401)
956
1124
  expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
957
1125
  })
1126
+
1127
+ it('evicts a transaction when a provider reports a terminal double-spend status', async () => {
1128
+ instance.configureArcApiKey('test-arc-key')
1129
+ instance.configureArcCallbackToken('secret-token')
1130
+ const handler = await captureArcIngestHandler()
1131
+ const res = mockRes()
1132
+
1133
+ handler({
1134
+ headers: { authorization: 'Bearer secret-token' },
1135
+ body: {
1136
+ txid: '11'.repeat(32),
1137
+ txStatus: 'DOUBLE_SPEND_ATTEMPTED',
1138
+ competingTxs: ['22'.repeat(32)]
1139
+ }
1140
+ }, res)
1141
+ await flush()
1142
+
1143
+ expect(mockEngine.evictAppliedTransaction).toHaveBeenCalledWith('11'.repeat(32), {
1144
+ topic: undefined,
1145
+ reason: 'DOUBLE_SPEND_ATTEMPTED'
1146
+ })
1147
+ expect(mockEngine.handleNewMerkleProof).not.toHaveBeenCalled()
1148
+ })
958
1149
  })
959
1150
 
960
1151
  it('should run knex migrations on start', async () => {
@@ -1026,7 +1217,8 @@ describe('OverlayExpress', () => {
1026
1217
  revokeAdvertisements: jest.fn(),
1027
1218
  parseAdvertisement: jest.fn()
1028
1219
  }
1029
- instance.engine!.advertiser = mockAdvertiser
1220
+ if (instance.engine === undefined) throw new Error('improper test setup')
1221
+ instance.engine.advertiser = mockAdvertiser
1030
1222
 
1031
1223
  jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
1032
1224
  callback()