@bsv/overlay-express 2.2.1 → 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 (53) hide show
  1. package/README.md +33 -0
  2. package/dist/cjs/mod.js +10 -1
  3. package/dist/cjs/mod.js.map +1 -1
  4. package/dist/cjs/package.json +12 -11
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  6. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  8. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  9. package/dist/cjs/src/OverlayExpress.js +375 -96
  10. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  11. package/dist/cjs/src/OverlayMonitor.js +464 -0
  12. package/dist/cjs/src/OverlayMonitor.js.map +1 -0
  13. package/dist/cjs/src/ReorgStream.js +193 -0
  14. package/dist/cjs/src/ReorgStream.js.map +1 -0
  15. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  16. package/dist/esm/mod.js +3 -0
  17. package/dist/esm/mod.js.map +1 -1
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  19. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  20. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  21. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  22. package/dist/esm/src/OverlayExpress.js +375 -94
  23. package/dist/esm/src/OverlayExpress.js.map +1 -1
  24. package/dist/esm/src/OverlayMonitor.js +458 -0
  25. package/dist/esm/src/OverlayMonitor.js.map +1 -0
  26. package/dist/esm/src/ReorgStream.js +190 -0
  27. package/dist/esm/src/ReorgStream.js.map +1 -0
  28. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  29. package/dist/types/mod.d.ts +4 -1
  30. package/dist/types/mod.d.ts.map +1 -1
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  32. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  34. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  35. package/dist/types/src/OverlayExpress.d.ts +82 -4
  36. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  37. package/dist/types/src/OverlayMonitor.d.ts +169 -0
  38. package/dist/types/src/OverlayMonitor.d.ts.map +1 -0
  39. package/dist/types/src/ReorgStream.d.ts +74 -0
  40. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  41. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  42. package/mod.ts +20 -1
  43. package/package.json +12 -11
  44. package/src/BanAwareDiscoveryStorage.ts +91 -0
  45. package/src/BanAwareTopicManager.ts +87 -0
  46. package/src/OverlayExpress.ts +461 -102
  47. package/src/OverlayMonitor.ts +657 -0
  48. package/src/ReorgStream.ts +221 -0
  49. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  50. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  51. package/src/__tests__/OverlayExpress.test.ts +86 -1
  52. package/src/__tests__/OverlayMonitor.test.ts +181 -0
  53. 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,8 +88,31 @@ 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;
114
+ // Optional ARC callback token for /arc-ingest notifications
115
+ arcCallbackToken = undefined;
90
116
  // Verbose request logging
91
117
  verboseRequestLogging = false;
92
118
  // Web UI configuration
@@ -240,6 +266,14 @@ export default class OverlayExpress {
240
266
  this.arcApiKey = apiKey;
241
267
  this.logger.log(chalk.blue('ARC API key has been configured.'));
242
268
  }
269
+ /**
270
+ * Configures the ARC callback token expected by /arc-ingest.
271
+ * @param token - The token ARC should present when posting callback notifications.
272
+ */
273
+ configureArcCallbackToken(token) {
274
+ this.arcCallbackToken = token;
275
+ this.logger.log(chalk.blue('ARC callback token has been configured.'));
276
+ }
243
277
  /**
244
278
  * Enables or disables GASP synchronization (high-level setting).
245
279
  * This is a broad toggle that can be overridden or customized through syncConfiguration.
@@ -249,6 +283,51 @@ export default class OverlayExpress {
249
283
  this.enableGASPSync = enable;
250
284
  this.logger.log(chalk.blue(`GASP synchronization ${enable ? 'enabled' : 'disabled'}.`));
251
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
+ }
252
331
  /**
253
332
  * Enables or disables verbose request logging.
254
333
  * @param enable - true to enable, false to disable
@@ -353,9 +432,9 @@ export default class OverlayExpress {
353
432
  * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
354
433
  * Then it merges in any advanced engine config from `this.engineConfig`.
355
434
  *
356
- * When a BanService is available (from configureMongo), SHIP and SLAP lookup
357
- * services are automatically wrapped with BanAwareLookupWrapper to prevent
358
- * 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.
359
438
  *
360
439
  * @param autoConfigureShipSlap - Whether to auto-configure SHIP and SLAP services (default: true)
361
440
  */
@@ -364,8 +443,20 @@ export default class OverlayExpress {
364
443
  if (autoConfigureShipSlap) {
365
444
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
366
445
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
367
- this.configureLookupServiceWithMongo('ls_ship', (db) => new DiscoveryServices.SHIPLookupService(new DiscoveryServices.SHIPStorage(db)));
368
- 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
+ });
369
460
  }
