@bsv/overlay-express 2.4.2 → 2.4.9

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 (135) hide show
  1. package/LICENSE.txt +57 -27
  2. package/README.md +141 -56
  3. package/dist/cjs/mod.d.ts +11 -0
  4. package/dist/cjs/mod.d.ts.map +1 -0
  5. package/dist/cjs/mod.js.map +1 -1
  6. package/dist/cjs/package.json +26 -13
  7. package/dist/cjs/src/ArcadeProvider.d.ts +37 -0
  8. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -0
  9. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  10. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts +36 -0
  11. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  12. package/dist/cjs/src/BanAwareDiscoveryStorage.js +5 -4
  13. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -1
  14. package/dist/cjs/src/BanAwareLookupWrapper.d.ts +31 -0
  15. package/dist/cjs/src/BanAwareLookupWrapper.d.ts.map +1 -0
  16. package/dist/cjs/src/BanAwareLookupWrapper.js +3 -2
  17. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -1
  18. package/dist/cjs/src/BanAwareTopicManager.d.ts +28 -0
  19. package/dist/cjs/src/BanAwareTopicManager.d.ts.map +1 -0
  20. package/dist/cjs/src/BanAwareTopicManager.js +3 -2
  21. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -1
  22. package/dist/cjs/src/BanService.d.ts +81 -0
  23. package/dist/cjs/src/BanService.d.ts.map +1 -0
  24. package/dist/cjs/src/BanService.js.map +1 -1
  25. package/dist/cjs/src/ChaintracksProvider.d.ts +29 -0
  26. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -0
  27. package/dist/cjs/src/ChaintracksProvider.js +1 -1
  28. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  29. package/dist/cjs/src/JanitorService.d.ts +128 -0
  30. package/dist/cjs/src/JanitorService.d.ts.map +1 -0
  31. package/dist/cjs/src/JanitorService.js +108 -37
  32. package/dist/cjs/src/JanitorService.js.map +1 -1
  33. package/dist/cjs/src/OverlayExpress.d.ts +466 -0
  34. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -0
  35. package/dist/cjs/src/OverlayExpress.js +307 -148
  36. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  37. package/dist/cjs/src/OverlayMonitor.d.ts +197 -0
  38. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -0
  39. package/dist/cjs/src/OverlayMonitor.js +6 -4
  40. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  41. package/dist/cjs/src/ProviderChainBroadcaster.d.ts +18 -0
  42. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -0
  43. package/dist/cjs/src/ProviderChainBroadcaster.js +7 -3
  44. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  45. package/dist/cjs/src/ReorgStream.d.ts +74 -0
  46. package/dist/cjs/src/ReorgStream.d.ts.map +1 -0
  47. package/dist/cjs/src/ReorgStream.js +14 -6
  48. package/dist/cjs/src/ReorgStream.js.map +1 -1
  49. package/dist/cjs/src/generalGuide.md.d.ts +3 -0
  50. package/dist/cjs/src/generalGuide.md.d.ts.map +1 -0
  51. package/dist/cjs/src/generalGuide.md.js.map +1 -1
  52. package/dist/cjs/src/makeUserInterface.d.ts +22 -0
  53. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -0
  54. package/dist/cjs/src/makeUserInterface.js +4 -4
  55. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  56. package/dist/cjs/src/security/edgePolicy.d.ts +57 -0
  57. package/dist/cjs/src/security/edgePolicy.d.ts.map +1 -0
  58. package/dist/cjs/src/security/edgePolicy.js +379 -0
  59. package/dist/cjs/src/security/edgePolicy.js.map +1 -0
  60. package/dist/esm/mod.js.map +1 -1
  61. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  62. package/dist/esm/src/BanAwareDiscoveryStorage.js +5 -4
  63. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  64. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  65. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  66. package/dist/esm/src/BanAwareTopicManager.js +3 -2
  67. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  68. package/dist/esm/src/ChaintracksProvider.js +1 -1
  69. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  70. package/dist/esm/src/JanitorService.js +84 -8
  71. package/dist/esm/src/JanitorService.js.map +1 -1
  72. package/dist/esm/src/OverlayExpress.js +290 -134
  73. package/dist/esm/src/OverlayExpress.js.map +1 -1
  74. package/dist/esm/src/ProviderChainBroadcaster.js +7 -3
  75. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  76. package/dist/esm/src/ReorgStream.js +14 -6
  77. package/dist/esm/src/ReorgStream.js.map +1 -1
  78. package/dist/esm/src/makeUserInterface.js +3 -4
  79. package/dist/esm/src/makeUserInterface.js.map +1 -1
  80. package/dist/esm/src/security/edgePolicy.js +377 -0
  81. package/dist/esm/src/security/edgePolicy.js.map +1 -0
  82. package/dist/types/mod.d.ts +1 -1
  83. package/dist/types/mod.d.ts.map +1 -1
  84. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  85. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  86. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  87. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  88. package/dist/types/src/BanService.d.ts.map +1 -1
  89. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  90. package/dist/types/src/JanitorService.d.ts +14 -1
  91. package/dist/types/src/JanitorService.d.ts.map +1 -1
  92. package/dist/types/src/OverlayExpress.d.ts +48 -2
  93. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  94. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  95. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  96. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  97. package/dist/types/src/generalGuide.md.d.ts +1 -1
  98. package/dist/types/src/generalGuide.md.d.ts.map +1 -1
  99. package/dist/types/src/makeUserInterface.d.ts +1 -2
  100. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  101. package/dist/types/src/security/edgePolicy.d.ts +57 -0
  102. package/dist/types/src/security/edgePolicy.d.ts.map +1 -0
  103. package/package.json +47 -25
  104. package/dist/cjs/tsconfig.cjs.tsbuildinfo +0 -1
  105. package/dist/esm/tsconfig.esm.tsbuildinfo +0 -1
  106. package/dist/types/tsconfig.types.tsbuildinfo +0 -1
  107. package/mod.ts +0 -47
  108. package/src/ArcadeProvider.ts +0 -232
  109. package/src/BanAwareDiscoveryStorage.ts +0 -91
  110. package/src/BanAwareLookupWrapper.ts +0 -95
  111. package/src/BanAwareTopicManager.ts +0 -87
  112. package/src/BanService.ts +0 -154
  113. package/src/ChaintracksProvider.ts +0 -79
  114. package/src/JanitorService.ts +0 -423
  115. package/src/OverlayExpress.ts +0 -2479
  116. package/src/OverlayMonitor.ts +0 -817
  117. package/src/ProviderChainBroadcaster.ts +0 -108
  118. package/src/ReorgStream.ts +0 -221
  119. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +0 -131
  120. package/src/__tests__/BanAwareLookupWrapper.test.ts +0 -255
  121. package/src/__tests__/BanAwareTopicManager.test.ts +0 -132
  122. package/src/__tests__/BanService.test.ts +0 -310
  123. package/src/__tests__/InMemoryMigrationSource.test.ts +0 -11
  124. package/src/__tests__/JanitorService.test.ts +0 -941
  125. package/src/__tests__/OverlayExpress.test.ts +0 -1300
  126. package/src/__tests__/OverlayMonitor.test.ts +0 -255
  127. package/src/__tests__/OverlayProviders.live.test.ts +0 -43
  128. package/src/__tests__/OverlayProviders.test.ts +0 -123
  129. package/src/__tests__/README.md +0 -105
  130. package/src/__tests__/ReorgStream.test.ts +0 -66
  131. package/src/__tests__/makeUserInterface.test.ts +0 -193
  132. package/src/__tests__/setup.ts +0 -36
  133. package/src/auth-express-middleware.d.ts +0 -16
  134. package/src/generalGuide.md.ts +0 -74
  135. package/src/makeUserInterface.ts +0 -1224
