@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
package/mod.ts CHANGED
@@ -30,3 +30,18 @@ export {
30
30
  type OverlayMonitorThresholds,
31
31
  type OverlayMonitorWarning
32
32
  } from './src/OverlayMonitor.js'
33
+ export {
34
+ ArcadeProvider,
35
+ isTerminalArcStatus,
36
+ type ArcadeMerkleProof,
37
+ type ArcadeProviderConfig
38
+ } from './src/ArcadeProvider.js'
39
+ export {
40
+ ProviderChainBroadcaster,
41
+ type NamedBroadcaster
42
+ } from './src/ProviderChainBroadcaster.js'
43
+ export {
44
+ ChaintracksProvider,
45
+ type ChaintracksHeader,
46
+ type ChaintracksProviderConfig
47
+ } from './src/ChaintracksProvider.js'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bsv/overlay-express",
3
- "version": "2.4.0",
3
+ "version": "2.4.2",
4
4
  "type": "module",
5
5
  "description": "BSV Blockchain Overlay Express",
6
6
  "main": "dist/cjs/mod.js",
@@ -45,32 +45,32 @@
45
45
  "homepage": "https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-express#readme",
46
46
  "devDependencies": {
47
47
  "@jest/globals": "^30.4.1",
48
- "@types/body-parser": "^1.19.5",
49
- "@types/express": "^5.0.0",
48
+ "@types/body-parser": "^1.19.6",
49
+ "@types/express": "^5.0.6",
50
50
  "@types/jest": "^30.0.0",
51
- "@types/node": "^25.9.3",
51
+ "@types/node": "^26.1.1",
52
52
  "jest": "^30.4.2",
53
- "ts-jest": "^29.4.11",
54
- "ts-standard": "^12.0.2",
55
- "ts2md": "^0.2.0",
53
+ "ts-jest": "^29.4.12",
54
+ "ts2md": "^0.2.8",
56
55
  "tsconfig-to-dual-package": "^1.2.0",
57
56
  "typescript": "^6.0.3",
58
- "@bsv/sdk": "^2.1.3"
57
+ "oxlint": "^1.75.0",
58
+ "@bsv/sdk": "^2.2.0"
59
59
  },
60
60
  "dependencies": {
61
- "@bsv/auth-express-middleware": "^2.0.6",
62
- "@bsv/overlay": "^2.0.4",
63
- "@bsv/overlay-discovery-services": "^2.0.3",
64
- "@bsv/wallet-toolbox-client": "^2.1.30",
65
- "body-parser": "^2.2.2",
61
+ "body-parser": "^2.3.0",
66
62
  "chalk": "^5.6.2",
67
63
  "express": "^5.2.1",
68
- "knex": "^3.2.10",
69
- "mongodb": "^7.3.0",
70
- "uuid": "^14.0.0"
64
+ "knex": "^3.3.0",
65
+ "mongodb": "^7.5.0",
66
+ "uuid": "^14.0.1",
67
+ "@bsv/auth-express-middleware": "^2.1.2",
68
+ "@bsv/overlay": "^2.2.1",
69
+ "@bsv/overlay-discovery-services": "^2.1.1",
70
+ "@bsv/wallet-toolbox-client": "^2.4.4"
71
71
  },
72
72
  "peerDependencies": {
73
- "@bsv/sdk": "^2"
73
+ "@bsv/sdk": "^2.1.6"
74
74
  },
