@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
@@ -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,10 +173,33 @@ 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
  }
175
190
 
191
+ function parseTopicsHeader (header: string): string[] {
192
+ const value = header.trim()
193
+ const parsed: unknown = value.startsWith('[')
194
+ ? JSON.parse(value)
195
+ : value.split(',').map(topic => topic.trim())
196
+
197
+ if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
198
+ throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array')
199
+ }
200
+ return parsed
201
+ }
202
+
176
203
  /**
177
204
  * OverlayExpress class provides an Express-based server for hosting Overlay Services.
178
205
  * It allows configuration of various components like databases, topic managers, and lookup services.
@@ -235,6 +262,12 @@ export default class OverlayExpress {
235
262
  // Handle for the BASM block-poll timer so it can be stopped.
236
263
  private basmBlockPollTimer?: ReturnType<typeof setInterval>
237
264
 
265
+ // How often (ms) to refresh proofs for old unproven rows and then evict rows
266
+ // that still have no proof. Set to 0 to disable background maintenance.
267
+ unprovenMaintenanceIntervalMs: number = 0
268
+
269
+ private unprovenMaintenanceTimer?: ReturnType<typeof setInterval>
270
+
238
271
  // Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
239
272
  // When set, reorgs are reconciled in real time; the block poll also runs a
240
273
  // revalidation sweep as a fallback / reconnect catch-up.
@@ -255,6 +288,15 @@ export default class OverlayExpress {
255
288
  // Optional ARC callback token for /arc-ingest notifications
256
289
  arcCallbackToken: string | undefined = undefined
257
290
 
291
+ // Optional Arcade URL/API key used for propagation, proof refresh, and
292
+ // go-chaintracks header/reorg access when available.
293
+ arcadeUrl: string | undefined = undefined
294
+ arcadeApiKey: string | undefined = undefined
295
+ arcadeDeploymentId: string | undefined = undefined
296
+ arcadeChaintracksApiPrefix: string = '/chaintracks/v2'
297
+
298
+ private arcadeProvider?: ArcadeProvider
299
+
258
300
  // Verbose request logging
259
301
  verboseRequestLogging: boolean = false
260
302
 
@@ -447,6 +489,50 @@ export default class OverlayExpress {
447
489
  this.logger.log(chalk.blue('ARC callback token has been configured.'))
448
490
  }
449
491
 
492
+ /**
493
+ * Configures Arcade for first-choice transaction propagation and proof lookup.
494
+ */
495
+ configureArcade (url: string, config: {
496
+ apiKey?: string
497
+ deploymentId?: string
498
+ chaintracksApiPrefix?: string
499
+ } = {}): void {
500
+ this.arcadeUrl = url
501
+ this.arcadeApiKey = config.apiKey
502
+ this.arcadeDeploymentId = config.deploymentId
503
+ if (config.chaintracksApiPrefix !== undefined) {
504
+ this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix
505
+ }
506
+ this.logger.log(chalk.blue('Arcade provider has been configured.'))
507
+ }
508
+
509
+ /**
510
+ * Configures a go-chaintracks compatible service for header validation and
511
+ * BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
512
+ */
513
+ configureChaintracks (url: string, config: {
514
+ apiPrefix?: string
515
+ reorgStream?: boolean
516
+ scanDepth?: number
517
+ } = {}): void {
518
+ const apiPrefix = config.apiPrefix ?? '/chaintracks/v2'
519
+ const client = new ChaintracksProvider(url, { apiPrefix })
520
+ this.configureChainTracker(client)
521
+ this.configureTopicAnchorHeaderResolver(async blockHeight => {
522
+ const header = await client.findHeaderForHeight(blockHeight)
523
+ if (header === undefined) return undefined
524
+ return {
525
+ blockHeight,
526
+ blockHash: header.hash,
527
+ merkleRoot: header.merkleRoot
528
+ }
529
+ })
530
+ if (config.reorgStream !== false) {
531
+ this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth)
532
+ }
533
+ this.logger.log(chalk.blue('go-chaintracks provider has been configured.'))
534
+ }
535
+
450
536
  /**
451
537
  * Enables or disables GASP synchronization (high-level setting).
452
538
  * This is a broad toggle that can be overridden or customized through syncConfiguration.
@@ -498,6 +584,20 @@ export default class OverlayExpress {
498
584
  this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'))
499
585
  }
500
586
 
587
+ /**
588
+ * Configures periodic unproven maintenance. Each run first tries configured
589
+ * proof providers, then evicts rows that are still unproven past the threshold.
590
+ */
591
+ configureUnprovenMaintenance (config: { intervalMs?: number, thresholdBlocks?: number }): void {
592
+ if (config.intervalMs !== undefined) {
593
+ this.unprovenMaintenanceIntervalMs = config.intervalMs
594
+ }
595
+ if (config.thresholdBlocks !== undefined) {
596
+ this.unprovenEvictionBlocks = config.thresholdBlocks
597
+ }
598
+ this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'))
599
+ }
600
+
501
601
  /**
502
602
  * Configures how often the BASM anchor chain is extended with empty anchors to
503
603
  * follow the chain tip. Set to 0 to disable periodic polling.
@@ -634,22 +734,29 @@ export default class OverlayExpress {
634
734
  const knex = this.ensureKnex()
635
735
 
636
736
  if (autoConfigureShipSlap) {
737
+ const mongoDb = this.ensureMongo()
738
+ const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb)
739
+ const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb)
740
+
741
+ // Run the one-time discovery migration before the engine can accept
742
+ // traffic, so a failed unique-index build is a visible startup failure.
743
+ await shipStorage.ensureIndexes()
744
+ await slapStorage.ensureIndexes()
745
+
637
746
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager())
638
747
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager())
639
- this.configureLookupServiceWithMongo('ls_ship', (db) => {
640
- const storage = new DiscoveryServices.SHIPStorage(db)
641
- const storageForLookup = this.banService === undefined
642
- ? storage
643
- : new BanAwareSHIPStorage(storage, this.banService, this.logger)
644
- return new DiscoveryServices.SHIPLookupService(storageForLookup as any)
645
- })
646
- this.configureLookupServiceWithMongo('ls_slap', (db) => {
647
- const storage = new DiscoveryServices.SLAPStorage(db)
648
- const storageForLookup = this.banService === undefined
649
- ? storage
650
- : new BanAwareSLAPStorage(storage, this.banService, this.logger)
651
- return new DiscoveryServices.SLAPLookupService(storageForLookup as any)
652
- })
748
+
749
+ const shipStorageForLookup = this.banService === undefined
750
+ ? shipStorage
751
+ : new BanAwareSHIPStorage(shipStorage, this.banService, this.logger)
752
+ const slapStorageForLookup = this.banService === undefined
753
+ ? slapStorage
754
+ : new BanAwareSLAPStorage(slapStorage, this.banService, this.logger)
755
+
756
+ this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup as any)
757
+ this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup as any)
758
+ this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'))
759
+ this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'))
653
760
  }
654
761
 
655
762
  this.wrapBanAwareServices()
@@ -677,7 +784,7 @@ export default class OverlayExpress {
677
784
  syncConfig,
678
785
  this.engineConfig.logTime ?? false,
679
786
  this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
680
- this.engineConfig.throwOnBroadcastFailure ?? false,
787
+ this.engineConfig.throwOnBroadcastFailure ?? true,
681
788
  this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
682
789
  this.logger,
683
790
  this.engineConfig.suppressDefaultSyncAdvertisements ?? true,
@@ -721,15 +828,85 @@ export default class OverlayExpress {
721
828
  return syncConfig
722
829
  }
723
830
 
724
- /** Build the ARC broadcaster if an API key is configured. */
831
+ /** Build the configured transaction propagation provider chain. */
725
832
  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,
