@bsv/overlay-express 2.3.1 → 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 +18 -10
  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 +18 -10
  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
@@ -0,0 +1,108 @@
1
+ import {
2
+ BroadcastFailure,
3
+ Broadcaster,
4
+ BroadcastResponse,
5
+ Transaction
6
+ } from '@bsv/sdk'
7
+
8
+ export interface NamedBroadcaster {
9
+ name: string
10
+ broadcaster: Broadcaster
11
+ }
12
+
13
+ const TERMINAL_CODES = new Set([
14
+ '400',
15
+ '460',
16
+ '463',
17
+ '464',
18
+ 'DOUBLE_SPEND_ATTEMPTED',
19
+ 'REJECTED',
20
+ 'INVALID',
21
+ 'MALFORMED',
22
+ 'MINED_IN_STALE_BLOCK'
23
+ ])
24
+
25
+ function isTerminalBroadcastFailure (failure: BroadcastFailure): boolean {
26
+ const code = failure.code.toUpperCase()
27
+ const description = failure.description.toUpperCase()
28
+ if (TERMINAL_CODES.has(code)) return true
29
+ if (code.includes('ORPHAN') || description.includes('ORPHAN')) return true
30
+ if (
31
+ typeof failure.more === 'object' &&
32
+ failure.more !== null &&
33
+ 'terminal' in failure.more &&
34
+ failure.more.terminal === true
35
+ ) {
36
+ return true
37
+ }
38
+ return false
39
+ }
40
+
41
+ /**
42
+ * Tries transaction propagation providers in priority order.
43
+ *
44
+ * Transient provider failures fall through to the next provider. Terminal
45
+ * validation states, including double spends, stop immediately so a conflicting
46
+ * transaction is not retried against a second propagation surface.
47
+ */
48
+ export class ProviderChainBroadcaster implements Broadcaster {
49
+ constructor (private readonly providers: NamedBroadcaster[]) {
50
+ if (providers.length === 0) {
51
+ throw new TypeError('ProviderChainBroadcaster requires at least one provider')
52
+ }
53
+ }
54
+
55
+ async broadcast (tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
56
+ const failures: Array<{ provider: string, failure: BroadcastFailure }> = []
57
+
58
+ for (const provider of this.providers) {
59
+ let response: BroadcastResponse | BroadcastFailure
60
+ try {
61
+ response = await provider.broadcaster.broadcast(tx)
62
+ } catch (error: unknown) {
63
+ response = {
64
+ status: 'error',
65
+ code: '500',
66
+ description: error instanceof Error ? error.message : 'Internal Server Error',
67
+ more: { provider: provider.name, terminal: false }
68
+ }
69
+ }
70
+
71
+ if (response.status === 'success') {
72
+ return {
73
+ ...response,
74
+ message: `[${provider.name}] ${response.message}`
75
+ }
76
+ }
77
+
78
+ failures.push({ provider: provider.name, failure: response })
79
+ if (isTerminalBroadcastFailure(response)) {
80
+ return annotateFailure(response, provider.name, failures)
81
+ }
82
+ }
83
+
84
+ const last = failures[failures.length - 1]
85
+ return annotateFailure(last.failure, last.provider, failures)
86
+ }
87
+ }
88
+
89
+ function annotateFailure (
90
+ failure: BroadcastFailure,
91
+ provider: string,
92
+ failures: Array<{ provider: string, failure: BroadcastFailure }>
93
+ ): BroadcastFailure {
94
+ return {
95
+ ...failure,
96
+ more: {
97
+ ...(typeof failure.more === 'object' && failure.more !== null ? failure.more : {}),
98
+ provider,
99
+ providerFailures: failures.map(item => ({
100
+ provider: item.provider,
101
+ code: item.failure.code,
102
+ description: item.failure.description,
103
+ txid: item.failure.txid,
104
+ more: item.failure.more
105
+ }))
106
+ }
107
+ }
108
+ }
@@ -672,6 +672,12 @@ describe('OverlayExpress', () => {
672
672
  syncAdvertisements: jest.fn().mockResolvedValue(undefined),
673
673
  // @ts-expect-error - Mock return values
674
674
  startGASPSync: jest.fn().mockResolvedValue(undefined),
675
+ // @ts-expect-error - Mock return values
676
+ refreshUnprovenTransactionProofs: jest.fn().mockResolvedValue({}),
677
+ // @ts-expect-error - Mock return values
678
+ maintainUnprovenTransactions: jest.fn().mockResolvedValue({}),
679
+ // @ts-expect-error - Mock return values
680
+ evictAppliedTransaction: jest.fn().mockResolvedValue({ evictedTransactions: 1, evictedOutputs: 1 }),
675
681
  lookupServices: {},
676
682
  advertiser: {
677
683
  // @ts-expect-error - Mock return values
@@ -881,6 +887,11 @@ describe('OverlayExpress', () => {
881
887
  }
882
888
  // Flush the async IIFE inside the /arc-ingest handler.
883
889
  const flush = async (): Promise<void> => { await new Promise(resolve => setImmediate(resolve)) }
890
+ const proofCallbackBody = {
891
+ txid: '11'.repeat(32),
892
+ merklePath: '00',
893
+ blockHeight: 800000
894
+ }
884
895
 
885
896
  const captureArcIngestHandler = async (): Promise<any> => {
886
897
  const postSpy = jest.spyOn(instance.app, 'post')
@@ -924,7 +935,7 @@ describe('OverlayExpress', () => {
924
935
  const handler = await captureArcIngestHandler()
925
936
  const res = mockRes()
926
937
 
927
- handler({ headers: { authorization: 'Bearer secret-token' }, body: {} }, res)
938
+ handler({ headers: { authorization: 'Bearer secret-token' }, body: proofCallbackBody }, res)
928
939
  await flush()
929
940
 
930
941
  expect(res.status).not.toHaveBeenCalledWith(401)
@@ -937,7 +948,7 @@ describe('OverlayExpress', () => {
937
948
  const handler = await captureArcIngestHandler()
938
949
  const res = mockRes()
939
950
 
940
- handler({ headers: { 'x-callback-token': 'secret-token' }, body: {} }, res)
951
+ handler({ headers: { 'x-callback-token': 'secret-token' }, body: proofCallbackBody }, res)
941
952
  await flush()
942
953
 
943
954
  expect(res.status).not.toHaveBeenCalledWith(401)
@@ -949,12 +960,35 @@ describe('OverlayExpress', () => {
949
960
  const handler = await captureArcIngestHandler()
950
961
  const res = mockRes()
951
962
 
952
- handler({ headers: {}, body: {} }, res)
963
+ handler({ headers: {}, body: proofCallbackBody }, res)
953
964
  await flush()
954
965
 
955
966
  expect(res.status).not.toHaveBeenCalledWith(401)
956
967
  expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
957
968
  })
969
+
970
+ it('evicts a transaction when a provider reports a terminal double-spend status', async () => {
971
+ instance.configureArcApiKey('test-arc-key')
972
+ instance.configureArcCallbackToken('secret-token')
973
+ const handler = await captureArcIngestHandler()
974
+ const res = mockRes()
975
+
976
+ handler({
977
+ headers: { authorization: 'Bearer secret-token' },
978
+ body: {
979
+ txid: '11'.repeat(32),
980
+ txStatus: 'DOUBLE_SPEND_ATTEMPTED',
981
+ competingTxs: ['22'.repeat(32)]
982
+ }
983
+ }, res)
984
+ await flush()
985
+
986
+ expect(mockEngine.evictAppliedTransaction).toHaveBeenCalledWith('11'.repeat(32), {
987
+ topic: undefined,
988
+ reason: 'DOUBLE_SPEND_ATTEMPTED'
989
+ })
990
+ expect(mockEngine.handleNewMerkleProof).not.toHaveBeenCalled()
991
+ })
958
992
  })
959
993
 
960
994
  it('should run knex migrations on start', async () => {
@@ -84,6 +84,7 @@ describe('OverlayMonitor', () => {
84
84
  }))
85
85
  expect(report.summary.targetCount).toBe(1)
86
86
  expect(report.summary.probeCount).toBe(1)
87
+ expect(report.summary.maintenanceActionCount).toBe(0)
87
88
  expect(report.summary.outputsMissingSubjectProof).toBe(1)
88
89
  })
89
90
 
@@ -152,6 +153,79 @@ describe('OverlayMonitor', () => {
152
153
  expect(report.anchorResults[0].warnings).toHaveLength(0)
153
154
  })
154
155
 
156
+ it('runs configured admin maintenance actions', async () => {
157
+ const fetchImpl = jest.fn<typeof fetch>(async (url) => {
158
+ if (String(url).endsWith('/admin/maintainUnproven')) {
159
+ return new Response(JSON.stringify({ status: 'success', data: { evictedTransactions: 1 } }), { status: 200 })
160
+ }
161
+ if (String(url).endsWith('/admin/startBASMSync')) {
162
+ return new Response(JSON.stringify({ status: 'success', data: { synced: true } }), { status: 200 })
163
+ }
164
+ return new Response(JSON.stringify({ status: 'success' }), { status: 200 })
165
+ })
166
+ const monitor = new OverlayMonitor({
167
+ targets: [
168
+ {
169
+ name: 'maintained-overlay',
170
+ baseUrl: 'https://overlay.example',
171
+ probes: [],
172
+ maintenance: {
173
+ adminToken: 'admin-secret',
174
+ startBASMSync: true,
175
+ maintainUnproven: {
176
+ topics: ['tm_a', 'tm_b'],
177
+ thresholdBlocks: 12
178
+ }
179
+ }
180
+ }
181
+ ],
182
+ fetchImpl
183
+ })
184
+
185
+ const report = await monitor.runOnce()
186
+
187
+ expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/admin/startBASMSync', expect.objectContaining({
188
+ method: 'POST',
189
+ headers: expect.objectContaining({ Authorization: 'Bearer admin-secret' }),
190
+ body: JSON.stringify({})
191
+ }))
192
+ expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/admin/maintainUnproven', expect.objectContaining({
193
+ method: 'POST',
194
+ headers: expect.objectContaining({ Authorization: 'Bearer admin-secret' }),
195
+ body: JSON.stringify({ topic: 'tm_a', thresholdBlocks: 12 })
196
+ }))
197
+ expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/admin/maintainUnproven', expect.objectContaining({
198
+ method: 'POST',
199
+ body: JSON.stringify({ topic: 'tm_b', thresholdBlocks: 12 })
200
+ }))
201
+ expect(report.maintenanceResults).toHaveLength(3)
202
+ expect(report.summary.maintenanceActionCount).toBe(3)
203
+ expect(report.summary.failedMaintenanceActionCount).toBe(0)
204
+ })
205
+
206
+ it('reports failed admin maintenance separately from probe failures', async () => {
207
+ const fetchImpl = jest.fn<typeof fetch>(async () => new Response(JSON.stringify({ message: 'Forbidden' }), { status: 403 }))
208
+ const monitor = new OverlayMonitor({
209
+ targets: [
210
+ {
211
+ name: 'maintained-overlay',
212
+ baseUrl: 'https://overlay.example',
213
+ probes: [],
214
+ maintenance: {
215
+ maintainUnproven: true
216
+ }
217
+ }
218
+ ],
219
+ fetchImpl
220
+ })
221
+
222
+ const report = await monitor.runOnce()
223
+
224
+ expect(report.summary.failedProbeCount).toBe(0)
225
+ expect(report.summary.failedMaintenanceActionCount).toBe(1)
226
+ expect(report.maintenanceResults[0].error).toBe('Forbidden')
227
+ })
228
+
155
229
  it('aborts a probe that exceeds the configured timeout', async () => {
156
230
  // Never resolves on its own; only settles when the abort signal fires.
157
231
  const fetchImpl = jest.fn<typeof fetch>(async (_url, init) => await new Promise<Response>((_resolve, reject) => {
@@ -0,0 +1,39 @@
1
+ import { ArcadeProvider } from '../ArcadeProvider.js'
2
+ import { ChaintracksProvider } from '../ChaintracksProvider.js'
3
+
4
+ const runLive = process.env.RUN_LIVE_OVERLAY_PROVIDER_TESTS === '1'
5
+ const describeLive = runLive ? describe : describe.skip
6
+
7
+ describeLive('Overlay providers live integration', () => {
8
+ jest.setTimeout(30000)
9
+
10
+ test.each([
11
+ ['mainnet', process.env.ARCADE_MAINNET_URL ?? 'https://arcade-v2-us-1.bsvblockchain.tech'],
12
+ ['teratestnet', process.env.ARCADE_TTN_URL ?? 'https://arcade-v2-ttn-us-1.bsvblockchain.tech']
13
+ ])('reads real %s headers through Arcade go-chaintracks', async (_label, url) => {
14
+ const chaintracks = new ChaintracksProvider(url)
15
+ const height = await chaintracks.currentHeight()
16
+ const header = await chaintracks.findHeaderForHeight(height)
17
+
18
+ expect(height).toBeGreaterThan(0)
19
+ expect(header?.height).toBe(height)
20
+ expect(header?.hash).toMatch(/^[0-9a-f]{64}$/)
21
+ expect(header?.merkleRoot).toMatch(/^[0-9a-f]{64}$/)
22
+ await expect(chaintracks.isValidRootForHeight(header!.merkleRoot, height)).resolves.toBe(true)
23
+ })
24
+
25
+ test('fetches and validates a real mined mainnet Arcade proof', async () => {
26
+ const txid = process.env.ARCADE_PROOF_TXID ?? 'f283c15af7fb9301ef35445eaa76e92d36382880078490b2f4fbae55b6f9551a'
27
+ const arcadeUrl = process.env.ARCADE_MAINNET_URL ?? 'https://arcade-v2-us-1.bsvblockchain.tech'
28
+ const arcade = new ArcadeProvider(arcadeUrl)
29
+ const chaintracks = new ChaintracksProvider(arcadeUrl)
30
+
31
+ const proof = await arcade.fetchMerkleProof(txid)
32
+
33
+ expect(proof).toBeDefined()
34
+ expect(proof?.txid).toBe(txid)
35
+ expect(proof?.blockHeight).toBeGreaterThan(0)
36
+ expect(proof?.merkleRoot).toMatch(/^[0-9a-f]{64}$/)
37
+ await expect(chaintracks.isValidRootForHeight(proof!.merkleRoot, proof!.blockHeight!)).resolves.toBe(true)
38
+ })
39
+ })
@@ -0,0 +1,123 @@
1
+ import { ArcadeProvider } from '../ArcadeProvider.js'
2
+ import { ChaintracksProvider } from '../ChaintracksProvider.js'
3
+ import { ProviderChainBroadcaster } from '../ProviderChainBroadcaster.js'
4
+
5
+ describe('Overlay transaction providers', () => {
6
+ const tx = {
7
+ id: jest.fn(() => '11'.repeat(32)),
8
+ toHexEF: jest.fn(() => 'efhex'),
9
+ toHex: jest.fn(() => 'rawhex')
10
+ } as any
11
+
12
+ beforeEach(() => {
13
+ jest.clearAllMocks()
14
+ })
15
+
16
+ it('tries the next broadcaster after a transient provider failure', async () => {
17
+ const first = {
18
+ broadcast: jest.fn(async () => ({
19
+ status: 'error' as const,
20
+ code: '503',
21
+ description: 'backpressure',
22
+ more: { terminal: false }
23
+ }))
24
+ }
25
+ const second = {
26
+ broadcast: jest.fn(async () => ({
27
+ status: 'success' as const,
28
+ txid: tx.id(),
29
+ message: 'accepted'
30
+ }))
31
+ }
32
+ const chain = new ProviderChainBroadcaster([
33
+ { name: 'Arcade', broadcaster: first },
34
+ { name: 'ARC', broadcaster: second }
35
+ ])
36
+
37
+ const response = await chain.broadcast(tx)
38
+
39
+ expect(response.status).toBe('success')
40
+ expect(first.broadcast).toHaveBeenCalledTimes(1)
41
+ expect(second.broadcast).toHaveBeenCalledTimes(1)
42
+ })
43
+
44
+ it('stops on terminal double-spend failures', async () => {
45
+ const first = {
46
+ broadcast: jest.fn(async () => ({
47
+ status: 'error' as const,
48
+ code: 'DOUBLE_SPEND_ATTEMPTED',
49
+ description: 'double spend',
50
+ more: { terminal: true, competingTxs: ['22'.repeat(32)] }
51
+ }))
52
+ }
53
+ const second = {
54
+ broadcast: jest.fn(async () => ({
55
+ status: 'success' as const,
56
+ txid: tx.id(),
57
+ message: 'accepted'
58
+ }))
59
+ }
60
+ const chain = new ProviderChainBroadcaster([
61
+ { name: 'Arcade', broadcaster: first },
62
+ { name: 'ARC', broadcaster: second }
63
+ ])
64
+
65
+ const response = await chain.broadcast(tx)
66
+
67
+ expect(response.status).toBe('error')
68
+ if (response.status === 'error') {
69
+ expect(response.code).toBe('DOUBLE_SPEND_ATTEMPTED')
70
+ }
71
+ expect(first.broadcast).toHaveBeenCalledTimes(1)
72
+ expect(second.broadcast).not.toHaveBeenCalled()
73
+ })
74
+
75
+ it('classifies Arcade double-spend status as a broadcast failure', async () => {
76
+ const requests: Array<{ url: string, init?: RequestInit }> = []
77
+ const fetcher = jest.fn(async (url: string, init?: RequestInit) => {
78
+ requests.push({ url, init })
79
+ return new Response(JSON.stringify({
80
+ txid: tx.id(),
81
+ txStatus: 'DOUBLE_SPEND_ATTEMPTED',
82
+ competingTxs: ['22'.repeat(32)]
83
+ }), { status: 202 })
84
+ }) as any
85
+ const arcade = new ArcadeProvider('https://arcade.example/', {
86
+ apiKey: 'secret',
87
+ callbackUrl: 'https://overlay.example/arc-ingest',
88
+ callbackToken: 'callback',
89
+ fetch: fetcher
90
+ })
91
+
92
+ const response = await arcade.broadcast(tx)
93
+
94
+ expect(response.status).toBe('error')
95
+ if (response.status === 'error') {
96
+ expect(response.code).toBe('DOUBLE_SPEND_ATTEMPTED')
97
+ }
98
+ expect(requests[0].url).toBe('https://arcade.example/tx')
99
+ expect((requests[0].init?.headers as Record<string, string>).Authorization).toBe('Bearer secret')
100
+ })
101
+
102
+ it('validates merkle roots through go-chaintracks headers', async () => {
103
+ const fetcher = jest.fn(async (url: string) => {
104
+ if (url.endsWith('/height')) {
105
+ return new Response(JSON.stringify({ height: 900000 }), { status: 200 })
106
+ }
107
+ if (url.endsWith('/header/height/900000')) {
108
+ return new Response(JSON.stringify({
109
+ height: 900000,
110
+ hash: 'aa'.repeat(32),
111
+ merkleRoot: 'bb'.repeat(32)
112
+ }), { status: 200 })
113
+ }
114
+ return new Response('', { status: 404 })
115
+ }) as any
116
+ const chaintracks = new ChaintracksProvider('https://arcade.example', { fetch: fetcher })
117
+
118
+ await expect(chaintracks.currentHeight()).resolves.toBe(900000)
119
+ await expect(chaintracks.isValidRootForHeight('bb'.repeat(32), 900000)).resolves.toBe(true)
120
+ await expect(chaintracks.isValidRootForHeight('cc'.repeat(32), 900000)).resolves.toBe(false)
121
+ expect(chaintracks.reorgStreamUrl()).toBe('https://arcade.example/chaintracks/v2/reorg/stream')
122
+ })
123
+ })