@bsv/overlay-express 2.4.0 → 2.4.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 (52) 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 +9 -9
  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 +235 -11
  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/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/ArcadeProvider.js +189 -0
  19. package/dist/esm/src/ArcadeProvider.js.map +1 -0
  20. package/dist/esm/src/ChaintracksProvider.js +62 -0
  21. package/dist/esm/src/ChaintracksProvider.js.map +1 -0
  22. package/dist/esm/src/OverlayExpress.js +231 -11
  23. package/dist/esm/src/OverlayExpress.js.map +1 -1
  24. package/dist/esm/src/OverlayMonitor.js +117 -3
  25. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  26. package/dist/esm/src/ProviderChainBroadcaster.js +88 -0
  27. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -0
  28. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  29. package/dist/types/mod.d.ts +3 -0
  30. package/dist/types/mod.d.ts.map +1 -1
  31. package/dist/types/src/ArcadeProvider.d.ts +37 -0
  32. package/dist/types/src/ArcadeProvider.d.ts.map +1 -0
  33. package/dist/types/src/ChaintracksProvider.d.ts +29 -0
  34. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -0
  35. package/dist/types/src/OverlayExpress.d.ts +38 -1
  36. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  37. package/dist/types/src/OverlayMonitor.d.ts +28 -0
  38. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  39. package/dist/types/src/ProviderChainBroadcaster.d.ts +18 -0
  40. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -0
  41. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  42. package/mod.ts +15 -0
  43. package/package.json +9 -9
  44. package/src/ArcadeProvider.ts +232 -0
  45. package/src/ChaintracksProvider.ts +79 -0
  46. package/src/OverlayExpress.ts +259 -11
  47. package/src/OverlayMonitor.ts +163 -3
  48. package/src/ProviderChainBroadcaster.ts +108 -0
  49. package/src/__tests__/OverlayExpress.test.ts +37 -3
  50. package/src/__tests__/OverlayMonitor.test.ts +74 -0
  51. package/src/__tests__/OverlayProviders.live.test.ts +39 -0
  52. package/src/__tests__/OverlayProviders.test.ts +123 -0
@@ -42,6 +42,9 @@ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoverySto
42
42
  import { ReorgSseAdapter, type ReorgHandlerInput } from './ReorgStream.js'
43
43
  import { Wallet, WalletSigner, WalletStorageManager, Services } from '@bsv/wallet-toolbox-client'
44
44
  import { createAuthMiddleware, type AuthRequest } from '@bsv/auth-express-middleware'
45
+ import { ArcadeProvider, isTerminalArcStatus, type ArcadeMerkleProof } from './ArcadeProvider.js'
46
+ import { ProviderChainBroadcaster, type NamedBroadcaster } from './ProviderChainBroadcaster.js'
47
+ import { ChaintracksProvider } from './ChaintracksProvider.js'
45
48
 
