@bsv/overlay-express 2.3.0 → 2.4.0

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 (51) hide show
  1. package/dist/cjs/mod.js +7 -1
  2. package/dist/cjs/mod.js.map +1 -1
  3. package/dist/cjs/package.json +15 -7
  4. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  6. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  8. package/dist/cjs/src/OverlayExpress.js +348 -95
  9. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  10. package/dist/cjs/src/OverlayMonitor.js +166 -8
  11. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  12. package/dist/cjs/src/ReorgStream.js +193 -0
  13. package/dist/cjs/src/ReorgStream.js.map +1 -0
  14. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  15. package/dist/esm/mod.js +3 -1
  16. package/dist/esm/mod.js.map +1 -1
  17. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  19. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  20. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  21. package/dist/esm/src/OverlayExpress.js +348 -93
  22. package/dist/esm/src/OverlayExpress.js.map +1 -1
  23. package/dist/esm/src/OverlayMonitor.js +160 -6
  24. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  25. package/dist/esm/src/ReorgStream.js +190 -0
  26. package/dist/esm/src/ReorgStream.js.map +1 -0
  27. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  28. package/dist/types/mod.d.ts +4 -2
  29. package/dist/types/mod.d.ts.map +1 -1
  30. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  32. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  34. package/dist/types/src/OverlayExpress.d.ts +76 -4
  35. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  36. package/dist/types/src/OverlayMonitor.d.ts +45 -1
  37. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  38. package/dist/types/src/ReorgStream.d.ts +74 -0
  39. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  40. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  41. package/mod.ts +7 -1
  42. package/package.json +15 -7
  43. package/src/BanAwareDiscoveryStorage.ts +91 -0
  44. package/src/BanAwareTopicManager.ts +87 -0
  45. package/src/OverlayExpress.ts +431 -100
  46. package/src/OverlayMonitor.ts +219 -7
  47. package/src/ReorgStream.ts +221 -0
  48. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  49. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  50. package/src/__tests__/OverlayMonitor.test.ts +66 -1
  51. package/src/__tests__/ReorgStream.test.ts +66 -0
@@ -50,6 +50,9 @@ const uuid_1 = require("uuid");
50
50
  const JanitorService_js_1 = require("./JanitorService.js");
51
51
  const BanService_js_1 = require("./BanService.js");
52
52
  const BanAwareLookupWrapper_js_1 = require("./BanAwareLookupWrapper.js");
53
+ const BanAwareTopicManager_js_1 = require("./BanAwareTopicManager.js");
54
+ const BanAwareDiscoveryStorage_js_1 = require("./BanAwareDiscoveryStorage.js");
55
+ const ReorgStream_js_1 = require("./ReorgStream.js");
53
56
  const wallet_toolbox_client_1 = require("@bsv/wallet-toolbox-client");
54
57
  const auth_express_middleware_1 = require("@bsv/auth-express-middleware");
