@exodus/bitcoin-api 4.11.1 → 4.12.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.12.0](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.11.1...@exodus/bitcoin-api@4.12.0) (2026-03-20)
+
+
+### Features
+
+
+* feat(bitcoin-api): add mempool ws client with insight parity (#7625)
+
+
+
 ## [4.11.1](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.11.0...@exodus/bitcoin-api@4.11.1) (2026-03-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bitcoin-api",
-  "version": "4.11.1",
+  "version": "4.12.0",
   "description": "Bitcoin transaction and fee monitors, RPC with the blockchain node, other networking code.",
   "type": "module",
   "main": "src/index.js",
@@ -41,6 +41,7 @@
     "bip32-path": "^0.4.2",
     "bs58check": "^3.0.1",
     "delay": "^4.0.1",
+    "eventemitter3": "^5.0.4",
     "events": "^3.3.0",
     "lodash": "^4.17.21",
     "minimalistic-assert": "^1.0.1",
@@ -62,5 +63,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "2933d00c85191b547e822a292f1884b8d6d9e6d7"
+  "gitHead": "f1f7c3ad9d55f774c9c6a09434139d46f605e43c"
 }

package/src/index.js

@@ -3,6 +3,7 @@ export * from './balances.js'
 export * from './btc-address.js'
 export * from './btc-like-address.js'
 export * from './btc-like-keys.js'
+export { default as MempoolWSClient } from './insight-api-client/mempool-ws-client.js'
 export { default as InsightAPIClient } from './insight-api-client/index.js'
 export { default as InsightWSClient } from './insight-api-client/ws.js'
 export { default as bip44Constants } from './constants/bip44.js'

package/src/insight-api-client/mempool-ws-client.js