75
75
  "peerDependenciesMeta": {
76
76
  "@bsv/sdk": {
@@ -81,8 +81,8 @@
81
81
  "test": "jest",
82
82
  "test:watch": "jest --watch",
83
83
  "test:coverage": "jest --coverage",
84
- "lint": "ts-standard --fix src/**/*.ts",
85
- "lint:ci": "ts-standard src/**/*.ts",
84
+ "lint": "oxlint src",
85
+ "lint:ci": "oxlint src",
86
86
  "build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
87
87
  "dev": "tsc -b -w",
88
88
  "prepublish": "npm run build",
@@ -0,0 +1,232 @@
1
+ import {
2
+ BroadcastFailure,
3
+ Broadcaster,
4
+ BroadcastResponse,
5
+ MerklePath,
6
+ Transaction
7
+ } from '@bsv/sdk'
8
+
9
+ export interface ArcadeProviderConfig {
10
+ apiKey?: string
11
+ callbackUrl?: string
12
+ callbackToken?: string
13
+ deploymentId?: string
14
+ headers?: Record<string, string>
15
+ fetch?: typeof fetch
16
+ }
17
+
18
+ export interface ArcadeMerkleProof {
19
+ txid: string
20
+ merklePath: MerklePath
21
+ blockHeight?: number
22
+ blockHash?: string
23
+ merkleRoot: string
24
+ }
25
+
26
+ interface ArcadeTxResponse {
27
+ txid?: string
28
+ txStatus?: string
29
+ status?: number | string
30
+ extraInfo?: string
31
+ detail?: string
32
+ error?: string
33
+ reason?: string
34
+ competingTxs?: string[]
35
+ merklePath?: string
36
+ blockHeight?: number
37
+ blockHash?: string
38
+ }
39
+
40
+ const TERMINAL_STATUSES = new Set([
41
+ 'DOUBLE_SPEND_ATTEMPTED',
42
+ 'REJECTED',
43
+ 'INVALID',
44
+ 'MALFORMED',
45
+ 'MINED_IN_STALE_BLOCK'
46
+ ])
47
+
48
+ const SUCCESS_STATUSES = new Set([
49
+ 'RECEIVED',
50
+ 'SENT_TO_NETWORK',
51
+ 'ANNOUNCED_TO_NETWORK',
52
+ 'ACCEPTED_BY_NETWORK',
53
+ 'SEEN_ON_NETWORK',
54
+ 'STORED',
55
+ 'MINED',
56
+ 'IMMUTABLE'
57
+ ])
58
+
59
+ export function isTerminalArcStatus (status: unknown, extraInfo?: unknown): boolean {
60
+ const statusText = typeof status === 'string' ? status.toUpperCase() : ''
61
+ const extraText = typeof extraInfo === 'string' ? extraInfo.toUpperCase() : ''
62
+ return TERMINAL_STATUSES.has(statusText) || statusText.includes('ORPHAN') || extraText.includes('ORPHAN')
63
+ }
64
+
65
+ function trimBaseUrl (url: string): string {
66
+ let base = url
67
+ while (base.endsWith('/')) base = base.slice(0, -1)
68
+ return base
69
+ }
70
+
71
+ function parseDescription (data: unknown, fallback: string): string {
72
+ if (typeof data === 'string') return data
73
+ if (typeof data === 'object' && data !== null) {
74
+ const d = data as ArcadeTxResponse
75
+ return d.detail ?? d.reason ?? d.error ?? `${d.txStatus ?? ''} ${d.extraInfo ?? ''}`.trim() ?? fallback
76
+ }
77
+ return fallback
78
+ }
79
+
80
+ function rawTxForArcade (tx: Transaction): string {
81
+ try {
82
+ return tx.toHexEF()
83
+ } catch (error: unknown) {
84
+ if (
85
+ error instanceof Error &&
86
+ error.message === 'All inputs must have source transactions when serializing to EF format'
87
+ ) {
88
+ return tx.toHex()
89
+ }
90
+ throw error
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Broadcaster/proof client for bsv-blockchain/arcade.
96
+ *
97
+ * Arcade exposes transaction propagation at `/tx` and status/proofs at
98
+ * `/tx/{txid}`. It returns terminal validation and double-spend statuses in the
99
+ * body, so callers must classify those as failed broadcasts even when HTTP
100
+ * accepted the request.
101
+ */
102
+ export class ArcadeProvider implements Broadcaster {
103
+ readonly name = 'Arcade'
104
+ private readonly baseUrl: string
105
+ private readonly fetcher: typeof fetch
106
+
107
+ constructor (url: string, private readonly config: ArcadeProviderConfig = {}) {
108
+ this.baseUrl = trimBaseUrl(url)
109
+ this.fetcher = config.fetch ?? fetch
110
+ }
111
+
112
+ async broadcast (tx: Transaction): Promise<BroadcastResponse | BroadcastFailure> {
113
+ const rawTx = rawTxForArcade(tx)
114
+ try {
115
+ const response = await this.fetcher(`${this.baseUrl}/tx`, {
116
+ method: 'POST',
117
+ headers: this.requestHeaders(),
118
+ body: JSON.stringify({ rawTx })
119
+ })
120
+ const data = await this.readResponse<ArcadeTxResponse>(response)
121
+ if (!response.ok) {
122
+ const failure: BroadcastFailure = {
123
+ status: 'error',
124
+ code: data?.txStatus ?? String(response.status),
125
+ txid: data?.txid,
126
+ description: parseDescription(data, response.statusText)
127
+ }
128
+ const more: Record<string, unknown> = {
129
+ provider: this.name,
130
+ httpStatus: response.status,
131
+ terminal: response.status === 400 || isTerminalArcStatus(data?.txStatus, data?.extraInfo),
132
+ response: data
133
+ }
134
+ if (data?.competingTxs !== undefined) {
135
+ more.competingTxs = data.competingTxs
136
+ }
137
+ failure.more = more
138
+ return failure
139
+ }
140
+
141
+ const txStatus = data?.txStatus
142
+ if (isTerminalArcStatus(txStatus, data?.extraInfo)) {
143
+ const failure: BroadcastFailure = {
144
+ status: 'error',
145
+ code: txStatus ?? 'UNKNOWN',
146
+ txid: data?.txid,
147
+ description: `${txStatus ?? ''} ${data?.extraInfo ?? ''}`.trim()
148
+ }
149
+ const more: Record<string, unknown> = { provider: this.name, terminal: true, response: data }
150
+ if (data?.competingTxs !== undefined) {
151
+ more.competingTxs = data.competingTxs
152
+ }
153
+ failure.more = more
154
+ return failure
155
+ }
156
+
157
+ const statusText = typeof txStatus === 'string' ? txStatus.toUpperCase() : undefined
158
+ return {
159
+ status: 'success',
160
+ txid: data?.txid ?? tx.id('hex'),
161
+ message: `${txStatus ?? (SUCCESS_STATUSES.has(statusText ?? '') ? statusText ?? '' : response.statusText)} ${data?.extraInfo ?? ''}`.trim(),
162
+ competingTxs: data?.competingTxs
163
+ }
164
+ } catch (error: unknown) {
165
+ return {
166
+ status: 'error',
167
+ code: '500',
168
+ description: error instanceof Error ? error.message : 'Internal Server Error',
169
+ more: { provider: this.name, terminal: false }
170
+ }
171
+ }
172
+ }
173
+
174
+ async fetchMerkleProof (txid: string): Promise<ArcadeMerkleProof | undefined> {
175
+ const response = await this.fetcher(`${this.baseUrl}/tx/${txid}`, {
176
+ method: 'GET',
177
+ headers: this.requestHeaders({ accept: 'application/json' })
178
+ })
179
+ if (response.status === 404) return undefined
180
+ const data = await this.readResponse<ArcadeTxResponse>(response)
181
+ if (!response.ok) {
182
+ throw new Error(`Arcade proof lookup failed for ${txid}: ${response.status} ${parseDescription(data, response.statusText)}`)
183
+ }
184
+ const mined = data?.txStatus === 'MINED' || data?.txStatus === 'IMMUTABLE'
185
+ if (!mined || data?.merklePath === undefined || data.merklePath === '') {
186
+ return undefined
187
+ }
188
+ const merklePath = MerklePath.fromHex(data.merklePath)
189
+ return {
190
+ txid,
191
+ merklePath,
192
+ blockHeight: data.blockHeight ?? merklePath.blockHeight,
193
+ blockHash: data.blockHash,
194
+ merkleRoot: merklePath.computeRoot(txid)
195
+ }
196
+ }
197
+
198
+ private requestHeaders (options: { accept?: string } = {}): Record<string, string> {
199
+ const headers: Record<string, string> = {
200
+ Accept: options.accept ?? 'application/json',
201
+ 'Content-Type': 'application/json'
202
+ }
203
+ if (this.config.deploymentId !== undefined && this.config.deploymentId !== '') {
204
+ headers['XDeployment-ID'] = this.config.deploymentId
205
+ }
206
+ if (this.config.apiKey !== undefined && this.config.apiKey !== '') {
207
+ headers.Authorization = `Bearer ${this.config.apiKey}`
208
+ }
209
+ if (this.config.callbackUrl !== undefined && this.config.callbackUrl !== '') {
210
+ headers['X-CallbackUrl'] = this.config.callbackUrl
211
+ }
212
+ if (this.config.callbackToken !== undefined && this.config.callbackToken !== '') {
213
+ headers['X-CallbackToken'] = this.config.callbackToken
214
+ }
215
+ if (this.config.headers !== undefined) {
216
+ for (const [key, value] of Object.entries(this.config.headers)) {
217
+ headers[key] = value
218
+ }
219
+ }
220
+ return headers
221
+ }
222
+
223
+ private async readResponse<T>(response: Response): Promise<T | undefined> {
224
+ const text = await response.text()
225
+ if (text === '') return undefined
226
+ try {
227
+ return JSON.parse(text) as T
228
+ } catch {
229
+ return text as T
230
+ }
231
+ }
232
+ }
@@ -0,0 +1,79 @@
1
+ import { ChainTracker } from '@bsv/sdk'
2
+
3
+ export interface ChaintracksProviderConfig {
4
+ apiPrefix?: string
5
+ fetch?: typeof fetch
6
+ }
7
+
8
+ export interface ChaintracksHeader {
9
+ height: number
10
+ hash: string
11
+ merkleRoot: string
12
+ }
13
+
14
+ function trimUrl (url: string): string {
15
+ let trimmed = url
16
+ while (trimmed.endsWith('/')) trimmed = trimmed.slice(0, -1)
17
+ return trimmed
18
+ }
19
+
20
+ function trimPrefix (prefix: string): string {
21
+ if (prefix === '') return ''
22
+ let trimmed = prefix.startsWith('/') ? prefix : `/${prefix}`
23
+ while (trimmed.endsWith('/')) trimmed = trimmed.slice(0, -1)
24
+ return trimmed
25
+ }
26
+
27
+ /**
28
+ * Minimal go-chaintracks HTTP client for Overlay Express.
29
+ *
30
+ * It intentionally implements the SDK ChainTracker surface plus header lookup,
31
+ * which is enough for proof validation, BASM headers, and reorg stream URL
32
+ * construction without depending on wallet-toolbox client export timing.
33
+ */
34
+ export class ChaintracksProvider implements ChainTracker {
35
+ private readonly baseUrl: string
36
+ private readonly fetcher: typeof fetch
37
+
38
+ constructor (url: string, config: ChaintracksProviderConfig = {}) {
39
+ this.baseUrl = `${trimUrl(url)}${trimPrefix(config.apiPrefix ?? '/chaintracks/v2')}`
40
+ this.fetcher = config.fetch ?? fetch
41
+ }
42
+
43
+ async currentHeight (): Promise<number> {
44
+ const response = await this.getJson<{ height: number }>('/height')
45
+ return response.height
46
+ }
47
+
48
+ async isValidRootForHeight (root: string, height: number): Promise<boolean> {
49
+ const header = await this.findHeaderForHeight(height)
50
+ return header !== undefined && header.merkleRoot === root
51
+ }
52
+
53
+ async findHeaderForHeight (height: number): Promise<ChaintracksHeader | undefined> {
54
+ return await this.getJsonOrUndefined<ChaintracksHeader>(`/header/height/${height}`)
55
+ }
56
+
57
+ reorgStreamUrl (): string {
58
+ return `${this.baseUrl}/reorg/stream`
59
+ }
60
+
61
+ private async getJson<T>(path: string): Promise<T> {
62
+ const value = await this.getJsonOrUndefined<T>(path)
63
+ if (value === undefined) {
64
+ throw new Error(`Chaintracks returned no value for ${path}`)
65
+ }
66
+ return value
67
+ }
68
+
69
+ private async getJsonOrUndefined<T>(path: string): Promise<T | undefined> {
70
+ const response = await this.fetcher(`${this.baseUrl}${path}`, {
71
+ headers: { Accept: 'application/json' }
72
+ })
73
+ if (response.status === 404) return undefined
74
+ if (!response.ok) {
75
+ throw new Error(`Chaintracks request failed for ${path}: ${response.status} ${response.statusText}`)
76
+ }
77
+ return await response.json() as T
78
+ }
79
+ }