@bsv/overlay-express 2.4.0 → 2.4.2
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.
- package/README.md +122 -3
- package/dist/cjs/mod.js +8 -1
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +19 -19
- package/dist/cjs/src/ArcadeProvider.js +196 -0
- package/dist/cjs/src/ArcadeProvider.js.map +1 -0
- package/dist/cjs/src/ChaintracksProvider.js +65 -0
- package/dist/cjs/src/ChaintracksProvider.js.map +1 -0
- package/dist/cjs/src/OverlayExpress.js +270 -28
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/src/OverlayMonitor.js +117 -3
- package/dist/cjs/src/OverlayMonitor.js.map +1 -1
- package/dist/cjs/src/ProviderChainBroadcaster.js +91 -0
- package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -0
- package/dist/cjs/src/generalGuide.md.js +1 -1
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js +3 -0
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/ArcadeProvider.js +189 -0
- package/dist/esm/src/ArcadeProvider.js.map +1 -0
- package/dist/esm/src/ChaintracksProvider.js +62 -0
- package/dist/esm/src/ChaintracksProvider.js.map +1 -0
- package/dist/esm/src/OverlayExpress.js +265 -28
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/src/OverlayMonitor.js +117 -3
- package/dist/esm/src/OverlayMonitor.js.map +1 -1
- package/dist/esm/src/ProviderChainBroadcaster.js +88 -0
- package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -0
- package/dist/esm/src/generalGuide.md.js +1 -1
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +3 -0
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/ArcadeProvider.d.ts +37 -0
- package/dist/types/src/ArcadeProvider.d.ts.map +1 -0
- package/dist/types/src/ChaintracksProvider.d.ts +29 -0
- package/dist/types/src/ChaintracksProvider.d.ts.map +1 -0
- package/dist/types/src/OverlayExpress.d.ts +38 -1
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/src/OverlayMonitor.d.ts +28 -0
- package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
- package/dist/types/src/ProviderChainBroadcaster.d.ts +18 -0
- package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -0
- package/dist/types/src/generalGuide.md.d.ts +1 -1
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +15 -0
- package/package.json +19 -19
- package/src/ArcadeProvider.ts +232 -0
- package/src/ChaintracksProvider.ts +79 -0
- package/src/OverlayExpress.ts +299 -28
- package/src/OverlayMonitor.ts +163 -3
- package/src/ProviderChainBroadcaster.ts +108 -0
- package/src/__tests__/OverlayExpress.test.ts +196 -4
- package/src/__tests__/OverlayMonitor.test.ts +74 -0
- package/src/__tests__/OverlayProviders.live.test.ts +43 -0
- package/src/__tests__/OverlayProviders.test.ts +123 -0
- package/src/generalGuide.md.ts +1 -1
package/src/OverlayExpress.ts
CHANGED
|
@@ -42,6 +42,9 @@ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoverySto
|
|
|
42
42
|
import { ReorgSseAdapter, type ReorgHandlerInput } from './ReorgStream.js'
|
|
43
43
|
import { Wallet, WalletSigner, WalletStorageManager, Services } from '@bsv/wallet-toolbox-client'
|
|
44
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'
|
|
45
48
|
|
|
46
49
|
/**
|
|
47
50
|
* Knex database migration.
|
|
@@ -107,6 +110,7 @@ export interface EngineConfig {
|
|
|
107
110
|
unprovenEvictionBlocks?: number
|
|
108
111
|
reorgStreamUrl?: string
|
|
109
112
|
reorgScanDepth?: number
|
|
113
|
+
unprovenMaintenanceIntervalMs?: number
|
|
110
114
|
}
|
|
111
115
|
|
|
112
116
|
export type HealthStatus = 'ok' | 'degraded' | 'error'
|
|
@@ -169,10 +173,33 @@ interface BASMCapableEngine extends Engine {
|
|
|
169
173
|
startBASMSync: () => Promise<any>
|
|
170
174
|
advanceTopicAnchorChains: (toHeight?: number) => Promise<void>
|
|
171
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>
|
|
172
187
|
handleReorg: (input: ReorgHandlerInput) => Promise<any>
|
|
173
188
|
revalidateRecentAnchors: (depth?: number) => Promise<any>
|
|
174
189
|
}
|
|
175
190
|
|
|
191
|
+
function parseTopicsHeader (header: string): string[] {
|
|
192
|
+
const value = header.trim()
|
|
193
|
+
const parsed: unknown = value.startsWith('[')
|
|
194
|
+
? JSON.parse(value)
|
|
195
|
+
: value.split(',').map(topic => topic.trim())
|
|
196
|
+
|
|
197
|
+
if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
|
|
198
|
+
throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array')
|
|
199
|
+
}
|
|
200
|
+
return parsed
|
|
201
|
+
}
|
|
202
|
+
|
|
176
203
|
/**
|
|
177
204
|
* OverlayExpress class provides an Express-based server for hosting Overlay Services.
|
|
178
205
|
* It allows configuration of various components like databases, topic managers, and lookup services.
|
|
@@ -235,6 +262,12 @@ export default class OverlayExpress {
|
|
|
235
262
|
// Handle for the BASM block-poll timer so it can be stopped.
|
|
236
263
|
private basmBlockPollTimer?: ReturnType<typeof setInterval>
|
|
237
264
|
|
|
265
|
+
// How often (ms) to refresh proofs for old unproven rows and then evict rows
|
|
266
|
+
// that still have no proof. Set to 0 to disable background maintenance.
|
|
267
|
+
unprovenMaintenanceIntervalMs: number = 0
|
|
268
|
+
|
|
269
|
+
private unprovenMaintenanceTimer?: ReturnType<typeof setInterval>
|
|
270
|
+
|
|
238
271
|
// Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
|
|
239
272
|
// When set, reorgs are reconciled in real time; the block poll also runs a
|
|
240
273
|
// revalidation sweep as a fallback / reconnect catch-up.
|
|
@@ -255,6 +288,15 @@ export default class OverlayExpress {
|
|
|
255
288
|
// Optional ARC callback token for /arc-ingest notifications
|
|
256
289
|
arcCallbackToken: string | undefined = undefined
|
|
257
290
|
|
|
291
|
+
// Optional Arcade URL/API key used for propagation, proof refresh, and
|
|
292
|
+
// go-chaintracks header/reorg access when available.
|
|
293
|
+
arcadeUrl: string | undefined = undefined
|
|
294
|
+
arcadeApiKey: string | undefined = undefined
|
|
295
|
+
arcadeDeploymentId: string | undefined = undefined
|
|
296
|
+
arcadeChaintracksApiPrefix: string = '/chaintracks/v2'
|
|
297
|
+
|
|
298
|
+
private arcadeProvider?: ArcadeProvider
|
|
299
|
+
|
|
258
300
|
// Verbose request logging
|
|
259
301
|
verboseRequestLogging: boolean = false
|
|
260
302
|
|
|
@@ -447,6 +489,50 @@ export default class OverlayExpress {
|
|
|
447
489
|
this.logger.log(chalk.blue('ARC callback token has been configured.'))
|
|
448
490
|
}
|
|
449
491
|
|
|
492
|
+
/**
|
|
493
|
+
* Configures Arcade for first-choice transaction propagation and proof lookup.
|
|
494
|
+
*/
|
|
495
|
+
configureArcade (url: string, config: {
|
|
496
|
+
apiKey?: string
|
|
497
|
+
deploymentId?: string
|
|
498
|
+
chaintracksApiPrefix?: string
|
|
499
|
+
} = {}): void {
|
|
500
|
+
this.arcadeUrl = url
|
|
501
|
+
this.arcadeApiKey = config.apiKey
|
|
502
|
+
this.arcadeDeploymentId = config.deploymentId
|
|
503
|
+
if (config.chaintracksApiPrefix !== undefined) {
|
|
504
|
+
this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix
|
|
505
|
+
}
|
|
506
|
+
this.logger.log(chalk.blue('Arcade provider has been configured.'))
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
/**
|
|
510
|
+
* Configures a go-chaintracks compatible service for header validation and
|
|
511
|
+
* BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
|
|
512
|
+
*/
|
|
513
|
+
configureChaintracks (url: string, config: {
|
|
514
|
+
apiPrefix?: string
|
|
515
|
+
reorgStream?: boolean
|
|
516
|
+
scanDepth?: number
|
|
517
|
+
} = {}): void {
|
|
518
|
+
const apiPrefix = config.apiPrefix ?? '/chaintracks/v2'
|
|
519
|
+
const client = new ChaintracksProvider(url, { apiPrefix })
|
|
520
|
+
this.configureChainTracker(client)
|
|
521
|
+
this.configureTopicAnchorHeaderResolver(async blockHeight => {
|
|
522
|
+
const header = await client.findHeaderForHeight(blockHeight)
|
|
523
|
+
if (header === undefined) return undefined
|
|
524
|
+
return {
|
|
525
|
+
blockHeight,
|
|
526
|
+
blockHash: header.hash,
|
|
527
|
+
merkleRoot: header.merkleRoot
|
|
528
|
+
}
|
|
529
|
+
})
|
|
530
|
+
if (config.reorgStream !== false) {
|
|
531
|
+
this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth)
|
|
532
|
+
}
|
|
533
|
+
this.logger.log(chalk.blue('go-chaintracks provider has been configured.'))
|
|
534
|
+
}
|
|
535
|
+
|
|
450
536
|
/**
|
|
451
537
|
* Enables or disables GASP synchronization (high-level setting).
|
|
452
538
|
* This is a broad toggle that can be overridden or customized through syncConfiguration.
|
|
@@ -498,6 +584,20 @@ export default class OverlayExpress {
|
|
|
498
584
|
this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'))
|
|
499
585
|
}
|
|
500
586
|
|
|
587
|
+
/**
|
|
588
|
+
* Configures periodic unproven maintenance. Each run first tries configured
|
|
589
|
+
* proof providers, then evicts rows that are still unproven past the threshold.
|
|
590
|
+
*/
|
|
591
|
+
configureUnprovenMaintenance (config: { intervalMs?: number, thresholdBlocks?: number }): void {
|
|
592
|
+
if (config.intervalMs !== undefined) {
|
|
593
|
+
this.unprovenMaintenanceIntervalMs = config.intervalMs
|
|
594
|
+
}
|
|
595
|
+
if (config.thresholdBlocks !== undefined) {
|
|
596
|
+
this.unprovenEvictionBlocks = config.thresholdBlocks
|
|
597
|
+
}
|
|
598
|
+
this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'))
|
|
599
|
+
}
|
|
600
|
+
|
|
501
601
|
/**
|
|
502
602
|
* Configures how often the BASM anchor chain is extended with empty anchors to
|
|
503
603
|
* follow the chain tip. Set to 0 to disable periodic polling.
|
|
@@ -634,22 +734,29 @@ export default class OverlayExpress {
|
|
|
634
734
|
const knex = this.ensureKnex()
|
|
635
735
|
|
|
636
736
|
if (autoConfigureShipSlap) {
|
|
737
|
+
const mongoDb = this.ensureMongo()
|
|
738
|
+
const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb)
|
|
739
|
+
const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb)
|
|
740
|
+
|
|
741
|
+
// Run the one-time discovery migration before the engine can accept
|
|
742
|
+
// traffic, so a failed unique-index build is a visible startup failure.
|
|
743
|
+
await shipStorage.ensureIndexes()
|
|
744
|
+
await slapStorage.ensureIndexes()
|
|
745
|
+
|
|
637
746
|
this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager())
|
|
638
747
|
this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager())
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
return new DiscoveryServices.SLAPLookupService(storageForLookup as any)
|
|
652
|
-
})
|
|
748
|
+
|
|
749
|
+
const shipStorageForLookup = this.banService === undefined
|
|
750
|
+
? shipStorage
|
|
751
|
+
: new BanAwareSHIPStorage(shipStorage, this.banService, this.logger)
|
|
752
|
+
const slapStorageForLookup = this.banService === undefined
|
|
753
|
+
? slapStorage
|
|
754
|
+
: new BanAwareSLAPStorage(slapStorage, this.banService, this.logger)
|
|
755
|
+
|
|
756
|
+
this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup as any)
|
|
757
|
+
this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup as any)
|
|
758
|
+
this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'))
|
|
759
|
+
this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'))
|
|
653
760
|
}
|
|
654
761
|
|
|
655
762
|
this.wrapBanAwareServices()
|
|
@@ -677,7 +784,7 @@ export default class OverlayExpress {
|
|
|
677
784
|
syncConfig,
|
|
678
785
|
this.engineConfig.logTime ?? false,
|
|
679
786
|
this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
|
|
680
|
-
this.engineConfig.throwOnBroadcastFailure ??
|
|
787
|
+
this.engineConfig.throwOnBroadcastFailure ?? true,
|
|
681
788
|
this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
|
|
682
789
|
this.logger,
|
|
683
790
|
this.engineConfig.suppressDefaultSyncAdvertisements ?? true,
|
|
@@ -721,15 +828,85 @@ export default class OverlayExpress {
|
|
|
721
828
|
return syncConfig
|
|
722
829
|
}
|
|
723
830
|
|
|
724
|
-
/** Build the
|
|
831
|
+
/** Build the configured transaction propagation provider chain. */
|
|
725
832
|
private buildBroadcaster (): Broadcaster | undefined {
|
|
726
|
-
|
|
727
|
-
const
|
|
728
|
-
|
|
729
|
-
|
|
833
|
+
const providers: NamedBroadcaster[] = []
|
|
834
|
+
const callbackUrl = `https://${this.advertisableFQDN}/arc-ingest`
|
|
835
|
+
|
|
836
|
+
if (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0) {
|
|
837
|
+
this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
|
|
838
|
+
apiKey: this.arcadeApiKey,
|
|
839
|
+
callbackUrl,
|
|
840
|
+
callbackToken: this.arcCallbackToken,
|
|
841
|
+
deploymentId: this.arcadeDeploymentId
|
|
842
|
+
})
|
|
843
|
+
providers.push({
|
|
844
|
+
name: 'Arcade',
|
|
845
|
+
broadcaster: this.arcadeProvider
|
|
846
|
+
})
|
|
847
|
+
} else {
|
|
848
|
+
this.arcadeProvider = undefined
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
|
|
852
|
+
const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
|
|
853
|
+
providers.push({
|
|
854
|
+
name: 'ARC',
|
|
855
|
+
broadcaster: new ARC(arcUrl, {
|
|
856
|
+
apiKey: this.arcApiKey,
|
|
857
|
+
callbackUrl,
|
|
858
|
+
callbackToken: this.arcCallbackToken
|
|
859
|
+
})
|
|
860
|
+
})
|
|
861
|
+
}
|
|
862
|
+
|
|
863
|
+
if (providers.length === 0) return undefined
|
|
864
|
+
if (providers.length === 1) return providers[0].broadcaster
|
|
865
|
+
return new ProviderChainBroadcaster(providers)
|
|
866
|
+
}
|
|
867
|
+
|
|
868
|
+
private ensureArcadeProvider (): ArcadeProvider | undefined {
|
|
869
|
+
if (this.arcadeProvider !== undefined) return this.arcadeProvider
|
|
870
|
+
if (typeof this.arcadeUrl !== 'string' || this.arcadeUrl.length === 0) return undefined
|
|
871
|
+
this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
|
|
872
|
+
apiKey: this.arcadeApiKey,
|
|
730
873
|
callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
|
|
731
|
-
callbackToken: this.arcCallbackToken
|
|
874
|
+
callbackToken: this.arcCallbackToken,
|
|
875
|
+
deploymentId: this.arcadeDeploymentId
|
|
732
876
|
})
|
|
877
|
+
return this.arcadeProvider
|
|
878
|
+
}
|
|
879
|
+
|
|
880
|
+
private async fetchArcadeProof (txid: string): Promise<ArcadeMerkleProof | undefined> {
|
|
881
|
+
const provider = this.ensureArcadeProvider()
|
|
882
|
+
if (provider === undefined) return undefined
|
|
883
|
+
const proof = await provider.fetchMerkleProof(txid)
|
|
884
|
+
if (proof === undefined) return undefined
|
|
885
|
+
const chainTracker = this.engineConfig.chainTracker ?? this.chainTracker
|
|
886
|
+
if (chainTracker === 'scripts only') {
|
|
887
|
+
throw new Error('Cannot validate Arcade proof with scripts-only chain tracker')
|
|
888
|
+
}
|
|
889
|
+
const blockHeight = proof.blockHeight ?? proof.merklePath.blockHeight
|
|
890
|
+
if (blockHeight === undefined) {
|
|
891
|
+
throw new Error(`Arcade proof for ${txid} did not include a block height`)
|
|
892
|
+
}
|
|
893
|
+
const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight)
|
|
894
|
+
if (!valid) {
|
|
895
|
+
throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`)
|
|
896
|
+
}
|
|
897
|
+
return {
|
|
898
|
+
...proof,
|
|
899
|
+
blockHeight
|
|
900
|
+
}
|
|
901
|
+
}
|
|
902
|
+
|
|
903
|
+
private async fetchConfiguredMerkleProof (txid: string): Promise<{ merklePath: MerklePath, blockHeight?: number } | undefined> {
|
|
904
|
+
const proof = await this.fetchArcadeProof(txid)
|
|
905
|
+
if (proof === undefined) return undefined
|
|
906
|
+
return {
|
|
907
|
+
merklePath: proof.merklePath,
|
|
908
|
+
blockHeight: proof.blockHeight
|
|
909
|
+
}
|
|
733
910
|
}
|
|
734
911
|
|
|
735
912
|
/** Build the BASM block header resolver. */
|
|
@@ -1309,9 +1486,13 @@ export default class OverlayExpress {
|
|
|
1309
1486
|
if (typeof topicsHeader !== 'string') {
|
|
1310
1487
|
throw new TypeError('Missing x-topics header')
|
|
1311
1488
|
}
|
|
1312
|
-
const topics =
|
|
1489
|
+
const topics = parseTopicsHeader(topicsHeader)
|
|
1490
|
+
const body = req.body
|
|
1491
|
+
if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
|
|
1492
|
+
throw new TypeError('Missing or empty BEEF body')
|
|
1493
|
+
}
|
|
1313
1494
|
let offChainValues: number[] | undefined
|
|
1314
|
-
let beef = Array.from(
|
|
1495
|
+
let beef = Array.from(body as number[])
|
|
1315
1496
|
if (includesOffChain) {
|
|
1316
1497
|
const r = new Utils.Reader(beef)
|
|
1317
1498
|
const l = r.readVarIntNum()
|
|
@@ -1417,8 +1598,11 @@ export default class OverlayExpress {
|
|
|
1417
1598
|
})
|
|
1418
1599
|
})
|
|
1419
1600
|
|
|
1420
|
-
// ARC ingest route (only if
|
|
1421
|
-
if (
|
|
1601
|
+
// ARC/Arcade ingest route (only if a provider is configured)
|
|
1602
|
+
if (
|
|
1603
|
+
(typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
|
|
1604
|
+
(typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)
|
|
1605
|
+
) {
|
|
1422
1606
|
this.app.post('/arc-ingest', (req, res) => {
|
|
1423
1607
|
; (async () => {
|
|
1424
1608
|
try {
|
|
@@ -1434,9 +1618,44 @@ export default class OverlayExpress {
|
|
|
1434
1618
|
return res.status(401).json({ status: 'error', message: 'Unauthorized callback' })
|
|
1435
1619
|
}
|
|
1436
1620
|
}
|
|
1437
|
-
const { txid, merklePath: merklePathHex, blockHeight } = req.body
|
|
1621
|
+
const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body
|
|
1622
|
+
if (typeof txid !== 'string' || txid === '') {
|
|
1623
|
+
throw new TypeError('Provider callback is missing txid')
|
|
1624
|
+
}
|
|
1625
|
+
if (isTerminalArcStatus(txStatus, extraInfo)) {
|
|
1626
|
+
const report = await (engine as BASMCapableEngine).evictAppliedTransaction(txid, {
|
|
1627
|
+
topic: typeof topic === 'string' ? topic : undefined,
|
|
1628
|
+
reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
|
|
1629
|
+
})
|
|
1630
|
+
this.logger.warn({
|
|
1631
|
+
operation: 'overlay.provider_callback',
|
|
1632
|
+
outcome: 'terminal_evicted',
|
|
1633
|
+
txid,
|
|
1634
|
+
txStatus,
|
|
1635
|
+
competingTxs,
|
|
1636
|
+
report
|
|
1637
|
+
})
|
|
1638
|
+
return res.status(200).json({
|
|
1639
|
+
status: 'success',
|
|
1640
|
+
message: 'Terminal transaction status processed',
|
|
1641
|
+
data: {
|
|
1642
|
+
...report,
|
|
1643
|
+
txStatus,
|
|
1644
|
+
competingTxs
|
|
1645
|
+
}
|
|
1646
|
+
})
|
|
1647
|
+
}
|
|
1648
|
+
if (typeof merklePathHex !== 'string' || merklePathHex === '') {
|
|
1649
|
+
return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' })
|
|
1650
|
+
}
|
|
1438
1651
|
const merklePath = MerklePath.fromHex(merklePathHex)
|
|
1439
1652
|
await engine.handleNewMerkleProof(txid, merklePath, blockHeight)
|
|
1653
|
+
this.logger.log({
|
|
1654
|
+
operation: 'overlay.provider_callback',
|
|
1655
|
+
outcome: 'proof_ingested',
|
|
1656
|
+
txid,
|
|
1657
|
+
blockHeight
|
|
1658
|
+
})
|
|
1440
1659
|
return res.status(200).json({ status: 'success', message: 'Transaction status updated' })
|
|
1441
1660
|
} catch (error) {
|
|
1442
1661
|
console.error(chalk.red('Error in /arc-ingest:'), error)
|
|
@@ -1453,7 +1672,7 @@ export default class OverlayExpress {
|
|
|
1453
1672
|
})
|
|
1454
1673
|
})
|
|
1455
1674
|
} else {
|
|
1456
|
-
this.logger.warn(chalk.yellow('Disabling ARC because no
|
|
1675
|
+
this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'))
|
|
1457
1676
|
}
|
|
1458
1677
|
|
|
1459
1678
|
// GASP sync routes if enabled
|
|
@@ -1786,7 +2005,7 @@ export default class OverlayExpress {
|
|
|
1786
2005
|
this.app.post('/admin/health-check', checkAdminAuth as any, (req, res) => {
|
|
1787
2006
|
; (async () => {
|
|
1788
2007
|
try {
|
|
1789
|
-
const
|
|
2008
|
+
const url = req.body?.url
|
|
1790
2009
|
if (typeof url !== 'string' || url.length === 0) {
|
|
1791
2010
|
return res.status(400).json({ status: 'error', message: 'url is required' })
|
|
1792
2011
|
}
|
|
@@ -2000,9 +2219,39 @@ export default class OverlayExpress {
|
|
|
2000
2219
|
topic: typeof topic === 'string' ? topic : undefined,
|
|
2001
2220
|
thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
|
|
2002
2221
|
})
|
|
2222
|
+
this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report })
|
|
2003
2223
|
return { status: 'success', message: 'Unproven eviction completed', data: report }
|
|
2004
2224
|
}, checkAdminAuth as any)
|
|
2005
2225
|
|
|
2226
|
+
/**
|
|
2227
|
+
* Admin route to refresh proofs for expired unproven topic transactions
|
|
2228
|
+
* using the configured proof providers.
|
|
2229
|
+
*/
|
|
2230
|
+
registerJsonRoute('/admin/refreshUnprovenProofs', async req => {
|
|
2231
|
+
const { topic, thresholdBlocks } = req.body ?? {}
|
|
2232
|
+
const report = await basmEngine.refreshUnprovenTransactionProofs({
|
|
2233
|
+
topic: typeof topic === 'string' ? topic : undefined,
|
|
2234
|
+
thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
|
|
2235
|
+
proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
|
|
2236
|
+
})
|
|
2237
|
+
this.logger.log({ operation: 'overlay.unproven_proof_refresh', outcome: 'ok', report })
|
|
2238
|
+
return { status: 'success', message: 'Unproven proof refresh completed', data: report }
|
|
2239
|
+
}, checkAdminAuth as any)
|
|
2240
|
+
|
|
2241
|
+
/**
|
|
2242
|
+
* Admin route to refresh proofs first, then evict rows that remain unproven.
|
|
2243
|
+
*/
|
|
2244
|
+
registerJsonRoute('/admin/maintainUnproven', async req => {
|
|
2245
|
+
const { topic, thresholdBlocks } = req.body ?? {}
|
|
2246
|
+
const report = await basmEngine.maintainUnprovenTransactions({
|
|
2247
|
+
topic: typeof topic === 'string' ? topic : undefined,
|
|
2248
|
+
thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
|
|
2249
|
+
proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
|
|
2250
|
+
})
|
|
2251
|
+
this.logger.log({ operation: 'overlay.unproven_maintenance', outcome: 'ok', report })
|
|
2252
|
+
return { status: 'success', message: 'Unproven maintenance completed', data: report }
|
|
2253
|
+
}, checkAdminAuth as any)
|
|
2254
|
+
|
|
2006
2255
|
/**
|
|
2007
2256
|
* Admin route to evict an outpoint, either from all services or a specific one.
|
|
2008
2257
|
*/
|
|
@@ -2118,6 +2367,7 @@ export default class OverlayExpress {
|
|
|
2118
2367
|
|
|
2119
2368
|
await this.runGaspStartupSync()
|
|
2120
2369
|
await this.runBasmStartupSync()
|
|
2370
|
+
this.startUnprovenMaintenance()
|
|
2121
2371
|
}
|
|
2122
2372
|
|
|
2123
2373
|
/** Attempt a GASP sync at startup when enabled. */
|
|
@@ -2205,4 +2455,25 @@ export default class OverlayExpress {
|
|
|
2205
2455
|
console.error(chalk.red('Failed to revalidate BASM anchors'), e)
|
|
2206
2456
|
}
|
|
2207
2457
|
}
|
|
2458
|
+
|
|
2459
|
+
private startUnprovenMaintenance (): void {
|
|
2460
|
+
const intervalMs = this.engineConfig.unprovenMaintenanceIntervalMs ?? this.unprovenMaintenanceIntervalMs
|
|
2461
|
+
if (intervalMs <= 0) return
|
|
2462
|
+
const run = (): void => {
|
|
2463
|
+
void (async () => {
|
|
2464
|
+
try {
|
|
2465
|
+
const report = await (this.engine as BASMCapableEngine | undefined)?.maintainUnprovenTransactions({
|
|
2466
|
+
thresholdBlocks: this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks,
|
|
2467
|
+
proofProvider: async txid => await this.fetchConfiguredMerkleProof(txid)
|
|
2468
|
+
})
|
|
2469
|
+
this.logger.log(chalk.green('Unproven transaction maintenance complete'), report)
|
|
2470
|
+
} catch (e) {
|
|
2471
|
+
console.error(chalk.red('Failed to maintain unproven transactions'), e)
|
|
2472
|
+
}
|
|
2473
|
+
})()
|
|
2474
|
+
}
|
|
2475
|
+
run()
|
|
2476
|
+
this.unprovenMaintenanceTimer = setInterval(run, intervalMs)
|
|
2477
|
+
this.unprovenMaintenanceTimer.unref?.()
|
|
2478
|
+
}
|
|
2208
2479
|
}
|