@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.
Files changed (52) hide show
  1. package/README.md +122 -3
  2. package/dist/cjs/mod.js +8 -1
  3. package/dist/cjs/mod.js.map +1 -1
  4. package/dist/cjs/package.json +9 -9
  5. package/dist/cjs/src/ArcadeProvider.js +196 -0
  6. package/dist/cjs/src/ArcadeProvider.js.map +1 -0
  7. package/dist/cjs/src/ChaintracksProvider.js +65 -0
  8. package/dist/cjs/src/ChaintracksProvider.js.map +1 -0
  9. package/dist/cjs/src/OverlayExpress.js +235 -11
  10. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  11. package/dist/cjs/src/OverlayMonitor.js +117 -3
  12. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  13. package/dist/cjs/src/ProviderChainBroadcaster.js +91 -0
  14. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -0
  15. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  16. package/dist/esm/mod.js +3 -0
  17. package/dist/esm/mod.js.map +1 -1
  18. package/dist/esm/src/ArcadeProvider.js +189 -0
  19. package/dist/esm/src/ArcadeProvider.js.map +1 -0
  20. package/dist/esm/src/ChaintracksProvider.js +62 -0
  21. package/dist/esm/src/ChaintracksProvider.js.map +1 -0
  22. package/dist/esm/src/OverlayExpress.js +231 -11
  23. package/dist/esm/src/OverlayExpress.js.map +1 -1
  24. package/dist/esm/src/OverlayMonitor.js +117 -3
  25. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  26. package/dist/esm/src/ProviderChainBroadcaster.js +88 -0
  27. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -0
  28. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  29. package/dist/types/mod.d.ts +3 -0
  30. package/dist/types/mod.d.ts.map +1 -1
  31. package/dist/types/src/ArcadeProvider.d.ts +37 -0
  32. package/dist/types/src/ArcadeProvider.d.ts.map +1 -0
  33. package/dist/types/src/ChaintracksProvider.d.ts +29 -0
  34. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -0
  35. package/dist/types/src/OverlayExpress.d.ts +38 -1
  36. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  37. package/dist/types/src/OverlayMonitor.d.ts +28 -0
  38. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  39. package/dist/types/src/ProviderChainBroadcaster.d.ts +18 -0
  40. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -0
  41. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  42. package/mod.ts +15 -0
  43. package/package.json +9 -9
  44. package/src/ArcadeProvider.ts +232 -0
  45. package/src/ChaintracksProvider.ts +79 -0
  46. package/src/OverlayExpress.ts +259 -11
  47. package/src/OverlayMonitor.ts +163 -3
  48. package/src/ProviderChainBroadcaster.ts +108 -0
  49. package/src/__tests__/OverlayExpress.test.ts +37 -3
  50. package/src/__tests__/OverlayMonitor.test.ts +74 -0
  51. package/src/__tests__/OverlayProviders.live.test.ts +39 -0
  52. package/src/__tests__/OverlayProviders.test.ts +123 -0
package/dist/esm/mod.js CHANGED
@@ -5,4 +5,7 @@ export { BanAwareTopicManager } from './src/BanAwareTopicManager.js';
5
5
  export { BanAwareSHIPStorage, BanAwareSLAPStorage } from './src/BanAwareDiscoveryStorage.js';
6
6
  export { JanitorService } from './src/JanitorService.js';
7
7
  export { OverlayMonitor, analyzeOverlayAnchorTip, analyzeOverlayLookupResponse } from './src/OverlayMonitor.js';
8
+ export { ArcadeProvider, isTerminalArcStatus } from './src/ArcadeProvider.js';
9
+ export { ProviderChainBroadcaster } from './src/ProviderChainBroadcaster.js';
10
+ export { ChaintracksProvider } from './src/ChaintracksProvider.js';
8
11
  //# sourceMappingURL=mod.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"mod.js","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EASR,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,UAAU,EAAqB,MAAM,qBAAqB,CAAA;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAC5F,OAAO,EAAE,cAAc,EAAiE,MAAM,yBAAyB,CAAA;AACvH,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,4BAA4B,EAY7B,MAAM,yBAAyB,CAAA"}