46
49
  /**
47
50
  * Knex database migration.
@@ -107,6 +110,7 @@ export interface EngineConfig {
107
110
  unprovenEvictionBlocks?: number
108
111
  reorgStreamUrl?: string
109
112
  reorgScanDepth?: number
113
+ unprovenMaintenanceIntervalMs?: number
110
114
  }
111
115
 
112
116
  export type HealthStatus = 'ok' | 'degraded' | 'error'
@@ -169,6 +173,17 @@ interface BASMCapableEngine extends Engine {
169
173
  startBASMSync: () => Promise<any>
170
174
  advanceTopicAnchorChains: (toHeight?: number) => Promise<void>
171
175
  evictUnprovenTransactions: (options?: { topic?: string, thresholdBlocks?: number }) => Promise<any>
176
+ refreshUnprovenTransactionProofs: (options: {
177
+ topic?: string
178
+ thresholdBlocks?: number
179
+ proofProvider: (txid: string) => Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined>
180
+ }) => Promise<any>
181
+ maintainUnprovenTransactions: (options: {
182
+ topic?: string
183
+ thresholdBlocks?: number
184
+ proofProvider: (txid: string) => Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined>
185
+ }) => Promise<any>
186
+ evictAppliedTransaction: (txid: string, options?: { topic?: string, reason?: string }) => Promise<any>
172
187
  handleReorg: (input: ReorgHandlerInput) => Promise<any>
173
188
  revalidateRecentAnchors: (depth?: number) => Promise<any>
174
189
  }
@@ -235,6 +250,12 @@ export default class OverlayExpress {
235
250
  // Handle for the BASM block-poll timer so it can be stopped.
236
251
  private basmBlockPollTimer?: ReturnType<typeof setInterval>
237
252
 
253
+ // How often (ms) to refresh proofs for old unproven rows and then evict rows
254
+ // that still have no proof. Set to 0 to disable background maintenance.
255
+ unprovenMaintenanceIntervalMs: number = 0
256
+
257
+ private unprovenMaintenanceTimer?: ReturnType<typeof setInterval>
258
+
238
259
  // Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
239
260
  // When set, reorgs are reconciled in real time; the block poll also runs a
240
261
  // revalidation sweep as a fallback / reconnect catch-up.
@@ -255,6 +276,15 @@ export default class OverlayExpress {
255
276
  // Optional ARC callback token for /arc-ingest notifications
256
277
  arcCallbackToken: string | undefined = undefined
257
278
 
279
+ // Optional Arcade URL/API key used for propagation, proof refresh, and
280
+ // go-chaintracks header/reorg access when available.
281
+ arcadeUrl: string | undefined = undefined
282
+ arcadeApiKey: string | undefined = undefined
283
+ arcadeDeploymentId: string | undefined = undefined
284
+ arcadeChaintracksApiPrefix: string = '/chaintracks/v2'
285
+
286
+ private arcadeProvider?: ArcadeProvider
287
+
258
288
  // Verbose request logging
259
289
  verboseRequestLogging: boolean = false
260
290
 
@@ -447,6 +477,50 @@ export default class OverlayExpress {
447
477
  this.logger.log(chalk.blue('ARC callback token has been configured.'))
448
478
  }
449
479
 
480
+ /**
481
+ * Configures Arcade for first-choice transaction propagation and proof lookup.
482
+ */
483
+ configureArcade (url: string, config: {
484
+ apiKey?: string
485
+ deploymentId?: string
486
+ chaintracksApiPrefix?: string
487
+ } = {}): void {
488
+ this.arcadeUrl = url
489
+ this.arcadeApiKey = config.apiKey
490
+ this.arcadeDeploymentId = config.deploymentId
491
+ if (config.chaintracksApiPrefix !== undefined) {
492
+ this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix
493
+ }
494
+ this.logger.log(chalk.blue('Arcade provider has been configured.'))
495
+ }
496
+
497
+ /**
498
+ * Configures a go-chaintracks compatible service for header validation and
499
+ * BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
500
+ */
501
+ configureChaintracks (url: string, config: {
502
+ apiPrefix?: string
503
+ reorgStream?: boolean
504
+ scanDepth?: number
505
+ } = {}): void {
506
+ const apiPrefix = config.apiPrefix ?? '/chaintracks/v2'
507
+ const client = new ChaintracksProvider(url, { apiPrefix })
508
+ this.configureChainTracker(client)
509
+ this.configureTopicAnchorHeaderResolver(async blockHeight => {
510
+ const header = await client.findHeaderForHeight(blockHeight)
511
+ if (header === undefined) return undefined
512
+ return {
513
+ blockHeight,
514
+ blockHash: header.hash,
515
+ merkleRoot: header.merkleRoot
516
+ }
517
+ })
518
+ if (config.reorgStream !== false) {
519
+ this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth)
520
+ }
521
+ this.logger.log(chalk.blue('go-chaintracks provider has been configured.'))
522
+ }
523
+
450
524
  /**
451
525
  * Enables or disables GASP synchronization (high-level setting).
452
526
  * This is a broad toggle that can be overridden or customized through syncConfiguration.
@@ -498,6 +572,20 @@ export default class OverlayExpress {
498
572
  this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'))
499
573
  }
500
574
 
575
+ /**
576
+ * Configures periodic unproven maintenance. Each run first tries configured
577
+ * proof providers, then evicts rows that are still unproven past the threshold.
578
+ */
579
+ configureUnprovenMaintenance (config: { intervalMs?: number, thresholdBlocks?: number }): void {
580
+ if (config.intervalMs !== undefined) {
581
+ this.unprovenMaintenanceIntervalMs = config.intervalMs
582
+ }
583
+ if (config.thresholdBlocks !== undefined) {
584
+ this.unprovenEvictionBlocks = config.thresholdBlocks
585
+ }
586
+ this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'))
587
+ }
588
+
501
589
  /**
502
590
  * Configures how often the BASM anchor chain is extended with empty anchors to
503
591
  * follow the chain tip. Set to 0 to disable periodic polling.
@@ -677,7 +765,7 @@ export default class OverlayExpress {
677
765
  syncConfig,
678
766
  this.engineConfig.logTime ?? false,
679
767
  this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
680
- this.engineConfig.throwOnBroadcastFailure ?? false,
768
+ this.engineConfig.throwOnBroadcastFailure ?? true,
681
769
  this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
682
770
  this.logger,
683
771
  this.engineConfig.suppressDefaultSyncAdvertisements ?? true,
@@ -721,15 +809,85 @@ export default class OverlayExpress {
721
809
  return syncConfig
722
810
  }
723
811
 
724
- /** Build the ARC broadcaster if an API key is configured. */
812
+ /** Build the configured transaction propagation provider chain. */
725
813
  private buildBroadcaster (): Broadcaster | undefined {
726
- if (typeof this.arcApiKey !== 'string') return undefined
727
- const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
728
- return new ARC(arcUrl, {
729
- apiKey: this.arcApiKey,
814
+ const providers: NamedBroadcaster[] = []
815
+ const callbackUrl = `https://${this.advertisableFQDN}/arc-ingest`
816
+
817
+ if (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0) {
818
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
819
+ apiKey: this.arcadeApiKey,
820
+ callbackUrl,
821
+ callbackToken: this.arcCallbackToken,
822
+ deploymentId: this.arcadeDeploymentId
823
+ })
824
+ providers.push({
825
+ name: 'Arcade',
826
+ broadcaster: this.arcadeProvider
827
+ })
828
+ } else {
829
+ this.arcadeProvider = undefined
830
+ }
831
+
832
+ if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
833
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
834
+ providers.push({
835
+ name: 'ARC',
836
+ broadcaster: new ARC(arcUrl, {
837
+ apiKey: this.arcApiKey,
838
+ callbackUrl,
839
+ callbackToken: this.arcCallbackToken
840
+ })
841
+ })
842
+ }
843
+
844
+ if (providers.length === 0) return undefined
845
+ if (providers.length === 1) return providers[0].broadcaster
846
+ return new ProviderChainBroadcaster(providers)
847
+ }
848
+
849
+ private ensureArcadeProvider (): ArcadeProvider | undefined {
850
+ if (this.arcadeProvider !== undefined) return this.arcadeProvider
851
+ if (typeof this.arcadeUrl !== 'string' || this.arcadeUrl.length === 0) return undefined
852
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
853
+ apiKey: this.arcadeApiKey,
730
854
  callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
731
- callbackToken: this.arcCallbackToken
855
+ callbackToken: this.arcCallbackToken,
856
+ deploymentId: this.arcadeDeploymentId
732
857
  })
