@bsv/overlay-express 2.3.0 → 2.3.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 (51) hide show
  1. package/dist/cjs/mod.js +7 -1
  2. package/dist/cjs/mod.js.map +1 -1
  3. package/dist/cjs/package.json +4 -4
  4. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  6. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  8. package/dist/cjs/src/OverlayExpress.js +348 -95
  9. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  10. package/dist/cjs/src/OverlayMonitor.js +166 -8
  11. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  12. package/dist/cjs/src/ReorgStream.js +193 -0
  13. package/dist/cjs/src/ReorgStream.js.map +1 -0
  14. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  15. package/dist/esm/mod.js +3 -1
  16. package/dist/esm/mod.js.map +1 -1
  17. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  19. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  20. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  21. package/dist/esm/src/OverlayExpress.js +348 -93
  22. package/dist/esm/src/OverlayExpress.js.map +1 -1
  23. package/dist/esm/src/OverlayMonitor.js +160 -6
  24. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  25. package/dist/esm/src/ReorgStream.js +190 -0
  26. package/dist/esm/src/ReorgStream.js.map +1 -0
  27. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  28. package/dist/types/mod.d.ts +4 -2
  29. package/dist/types/mod.d.ts.map +1 -1
  30. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  32. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  34. package/dist/types/src/OverlayExpress.d.ts +76 -4
  35. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  36. package/dist/types/src/OverlayMonitor.d.ts +45 -1
  37. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  38. package/dist/types/src/ReorgStream.d.ts +74 -0
  39. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  40. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  41. package/mod.ts +7 -1
  42. package/package.json +4 -4
  43. package/src/BanAwareDiscoveryStorage.ts +91 -0
  44. package/src/BanAwareTopicManager.ts +87 -0
  45. package/src/OverlayExpress.ts +431 -100
  46. package/src/OverlayMonitor.ts +219 -7
  47. package/src/ReorgStream.ts +221 -0
  48. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  49. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  50. package/src/__tests__/OverlayMonitor.test.ts +66 -1
  51. package/src/__tests__/ReorgStream.test.ts +66 -0