833
+ const providers: NamedBroadcaster[] = []
834
+ const callbackUrl = `https://${this.advertisableFQDN}/arc-ingest`
835
+
836
+ if (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0) {
837
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
838
+ apiKey: this.arcadeApiKey,
839
+ callbackUrl,
840
+ callbackToken: this.arcCallbackToken,
841
+ deploymentId: this.arcadeDeploymentId
842
+ })
843
+ providers.push({
844
+ name: 'Arcade',
845
+ broadcaster: this.arcadeProvider
846
+ })
847
+ } else {
848
+ this.arcadeProvider = undefined
849
+ }
850
+
851
+ if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
852
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
853
+ providers.push({
854
+ name: 'ARC',
855
+ broadcaster: new ARC(arcUrl, {
856
+ apiKey: this.arcApiKey,
857
+ callbackUrl,
858
+ callbackToken: this.arcCallbackToken
859
+ })
860
+ })
861
+ }
862
+
863
+ if (providers.length === 0) return undefined
864
+ if (providers.length === 1) return providers[0].broadcaster
865
+ return new ProviderChainBroadcaster(providers)
866
+ }
867
+
868
+ private ensureArcadeProvider (): ArcadeProvider | undefined {
869
+ if (this.arcadeProvider !== undefined) return this.arcadeProvider
870
+ if (typeof this.arcadeUrl !== 'string' || this.arcadeUrl.length === 0) return undefined
871
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
872
+ apiKey: this.arcadeApiKey,
730
873
  callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
731
- callbackToken: this.arcCallbackToken
874
+ callbackToken: this.arcCallbackToken,
875
+ deploymentId: this.arcadeDeploymentId
732
876
  })
