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