@bsv/overlay-express 2.4.0 → 2.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +9 -9
- 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 +235 -11
- 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/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 +231 -11
- 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/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/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +15 -0
- package/package.json +9 -9
- package/src/ArcadeProvider.ts +232 -0
- package/src/ChaintracksProvider.ts +79 -0
- package/src/OverlayExpress.ts +259 -11
- package/src/OverlayMonitor.ts +163 -3
- package/src/ProviderChainBroadcaster.ts +108 -0
- package/src/__tests__/OverlayExpress.test.ts +37 -3
- package/src/__tests__/OverlayMonitor.test.ts +74 -0
- package/src/__tests__/OverlayProviders.live.test.ts +39 -0
- package/src/__tests__/OverlayProviders.test.ts +123 -0
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,6 +173,17 @@ 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
|
}
|
|
@@ -235,6 +250,12 @@ export default class OverlayExpress {
|
|
|
235
250
|
// Handle for the BASM block-poll timer so it can be stopped.
|
|
236
251
|
private basmBlockPollTimer?: ReturnType<typeof setInterval>
|
|
237
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
|
+
|
|
238
259
|
// Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
|
|
239
260
|
// When set, reorgs are reconciled in real time; the block poll also runs a
|
|
240
261
|
// revalidation sweep as a fallback / reconnect catch-up.
|
|
@@ -255,6 +276,15 @@ export default class OverlayExpress {
|
|
|
255
276
|
// Optional ARC callback token for /arc-ingest notifications
|
|
256
277
|
arcCallbackToken: string | undefined = undefined
|
|
257
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
|
+
|
|
258
288
|
// Verbose request logging
|
|
259
289
|
verboseRequestLogging: boolean = false
|
|
260
290
|
|
|
@@ -447,6 +477,50 @@ export default class OverlayExpress {
|
|
|
447
477
|
this.logger.log(chalk.blue('ARC callback token has been configured.'))
|
|
448
478
|
}
|
|
449
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
|
+
|
|
450
524
|
/**
|
|
451
525
|
* Enables or disables GASP synchronization (high-level setting).
|
|
452
526
|
* This is a broad toggle that can be overridden or customized through syncConfiguration.
|
|
@@ -498,6 +572,20 @@ export default class OverlayExpress {
|
|
|
498
572
|
this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'))
|
|
499
573
|
}
|
|
500
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
|
+
|
|
501
589
|
/**
|
|
502
590
|
* Configures how often the BASM anchor chain is extended with empty anchors to
|
|
503
591
|
* follow the chain tip. Set to 0 to disable periodic polling.
|
|
@@ -677,7 +765,7 @@ export default class OverlayExpress {
|
|
|
677
765
|
syncConfig,
|
|
678
766
|
this.engineConfig.logTime ?? false,
|
|
679
767
|
this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
|
|
680
|
-
this.engineConfig.throwOnBroadcastFailure ??
|
|
768
|
+
this.engineConfig.throwOnBroadcastFailure ?? true,
|
|
681
769
|
this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
|
|
682
770
|
this.logger,
|
|
683
771
|
this.engineConfig.suppressDefaultSyncAdvertisements ?? true,
|
|
@@ -721,15 +809,85 @@ export default class OverlayExpress {
|
|
|
721
809
|
return syncConfig
|
|
722
810
|
}
|
|
723
811
|
|
|
724
|
-
/** Build the
|
|
812
|
+
/** Build the configured transaction propagation provider chain. */
|
|
725
813
|
private buildBroadcaster (): Broadcaster | undefined {
|
|
726
|
-
|
|
727
|
-
const
|
|
728
|
-
|
|
729
|
-
|
|
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,
|
|
730
854
|
callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
|
|
731
|
-
callbackToken: this.arcCallbackToken
|
|
855
|
+
callbackToken: this.arcCallbackToken,
|
|
856
|
+
deploymentId: this.arcadeDeploymentId
|
|
732
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
|
+
}
|
|
733
891
|
}
|
|
734
892
|
|
|
735
893
|
/** Build the BASM block header resolver. */
|
|
@@ -1417,8 +1575,11 @@ export default class OverlayExpress {
|
|
|
1417
1575
|
})
|
|
1418
1576
|
})
|
|
1419
1577
|
|
|
1420
|
-
// ARC ingest route (only if
|
|
1421
|
-
if (
|
|
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
|
+
) {
|
|
1422
1583
|
this.app.post('/arc-ingest', (req, res) => {
|
|
1423
1584
|
; (async () => {
|
|
1424
1585
|
try {
|
|
@@ -1434,9 +1595,44 @@ export default class OverlayExpress {
|
|
|
1434
1595
|
return res.status(401).json({ status: 'error', message: 'Unauthorized callback' })
|
|
1435
1596
|
}
|
|
1436
1597
|
}
|
|
1437
|
-
const { txid, merklePath: merklePathHex, blockHeight } = req.body
|
|
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
|
+
}
|
|
1438
1628
|
const merklePath = MerklePath.fromHex(merklePathHex)
|
|
1439
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
|
+
})
|
|
1440
1636
|
return res.status(200).json({ status: 'success', message: 'Transaction status updated' })
|
|
1441
1637
|
} catch (error) {
|
|
1442
1638
|
console.error(chalk.red('Error in /arc-ingest:'), error)
|
|
@@ -1453,7 +1649,7 @@ export default class OverlayExpress {
|
|
|
1453
1649
|
})
|
|
1454
1650
|
})
|
|
1455
1651
|
} else {
|
|
1456
|
-
this.logger.warn(chalk.yellow('Disabling ARC because no
|
|
1652
|
+
this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'))
|
|
1457
1653
|
}
|
|
1458
1654
|
|
|
1459
1655
|
// GASP sync routes if enabled
|
|
@@ -2000,9 +2196,39 @@ export default class OverlayExpress {
|
|
|
2000
2196
|
topic: typeof topic === 'string' ? topic : undefined,
|
|
2001
2197
|
thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
|
|
2002
2198
|
})
|
|
2199
|
+
this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report })
|
|
2003
2200
|
return { status: 'success', message: 'Unproven eviction completed', data: report }
|
|
2004
2201
|
}, checkAdminAuth as any)
|
|
2005
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
|
+
|
|
2006
2232
|
/**
|
|
2007
2233
|
* Admin route to evict an outpoint, either from all services or a specific one.
|
|
2008
2234
|
*/
|
|
@@ -2118,6 +2344,7 @@ export default class OverlayExpress {
|
|
|
2118
2344
|
|
|
2119
2345
|
await this.runGaspStartupSync()
|
|
2120
2346
|
await this.runBasmStartupSync()
|
|
2347
|
+
this.startUnprovenMaintenance()
|
|
2121
2348
|
}
|
|
2122
2349
|
|
|
2123
2350
|
/** Attempt a GASP sync at startup when enabled. */
|
|
@@ -2205,4 +2432,25 @@ export default class OverlayExpress {
|
|
|
2205
2432
|
console.error(chalk.red('Failed to revalidate BASM anchors'), e)
|
|
2206
2433
|
}
|
|
2207
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
|
+
}
|
|
2208
2456
|
}
|
package/src/OverlayMonitor.ts
CHANGED
|
@@ -22,11 +22,23 @@ export interface OverlayAnchorProbe {
|
|
|
22
22
|
maxTipLagBlocks?: number
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
+
export interface OverlayMaintenanceConfig {
|
|
26
|
+
adminToken?: string
|
|
27
|
+
headers?: Record<string, string>
|
|
28
|
+
maintainUnproven?: boolean | {
|
|
29
|
+
topics?: string[]
|
|
30
|
+
thresholdBlocks?: number
|
|
31
|
+
}
|
|
32
|
+
startBASMSync?: boolean
|
|
33
|
+
janitor?: boolean
|
|
34
|
+
}
|
|
35
|
+
|
|
25
36
|
export interface OverlayMonitorTarget {
|
|
26
37
|
name: string
|
|
27
38
|
baseUrl: string
|
|
28
39
|
probes: OverlayLookupProbe[]
|
|
29
40
|
anchorProbes?: OverlayAnchorProbe[]
|
|
41
|
+
maintenance?: OverlayMaintenanceConfig
|
|
30
42
|
headers?: Record<string, string>
|
|
31
43
|
}
|
|
32
44
|
|
|
@@ -105,17 +117,33 @@ export interface OverlayAnchorProbeResult {
|
|
|
105
117
|
error?: string
|
|
106
118
|
}
|
|
107
119
|
|
|
120
|
+
export interface OverlayMaintenanceResult {
|
|
121
|
+
target: string
|
|
122
|
+
url: string
|
|
123
|
+
operation: 'maintain-unproven' | 'start-basm-sync' | 'janitor'
|
|
124
|
+
topic?: string
|
|
125
|
+
status: number
|
|
126
|
+
ok: boolean
|
|
127
|
+
responseBytes: number
|
|
128
|
+
durationMs: number
|
|
129
|
+
data?: unknown
|
|
130
|
+
error?: string
|
|
131
|
+
}
|
|
132
|
+
|
|
108
133
|
export interface OverlayMonitorReport {
|
|
109
134
|
startedAt: Date
|
|
110
135
|
completedAt: Date
|
|
111
136
|
durationMs: number
|
|
112
137
|
results: OverlayLookupProbeResult[]
|
|
113
138
|
anchorResults: OverlayAnchorProbeResult[]
|
|
139
|
+
maintenanceResults: OverlayMaintenanceResult[]
|
|
114
140
|
summary: {
|
|
115
141
|
targetCount: number
|
|
116
142
|
probeCount: number
|
|
117
143
|
anchorProbeCount: number
|
|
144
|
+
maintenanceActionCount: number
|
|
118
145
|
failedProbeCount: number
|
|
146
|
+
failedMaintenanceActionCount: number
|
|
119
147
|
responseBytes: number
|
|
120
148
|
outputCount: number
|
|
121
149
|
analyzedOutputCount: number
|
|
@@ -182,6 +210,7 @@ export class OverlayMonitor {
|
|
|
182
210
|
const startedAt = this.now()
|
|
183
211
|
const results: OverlayLookupProbeResult[] = []
|
|
184
212
|
const anchorResults: OverlayAnchorProbeResult[] = []
|
|
213
|
+
const maintenanceResults: OverlayMaintenanceResult[] = []
|
|
185
214
|
|
|
186
215
|
for (const target of this.targets) {
|
|
187
216
|
for (const probe of target.probes) {
|
|
@@ -190,6 +219,7 @@ export class OverlayMonitor {
|
|
|
190
219
|
for (const probe of target.anchorProbes ?? []) {
|
|
191
220
|
anchorResults.push(await this.runAnchorProbe(target, probe))
|
|
192
221
|
}
|
|
222
|
+
maintenanceResults.push(...await this.runMaintenance(target))
|
|
193
223
|
}
|
|
194
224
|
|
|
195
225
|
const completedAt = this.now()
|
|
@@ -199,7 +229,8 @@ export class OverlayMonitor {
|
|
|
199
229
|
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
200
230
|
results,
|
|
201
231
|
anchorResults,
|
|
202
|
-
|
|
232
|
+
maintenanceResults,
|
|
233
|
+
summary: summarize(results, anchorResults, maintenanceResults, this.targets.length)
|
|
203
234
|
}
|
|
204
235
|
|
|
205
236
|
await this.onReport?.(report)
|
|
@@ -377,6 +408,117 @@ export class OverlayMonitor {
|
|
|
377
408
|
clearTimeout(timeout)
|
|
378
409
|
}
|
|
379
410
|
}
|
|
411
|
+
|
|
412
|
+
private async runMaintenance(target: OverlayMonitorTarget): Promise<OverlayMaintenanceResult[]> {
|
|
413
|
+
const maintenance = target.maintenance
|
|
414
|
+
if (maintenance === undefined) return []
|
|
415
|
+
|
|
416
|
+
const results: OverlayMaintenanceResult[] = []
|
|
417
|
+
if (maintenance.startBASMSync === true) {
|
|
418
|
+
results.push(await this.runMaintenanceRequest(target, maintenance, 'start-basm-sync', '/admin/startBASMSync', {}))
|
|
419
|
+
}
|
|
420
|
+
if (maintenance.maintainUnproven !== undefined && maintenance.maintainUnproven !== false) {
|
|
421
|
+
const config = maintenance.maintainUnproven === true ? {} : maintenance.maintainUnproven
|
|
422
|
+
const topics = config.topics !== undefined && config.topics.length > 0 ? config.topics : [undefined]
|
|
423
|
+
for (const topic of topics) {
|
|
424
|
+
results.push(await this.runMaintenanceRequest(
|
|
425
|
+
target,
|
|
426
|
+
maintenance,
|
|
427
|
+
'maintain-unproven',
|
|
428
|
+
'/admin/maintainUnproven',
|
|
429
|
+
{
|
|
430
|
+
topic,
|
|
431
|
+
thresholdBlocks: config.thresholdBlocks
|
|
432
|
+
}
|
|
433
|
+
))
|
|
434
|
+
}
|
|
435
|
+
}
|
|
436
|
+
if (maintenance.janitor === true) {
|
|
437
|
+
results.push(await this.runMaintenanceRequest(target, maintenance, 'janitor', '/admin/janitor', {}))
|
|
438
|
+
}
|
|
439
|
+
return results
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
private async runMaintenanceRequest(
|
|
443
|
+
target: OverlayMonitorTarget,
|
|
444
|
+
maintenance: OverlayMaintenanceConfig,
|
|
445
|
+
operation: OverlayMaintenanceResult['operation'],
|
|
446
|
+
path: string,
|
|
447
|
+
body: { topic?: string, thresholdBlocks?: number }
|
|
448
|
+
): Promise<OverlayMaintenanceResult> {
|
|
449
|
+
const startedAt = this.now()
|
|
450
|
+
const url = new URL(path, target.baseUrl).toString()
|
|
451
|
+
const controller = new AbortController()
|
|
452
|
+
const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
|
|
453
|
+
|
|
454
|
+
try {
|
|
455
|
+
const headers: Record<string, string> = {
|
|
456
|
+
Accept: 'application/json',
|
|
457
|
+
'Content-Type': 'application/json',
|
|
458
|
+
...target.headers,
|
|
459
|
+
...maintenance.headers
|
|
460
|
+
}
|
|
461
|
+
if (maintenance.adminToken !== undefined && maintenance.adminToken !== '') {
|
|
462
|
+
headers.Authorization = `Bearer ${maintenance.adminToken}`
|
|
463
|
+
}
|
|
464
|
+
const response = await this.fetchImpl(url, {
|
|
465
|
+
method: 'POST',
|
|
466
|
+
headers,
|
|
467
|
+
body: JSON.stringify(stripUndefined(body)),
|
|
468
|
+
signal: controller.signal
|
|
469
|
+
})
|
|
470
|
+
const text = await response.text()
|
|
471
|
+
const responseBytes = new TextEncoder().encode(text).length
|
|
472
|
+
const completedAt = this.now()
|
|
473
|
+
let parsed: unknown
|
|
474
|
+
try {
|
|
475
|
+
parsed = text.length === 0 ? {} : JSON.parse(text)
|
|
476
|
+
} catch (error) {
|
|
477
|
+
return {
|
|
478
|
+
target: target.name,
|
|
479
|
+
url,
|
|
480
|
+
operation,
|
|
481
|
+
topic: body.topic,
|
|
482
|
+
status: response.status,
|
|
483
|
+
ok: false,
|
|
484
|
+
responseBytes,
|
|
485
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
486
|
+
error: error instanceof Error ? error.message : 'Invalid JSON response'
|
|
487
|
+
}
|
|
488
|
+
}
|
|
489
|
+
return {
|
|
490
|
+
target: target.name,
|
|
491
|
+
url,
|
|
492
|
+
operation,
|
|
493
|
+
topic: body.topic,
|
|
494
|
+
status: response.status,
|
|
495
|
+
ok: response.ok,
|
|
496
|
+
responseBytes,
|
|
497
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
498
|
+
data: parsed,
|
|
499
|
+
error: response.ok ? undefined : readErrorMessage(parsed)
|
|
500
|
+
}
|
|
501
|
+
} catch (error) {
|
|
502
|
+
const completedAt = this.now()
|
|
503
|
+
const fallbackMessage = error instanceof Error ? error.message : 'Maintenance request failed'
|
|
504
|
+
const message = controller.signal.aborted
|
|
505
|
+
? `Maintenance request timed out after ${this.timeoutMs}ms`
|
|
506
|
+
: fallbackMessage
|
|
507
|
+
return {
|
|
508
|
+
target: target.name,
|
|
509
|
+
url,
|
|
510
|
+
operation,
|
|
511
|
+
topic: body.topic,
|
|
512
|
+
status: 0,
|
|
513
|
+
ok: false,
|
|
514
|
+
responseBytes: 0,
|
|
515
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
516
|
+
error: message
|
|
517
|
+
}
|
|
518
|
+
} finally {
|
|
519
|
+
clearTimeout(timeout)
|
|
520
|
+
}
|
|
521
|
+
}
|
|
380
522
|
}
|
|
381
523
|
|
|
382
524
|
export function analyzeOverlayAnchorTip(options: {
|
|
@@ -540,15 +682,23 @@ function makeFailedAnchorResult(options: {
|
|
|
540
682
|
}
|
|
541
683
|
}
|
|
542
684
|
|
|
543
|
-
function summarize (
|
|
685
|
+
function summarize (
|
|
686
|
+
results: OverlayLookupProbeResult[],
|
|
687
|
+
anchorResults: OverlayAnchorProbeResult[],
|
|
688
|
+
maintenanceResults: OverlayMaintenanceResult[],
|
|
689
|
+
targetCount: number
|
|
690
|
+
): OverlayMonitorReport['summary'] {
|
|
544
691
|
return {
|
|
545
692
|
targetCount,
|
|
546
693
|
probeCount: results.length,
|
|
547
694
|
anchorProbeCount: anchorResults.length,
|
|
695
|
+
maintenanceActionCount: maintenanceResults.length,
|
|
548
696
|
failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length +
|
|
549
697
|
anchorResults.filter(result => !result.ok || result.error !== undefined).length,
|
|
698
|
+
failedMaintenanceActionCount: maintenanceResults.filter(result => !result.ok || result.error !== undefined).length,
|
|
550
699
|
responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0) +
|
|
551
|
-
anchorResults.reduce((sum, result) => sum + result.responseBytes, 0)
|
|
700
|
+
anchorResults.reduce((sum, result) => sum + result.responseBytes, 0) +
|
|
701
|
+
maintenanceResults.reduce((sum, result) => sum + result.responseBytes, 0),
|
|
552
702
|
outputCount: results.reduce((sum, result) => sum + result.outputCount, 0),
|
|
553
703
|
analyzedOutputCount: results.reduce((sum, result) => sum + result.analyzedOutputCount, 0),
|
|
554
704
|
outputsMissingSubjectProof: results.reduce((sum, result) => {
|
|
@@ -559,6 +709,16 @@ function summarize (results: OverlayLookupProbeResult[], anchorResults: OverlayA
|
|
|
559
709
|
}
|
|
560
710
|
}
|
|
561
711
|
|
|
712
|
+
function stripUndefined<T extends Record<string, unknown>>(value: T): Record<string, unknown> {
|
|
713
|
+
return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined))
|
|
714
|
+
}
|
|
715
|
+
|
|
716
|
+
function readErrorMessage(body: unknown): string | undefined {
|
|
717
|
+
if (typeof body !== 'object' || body === null) return undefined
|
|
718
|
+
const message = (body as { message?: unknown }).message
|
|
719
|
+
return typeof message === 'string' ? message : undefined
|
|
720
|
+
}
|
|
721
|
+
|
|
562
722
|
function extractOutputs (body: unknown): Array<Record<string, unknown>> {
|
|
563
723
|
if (typeof body !== 'object' || body === null || !('outputs' in body)) return []
|
|
564
724
|
const outputs = (body as { outputs?: unknown }).outputs
|