@@ -0,0 +1,132 @@
1
+ import { describe, it, expect, jest, beforeEach } from '@jest/globals'
2
+ import { TopicManager } from '@bsv/overlay'
3
+ import { PushDrop, Transaction, Utils } from '@bsv/sdk'
4
+ import { BanAwareTopicManager } from '../BanAwareTopicManager.js'
5
+ import { BanService } from '../BanService.js'
6
+
7
+ jest.mock('@bsv/sdk', () => ({
8
+ PushDrop: {
9
+ decode: jest.fn()
10
+ },
11
+ Transaction: {
12
+ fromBEEF: jest.fn()
13
+ },
14
+ Utils: {
15
+ toUTF8: jest.fn()
16
+ }
17
+ }))
18
+
19
+ const mockPushDropDecode = PushDrop.decode as unknown as jest.Mock<any>
20
+ const mockTransactionFromBEEF = Transaction.fromBEEF as unknown as jest.Mock<any>
21
+ const mockToUTF8 = Utils.toUTF8 as unknown as jest.Mock<any>
22
+
23
+ describe('BanAwareTopicManager', () => {
24
+ let wrapper: BanAwareTopicManager
25
+ let mockWrapped: jest.Mocked<TopicManager>
26
+ let mockBanService: jest.Mocked<BanService>
27
+ let mockLogger: any
28
+
29
+ beforeEach(() => {
30
+ jest.clearAllMocks()
31
+
32
+ mockWrapped = {
33
+ identifyAdmissibleOutputs: jest.fn<any>().mockResolvedValue({
34
+ outputsToAdmit: [0, 1],
35
+ coinsToRetain: [0],
36
+ coinsRemoved: [1]
37
+ }),
38
+ identifyNeededInputs: jest.fn<any>().mockResolvedValue([{ txid: 'needed-txid', outputIndex: 0 }]),
39
+ getDocumentation: jest.fn<any>().mockResolvedValue('docs'),
40
+ getMetaData: jest.fn<any>().mockResolvedValue({ name: 'test', shortDescription: 'test' })
41
+ } as any
42
+
43
+ mockBanService = {
44
+ isOutpointBanned: jest.fn<any>().mockResolvedValue(false),
45
+ isDomainBanned: jest.fn<any>().mockResolvedValue(false)
46
+ } as any
47
+
48
+ mockLogger = {
49
+ log: jest.fn()
50
+ }
51
+
52
+ mockTransactionFromBEEF.mockReturnValue({
53
+ id: jest.fn().mockReturnValue('ad-txid'),
54
+ outputs: [
55
+ { lockingScript: 'script-0' },
56
+ { lockingScript: 'script-1' }
57
+ ]
58
+ })
59
+ mockPushDropDecode.mockReturnValue({
60
+ fields: [Buffer.from('SHIP'), Buffer.from('topic'), Buffer.from('https://good.example')]
61
+ })
62
+ mockToUTF8.mockImplementation((value: Buffer) => value.toString('utf8'))
63
+
64
+ wrapper = new BanAwareTopicManager(mockWrapped, mockBanService, 'SHIP', mockLogger)
65
+ })
66
+
67
+ it('should remove banned outpoints from admittance instructions', async () => {
68
+ mockBanService.isOutpointBanned.mockResolvedValueOnce(true).mockResolvedValue(false)
69
+
70
+ const result = await wrapper.identifyAdmissibleOutputs([1, 2, 3], [0], [42], 'current-tx')
71
+
72
+ expect(result.outputsToAdmit).toEqual([1])
73
+ expect(mockWrapped.identifyAdmissibleOutputs).toHaveBeenCalledWith([1, 2, 3], [0], [42], 'current-tx')
74
+ expect(mockBanService.isOutpointBanned).toHaveBeenCalledWith('ad-txid', 0)
75
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned outpoint'))
76
+ })
77
+
78
+ it('should remove outputs whose advertised domain is banned', async () => {
79
+ mockBanService.isDomainBanned.mockResolvedValueOnce(true).mockResolvedValue(false)
80
+
81
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
82
+
83
+ expect(result.outputsToAdmit).toEqual([1])
84
+ expect(mockBanService.isDomainBanned).toHaveBeenCalledWith('https://good.example')
85
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned domain'))
86
+ })
87
+
88
+ it('should preserve all outputs when nothing is banned', async () => {
89
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
90
+
91
+ expect(result.outputsToAdmit).toEqual([0, 1])
92
+ })
93
+
94
+ it('should preserve wrapped instructions when BEEF parsing fails', async () => {
95
+ mockTransactionFromBEEF.mockImplementation(() => { throw new Error('bad beef') })
96
+
97
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
98
+
99
+ expect(result.outputsToAdmit).toEqual([0, 1])
100
+ expect(mockBanService.isOutpointBanned).not.toHaveBeenCalled()
101
+ })
102
+
103
+ it('should preserve wrapped instructions for non-standard outputs', async () => {
104
+ mockPushDropDecode.mockImplementation(() => { throw new Error('bad script') })
105
+
106
+ const result = await wrapper.identifyAdmissibleOutputs([1], [])
107
+
108
+ expect(result.outputsToAdmit).toEqual([0, 1])
109
+ expect(mockBanService.isDomainBanned).not.toHaveBeenCalled()
110
+ })
111
+
112
+ it('should delegate identifyNeededInputs', async () => {
113
+ await expect(wrapper.identifyNeededInputs([1], [2])).resolves.toEqual([{ txid: 'needed-txid', outputIndex: 0 }])
114
+ expect(mockWrapped.identifyNeededInputs).toHaveBeenCalledWith([1], [2])
115
+ })
116
+
117
+ it('should return no needed inputs when wrapped manager does not implement it', async () => {
118
+ const manager = new BanAwareTopicManager(
119
+ { ...mockWrapped, identifyNeededInputs: undefined },
120
+ mockBanService,
121
+ 'SLAP',
122
+ mockLogger
123
+ )
124
+
125
+ await expect(manager.identifyNeededInputs([1])).resolves.toEqual([])
126
+ })
127
+
128
+ it('should delegate documentation and metadata', async () => {
129
+ await expect(wrapper.getDocumentation()).resolves.toBe('docs')
130
+ await expect(wrapper.getMetaData()).resolves.toEqual({ name: 'test', shortDescription: 'test' })
131
+ })
132
+ })
@@ -1,6 +1,6 @@
1
1
  import { describe, it, expect, jest } from '@jest/globals'
2
2
  import { Transaction } from '@bsv/sdk'
3
- import { OverlayMonitor, analyzeOverlayLookupResponse } from '../OverlayMonitor.js'
3
+ import { OverlayMonitor, analyzeOverlayAnchorTip, analyzeOverlayLookupResponse } from '../OverlayMonitor.js'
4
4
 