370
461
  this.wrapBanAwareServices();
371
462
  const syncConfig = this.buildSyncConfig();
@@ -373,16 +464,24 @@ export default class OverlayExpress {
373
464
  this.migrationsToRun = [...KnexStorageMigrations.default, ...this.migrationsToRun];
374
465
  const broadcaster = this.buildBroadcaster();
375
466
  const advertiser = await this.buildAdvertiser();
376
- 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'
377
469
  ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
378
- : 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);
379
471
  this.initServerWallet();
380
472
  this.logger.log(chalk.green('Engine has been configured.'));
381
473
  }
382
- /** 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. */
383
475
  wrapBanAwareServices() {
384
476
  if (this.banService === undefined)
385
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
+ }
386
485
  for (const key of ['ls_ship', 'ls_slap']) {
387
486
  if (this.services[key] !== undefined) {
388
487
  const label = key === 'ls_ship' ? 'SHIP' : 'SLAP';
@@ -407,7 +506,36 @@ export default class OverlayExpress {
407
506
  if (typeof this.arcApiKey !== 'string')
408
507
  return undefined;
409
508
  const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
410
- return new ARC(arcUrl, { apiKey: this.arcApiKey });
509
+ return new ARC(arcUrl, {
510
+ apiKey: this.arcApiKey,
511
+ callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
512
+ callbackToken: this.arcCallbackToken
513
+ });
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
+ };
411
539
  }
412
540
  /** Resolve the SLAP trackers from config or network defaults. */
413
541
  resolveSlapTrackers() {
@@ -698,6 +826,60 @@ export default class OverlayExpress {
698
826
  };
699
827
  return report;
700
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
+ }
701
883
  /**
702
884
  * Starts the Express server.
703
885
  * Sets up routes and begins listening on the configured port.
@@ -709,74 +891,7 @@ export default class OverlayExpress {
709
891
  this.app.use(bodyParser.json({ limit: '1gb', type: 'application/json' }));
710
892
  this.app.use(bodyParser.raw({ limit: '1gb', type: 'application/octet-stream' }));
711
893
  if (this.verboseRequestLogging) {
712
- this.app.use((req, res, next) => {
713
- const startTime = Date.now();
714
- // Log incoming request details
715
- this.logger.log(chalk.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
716
- // Pretty-print headers
717
- this.logger.log(chalk.cyan('Headers:'));
718
- this.logger.log(util.inspect(req.headers, { colors: true, depth: null }));
719
- // Handle request body
720
- if (req.body != null && Object.keys(req.body).length > 0) {
721
- let bodyContent;
722
- let bodyString;
723
- if (typeof req.body === 'object') {
724
- bodyString = JSON.stringify(req.body, null, 2);
725
- }
726
- else if (Buffer.isBuffer(req.body)) {
727
- bodyString = req.body.toString('utf8');
728
- }
729
- else {
730
- bodyString = String(req.body);
731
- }
732
- if (bodyString.length > 280) {
733
- bodyContent = chalk.yellow(`(Body too long to display, length: ${String(bodyString.length)} characters)`);
734
- }
735
- else {
736
- bodyContent = chalk.green(`Request Body:\n${String(bodyString)}`);
737
- }
738
- this.logger.log(bodyContent);
739
- }
740
- // Intercept the res.send method to log responses
741
- const originalSend = res.send;
742
- let responseBody;
743
- res.send = function (body) {
744
- responseBody = body;
745
- return originalSend.call(this, body);
746
- };
747
- // Log outgoing response details after the response is finished
748
- res.on('finish', () => {
749
- const duration = Date.now() - startTime;
750
- this.logger.log(chalk.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
751
- this.logger.log(chalk.cyan('Response Headers:'));
752
- this.logger.log(util.inspect(res.getHeaders(), { colors: true, depth: null }));
753
- // Handle response body
754
- if (responseBody != null) {
755
- let bodyContent;
756
- let bodyString;
757
- if (typeof responseBody === 'object') {
758
- bodyString = JSON.stringify(responseBody, null, 2);
759
- }
760
- else if (Buffer.isBuffer(responseBody)) {
761
- bodyString = responseBody.toString('utf8');
762
- }
763
- else if (typeof responseBody === 'string') {
764
- bodyString = responseBody;
765
- }
766
- else {
767
- bodyString = String(responseBody);
768
- }
769
- if (bodyString.length > 280) {
770
- bodyContent = chalk.yellow(`(Response body too long to display, length: ${String(bodyString.length)} characters)`);
771
- }
772
- else {
773
- bodyContent = chalk.green(`Response Body:\n${String(bodyString)}`);
774
- }
775
- this.logger.log(bodyContent);
776
- }
777
- });
778
- next();
779
- });
894
+ this.setupVerboseRequestLogging();
780
895
  }
781
896
  // Enable CORS
782
897
  this.app.use((req, res, next) => {
@@ -1040,6 +1155,18 @@ export default class OverlayExpress {
1040
1155
  ;
1041
1156
  (async () => {
1042
1157
  try {
1158
+ if (typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0) {
1159
+ const authorization = req.headers.authorization;
1160
+ const headerToken = Array.isArray(authorization) ? authorization[0] : authorization;
1161
+ const xCallbackToken = req.headers['x-callback-token'];
1162
+ const callbackToken = Array.isArray(xCallbackToken) ? xCallbackToken[0] : xCallbackToken;
1163
+ const bearerToken = typeof headerToken === 'string' && headerToken.startsWith('Bearer ')
1164
+ ? headerToken.slice('Bearer '.length)
1165
+ : headerToken;
1166
+ if (bearerToken !== this.arcCallbackToken && callbackToken !== this.arcCallbackToken) {
1167
+ return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1168
+ }
1169
+ }
1043
1170
  const { txid, merklePath: merklePathHex, blockHeight } = req.body;
1044
1171
  const merklePath = MerklePath.fromHex(merklePathHex);
1045
1172
  await engine.handleNewMerkleProof(txid, merklePath, blockHeight);
@@ -1113,6 +1240,62 @@ export default class OverlayExpress {
1113
1240
  else {
1114
1241
  this.logger.warn(chalk.yellow('GASP sync is disabled.'));
1115
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)));
1116
1299
  /**
1117
1300
  * ============== ADMIN ROUTES ==============
1118
1301
  * These routes expose advanced engine operations.
@@ -1201,7 +1384,9 @@ export default class OverlayExpress {
1201
1384
  totalBans: banStats.totalBans,
1202
1385
  topicManagers: Object.keys(this.managers),
1203
1386
  lookupServices: Object.keys(this.services),
1204
- gaspSyncEnabled: this.enableGASPSync
1387
+ gaspSyncEnabled: this.enableGASPSync,
1388
+ basmSyncEnabled: this.enableBASMSync,
1389
+ unprovenEvictionBlocks: this.unprovenEvictionBlocks
1205
1390
  }
1206
1391
  });
1207
1392
  }
@@ -1503,6 +1688,24 @@ export default class OverlayExpress {
1503
1688
  });
1504
1689
  });
1505
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);
1506
1709
  /**
1507
1710
  * Admin route to evict an outpoint, either from all services or a specific one.
1508
1711
  */
@@ -1581,6 +1784,18 @@ export default class OverlayExpress {
1581
1784
  description: 'Route not found.'
1582
1785
  });
