@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.
- package/README.md +122 -3
- package/dist/cjs/mod.js +8 -1
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +9 -9
- package/dist/cjs/src/ArcadeProvider.js +196 -0
- package/dist/cjs/src/ArcadeProvider.js.map +1 -0
- package/dist/cjs/src/ChaintracksProvider.js +65 -0
- package/dist/cjs/src/ChaintracksProvider.js.map +1 -0
- package/dist/cjs/src/OverlayExpress.js +235 -11
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/src/OverlayMonitor.js +117 -3
- package/dist/cjs/src/OverlayMonitor.js.map +1 -1
- package/dist/cjs/src/ProviderChainBroadcaster.js +91 -0
- package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -0
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js +3 -0
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/ArcadeProvider.js +189 -0
- package/dist/esm/src/ArcadeProvider.js.map +1 -0
- package/dist/esm/src/ChaintracksProvider.js +62 -0
- package/dist/esm/src/ChaintracksProvider.js.map +1 -0
- package/dist/esm/src/OverlayExpress.js +231 -11
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/src/OverlayMonitor.js +117 -3
- package/dist/esm/src/OverlayMonitor.js.map +1 -1
- package/dist/esm/src/ProviderChainBroadcaster.js +88 -0
- package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -0
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +3 -0
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/ArcadeProvider.d.ts +37 -0
- package/dist/types/src/ArcadeProvider.d.ts.map +1 -0
- package/dist/types/src/ChaintracksProvider.d.ts +29 -0
- package/dist/types/src/ChaintracksProvider.d.ts.map +1 -0
- package/dist/types/src/OverlayExpress.d.ts +38 -1
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/src/OverlayMonitor.d.ts +28 -0
- package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
- package/dist/types/src/ProviderChainBroadcaster.d.ts +18 -0
- package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -0
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +15 -0
- package/package.json +9 -9
- package/src/ArcadeProvider.ts +232 -0
- package/src/ChaintracksProvider.ts +79 -0
- package/src/OverlayExpress.ts +259 -11
- package/src/OverlayMonitor.ts +163 -3
- package/src/ProviderChainBroadcaster.ts +108 -0
- package/src/__tests__/OverlayExpress.test.ts +37 -3
- package/src/__tests__/OverlayMonitor.test.ts +74 -0
- package/src/__tests__/OverlayProviders.live.test.ts +39 -0
- package/src/__tests__/OverlayProviders.test.ts +123 -0
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.
|
|
3
|
+
"version": "2.4.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "BSV Blockchain Overlay Express",
|
|
6
6
|
"main": "dist/cjs/mod.js",
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"@types/body-parser": "^1.19.5",
|
|
49
49
|
"@types/express": "^5.0.0",
|
|
50
50
|
"@types/jest": "^30.0.0",
|
|
51
|
-
"@types/node": "^
|
|
51
|
+
"@types/node": "^26.0.0",
|
|
52
52
|
"jest": "^30.4.2",
|
|
53
53
|
"ts-jest": "^29.4.11",
|
|
54
54
|
"ts-standard": "^12.0.2",
|
|
@@ -58,19 +58,19 @@
|
|
|
58
58
|
"@bsv/sdk": "^2.1.3"
|
|
59
59
|
},
|
|
60
60
|
"dependencies": {
|
|
61
|
-
"@bsv/auth-express-middleware": "^2.0
|
|
62
|
-
"@bsv/overlay": "^2.0
|
|
63
|
-
"@bsv/overlay-discovery-services": "^2.0
|
|
64
|
-
"@bsv/wallet-toolbox-client": "^2.
|
|
65
|
-
"body-parser": "^2.
|
|
61
|
+
"@bsv/auth-express-middleware": "^2.1.0",
|
|
62
|
+
"@bsv/overlay": "^2.1.0",
|
|
63
|
+
"@bsv/overlay-discovery-services": "^2.1.0",
|
|
64
|
+
"@bsv/wallet-toolbox-client": "^2.3.2",
|
|
65
|
+
"body-parser": "^2.3.0",
|
|
66
66
|
"chalk": "^5.6.2",
|
|
67
67
|
"express": "^5.2.1",
|
|
68
68
|
"knex": "^3.2.10",
|
|
69
69
|
"mongodb": "^7.3.0",
|
|
70
|
-
"uuid": "^14.0.
|
|
70
|
+
"uuid": "^14.0.1"
|
|
71
71
|
},
|
|
72
72
|
"peerDependencies": {
|
|
73
|
-
"@bsv/sdk": "^2"
|
|
73
|
+
"@bsv/sdk": "^2.1.6"
|
|
74
74
|
},
|
|
75
75
|
"peerDependenciesMeta": {
|
|
76
76
|
"@bsv/sdk": {
|
|
@@ -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
|
+
}
|