1
+ {"version":3,"file":"mod.js","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EASR,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,UAAU,EAAqB,MAAM,qBAAqB,CAAA;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAC5F,OAAO,EAAE,cAAc,EAAiE,MAAM,yBAAyB,CAAA;AACvH,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,4BAA4B,EAY7B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,cAAc,EACd,mBAAmB,EAGpB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,wBAAwB,EAEzB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,mBAAmB,EAGpB,MAAM,8BAA8B,CAAA"}
@@ -0,0 +1,189 @@
1
+ import { MerklePath } from '@bsv/sdk';
2
+ const TERMINAL_STATUSES = new Set([
3
+ 'DOUBLE_SPEND_ATTEMPTED',
4
+ 'REJECTED',
5
+ 'INVALID',
6
+ 'MALFORMED',
7
+ 'MINED_IN_STALE_BLOCK'
8
+ ]);
9
+ const SUCCESS_STATUSES = new Set([
10
+ 'RECEIVED',
11
+ 'SENT_TO_NETWORK',
12
+ 'ANNOUNCED_TO_NETWORK',
13
+ 'ACCEPTED_BY_NETWORK',
14
+ 'SEEN_ON_NETWORK',
15
+ 'STORED',
16
+ 'MINED',
17
+ 'IMMUTABLE'
18
+ ]);
19
+ export function isTerminalArcStatus(status, extraInfo) {
20
+ const statusText = typeof status === 'string' ? status.toUpperCase() : '';
21
+ const extraText = typeof extraInfo === 'string' ? extraInfo.toUpperCase() : '';
22
+ return TERMINAL_STATUSES.has(statusText) || statusText.includes('ORPHAN') || extraText.includes('ORPHAN');
23
+ }
24
+ function trimBaseUrl(url) {
25
+ let base = url;
26
+ while (base.endsWith('/'))
27
+ base = base.slice(0, -1);
28
+ return base;
29
+ }
30
+ function parseDescription(data, fallback) {
31
+ if (typeof data === 'string')
32
+ return data;
33
+ if (typeof data === 'object' && data !== null) {
34
+ const d = data;
35
+ return d.detail ?? d.reason ?? d.error ?? `${d.txStatus ?? ''} ${d.extraInfo ?? ''}`.trim() ?? fallback;
36
+ }
37
+ return fallback;
38
+ }
39
+ function rawTxForArcade(tx) {
40
+ try {
41
+ return tx.toHexEF();
42
+ }
43
+ catch (error) {
44
+ if (error instanceof Error &&
45
+ error.message === 'All inputs must have source transactions when serializing to EF format') {
46
+ return tx.toHex();
47
+ }
48
+ throw error;
49
+ }
50
+ }
51
+ /**
52
+ * Broadcaster/proof client for bsv-blockchain/arcade.
53
+ *
54
+ * Arcade exposes transaction propagation at `/tx` and status/proofs at
55
+ * `/tx/{txid}`. It returns terminal validation and double-spend statuses in the
56
+ * body, so callers must classify those as failed broadcasts even when HTTP
57
+ * accepted the request.
58
+ */
59
+ export class ArcadeProvider {
60
+ config;
61
+ name = 'Arcade';
62
+ baseUrl;
63
+ fetcher;
64
+ constructor(url, config = {}) {
65
+ this.config = config;
66
+ this.baseUrl = trimBaseUrl(url);
67
+ this.fetcher = config.fetch ?? fetch;
68
+ }
69
+ async broadcast(tx) {
70
+ const rawTx = rawTxForArcade(tx);
71
+ try {
72
+ const response = await this.fetcher(`${this.baseUrl}/tx`, {
73
+ method: 'POST',
74
+ headers: this.requestHeaders(),
75
+ body: JSON.stringify({ rawTx })
76
+ });
77
+ const data = await this.readResponse(response);
78
+ if (!response.ok) {
79
+ const failure = {
80
+ status: 'error',
81
+ code: data?.txStatus ?? String(response.status),
82
+ txid: data?.txid,
83
+ description: parseDescription(data, response.statusText)
84
+ };
85
+ const more = {
86
+ provider: this.name,
87
+ httpStatus: response.status,
88
+ terminal: response.status === 400 || isTerminalArcStatus(data?.txStatus, data?.extraInfo),
89
+ response: data
90
+ };
91
+ if (data?.competingTxs !== undefined) {
92
+ more.competingTxs = data.competingTxs;
93
+ }
94
+ failure.more = more;
95
+ return failure;
96
+ }
97
+ const txStatus = data?.txStatus;
98
+ if (isTerminalArcStatus(txStatus, data?.extraInfo)) {
99
+ const failure = {
100
+ status: 'error',
101
+ code: txStatus ?? 'UNKNOWN',
102
+ txid: data?.txid,
103
+ description: `${txStatus ?? ''} ${data?.extraInfo ?? ''}`.trim()
104
+ };
105
+ const more = { provider: this.name, terminal: true, response: data };
106
+ if (data?.competingTxs !== undefined) {
107
+ more.competingTxs = data.competingTxs;
108
+ }
109
+ failure.more = more;
110
+ return failure;
111
+ }
112
+ const statusText = typeof txStatus === 'string' ? txStatus.toUpperCase() : undefined;
113
+ return {
114
+ status: 'success',
115
+ txid: data?.txid ?? tx.id('hex'),
116
+ message: `${txStatus ?? (SUCCESS_STATUSES.has(statusText ?? '') ? statusText ?? '' : response.statusText)} ${data?.extraInfo ?? ''}`.trim(),
117
+ competingTxs: data?.competingTxs
118
+ };
119
+ }
120
+ catch (error) {
121
+ return {
122
+ status: 'error',
123
+ code: '500',
124
+ description: error instanceof Error ? error.message : 'Internal Server Error',
125
+ more: { provider: this.name, terminal: false }
126
+ };
127
+ }
128
+ }
129
+ async fetchMerkleProof(txid) {
130
+ const response = await this.fetcher(`${this.baseUrl}/tx/${txid}`, {
131
+ method: 'GET',
132
+ headers: this.requestHeaders({ accept: 'application/json' })
133
+ });
134
+ if (response.status === 404)
135
+ return undefined;
136
+ const data = await this.readResponse(response);
137
+ if (!response.ok) {
138
+ throw new Error(`Arcade proof lookup failed for ${txid}: ${response.status} ${parseDescription(data, response.statusText)}`);
139
+ }
140
+ const mined = data?.txStatus === 'MINED' || data?.txStatus === 'IMMUTABLE';
141
+ if (!mined || data?.merklePath === undefined || data.merklePath === '') {
142
+ return undefined;
143
+ }
144
+ const merklePath = MerklePath.fromHex(data.merklePath);
145
+ return {
146
+ txid,
147
+ merklePath,
148
+ blockHeight: data.blockHeight ?? merklePath.blockHeight,
149
+ blockHash: data.blockHash,
150
+ merkleRoot: merklePath.computeRoot(txid)
151
+ };
152
+ }
153
+ requestHeaders(options = {}) {
154
+ const headers = {
155
+ Accept: options.accept ?? 'application/json',
156
+ 'Content-Type': 'application/json'
157
+ };
158
+ if (this.config.deploymentId !== undefined && this.config.deploymentId !== '') {
159
+ headers['XDeployment-ID'] = this.config.deploymentId;
160
+ }
161
+ if (this.config.apiKey !== undefined && this.config.apiKey !== '') {
162
+ headers.Authorization = `Bearer ${this.config.apiKey}`;
163
+ }
164
+ if (this.config.callbackUrl !== undefined && this.config.callbackUrl !== '') {
165
+ headers['X-CallbackUrl'] = this.config.callbackUrl;
166
+ }
167
+ if (this.config.callbackToken !== undefined && this.config.callbackToken !== '') {
168
+ headers['X-CallbackToken'] = this.config.callbackToken;
169
+ }
170
+ if (this.config.headers !== undefined) {
171
+ for (const [key, value] of Object.entries(this.config.headers)) {
172
+ headers[key] = value;
173
+ }
174
+ }
175
+ return headers;
176
+ }
177
+ async readResponse(response) {
178
+ const text = await response.text();
179
+ if (text === '')
180
+ return undefined;
181
+ try {
182
+ return JSON.parse(text);
183
+ }
184
+ catch {
185
+ return text;
186
+ }
187
+ }
188
+ }
189
+ //# sourceMappingURL=ArcadeProvider.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ArcadeProvider.js","sourceRoot":"","sources":["../../../src/ArcadeProvider.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,62 @@
1
+ function trimUrl(url) {
2
+ let trimmed = url;
3
+ while (trimmed.endsWith('/'))
4
+ trimmed = trimmed.slice(0, -1);
5
+ return trimmed;
6
+ }
7
+ function trimPrefix(prefix) {
8
+ if (prefix === '')
9
+ return '';
10
+ let trimmed = prefix.startsWith('/') ? prefix : `/${prefix}`;
11
+ while (trimmed.endsWith('/'))
12
+ trimmed = trimmed.slice(0, -1);
13
+ return trimmed;
14
+ }
15
+ /**
16
+ * Minimal go-chaintracks HTTP client for Overlay Express.
17
+ *
18
+ * It intentionally implements the SDK ChainTracker surface plus header lookup,
19
+ * which is enough for proof validation, BASM headers, and reorg stream URL
20
+ * construction without depending on wallet-toolbox client export timing.
21
+ */
22
+ export class ChaintracksProvider {
23
+ baseUrl;
24
+ fetcher;
25
+ constructor(url, config = {}) {
26
+ this.baseUrl = `${trimUrl(url)}${trimPrefix(config.apiPrefix ?? '/chaintracks/v2')}`;
27
+ this.fetcher = config.fetch ?? fetch;
28
+ }
29
+ async currentHeight() {
30
+ const response = await this.getJson('/height');
31
+ return response.height;
32
+ }
33
+ async isValidRootForHeight(root, height) {
34
+ const header = await this.findHeaderForHeight(height);
35
+ return header !== undefined && header.merkleRoot === root;
36
+ }
37
+ async findHeaderForHeight(height) {
38
+ return await this.getJsonOrUndefined(`/header/height/${height}`);
39
+ }
40
+ reorgStreamUrl() {
41
+ return `${this.baseUrl}/reorg/stream`;
42
+ }
43
+ async getJson(path) {
44
+ const value = await this.getJsonOrUndefined(path);
45
+ if (value === undefined) {
46
+ throw new Error(`Chaintracks returned no value for ${path}`);
47
+ }
48
+ return value;
49
+ }
50
+ async getJsonOrUndefined(path) {
51
+ const response = await this.fetcher(`${this.baseUrl}${path}`, {
52
+ headers: { Accept: 'application/json' }
53
+ });
54
+ if (response.status === 404)
55
+ return undefined;
56
+ if (!response.ok) {
57
+ throw new Error(`Chaintracks request failed for ${path}: ${response.status} ${response.statusText}`);
58
+ }
59
+ return await response.json();
60
+ }
61
+ }
62
+ //# sourceMappingURL=ChaintracksProvider.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ChaintracksProvider.js","sourceRoot":"","sources":["../../../src/ChaintracksProvider.ts"],"names":[],"mappings":"AAaA,SAAS,OAAO,CAAE,GAAW;IAC3B,IAAI,OAAO,GAAG,GAAG,CAAA;IACjB,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC5D,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,SAAS,UAAU,CAAE,MAAc;IACjC,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,EAAE,CAAA;IAC5B,IAAI,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAA;IAC5D,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC5D,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IACb,OAAO,CAAQ;IACf,OAAO,CAAc;IAEtC,YAAa,GAAW,EAAE,SAAoC,EAAE;QAC9D,IAAI,CAAC,OAAO,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,SAAS,IAAI,iBAAiB,CAAC,EAAE,CAAA;QACpF,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAqB,SAAS,CAAC,CAAA;QAClE,OAAO,QAAQ,CAAC,MAAM,CAAA;IACxB,CAAC;IAED,KAAK,CAAC,oBAAoB,CAAE,IAAY,EAAE,MAAc;QACtD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QACrD,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,CAAA;IAC3D,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAE,MAAc;QACvC,OAAO,MAAM,IAAI,CAAC,kBAAkB,CAAoB,kBAAkB,MAAM,EAAE,CAAC,CAAA;IACrF,CAAC;IAED,cAAc;QACZ,OAAO,GAAG,IAAI,CAAC,OAAO,eAAe,CAAA;IACvC,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,IAAY;QACnC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAI,IAAI,CAAC,CAAA;QACpD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,EAAE,CAAC,CAAA;QAC9D,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAEO,KAAK,CAAC,kBAAkB,CAAI,IAAY;QAC9C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YAC5D,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAA;QACF,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAS,CAAA;QAC7C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,KAAK,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;QACtG,CAAC;QACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAO,CAAA;IACnC,CAAC;CACF"}
@@ -17,6 +17,9 @@ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from './BanAwareDiscoverySto
17
17
  import { ReorgSseAdapter } from './ReorgStream.js';