5
5
  describe('OverlayMonitor', () => {
6
6
  it('summarizes an empty lookup response', () => {
@@ -87,6 +87,71 @@ describe('OverlayMonitor', () => {
87
87
  expect(report.summary.outputsMissingSubjectProof).toBe(1)
88
88
  })
89
89
 
90
+ it('reports stale and mismatched BASM anchor tips', () => {
91
+ const result = analyzeOverlayAnchorTip({
92
+ target: 'local-overlay',
93
+ url: 'https://overlay.example/requestTopicAnchorTip',
94
+ probe: 'anchors',
95
+ topic: 'tm_example',
96
+ status: 200,
97
+ ok: true,
98
+ responseBody: {
99
+ blockHeight: 850000,
100
+ tac: '11'.repeat(32),
101
+ expiredUnprovenCount: 2
102
+ },
103
+ responseBytes: 128,
104
+ durationMs: 5,
105
+ expectedTac: '22'.repeat(32),
106
+ currentHeight: 850020,
107
+ thresholds: {
108
+ anchorTipLagBlocks: 6,
109
+ expiredUnprovenCount: 0
110
+ }
111
+ })
112
+
113
+ expect(result.warnings.map(warning => warning.code)).toEqual([
114
+ 'anchor-tip-mismatch',
115
+ 'anchor-stale-height',
116
+ 'expired-unproven-state'
117
+ ])
118
+ })
119
+
120
+ it('runs configured anchor probes through Overlay Express BASM endpoints', async () => {
121
+ const responseBody = JSON.stringify({
122
+ topic: 'tm_example',
123
+ blockHeight: 850000,
124
+ tac: '11'.repeat(32)
125
+ })
126
+ const fetchImpl = jest.fn<typeof fetch>(async () => new Response(responseBody, { status: 200 }))
127
+ const monitor = new OverlayMonitor({
128
+ targets: [
129
+ {
130
+ name: 'local-overlay',
131
+ baseUrl: 'https://overlay.example',
132
+ probes: [],
133
+ anchorProbes: [
134
+ {
135
+ name: 'topic-tip',
136
+ topic: 'tm_example',
137
+ expectedTac: '11'.repeat(32)
138
+ }
139
+ ]
140
+ }
141
+ ],
142
+ fetchImpl
143
+ })
144
+
145
+ const report = await monitor.runOnce()
146
+
147
+ expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/requestTopicAnchorTip', expect.objectContaining({
148
+ method: 'POST',
149
+ headers: expect.objectContaining({ 'x-bsv-topic': 'tm_example' })
150
+ }))
151
+ expect(report.summary.anchorProbeCount).toBe(1)
152
+ expect(report.anchorResults[0].warnings).toHaveLength(0)
153
+ })
154
+
90
155
  it('aborts a probe that exceeds the configured timeout', async () => {
91
156
  // Never resolves on its own; only settles when the abort signal fires.
92
157
  const fetchImpl = jest.fn<typeof fetch>(async (_url, init) => await new Promise<Response>((_resolve, reject) => {
@@ -0,0 +1,66 @@
1
+ import { parseReorgEvent, extractSseFrames } from '../ReorgStream.js'
2
+
3
+ const HASH_A = 'AABB000000000000000000000000000000000000000000000000000000000000'
4
+ const HASH_B = 'ccdd000000000000000000000000000000000000000000000000000000000000'
5
+
6
+ describe('parseReorgEvent', () => {
7
+ it('maps a go-chaintracks ReorgEvent to handleReorg input (normalizing hashes)', () => {
8
+ const event = JSON.stringify({
9
+ orphanedHashes: [HASH_A, HASH_B],
10
+ commonAncestor: { height: 100, hash: '00ff' },
11
+ newTip: { height: 103, hash: '11ee' },
12
+ depth: 3
13
+ })
14
+
15
+ const result = parseReorgEvent(event)
16
+
17
+ expect(result).toEqual({
18
+ orphanedBlockHashes: [HASH_A.toLowerCase(), HASH_B],
19
+ rebuildFromHeight: 101,
20
+ newTipHeight: 103
21
+ })
22
+ })
23
+
24
+ it('falls back to depth when commonAncestor is absent (reorg past pruned history)', () => {
25
+ const event = JSON.stringify({
26
+ orphanedHashes: [HASH_A],
27
+ commonAncestor: null,
28
+ newTip: { height: 103, hash: '11ee' },
29
+ depth: 3
30
+ })
31
+
32
+ const result = parseReorgEvent(event)
33
+
34
+ // 103 - 3 + 1 = 101
35
+ expect(result?.rebuildFromHeight).toBe(101)
36
+ expect(result?.newTipHeight).toBe(103)
37
+ })
38
+
39
+ it('returns null for malformed frames', () => {
40
+ expect(parseReorgEvent('not json')).toBeNull()
41
+ expect(parseReorgEvent(JSON.stringify({ orphanedHashes: [] }))).toBeNull() // no newTip
42
+ })
43
+ })
44
+
45
+ describe('extractSseFrames', () => {
46
+ it('extracts complete data frames and ignores keepalive comments', () => {
47
+ const buffer = 'data: {"a":1}\n\n: keepalive\n\ndata: {"b":2}\n\n'
48
+ const { events, rest } = extractSseFrames(buffer)
49
+ expect(events).toEqual(['{"a":1}', '{"b":2}'])
50
+ expect(rest).toBe('')
51
+ })
52
+
53
+ it('retains a partial trailing frame in rest', () => {
54
+ const buffer = 'data: {"a":1}\n\ndata: {"b":'
55
+ const { events, rest } = extractSseFrames(buffer)
56
+ expect(events).toEqual(['{"a":1}'])
57
+ expect(rest).toBe('data: {"b":')
58
+ })
59
+
60
+ it('concatenates multi-line data fields within one frame', () => {
61
+ const buffer = 'data: {"a":\ndata: 1}\n\n'
62
+ const { events, rest } = extractSseFrames(buffer)
63
+ expect(events).toEqual(['{"a":1}'])
64
+ expect(rest).toBe('')
65
+ })
66
+ })