@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
@@ -17,6 +17,9 @@ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoverySto
17
17
  import { ReorgSseAdapter } from './ReorgStream.js';
18
18
  import { Wallet, WalletSigner, WalletStorageManager, Services } from '@bsv/wallet-toolbox-client';
19
19
  import { createAuthMiddleware } from '@bsv/auth-express-middleware';
20
+ import { ArcadeProvider, isTerminalArcStatus } from './ArcadeProvider.js';
21
+ import { ProviderChainBroadcaster } from './ProviderChainBroadcaster.js';
22
+ import { ChaintracksProvider } from './ChaintracksProvider.js';
20
23
  /**
21
24
  * In-memory migration source for Knex migrations.
22
25
  * Allows running migrations defined in code rather than files.
@@ -51,6 +54,16 @@ class InMemoryMigrationSource {
51
54
  return await Promise.resolve(migration);
52
55
  }
53
56
  }
57
+ function parseTopicsHeader(header) {
58
+ const value = header.trim();
59
+ const parsed = value.startsWith('[')
60
+ ? JSON.parse(value)
61
+ : value.split(',').map(topic => topic.trim());
62
+ if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
63
+ throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array');
64
+ }
65
+ return parsed;
66
+ }
54
67
  /**
55
68
  * OverlayExpress class provides an Express-based server for hosting Overlay Services.
56
69
  * It allows configuration of various components like databases, topic managers, and lookup services.
@@ -99,6 +112,10 @@ export default class OverlayExpress {
99
112
  basmBlockPollIntervalMs = 10 * 60 * 1000;
100
113
  // Handle for the BASM block-poll timer so it can be stopped.
101
114
  basmBlockPollTimer;
115
+ // How often (ms) to refresh proofs for old unproven rows and then evict rows
116
+ // that still have no proof. Set to 0 to disable background maintenance.
117
+ unprovenMaintenanceIntervalMs = 0;
118
+ unprovenMaintenanceTimer;
102
119
  // Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
103
120
  // When set, reorgs are reconciled in real time; the block poll also runs a
104
121
  // revalidation sweep as a fallback / reconnect catch-up.
@@ -113,6 +130,13 @@ export default class OverlayExpress {
113
130
  arcApiKey = undefined;
114
131
  // Optional ARC callback token for /arc-ingest notifications
115
132
  arcCallbackToken = undefined;
133
+ // Optional Arcade URL/API key used for propagation, proof refresh, and
134
+ // go-chaintracks header/reorg access when available.
135
+ arcadeUrl = undefined;
136
+ arcadeApiKey = undefined;
137
+ arcadeDeploymentId = undefined;
138
+ arcadeChaintracksApiPrefix = '/chaintracks/v2';
139
+ arcadeProvider;
116
140
  // Verbose request logging
117
141
  verboseRequestLogging = false;
118
142
  // Web UI configuration
@@ -274,6 +298,41 @@ export default class OverlayExpress {
274
298
  this.arcCallbackToken = token;
275
299
  this.logger.log(chalk.blue('ARC callback token has been configured.'));
276
300
  }
301
+ /**
302
+ * Configures Arcade for first-choice transaction propagation and proof lookup.
303
+ */
304
+ configureArcade(url, config = {}) {
305
+ this.arcadeUrl = url;
306
+ this.arcadeApiKey = config.apiKey;
307
+ this.arcadeDeploymentId = config.deploymentId;
308
+ if (config.chaintracksApiPrefix !== undefined) {
309
+ this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix;
310
+ }
311
+ this.logger.log(chalk.blue('Arcade provider has been configured.'));
312
+ }
313
+ /**
314
+ * Configures a go-chaintracks compatible service for header validation and
315
+ * BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
316
+ */
317
+ configureChaintracks(url, config = {}) {
318
+ const apiPrefix = config.apiPrefix ?? '/chaintracks/v2';
319
+ const client = new ChaintracksProvider(url, { apiPrefix });
320
+ this.configureChainTracker(client);
321
+ this.configureTopicAnchorHeaderResolver(async (blockHeight) => {
322
+ const header = await client.findHeaderForHeight(blockHeight);
323
+ if (header === undefined)
324
+ return undefined;
325
+ return {
326
+ blockHeight,
327
+ blockHash: header.hash,
328
+ merkleRoot: header.merkleRoot
329
+ };
330
+ });
331
+ if (config.reorgStream !== false) {
332
+ this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth);
333
+ }
334
+ this.logger.log(chalk.blue('go-chaintracks provider has been configured.'));
335
+ }
277
336
  /**
278
337
  * Enables or disables GASP synchronization (high-level setting).
279
338
  * This is a broad toggle that can be overridden or customized through syncConfiguration.
@@ -320,6 +379,19 @@ export default class OverlayExpress {
320
379
  }
321
380
  this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'));
322
381
  }
382
+ /**
383
+ * Configures periodic unproven maintenance. Each run first tries configured
384
+ * proof providers, then evicts rows that are still unproven past the threshold.
385
+ */
386
+ configureUnprovenMaintenance(config) {
387
+ if (config.intervalMs !== undefined) {
388
+ this.unprovenMaintenanceIntervalMs = config.intervalMs;
389
+ }
390
+ if (config.thresholdBlocks !== undefined) {
391
+ this.unprovenEvictionBlocks = config.thresholdBlocks;
392
+ }
393
+ this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'));
394
+ }
323
395
  /**
324
396
  * Configures how often the BASM anchor chain is extended with empty anchors to
325
397
  * follow the chain tip. Set to 0 to disable periodic polling.
@@ -441,22 +513,25 @@ export default class OverlayExpress {
441
513
  async configureEngine(autoConfigureShipSlap = true) {
442
514
  const knex = this.ensureKnex();
443
515
  if (autoConfigureShipSlap) {
516
+ const mongoDb = this.ensureMongo();
517
+ const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb);
518
+ const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb);
519
+ // Run the one-time discovery migration before the engine can accept
520
+ // traffic, so a failed unique-index build is a visible startup failure.
521
+ await shipStorage.ensureIndexes();
522
+ await slapStorage.ensureIndexes();
444
523
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
445
524
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
446
- this.configureLookupServiceWithMongo('ls_ship', (db) => {
447
- const storage = new DiscoveryServices.SHIPStorage(db);
448
- const storageForLookup = this.banService === undefined
449
- ? storage
450
- : new BanAwareSHIPStorage(storage, this.banService, this.logger);
451
- return new DiscoveryServices.SHIPLookupService(storageForLookup);
452
- });
453
- this.configureLookupServiceWithMongo('ls_slap', (db) => {
454
- const storage = new DiscoveryServices.SLAPStorage(db);
455
- const storageForLookup = this.banService === undefined
456
- ? storage
457
- : new BanAwareSLAPStorage(storage, this.banService, this.logger);
458
- return new DiscoveryServices.SLAPLookupService(storageForLookup);
459
- });
525
+ const shipStorageForLookup = this.banService === undefined
526
+ ? shipStorage
527
+ : new BanAwareSHIPStorage(shipStorage, this.banService, this.logger);
528
+ const slapStorageForLookup = this.banService === undefined
529
+ ? slapStorage
530
+ : new BanAwareSLAPStorage(slapStorage, this.banService, this.logger);
531
+ this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup);
532
+ this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup);
533
+ this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'));
534
+ this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'));
460
535
  }
461
536
  this.wrapBanAwareServices();
462
537
  const syncConfig = this.buildSyncConfig();
@@ -467,7 +542,7 @@ export default class OverlayExpress {
467
542
  const EngineWithBASM = Engine;
468
543
  this.engine = new EngineWithBASM(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
469
544
  ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
470
- : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? false, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks);
545
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? true, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks);
471
546
  this.initServerWallet();
472
547
  this.logger.log(chalk.green('Engine has been configured.'));
473
548
  }
@@ -501,16 +576,87 @@ export default class OverlayExpress {
501
576
  }
502
577
  return syncConfig;
503
578
  }
504
- /** Build the ARC broadcaster if an API key is configured. */
579
+ /** Build the configured transaction propagation provider chain. */
505
580
  buildBroadcaster() {
506
- if (typeof this.arcApiKey !== 'string')
581
+ const providers = [];
582
+ const callbackUrl = `https://${this.advertisableFQDN}/arc-ingest`;
583
+ if (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0) {
584
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
585
+ apiKey: this.arcadeApiKey,
586
+ callbackUrl,
587
+ callbackToken: this.arcCallbackToken,
588
+ deploymentId: this.arcadeDeploymentId
589
+ });
590
+ providers.push({
591
+ name: 'Arcade',
592
+ broadcaster: this.arcadeProvider
593
+ });
594
+ }
595
+ else {
596
+ this.arcadeProvider = undefined;
597
+ }
598
+ if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
599
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
600
+ providers.push({
601
+ name: 'ARC',
602
+ broadcaster: new ARC(arcUrl, {
603
+ apiKey: this.arcApiKey,
604
+ callbackUrl,
605
+ callbackToken: this.arcCallbackToken
606
+ })
607
+ });
608
+ }
609
+ if (providers.length === 0)
610
+ return undefined;
611
+ if (providers.length === 1)
612
+ return providers[0].broadcaster;
613
+ return new ProviderChainBroadcaster(providers);
614
+ }
615
+ ensureArcadeProvider() {
616
+ if (this.arcadeProvider !== undefined)
617
+ return this.arcadeProvider;
618
+ if (typeof this.arcadeUrl !== 'string' || this.arcadeUrl.length === 0)
507
619
  return undefined;
508
- const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
509
- return new ARC(arcUrl, {
510
- apiKey: this.arcApiKey,
620
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
621
+ apiKey: this.arcadeApiKey,
511
622
  callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
512
- callbackToken: this.arcCallbackToken
623
+ callbackToken: this.arcCallbackToken,
624
+ deploymentId: this.arcadeDeploymentId
513
625
  });
626
+ return this.arcadeProvider;
627
+ }
628
+ async fetchArcadeProof(txid) {
629
+ const provider = this.ensureArcadeProvider();
630
+ if (provider === undefined)
631
+ return undefined;
632
+ const proof = await provider.fetchMerkleProof(txid);
633
+ if (proof === undefined)
634
+ return undefined;
635
+ const chainTracker = this.engineConfig.chainTracker ?? this.chainTracker;
636
+ if (chainTracker === 'scripts only') {
637
+ throw new Error('Cannot validate Arcade proof with scripts-only chain tracker');
638
+ }
639
+ const blockHeight = proof.blockHeight ?? proof.merklePath.blockHeight;
640
+ if (blockHeight === undefined) {
641
+ throw new Error(`Arcade proof for ${txid} did not include a block height`);
642
+ }
643
+ const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight);
644
+ if (!valid) {
645
+ throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`);
646
+ }
647
+ return {
648
+ ...proof,
649
+ blockHeight
650
+ };
651
+ }
652
+ async fetchConfiguredMerkleProof(txid) {
653
+ const proof = await this.fetchArcadeProof(txid);
654
+ if (proof === undefined)
655
+ return undefined;
656
+ return {
657
+ merklePath: proof.merklePath,
658
+ blockHeight: proof.blockHeight
659
+ };
514
660
  }
515
661
  /** Build the BASM block header resolver. */
516
662
  buildTopicAnchorHeaderResolver() {
@@ -1049,9 +1195,13 @@ export default class OverlayExpress {
1049
1195
  if (typeof topicsHeader !== 'string') {
1050
1196
  throw new TypeError('Missing x-topics header');
1051
1197
  }
1052
- const topics = JSON.parse(topicsHeader);
1198
+ const topics = parseTopicsHeader(topicsHeader);
1199
+ const body = req.body;
1200
+ if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
1201
+ throw new TypeError('Missing or empty BEEF body');
1202
+ }
1053
1203
  let offChainValues;
1054
- let beef = Array.from(req.body);
1204
+ let beef = Array.from(body);
1055
1205
  if (includesOffChain) {
1056
1206
  const r = new Utils.Reader(beef);
1057
1207
  const l = r.readVarIntNum();
@@ -1149,8 +1299,9 @@ export default class OverlayExpress {
1149
1299
  });
1150
1300
  });
1151
1301
  });
1152
- // ARC ingest route (only if we have an ARC API key)
1153
- if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
1302
+ // ARC/Arcade ingest route (only if a provider is configured)
1303
+ if ((typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1304
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)) {
1154
1305
  this.app.post('/arc-ingest', (req, res) => {
1155
1306
  ;
1156
1307
  (async () => {
@@ -1167,9 +1318,44 @@ export default class OverlayExpress {
1167
1318
  return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1168
1319
  }
1169
1320
  }
1170
- const { txid, merklePath: merklePathHex, blockHeight } = req.body;
1321
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1322
+ if (typeof txid !== 'string' || txid === '') {
1323
+ throw new TypeError('Provider callback is missing txid');
1324
+ }
1325
+ if (isTerminalArcStatus(txStatus, extraInfo)) {
1326
+ const report = await engine.evictAppliedTransaction(txid, {
1327
+ topic: typeof topic === 'string' ? topic : undefined,
1328
+ reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1329
+ });
1330
+ this.logger.warn({
1331
+ operation: 'overlay.provider_callback',
1332
+ outcome: 'terminal_evicted',
1333
+ txid,
1334
+ txStatus,
1335
+ competingTxs,
1336
+ report
1337
+ });
1338
+ return res.status(200).json({
1339
+ status: 'success',
1340
+ message: 'Terminal transaction status processed',
1341
+ data: {
1342
+ ...report,
1343
+ txStatus,
1344
+ competingTxs
1345
+ }
1346
+ });
1347
+ }
1348
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1349
+ return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' });
1350
+ }
1171
1351
  const merklePath = MerklePath.fromHex(merklePathHex);
1172
1352
  await engine.handleNewMerkleProof(txid, merklePath, blockHeight);
1353
+ this.logger.log({
1354
+ operation: 'overlay.provider_callback',
1355
+ outcome: 'proof_ingested',
1356
+ txid,
1357
+ blockHeight
1358
+ });
1173
1359
  return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
1174
1360
  }
1175
1361
  catch (error) {
@@ -1188,7 +1374,7 @@ export default class OverlayExpress {
1188
1374
  });
1189
1375
  }
1190
1376
  else {
1191
- this.logger.warn(chalk.yellow('Disabling ARC because no ARC API key was provided.'));
1377
+ this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'));
1192
1378
  }
1193
1379
  // GASP sync routes if enabled
1194
1380
  if (this.enableGASPSync) {
@@ -1493,7 +1679,7 @@ export default class OverlayExpress {
1493
1679
  ;
1494
1680
  (async () => {
1495
1681
  try {
1496
- const { url } = req.body;
1682
+ const url = req.body?.url;
1497
1683
  if (typeof url !== 'string' || url.length === 0) {
1498
1684
  return res.status(400).json({ status: 'error', message: 'url is required' });
1499
1685
  }
@@ -1704,8 +1890,36 @@ export default class OverlayExpress {
1704
1890
  topic: typeof topic === 'string' ? topic : undefined,
1705
1891
  thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
1706
1892
  });
1893
+ this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report });
1707
1894
  return { status: 'success', message: 'Unproven eviction completed', data: report };
1708
1895
  }, checkAdminAuth);
1896
+ /**
1897
+ * Admin route to refresh proofs for expired unproven topic transactions
1898
+ * using the configured proof providers.
1899
+ */
1900
+ registerJsonRoute('/admin/refreshUnprovenProofs', async (req) => {
1901
+ const { topic, thresholdBlocks } = req.body ?? {};
1902
+ const report = await basmEngine.refreshUnprovenTransactionProofs({
1903
+ topic: typeof topic === 'string' ? topic : undefined,
1904
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
1905
+ proofProvider: async (txid) => await this.fetchConfiguredMerkleProof(txid)
1906
+ });
1907
+ this.logger.log({ operation: 'overlay.unproven_proof_refresh', outcome: 'ok', report });
1908
+ return { status: 'success', message: 'Unproven proof refresh completed', data: report };
1909
+ }, checkAdminAuth);
1910
+ /**
1911
+ * Admin route to refresh proofs first, then evict rows that remain unproven.
1912
+ */
1913
+ registerJsonRoute('/admin/maintainUnproven', async (req) => {
1914
+ const { topic, thresholdBlocks } = req.body ?? {};
1915
+ const report = await basmEngine.maintainUnprovenTransactions({
1916
+ topic: typeof topic === 'string' ? topic : undefined,
1917
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
1918
+ proofProvider: async (txid) => await this.fetchConfiguredMerkleProof(txid)
1919
+ });
1920
+ this.logger.log({ operation: 'overlay.unproven_maintenance', outcome: 'ok', report });
1921
+ return { status: 'success', message: 'Unproven maintenance completed', data: report };
1922
+ }, checkAdminAuth);
1709
1923
  /**
1710
1924
  * Admin route to evict an outpoint, either from all services or a specific one.
1711
1925
  */
@@ -1815,6 +2029,7 @@ export default class OverlayExpress {
1815
2029
  }
1816
2030
  await this.runGaspStartupSync();
1817
2031
  await this.runBasmStartupSync();
2032
+ this.startUnprovenMaintenance();
1818
2033
  }
1819
2034
  /** Attempt a GASP sync at startup when enabled. */
1820
2035
  async runGaspStartupSync() {
@@ -1899,5 +2114,27 @@ export default class OverlayExpress {
1899
2114
  console.error(chalk.red('Failed to revalidate BASM anchors'), e);
1900
2115
  }
1901
2116
  }
2117
+ startUnprovenMaintenance() {
2118
+ const intervalMs = this.engineConfig.unprovenMaintenanceIntervalMs ?? this.unprovenMaintenanceIntervalMs;
2119
+ if (intervalMs <= 0)
2120
+ return;
2121
+ const run = () => {
2122
+ void (async () => {
2123
+ try {
2124
+ const report = await this.engine?.maintainUnprovenTransactions({
2125
+ thresholdBlocks: this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks,
2126
+ proofProvider: async (txid) => await this.fetchConfiguredMerkleProof(txid)
2127
+ });
2128
+ this.logger.log(chalk.green('Unproven transaction maintenance complete'), report);
2129
+ }
2130
+ catch (e) {
2131
+ console.error(chalk.red('Failed to maintain unproven transactions'), e);
2132
+ }
2133
+ })();
2134
+ };
2135
+ run();
2136
+ this.unprovenMaintenanceTimer = setInterval(run, intervalMs);
2137
+ this.unprovenMaintenanceTimer.unref?.();
2138
+ }
1902
2139
  }
1903
2140
  //# sourceMappingURL=OverlayExpress.js.map