18
18
  import { Wallet, WalletSigner, WalletStorageManager, Services } from '@bsv/wallet-toolbox-client';
19
19
  import { createAuthMiddleware } from '@bsv/auth-express-middleware';
20
+ import { ArcadeProvider, isTerminalArcStatus } from './ArcadeProvider.js';
21
+ import { ProviderChainBroadcaster } from './ProviderChainBroadcaster.js';
22
+ import { ChaintracksProvider } from './ChaintracksProvider.js';
20
23
  /**
21
24
  * In-memory migration source for Knex migrations.
22
25
  * Allows running migrations defined in code rather than files.
@@ -99,6 +102,10 @@ export default class OverlayExpress {
99
102
  basmBlockPollIntervalMs = 10 * 60 * 1000;
100
103
  // Handle for the BASM block-poll timer so it can be stopped.
101
104
  basmBlockPollTimer;
105
+ // How often (ms) to refresh proofs for old unproven rows and then evict rows
106
+ // that still have no proof. Set to 0 to disable background maintenance.
107
+ unprovenMaintenanceIntervalMs = 0;
108
+ unprovenMaintenanceTimer;
102
109
  // Optional go-chaintracks (Arcade) reorg SSE URL (e.g. `<base>/v2/reorg/stream`).
103
110
  // When set, reorgs are reconciled in real time; the block poll also runs a
104
111
  // revalidation sweep as a fallback / reconnect catch-up.
@@ -113,6 +120,13 @@ export default class OverlayExpress {
113
120
  arcApiKey = undefined;
114
121
  // Optional ARC callback token for /arc-ingest notifications
115
122
  arcCallbackToken = undefined;
123
+ // Optional Arcade URL/API key used for propagation, proof refresh, and
124
+ // go-chaintracks header/reorg access when available.
125
+ arcadeUrl = undefined;
126
+ arcadeApiKey = undefined;
127
+ arcadeDeploymentId = undefined;
128
+ arcadeChaintracksApiPrefix = '/chaintracks/v2';
129
+ arcadeProvider;
116
130
  // Verbose request logging
117
131
  verboseRequestLogging = false;
118
132
  // Web UI configuration
@@ -274,6 +288,41 @@ export default class OverlayExpress {
274
288
  this.arcCallbackToken = token;
275
289
  this.logger.log(chalk.blue('ARC callback token has been configured.'));
276
290
  }
291
+ /**
292
+ * Configures Arcade for first-choice transaction propagation and proof lookup.
293
+ */
294
+ configureArcade(url, config = {}) {
295
+ this.arcadeUrl = url;
296
+ this.arcadeApiKey = config.apiKey;
297
+ this.arcadeDeploymentId = config.deploymentId;
298
+ if (config.chaintracksApiPrefix !== undefined) {
299
+ this.arcadeChaintracksApiPrefix = config.chaintracksApiPrefix;
300
+ }
301
+ this.logger.log(chalk.blue('Arcade provider has been configured.'));
302
+ }
303
+ /**
304
+ * Configures a go-chaintracks compatible service for header validation and
305
+ * BASM reorg streaming. Arcade exposes this at `/chaintracks/v2`.
306
+ */
307
+ configureChaintracks(url, config = {}) {
308
+ const apiPrefix = config.apiPrefix ?? '/chaintracks/v2';
309
+ const client = new ChaintracksProvider(url, { apiPrefix });
310
+ this.configureChainTracker(client);
311
+ this.configureTopicAnchorHeaderResolver(async (blockHeight) => {
312
+ const header = await client.findHeaderForHeight(blockHeight);
313
+ if (header === undefined)
314
+ return undefined;
315
+ return {
316
+ blockHeight,
317
+ blockHash: header.hash,
318
+ merkleRoot: header.merkleRoot
319
+ };
320
+ });
321
+ if (config.reorgStream !== false) {
322
+ this.configureReorgStream(client.reorgStreamUrl(), config.scanDepth);
323
+ }
324
+ this.logger.log(chalk.blue('go-chaintracks provider has been configured.'));
325
+ }
277
326
  /**
278
327
  * Enables or disables GASP synchronization (high-level setting).
279
328
  * This is a broad toggle that can be overridden or customized through syncConfiguration.
@@ -320,6 +369,19 @@ export default class OverlayExpress {
320
369
  }
321
370
  this.logger.log(chalk.blue('Unproven transaction eviction has been configured.'));
322
371
  }
372
+ /**
373
+ * Configures periodic unproven maintenance. Each run first tries configured
374
+ * proof providers, then evicts rows that are still unproven past the threshold.
375
+ */
376
+ configureUnprovenMaintenance(config) {
377
+ if (config.intervalMs !== undefined) {
378
+ this.unprovenMaintenanceIntervalMs = config.intervalMs;
379
+ }
380
+ if (config.thresholdBlocks !== undefined) {
381
+ this.unprovenEvictionBlocks = config.thresholdBlocks;
382
+ }
383
+ this.logger.log(chalk.blue('Unproven transaction maintenance has been configured.'));
384
+ }
323
385
  /**
324
386
  * Configures how often the BASM anchor chain is extended with empty anchors to
325
387
  * follow the chain tip. Set to 0 to disable periodic polling.
@@ -467,7 +529,7 @@ export default class OverlayExpress {
467
529
  const EngineWithBASM = Engine;
468
530
  this.engine = new EngineWithBASM(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
469
531
  ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
470
- : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? false, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks);
532
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? true, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true, this.buildTopicAnchorHeaderResolver(), this.engineConfig.enableBASMSync ?? this.enableBASMSync, this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks);
471
533
  this.initServerWallet();
472
534
  this.logger.log(chalk.green('Engine has been configured.'));
473
535
  }
@@ -501,16 +563,87 @@ export default class OverlayExpress {
501
563
  }
502
564
  return syncConfig;
503
565
  }
504
- /** Build the ARC broadcaster if an API key is configured. */
566
+ /** Build the configured transaction propagation provider chain. */
505
567
  buildBroadcaster() {
506
- if (typeof this.arcApiKey !== 'string')
568
+ const providers = [];
569
+ const callbackUrl = `https://${this.advertisableFQDN}/arc-ingest`;
570
+ if (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0) {
571
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
572
+ apiKey: this.arcadeApiKey,
573
+ callbackUrl,
574
+ callbackToken: this.arcCallbackToken,
575
+ deploymentId: this.arcadeDeploymentId
576
+ });
577
+ providers.push({
578
+ name: 'Arcade',
579
+ broadcaster: this.arcadeProvider
580
+ });
581
+ }
582
+ else {
583
+ this.arcadeProvider = undefined;
584
+ }
585
+ if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
586
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
587
+ providers.push({
588
+ name: 'ARC',
589
+ broadcaster: new ARC(arcUrl, {
590
+ apiKey: this.arcApiKey,
591
+ callbackUrl,
592
+ callbackToken: this.arcCallbackToken
593
+ })
594
+ });
595
+ }
596
+ if (providers.length === 0)
507
597
  return undefined;