858
+ return this.arcadeProvider
859
+ }
860
+
861
+ private async fetchArcadeProof (txid: string): Promise<ArcadeMerkleProof | undefined> {
862
+ const provider = this.ensureArcadeProvider()
863
+ if (provider === undefined) return undefined
864
+ const proof = await provider.fetchMerkleProof(txid)
865
+ if (proof === undefined) return undefined
866
+ const chainTracker = this.engineConfig.chainTracker ?? this.chainTracker
867
+ if (chainTracker === 'scripts only') {
868
+ throw new Error('Cannot validate Arcade proof with scripts-only chain tracker')
869
+ }
870
+ const blockHeight = proof.blockHeight ?? proof.merklePath.blockHeight
871
+ if (blockHeight === undefined) {
872
+ throw new Error(`Arcade proof for ${txid} did not include a block height`)
873
+ }
874
+ const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight)
875
+ if (!valid) {
876
+ throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`)
877
+ }
878
+ return {
879
+ ...proof,
880
+ blockHeight
881
+ }
882
+ }
883
+
884
+ private async fetchConfiguredMerkleProof (txid: string): Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined> {
885
+ const proof = await this.fetchArcadeProof(txid)
886
+ if (proof === undefined) return undefined
887
+ return {
888
+ merklePath: proof.merklePath,
889
+ blockHeight: proof.blockHeight
890
+ }
733
891
  }
734
892
 
735
893
  /** Build the BASM block header resolver. */
@@ -1417,8 +1575,11 @@ export default class OverlayExpress {
1417
1575
  })
1418
1576
  })
1419
1577
 
1420
- // ARC ingest route (only if we have an ARC API key)
1421
- if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
1578
+ // ARC/Arcade ingest route (only if a provider is configured)
1579
+ if (
1580
+ (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1581
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)
1582
+ ) {
1422
1583
  this.app.post('/arc-ingest', (req, res) => {
1423
1584
  ; (async () => {
1424
1585
  try {
@@ -1434,9 +1595,44 @@ export default class OverlayExpress {
1434
1595
  return res.status(401).json({ status: 'error', message: 'Unauthorized callback' })
1435
1596
  }
1436
1597
  }
1437
- const { txid, merklePath: merklePathHex, blockHeight } = req.body
1598
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body
1599
+ if (typeof txid !== 'string' || txid === '') {
1600
+ throw new TypeError('Provider callback is missing txid')
1601
+ }
1602
+ if (isTerminalArcStatus(txStatus, extraInfo)) {
1603
+ const report = await (engine as BASMCapableEngine).evictAppliedTransaction(txid, {
1604
+ topic: typeof topic === 'string' ? topic : undefined,
1605
+ reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1606
+ })
1607
+ this.logger.warn({
1608
+ operation: 'overlay.provider_callback',
1609
+ outcome: 'terminal_evicted',
1610
+ txid,
1611
+ txStatus,
1612
+ competingTxs,
1613
+ report
1614
+ })
1615
+ return res.status(200).json({
1616
+ status: 'success',
1617
+ message: 'Terminal transaction status processed',
1618
+ data: {
1619
+ ...report,
1620
+ txStatus,
1621
+ competingTxs
1622
+ }
1623
+ })
1624
+ }
1625
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1626
+ return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' })
1627
+ }
1438
1628
  const merklePath = MerklePath.fromHex(merklePathHex)
1439
1629
  await engine.handleNewMerkleProof(txid, merklePath, blockHeight)
1630
+ this.logger.log({
1631
+ operation: 'overlay.provider_callback',
1632
+ outcome: 'proof_ingested',
1633
+ txid,
1634
+ blockHeight
1635
+ })
1440
1636
  return res.status(200).json({ status: 'success', message: 'Transaction status updated' })
1441
1637
  } catch (error) {
1442
1638
  console.error(chalk.red('Error in /arc-ingest:'), error)
@@ -1453,7 +1649,7 @@ export default class OverlayExpress {
1453
1649
  })
1454
1650
  })
1455
1651
  } else {
1456
- this.logger.warn(chalk.yellow('Disabling ARC because no ARC API key was provided.'))
1652
+ this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'))
1457
1653
  }
1458
1654
 
1459
1655
  // GASP sync routes if enabled
@@ -2000,9 +2196,39 @@ export default class OverlayExpress {
2000
2196
  topic: typeof topic === 'string' ? topic : undefined,
2001
2197
  thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
2002
2198
  })
2199
+ this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report })
2003
2200
  return { status: 'success', message: 'Unproven eviction completed', data: report }
2004
2201
  }, checkAdminAuth as any)
2005
2202
 
2203
+ /**
2204
+ * Admin route to refresh proofs for expired unproven topic transactions
2205
+ * using the configured proof providers.
2206
+ */
2207
+ registerJsonRoute('/admin/refreshUnprovenProofs', async req => {
2208
+ const { topic, thresholdBlocks } = req.body ?? {}
2209
+ const report = await basmEngine.refreshUnprovenTransactionProofs({
2210
+ topic: typeof topic === 'string' ? topic : undefined,
2211
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
2212
+ proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2213
+ })
2214
+ this.logger.log({ operation: 'overlay.unproven_proof_refresh', outcome: 'ok', report })
2215
+ return { status: 'success', message: 'Unproven proof refresh completed', data: report }
2216
+ }, checkAdminAuth as any)
2217
+
2218
+ /**
2219
+ * Admin route to refresh proofs first, then evict rows that remain unproven.
2220
+ */
2221
+ registerJsonRoute('/admin/maintainUnproven', async req => {
2222
+ const { topic, thresholdBlocks } = req.body ?? {}
2223
+ const report = await basmEngine.maintainUnprovenTransactions({
2224
+ topic: typeof topic === 'string' ? topic : undefined,
2225
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
2226
+ proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2227
+ })
2228
+ this.logger.log({ operation: 'overlay.unproven_maintenance', outcome: 'ok', report })
2229
+ return { status: 'success', message: 'Unproven maintenance completed', data: report }
2230
+ }, checkAdminAuth as any)
2231
+
2006
2232
  /**
2007
2233
  * Admin route to evict an outpoint, either from all services or a specific one.
2008
2234
  */
@@ -2118,6 +2344,7 @@ export default class OverlayExpress {
2118
2344
 
2119
2345
  await this.runGaspStartupSync()
2120
2346
  await this.runBasmStartupSync()
2347
+ this.startUnprovenMaintenance()
2121
2348
  }
2122
2349
 
2123
2350
  /** Attempt a GASP sync at startup when enabled. */
@@ -2205,4 +2432,25 @@ export default class OverlayExpress {
2205
2432
  console.error(chalk.red('Failed to revalidate BASM anchors'), e)
2206
2433
  }
2207
2434
  }
2435
+
2436
+ private startUnprovenMaintenance (): void {
2437
+ const intervalMs = this.engineConfig.unprovenMaintenanceIntervalMs ?? this.unprovenMaintenanceIntervalMs
2438
+ if (intervalMs <= 0) return
2439
+ const run = (): void => {
2440
+ void (async () => {
2441
+ try {
2442
+ const report = await (this.engine as BASMCapableEngine | undefined)?.maintainUnprovenTransactions({
2443
+ thresholdBlocks: this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks,
2444
+ proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2445
+ })
2446
+ this.logger.log(chalk.green('Unproven transaction maintenance complete'), report)
2447
+ } catch (e) {
2448
+ console.error(chalk.red('Failed to maintain unproven transactions'), e)
2449
+ }
2450
+ })()
2451
+ }
2452
+ run()
2453
+ this.unprovenMaintenanceTimer = setInterval(run, intervalMs)
2454
+ this.unprovenMaintenanceTimer.unref?.()
2455
+ }
2208
2456
  }
@@ -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