55
58
  /**
@@ -121,6 +124,17 @@ class OverlayExpress {
121
124
  // Enable GASP Sync
122
125
  // (We allow an on/off toggle, but also can do advanced custom sync config below)
123
126
  this.enableGASPSync = true;
127
+ // Enable BRC-136 BASM sync. Off by default; endpoints remain available when
128
+ // storage supports anchors.
129
+ this.enableBASMSync = false;
130
+ // Opt-in unproven eviction default threshold in blocks.
131
+ this.unprovenEvictionBlocks = 144;
132
+ // How often (ms) to poll the chain tip and extend each topic's BASM anchor
133
+ // chain with empty anchors, so the cumulative TAC advances "after each new
134
+ // block" per BRC-136. Set to 0 to disable polling (startup extension still runs).
135
+ this.basmBlockPollIntervalMs = 10 * 60 * 1000;
136
+ // Depth (in blocks from the tip) for the reorg revalidation sweep.
137
+ this.reorgScanDepth = 3;
124
138
  // ARC API Key
125
139
  this.arcApiKey = undefined;
126
140
  // Optional ARC callback token for /arc-ingest notifications
@@ -272,6 +286,51 @@ class OverlayExpress {
272
286
  this.enableGASPSync = enable;
273
287
  this.logger.log(chalk_1.default.blue(`GASP synchronization ${enable ? 'enabled' : 'disabled'}.`));
274
288
  }
289
+ /**
290
+ * Enables or disables BRC-136 BASM synchronization.
291
+ * BASM is opt-in because it requires direct proofs and block hash resolution.
292
+ */
293
+ configureEnableBASMSync(enable) {
294
+ this.enableBASMSync = enable;
295
+ this.logger.log(chalk_1.default.blue(`BASM synchronization ${enable ? 'enabled' : 'disabled'}.`));
296
+ }
297
+ /**
298
+ * Configures the block header resolver used to derive BASM block hashes.
299
+ */
300
+ configureTopicAnchorHeaderResolver(resolver) {
301
+ this.topicAnchorHeaderResolver = resolver;
302
+ this.logger.log(chalk_1.default.blue('BASM topic anchor header resolver has been configured.'));
303
+ }
304
+ /**
305
+ * Configures the go-chaintracks (Arcade) reorg SSE stream used to reconcile
306
+ * BASM anchors with blockchain reorganizations in real time.
307
+ * @param url - The reorg stream URL, e.g. `https://arcade.example/v2/reorg/stream`.
308
+ * @param scanDepth - Optional revalidation-sweep depth in blocks (default 3).
309
+ */
310
+ configureReorgStream(url, scanDepth) {
311
+ this.reorgStreamUrl = url;
312
+ if (scanDepth !== undefined) {
313
+ this.reorgScanDepth = scanDepth;
314
+ }
315
+ this.logger.log(chalk_1.default.blue('BASM reorg stream has been configured.'));
316
+ }
317
+ /**
318
+ * Configures the opt-in unproven state eviction threshold.
319
+ */
320
+ configureUnprovenEviction(config) {
321
+ if (config.thresholdBlocks !== undefined) {
322
+ this.unprovenEvictionBlocks = config.thresholdBlocks;
323
+ }
324
+ this.logger.log(chalk_1.default.blue('Unproven transaction eviction has been configured.'));
325
+ }
326
+ /**
327
+ * Configures how often the BASM anchor chain is extended with empty anchors to
328
+ * follow the chain tip. Set to 0 to disable periodic polling.
329
+ */
330
+ configureBASMBlockPollInterval(intervalMs) {
331
+ this.basmBlockPollIntervalMs = intervalMs;
332
+ this.logger.log(chalk_1.default.blue(`BASM block poll interval set to ${intervalMs}ms.`));
333
+ }
275
334
  /**
276
335
  * Enables or disables verbose request logging.
277
336
  * @param enable - true to enable, false to disable
@@ -376,20 +435,32 @@ class OverlayExpress {
376
435
  * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
377
436
  * Then it merges in any advanced engine config from `this.engineConfig`.
378
437
  *
379
- * When a BanService is available (from configureMongo), SHIP and SLAP lookup
380
- * services are automatically wrapped with BanAwareLookupWrapper to prevent
381
- * GASP from re-syncing banned tokens.
438
+ * When a BanService is available (from configureMongo), auto-configured SHIP
439
+ * and SLAP managers, discovery storage, and lookup services are wrapped so
440
+ * banned outputs are not admitted or indexed.
382
441
  *
383
442
  * @param autoConfigureShipSlap - Whether to auto-configure SHIP and SLAP services (default: true)
384
443
  */
