@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.
Files changed (56) 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 +19 -19
  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 +270 -28
  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/src/generalGuide.md.js +1 -1
  16. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  17. package/dist/esm/mod.js +3 -0
  18. package/dist/esm/mod.js.map +1 -1
  19. package/dist/esm/src/ArcadeProvider.js +189 -0
  20. package/dist/esm/src/ArcadeProvider.js.map +1 -0
  21. package/dist/esm/src/ChaintracksProvider.js +62 -0
  22. package/dist/esm/src/ChaintracksProvider.js.map +1 -0
  23. package/dist/esm/src/OverlayExpress.js +265 -28
  24. package/dist/esm/src/OverlayExpress.js.map +1 -1
  25. package/dist/esm/src/OverlayMonitor.js +117 -3
  26. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  27. package/dist/esm/src/ProviderChainBroadcaster.js +88 -0
  28. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -0
  29. package/dist/esm/src/generalGuide.md.js +1 -1
  30. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  31. package/dist/types/mod.d.ts +3 -0
  32. package/dist/types/mod.d.ts.map +1 -1
  33. package/dist/types/src/ArcadeProvider.d.ts +37 -0
  34. package/dist/types/src/ArcadeProvider.d.ts.map +1 -0
  35. package/dist/types/src/ChaintracksProvider.d.ts +29 -0
  36. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -0
  37. package/dist/types/src/OverlayExpress.d.ts +38 -1
  38. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  39. package/dist/types/src/OverlayMonitor.d.ts +28 -0
  40. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  41. package/dist/types/src/ProviderChainBroadcaster.d.ts +18 -0
  42. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -0
  43. package/dist/types/src/generalGuide.md.d.ts +1 -1
  44. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  45. package/mod.ts +15 -0
  46. package/package.json +19 -19
  47. package/src/ArcadeProvider.ts +232 -0
  48. package/src/ChaintracksProvider.ts +79 -0
  49. package/src/OverlayExpress.ts +299 -28
  50. package/src/OverlayMonitor.ts +163 -3
  51. package/src/ProviderChainBroadcaster.ts +108 -0
  52. package/src/__tests__/OverlayExpress.test.ts +196 -4
  53. package/src/__tests__/OverlayMonitor.test.ts +74 -0
  54. package/src/__tests__/OverlayProviders.live.test.ts +43 -0
  55. package/src/__tests__/OverlayProviders.test.ts +123 -0
  56. package/src/generalGuide.md.ts +1 -1
@@ -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,43 @@
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
+ if (header === undefined) throw new Error('header was not returned')
23
+ await expect(chaintracks.isValidRootForHeight(header.merkleRoot, height)).resolves.toBe(true)
24
+ })
25
+
26
+ test('fetches and validates a real mined mainnet Arcade proof', async () => {
27
+ const txid = process.env.ARCADE_PROOF_TXID ?? 'f283c15af7fb9301ef35445eaa76e92d36382880078490b2f4fbae55b6f9551a'
28
+ const arcadeUrl = process.env.ARCADE_MAINNET_URL ?? 'https://arcade-v2-us-1.bsvblockchain.tech'
29
+ const arcade = new ArcadeProvider(arcadeUrl)
30
+ const chaintracks = new ChaintracksProvider(arcadeUrl)
31
+
32
+ const proof = await arcade.fetchMerkleProof(txid)
33
+
34
+ expect(proof).toBeDefined()
35
+ expect(proof?.txid).toBe(txid)
36
+ expect(proof?.blockHeight).toBeGreaterThan(0)
37
+ expect(proof?.merkleRoot).toMatch(/^[0-9a-f]{64}$/)
38
+ if (proof === undefined || proof.blockHeight === undefined) {
39
+ throw new Error('complete proof was not returned')
40
+ }
41
+ await expect(chaintracks.isValidRootForHeight(proof.merkleRoot, proof.blockHeight)).resolves.toBe(true)
42
+ })
43
+ })
@@ -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
+ })
@@ -10,7 +10,7 @@ A Topic Manager controls addition and removal of transaction outputs to an Overl
10
10
  #### Request Headers
11
11
  \\\`\\\`\\\`json
12
12
  {
13
- "x-topics": "["tm_messagebox"]", // array of topic identifiers as stringified JSON
13
+ "x-topics": "tm_messagebox", // comma-separated topic identifiers
14
14
  "x-includes-off-chain-values": "false" // string "true" or "false"
15
15
  }
16
16
  \\\`\\\`\\\`