@@ -1,2479 +0,0 @@
1
- import express from 'express'
2
- import bodyParser from 'body-parser'
3
- import {
4
- Engine,
5
- KnexStorage,
6
- LookupService,
7
- TopicManager,
8
- KnexStorageMigrations,
9
- Advertiser
10
- } from '@bsv/overlay'
11
- import {
12
- ARC,
13
- ChainTracker,
14
- MerklePath,
15
- STEAK,
16
- TaggedBEEF,
17
- WhatsOnChain,
18
- Broadcaster,
19
- OverlayBroadcastFacilitator,
20
- HTTPSOverlayBroadcastFacilitator,
21
- DEFAULT_TESTNET_SLAP_TRACKERS,
22
- DEFAULT_SLAP_TRACKERS,
23
- Utils,
24
- Beef,
25
- Transaction,
26
- PrivateKey,
27
- KeyDeriver,
28
- WalletInterface
29
- } from '@bsv/sdk'
30
- import Knex from 'knex'
31
- import { MongoClient, Db } from 'mongodb'
32
- import makeUserInterface, { type UIConfig } from './makeUserInterface.js'
33
- import * as DiscoveryServices from '@bsv/overlay-discovery-services'
34
- import chalk from 'chalk'
35
- import util from 'node:util'
36
- import { v4 as uuidv4 } from 'uuid'
37
- import { JanitorService, type JanitorReport } from './JanitorService.js'
38
- import { BanService } from './BanService.js'
39
- import { BanAwareLookupWrapper } from './BanAwareLookupWrapper.js'
40
- import { BanAwareTopicManager } from './BanAwareTopicManager.js'
41
- import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoveryStorage.js'
42
- import { ReorgSseAdapter, type ReorgHandlerInput } from './ReorgStream.js'
43
- import { Wallet, WalletSigner, WalletStorageManager, Services } from '@bsv/wallet-toolbox-client'
44
- import { createAuthMiddleware, type AuthRequest } from '@bsv/auth-express-middleware'
45
- import { ArcadeProvider, isTerminalArcStatus, type ArcadeMerkleProof } from './ArcadeProvider.js'
46
- import { ProviderChainBroadcaster, type NamedBroadcaster } from './ProviderChainBroadcaster.js'
47
- import { ChaintracksProvider } from './ChaintracksProvider.js'
48
-
49
- /**
50
- * Knex database migration.
51
- */
52
- interface Migration {
53
- name?: string
54
- up: (knex: Knex.Knex) => Promise<void>
55
- down?: (knex: Knex.Knex) => Promise<void>
56
- }
57
-
58
- /**
59
- * In-memory migration source for Knex migrations.
60
- * Allows running migrations defined in code rather than files.
61
- */
62
- class InMemoryMigrationSource implements Knex.Knex.MigrationSource<Migration> {
63
- constructor (private readonly migrations: Migration[]) { }
64
-
65
- /**
66
- * Gets the list of migrations.
67
- * @param loadExtensions - Array of file extensions to filter by (not used here)
68
- * @returns Promise resolving to the array of migrations
69
- */
70
- async getMigrations (loadExtensions: readonly string[]): Promise<Migration[]> {
71
- return this.migrations
72
- }
73
-
74
- /**
75
- * Gets the name of a migration.
76
- * @param migration - The migration object
77
- * @returns The name of the migration
78
- */
79
- getMigrationName (migration: Migration): string {
80
- return typeof migration.name === 'string' ? migration.name : `Migration at index ${this.migrations.indexOf(migration)}`
81
- }
82
-
83
- /**
84
- * Gets the migration object.
85
- * @param migration - The migration object
86
- * @returns Promise resolving to the migration object
87
- */
88
- async getMigration (migration: Migration): Promise<Knex.Knex.Migration> {
89
- return await Promise.resolve(migration)
90
- }
91
- }
92
-
93
- /**
94
- * Configuration options that map to Engine constructor parameters.
95
- */
96
- export interface EngineConfig {
97
- chainTracker?: ChainTracker | 'scripts only'
98
- shipTrackers?: string[]
99
- slapTrackers?: string[]
100
- broadcaster?: Broadcaster
101
- advertiser?: Advertiser
102
- syncConfiguration?: Record<string, string[] | 'SHIP' | false>
103
- logTime?: boolean
104
- logPrefix?: string
105
- throwOnBroadcastFailure?: boolean
106
- overlayBroadcastFacilitator?: OverlayBroadcastFacilitator
107
- suppressDefaultSyncAdvertisements?: boolean
108
- topicAnchorHeaderResolver?: TopicAnchorHeaderResolver
109
- enableBASMSync?: boolean
110
- unprovenEvictionBlocks?: number
111
- reorgStreamUrl?: string
112
- reorgScanDepth?: number
113
- unprovenMaintenanceIntervalMs?: number
114
- }
115
-
116
- export type HealthStatus = 'ok' | 'degraded' | 'error'
117
-
118
- export interface HealthCheckResult {
119
- name: string
120
- scope: 'live' | 'ready'
121
- status: HealthStatus
122
- critical: boolean
123
- message?: string
124
- details?: Record<string, any>
125
- durationMs: number
126
- }
127
-
128
- export type HealthCheckHandler = () => Promise<Omit<HealthCheckResult, 'name' | 'scope' | 'critical' | 'durationMs'> | void> | Omit<HealthCheckResult, 'name' | 'scope' | 'critical' | 'durationMs'> | void
129
-
130
- export interface HealthCheckDefinition {
131
- name: string
132
- scope?: 'live' | 'ready'
133
- critical?: boolean
134
- handler: HealthCheckHandler
135
- }
136
-
137
- export interface HealthConfig {
138
- includeDetails: boolean
139
- timeoutMs: number
140
- contextProvider?: () => Promise<Record<string, any> | undefined> | Record<string, any> | undefined
141
- }
142
-
143
- export interface HealthReport {
144
- status: HealthStatus
145
- live: boolean
146
- ready: boolean
147
- service: {
148
- name: string
149
- advertisableFQDN: string
150
- port: number
151
- network: 'main' | 'test'
152
- startedAt?: string
153
- uptimeMs: number
154
- topicManagerCount: number
155
- lookupServiceCount: number
156
- }
157
- checks: HealthCheckResult[]
158
- context?: Record<string, any>
159
- }
160
-
161
- export type TopicAnchorHeaderResolver = (blockHeight: number) => Promise<{
162
- blockHeight: number
163
- blockHash: string
164
- merkleRoot?: string
165
- } | undefined>
166
-
167
- interface BASMCapableEngine extends Engine {
168
- provideTopicAnchorTip: (topic: string) => Promise<any>
169
- provideTopicAnchorRange: (topic: string, fromHeight: number, toHeight: number) => Promise<any>
170
- provideAdmittedList: (topic: string, blockHeight: number, blockHash?: string) => Promise<any>
171
- provideCompoundMerklePath: (topic: string, blockHeight: number, txids: string[]) => Promise<any>
172
- provideRawTransactions: (txids: string[]) => Promise<any>
173
- startBASMSync: () => Promise<any>
174
- advanceTopicAnchorChains: (toHeight?: number) => Promise<void>
175
- evictUnprovenTransactions: (options?: { topic?: string, thresholdBlocks?: number }) => Promise<any>
176
- refreshUnprovenTransactionProofs: (options: {
177
- topic?: string
178
- thresholdBlocks?: number
179
- proofProvider: (txid: string) => Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined>
180
- }) => Promise<any>
181
- maintainUnprovenTransactions: (options: {
182
- topic?: string
183
- thresholdBlocks?: number
184
- proofProvider: (txid: string) => Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined>
185
- }) => Promise<any>
186
- evictAppliedTransaction: (txid: string, options?: { topic?: string, reason?: string }) => Promise<any>
187
- handleReorg: (input: ReorgHandlerInput) => Promise<any>
188
- revalidateRecentAnchors: (depth?: number) => Promise<any>
189
- }
190
-
191
- function parseTopicsHeader (header: string): string[] {
192
- const value = header.trim()
193
- const parsed: unknown = value.startsWith('[')
194
- ? JSON.parse(value)
195
- : value.split(',').map(topic => topic.trim())
196
-
197
- if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
198
- throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array')
199
- }
200
- return parsed
201
- }
202
-
203
- /**
204
- * OverlayExpress class provides an Express-based server for hosting Overlay Services.
205
- * It allows configuration of various components like databases, topic managers, and lookup services.
206
- * It encapsulates an Express application and provides methods to start the server.
207
- */
208
- export default class OverlayExpress {
209
- // Express application
210
- app: express.Application
211
-
212
- // Server port
213
- port: number = 3000
214
-
215
- // Logger (defaults to console)
216
- logger: typeof console = console
217
-
218
- // Knex (SQL) database
219
- knex?: Knex.Knex
220
-
221
- // Knex migrations to run
222
- migrationsToRun: Migration[] = []
223
-
224
- // MongoDB database
225
- mongoDb?: Db
226
-
227
- // MongoDB client retained for health checks
228
- mongoClient?: MongoClient
229
-
230
- // Network ('main' or 'test')
231
- network: 'main' | 'test' = 'main'
232
-
233
- // If no custom ChainTracker is configured, default is a WhatsOnChain instance
234
- // (We keep a property for it, so we can pass it to Engine)
235
- chainTracker: ChainTracker | 'scripts only' = new WhatsOnChain(this.network)
236
-
237
- // The Overlay Engine
238
- engine?: Engine
239
-
240
- // Configured Topic Managers
241
- managers: Record<string, TopicManager> = {}
242
-
243
- // Configured Lookup Services
244
- services: Record<string, LookupService> = {}
245
-
246
- // Enable GASP Sync
247
- // (We allow an on/off toggle, but also can do advanced custom sync config below)
248
- enableGASPSync: boolean = true
249
-
250
- // Enable BRC-136 BASM sync. Off by default; endpoints remain available when
251
- // storage supports anchors.
252
- enableBASMSync: boolean = false
253
-
254
- // Opt-in unproven eviction default threshold in blocks.
255
- unprovenEvictionBlocks: number = 144
256
-
257
- // How often (ms) to poll the chain tip and extend each topic's BASM anchor
258
- // chain with empty anchors, so the cumulative TAC advances "after each new
259
- // block" per BRC-136. Set to 0 to disable polling (startup extension still runs).
260
- basmBlockPollIntervalMs: number = 10 * 60 * 1000
261
-
262
- // Handle for the BASM block-poll timer so it can be stopped.
263
- private basmBlockPollTimer?: ReturnType<typeof setInterval>
264
-
265
- // How often (ms) to refresh proofs for old unproven rows and then evict rows
266
- // that still have no proof. Set to 0 to disable background maintenance.
267
- unprovenMaintenanceIntervalMs: number = 0
268
-
269
- private unprovenMaintenanceTimer?: ReturnType<typeof setInterval>
270
-
271
- // Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
272
- // When set, reorgs are reconciled in real time; the block poll also runs a
273
- // revalidation sweep as a fallback / reconnect catch-up.
274
- reorgStreamUrl?: string
275
-
276
- // Depth (in blocks from the tip) for the reorg revalidation sweep.
277
- reorgScanDepth: number = 3
278
-
279
- // Handle for the reorg SSE adapter.
280
- private reorgAdapter?: ReorgSseAdapter
281
-
282
- // Optional resolver for block hashes and header merkle roots used by BASM.
283
- topicAnchorHeaderResolver?: TopicAnchorHeaderResolver
284
-
285
- // ARC API Key
286
- arcApiKey: string | undefined = undefined
287
-
288
- // Optional ARC callback token for /arc-ingest notifications
289
- arcCallbackToken: string | undefined = undefined
290
-
291
- // Optional Arcade URL/API key used for propagation, proof refresh, and
292
- // go-chaintracks header/reorg access when available.
293
- arcadeUrl: string | undefined = undefined
294
- arcadeApiKey: string | undefined = undefined
295
- arcadeDeploymentId: string | undefined = undefined
296
- arcadeChaintracksApiPrefix: string = '/chaintracks/v2'
297
-
298
- private arcadeProvider?: ArcadeProvider
299
-
300
- // Verbose request logging
301
- verboseRequestLogging: boolean = false
302
-
303
- // Web UI configuration
304
- webUIConfig: UIConfig = {}
305
-
306
- // Additional advanced engine config (these map to Engine constructor parameters).
307
- // Default to undefined or default values that are used in the Engine if not specified.
308
- engineConfig: EngineConfig = {}
309
-
310
- // The administrative Bearer token used for the admin routes.
311
- // If not passed in, we'll generate a random one.
312
- private readonly adminToken: string
313
-
314
- // Configuration for the janitor service
315
- janitorConfig: {
316
- requestTimeoutMs: number
317
- hostDownRevokeScore: number
318
- autoBanOnRemoval: boolean
319
- } = {
320
- requestTimeoutMs: 10000, // 10 seconds
321
- hostDownRevokeScore: 3,
322
- autoBanOnRemoval: true
323
- }
324
-
325
- // Ban service for persistent domain/outpoint blocking
326
- banService?: BanService
327
-
328
- // Admin identity key for wallet-based admin detection on the frontend
329
- adminIdentityKey?: string
330
-
331
- // Server-side wallet (WalletInterface) used for BSV mutual authentication
332
- serverWallet?: WalletInterface
333
-
334
- // Server start time for uptime tracking
335
- private startTime?: Date
336
-
337
- // Health endpoint configuration
338
- healthConfig: HealthConfig = {
339
- includeDetails: true,
340
- timeoutMs: 5000
341
- }
342
-
343
- // Extra application-specific health checks
344
- healthChecks: HealthCheckDefinition[] = []
345
-
346
- // Lifecycle marker for readiness/liveness reporting
347
- isListening: boolean = false
348
-
349
- /**
350
- * Constructs an instance of OverlayExpress.
351
- * @param name - The name of the service
352
- * @param privateKey - Private key used for signing advertisements
353
- * @param advertisableFQDN - The fully qualified domain name where this service is available. Does not include "https://".
354
- * @param adminToken - Optional. An administrative Bearer token used to protect admin routes.
355
- * If not provided, a random token will be generated at runtime.
356
- */
357
- constructor (
358
- public name: string,
359
- public privateKey: string,
360
- public advertisableFQDN: string,
361
- adminToken?: string
362
- ) {
363
- this.app = express()
364
- this.logger.log(chalk.green.bold(`${name} constructed`))
365
- this.adminToken = adminToken ?? uuidv4() // generate random if not provided
366
- }
367
-
368
- /**
369
- * Returns the current admin token in case you need to programmatically retrieve or display it.
370
- */
371
- getAdminToken (): string {
372
- return this.adminToken
373
- }
374
-
375
- /**
376
- * Configures the port on which the server will listen.
377
- * @param port - The port number
378
- */
379
- configurePort (port: number): void {
380
- this.port = port
381
- this.logger.log(chalk.blue(`Server port set to ${port}`))
382
- }
383
-
384
- /**
385
- * Configures the web user interface
386
- * @param config - Web UI configuration options
387
- */
388
- configureWebUI (config: UIConfig): void {
389
- this.webUIConfig = config
390
- this.logger.log(chalk.blue('Web UI has been configured.'))
391
- }
392
-
393
- /**
394
- * Configures the janitor service parameters
395
- * @param config - Janitor configuration options
396
- * - requestTimeoutMs: Timeout for health check requests (default: 10000ms)
397
- * - hostDownRevokeScore: Number of consecutive failures before deleting output (default: 3)
398
- * - autoBanOnRemoval: Whether to auto-ban domains when removed by janitor (default: true)
399
- */
400
- configureJanitor (config: Partial<typeof this.janitorConfig>): void {
401
- this.janitorConfig = {
402
- ...this.janitorConfig,
403
- ...config
404
- }
405
- this.logger.log(chalk.blue('Janitor service has been configured.'))
406
- }
407
-
408
- /**
409
- * Configures health-report behavior.
410
- */
411
- configureHealth (config: Partial<HealthConfig>): void {
412
- this.healthConfig = {
413
- ...this.healthConfig,
414
- ...config
415
- }
416
- this.logger.log(chalk.blue('Health reporting has been configured.'))
417
- }
418
-
419
- /**
420
- * Registers an application-specific health check.
421
- */
422
- registerHealthCheck (definition: HealthCheckDefinition): void {
423
- this.healthChecks = this.healthChecks.filter(check => check.name !== definition.name)
424
- this.healthChecks.push({
425
- scope: 'ready',
426
- critical: false,
427
- ...definition
428
- })
429
- this.logger.log(chalk.blue(`Registered health check ${definition.name}`))
430
- }
431
-
432
- /**
433
- * Configures the admin identity key for wallet-based admin detection.
434
- * When set, the frontend can compare the user's wallet identity key against this
435
- * to determine whether to show the admin dashboard.
436
- *
437
- * @param identityKey - The hex-encoded public key of the admin
438
- */
439
- configureAdminIdentityKey (identityKey: string): void {
440
- this.adminIdentityKey = identityKey
441
- this.logger.log(chalk.blue('Admin identity key has been configured.'))
442
- }
443
-
444
- /**
445
- * Configures the logger to be used by the server.
446
- * @param logger - A logger object (e.g., console)
447
- */
448
- configureLogger (logger: typeof console): void {
449
- this.logger = logger
450
- this.logger.log(chalk.blue('Logger has been configured.'))
451
- }
452
-
453
- /**
454
- * Configures the BSV Blockchain network to be used ('main' or 'test').
455
- * By default, it re-initializes chainTracker as a WhatsOnChain for that network.
456
- * @param network - The network ('main' or 'test')
457
- */
458
- configureNetwork (network: 'main' | 'test'): void {
459
- this.network = network
460
- this.chainTracker = new WhatsOnChain(this.network)
461
- this.logger.log(chalk.blue(`Network set to ${network}`))
462
- }
463
-
464
- /**
465
- * Configures the ChainTracker to be used.
466
- * If 'scripts only' is used, it implies no full SPV chain tracking in the Engine.
467
- * @param chainTracker - An instance of ChainTracker or 'scripts only'
468
- */
469
- configureChainTracker (chainTracker: ChainTracker | 'scripts only' = new WhatsOnChain(this.network)): void {
470
- this.chainTracker = chainTracker
471
- this.logger.log(chalk.blue('ChainTracker has been configured.'))
472
- }
473
-
474
- /**
475
- * Configures the ARC API key.
476
- * @param apiKey - The ARC API key
477
- */
478
- configureArcApiKey (apiKey: string): void {
479
- this.arcApiKey = apiKey
480
- this.logger.log(chalk.blue('ARC API key has been configured.'))
481
- }
482
-
483
- /**
484
- * Configures the ARC callback token expected by /arc-ingest.
485
- * @param token - The token ARC should present when posting callback notifications.
486
- */
487
- configureArcCallbackToken (token: string): void {
488
- this.arcCallbackToken = token
489
- this.logger.log(chalk.blue('ARC callback token has been configured.'))
490
- }
491
-
492
- /**
493
- * Configures Arcade for first-choice transaction propagation and proof lookup.
494
- */
495
- configureArcade (url: string, config: {
496
- apiKey?: string
497
- deploymentId?: string
498
- chaintracksApiPrefix?: string
499
- } = {}): void {
500
- this.arcadeUrl = url
501
- this.arcadeApiKey = config.apiKey
502
- this.arcadeDeploymentId = config.deploymentId
503
- if (config.chaintracksApiPrefix !== undefined) {
504
- this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix
505
- }
506
- this.logger.log(chalk.blue('Arcade provider has been configured.'))
507
- }
508
-
509
- /**
510
- * Configures a go-chaintracks compatible service for header validation and
511
- * BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
512
- */
513
- configureChaintracks (url: string, config: {
514
- apiPrefix?: string
515
- reorgStream?: boolean
516
- scanDepth?: number
517
- } = {}): void {
518
- const apiPrefix = config.apiPrefix ?? '/chaintracks/v2'
519
- const client = new ChaintracksProvider(url, { apiPrefix })
520
- this.configureChainTracker(client)
521
- this.configureTopicAnchorHeaderResolver(async blockHeight => {
522
- const header = await client.findHeaderForHeight(blockHeight)
523
- if (header === undefined) return undefined
524
- return {
525
- blockHeight,
526
- blockHash: header.hash,
527
- merkleRoot: header.merkleRoot
528
- }
529
- })
530
- if (config.reorgStream !== false) {
531
- this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth)
532
- }
533
- this.logger.log(chalk.blue('go-chaintracks provider has been configured.'))
534
- }
535
-
536
- /**
537
- * Enables or disables GASP synchronization (high-level setting).
538
- * This is a broad toggle that can be overridden or customized through syncConfiguration.
539
- * @param enable - true to enable, false to disable
540
- */
541
- configureEnableGASPSync (enable: boolean): void {
542
- this.enableGASPSync = enable
543
- this.logger.log(chalk.blue(`GASP synchronization ${enable ? 'enabled' : 'disabled'}.`))
544
- }
545
-
546
- /**
547
- * Enables or disables BRC-136 BASM synchronization.
548
- * BASM is opt-in because it requires direct proofs and block hash resolution.
549
- */
550
- configureEnableBASMSync (enable: boolean): void {
551
- this.enableBASMSync = enable
552
- this.logger.log(chalk.blue(`BASM synchronization ${enable ? 'enabled' : 'disabled'}.`))
553
- }
554
-
555
- /**
556
- * Configures the block header resolver used to derive BASM block hashes.
557
- */
558
- configureTopicAnchorHeaderResolver (resolver: TopicAnchorHeaderResolver): void {
559
- this.topicAnchorHeaderResolver = resolver
560
- this.logger.log(chalk.blue('BASM topic anchor header resolver has been configured.'))
561
- }
562
-
563
- /**
564
- * Configures the go-chaintracks (Arcade) reorg SSE stream used to reconcile
565
- * BASM anchors with blockchain reorganizations in real time.
566
- * @param url - The reorg stream URL, e.g. `https://arcade.example/v2/reorg/stream`.
567
- * @param scanDepth - Optional revalidation-sweep depth in blocks (default 3).
568
- */
569
- configureReorgStream (url: string, scanDepth?: number): void {
570
- this.reorgStreamUrl = url
571
- if (scanDepth !== undefined) {
572
- this.reorgScanDepth = scanDepth
573
- }
574
- this.logger.log(chalk.blue('BASM reorg stream has been configured.'))
575
- }
576
-
577
- /**
578
- * Configures the opt-in unproven state eviction threshold.
579
- */
580
- configureUnprovenEviction (config: { thresholdBlocks?: number }): void {
581
- if (config.thresholdBlocks !== undefined) {
582
- this.unprovenEvictionBlocks = config.thresholdBlocks
583
- }
584
- this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'))
585
- }
586
-
587
- /**
588
- * Configures periodic unproven maintenance. Each run first tries configured
589
- * proof providers, then evicts rows that are still unproven past the threshold.
590
- */
591
- configureUnprovenMaintenance (config: { intervalMs?: number, thresholdBlocks?: number }): void {
592
- if (config.intervalMs !== undefined) {
593
- this.unprovenMaintenanceIntervalMs = config.intervalMs
594
- }
595
- if (config.thresholdBlocks !== undefined) {
596
- this.unprovenEvictionBlocks = config.thresholdBlocks
597
- }
598
- this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'))
599
- }
600
-
601
- /**
602
- * Configures how often the BASM anchor chain is extended with empty anchors to
603
- * follow the chain tip. Set to 0 to disable periodic polling.
604
- */
605
- configureBASMBlockPollInterval (intervalMs: number): void {
606
- this.basmBlockPollIntervalMs = intervalMs
607
- this.logger.log(chalk.blue(`BASM block poll interval set to ${intervalMs}ms.`))
608
- }
609
-
610
- /**
611
- * Enables or disables verbose request logging.
612
- * @param enable - true to enable, false to disable
613
- */
614
- configureVerboseRequestLogging (enable: boolean): void {
615
- this.verboseRequestLogging = enable
616
- this.logger.log(chalk.blue(`Verbose request logging ${enable ? 'enabled' : 'disabled'}.`))
617
- }
618
-
619
- /**
620
- * Configure Knex (SQL) database connection.
621
- * @param config - Knex configuration object, or a MySQL connection string loaded from configuration.
622
- */
623
- async configureKnex (config: Knex.Knex.Config | string): Promise<void> {
624
- if (typeof config === 'string') {
625
- config = {
626
- client: 'mysql2',
627
- connection: config
628
- }
629
- }
630
- this.knex = Knex(config)
631
- this.logger.log(chalk.blue('Knex successfully configured.'))
632
- }
633
-
634
- /**
635
- * Configures the MongoDB database connection.
636
- * Also initializes the BanService for persistent ban tracking.
637
- * @param connectionString - MongoDB connection string
638
- */
639
- async configureMongo (connectionString: string): Promise<void> {
640
- const mongoClient = new MongoClient(connectionString)
641
- await mongoClient.connect()
642
- this.mongoClient = mongoClient
643
- const db = mongoClient.db(`${this.name}_lookup_services`)
644
- this.mongoDb = db
645
-
646
- // Initialize the BanService
647
- this.banService = new BanService(db)
648
- await this.banService.ensureIndexes()
649
-
650
- this.logger.log(chalk.blue('MongoDB successfully configured and connected.'))
651
- }
652
-
653
- /**
654
- * Configures a Topic Manager.
655
- * @param name - The name of the Topic Manager
656
- * @param manager - An instance of TopicManager
657
- */
658
- configureTopicManager (name: string, manager: TopicManager): void {
659
- this.managers[name] = manager
660
- this.logger.log(chalk.blue(`Configured topic manager ${name}`))
661
- }
662
-
663
- /**
664
- * Configures a Lookup Service.
665
- * @param name - The name of the Lookup Service
666
- * @param service - An instance of LookupService
667
- */
668
- configureLookupService (name: string, service: LookupService): void {
669
- this.services[name] = service
670
- this.logger.log(chalk.blue(`Configured lookup service ${name}`))
671
- }
672
-
673
- /**
674
- * Configures a Lookup Service using Knex (SQL) database.
675
- * @param name - The name of the Lookup Service
676
- * @param serviceFactory - A factory function that creates a LookupService instance using Knex
677
- */
678
- configureLookupServiceWithKnex (
679
- name: string,
680
- serviceFactory: (knex: Knex.Knex) => { service: LookupService, migrations: Migration[] }
681
- ): void {
682
- const knex = this.ensureKnex()
683
- const factoryResult = serviceFactory(knex)
684
- this.services[name] = factoryResult.service
685
- this.migrationsToRun.push(...factoryResult.migrations)
686
- this.logger.log(chalk.blue(`Configured lookup service ${name} with Knex`))
687
- }
688
-
689
- /**
690
- * Configures a Lookup Service using MongoDB.
691
- * @param name - The name of the Lookup Service
692
- * @param serviceFactory - A factory function that creates a LookupService instance using MongoDB
693
- */
694
- configureLookupServiceWithMongo (name: string, serviceFactory: (mongoDb: Db) => LookupService): void {
695
- const mongoDb = this.ensureMongo()
696
- this.services[name] = serviceFactory(mongoDb)
697
- this.logger.log(chalk.blue(`Configured lookup service ${name} with MongoDB`))
698
- }
699
-
700
- /**
701
- * Advanced configuration method for setting or overriding any
702
- * Engine constructor parameters via an EngineConfig object.
703
- *
704
- * Example usage:
705
- * configureEngineParams({
706
- * logTime: true,
707
- * throwOnBroadcastFailure: true,
708
- * overlayBroadcastFacilitator: new MyCustomFacilitator()
709
- * })
710
- *
711
- * These fields will be respected when we finally build/configure the Engine
712
- * in the `configureEngine()` method below.
713
- */
714
- configureEngineParams (params: EngineConfig): void {
715
- this.engineConfig = {
716
- ...this.engineConfig,
717
- ...params
718
- }
719
- this.logger.log(chalk.blue('Advanced Engine configuration params have been updated.'))
720
- }
721
-
722
- /**
723
- * Configures the Overlay Engine itself.
724
- * By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false
725
- * Then it merges in any advanced engine config from `this.engineConfig`.
726
- *
727
- * When a BanService is available (from configureMongo), auto-configured SHIP
728
- * and SLAP managers, discovery storage, and lookup services are wrapped so
729
- * banned outputs are not admitted or indexed.
730
- *
731
- * @param autoConfigureShipSlap - Whether to auto-configure SHIP and SLAP services (default: true)
732
- */
733
- async configureEngine (autoConfigureShipSlap = true): Promise<void> {
734
- const knex = this.ensureKnex()
735
-
736
- if (autoConfigureShipSlap) {
737
- const mongoDb = this.ensureMongo()
738
- const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb)
739
- const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb)
740
-
741
- // Run the one-time discovery migration before the engine can accept
742
- // traffic, so a failed unique-index build is a visible startup failure.
743
- await shipStorage.ensureIndexes()
744
- await slapStorage.ensureIndexes()
745
-
746
- this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager())
747
- this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager())
748
-
749
- const shipStorageForLookup = this.banService === undefined
750
- ? shipStorage
751
- : new BanAwareSHIPStorage(shipStorage, this.banService, this.logger)
752
- const slapStorageForLookup = this.banService === undefined
753
- ? slapStorage
754
- : new BanAwareSLAPStorage(slapStorage, this.banService, this.logger)
755
-
756
- this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup as any)
757
- this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup as any)
758
- this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'))
759
- this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'))
760
- }
761
-
762
- this.wrapBanAwareServices()
763
-
764
- const syncConfig = this.buildSyncConfig()
765
- const storage = new KnexStorage(knex)
766
- this.migrationsToRun = [...KnexStorageMigrations.default, ...this.migrationsToRun]
767
-
768
- const broadcaster = this.buildBroadcaster()
769
- const advertiser = await this.buildAdvertiser()
770
-
771
- const EngineWithBASM = Engine as unknown as new (...args: any[]) => Engine
772
- this.engine = new EngineWithBASM(
773
- this.managers,
774
- this.services,
775
- storage,
776
- this.engineConfig.chainTracker ?? this.chainTracker,
777
- `https://${this.advertisableFQDN}`,
778
- this.network === 'test'
779
- ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
780
- : this.engineConfig.shipTrackers,
781
- this.resolveSlapTrackers(),
782
- broadcaster ?? this.engineConfig.broadcaster,
783
- advertiser,
784
- syncConfig,
785
- this.engineConfig.logTime ?? false,
786
- this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
787
- this.engineConfig.throwOnBroadcastFailure ?? true,
788
- this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
789
- this.logger,
790
- this.engineConfig.suppressDefaultSyncAdvertisements ?? true,
791
- this.buildTopicAnchorHeaderResolver(),
792
- this.engineConfig.enableBASMSync ?? this.enableBASMSync,
793
- this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks
794
- )
795
-
796
- this.initServerWallet()
797
- this.logger.log(chalk.green('Engine has been configured.'))
798
- }
799
-
800
- /** Wrap SHIP/SLAP managers and services with ban-aware filters if BanService is configured. */
801
- private wrapBanAwareServices (): void {
802
- if (this.banService === undefined) return
803
- for (const key of ['tm_ship', 'tm_slap'] as const) {
804
- if (this.managers[key] !== undefined) {
805
- const label = key === 'tm_ship' ? 'SHIP' : 'SLAP'
806
- this.managers[key] = new BanAwareTopicManager(this.managers[key], this.banService, label, this.logger)
807
- this.logger.log(chalk.blue(`${label} topic manager wrapped with ban-aware filter.`))
808
- }
809
- }
810
- for (const key of ['ls_ship', 'ls_slap'] as const) {
811
- if (this.services[key] !== undefined) {
812
- const label = key === 'ls_ship' ? 'SHIP' : 'SLAP'
813
- this.services[key] = new BanAwareLookupWrapper(this.services[key], this.banService, label, this.logger)
814
- this.logger.log(chalk.blue(`${label} lookup service wrapped with ban-aware filter.`))
815
- }
816
- }
817
- }
818
-
819
- /** Build the sync config based on enableGASPSync and engineConfig. */
820
- private buildSyncConfig (): Record<string, string[] | 'SHIP' | false> {
821
- if (this.enableGASPSync) {
822
- return this.engineConfig.syncConfiguration ?? {}
823
- }
824
- const syncConfig: Record<string, string[] | 'SHIP' | false> = {}
825
- for (const name of Object.keys(this.managers)) {
826
- syncConfig[name] = false
827
- }
828
- return syncConfig
829
- }
830
-
831
- /** Build the configured transaction propagation provider chain. */
832
- private buildBroadcaster (): Broadcaster | undefined {
833
- const providers: NamedBroadcaster[] = []
834
- const callbackUrl = `https://${this.advertisableFQDN}/arc-ingest`
835
-
836
- if (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0) {
837
- this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
838
- apiKey: this.arcadeApiKey,
839
- callbackUrl,
840
- callbackToken: this.arcCallbackToken,
841
- deploymentId: this.arcadeDeploymentId
842
- })
843
- providers.push({
844
- name: 'Arcade',
845
- broadcaster: this.arcadeProvider
846
- })
847
- } else {
848
- this.arcadeProvider = undefined
849
- }
850
-
851
- if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
852
- const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
853
- providers.push({
854
- name: 'ARC',
855
- broadcaster: new ARC(arcUrl, {
856
- apiKey: this.arcApiKey,
857
- callbackUrl,
858
- callbackToken: this.arcCallbackToken
859
- })
860
- })
861
- }
862
-
863
- if (providers.length === 0) return undefined
864
- if (providers.length === 1) return providers[0].broadcaster
865
- return new ProviderChainBroadcaster(providers)
866
- }
867
-
868
- private ensureArcadeProvider (): ArcadeProvider | undefined {
869
- if (this.arcadeProvider !== undefined) return this.arcadeProvider
870
- if (typeof this.arcadeUrl !== 'string' || this.arcadeUrl.length === 0) return undefined
871
- this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
872
- apiKey: this.arcadeApiKey,
873
- callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
874
- callbackToken: this.arcCallbackToken,
875
- deploymentId: this.arcadeDeploymentId
876
- })
877
- return this.arcadeProvider
878
- }
879
-
880
- private async fetchArcadeProof (txid: string): Promise<ArcadeMerkleProof | undefined> {
881
- const provider = this.ensureArcadeProvider()
882
- if (provider === undefined) return undefined
883
- const proof = await provider.fetchMerkleProof(txid)
884
- if (proof === undefined) return undefined
885
- const chainTracker = this.engineConfig.chainTracker ?? this.chainTracker
886
- if (chainTracker === 'scripts only') {
887
- throw new Error('Cannot validate Arcade proof with scripts-only chain tracker')
888
- }
889
- const blockHeight = proof.blockHeight ?? proof.merklePath.blockHeight
890
- if (blockHeight === undefined) {
891
- throw new Error(`Arcade proof for ${txid} did not include a block height`)
892
- }
893
- const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight)
894
- if (!valid) {
895
- throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`)
896
- }
897
- return {
898
- ...proof,
899
- blockHeight
900
- }
901
- }
902
-
903
- private async fetchConfiguredMerkleProof (txid: string): Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined> {
904
- const proof = await this.fetchArcadeProof(txid)
905
- if (proof === undefined) return undefined
906
- return {
907
- merklePath: proof.merklePath,
908
- blockHeight: proof.blockHeight
909
- }
910
- }
911
-
912
- /** Build the BASM block header resolver. */
913
- private buildTopicAnchorHeaderResolver (): TopicAnchorHeaderResolver | undefined {
914
- const configured = this.engineConfig.topicAnchorHeaderResolver ?? this.topicAnchorHeaderResolver
915
- if (configured !== undefined) {
916
- return configured
917
- }
918
-
919
- return async (blockHeight: number) => {
920
- const response = await fetch(`https://api.whatsonchain.com/v1/bsv/${this.network}/block/${blockHeight}/header`, {
921
- method: 'GET',
922
- headers: { Accept: 'application/json' }
923
- })
924
- if (!response.ok) {
925
- throw new Error(`WhatsOnChain header lookup failed for height ${blockHeight}: ${response.status}`)
926
- }
927
- const header = await response.json() as { hash?: string, merkleroot?: string }
928
- if (typeof header.hash !== 'string') {
929
- throw new TypeError(`WhatsOnChain did not return a block hash for height ${blockHeight}`)
930
- }
931
- return {
932
- blockHeight,
933
- blockHash: header.hash,
934
- merkleRoot: header.merkleroot
935
- }
936
- }
937
- }
938
-
939
- /** Resolve the SLAP trackers from config or network defaults. */
940
- private resolveSlapTrackers (): string[] | undefined {
941
- if (Array.isArray(this.engineConfig.slapTrackers)) return this.engineConfig.slapTrackers
942
- return this.network === 'test' ? DEFAULT_TESTNET_SLAP_TRACKERS : DEFAULT_SLAP_TRACKERS
943
- }
944
-
945
- /** Build the WalletAdvertiser (or use user-provided one). */
946
- private async buildAdvertiser (): Promise<Advertiser | undefined> {
947
- if (this.engineConfig.advertiser !== undefined) return this.engineConfig.advertiser
948
- const storageBase = this.network === 'test'
949
- ? 'https://staging-storage.babbage.systems'
950
- : 'https://storage.babbage.systems'
951
- try {
952
- return new DiscoveryServices.WalletAdvertiser(
953
- this.network,
954
- this.privateKey,
955
- storageBase,
956
- `https://${this.advertisableFQDN}`
957
- )
958
- } catch (e) {
959
- this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled. Reason: ${e}`)
960
- return undefined
961
- }
962
- }
963
-
964
- /** Initialize the server wallet for BSV mutual authentication. */
965
- private initServerWallet (): void {
966
- try {
967
- const keyDeriver = new KeyDeriver(new PrivateKey(this.privateKey, 'hex'))
968
- const storageManager = new WalletStorageManager(keyDeriver.identityKey)
969
- const signer = new WalletSigner(this.network, keyDeriver, storageManager)
970
- const services = new Services(this.network)
971
- this.serverWallet = new Wallet(signer, services)
972
- this.adminIdentityKey ??= keyDeriver.identityKey
973
- this.logger.log(chalk.blue('Server wallet initialized for BSV mutual authentication.'))
974
- } catch (e) {
975
- this.logger.log(chalk.yellow(`Server wallet could not be initialized. BSV auth will not be available. Reason: ${e}`))
976
- }
977
- }
978
-
979
- /**
980
- * Ensures that Knex is configured and returns it.
981
- * @throws Error if Knex is not configured
982
- */
983
- private ensureKnex (): Knex.Knex {
984
- if (this.knex === undefined) {
985
- throw new TypeError('You must configure your SQL database with the .configureKnex() method first!')
986
- }
987
- return this.knex
988
- }
989
-
990
- /**
991
- * Ensures that MongoDB is configured and returns it.
992
- * @throws Error if MongoDB is not configured
993
- */
994
- private ensureMongo (): Db {
995
- if (this.mongoDb === undefined) {
996
- throw new TypeError('You must configure your MongoDB connection with the .configureMongo() method first!')
997
- }
998
- return this.mongoDb
999
- }
1000
-
1001
- /**
1002
- * Ensures that the Overlay Engine is configured and returns it.
1003
- * @throws Error if the Engine is not configured
1004
- */
1005
- private ensureEngine (): Engine {
1006
- if (this.engine === undefined) {
1007
- throw new TypeError('You must configure your Overlay Services engine with the .configureEngine() method first!')
1008
- }
1009
- return this.engine
1010
- }
1011
-
1012
- /**
1013
- * Creates a JanitorService instance with current configuration.
1014
- */
1015
- private createJanitor (): JanitorService {
1016
- const mongoDb = this.ensureMongo()
1017
- return new JanitorService({
1018
- mongoDb,
1019
- logger: this.logger,
1020
- requestTimeoutMs: this.janitorConfig.requestTimeoutMs,
1021
- hostDownRevokeScore: this.janitorConfig.hostDownRevokeScore,
1022
- banService: this.banService,
1023
- autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval
1024
- })
1025
- }
1026
-
1027
- /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
1028
- private async handleBanDomain (res: express.Response, value: string, reason?: string): Promise<express.Response> {
1029
- await this.banService!.banDomain(value, reason)
1030
- const db = this.ensureMongo()
1031
- const [shipDeleted, slapDeleted] = await Promise.all([
1032
- db.collection('shipRecords').deleteMany({ domain: value }),
1033
- db.collection('slapRecords').deleteMany({ domain: value })
1034
- ])
1035
- return res.status(200).json({
1036
- status: 'success',
1037
- message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
1038
- })
1039
- }
1040
-
1041
- /** Parse outpoint string, ban it, and evict it from all lookup services. */
1042
- private async handleBanOutpoint (res: express.Response, engine: Engine, value: string, reason?: string): Promise<express.Response> {
1043
- const dotIndex = value.lastIndexOf('.')
1044
- if (dotIndex === -1) {
1045
- return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' })
1046
- }
1047
- const txid = value.substring(0, dotIndex)
1048
- const outputIndex = Number.parseInt(value.substring(dotIndex + 1))
1049
- if (Number.isNaN(outputIndex)) {
1050
- return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' })
1051
- }
1052
- await this.banService!.banOutpoint(txid, outputIndex, reason)
1053
- await this.evictFromServices(engine, txid, outputIndex)
1054
- return res.status(200).json({
1055
- status: 'success',
1056
- message: `Outpoint "${value}" banned and evicted from lookup services.`
1057
- })
1058
- }
1059
-
1060
- /** Evict an output from a specific service or all services (silent per-service errors). */
1061
- private async evictFromServices (engine: Engine, txid: string, outputIndex: number, service?: string): Promise<void> {
1062
- if (typeof service === 'string') {
1063
- const svc = engine.lookupServices[service]
1064
- if (svc !== undefined) await svc.outputEvicted(txid, outputIndex)
1065
- return
1066
- }
1067
- for (const svc of Object.values(engine.lookupServices)) {
1068
- try { await svc.outputEvicted(txid, outputIndex) } catch { /* best-effort */ }
1069
- }
1070
- }
1071
-
1072
- /** Look up the domain of an outpoint from SHIP or SLAP records. */
1073
- private async lookupDomainForOutpoint (txid: string, outputIndex: number): Promise<string | undefined> {
1074
- const db = this.ensureMongo()
1075
- const [shipRecord, slapRecord] = await Promise.all([
1076
- db.collection('shipRecords').findOne({ txid, outputIndex }),
1077
- db.collection('slapRecords').findOne({ txid, outputIndex })
1078
- ])
1079
- return (shipRecord?.domain ?? slapRecord?.domain) as string | undefined
1080
- }
1081
-
1082
- /** Ban a domain and delete all SHIP/SLAP records for it. */
1083
- private async banDomainAndRemoveRecords (domain: string, reason: string): Promise<void> {
1084
- await this.banService!.banDomain(domain, reason)
1085
- const db = this.ensureMongo()
1086
- await Promise.all([
1087
- db.collection('shipRecords').deleteMany({ domain }),
1088
- db.collection('slapRecords').deleteMany({ domain })
1089
- ])
1090
- }
1091
-
1092
- private async runHealthCheck (
1093
- definition: Required<Pick<HealthCheckDefinition, 'name' | 'scope' | 'critical'>> & { handler: HealthCheckHandler }
1094
- ): Promise<HealthCheckResult> {
1095
- const startedAt = Date.now()
1096
-
1097
- try {
1098
- const result = ((await Promise.race([
1099
- Promise.resolve(definition.handler()),
1100
- new Promise<never>((_, reject) => {
1101
- setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs)
1102
- })
1103
- ])) ?? {}) as {
1104
- status?: HealthStatus
1105
- message?: string
1106
- details?: Record<string, any>
1107
- }
1108
-
1109
- return {
1110
- name: definition.name,
1111
- scope: definition.scope,
1112
- critical: definition.critical,
1113
- status: result.status ?? 'ok',
1114
- message: result.message,
1115
- details: result.details,
1116
- durationMs: Date.now() - startedAt
1117
- }
1118
- } catch (error) {
1119
- return {
1120
- name: definition.name,
1121
- scope: definition.scope,
1122
- critical: definition.critical,
1123
- status: 'error',
1124
- message: error instanceof Error ? error.message : 'Unknown health-check error',
1125
- durationMs: Date.now() - startedAt
1126
- }
1127
- }
1128
- }
1129
-
1130
- private async collectHealthReport (mode: 'live' | 'ready' | 'full'): Promise<HealthReport> {
1131
- const definitions: Array<Required<Pick<HealthCheckDefinition, 'name' | 'scope' | 'critical'>> & { handler: HealthCheckHandler }> = [
1132
- {
1133
- name: 'process',
1134
- scope: 'live',
1135
- critical: true,
1136
- handler: async () => ({
1137
- status: 'ok',
1138
- details: {
1139
- listening: this.isListening
1140
- }
1141
- })
1142
- },
1143
- {
1144
- name: 'engine',
1145
- scope: 'ready',
1146
- critical: true,
1147
- handler: async () => {
1148
- if (this.engine === undefined) {
1149
- throw new TypeError('Overlay engine is not configured')
1150
- }
1151
-
1152
- return {
1153
- status: 'ok',
1154
- details: {
1155
- topicManagers: Object.keys(this.managers),
1156
- lookupServices: Object.keys(this.services)
1157
- }
1158
- }
1159
- }
1160
- },
1161
- {
1162
- name: 'knex',
1163
- scope: 'ready',
1164
- critical: true,
1165
- handler: async () => {
1166
- if (this.knex === undefined) {
1167
- throw new TypeError('Knex is not configured')
1168
- }
1169
-
1170
- await this.knex.raw('select 1 as ok')
1171
- return {
1172
- status: 'ok',
1173
- details: {
1174
- client: this.knex.client?.config?.client ?? 'unknown'
1175
- }
1176
- }
1177
- }
1178
- },
1179
- {
1180
- name: 'mongo',
1181
- scope: 'ready',
1182
- critical: true,
1183
- handler: async () => {
1184
- if (this.mongoDb === undefined) {
1185
- throw new TypeError('MongoDB is not configured')
1186
- }
1187
-
1188
- await this.mongoDb.command({ ping: 1 })
1189
- return {
1190
- status: 'ok',
1191
- details: {
1192
- database: this.mongoDb.databaseName
1193
- }
1194
- }
1195
- }
1196
- }
1197
- ]
1198
-
1199
- for (const check of this.healthChecks) {
1200
- definitions.push({
1201
- name: check.name,
1202
- scope: check.scope ?? 'ready',
1203
- critical: check.critical ?? false,
1204
- handler: check.handler
1205
- })
1206
- }
1207
-
1208
- const filteredDefinitions = definitions.filter((definition) => {
1209
- if (mode === 'full') {
1210
- return true
1211
- }
1212
-
1213
- return definition.scope === mode
1214
- })
1215
-
1216
- const checks = await Promise.all(filteredDefinitions.map(async definition => await this.runHealthCheck(definition)))
1217
- const liveChecks = checks.filter(check => check.scope === 'live')
1218
- const readyChecks = checks.filter(check => check.scope === 'ready')
1219
- const live = liveChecks.every(check => !check.critical || check.status === 'ok')
1220
- const ready = readyChecks.every(check => !check.critical || check.status === 'ok')
1221
-
1222
- let status: HealthStatus = 'ok'
1223
- if (!live || !ready || checks.some(check => check.critical && check.status === 'error')) {
1224
- status = 'error'
1225
- } else if (checks.some(check => check.status !== 'ok')) {
1226
- status = 'degraded'
1227
- }
1228
-
1229
- const context = typeof this.healthConfig.contextProvider === 'function'
1230
- ? await this.healthConfig.contextProvider()
1231
- : undefined
1232
-
1233
- const report: HealthReport = {
1234
- status,
1235
- live,
1236
- ready,
1237
- service: {
1238
- name: this.name,
1239
- advertisableFQDN: this.advertisableFQDN,
1240
- port: this.port,
1241
- network: this.network,
1242
- startedAt: this.startTime?.toISOString(),
1243
- uptimeMs: this.startTime === undefined ? 0 : Date.now() - this.startTime.getTime(),
1244
- topicManagerCount: Object.keys(this.managers).length,
1245
- lookupServiceCount: Object.keys(this.services).length
1246
- },
1247
- checks: this.healthConfig.includeDetails
1248
- ? checks
1249
- : checks.map(({ details, ...check }) => check),
1250
- context
1251
- }
1252
-
1253
- return report
1254
- }
1255
-
1256
- /**
1257
- * Renders a request or response body for verbose logging, truncating overly long payloads.
1258
- */
1259
- private formatBodyForLog (body: any, tooLongLabel: string, okPrefix: string): string {
1260
- let bodyString: string
1261
- if (typeof body === 'object') {
1262
- bodyString = JSON.stringify(body, null, 2)
1263
- } else if (Buffer.isBuffer(body)) {
1264
- bodyString = body.toString('utf8')
1265
- } else {
1266
- bodyString = String(body)
1267
- }
1268
- return bodyString.length > 280
1269
- ? chalk.yellow(`(${tooLongLabel}, length: ${String(bodyString.length)} characters)`)
1270
- : chalk.green(`${okPrefix}\n${bodyString}`)
1271
- }
1272
-
1273
- /**
1274
- * Installs middleware that verbosely logs incoming requests and outgoing responses.
1275
- */
1276
- private setupVerboseRequestLogging (): void {
1277
- this.app.use((req, res, next) => {
1278
- const startTime = Date.now()
1279
-
1280
- // Log incoming request details
1281
- this.logger.log(chalk.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`))
1282
- // Pretty-print headers
1283
- this.logger.log(chalk.cyan('Headers:'))
1284
- this.logger.log(util.inspect(req.headers, { colors: true, depth: null }))
1285
-
1286
- // Handle request body
1287
- if (req.body != null && Object.keys(req.body).length > 0) {
1288
- this.logger.log(this.formatBodyForLog(req.body, 'Body too long to display', 'Request Body:'))
1289
- }
1290
-
1291
- // Intercept the res.send method to log responses
1292
- const originalSend = res.send
1293
- let responseBody: any
1294
-
1295
- res.send = function (body?: any): any {
1296
- responseBody = body
1297
- return originalSend.call(this, body)
1298
- }
1299
-
1300
- // Log outgoing response details after the response is finished
1301
- res.on('finish', () => {
1302
- const duration = Date.now() - startTime
1303
- this.logger.log(
1304
- chalk.magenta.bold(
1305
- `Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`
1306
- )
1307
- )
1308
- this.logger.log(chalk.cyan('Response Headers:'))
1309
- this.logger.log(util.inspect(res.getHeaders(), { colors: true, depth: null }))
1310
-
1311
- // Handle response body
1312
- if (responseBody != null) {
1313
- this.logger.log(this.formatBodyForLog(responseBody, 'Response body too long to display', 'Response Body:'))
1314
- }
1315
- })
1316
-
1317
- next()
1318
- })
1319
- }
1320
-
1321
- /**
1322
- * Starts the Express server.
1323
- * Sets up routes and begins listening on the configured port.
1324
- */
1325
- async start (): Promise<void> {
1326
- const engine = this.ensureEngine()
1327
- const knex = this.ensureKnex()
1328
- this.startTime = new Date()
1329
-
1330
- this.app.use(bodyParser.json({ limit: '1gb', type: 'application/json' }))
1331
- this.app.use(bodyParser.raw({ limit: '1gb', type: 'application/octet-stream' }))
1332
-
1333
- if (this.verboseRequestLogging) {
1334
- this.setupVerboseRequestLogging()
1335
- }
1336
-
1337
- // Enable CORS
1338
- this.app.use((req, res, next) => {
1339
- res.header('Access-Control-Allow-Origin', '*')
1340
- res.header('Access-Control-Allow-Headers', '*')
1341
- res.header('Access-Control-Allow-Methods', '*')
1342
- res.header('Access-Control-Expose-Headers', '*')
1343
- res.header('Access-Control-Allow-Private-Network', 'true')
1344
- if (req.method === 'OPTIONS') {
1345
- res.sendStatus(200)
1346
- } else {
1347
- next()
1348
- }
1349
- })
1350
-
1351
- // Serve a static documentation site or user interface
1352
- this.app.get('/', (req, res) => {
1353
- res.set('content-type', 'text/html')
1354
- res.send(makeUserInterface({
1355
- ...this.webUIConfig,
1356
- adminIdentityKey: this.adminIdentityKey
1357
- }))
1358
- })
1359
-
1360
- // Serve health check endpoints
1361
- this.app.get('/health/live', (_, res) => {
1362
- ; (async () => {
1363
- const report = await this.collectHealthReport('live')
1364
- return res.status(report.live ? 200 : 503).json(report)
1365
- })().catch((error) => {
1366
- res.status(500).json({
1367
- status: 'error',
1368
- message: error instanceof Error ? error.message : 'Unexpected error'
1369
- })
1370
- })
1371
- })
1372
-
1373
- this.app.get('/health/ready', (_, res) => {
1374
- ; (async () => {
1375
- const report = await this.collectHealthReport('ready')
1376
- return res.status(report.ready ? 200 : 503).json(report)
1377
- })().catch((error) => {
1378
- res.status(500).json({
1379
- status: 'error',
1380
- message: error instanceof Error ? error.message : 'Unexpected error'
1381
- })
1382
- })
1383
- })
1384
-
1385
- this.app.get('/health', (_, res) => {
1386
- ; (async () => {
1387
- const report = await this.collectHealthReport('full')
1388
- return res.status(report.ready ? 200 : 503).json(report)
1389
- })().catch((error) => {
1390
- res.status(500).json({
1391
- status: 'error',
1392
- message: error instanceof Error ? error.message : 'Unexpected error'
1393
- })
1394
- })
1395
- })
1396
-
1397
- // List hosted topic managers and lookup services
1398
- this.app.get('/listTopicManagers', (_, res) => {
1399
- ; (async () => {
1400
- try {
1401
- const result = await engine.listTopicManagers()
1402
- return res.status(200).json(result)
1403
- } catch (error) {
1404
- return res.status(400).json({
1405
- status: 'error',
1406
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1407
- })
1408
- }
1409
- })().catch(() => {
1410
- res.status(500).json({
1411
- status: 'error',
1412
- message: 'Unexpected error'
1413
- })
1414
- })
1415
- })
1416
-
1417
- this.app.get('/listLookupServiceProviders', (_, res) => {
1418
- ; (async () => {
1419
- try {
1420
- const result = await engine.listLookupServiceProviders()
1421
- return res.status(200).json(result)
1422
- } catch (error) {
1423
- return res.status(400).json({
1424
- status: 'error',
1425
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1426
- })
1427
- }
1428
- })().catch(() => {
1429
- res.status(500).json({
1430
- status: 'error',
1431
- message: 'Unexpected error'
1432
- })
1433
- })
1434
- })
1435
-
1436
- // Host documentation for the services
1437
- this.app.get('/getDocumentationForTopicManager', (req, res) => {
1438
- ; (async () => {
1439
- try {
1440
- const manager = req.query.manager as string
1441
- const result = await engine.getDocumentationForTopicManager(manager)
1442
- res.setHeader('Content-Type', 'text/markdown')
1443
- return res.status(200).send(result)
1444
- } catch (error) {
1445
- return res.status(400).json({
1446
- status: 'error',
1447
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1448
- })
1449
- }
1450
- })().catch(() => {
1451
- res.status(500).json({
1452
- status: 'error',
1453
- message: 'Unexpected error'
1454
- })
1455
- })
1456
- })
1457
-
1458
- this.app.get('/getDocumentationForLookupServiceProvider', (req, res) => {
1459
- ; (async () => {
1460
- try {
1461
- const lookupService = req.query.lookupService as string
1462
- const result = await engine.getDocumentationForLookupServiceProvider(lookupService)
1463
- res.setHeader('Content-Type', 'text/markdown')
1464
- return res.status(200).send(result)
1465
- } catch (error) {
1466
- return res.status(400).json({
1467
- status: 'error',
1468
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1469
- })
1470
- }
1471
- })().catch(() => {
1472
- res.status(500).json({
1473
- status: 'error',
1474
- message: 'Unexpected error'
1475
- })
1476
- })
1477
- })
1478
-
1479
- // Submit transactions and facilitate lookup requests
1480
- this.app.post('/submit', (req, res) => {
1481
- ; (async () => {
1482
- try {
1483
- // Parse out the topics and construct the tagged BEEF
1484
- const topicsHeader = req.headers['x-topics']
1485
- const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true'
1486
- if (typeof topicsHeader !== 'string') {
1487
- throw new TypeError('Missing x-topics header')
1488
- }
1489
- const topics = parseTopicsHeader(topicsHeader)
1490
- const body = req.body
1491
- if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
1492
- throw new TypeError('Missing or empty BEEF body')
1493
- }
1494
- let offChainValues: number[] | undefined
1495
- let beef = Array.from(body as number[])
1496
- if (includesOffChain) {
1497
- const r = new Utils.Reader(beef)
1498
- const l = r.readVarIntNum()
1499
- beef = r.read(l)
1500
- offChainValues = r.read()
1501
- }
1502
- const taggedBEEF: TaggedBEEF = {
1503
- beef,
1504
- topics,
1505
- offChainValues
1506
- }
1507
-
1508
- // Using a callback function, we can return once the STEAK is ready
1509
- let responseSent = false
1510
- const steak = await engine.submit(taggedBEEF, (steak: STEAK) => {
1511
- responseSent = true
1512
- return res.status(200).json(steak)
1513
- }, 'current-tx', offChainValues)
1514
- if (!responseSent) {
1515
- res.status(200).json(steak)
1516
- }
1517
- } catch (error) {
1518
- console.error(chalk.red('Error in /submit:'), error)
1519
- return res.status(400).json({
1520
- status: 'error',
1521
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1522
- })
1523
- }
1524
- })().catch(() => {
1525
- res.status(500).json({
1526
- status: 'error',
1527
- message: 'Unexpected error'
1528
- })
1529
- })
1530
- })
1531
-
1532
- this.app.post('/lookup', (req, res) => {
1533
- ; (async () => {
1534
- try {
1535
- // Check for aggregation header to determine response format
1536
- const aggregationHeader = req.headers['x-aggregation']
1537
- const shouldReturnBinary = aggregationHeader === 'yes'
1538
-
1539
- // Validate request body structure
1540
- const lookupRequest = req.body as { service: string, query: unknown }
1541
- if (typeof lookupRequest.service !== 'string' || lookupRequest.query === undefined) {
1542
- return res.status(400).json({
1543
- status: 'error',
1544
- message: 'Invalid request: body must contain "service" (string) and "query" fields'
1545
- })
1546
- }
1547
-
1548
- const result = await engine.lookup(lookupRequest)
1549
-
1550
- if (!shouldReturnBinary) {
1551
- // Return JSON response (default behavior)
1552
- return res.status(200).json(result)
1553
- }
1554
-
1555
- const beef = new Beef()
1556
- const outputs = result.outputs
1557
-
1558
- // Serialize in the format expected by LookupResolver
1559
- const writer = new Utils.Writer()
1560
-
1561
- // Write number of outpoints
1562
- writer.writeVarIntNum(outputs.length)
1563
-
1564
- // Write each outpoint data
1565
- for (const output of outputs) {
1566
- const tx = Transaction.fromBEEF(output.beef)
1567
- // Write txid (32 bytes)
1568
- writer.write(tx.id())
1569
- // Write outputIndex
1570
- writer.writeVarIntNum(output.outputIndex)
1571
- // Write context length and data
1572
- if ((output.context != null) && output.context.length > 0) {
1573
- writer.writeVarIntNum(output.context.length)
1574
- writer.write(output.context)
1575
- } else {
1576
- writer.writeVarIntNum(0)
1577
- }
1578
- beef.mergeTransaction(tx)
1579
- }
1580
-
1581
- // Write the beef data
1582
- writer.write(beef.toBinary())
1583
-
1584
- res.setHeader('Content-Type', 'application/octet-stream')
1585
- return res.status(200).send(Buffer.from(writer.toArray()))
1586
- } catch (error) {
1587
- console.error(chalk.red('Error in /lookup:'), error)
1588
- return res.status(400).json({
1589
- status: 'error',
1590
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1591
- })
1592
- }
1593
- })().catch(() => {
1594
- res.status(500).json({
1595
- status: 'error',
1596
- message: 'Unexpected error'
1597
- })
1598
- })
1599
- })
1600
-
1601
- // ARC/Arcade ingest route (only if a provider is configured)
1602
- if (
1603
- (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1604
- (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)
1605
- ) {
1606
- this.app.post('/arc-ingest', (req, res) => {
1607
- ; (async () => {
1608
- try {
1609
- if (typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0) {
1610
- const authorization = req.headers.authorization
1611
- const headerToken = Array.isArray(authorization) ? authorization[0] : authorization
1612
- const xCallbackToken = req.headers['x-callback-token']
1613
- const callbackToken = Array.isArray(xCallbackToken) ? xCallbackToken[0] : xCallbackToken
1614
- const bearerToken = typeof headerToken === 'string' && headerToken.startsWith('Bearer ')
1615
- ? headerToken.slice('Bearer '.length)
1616
- : headerToken
1617
- if (bearerToken !== this.arcCallbackToken && callbackToken !== this.arcCallbackToken) {
1618
- return res.status(401).json({ status: 'error', message: 'Unauthorized callback' })
1619
- }
1620
- }
1621
- const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body
1622
- if (typeof txid !== 'string' || txid === '') {
1623
- throw new TypeError('Provider callback is missing txid')
1624
- }
1625
- if (isTerminalArcStatus(txStatus, extraInfo)) {
1626
- const report = await (engine as BASMCapableEngine).evictAppliedTransaction(txid, {
1627
- topic: typeof topic === 'string' ? topic : undefined,
1628
- reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1629
- })
1630
- this.logger.warn({
1631
- operation: 'overlay.provider_callback',
1632
- outcome: 'terminal_evicted',
1633
- txid,
1634
- txStatus,
1635
- competingTxs,
1636
- report
1637
- })
1638
- return res.status(200).json({
1639
- status: 'success',
1640
- message: 'Terminal transaction status processed',
1641
- data: {
1642
- ...report,
1643
- txStatus,
1644
- competingTxs
1645
- }
1646
- })
1647
- }
1648
- if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1649
- return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' })
1650
- }
1651
- const merklePath = MerklePath.fromHex(merklePathHex)
1652
- await engine.handleNewMerkleProof(txid, merklePath, blockHeight)
1653
- this.logger.log({
1654
- operation: 'overlay.provider_callback',
1655
- outcome: 'proof_ingested',
1656
- txid,
1657
- blockHeight
1658
- })
1659
- return res.status(200).json({ status: 'success', message: 'Transaction status updated' })
1660
- } catch (error) {
1661
- console.error(chalk.red('Error in /arc-ingest:'), error)
1662
- return res.status(400).json({
1663
- status: 'error',
1664
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1665
- })
1666
- }
1667
- })().catch(() => {
1668
- res.status(500).json({
1669
- status: 'error',
1670
- message: 'Unexpected error'
1671
- })
1672
- })
1673
- })
1674
- } else {
1675
- this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'))
1676
- }
1677
-
1678
- // GASP sync routes if enabled
1679
- if (this.enableGASPSync) {
1680
- this.app.post('/requestSyncResponse', (req, res) => {
1681
- ; (async () => {
1682
- try {
1683
- const topic = req.headers['x-bsv-topic'] as string
1684
- const response = await engine.provideForeignSyncResponse(req.body, topic)
1685
- return res.status(200).json(response)
1686
- } catch (error) {
1687
- console.error(chalk.red('Error in /requestSyncResponse:'), error)
1688
- return res.status(400).json({
1689
- status: 'error',
1690
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1691
- })
1692
- }
1693
- })().catch(() => {
1694
- res.status(500).json({
1695
- status: 'error',
1696
- message: 'Unexpected error'
1697
- })
1698
- })
1699
- })
1700
-
1701
- this.app.post('/requestForeignGASPNode', (req, res) => {
1702
- ; (async () => {
1703
- try {
1704
- const { graphID, txid, outputIndex } = req.body
1705
- const response = await engine.provideForeignGASPNode(graphID, txid, outputIndex)
1706
- return res.status(200).json(response)
1707
- } catch (error) {
1708
- console.error(chalk.red('Error in /requestForeignGASPNode:'), error)
1709
- return res.status(400).json({
1710
- status: 'error',
1711
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1712
- })
1713
- }
1714
- })().catch(() => {
1715
- res.status(500).json({
1716
- status: 'error',
1717
- message: 'Unexpected error'
1718
- })
1719
- })
1720
- })
1721
- } else {
1722
- this.logger.warn(chalk.yellow('GASP sync is disabled.'))
1723
- }
1724
-
1725
- // BRC-136 BASM anchor and raw transaction endpoints.
1726
- const basmEngine = engine as BASMCapableEngine
1727
- const readBasmTopic = (req: express.Request): string => {
1728
- const header = req.headers['x-bsv-topic']
1729
- if (typeof header !== 'string' || header.length === 0) {
1730
- throw new TypeError('Missing x-bsv-topic header')
1731
- }
1732
- return header
1733
- }
1734
-
1735
- /**
1736
- * Registers a POST route whose handler resolves to the JSON payload returned
1737
- * with HTTP 200. Any thrown error is logged and returned as HTTP 400, while
1738
- * unexpected rejections fall back to HTTP 500. This consolidates the shared
1739
- * async/try-catch boilerplate used by the BRC-136 BASM endpoints (and the
1740
- * BASM-related admin endpoints, which additionally pass `checkAdminAuth`).
1741
- */
1742
- const registerJsonRoute = (
1743
- path: string,
1744
- handler: (req: express.Request) => Promise<unknown>,
1745
- ...middleware: express.RequestHandler[]
1746
- ): void => {
1747
- this.app.post(path, ...(middleware as any[]), (req: express.Request, res: express.Response) => {
1748
- ; (async () => {
1749
- try {
1750
- return res.status(200).json(await handler(req))
1751
- } catch (error) {
1752
- console.error(chalk.red(`Error in ${path}:`), error)
1753
- return res.status(400).json({
1754
- status: 'error',
1755
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1756
- })
1757
- }
1758
- })().catch(() => {
1759
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
1760
- })
1761
- })
1762
- }
1763
-
1764
- const requireTxids = (value: unknown): string[] => {
1765
- if (!Array.isArray(value) || !value.every(txid => typeof txid === 'string')) {
1766
- throw new TypeError('txids must be an array of strings')
1767
- }
1768
- return value
1769
- }
1770
-
1771
- registerJsonRoute('/requestTopicAnchorTip', async req =>
1772
- await basmEngine.provideTopicAnchorTip(readBasmTopic(req)))
1773
-
1774
- registerJsonRoute('/requestTopicAnchorRange', async req => {
1775
- const { fromHeight, toHeight } = req.body
1776
- return await basmEngine.provideTopicAnchorRange(readBasmTopic(req), Number(fromHeight), Number(toHeight))
1777
- })
1778
-
1779
- registerJsonRoute('/requestAdmittedList', async req => {
1780
- const { blockHeight, blockHash } = req.body
1781
- return await basmEngine.provideAdmittedList(
1782
- readBasmTopic(req),
1783
- Number(blockHeight),
1784
- typeof blockHash === 'string' ? blockHash : undefined
1785
- )
1786
- })
1787
-
1788
- registerJsonRoute('/requestCompoundMerklePath', async req => {
1789
- const topic = readBasmTopic(req)
1790
- const { blockHeight, txids } = req.body
1791
- return await basmEngine.provideCompoundMerklePath(topic, Number(blockHeight), requireTxids(txids))
1792
- })
1793
-
1794
- registerJsonRoute('/requestRawTransactions', async req =>
1795
- await basmEngine.provideRawTransactions(requireTxids(req.body.txids)))
1796
-
1797
- /**
1798
- * ============== ADMIN ROUTES ==============
1799
- * These routes expose advanced engine operations.
1800
- * Authentication: Bearer token OR BSV mutual auth (identity key match).
1801
- */
1802
-
1803
- /**
1804
- * Set up BSV mutual authentication middleware if a server wallet is available.
1805
- * This handles the /.well-known/auth handshake automatically.
1806
- * With allowUnauthenticated: true, it passes through when no BSV auth headers
1807
- * are present, allowing Bearer token fallback.
1808
- */
1809
- if (this.serverWallet !== undefined) {
1810
- const bsvAuth = createAuthMiddleware({
1811
- wallet: this.serverWallet,
1812
- allowUnauthenticated: true
1813
- })
1814
- this.app.use(bsvAuth as any)
1815
- this.logger.log(chalk.blue('BSV mutual authentication middleware enabled.'))
1816
- }
1817
-
1818
- /**
1819
- * Middleware for checking admin authentication.
1820
- * Supports two authentication methods:
1821
- * 1. Bearer token (Authorization: Bearer <token>) - for cron jobs, scripts, and fallback
1822
- * 2. BSV mutual auth - if req.auth.identityKey matches the admin identity key
1823
- */
1824
- const checkAdminAuth = (req: express.Request, res: express.Response, next: express.NextFunction): void => {
1825
- // Method 1: BSV mutual authentication (identity key match)
1826
- const authReq = req as unknown as AuthRequest
1827
- if (
1828
- typeof this.adminIdentityKey === 'string' &&
1829
- authReq.auth !== undefined &&
1830
- typeof authReq.auth.identityKey === 'string' &&
1831
- authReq.auth.identityKey !== 'unknown' &&
1832
- authReq.auth.identityKey === this.adminIdentityKey
1833
- ) {
1834
- next()
1835
- return
1836
- }
1837
-
1838
- // Method 2: Bearer token authentication
1839
- const authHeader = req.headers.authorization
1840
- if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
1841
- const token = authHeader.substring('Bearer '.length)
1842
- if (token === this.adminToken) {
1843
- next()
1844
- return
1845
- }
1846
- res.status(403).json({ status: 'error', message: 'Forbidden: Invalid credentials' })
1847
- return
1848
- }
1849
-
1850
- res.status(401).json({ status: 'error', message: 'Unauthorized: Provide a Bearer token or authenticate with your wallet' })
1851
- }
1852
-
1853
- /**
1854
- * Public endpoint that returns the admin identity key (if configured).
1855
- * This allows the frontend to detect whether the current wallet user
1856
- * is the admin by comparing their identity key against this value.
1857
- * The identity key is a public key, so exposing it is safe.
1858
- */
1859
- this.app.get('/admin/config', (_, res) => {
1860
- res.status(200).json({
1861
- adminIdentityKey: this.adminIdentityKey ?? null,
1862
- nodeName: this.name
1863
- })
1864
- })
1865
-
1866
- /**
1867
- * Admin route: Get server statistics and overview.
1868
- */
1869
- this.app.get('/admin/stats', checkAdminAuth as any, (req, res) => {
1870
- ; (async () => {
1871
- try {
1872
- const db = this.ensureMongo()
1873
-
1874
- const [shipCount, slapCount, banStats] = await Promise.all([
1875
- db.collection('shipRecords').countDocuments(),
1876
- db.collection('slapRecords').countDocuments(),
1877
- this.banService?.getStats() ?? { domainBans: 0, outpointBans: 0, totalBans: 0 }
1878
- ])
1879
-
1880
- return res.status(200).json({
1881
- status: 'success',
1882
- data: {
1883
- nodeName: this.name,
1884
- network: this.network,
1885
- uptime: this.startTime != null ? Date.now() - this.startTime.getTime() : 0,
1886
- startedAt: this.startTime?.toISOString(),
1887
- shipRecordCount: shipCount,
1888
- slapRecordCount: slapCount,
1889
- bannedDomains: banStats.domainBans,
1890
- bannedOutpoints: banStats.outpointBans,
1891
- totalBans: banStats.totalBans,
1892
- topicManagers: Object.keys(this.managers),
1893
- lookupServices: Object.keys(this.services),
1894
- gaspSyncEnabled: this.enableGASPSync,
1895
- basmSyncEnabled: this.enableBASMSync,
1896
- unprovenEvictionBlocks: this.unprovenEvictionBlocks
1897
- }
1898
- })
1899
- } catch (error) {
1900
- return res.status(400).json({
1901
- status: 'error',
1902
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1903
- })
1904
- }
1905
- })().catch(() => {
1906
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
1907
- })
1908
- })
1909
-
1910
- /**
1911
- * Admin route: List all SHIP records with full details.
1912
- */
1913
- this.app.get('/admin/ship-records', checkAdminAuth as any, (req, res) => {
1914
- ; (async () => {
1915
- try {
1916
- const db = this.ensureMongo()
1917
- const collection = db.collection('shipRecords')
1918
-
1919
- const search = typeof req.query.search === 'string' ? req.query.search : undefined
1920
- const rawPage = Number.parseInt(req.query.page as string, 10)
1921
- const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage)
1922
- const rawLimit = Number.parseInt(req.query.limit as string, 10)
1923
- const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit))
1924
- const skip = (page - 1) * limit
1925
-
1926
- const query: any = {}
1927
- if (typeof search === 'string' && search.length > 0) {
1928
- query.$or = [
1929
- { domain: { $regex: search, $options: 'i' } },
1930
- { topic: { $regex: search, $options: 'i' } },
1931
- { identityKey: { $regex: search, $options: 'i' } },
1932
- { txid: { $regex: search, $options: 'i' } }
1933
- ]
1934
- }
1935
-
1936
- const [records, total] = await Promise.all([
1937
- collection.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray(),
1938
- collection.countDocuments(query)
1939
- ])
1940
-
1941
- return res.status(200).json({
1942
- status: 'success',
1943
- data: { records, total, page, limit, pages: Math.ceil(total / limit) }
1944
- })
1945
- } catch (error) {
1946
- return res.status(400).json({
1947
- status: 'error',
1948
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1949
- })
1950
- }
1951
- })().catch(() => {
1952
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
1953
- })
1954
- })
1955
-
1956
- /**
1957
- * Admin route: List all SLAP records with full details.
1958
- */
1959
- this.app.get('/admin/slap-records', checkAdminAuth as any, (req, res) => {
1960
- ; (async () => {
1961
- try {
1962
- const db = this.ensureMongo()
1963
- const collection = db.collection('slapRecords')
1964
-
1965
- const search = typeof req.query.search === 'string' ? req.query.search : undefined
1966
- const rawPage = Number.parseInt(req.query.page as string, 10)
1967
- const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage)
1968
- const rawLimit = Number.parseInt(req.query.limit as string, 10)
1969
- const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit))
1970
- const skip = (page - 1) * limit
1971
-
1972
- const query: any = {}
1973
- if (typeof search === 'string' && search.length > 0) {
1974
- query.$or = [
1975
- { domain: { $regex: search, $options: 'i' } },
1976
- { service: { $regex: search, $options: 'i' } },
1977
- { identityKey: { $regex: search, $options: 'i' } },
1978
- { txid: { $regex: search, $options: 'i' } }
1979
- ]
1980
- }
1981
-
1982
- const [records, total] = await Promise.all([
1983
- collection.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).toArray(),
1984
- collection.countDocuments(query)
1985
- ])
1986
-
1987
- return res.status(200).json({
1988
- status: 'success',
1989
- data: { records, total, page, limit, pages: Math.ceil(total / limit) }
1990
- })
1991
- } catch (error) {
1992
- return res.status(400).json({
1993
- status: 'error',
1994
- message: error instanceof Error ? error.message : 'An unknown error occurred'
1995
- })
1996
- }
1997
- })().catch(() => {
1998
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
1999
- })
2000
- })
2001
-
2002
- /**
2003
- * Admin route: Check health of a specific URL.
2004
- */
2005
- this.app.post('/admin/health-check', checkAdminAuth as any, (req, res) => {
2006
- ; (async () => {
2007
- try {
2008
- const url = req.body?.url
2009
- if (typeof url !== 'string' || url.length === 0) {
2010
- return res.status(400).json({ status: 'error', message: 'url is required' })
2011
- }
2012
- const janitor = this.createJanitor()
2013
- const result = await janitor.checkHost(url)
2014
- return res.status(200).json({ status: 'success', data: { url, ...result } })
2015
- } catch (error) {
2016
- return res.status(400).json({
2017
- status: 'error',
2018
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2019
- })
2020
- }
2021
- })().catch(() => {
2022
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
2023
- })
2024
- })
2025
-
2026
- /**
2027
- * Admin route: Ban a domain or outpoint.
2028
- */
2029
- this.app.post('/admin/ban', checkAdminAuth as any, (req, res) => {
2030
- ; (async () => {
2031
- try {
2032
- if (this.banService === undefined) {
2033
- return res.status(400).json({ status: 'error', message: 'Ban service not available (MongoDB not configured)' })
2034
- }
2035
-
2036
- const { type, value, reason } = req.body
2037
- if (type !== 'domain' && type !== 'outpoint') {
2038
- return res.status(400).json({ status: 'error', message: 'type must be "domain" or "outpoint"' })
2039
- }
2040
- if (typeof value !== 'string' || value.length === 0) {
2041
- return res.status(400).json({ status: 'error', message: 'value is required' })
2042
- }
2043
-
2044
- if (type === 'domain') {
2045
- return await this.handleBanDomain(res, value, reason)
2046
- }
2047
- return await this.handleBanOutpoint(res, engine, value, reason)
2048
- } catch (error) {
2049
- return res.status(400).json({
2050
- status: 'error',
2051
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2052
- })
2053
- }
2054
- })().catch(() => {
2055
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
2056
- })
2057
- })
2058
-
2059
- /**
2060
- * Admin route: Remove a ban.
2061
- */
2062
- this.app.post('/admin/unban', checkAdminAuth as any, (req, res) => {
2063
- ; (async () => {
2064
- try {
2065
- if (this.banService === undefined) {
2066
- return res.status(400).json({ status: 'error', message: 'Ban service not available' })
2067
- }
2068
- const { type, value } = req.body as { type: unknown, value: unknown }
2069
- if (type !== 'domain' && type !== 'outpoint') {
2070
- return res.status(400).json({ status: 'error', message: 'type must be "domain" or "outpoint"' })
2071
- }
2072
- if (typeof value !== 'string' || value.length === 0) {
2073
- return res.status(400).json({ status: 'error', message: 'value is required' })
2074
- }
2075
-
2076
- await this.banService.removeBan(type, value)
2077
- return res.status(200).json({ status: 'success', message: `${type} "${String(value)}" unbanned.` })
2078
- } catch (error) {
2079
- return res.status(400).json({
2080
- status: 'error',
2081
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2082
- })
2083
- }
2084
- })().catch(() => {
2085
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
2086
- })
2087
- })
2088
-
2089
- /**
2090
- * Admin route: List all bans.
2091
- */
2092
- this.app.get('/admin/bans', checkAdminAuth as any, (req, res) => {
2093
- ; (async () => {
2094
- try {
2095
- if (this.banService === undefined) {
2096
- return res.status(200).json({ status: 'success', data: { bans: [] } })
2097
- }
2098
- const type = req.query.type as 'domain' | 'outpoint' | undefined
2099
- const validType = type === 'domain' || type === 'outpoint' ? type : undefined
2100
- const bans = await this.banService.listBans(validType)
2101
- return res.status(200).json({ status: 'success', data: { bans } })
2102
- } catch (error) {
2103
- return res.status(400).json({
2104
- status: 'error',
2105
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2106
- })
2107
- }
2108
- })().catch(() => {
2109
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
2110
- })
2111
- })
2112
-
2113
- /**
2114
- * Admin route: Remove a token by outpoint, optionally banning the domain.
2115
- */
2116
- this.app.post('/admin/remove-token', checkAdminAuth as any, (req, res) => {
2117
- ; (async () => {
2118
- try {
2119
- const { txid, outputIndex, service, ban, banDomain: shouldBanDomain } = req.body
2120
- if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
2121
- return res.status(400).json({ status: 'error', message: 'txid (string) and outputIndex (number) are required' })
2122
- }
2123
-
2124
- // Look up domain before eviction if needed for banning
2125
- let removedDomain: string | undefined
2126
- if (shouldBanDomain === true || ban === true) {
2127
- removedDomain = await this.lookupDomainForOutpoint(txid, outputIndex)
2128
- }
2129
-
2130
- await this.evictFromServices(engine, txid, outputIndex, service)
2131
-
2132
- if (ban === true && this.banService !== undefined) {
2133
- await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain)
2134
- }
2135
-
2136
- if (shouldBanDomain === true && typeof removedDomain === 'string' && this.banService !== undefined) {
2137
- await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal')
2138
- }
2139
-
2140
- const banMsg = ban === true ? ' Outpoint banned.' : ''
2141
- const domainMsg = shouldBanDomain === true && typeof removedDomain === 'string'
2142
- ? ` Domain "${removedDomain}" banned.`
2143
- : ''
2144
- return res.status(200).json({
2145
- status: 'success',
2146
- message: `Token ${txid}.${outputIndex} removed.${banMsg}${domainMsg}`
2147
- })
2148
- } catch (error) {
2149
- return res.status(400).json({
2150
- status: 'error',
2151
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2152
- })
2153
- }
2154
- })().catch(() => {
2155
- res.status(500).json({ status: 'error', message: 'Unexpected error' })
2156
- })
2157
- })
2158
-
2159
- /**
2160
- * Admin route to manually sync advertisements, calling `engine.syncAdvertisements()`.
2161
- */
2162
- this.app.post('/admin/syncAdvertisements', checkAdminAuth as any, (req, res) => {
2163
- ; (async () => {
2164
- try {
2165
- await engine.syncAdvertisements()
2166
- return res.status(200).json({ status: 'success', message: 'Advertisements synced successfully' })
2167
- } catch (error) {
2168
- console.error(chalk.red('Error in /admin/syncAdvertisements:'), error)
2169
- return res.status(400).json({
2170
- status: 'error',
2171
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2172
- })
2173
- }
2174
- })().catch(() => {
2175
- res.status(500).json({
2176
- status: 'error',
2177
- message: 'Unexpected error'
2178
- })
2179
- })
2180
- })
2181
-
2182
- /**
2183
- * Admin route to manually start GASP sync, calling `engine.startGASPSync()`.
2184
- */
2185
- this.app.post('/admin/startGASPSync', checkAdminAuth as any, (req, res) => {
2186
- ; (async () => {
2187
- try {
2188
- await engine.startGASPSync()
2189
- return res.status(200).json({ status: 'success', message: 'GASP sync started and completed' })
2190
- } catch (error) {
2191
- console.error(chalk.red('Error in /admin/startGASPSync:'), error)
2192
- return res.status(400).json({
2193
- status: 'error',
2194
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2195
- })
2196
- }
2197
- })().catch(() => {
2198
- res.status(500).json({
2199
- status: 'error',
2200
- message: 'Unexpected error'
2201
- })
2202
- })
2203
- })
2204
-
2205
- /**
2206
- * Admin route to manually start BASM sync, calling `engine.startBASMSync()`.
2207
- */
2208
- registerJsonRoute('/admin/startBASMSync', async () => {
2209
- const report = await basmEngine.startBASMSync()
2210
- return { status: 'success', message: 'BASM sync started and completed', data: report }
2211
- }, checkAdminAuth as any)
2212
-
2213
- /**
2214
- * Admin route to evict expired unproven topic transactions.
2215
- */
2216
- registerJsonRoute('/admin/evictUnproven', async req => {
2217
- const { topic, thresholdBlocks } = req.body ?? {}
2218
- const report = await basmEngine.evictUnprovenTransactions({
2219
- topic: typeof topic === 'string' ? topic : undefined,
2220
- thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
2221
- })
2222
- this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report })
2223
- return { status: 'success', message: 'Unproven eviction completed', data: report }
2224
- }, checkAdminAuth as any)
2225
-
2226
- /**
2227
- * Admin route to refresh proofs for expired unproven topic transactions
2228
- * using the configured proof providers.
2229
- */
2230
- registerJsonRoute('/admin/refreshUnprovenProofs', async req => {
2231
- const { topic, thresholdBlocks } = req.body ?? {}
2232
- const report = await basmEngine.refreshUnprovenTransactionProofs({
2233
- topic: typeof topic === 'string' ? topic : undefined,
2234
- thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
2235
- proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2236
- })
2237
- this.logger.log({ operation: 'overlay.unproven_proof_refresh', outcome: 'ok', report })
2238
- return { status: 'success', message: 'Unproven proof refresh completed', data: report }
2239
- }, checkAdminAuth as any)
2240
-
2241
- /**
2242
- * Admin route to refresh proofs first, then evict rows that remain unproven.
2243
- */
2244
- registerJsonRoute('/admin/maintainUnproven', async req => {
2245
- const { topic, thresholdBlocks } = req.body ?? {}
2246
- const report = await basmEngine.maintainUnprovenTransactions({
2247
- topic: typeof topic === 'string' ? topic : undefined,
2248
- thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
2249
- proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2250
- })
2251
- this.logger.log({ operation: 'overlay.unproven_maintenance', outcome: 'ok', report })
2252
- return { status: 'success', message: 'Unproven maintenance completed', data: report }
2253
- }, checkAdminAuth as any)
2254
-
2255
- /**
2256
- * Admin route to evict an outpoint, either from all services or a specific one.
2257
- */
2258
- this.app.post('/admin/evictOutpoint', checkAdminAuth as any, (req, res) => {
2259
- ; (async () => {
2260
- try {
2261
- if (typeof req.body.service === 'string') {
2262
- const service = engine.lookupServices[req.body.service]
2263
- await service.outputEvicted(req.body.txid, req.body.outputIndex)
2264
- } else {
2265
- const services = Object.values(engine.lookupServices)
2266
- for (const service of services) {
2267
- try {
2268
- await service.outputEvicted(req.body.txid, req.body.outputIndex)
2269
- } catch {
2270
- continue
2271
- }
2272
- }
2273
- }
2274
- return res.status(200).json({ status: 'success', message: 'Outpoint evicted' })
2275
- } catch (error) {
2276
- console.error(chalk.red('Error in /admin/evictOutpoint:'), error)
2277
- return res.status(400).json({
2278
- status: 'error',
2279
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2280
- })
2281
- }
2282
- })().catch(() => {
2283
- res.status(500).json({
2284
- status: 'error',
2285
- message: 'Unexpected error'
2286
- })
2287
- })
2288
- })
2289
-
2290
- /**
2291
- * Admin route to run the janitor service with enhanced reporting.
2292
- */
2293
- this.app.post('/admin/janitor', checkAdminAuth as any, (req, res) => {
2294
- ; (async () => {
2295
- try {
2296
- const janitor = this.createJanitor()
2297
- const report: JanitorReport = await janitor.run()
2298
- return res.status(200).json({ status: 'success', message: 'Janitor run completed', data: report })
2299
- } catch (error) {
2300
- console.error(chalk.red('Error in /admin/janitor:'), error)
2301
- return res.status(400).json({
2302
- status: 'error',
2303
- message: error instanceof Error ? error.message : 'An unknown error occurred'
2304
- })
2305
- }
2306
- })().catch(() => {
2307
- res.status(500).json({
2308
- status: 'error',
2309
- message: 'Unexpected error'
2310
- })
2311
- })
2312
- })
2313
-
2314
- // Automatically handle migrations
2315
- const migrationSource = new InMemoryMigrationSource(this.migrationsToRun)
2316
- const result = await knex.migrate.latest({
2317
- migrationSource
2318
- })
2319
- this.logger.log(chalk.green('Knex migrations run'), result)
2320
-
2321
- // 404 handler for all other routes
2322
- this.app.use((req, res) => {
2323
- this.logger.log(chalk.red('404 Not Found:'), req.url)
2324
- res.status(404).json({
2325
- status: 'error',
2326
- code: 'ERR_ROUTE_NOT_FOUND',
2327
- description: 'Route not found.'
2328
- })
2329
- })
2330
-
2331
- await this.runStartupSync()
2332
-
2333
- // Start listening on the configured port
2334
- this.app.listen(this.port, () => {
2335
- this.isListening = true
2336
- this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`))
2337
- })
2338
- }
2339
-
2340
- /**
2341
- * Runs the post-listen startup work: advertiser init, advertisement sync,
2342
- * and the optional GASP/BASM background syncs.
2343
- */
2344
- private async runStartupSync (): Promise<void> {
2345
- // The legacy Ninja advertiser has a setLookupEngine method.
2346
- if (this.engine?.advertiser instanceof DiscoveryServices.WalletAdvertiser) {
2347
- this.logger.log(
2348
- chalk.cyan(
2349
- `${this.name} will now advertise with SHIP and SLAP as appropriate at FQDN: ${this.advertisableFQDN}`
2350
- )
2351
- )
2352
- await this.engine.advertiser.init()
2353
- }
2354
-
2355
- // Log some info about topic managers and services
2356
- const numTopicManagers = Object.keys(this.managers).length
2357
- const numLookupServices = Object.keys(this.services).length
2358
- this.logger.log(chalk.blue(`Topic Managers: ${numTopicManagers}`))
2359
- this.logger.log(chalk.blue(`Lookup Services: ${numLookupServices}`))
2360
-
2361
- // Attempt to sync advertisements
2362
- try {
2363
- await this.engine?.syncAdvertisements()
2364
- } catch (e) {
2365
- this.logger.log(chalk.red('Error syncing advertisements:'), e)
2366
- }
2367
-
2368
- await this.runGaspStartupSync()
2369
- await this.runBasmStartupSync()
2370
- this.startUnprovenMaintenance()
2371
- }
2372
-
2373
- /** Attempt a GASP sync at startup when enabled. */
2374
- private async runGaspStartupSync (): Promise<void> {
2375
- if (!this.enableGASPSync) {
2376
- this.logger.log(chalk.yellow(`${this.name} will not sync because GASP has been disabled.`))
2377
- return
2378
- }
2379
- try {
2380
- this.logger.log(chalk.green('Starting GASP sync...'))
2381
- await this.engine?.startGASPSync()
2382
- this.logger.log(chalk.green('GASP sync complete!'))
2383
- } catch (e) {
2384
- console.error(chalk.red('Failed to GASP sync'), e)
2385
- }
2386
- }
2387
-
2388
- /** Attempt a BASM sync at startup when enabled, then begin tip-following. */
2389
- private async runBasmStartupSync (): Promise<void> {
2390
- if (!(this.enableBASMSync || this.engineConfig.enableBASMSync === true)) {
2391
- return
2392
- }
2393
- try {
2394
- this.logger.log(chalk.green('Starting BASM sync...'))
2395
- const report = await (this.engine as BASMCapableEngine | undefined)?.startBASMSync()
2396
- this.logger.log(chalk.green('BASM sync complete!'), report)
2397
- } catch (e) {
2398
- console.error(chalk.red('Failed to BASM sync'), e)
2399
- }
2400
-
2401
- // Extend each topic's anchor chain to the current tip on startup, then keep
2402
- // it following the tip so the cumulative TAC advances after each new block.
2403
- await this.advanceBASMAnchorChains()
2404
- this.startBASMBlockPolling()
2405
- this.startBASMReorgStream()
2406
- }
2407
-
2408
- /** Poll for new blocks to advance anchor chains and detect reorgs. */
2409
- private startBASMBlockPolling (): void {
2410
- if (this.basmBlockPollIntervalMs <= 0) {
2411
- return
2412
- }
2413
- this.basmBlockPollTimer = setInterval(() => {
2414
- void this.advanceBASMAnchorChains()
2415
- // Fallback reorg detection for chain trackers without a reorg stream,
2416
- // and a safety net even when the SSE adapter is active.
2417
- void this.revalidateBASMAnchors()
2418
- }, this.basmBlockPollIntervalMs)
2419
- this.basmBlockPollTimer.unref?.()
2420
- }
2421
-
2422
- /** Real-time reorg reconciliation via the go-chaintracks (Arcade) reorg SSE. */
2423
- private startBASMReorgStream (): void {
2424
- const reorgStreamUrl = this.engineConfig.reorgStreamUrl ?? this.reorgStreamUrl
2425
- const reorgScanDepth = this.engineConfig.reorgScanDepth ?? this.reorgScanDepth
2426
- if (reorgStreamUrl === undefined || reorgStreamUrl === '') {
2427
- return
2428
- }
2429
- const basmEngine = this.engine as BASMCapableEngine | undefined
2430
- this.reorgAdapter = new ReorgSseAdapter({
2431
- url: reorgStreamUrl,
2432
- onReorg: async input => { await basmEngine?.handleReorg(input) },
2433
- onConnect: async () => { await basmEngine?.revalidateRecentAnchors(reorgScanDepth) },
2434
- logger: this.logger
2435
- })
2436
- this.reorgAdapter.start()
2437
- this.logger.log(chalk.green(`BASM reorg stream listening at ${reorgStreamUrl}`))
2438
- }
2439
-
2440
- /** Extend every topic's BASM anchor chain to the current chain tip. */
2441
- private async advanceBASMAnchorChains (): Promise<void> {
2442
- try {
2443
- await (this.engine as BASMCapableEngine | undefined)?.advanceTopicAnchorChains()
2444
- } catch (e) {
2445
- console.error(chalk.red('Failed to advance BASM anchor chains'), e)
2446
- }
2447
- }
2448
-
2449
- /** Revalidate recent BASM anchors against the chain tracker, reconciling any reorg. */
2450
- private async revalidateBASMAnchors (): Promise<void> {
2451
- try {
2452
- const depth = this.engineConfig.reorgScanDepth ?? this.reorgScanDepth
2453
- await (this.engine as BASMCapableEngine | undefined)?.revalidateRecentAnchors(depth)
2454
- } catch (e) {
2455
- console.error(chalk.red('Failed to revalidate BASM anchors'), e)
2456
- }
2457
- }
2458
-
2459
- private startUnprovenMaintenance (): void {
2460
- const intervalMs = this.engineConfig.unprovenMaintenanceIntervalMs ?? this.unprovenMaintenanceIntervalMs
2461
- if (intervalMs <= 0) return
2462
- const run = (): void => {
2463
- void (async () => {
2464
- try {
2465
- const report = await (this.engine as BASMCapableEngine | undefined)?.maintainUnprovenTransactions({
2466
- thresholdBlocks: this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks,
2467
- proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
2468
- })
2469
- this.logger.log(chalk.green('Unproven transaction maintenance complete'), report)
2470
- } catch (e) {
2471
- console.error(chalk.red('Failed to maintain unproven transactions'), e)
2472
- }
2473
- })()
2474
- }
2475
- run()
2476
- this.unprovenMaintenanceTimer = setInterval(run, intervalMs)
2477
- this.unprovenMaintenanceTimer.unref?.()
2478
- }
2479
- }