508
- const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
509
- return new ARC(arcUrl, {
510
- apiKey: this.arcApiKey,
598
+ if (providers.length === 1)
599
+ return providers[0].broadcaster;
600
+ return new ProviderChainBroadcaster(providers);
601
+ }
602
+ ensureArcadeProvider() {
603
+ if (this.arcadeProvider !== undefined)
604
+ return this.arcadeProvider;
605
+ if (typeof this.arcadeUrl !== 'string' || this.arcadeUrl.length === 0)
606
+ return undefined;
607
+ this.arcadeProvider = new ArcadeProvider(this.arcadeUrl, {
608
+ apiKey: this.arcadeApiKey,
511
609
  callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
512
- callbackToken: this.arcCallbackToken
610
+ callbackToken: this.arcCallbackToken,
611
+ deploymentId: this.arcadeDeploymentId
513
612
  });
613
+ return this.arcadeProvider;
614
+ }
615
+ async fetchArcadeProof(txid) {
616
+ const provider = this.ensureArcadeProvider();
617
+ if (provider === undefined)
618
+ return undefined;
619
+ const proof = await provider.fetchMerkleProof(txid);
620
+ if (proof === undefined)
621
+ return undefined;
622
+ const chainTracker = this.engineConfig.chainTracker ?? this.chainTracker;
623
+ if (chainTracker === 'scripts only') {
624
+ throw new Error('Cannot validate Arcade proof with scripts-only chain tracker');
625
+ }
626
+ const blockHeight = proof.blockHeight ?? proof.merklePath.blockHeight;
627
+ if (blockHeight === undefined) {
628
+ throw new Error(`Arcade proof for ${txid} did not include a block height`);
629
+ }
630
+ const valid = await chainTracker.isValidRootForHeight(proof.merkleRoot, blockHeight);
631
+ if (!valid) {
632
+ throw new Error(`Arcade proof for ${txid} did not match the chain tracker at height ${blockHeight}`);
633
+ }
634
+ return {
635
+ ...proof,
636
+ blockHeight
637
+ };
638
+ }
639
+ async fetchConfiguredMerkleProof(txid) {
640
+ const proof = await this.fetchArcadeProof(txid);
641
+ if (proof === undefined)
642
+ return undefined;
643
+ return {
644
+ merklePath: proof.merklePath,
645
+ blockHeight: proof.blockHeight
646
+ };
514
647
  }
515
648
  /** Build the BASM block header resolver. */
516
649
  buildTopicAnchorHeaderResolver() {
@@ -1149,8 +1282,9 @@ export default class OverlayExpress {
1149
1282
  });
1150
1283
  });