@@ -0,0 +1,239 @@
+import EventEmitter from 'eventemitter3'
+
+const DEFAULT_RECONNECTION_DELAY = 10_000
+const DEFAULT_RECONNECTION_DELAY_MAX = 30_000
+const DEFAULT_PING_INTERVAL = 25_000
+const BLOCK_SUBSCRIBED_ASSETS = new Set(['bitcoin', 'bitcoinregtest', 'bitcointestnet'])
+
+const toMessageString = (data) => {
+  if (typeof data === 'string') return data
+  // Keep tiny compatibility for ws-style Buffer payloads.
+  if (data && typeof data.toString === 'function') return data.toString('utf8')
+
+  return ''
+}
+
+const flattenAddressEntries = (data) => {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return []
+  return Object.entries(data).filter(([address, payload]) => typeof address === 'string' && payload)
+}
+
+const tryParseJSON = (rawData) => {
+  const message = toMessageString(rawData)
+  if (!message) return null
+
+  try {
+    return JSON.parse(message)
+  } catch (error) {
+    console.warn('mempool-ws-client parse failed', {
+      error: error instanceof Error ? error.message : error,
+      preview: message.slice(0, 200),
+    })
+    return null
+  }
+}
+
+const getReconnectDelay = (attempt, reconnectionDelay, reconnectionDelayMax) => {
+  const baseDelay = reconnectionDelay * 2 ** Math.max(0, attempt)
+  const cappedDelay = Math.min(baseDelay, reconnectionDelayMax)
+  const jitter = 0.8 + Math.random() * 0.4
+  return Math.round(cappedDelay * jitter)
+}
+
+const normalizeOptions = (assetName, opts = {}) => {
+  return {
+    reconnectionDelay: DEFAULT_RECONNECTION_DELAY,
+    reconnectionDelayMax: DEFAULT_RECONNECTION_DELAY_MAX,
+    pingIntervalMs: DEFAULT_PING_INTERVAL,
+    subscribeBlocks: BLOCK_SUBSCRIBED_ASSETS.has(assetName),
+    ...opts,
+  }
+}
+
+export default class MempoolWSClient extends EventEmitter {
+  constructor(url, assetName, { WebSocketClass = globalThis.WebSocket } = {}) {
+    super()
+    this.url = url
+    this.assetName = assetName
+    this.WebSocketClass = WebSocketClass
+    this.socket = null
+    this.addresses = []
+    this.options = null
+    this.reconnectAttempt = 0
+    this.reconnectTimer = null
+    this.pingInterval = null
+    this.closed = false
+    this.socketListeners = null
+    this.connected = false
+  }
+
+  connect(addresses = [], opts = {}) {
+    // Guard against accidental duplicate connect() calls creating parallel sockets.
+    if (this.socket || this.reconnectTimer) {
+      this.close()
+    }
+
+    this.addresses = [...new Set(addresses.filter((address) => typeof address === 'string'))]
+    this.options = normalizeOptions(this.assetName, opts)
+    this.closed = false
+    this.reconnectAttempt = 0
+    this.#clearReconnectTimer()
+    this.#openSocket({ isReconnect: false })
+  }
+
+  #openSocket({ isReconnect }) {
+    if (this.closed) return
+
+    const socket = new this.WebSocketClass(this.url)
+    this.socket = socket
+
+    const onOpen = () => {
+      if (this.socket !== socket || this.closed) return
+
+      this.connected = true
+      this.reconnectAttempt = 0
+      this.emit('connect')
+      if (isReconnect) this.emit('reconnect')
+      this.#subscribe(socket)
+      this.#startPing()
+    }
+
+    const onMessage = (event) => {
+      if (this.socket !== socket || this.closed) return
+      this.#handleMessage(event?.data)
+    }
+
+    const onError = (event) => {
+      // Some runtimes can stall without close; explicitly close to trigger reconnect flow.
+      if (this.socket !== socket || this.closed) return
+      console.warn('mempool-ws-client socket error', event)
+      try {
+        socket.close()
+      } catch {}
+    }
+
+    const onClose = () => {
+      if (this.socket !== socket) return
+      const wasConnected = this.connected
+      this.connected = false
+      this.#clearPing()
+      if (wasConnected) this.emit('disconnect')
+      this.socket = null
+      this.socketListeners = null
+      this.#scheduleReconnect()
+    }
+
+    socket.addEventListener('open', onOpen)
+    socket.addEventListener('message', onMessage)
+    socket.addEventListener('error', onError)
+    socket.addEventListener('close', onClose)
+    this.socketListeners = { onOpen, onMessage, onError, onClose }
+  }
+
+  #scheduleReconnect() {
+    if (this.closed || this.reconnectTimer) return
+
+    const reconnectDelay = getReconnectDelay(
+      this.reconnectAttempt,
+      this.options?.reconnectionDelay ?? DEFAULT_RECONNECTION_DELAY,
+      this.options?.reconnectionDelayMax ?? DEFAULT_RECONNECTION_DELAY_MAX
+    )
+    this.reconnectAttempt += 1
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.#openSocket({ isReconnect: true })
+    }, reconnectDelay)
+  }
+
+  #clearReconnectTimer() {
+    if (!this.reconnectTimer) return
+    clearTimeout(this.reconnectTimer)
+    this.reconnectTimer = null
+  }
+
+  #startPing() {
+    this.#clearPing()
+    const intervalMs = this.options?.pingIntervalMs
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) return
+
+    this.pingInterval = setInterval(() => {
+      if (!this.socket || this.socket.readyState !== (this.WebSocketClass?.OPEN ?? 1)) return
+      this.#send(this.socket, { action: 'ping' })
+    }, intervalMs)
+  }
+
+  #clearPing() {
+    if (!this.pingInterval) return
+    clearInterval(this.pingInterval)
+    this.pingInterval = null
+  }
+
+  #send(socket, payload) {
+    if (!socket || socket.readyState !== (this.WebSocketClass?.OPEN ?? 1)) return
+
+    try {
+      socket.send(JSON.stringify(payload))
+    } catch (error) {
+      console.warn('mempool-ws-client send failed', {
+        payload,
+        error: error instanceof Error ? error.message : error,
+      })
+    }
+  }
+
+  #subscribe(socket) {
+    if (this.addresses.length > 0) {
+      this.#send(socket, { 'track-addresses': this.addresses })
+    }
+
+    if (this.options?.subscribeBlocks) {
+      this.#send(socket, { action: 'want', data: ['blocks'] })
+    }
+  }
+
+  #emitMessage(data, address) {
+    this.emit('message', {
+      address,
+      data,
+    })
+  }
+
+  #handleMessage(rawData) {
+    const payload = tryParseJSON(rawData)
+    if (!payload || typeof payload !== 'object') return
+
+    if (payload.block) {
+      this.emit('block', payload.block)
+    }
+
+    if (payload['multi-address-transactions']) {
+      const entries = flattenAddressEntries(payload['multi-address-transactions'])
+      entries.forEach(([address, addressPayload]) => {
+        this.#emitMessage(addressPayload, address)
+      })
+    }
+  }
+
+  close() {
+    this.closed = true
+    const wasConnected = this.connected
+    this.connected = false
+    this.#clearReconnectTimer()
+    this.#clearPing()
+
+    if (!this.socket) return
+    const socket = this.socket
+    this.socket = null
+    const listeners = this.socketListeners
+    this.socketListeners = null
+    if (listeners) {
+      socket.removeEventListener('open', listeners.onOpen)
+      socket.removeEventListener('message', listeners.onMessage)
+      socket.removeEventListener('close', listeners.onClose)
+      socket.removeEventListener('error', listeners.onError)
+    }
+
+    socket.close()
+    if (wasConnected) this.emit('disconnect')
+  }
+}