@bsv/overlay-express 2.3.0 → 2.3.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 (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 +4 -4
  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 +4 -4
  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
@@ -12,6 +12,9 @@ import { v4 as uuidv4 } from 'uuid';
12
12
  import { JanitorService } from './JanitorService.js';
13
13
  import { BanService } from './BanService.js';
14
14
  import { BanAwareLookupWrapper } from './BanAwareLookupWrapper.js';
15
+ import { BanAwareTopicManager } from './BanAwareTopicManager.js';
16
+ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoveryStorage.js';
17
+ import { ReorgSseAdapter } from './ReorgStream.js';
15
18
  import { Wallet, WalletSigner, WalletStorageManager, Services } from '@bsv/wallet-toolbox-client';
16
19
  import { createAuthMiddleware } from '@bsv/auth-express-middleware';
17
20
  /**
@@ -85,6 +88,27 @@ export default class OverlayExpress {
85
88
  // Enable GASP Sync
86
89
  // (We allow an on/off toggle, but also can do advanced custom sync config below)
87
90
  enableGASPSync = true;
91
+ // Enable BRC-136 BASM sync. Off by default; endpoints remain available when
92
+ // storage supports anchors.
93
+ enableBASMSync = false;
94
+ // Opt-in unproven eviction default threshold in blocks.
95
+ unprovenEvictionBlocks = 144;
96
+ // How often (ms) to poll the chain tip and extend each topic's BASM anchor
97
+ // chain with empty anchors, so the cumulative TAC advances "after each new
98
+ // block" per BRC-136. Set to 0 to disable polling (startup extension still runs).
99
+ basmBlockPollIntervalMs = 10 * 60 * 1000;
100
+ // Handle for the BASM block-poll timer so it can be stopped.
101
+ basmBlockPollTimer;
102
+ // Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
103
+ // When set, reorgs are reconciled in real time; the block poll also runs a
104
+ // revalidation sweep as a fallback / reconnect catch-up.
105
+ reorgStreamUrl;
106
+ // Depth (in blocks from the tip) for the reorg revalidation sweep.
107
+ reorgScanDepth = 3;
108
+ // Handle for the reorg SSE adapter.
109
+ reorgAdapter;
110
+ // Optional resolver for block hashes and header merkle roots used by BASM.
111
+ topicAnchorHeaderResolver;
88
112
  // ARC API Key
89
113
  arcApiKey = undefined;
90
114
  // Optional ARC callback token for /arc-ingest notifications
@@ -259,6 +283,51 @@ export default class OverlayExpress {
259
283
  this.enableGASPSync = enable;
260
284
  this.logger.log(chalk.blue(`GASP synchronization ${enable ? 'enabled' : 'disabled'}.`));
261
285
  }
286
+ /**
287
+ * Enables or disables BRC-136 BASM synchronization.
288
+ * BASM is opt-in because it requires direct proofs and block hash resolution.
289
+ */
290
+ configureEnableBASMSync(enable) {
291
+ this.enableBASMSync = enable;
292
+ this.logger.log(chalk.blue(`BASM synchronization ${enable ? 'enabled' : 'disabled'}.`));
293
+ }
294
+ /**
295
+ * Configures the block header resolver used to derive BASM block hashes.
296
+ */
297
+ configureTopicAnchorHeaderResolver(resolver) {
298
+ this.topicAnchorHeaderResolver = resolver;
299
+ this.logger.log(chalk.blue('BASM topic anchor header resolver has been configured.'));
300
+ }
301
+ /**
302
+ * Configures the go-chaintracks (Arcade) reorg SSE stream used to reconcile
303
+ * BASM anchors with blockchain reorganizations in real time.
304
+ * @param url - The reorg stream URL, e.g. `https://arcade.example/v2/reorg/stream`.
305
+ * @param scanDepth - Optional revalidation-sweep depth in blocks (default 3).
306
+ */
307
+ configureReorgStream(url, scanDepth) {
308
+ this.reorgStreamUrl = url;
309
+ if (scanDepth !== undefined) {
310
+ this.reorgScanDepth = scanDepth;
311
+ }
312
+ this.logger.log(chalk.blue('BASM reorg stream has been configured.'));
313
+ }
314
+ /**
315
+ * Configures the opt-in unproven state eviction threshold.
316
+ */
317
+ configureUnprovenEviction(config) {
318
+ if (config.thresholdBlocks !== undefined) {
319
+ this.unprovenEvictionBlocks = config.thresholdBlocks;
320
+ }
321
+ this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'));
322
+ }
323
+ /**
324
+ * Configures how often the BASM anchor chain is extended with empty anchors to
325
+ * follow the chain tip. Set to 0 to disable periodic polling.
326
+ */
327
+ configureBASMBlockPollInterval(intervalMs) {
328
+ this.basmBlockPollIntervalMs = intervalMs;
329
+ this.logger.log(chalk.blue(`BASM block poll interval set to ${intervalMs}ms.`));
330
+ }
262
331
  /**
263
332
  * Enables or disables verbose request logging.
264
333
  * @param enable - true to enable, false to disable
@@ -363,9 +432,9 @@ export default class OverlayExpress {
363
432
  * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
364
433
  * Then it merges in any advanced engine config from `this.engineConfig`.
365
434
  *
366
- * When a BanService is available (from configureMongo), SHIP and SLAP lookup
367
- * services are automatically wrapped with BanAwareLookupWrapper to prevent
368
- * GASP from re-syncing banned tokens.
435
+ * When a BanService is available (from configureMongo), auto-configured SHIP
436
+ * and SLAP managers, discovery storage, and lookup services are wrapped so
437
+ * banned outputs are not admitted or indexed.
369
438
  *
370
439
  * @param autoConfigureShipSlap - Whether to auto-configure SHIP and SLAP services (default: true)
371
440
  */
@@ -374,8 +443,20 @@ export default class OverlayExpress {
374
443
  if (autoConfigureShipSlap) {
375
444
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
376
445
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
377
- this.configureLookupServiceWithMongo('ls_ship', (db) => new DiscoveryServices.SHIPLookupService(new DiscoveryServices.SHIPStorage(db)));
378
- this.configureLookupServiceWithMongo('ls_slap', (db) => new DiscoveryServices.SLAPLookupService(new DiscoveryServices.SLAPStorage(db)));
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
+ });
379
460
  }