1151
1284
  });
1152
- // ARC ingest route (only if we have an ARC API key)
1153
- if (typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) {
1285
+ // ARC/Arcade ingest route (only if a provider is configured)
1286
+ if ((typeof this.arcApiKey === 'string' && this.arcApiKey.length > 0) ||
1287
+ (typeof this.arcadeUrl === 'string' && this.arcadeUrl.length > 0)) {
1154
1288
  this.app.post('/arc-ingest', (req, res) => {
1155
1289
  ;
1156
1290
  (async () => {
@@ -1167,9 +1301,44 @@ export default class OverlayExpress {
1167
1301
  return res.status(401).json({ status: 'error', message: 'Unauthorized callback' });
1168
1302
  }
1169
1303
  }
1170
- const { txid, merklePath: merklePathHex, blockHeight } = req.body;
1304
+ const { txid, merklePath: merklePathHex, blockHeight, txStatus, extraInfo, competingTxs, topic } = req.body;
1305
+ if (typeof txid !== 'string' || txid === '') {
1306
+ throw new TypeError('Provider callback is missing txid');
1307
+ }
1308
+ if (isTerminalArcStatus(txStatus, extraInfo)) {
1309
+ const report = await engine.evictAppliedTransaction(txid, {
1310
+ topic: typeof topic === 'string' ? topic : undefined,
1311
+ reason: `${txStatus ?? ''} ${extraInfo ?? ''}`.trim()
1312
+ });
1313
+ this.logger.warn({
1314
+ operation: 'overlay.provider_callback',
1315
+ outcome: 'terminal_evicted',
1316
+ txid,
1317
+ txStatus,
1318
+ competingTxs,
1319
+ report
1320
+ });
1321
+ return res.status(200).json({
1322
+ status: 'success',
1323
+ message: 'Terminal transaction status processed',
1324
+ data: {
1325
+ ...report,
1326
+ txStatus,
1327
+ competingTxs
1328
+ }
1329
+ });
1330
+ }
1331
+ if (typeof merklePathHex !== 'string' || merklePathHex === '') {
1332
+ return res.status(202).json({ status: 'success', message: 'Transaction status received without proof' });
1333
+ }
1171
1334
  const merklePath = MerklePath.fromHex(merklePathHex);
1172
1335
  await engine.handleNewMerkleProof(txid, merklePath, blockHeight);
1336
+ this.logger.log({
1337
+ operation: 'overlay.provider_callback',
1338
+ outcome: 'proof_ingested',
1339
+ txid,
1340
+ blockHeight
1341
+ });
1173
1342
  return res.status(200).json({ status: 'success', message: 'Transaction status updated' });
1174
1343
  }
1175
1344
  catch (error) {
@@ -1188,7 +1357,7 @@ export default class OverlayExpress {
1188
1357
  });
1189
1358
  }
1190
1359
  else {
1191
- this.logger.warn(chalk.yellow('Disabling ARC because no ARC API key was provided.'));
1360
+ this.logger.warn(chalk.yellow('Disabling ARC/Arcade ingest because no provider was configured.'));
1192
1361
  }
1193
1362
  // GASP sync routes if enabled
1194
1363
  if (this.enableGASPSync) {
@@ -1704,8 +1873,36 @@ export default class OverlayExpress {
1704
1873
  topic: typeof topic === 'string' ? topic : undefined,
1705
1874
  thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined
1706
1875
  });
1876
+ this.logger.log({ operation: 'overlay.unproven_eviction', outcome: 'ok', report });
1707
1877
  return { status: 'success', message: 'Unproven eviction completed', data: report };
1708
1878
  }, checkAdminAuth);
1879
+ /**
1880
+ * Admin route to refresh proofs for expired unproven topic transactions
1881
+ * using the configured proof providers.
1882
+ */
1883
+ registerJsonRoute('/admin/refreshUnprovenProofs', async (req) => {
1884
+ const { topic, thresholdBlocks } = req.body ?? {};
1885
+ const report = await basmEngine.refreshUnprovenTransactionProofs({
1886
+ topic: typeof topic === 'string' ? topic : undefined,
1887
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
1888
+ proofProvider: async (txid) => await this.fetchConfiguredMerkleProof(txid)
1889
+ });
1890
+ this.logger.log({ operation: 'overlay.unproven_proof_refresh', outcome: 'ok', report });
1891
+ return { status: 'success', message: 'Unproven proof refresh completed', data: report };
1892
+ }, checkAdminAuth);
1893
+ /**
1894
+ * Admin route to refresh proofs first, then evict rows that remain unproven.
1895
+ */
1896
+ registerJsonRoute('/admin/maintainUnproven', async (req) => {
1897
+ const { topic, thresholdBlocks } = req.body ?? {};
1898
+ const report = await basmEngine.maintainUnprovenTransactions({
1899
+ topic: typeof topic === 'string' ? topic : undefined,
1900
+ thresholdBlocks: typeof thresholdBlocks === 'number' ? thresholdBlocks : undefined,
1901
+ proofProvider: async (txid) => await this.fetchConfiguredMerkleProof(txid)
1902
+ });
1903
+ this.logger.log({ operation: 'overlay.unproven_maintenance', outcome: 'ok', report });
1904
+ return { status: 'success', message: 'Unproven maintenance completed', data: report };
1905
+ }, checkAdminAuth);
1709
1906
  /**
1710
1907
  * Admin route to evict an outpoint, either from all services or a specific one.
1711
1908
  */
@@ -1815,6 +2012,7 @@ export default class OverlayExpress {
1815
2012
  }
1816
2013
  await this.runGaspStartupSync();
1817
2014
  await this.runBasmStartupSync();
2015
+ this.startUnprovenMaintenance();
1818
2016
  }