1583
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() {
1584
1799
  // The legacy Ninja advertiser has a setLookupEngine method.
1585
1800
  if (this.engine?.advertiser instanceof DiscoveryServices.WalletAdvertiser) {
1586
1801
  this.logger.log(chalk.cyan(`${this.name} will now advertise with SHIP and SLAP as appropriate at FQDN: ${this.advertisableFQDN}`));
@@ -1598,25 +1813,91 @@ export default class OverlayExpress {
1598
1813
  catch (e) {
1599
1814
  this.logger.log(chalk.red('Error syncing advertisements:'), e);
1600
1815
  }
1601
- // Attempt to do GASP sync if enabled
1602
- if (this.enableGASPSync) {
1603
- try {
1604
- this.logger.log(chalk.green('Starting GASP sync...'));
1605
- await this.engine?.startGASPSync();
1606
- this.logger.log(chalk.green('GASP sync complete!'));
1607
- }
1608
- catch (e) {
1609
- console.error(chalk.red('Failed to GASP sync'), e);
1610
- }
1611
- }
1612
- 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) {
1613
1822
  this.logger.log(chalk.yellow(`${this.name} will not sync because GASP has been disabled.`));
1823
+ return;
1614
1824
  }
1615
- // Start listening on the configured port
1616
- this.app.listen(this.port, () => {
1617
- this.isListening = true;
1618
- 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
1619
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
+ }
1620
1901
  }
1621
1902
  }
1622
1903
  //# sourceMappingURL=OverlayExpress.js.map