380
461
  this.wrapBanAwareServices();
381
462
  const syncConfig = this.buildSyncConfig();
@@ -383,16 +464,24 @@ export default class OverlayExpress {
383
464
  this.migrationsToRun = [...KnexStorageMigrations.default, ...this.migrationsToRun];
384
465
  const broadcaster = this.buildBroadcaster();
385
466
  const advertiser = await this.buildAdvertiser();
386
- this.engine = new Engine(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
467
+ const EngineWithBASM = Engine;
468
+ this.engine = new EngineWithBASM(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
387
469
  ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
388
- : 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);
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);
389
471
  this.initServerWallet();
390
472
  this.logger.log(chalk.green('Engine has been configured.'));
391
473
  }
392
- /** Wrap SHIP/SLAP with ban-aware filter if BanService is configured. */
474
+ /** Wrap SHIP/SLAP managers and services with ban-aware filters if BanService is configured. */
393
475
  wrapBanAwareServices() {
394
476
  if (this.banService === undefined)
395
477
  return;
478
+ for (const key of ['tm_ship', 'tm_slap']) {
479
+ if (this.managers[key] !== undefined) {
480
+ const label = key === 'tm_ship' ? 'SHIP' : 'SLAP';
481
+ this.managers[key] = new BanAwareTopicManager(this.managers[key], this.banService, label, this.logger);
482
+ this.logger.log(chalk.blue(`${label} topic manager wrapped with ban-aware filter.`));
483
+ }
484
+ }
396
485
  for (const key of ['ls_ship', 'ls_slap']) {
397
486
  if (this.services[key] !== undefined) {
398
487
  const label = key === 'ls_ship' ? 'SHIP' : 'SLAP';
@@ -423,6 +512,31 @@ export default class OverlayExpress {
423
512
  callbackToken: this.arcCallbackToken
424
513
  });
425
514
  }
515
+ /** Build the BASM block header resolver. */
516
+ buildTopicAnchorHeaderResolver() {
517
+ const configured = this.engineConfig.topicAnchorHeaderResolver ?? this.topicAnchorHeaderResolver;
518
+ if (configured !== undefined) {
519
+ return configured;
520
+ }
521
+ return async (blockHeight) => {
522
+ const response = await fetch(`https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
523
+ method: 'GET',
524
+ headers: { Accept: 'application/json' }
525
+ });
526
+ if (!response.ok) {
527
+ throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`);
528
+ }
529
+ const header = await response.json();
530
+ if (typeof header.hash !== 'string') {
531
+ throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`);
532
+ }
533
+ return {
534
+ blockHeight,
535
+ blockHash: header.hash,
536
+ merkleRoot: header.merkleroot
537
+ };
538
+ };
539
+ }
426
540
  /** Resolve the SLAP trackers from config or network defaults. */
427
541
  resolveSlapTrackers() {
428
542
  if (Array.isArray(this.engineConfig.slapTrackers))
@@ -712,6 +826,60 @@ export default class OverlayExpress {
712
826
  };
713
827
  return report;
714
828
  }
829
+ /**
830
+ * Renders a request or response body for verbose logging, truncating overly long payloads.
831
+ */
832
+ formatBodyForLog(body, tooLongLabel, okPrefix) {
833
+ let bodyString;
834
+ if (typeof body === 'object') {
835
+ bodyString = JSON.stringify(body, null, 2);
836
+ }
837
+ else if (Buffer.isBuffer(body)) {
838
+ bodyString = body.toString('utf8');
839
+ }
840
+ else {
841
+ bodyString = String(body);
842
+ }
843
+ return bodyString.length > 280
844
+ ? chalk.yellow(`(${tooLongLabel}, length: ${String(bodyString.length)} characters)`)
845
+ : chalk.green(`${okPrefix}\n${bodyString}`);
846
+ }
847
+ /**
848
+ * Installs middleware that verbosely logs incoming requests and outgoing responses.
849
+ */
850
+ setupVerboseRequestLogging() {
851
+ this.app.use((req, res, next) => {
852
+ const startTime = Date.now();
853
+ // Log incoming request details
854
+ this.logger.log(chalk.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
855
+ // Pretty-print headers
856
+ this.logger.log(chalk.cyan('Headers:'));
857
+ this.logger.log(util.inspect(req.headers, { colors: true, depth: null }));
858
+ // Handle request body
859
+ if (req.body != null && Object.keys(req.body).length > 0) {
860
+ this.logger.log(this.formatBodyForLog(req.body, 'Body too long to display', 'Request Body:'));
861
+ }
862
+ // Intercept the res.send method to log responses
863
+ const originalSend = res.send;
864
+ let responseBody;
865
+ res.send = function (body) {
866
+ responseBody = body;
867
+ return originalSend.call(this, body);
868
+ };
869
+ // Log outgoing response details after the response is finished
870
+ res.on('finish', () => {
871
+ const duration = Date.now() - startTime;
872
+ this.logger.log(chalk.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
873
+ this.logger.log(chalk.cyan('Response Headers:'));
874
+ this.logger.log(util.inspect(res.getHeaders(), { colors: true, depth: null }));
875
+ // Handle response body
876
+ if (responseBody != null) {
877
+ this.logger.log(this.formatBodyForLog(responseBody, 'Response body too long to display', 'Response Body:'));
878
+ }
879
+ });
880
+ next();
881
+ });
882
+ }
715
883
  /**
716
884
  * Starts the Express server.
717
885
  * Sets up routes and begins listening on the configured port.
@@ -723,74 +891,7 @@ export default class OverlayExpress {
723
891
  this.app.use(bodyParser.json({ limit: '1gb', type: 'application/json' }));
724
892
  this.app.use(bodyParser.raw({ limit: '1gb', type: 'application/octet-stream' }));
725
893
  if (this.verboseRequestLogging) {
726
- this.app.use((req, res, next) => {
727
- const startTime = Date.now();
728
- // Log incoming request details
729
- this.logger.log(chalk.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
730
- // Pretty-print headers
731
- this.logger.log(chalk.cyan('Headers:'));
732
- this.logger.log(util.inspect(req.headers, { colors: true, depth: null }));
733
- // Handle request body
734
- if (req.body != null && Object.keys(req.body).length > 0) {
735
- let bodyContent;
736
- let bodyString;
737
- if (typeof req.body === 'object') {
738
- bodyString = JSON.stringify(req.body, null, 2);
739
- }
740
- else if (Buffer.isBuffer(req.body)) {
741
- bodyString = req.body.toString('utf8');
742
- }
743
- else {
744
- bodyString = String(req.body);
745
- }
746
- if (bodyString.length > 280) {
747
- bodyContent = chalk.yellow(`(Body too long to display, length: ${String(bodyString.length)} characters)`);
748
- }
749
- else {
750
- bodyContent = chalk.green(`Request Body:\n${String(bodyString)}`);
751
- }
752
- this.logger.log(bodyContent);
753
- }
754
- // Intercept the res.send method to log responses
755
- const originalSend = res.send;
756
- let responseBody;
757
- res.send = function (body) {
758
- responseBody = body;
759
- return originalSend.call(this, body);
760
- };
761
- // Log outgoing response details after the response is finished
762
- res.on('finish', () => {
763
- const duration = Date.now() - startTime;
764
- this.logger.log(chalk.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
765
- this.logger.log(chalk.cyan('Response Headers:'));
766
- this.logger.log(util.inspect(res.getHeaders(), { colors: true, depth: null }));
767
- // Handle response body
768
- if (responseBody != null) {
769
- let bodyContent;
770
- let bodyString;
771
- if (typeof responseBody === 'object') {
772
- bodyString = JSON.stringify(responseBody, null, 2);
773
- }
774
- else if (Buffer.isBuffer(responseBody)) {
775
- bodyString = responseBody.toString('utf8');
776
- }
777
- else if (typeof responseBody === 'string') {
778
- bodyString = responseBody;
779
- }
780
- else {
781
- bodyString = String(responseBody);
782
- }
783
- if (bodyString.length > 280) {
784
- bodyContent = chalk.yellow(`(Response body too long to display, length: ${String(bodyString.length)} characters)`);
785
- }
786
- else {
787
- bodyContent = chalk.green(`Response Body:\n${String(bodyString)}`);
788
- }
789
- this.logger.log(bodyContent);
790
- }
791
- });
792
- next();
793
- });
894
+ this.setupVerboseRequestLogging();
794
895
  }
795
896
  // Enable CORS
796
897
  this.app.use((req, res, next) => {
@@ -1139,6 +1240,62 @@ export default class OverlayExpress {
1139
1240
  else {
1140
1241
  this.logger.warn(chalk.yellow('GASP sync is disabled.'));
1141
1242
  }
1243
+ // BRC-136 BASM anchor and raw transaction endpoints.
1244
+ const basmEngine = engine;
1245
+ const readBasmTopic = (req) => {
1246
+ const header = req.headers['x-bsv-topic'];
1247
+ if (typeof header !== 'string' || header.length === 0) {
1248
+ throw new TypeError('Missing x-bsv-topic header');
1249
+ }
1250
+ return header;
1251
+ };
1252
+ /**
1253
+ * Registers a POST route whose handler resolves to the JSON payload returned
1254
+ * with HTTP 200. Any thrown error is logged and returned as HTTP 400, while
1255
+ * unexpected rejections fall back to HTTP 500. This consolidates the shared
1256
+ * async/try-catch boilerplate used by the BRC-136 BASM endpoints (and the
1257
+ * BASM-related admin endpoints, which additionally pass `checkAdminAuth`).
1258
+ */
1259
+ const registerJsonRoute = (path, handler, ...middleware) => {
1260
+ this.app.post(path, ...middleware, (req, res) => {
1261
+ ;
1262
+ (async () => {
1263
+ try {
1264
+ return res.status(200).json(await handler(req));
1265
+ }
1266
+ catch (error) {
1267
+ console.error(chalk.red(`Error in ${path}:`), error);
1268
+ return res.status(400).json({
1269
+ status: 'error',
1270
+ message: error instanceof Error ? error.message : 'An unknown error occurred'
1271
+ });
1272
+ }
1273
+ })().catch(() => {
1274
+ res.status(500).json({ status: 'error', message: 'Unexpected error' });
1275
+ });
1276
+ });
1277
+ };
1278
+ const requireTxids = (value) => {
1279
+ if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1280
+ throw new TypeError('txids must be an array of strings');
1281
+ }
1282
+ return value;
1283
+ };
1284
+ registerJsonRoute('/requestTopicAnchorTip', async (req) => await basmEngine.provideTopicAnchorTip(readBasmTopic(req)));
1285
+ registerJsonRoute('/requestTopicAnchorRange', async (req) => {
1286
+ const { fromHeight, toHeight } = req.body;
1287
+ return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), Number(fromHeight), Number(toHeight));
1288
+ });
1289
+ registerJsonRoute('/requestAdmittedList', async (req) => {
1290
+ const { blockHeight, blockHash } = req.body;
1291
+ return await basmEngine.provideAdmittedList(readBasmTopic(req), Number(blockHeight), typeof blockHash === 'string' ? blockHash : undefined);
1292
+ });
1293
+ registerJsonRoute('/requestCompoundMerklePath', async (req) => {
1294
+ const topic = readBasmTopic(req);
1295
+ const { blockHeight, txids } = req.body;
1296
+ return await basmEngine.provideCompoundMerklePath(topic, Number(blockHeight), requireTxids(txids));
1297
+ });
1298
+ registerJsonRoute('/requestRawTransactions', async (req) => await basmEngine.provideRawTransactions(requireTxids(req.body.txids)));
1142
1299
  /**
1143
1300
  * ============== ADMIN ROUTES ==============
1144
1301
  * These routes expose advanced engine operations.
@@ -1227,7 +1384,9 @@ export default class OverlayExpress {
1227
1384
  totalBans: banStats.totalBans,
1228
1385
  topicManagers: Object.keys(this.managers),
1229
1386
  lookupServices: Object.keys(this.services),
1230
- gaspSyncEnabled: this.enableGASPSync
1387
+ gaspSyncEnabled: this.enableGASPSync,
1388
+ basmSyncEnabled: this.enableBASMSync,
1389
+ unprovenEvictionBlocks: this.unprovenEvictionBlocks
1231
1390
  }
1232
1391
  });
1233
1392
  }
@@ -1529,6 +1688,24 @@ export default class OverlayExpress {
1529
1688
  });
1530
1689
  });
1531
1690
  });
1691
+ /**
1692
+ * Admin route to manually start BASM sync, calling `engine.startBASMSync()`.
1693
+ */
1694
+ registerJsonRoute('/admin/startBASMSync', async () => {
1695
+ const report = await basmEngine.startBASMSync();
1696
+ return { status: 'success', message: 'BASM sync started and completed', data: report };
1697
+ }, checkAdminAuth);
1698
+ /**
1699
+ * Admin route to evict expired unproven topic transactions.
1700
+ */
1701
+ registerJsonRoute('/admin/evictUnproven', async (req) => {
1702
+ const { topic, thresholdBlocks } = req.body ?? {};
1703
+ const report = await basmEngine.evictUnprovenTransactions({
1704
+ topic: typeof topic === 'string' ? topic : undefined,
1705
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
1706
+ });
1707
+ return { status: 'success', message: 'Unproven eviction completed', data: report };
1708
+ }, checkAdminAuth);
1532
1709
  /**
1533
1710
  * Admin route to evict an outpoint, either from all services or a specific one.
1534
1711
  */
@@ -1607,6 +1784,18 @@ export default class OverlayExpress {
1607
1784
  description: 'Route not found.'
1608
1785
  });
1609
1786
  });
1787
+ await this.runStartupSync();
1788
+ // Start listening on the configured port
1789
+ this.app.listen(this.port, () => {
1790
+ this.isListening = true;
1791
+ this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1792
+ });
1793
+ }
1794
+ /**
1795
+ * Runs the post-listen startup work: advertiser init, advertisement sync,
1796
+ * and the optional GASP/BASM background syncs.
1797
+ */
1798
+ async runStartupSync() {
1610
1799
  // The legacy Ninja advertiser has a setLookupEngine method.
1611
1800
  if (this.engine?.advertiser instanceof DiscoveryServices.WalletAdvertiser) {
1612
1801
  this.logger.log(chalk.cyan(`${this.name} will now advertise with SHIP and SLAP as appropriate at FQDN: ${this.advertisableFQDN}`));
@@ -1624,25 +1813,91 @@ export default class OverlayExpress {
1624
1813
  catch (e) {
1625
1814
  this.logger.log(chalk.red('Error syncing advertisements:'), e);
1626
1815
  }
1627
- // Attempt to do GASP sync if enabled
1628
- if (this.enableGASPSync) {
1629
- try {
1630
- this.logger.log(chalk.green('Starting GASP sync...'));
1631
- await this.engine?.startGASPSync();
1632
- this.logger.log(chalk.green('GASP sync complete!'));
1633
- }
1634
- catch (e) {
1635
- console.error(chalk.red('Failed to GASP sync'), e);
1636
- }
1637
- }
1638
- else {
1816
+ await this.runGaspStartupSync();
1817
+ await this.runBasmStartupSync();
1818
+ }
1819
+ /** Attempt a GASP sync at startup when enabled. */
1820
+ async runGaspStartupSync() {
1821
+ if (!this.enableGASPSync) {
1639
1822
  this.logger.log(chalk.yellow(`${this.name} will not sync because GASP has been disabled.`));
1823
+ return;
1640
1824
  }
1641
- // Start listening on the configured port
1642
- this.app.listen(this.port, () => {
1643
- this.isListening = true;
1644
- this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1825
+ try {
1826
+ this.logger.log(chalk.green('Starting GASP sync...'));
1827
+ await this.engine?.startGASPSync();
1828
+ this.logger.log(chalk.green('GASP sync complete!'));
1829
+ }
1830
+ catch (e) {
1831
+ console.error(chalk.red('Failed to GASP sync'), e);
1832
+ }
1833
+ }
1834
+ /** Attempt a BASM sync at startup when enabled, then begin tip-following. */
1835
+ async runBasmStartupSync() {
1836
+ if (!(this.enableBASMSync || this.engineConfig.enableBASMSync === true)) {
1837
+ return;
1838
+ }
1839
+ try {
1840
+ this.logger.log(chalk.green('Starting BASM sync...'));
1841
+ const report = await this.engine?.startBASMSync();
1842
+ this.logger.log(chalk.green('BASM sync complete!'), report);
1843
+ }
1844
+ catch (e) {
1845
+ console.error(chalk.red('Failed to BASM sync'), e);
1846
+ }
1847
+ // Extend each topic's anchor chain to the current tip on startup, then keep
1848
+ // it following the tip so the cumulative TAC advances after each new block.
1849
+ await this.advanceBASMAnchorChains();
1850
+ this.startBASMBlockPolling();
1851
+ this.startBASMReorgStream();
1852
+ }
1853
+ /** Poll for new blocks to advance anchor chains and detect reorgs. */
1854
+ startBASMBlockPolling() {
1855
+ if (this.basmBlockPollIntervalMs <= 0) {
1856
+ return;
1857
+ }
1858
+ this.basmBlockPollTimer = setInterval(() => {
1859
+ void this.advanceBASMAnchorChains();
1860
+ // Fallback reorg detection for chain trackers without a reorg stream,
1861
+ // and a safety net even when the SSE adapter is active.
1862
+ void this.revalidateBASMAnchors();
1863
+ }, this.basmBlockPollIntervalMs);
1864
+ this.basmBlockPollTimer.unref?.();
1865
+ }
1866
+ /** Real-time reorg reconciliation via the go-chaintracks (Arcade) reorg SSE. */
1867
+ startBASMReorgStream() {
1868
+ const reorgStreamUrl = this.engineConfig.reorgStreamUrl ?? this.reorgStreamUrl;
1869
+ const reorgScanDepth = this.engineConfig.reorgScanDepth ?? this.reorgScanDepth;
1870
+ if (reorgStreamUrl === undefined || reorgStreamUrl === '') {
1871
+ return;
1872
+ }
1873
+ const basmEngine = this.engine;
1874
+ this.reorgAdapter = new ReorgSseAdapter({
1875
+ url: reorgStreamUrl,
1876
+ onReorg: async (input) => { await basmEngine?.handleReorg(input); },
1877
+ onConnect: async () => { await basmEngine?.revalidateRecentAnchors(reorgScanDepth); },
1878
+ logger: this.logger
1645
1879
  });
1880
+ this.reorgAdapter.start();
1881
+ this.logger.log(chalk.green(`BASM reorg stream listening at ${reorgStreamUrl}`));
1882
+ }
1883
+ /** Extend every topic's BASM anchor chain to the current chain tip. */
1884
+ async advanceBASMAnchorChains() {
1885
+ try {
1886
+ await this.engine?.advanceTopicAnchorChains();
1887
+ }
1888
+ catch (e) {
1889
+ console.error(chalk.red('Failed to advance BASM anchor chains'), e);
1890
+ }
1891
+ }
1892
+ /** Revalidate recent BASM anchors against the chain tracker, reconciling any reorg. */
1893
+ async revalidateBASMAnchors() {
1894
+ try {
1895
+ const depth = this.engineConfig.reorgScanDepth ?? this.reorgScanDepth;
1896
+ await this.engine?.revalidateRecentAnchors(depth);
1897
+ }
1898
+ catch (e) {
1899
+ console.error(chalk.red('Failed to revalidate BASM anchors'), e);
1900
+ }
1646
1901
  }
1647
1902
  }
1648
1903
  //# sourceMappingURL=OverlayExpress.js.map