877
+ return this.arcadeProvider
878
+ }
879
+
880
+ private async fetchArcadeProof (txid: string): Promise<ArcadeMerkleProof | undefined> {
881
+ const provider = this.ensureArcadeProvider()
882
+ if (provider === undefined) return undefined
883
+ const proof = await provider.fetchMerkleProof(txid)
884
+ if (proof === undefined) return undefined
885
+ const chainTracker = this.engineConfig.chainTracker ?? this.chainTracker
886
+ if (chainTracker === 'scripts only') {
887
+ throw new Error('Cannot validate Arcade proof with scripts-only chain tracker')
888
+ }
889
+ const blockHeight = proof.blockHeight ?? proof.merklePath.blockHeight
890
+ if (blockHeight === undefined) {
891
+ throw new Error(`Arcade proof for ${txid} did not include a block height`)
892
+ }
893
+ const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight)
894
+ if (!valid) {
895
+ throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`)
896
+ }
897
+ return {
898
+ ...proof,
899
+ blockHeight
900
+ }
901
+ }
902
+
903
+ private async fetchConfiguredMerkleProof (txid: string): Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined> {
904
+ const proof = await this.fetchArcadeProof(txid)
905
+ if (proof === undefined) return undefined
906
+ return {
907
+ merklePath: proof.merklePath,
908
+ blockHeight: proof.blockHeight
909
+ }
733
910
  }
734
911
 
735
912
  /** Build the BASM block header resolver. */
@@ -1309,9 +1486,13 @@ export default class OverlayExpress {
1309
1486
  if (typeof topicsHeader !== 'string') {
1310
1487
  throw new TypeError('Missing x-topics header')
1311
1488
  }
1312
- const topics = JSON.parse(topicsHeader)
1489
+ const topics = parseTopicsHeader(topicsHeader)
1490
+ const body = req.body
1491
+ if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
1492
+ throw new TypeError('Missing or empty BEEF body')
1493
+ }
1313
1494
  let offChainValues: number[] | undefined
1314
- let beef = Array.from(req.body as number[])
1495
+ let beef = Array.from(body as number[])
1315
1496
  if (includesOffChain) {
1316
1497
  const r = new Utils.Reader(beef)
1317
1498
  const l = r.readVarIntNum()
@@ -1417,8 +1598,11 @@ export default class OverlayExpress {
1417
1598
  })
1418
1599
  })
1419
1600
 
1420
- // ARC ingest route (only if we have an ARC API key)
1421
- if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
1601
+ // ARC/Arcade ingest route (only if a provider is configured)
1602
+ if (
1603
+ (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1604
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)
1605
+ ) {
1422
1606
  this.app.post('/arc-ingest', (req, res) => {
1423
1607
  ; (async () => {
1424
1608
  try {
@@ -1434,9 +1618,44 @@ export default class OverlayExpress {
1434
1618
  return res.status(401).json({ status: 'error', message: 'Unauthorized callback' })
1435
1619
  }
1436
1620
  }
1437
- const { txid, merklePath: merklePathHex, blockHeight } = req.body
1621
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body
1622
+ if (typeof txid !== 'string' || txid === '') {
1623
+ throw new TypeError('Provider callback is missing txid')
1624
+ }
1625
+ if (isTerminalArcStatus(txStatus, extraInfo)) {
1626
+ const report = await (engine as BASMCapableEngine).evictAppliedTransaction(txid, {
1627
+ topic: typeof topic === 'string' ? topic : undefined,
1628
+ reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1629
+ })
1630
+ this.logger.warn({
1631
+ operation: 'overlay.provider_callback',
1632
+ outcome: 'terminal_evicted',
1633
+ txid,
1634
+ txStatus,
1635
+ competingTxs,
1636
+ report
1637
+ })
1638
+ return res.status(200).json({
1639
+ status: 'success',
1640
+ message: 'Terminal transaction status processed',
1641
+ data: {
1642
+ ...report,
1643
+ txStatus,
1644
+ competingTxs
1645
+ }
1646
+ })
1647
+ }
1648
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1649
+ return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' })
1650
+ }
1438
1651
  const merklePath = MerklePath.fromHex(merklePathHex)
1439
1652
  await engine.handleNewMerkleProof(txid, merklePath, blockHeight)
1653
+ this.logger.log({
1654
+ operation: 'overlay.provider_callback',
1655
+ outcome: 'proof_ingested',
1656
+ txid,
1657
+ blockHeight
1658
+ })
1440
1659
  return res.status(200).json({ status: 'success', message: 'Transaction status updated' })
1441
1660
  } catch (error) {
1442
1661
  console.error(chalk.red('Error in /arc-ingest:'), error)
@@ -1453,7 +1672,7 @@ export default class OverlayExpress {
1453
1672
  })
1454
1673
  })
1455
1674
  } else {
1456
- this.logger.warn(chalk.yellow('Disabling ARC because no ARC API key was provided.'))
1675
+ this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'))
1457
1676
  }
1458
1677
 
1459
1678
  // GASP sync routes if enabled
@@ -1786,7 +2005,7 @@ export default class OverlayExpress {
1786
2005
  this.app.post('/admin/health-check', checkAdminAuth as any, (req, res) => {
1787
2006
  ; (async () => {
1788
2007
  try {
1789
- const { url } = req.body
2008
+ const url = req.body?.url
1790
2009
  if (typeof url !== 'string' || url.length === 0) {
1791
2010
  return res.status(400).json({ status: 'error', message: 'url is required' })
1792
2011
  }
@@ -2000,9 +2219,39 @@ export default class OverlayExpress {
2000
2219
  topic: typeof topic === 'string' ? topic : undefined,
2001
2220
  thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
2002
2221
  })
2222
+ this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report })
2003
2223
  return { status: 'success', message: 'Unproven eviction completed', data: report }
2004
2224
  }, checkAdminAuth as any)
2005
2225
 
2226
+ /**
2227
+ * Admin route to refresh proofs for expired unproven topic transactions
2228
+ * using the configured proof providers.
2229
+ */
2230
+ registerJsonRoute('/admin/refreshUnprovenProofs', async req => {
2231
+ const { topic, thresholdBlocks } = req.body ?? {}
2232
+ const report = await basmEngine.refreshUnprovenTransactionProofs({
2233
+ topic: typeof topic === 'string' ? topic : undefined,
2234
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
2235
+ proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2236
+ })
2237
+ this.logger.log({ operation: 'overlay.unproven_proof_refresh', outcome: 'ok', report })
2238
+ return { status: 'success', message: 'Unproven proof refresh completed', data: report }
2239
+ }, checkAdminAuth as any)
2240
+
2241
+ /**
2242
+ * Admin route to refresh proofs first, then evict rows that remain unproven.
2243
+ */
2244
+ registerJsonRoute('/admin/maintainUnproven', async req => {
2245
+ const { topic, thresholdBlocks } = req.body ?? {}
2246
+ const report = await basmEngine.maintainUnprovenTransactions({
2247
+ topic: typeof topic === 'string' ? topic : undefined,
2248
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
2249
+ proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2250
+ })
2251
+ this.logger.log({ operation: 'overlay.unproven_maintenance', outcome: 'ok', report })
2252
+ return { status: 'success', message: 'Unproven maintenance completed', data: report }
2253
+ }, checkAdminAuth as any)
2254
+
2006
2255
  /**
2007
2256
  * Admin route to evict an outpoint, either from all services or a specific one.
2008
2257
  */
@@ -2118,6 +2367,7 @@ export default class OverlayExpress {
2118
2367
 
2119
2368
  await this.runGaspStartupSync()
2120
2369
  await this.runBasmStartupSync()
2370
+ this.startUnprovenMaintenance()
2121
2371
  }
2122
2372
 
2123
2373
  /** Attempt a GASP sync at startup when enabled. */
@@ -2205,4 +2455,25 @@ export default class OverlayExpress {
2205
2455
  console.error(chalk.red('Failed to revalidate BASM anchors'), e)
2206
2456
  }
2207
2457
  }
2458
+
2459
+ private startUnprovenMaintenance (): void {
2460
+ const intervalMs = this.engineConfig.unprovenMaintenanceIntervalMs ?? this.unprovenMaintenanceIntervalMs
2461
+ if (intervalMs <= 0) return
2462
+ const run = (): void => {
2463
+ void (async () => {
2464
+ try {
2465
+ const report = await (this.engine as BASMCapableEngine | undefined)?.maintainUnprovenTransactions({
2466
+ thresholdBlocks: this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks,
2467
+ proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2468
+ })
2469
+ this.logger.log(chalk.green('Unproven transaction maintenance complete'), report)
2470
+ } catch (e) {
2471
+ console.error(chalk.red('Failed to maintain unproven transactions'), e)
2472
+ }
2473
+ })()
2474
+ }
2475
+ run()
2476
+ this.unprovenMaintenanceTimer = setInterval(run, intervalMs)
2477
+ this.unprovenMaintenanceTimer.unref?.()
2478
+ }
2208
2479
  }