1819
2017
  /** Attempt a GASP sync at startup when enabled. */
1820
2018
  async runGaspStartupSync() {
@@ -1899,5 +2097,27 @@ export default class OverlayExpress {
1899
2097
  console.error(chalk.red('Failed to revalidate BASM anchors'), e);
1900
2098
  }
1901
2099
  }
2100
+ startUnprovenMaintenance() {
2101
+ const intervalMs = this.engineConfig.unprovenMaintenanceIntervalMs ?? this.unprovenMaintenanceIntervalMs;
2102
+ if (intervalMs <= 0)
2103
+ return;
2104
+ const run = () => {
2105
+ void (async () => {
2106
+ try {
2107
+ const report = await this.engine?.maintainUnprovenTransactions({
2108
+ thresholdBlocks: this.engineConfig.unprovenEvictionBlocks ?? this.unprovenEvictionBlocks,
2109
+ proofProvider: async (txid) => await this.fetchConfiguredMerkleProof(txid)
2110
+ });
2111
+ this.logger.log(chalk.green('Unproven transaction maintenance complete'), report);
2112
+ }
2113
+ catch (e) {
2114
+ console.error(chalk.red('Failed to maintain unproven transactions'), e);
2115
+ }
2116
+ })();
2117
+ };
2118
+ run();
2119
+ this.unprovenMaintenanceTimer = setInterval(run, intervalMs);
2120
+ this.unprovenMaintenanceTimer.unref?.();
2121
+ }
1902
2122
  }
1903
2123
  //# sourceMappingURL=OverlayExpress.js.map