385
444
  async configureEngine(autoConfigureShipSlap = true) {
386
- var _a, _b, _c, _d, _e, _f, _g;
445
+ var _a, _b, _c, _d, _e, _f, _g, _h, _j;
387
446
  const knex = this.ensureKnex();
388
447
  if (autoConfigureShipSlap) {
389
448
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
390
449
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
391
- this.configureLookupServiceWithMongo('ls_ship', (db) => new DiscoveryServices.SHIPLookupService(new DiscoveryServices.SHIPStorage(db)));
392
- this.configureLookupServiceWithMongo('ls_slap', (db) => new DiscoveryServices.SLAPLookupService(new DiscoveryServices.SLAPStorage(db)));
450
+ this.configureLookupServiceWithMongo('ls_ship', (db) => {
451
+ const storage = new DiscoveryServices.SHIPStorage(db);
452
+ const storageForLookup = this.banService === undefined
453
+ ? storage
454
+ : new BanAwareDiscoveryStorage_js_1.BanAwareSHIPStorage(storage, this.banService, this.logger);
455
+ return new DiscoveryServices.SHIPLookupService(storageForLookup);
456
+ });
457
+ this.configureLookupServiceWithMongo('ls_slap', (db) => {
458
+ const storage = new DiscoveryServices.SLAPStorage(db);
459
+ const storageForLookup = this.banService === undefined
460
+ ? storage
461
+ : new BanAwareDiscoveryStorage_js_1.BanAwareSLAPStorage(storage, this.banService, this.logger);
462
+ return new DiscoveryServices.SLAPLookupService(storageForLookup);
463
+ });
393
464
  }
394
465
  this.wrapBanAwareServices();
395
466
  const syncConfig = this.buildSyncConfig();
@@ -397,16 +468,24 @@ class OverlayExpress {
397
468
  this.migrationsToRun = [...overlay_1.KnexStorageMigrations.default, ...this.migrationsToRun];
398
469
  const broadcaster = this.buildBroadcaster();
399
470
  const advertiser = await this.buildAdvertiser();
400
- this.engine = new overlay_1.Engine(this.managers, this.services, storage, (_a = this.engineConfig.chainTracker) !== null && _a !== void 0 ? _a : this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
471
+ const EngineWithBASM = overlay_1.Engine;
472
+ this.engine = new EngineWithBASM(this.managers, this.services, storage, (_a = this.engineConfig.chainTracker) !== null && _a !== void 0 ? _a : this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
401
473
  ? ((_b = this.engineConfig.shipTrackers) !== null && _b !== void 0 ? _b : sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS)
402
- : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster !== null && broadcaster !== void 0 ? broadcaster : this.engineConfig.broadcaster, advertiser, syncConfig, (_c = this.engineConfig.logTime) !== null && _c !== void 0 ? _c : false, (_d = this.engineConfig.logPrefix) !== null && _d !== void 0 ? _d : '[OVERLAY_ENGINE] ', (_e = this.engineConfig.throwOnBroadcastFailure) !== null && _e !== void 0 ? _e : false, (_f = this.engineConfig.overlayBroadcastFacilitator) !== null && _f !== void 0 ? _f : new sdk_1.HTTPSOverlayBroadcastFacilitator(), this.logger, (_g = this.engineConfig.suppressDefaultSyncAdvertisements) !== null && _g !== void 0 ? _g : true);
474
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster !== null && broadcaster !== void 0 ? broadcaster : this.engineConfig.broadcaster, advertiser, syncConfig, (_c = this.engineConfig.logTime) !== null && _c !== void 0 ? _c : false, (_d = this.engineConfig.logPrefix) !== null && _d !== void 0 ? _d : '[OVERLAY_ENGINE] ', (_e = this.engineConfig.throwOnBroadcastFailure) !== null && _e !== void 0 ? _e : false, (_f = this.engineConfig.overlayBroadcastFacilitator) !== null && _f !== void 0 ? _f : new sdk_1.HTTPSOverlayBroadcastFacilitator(), this.logger, (_g = this.engineConfig.suppressDefaultSyncAdvertisements) !== null && _g !== void 0 ? _g : true, this.buildTopicAnchorHeaderResolver(), (_h = this.engineConfig.enableBASMSync) !== null && _h !== void 0 ? _h : this.enableBASMSync, (_j = this.engineConfig.unprovenEvictionBlocks) !== null && _j !== void 0 ? _j : this.unprovenEvictionBlocks);
403
475
  this.initServerWallet();
404
476
  this.logger.log(chalk_1.default.green('Engine has been configured.'));
405
477
  }
406
- /** Wrap SHIP/SLAP with ban-aware filter if BanService is configured. */
478
+ /** Wrap SHIP/SLAP managers and services with ban-aware filters if BanService is configured. */
407
479
  wrapBanAwareServices() {
408
480
  if (this.banService === undefined)
409
481
  return;
482
+ for (const key of ['tm_ship', 'tm_slap']) {
483
+ if (this.managers[key] !== undefined) {
484
+ const label = key === 'tm_ship' ? 'SHIP' : 'SLAP';
485
+ this.managers[key] = new BanAwareTopicManager_js_1.BanAwareTopicManager(this.managers[key], this.banService, label, this.logger);
486
+ this.logger.log(chalk_1.default.blue(`${label} topic manager wrapped with ban-aware filter.`));
487
+ }
488
+ }
410
489
  for (const key of ['ls_ship', 'ls_slap']) {
411
490
  if (this.services[key] !== undefined) {
412
491
  const label = key === 'ls_ship' ? 'SHIP' : 'SLAP';
@@ -438,6 +517,32 @@ class OverlayExpress {
438
517
  callbackToken: this.arcCallbackToken
439
518
  });
440
519
  }
520
+ /** Build the BASM block header resolver. */
521
+ buildTopicAnchorHeaderResolver() {
522
+ var _a;
523
+ const configured = (_a = this.engineConfig.topicAnchorHeaderResolver) !== null && _a !== void 0 ? _a : this.topicAnchorHeaderResolver;
524
+ if (configured !== undefined) {
525
+ return configured;
526
+ }
527
+ return async (blockHeight) => {
528
+ const response = await fetch(`https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
529
+ method: 'GET',
530
+ headers: { Accept: 'application/json' }
531
+ });
532
+ if (!response.ok) {
533
+ throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`);
534
+ }
535
+ const header = await response.json();
536
+ if (typeof header.hash !== 'string') {
537
+ throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`);
538
+ }
539
+ return {
540
+ blockHeight,
541
+ blockHash: header.hash,
542
+ merkleRoot: header.merkleroot
543
+ };
544
+ };
545
+ }
441
546
  /** Resolve the SLAP trackers from config or network defaults. */
442
547
  resolveSlapTrackers() {
443
548
  if (Array.isArray(this.engineConfig.slapTrackers))
@@ -732,86 +837,72 @@ class OverlayExpress {
732
837
  };
733
838
  return report;
734
839
  }
840
+ /**
841
+ * Renders a request or response body for verbose logging, truncating overly long payloads.
842
+ */
843
+ formatBodyForLog(body, tooLongLabel, okPrefix) {
844
+ let bodyString;
845
+ if (typeof body === 'object') {
846
+ bodyString = JSON.stringify(body, null, 2);
847
+ }
848
+ else if (Buffer.isBuffer(body)) {
849
+ bodyString = body.toString('utf8');
850
+ }
851
+ else {
852
+ bodyString = String(body);
853
+ }
854
+ return bodyString.length > 280
855
+ ? chalk_1.default.yellow(`(${tooLongLabel}, length: ${String(bodyString.length)} characters)`)
856
+ : chalk_1.default.green(`${okPrefix}\n${bodyString}`);
857
+ }
858
+ /**
859
+ * Installs middleware that verbosely logs incoming requests and outgoing responses.
860
+ */
861
+ setupVerboseRequestLogging() {
862
+ this.app.use((req, res, next) => {
863
+ const startTime = Date.now();
864
+ // Log incoming request details
865
+ this.logger.log(chalk_1.default.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
866
+ // Pretty-print headers
867
+ this.logger.log(chalk_1.default.cyan('Headers:'));
868
+ this.logger.log(node_util_1.default.inspect(req.headers, { colors: true, depth: null }));
869
+ // Handle request body
870
+ if (req.body != null && Object.keys(req.body).length > 0) {
871
+ this.logger.log(this.formatBodyForLog(req.body, 'Body too long to display', 'Request Body:'));
872
+ }
873
+ // Intercept the res.send method to log responses
874
+ const originalSend = res.send;
875
+ let responseBody;
876
+ res.send = function (body) {
877
+ responseBody = body;
878
+ return originalSend.call(this, body);
879
+ };
880
+ // Log outgoing response details after the response is finished
881
+ res.on('finish', () => {
882
+ const duration = Date.now() - startTime;
883
+ this.logger.log(chalk_1.default.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
884
+ this.logger.log(chalk_1.default.cyan('Response Headers:'));
885
+ this.logger.log(node_util_1.default.inspect(res.getHeaders(), { colors: true, depth: null }));
886
+ // Handle response body
887
+ if (responseBody != null) {
888
+ this.logger.log(this.formatBodyForLog(responseBody, 'Response body too long to display', 'Response Body:'));
889
+ }
890
+ });
891
+ next();
892
+ });
893
+ }
735
894
  /**
736
895
  * Starts the Express server.
737
896
  * Sets up routes and begins listening on the configured port.
738
897
  */
739
898
  async start() {
740
- var _a, _b, _c;
741
899
  const engine = this.ensureEngine();
742
900
  const knex = this.ensureKnex();
743
901
  this.startTime = new Date();
744
902
  this.app.use(body_parser_1.default.json({ limit: '1gb', type: 'application/json' }));
745
903
  this.app.use(body_parser_1.default.raw({ limit: '1gb', type: 'application/octet-stream' }));
746
904
  if (this.verboseRequestLogging) {
747
- this.app.use((req, res, next) => {
748
- const startTime = Date.now();
749
- // Log incoming request details
750
- this.logger.log(chalk_1.default.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
751
- // Pretty-print headers
752
- this.logger.log(chalk_1.default.cyan('Headers:'));
753
- this.logger.log(node_util_1.default.inspect(req.headers, { colors: true, depth: null }));
754
- // Handle request body
755
- if (req.body != null && Object.keys(req.body).length > 0) {
756
- let bodyContent;
757
- let bodyString;
758
- if (typeof req.body === 'object') {
759
- bodyString = JSON.stringify(req.body, null, 2);
760
- }
761
- else if (Buffer.isBuffer(req.body)) {
762
- bodyString = req.body.toString('utf8');
763
- }
764
- else {
765
- bodyString = String(req.body);
766
- }
767
- if (bodyString.length > 280) {
768
- bodyContent = chalk_1.default.yellow(`(Body too long to display, length: ${String(bodyString.length)} characters)`);
769
- }
770
- else {
771
- bodyContent = chalk_1.default.green(`Request Body:\n${String(bodyString)}`);
772
- }
773
- this.logger.log(bodyContent);
774
- }
775
- // Intercept the res.send method to log responses
776
- const originalSend = res.send;
777
- let responseBody;
778
- res.send = function (body) {
779
- responseBody = body;
780
- return originalSend.call(this, body);
781
- };
782
- // Log outgoing response details after the response is finished
783
- res.on('finish', () => {
784
- const duration = Date.now() - startTime;
785
- this.logger.log(chalk_1.default.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
786
- this.logger.log(chalk_1.default.cyan('Response Headers:'));
787
- this.logger.log(node_util_1.default.inspect(res.getHeaders(), { colors: true, depth: null }));
788
- // Handle response body
789
- if (responseBody != null) {
790
- let bodyContent;
791
- let bodyString;
792
- if (typeof responseBody === 'object') {
793
- bodyString = JSON.stringify(responseBody, null, 2);
794
- }
795
- else if (Buffer.isBuffer(responseBody)) {
796
- bodyString = responseBody.toString('utf8');
797
- }
798
- else if (typeof responseBody === 'string') {
799
- bodyString = responseBody;
800
- }
801
- else {
802
- bodyString = String(responseBody);
803
- }
804
- if (bodyString.length > 280) {
805
- bodyContent = chalk_1.default.yellow(`(Response body too long to display, length: ${String(bodyString.length)} characters)`);
806
- }
807
- else {
808
- bodyContent = chalk_1.default.green(`Response Body:\n${String(bodyString)}`);
809
- }
810
- this.logger.log(bodyContent);
811
- }
812
- });
813
- next();
814
- });
905
+ this.setupVerboseRequestLogging();
815
906
  }
816
907
  // Enable CORS
817
908
  this.app.use((req, res, next) => {
@@ -1160,6 +1251,62 @@ class OverlayExpress {
1160
1251
  else {
1161
1252
  this.logger.warn(chalk_1.default.yellow('GASP sync is disabled.'));
1162
1253
  }
1254
+ // BRC-136 BASM anchor and raw transaction endpoints.
1255
+ const basmEngine = engine;
1256
+ const readBasmTopic = (req) => {
1257
+ const header = req.headers['x-bsv-topic'];
1258
+ if (typeof header !== 'string' || header.length === 0) {
1259
+ throw new TypeError('Missing x-bsv-topic header');
1260
+ }
1261
+ return header;
1262
+ };
1263
+ /**
1264
+ * Registers a POST route whose handler resolves to the JSON payload returned
1265
+ * with HTTP 200. Any thrown error is logged and returned as HTTP 400, while
1266
+ * unexpected rejections fall back to HTTP 500. This consolidates the shared
1267
+ * async/try-catch boilerplate used by the BRC-136 BASM endpoints (and the
1268
+ * BASM-related admin endpoints, which additionally pass `checkAdminAuth`).
1269
+ */
1270
+ const registerJsonRoute = (path, handler, ...middleware) => {
1271
+ this.app.post(path, ...middleware, (req, res) => {
1272
+ ;
1273
+ (async () => {
1274
+ try {
1275
+ return res.status(200).json(await handler(req));
1276
+ }
1277
+ catch (error) {
1278
+ console.error(chalk_1.default.red(`Error in ${path}:`), error);
1279
+ return res.status(400).json({
1280
+ status: 'error',
1281
+ message: error instanceof Error ? error.message : 'An unknown error occurred'
1282
+ });
1283
+ }
1284
+ })().catch(() => {
1285
+ res.status(500).json({ status: 'error', message: 'Unexpected error' });
1286
+ });
1287
+ });
1288
+ };
1289
+ const requireTxids = (value) => {
1290
+ if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1291
+ throw new TypeError('txids must be an array of strings');
1292
+ }
1293
+ return value;
1294
+ };
1295
+ registerJsonRoute('/requestTopicAnchorTip', async (req) => await basmEngine.provideTopicAnchorTip(readBasmTopic(req)));
1296
+ registerJsonRoute('/requestTopicAnchorRange', async (req) => {
1297
+ const { fromHeight, toHeight } = req.body;
1298
+ return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), Number(fromHeight), Number(toHeight));
1299
+ });
1300
+ registerJsonRoute('/requestAdmittedList', async (req) => {
1301
+ const { blockHeight, blockHash } = req.body;
1302
+ return await basmEngine.provideAdmittedList(readBasmTopic(req), Number(blockHeight), typeof blockHash === 'string' ? blockHash : undefined);
1303
+ });
1304
+ registerJsonRoute('/requestCompoundMerklePath', async (req) => {
1305
+ const topic = readBasmTopic(req);
1306
+ const { blockHeight, txids } = req.body;
1307
+ return await basmEngine.provideCompoundMerklePath(topic, Number(blockHeight), requireTxids(txids));
1308
+ });
1309
+ registerJsonRoute('/requestRawTransactions', async (req) => await basmEngine.provideRawTransactions(requireTxids(req.body.txids)));
1163
1310
  /**
1164
1311
  * ============== ADMIN ROUTES ==============
1165
1312
  * These routes expose advanced engine operations.
@@ -1250,7 +1397,9 @@ class OverlayExpress {
1250
1397
  totalBans: banStats.totalBans,
1251
1398
  topicManagers: Object.keys(this.managers),
1252
1399
  lookupServices: Object.keys(this.services),
1253
- gaspSyncEnabled: this.enableGASPSync
1400
+ gaspSyncEnabled: this.enableGASPSync,
1401
+ basmSyncEnabled: this.enableBASMSync,
1402
+ unprovenEvictionBlocks: this.unprovenEvictionBlocks
1254
1403
  }
1255
1404
  });
1256
1405
  }
@@ -1552,6 +1701,25 @@ class OverlayExpress {
1552
1701
  });
1553
1702
  });
1554
1703
  });
1704
+ /**
1705
+ * Admin route to manually start BASM sync, calling `engine.startBASMSync()`.
1706
+ */
1707
+ registerJsonRoute('/admin/startBASMSync', async () => {
1708
+ const report = await basmEngine.startBASMSync();
1709
+ return { status: 'success', message: 'BASM sync started and completed', data: report };
1710
+ }, checkAdminAuth);
1711
+ /**
1712
+ * Admin route to evict expired unproven topic transactions.
1713
+ */
1714
+ registerJsonRoute('/admin/evictUnproven', async (req) => {
1715
+ var _a;
1716
+ const { topic, thresholdBlocks } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
1717
+ const report = await basmEngine.evictUnprovenTransactions({
1718
+ topic: typeof topic === 'string' ? topic : undefined,
1719
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
1720
+ });
1721
+ return { status: 'success', message: 'Unproven eviction completed', data: report };
1722
+ }, checkAdminAuth);
1555
1723
  /**
1556
1724
  * Admin route to evict an outpoint, either from all services or a specific one.
1557
1725
  */
@@ -1630,6 +1798,19 @@ class OverlayExpress {
1630
1798
  description: 'Route not found.'
1631
1799
  });
1632
1800
  });
1801
+ await this.runStartupSync();
1802
+ // Start listening on the configured port
1803
+ this.app.listen(this.port, () => {
1804
+ this.isListening = true;
1805
+ this.logger.log(chalk_1.default.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1806
+ });
1807
+ }
1808
+ /**
1809
+ * Runs the post-listen startup work: advertiser init, advertisement sync,
1810
+ * and the optional GASP/BASM background syncs.
1811
+ */
1812
+ async runStartupSync() {
1813
+ var _a, _b;
1633
1814
  // The legacy Ninja advertiser has a setLookupEngine method.
1634
1815
  if (((_a = this.engine) === null || _a === void 0 ? void 0 : _a.advertiser) instanceof DiscoveryServices.WalletAdvertiser) {
1635
1816
  this.logger.log(chalk_1.default.cyan(`${this.name} will now advertise with SHIP and SLAP as appropriate at FQDN: ${this.advertisableFQDN}`));
@@ -1647,25 +1828,97 @@ class OverlayExpress {
1647
1828
  catch (e) {
1648
1829
  this.logger.log(chalk_1.default.red('Error syncing advertisements:'), e);
1649
1830
  }
1650
- // Attempt to do GASP sync if enabled
1651
- if (this.enableGASPSync) {
1652
- try {
1653
- this.logger.log(chalk_1.default.green('Starting GASP sync...'));
1654
- await ((_c = this.engine) === null || _c === void 0 ? void 0 : _c.startGASPSync());
1655
- this.logger.log(chalk_1.default.green('GASP sync complete!'));
1656
- }
1657
- catch (e) {
1658
- console.error(chalk_1.default.red('Failed to GASP sync'), e);
1659
- }
1660
- }
1661
- else {
1831
+ await this.runGaspStartupSync();
1832
+ await this.runBasmStartupSync();
1833
+ }
1834
+ /** Attempt a GASP sync at startup when enabled. */
1835
+ async runGaspStartupSync() {
1836
+ var _a;
1837
+ if (!this.enableGASPSync) {
1662
1838
  this.logger.log(chalk_1.default.yellow(`${this.name} will not sync because GASP has been disabled.`));
1839
+ return;
1663
1840
  }
1664
- // Start listening on the configured port
1665
- this.app.listen(this.port, () => {
1666
- this.isListening = true;
1667
- this.logger.log(chalk_1.default.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1841
+ try {
1842
+ this.logger.log(chalk_1.default.green('Starting GASP sync...'));
1843
+ await ((_a = this.engine) === null || _a === void 0 ? void 0 : _a.startGASPSync());
1844
+ this.logger.log(chalk_1.default.green('GASP sync complete!'));
1845
+ }
1846
+ catch (e) {
1847
+ console.error(chalk_1.default.red('Failed to GASP sync'), e);
1848
+ }
1849
+ }
1850
+ /** Attempt a BASM sync at startup when enabled, then begin tip-following. */
1851
+ async runBasmStartupSync() {
1852
+ var _a;
1853
+ if (!(this.enableBASMSync || this.engineConfig.enableBASMSync === true)) {
1854
+ return;
1855
+ }
1856
+ try {
1857
+ this.logger.log(chalk_1.default.green('Starting BASM sync...'));
1858
+ const report = await ((_a = this.engine) === null || _a === void 0 ? void 0 : _a.startBASMSync());
1859
+ this.logger.log(chalk_1.default.green('BASM sync complete!'), report);
1860
+ }
1861
+ catch (e) {
1862
+ console.error(chalk_1.default.red('Failed to BASM sync'), e);
1863
+ }
1864
+ // Extend each topic's anchor chain to the current tip on startup, then keep
1865
+ // it following the tip so the cumulative TAC advances after each new block.
1866
+ await this.advanceBASMAnchorChains();
1867
+ this.startBASMBlockPolling();
1868
+ this.startBASMReorgStream();
1869
+ }
1870
+ /** Poll for new blocks to advance anchor chains and detect reorgs. */
1871
+ startBASMBlockPolling() {
1872
+ var _a, _b;
1873
+ if (this.basmBlockPollIntervalMs <= 0) {
1874
+ return;
1875
+ }
1876
+ this.basmBlockPollTimer = setInterval(() => {
1877
+ void this.advanceBASMAnchorChains();
1878
+ // Fallback reorg detection for chain trackers without a reorg stream,
1879
+ // and a safety net even when the SSE adapter is active.
1880
+ void this.revalidateBASMAnchors();
1881
+ }, this.basmBlockPollIntervalMs);
1882
+ (_b = (_a = this.basmBlockPollTimer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
1883
+ }
1884
+ /** Real-time reorg reconciliation via the go-chaintracks (Arcade) reorg SSE. */
1885
+ startBASMReorgStream() {
1886
+ var _a, _b;
1887
+ const reorgStreamUrl = (_a = this.engineConfig.reorgStreamUrl) !== null && _a !== void 0 ? _a : this.reorgStreamUrl;
1888
+ const reorgScanDepth = (_b = this.engineConfig.reorgScanDepth) !== null && _b !== void 0 ? _b : this.reorgScanDepth;
1889
+ if (reorgStreamUrl === undefined || reorgStreamUrl === '') {
1890
+ return;
1891
+ }
1892
+ const basmEngine = this.engine;
1893
+ this.reorgAdapter = new ReorgStream_js_1.ReorgSseAdapter({
1894
+ url: reorgStreamUrl,
1895
+ onReorg: async (input) => { await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.handleReorg(input)); },
1896
+ onConnect: async () => { await (basmEngine === null || basmEngine === void 0 ? void 0 : basmEngine.revalidateRecentAnchors(reorgScanDepth)); },
1897
+ logger: this.logger
1668
1898
  });
1899
+ this.reorgAdapter.start();
1900
+ this.logger.log(chalk_1.default.green(`BASM reorg stream listening at ${reorgStreamUrl}`));
1901
+ }
1902
+ /** Extend every topic's BASM anchor chain to the current chain tip. */
1903
+ async advanceBASMAnchorChains() {
1904
+ var _a;
1905
+ try {
1906
+ await ((_a = this.engine) === null || _a === void 0 ? void 0 : _a.advanceTopicAnchorChains());
1907
+ }
1908
+ catch (e) {
1909
+ console.error(chalk_1.default.red('Failed to advance BASM anchor chains'), e);
1910
+ }
1911
+ }
1912
+ /** Revalidate recent BASM anchors against the chain tracker, reconciling any reorg. */
1913
+ async revalidateBASMAnchors() {
1914
+ var _a, _b;
1915
+ try {
1916
+ const depth = (_a = this.engineConfig.reorgScanDepth) !== null && _a !== void 0 ? _a : this.reorgScanDepth;
1917
+ await ((_b = this.engine) === null || _b === void 0 ? void 0 : _b.revalidateRecentAnchors(depth));
1918
+ }
1919
+ catch (e) {
1920
+ console.error(chalk_1.default.red('Failed to revalidate BASM anchors'), e);
1921
+ }
1669
1922
  }
1670
1923
  }
1671
1924
  exports.default = OverlayExpress;