@exodus/bitcoin-api 4.14.7 → 4.15.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.15.0](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.14.7...@exodus/bitcoin-api@4.15.0) (2026-05-18)
+
+
+### Features
+
+
+* feat: add init time mempool WS URL support (#8045)
+
+
+### Bug Fixes
+
+
+* fix(bitcoin-api): reduce dogecoin change dust to 1M koinu (#8080)
+
+* fix: repair stale spent UTXOs after broadcast failure (#8087)
+
+* fix: split mempool reads from clarity broadcast (#8094)
+
+
+
 ## [4.14.7](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.14.6...@exodus/bitcoin-api@4.14.7) (2026-05-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bitcoin-api",
-  "version": "4.14.7",
+  "version": "4.15.0",
   "description": "Bitcoin transaction and fee monitors, RPC with the blockchain node, other networking code.",
   "type": "module",
   "main": "src/index.js",
@@ -63,5 +63,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "241709879859db46e15f71aa02898c7d23b282b8"
+  "gitHead": "266396ec25f5aa6ce87887d0df7f0e882e83f1aa"
 }

package/src/dust.js

@@ -7,7 +7,14 @@ const CHANGE_DUST_VALUES = {
   bgold: 6000,
   litecoin: 60_000,
   dash: 5500,
-  dogecoin: 99_999_999,
+  // Dogecoin's network min-relay fee is high (~100 sat/byte), so the economic dust
+  // floor is ~55k sats for a P2PKH output. We keep a healthy margin (1 DOGE = 100M
+  // sats here is way too high — it caused legitimate sub-1-DOGE change to be folded
+  // into the fee, occasionally pushing the effective fee rate past the 200k sat/vB
+  // PSBT cap in `tx-sign/maximum-fee-rates.js` and blocking the send). 1M sats
+  // (~0.01 DOGE) keeps change outputs economically meaningful while leaving plenty
+  // of headroom below the max-fee-rate cap.
+  dogecoin: 1_000_000,
   decred: 70_000,
   digibyte: 60_000,
   zcash: 1500,

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

@@ -209,32 +209,32 @@ const normalizeTx = (tx, tipHeight, outspends) => {
 
 export default class MempoolRestClient {
   constructor({
-    baseURL,
-    insightBaseURL,
+    mempoolBaseURL,
+    clarityBaseURL,
     retryWaitTimes = RETRY_WAIT_TIMES,
     configMinFeeRate = 10,
   } = {}) {
-    this._baseURL = baseURL
-    this._insightBaseURL = insightBaseURL
+    this._mempoolBaseURL = mempoolBaseURL
+    this._clarityBaseURL = clarityBaseURL
     this._retryWaitTimes = retryWaitTimes
     this._configMinFeeRate = configMinFeeRate
   }
 
-  setBaseUrl(baseURL) {
-    this._baseURL = baseURL
+  setMempoolBaseUrl(mempoolBaseURL) {
+    this._mempoolBaseURL = mempoolBaseURL
   }
 
-  setInsightBaseUrl(baseURL) {
-    this._insightBaseURL = baseURL
+  setClarityBaseUrl(clarityBaseURL) {
+    this._clarityBaseURL = clarityBaseURL
   }
 
-  _apiUrl(path, { version } = {}) {
-    return urlJoin(this._baseURL, version === 'v1' ? '/api/v1' : '/api', path)
+  _mempoolApiUrl(path, { version } = {}) {
+    return urlJoin(this._mempoolBaseURL, version === 'v1' ? '/api/v1' : '/api', path)
   }
 
   async _fetchTipHeight() {
     const tipText = await fetchText(
-      this._apiUrl('/blocks/tip/height'),
+      this._mempoolApiUrl('/blocks/tip/height'),
       { timeout: 10_000 },
       { httpErrorMessage: MEMPOOL_HTTP_ERROR_STATUS_MESSAGE }
     )
@@ -248,10 +248,14 @@ export default class MempoolRestClient {
 
   async _fetchTxOutspends(txid) {
     const encodedTxid = encodeURIComponent(txid)
-    const outspends = await fetchJson(this._apiUrl(`/tx/${encodedTxid}/outspends`), undefined, {
-      nullWhen404: true,
-      httpErrorMessage: MEMPOOL_HTTP_ERROR_OUTSPENDS_MESSAGE,
-    })
+    const outspends = await fetchJson(
+      this._mempoolApiUrl(`/tx/${encodedTxid}/outspends`),
+      undefined,
+      {
+        nullWhen404: true,
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_OUTSPENDS_MESSAGE,
+      }
+    )
     return Array.isArray(outspends) ? outspends : []
   }
 
@@ -260,7 +264,7 @@ export default class MempoolRestClient {
     const result = await withRetry(
       fetchJson,
       [
-        this._apiUrl(`/txs/outspends?${query}`),
+        this._mempoolApiUrl(`/txs/outspends?${query}`),
         undefined,
         { nullWhen404: true, httpErrorMessage: MEMPOOL_HTTP_ERROR_OUTSPENDS_MESSAGE },
       ],
@@ -290,7 +294,7 @@ export default class MempoolRestClient {
 
   async _fetchPrevouts(outpoints) {
     return fetchJson(
-      this._apiUrl('/prevouts', { version: 'v1' }),
+      this._mempoolApiUrl('/prevouts', { version: 'v1' }),
       {
         method: 'post',
         headers: {
@@ -320,7 +324,7 @@ export default class MempoolRestClient {
     const page = await withRetry(
       fetchJson,
       [
-        this._apiUrl(path),
+        this._mempoolApiUrl(path),
         {
           method: 'post',
           headers: {
@@ -343,9 +347,13 @@ export default class MempoolRestClient {
 
   async fetchBalance(address) {
     const encodedAddress = encodeURIComponent(address)
-    const utxos = await fetchJson(this._apiUrl(`/address/${encodedAddress}/utxo`), undefined, {
-      httpErrorMessage: MEMPOOL_HTTP_ERROR_BALANCE_MESSAGE,
-    })
+    const utxos = await fetchJson(
+      this._mempoolApiUrl(`/address/${encodedAddress}/utxo`),
+      undefined,
+      {
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_BALANCE_MESSAGE,
+      }
+    )
     const values = Array.isArray(utxos) ? utxos : []
     const totalSats = values.reduce((sum, utxo) => sum + Number(utxo?.value || 0), 0)
     return {
@@ -361,7 +369,7 @@ export default class MempoolRestClient {
   async fetchTx(txid) {
     const tipHeightPromise = this._fetchTipHeight()
     const encodedTxid = encodeURIComponent(txid)
-    const tx = await fetchJson(this._apiUrl(`/tx/${encodedTxid}`), undefined, {
+    const tx = await fetchJson(this._mempoolApiUrl(`/tx/${encodedTxid}`), undefined, {
       nullWhen404: true,
       httpErrorMessage: MEMPOOL_HTTP_ERROR_TX_MESSAGE,
     })
@@ -380,7 +388,7 @@ export default class MempoolRestClient {
 
   async fetchRawTx(txid) {
     const encodedTxid = encodeURIComponent(txid)
-    const rawTx = await fetchText(this._apiUrl(`/tx/${encodedTxid}/hex`), undefined, {
+    const rawTx = await fetchText(this._mempoolApiUrl(`/tx/${encodedTxid}/hex`), undefined, {
       httpErrorMessage: MEMPOOL_HTTP_ERROR_RAWTX_MESSAGE,
     })
     return String(rawTx).trim()
@@ -499,9 +507,13 @@ export default class MempoolRestClient {
 
   async fetchUTXOs(address) {
     const encodedAddress = encodeURIComponent(address)
-    const utxos = await fetchJson(this._apiUrl(`/address/${encodedAddress}/utxo`), undefined, {
-      httpErrorMessage: MEMPOOL_HTTP_ERROR_UTXO_MESSAGE,
-    })
+    const utxos = await fetchJson(
+      this._mempoolApiUrl(`/address/${encodedAddress}/utxo`),
+      undefined,
+      {
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_UTXO_MESSAGE,
+      }
+    )
 
     if (!Array.isArray(utxos) || utxos.length === 0) return []
     const tipHeightPromise = this._fetchTipHeight()
@@ -536,10 +548,10 @@ export default class MempoolRestClient {
 
   async fetchFeeRate() {
     const [mempoolFeeRate, blocks] = await Promise.all([
-      fetchJson(this._apiUrl('/fees/recommended', { version: 'v1' }), undefined, {
+      fetchJson(this._mempoolApiUrl('/fees/recommended', { version: 'v1' }), undefined, {
         httpErrorMessage: MEMPOOL_HTTP_ERROR_FEES_MESSAGE,
       }),
-      fetchJson(this._apiUrl('/fees/mempool-blocks', { version: 'v1' }), undefined, {
+      fetchJson(this._mempoolApiUrl('/fees/mempool-blocks', { version: 'v1' }), undefined, {
         httpErrorMessage: MEMPOOL_HTTP_ERROR_FEES_MESSAGE,
       }),
     ])
@@ -582,7 +594,7 @@ export default class MempoolRestClient {
   async fetchUnconfirmedAncestorData(txid) {
     const encodedTxid = encodeURIComponent(txid)
     const data = await fetchJson(
-      this._apiUrl(`/cpfp/${encodedTxid}`, { version: 'v1' }),
+      this._mempoolApiUrl(`/cpfp/${encodedTxid}`, { version: 'v1' }),
       undefined,
       {
         httpErrorMessage: MEMPOOL_HTTP_ERROR_CPFP_MESSAGE,
@@ -598,7 +610,7 @@ export default class MempoolRestClient {
       return sum + Math.ceil(ancestor.weight / 4)
     }, 0)
     const selfFees = isFiniteNumber(data?.fee) ? data.fee : 0
-    const tx = await fetchJson(this._apiUrl(`/tx/${encodedTxid}`), undefined, {
+    const tx = await fetchJson(this._mempoolApiUrl(`/tx/${encodedTxid}`), undefined, {
       nullWhen404: true,
       httpErrorMessage: MEMPOOL_HTTP_ERROR_TX_MESSAGE,
     })
@@ -616,7 +628,7 @@ export default class MempoolRestClient {
   // is temporary. The mempool REST API alone is not a drop-in replacement for that.
   async broadcastTx(rawTx) {
     const payload = rawTx instanceof Uint8Array ? Buffer.from(rawTx).toString('hex') : rawTx
-    const response = await fetch(urlJoin(this._insightBaseURL, '/tx/send'), {
+    const response = await fetch(urlJoin(this._clarityBaseURL, '/tx/send'), {
       method: 'post',
       headers: {
         Accept: 'application/json',

package/src/insight-api-client/util.js

@@ -118,9 +118,10 @@ export function toMempoolWebSocketUrl(apiUrl) {
 export function normalizeInsightConfig(config, monitorType) {
   const apiUrl = config?.insightServers?.[0]
   const mempoolApiUrl = config?.mempoolServer
+  const clarityApiUrl = config?.clarityServer
   const wsUrl =
     monitorType === 'mempool'
       ? config?.mempoolServerWS || toMempoolWebSocketUrl(mempoolApiUrl)
       : config?.insightServersWS?.[0] || toWSUrl(apiUrl)
-  return { apiUrl, mempoolApiUrl, wsUrl }
+  return { apiUrl, mempoolApiUrl, clarityApiUrl, wsUrl }
 }

package/src/tx-log/bitcoin-monitor-scanner.js

@@ -252,6 +252,11 @@ export class BitcoinMonitorScanner {
       }
     })
 
+    // Scan each receive/change chain from the known unused index plus the gap limit.
+    // Example: if purpose 84 has chain [3, 2] and gapLimit is 5, first scan
+    // receive indexes 0..8 and change indexes 0..7. If a tx pays receive index 6,
+    // newChains moves receive to 7. The second loop then scans receive 8..12
+    // and change 7..7. This keeps expanding until the fetched address batch has no txs.
     let allTxs = []
     for (let fetchCount = 0; ; fetchCount++) {
       const chainObjects = gapSearchParameters.flatMap(
@@ -591,8 +596,11 @@ export class BitcoinMonitorScanner {
     let utxoCol = UtxoCollection.fromArray(utxos, { currency })
 
     const utxosToRemoveCol = UtxoCollection.fromArray(utxosToRemove, { currency })
-    // Keep new utxos when they intersect with the stored utxos.
-    utxoCol = utxoCol.union(storedUtxos).difference(utxosToRemoveCol)
+    const spentStoredUtxos = storedUtxos.filter((utxo) => vinTxids[`${utxo.txId}-${utxo.vout}`])
+    // utxosToRemove only contains inputs we matched to our wallet addresses or outputs we exclude.
+    // spentStoredUtxos prevents stale stored UTXOs from surviving when their outpoint was spent,
+    // but vin.addr did not match our wallet address map.
+    utxoCol = utxoCol.union(storedUtxos).difference(utxosToRemoveCol).difference(spentStoredUtxos)
 
     const pendingDropCandidates = Object.values(unconfirmedTxsToCheck)
     const verificationResults = await Promise.all(

package/src/tx-log/bitcoin-monitor.js

@@ -26,6 +26,7 @@ export class Monitor extends BaseMonitor {
   #ws
   #apiUrl
   #mempoolApiUrl
+  #mempoolWsUrl
   #monitorType
   #maxTrackedAddresses
   #wsUrl
@@ -45,6 +46,7 @@ export class Monitor extends BaseMonitor {
     insightClient,
     apiUrl,
     mempoolApiUrl,
+    mempoolWsUrl,
     monitorType,
     maxTrackedAddresses,
     scanner,
@@ -53,12 +55,12 @@ export class Monitor extends BaseMonitor {
   }) {
     super({ asset, interval, assetClientInterface, logger, runner })
     assert(insightClient, 'insightClient is required!')
-    assert(apiUrl, 'apiUrl is required')
     assert(typeof yieldToUI === 'function', 'yieldToUI must be a function')
     this.#wsInterval = wsInterval
     this.#ws = null
     this.#apiUrl = apiUrl
     this.#mempoolApiUrl = mempoolApiUrl
+    this.#mempoolWsUrl = mempoolWsUrl
     this.#monitorType = monitorType
     this.#maxTrackedAddresses = maxTrackedAddresses
     this.#yieldToUI = yieldToUI
@@ -89,15 +91,20 @@ export class Monitor extends BaseMonitor {
   }
 
   setServer(assetConfig = {}) {
-    const { apiUrl, mempoolApiUrl, wsUrl } = normalizeInsightConfig(assetConfig, this.#monitorType)
+    const { apiUrl, mempoolApiUrl, clarityApiUrl, wsUrl } = normalizeInsightConfig(
+      assetConfig,
+      this.#monitorType
+    )
 
     if (this.#monitorType === 'mempool') {
+      const clarityBaseUrl = clarityApiUrl || apiUrl
+
       if (mempoolApiUrl) {
-        this.#insightClient.setBaseUrl(mempoolApiUrl)
+        this.#insightClient.setMempoolBaseUrl(mempoolApiUrl)
       }
 
-      if (apiUrl) {
-        this.#insightClient.setInsightBaseUrl(apiUrl)
+      if (clarityBaseUrl) {
+        this.#insightClient.setClarityBaseUrl(clarityBaseUrl)
       }
     } else if (apiUrl) {
       this.#insightClient.setBaseUrl(apiUrl)
@@ -108,7 +115,7 @@ export class Monitor extends BaseMonitor {
         wsUrl ||
           this.#wsUrl ||
           (this.#monitorType === 'mempool'
-            ? toMempoolWebSocketUrl(this.#mempoolApiUrl)
+            ? this.#mempoolWsUrl || toMempoolWebSocketUrl(this.#mempoolApiUrl)
             : toWSUrl(this.#apiUrl))
       )
     }

package/src/tx-send/index.js

@@ -4,6 +4,7 @@ import assert from 'minimalistic-assert'
 
 import { extractTransactionContext } from '../psbt-parser.js'
 import { broadcastTransaction } from './broadcast-tx.js'
+import { repairConfirmedSpentInputs } from './repair-spent-inputs.js'
 import { updateAccountState, updateTransactionLog } from './update-state.js'
 
 const getErrorText = (error) => [error?.message, error?.reason].filter(Boolean).join(' ')
@@ -215,9 +216,27 @@ export const sendTxFactory = ({
         console.warn(`tx-send: ${assetName} tx already broadcast`, txId)
       } else {
         if (/(missing inputs|missingorspent)/i.test(getErrorText(err))) {
+          let prunedUtxos
+          try {
+            // Self-custody wallets can end up with phantom UTXOs after missed scans,
+            // restores, external spends, or backend gaps. If broadcast proves a selected
+            // input is already spent, repair local state, but only after confirming the
+            // spending tx so the same stale UTXO is not selected again.
+            prunedUtxos = await repairConfirmedSpentInputs({
+              asset,
+              assetClientInterface,
+              assetName,
+              walletAccount,
+              selectedUtxos,
+            })
+          } catch {
+            // Keep the original broadcast error. Repair is best-effort.
+          }
+
           err.txInfo = JSON.stringify({
             amount: sendAmount.toDefaultString({ unit: true }),
             fee: ((fee && fee.toDefaultString({ unit: true })) || 0).toString(),
+            prunedUtxos: prunedUtxos?.toJSON(),
             allUtxos: usableUtxos.toJSON(),
           })
         }
@@ -245,7 +264,6 @@ export const sendTxFactory = ({
       txId,
       changeUtxoIndex,
       script,
-      usableUtxos,
       selectedUtxos,
       replaceTx,
       changeAmount,

package/src/tx-send/repair-spent-inputs.js

@@ -0,0 +1,99 @@
+import { UtxoCollection } from '@exodus/models'
+
+import { getUtxos } from '../utxos-utils.js'
+
+const MIN_SPENT_INPUT_CONFIRMATIONS = 6
+const REPAIR_SPENT_INPUTS_ASSETS = new Set(['bitcoin', 'bitcointestnet', 'bitcoinregtest'])
+
+const getOutputByVout = ({ tx, vout }) => {
+  if (!Array.isArray(tx?.vout)) return
+
+  return tx.vout.find((output) => output.n === vout)
+}
+
+const fetchTxObjectsById = async ({ insightClient, txIds }) => {
+  const txEntries = await Promise.all(
+    [...txIds].map(async (txId) => {
+      try {
+        return [txId, (await insightClient.fetchTxObject(txId)) || null]
+      } catch {
+        return [txId, null]
+      }
+    })
+  )
+
+  return new Map(txEntries)
+}
+
+export async function getConfirmedSpentSelectedUtxos({
+  asset,
+  selectedUtxos,
+  minConfirmations = MIN_SPENT_INPUT_CONFIRMATIONS,
+}) {
+  const insightClient = asset.insightClient
+  if (
+    !REPAIR_SPENT_INPUTS_ASSETS.has(asset.name) ||
+    typeof insightClient.fetchTxObject !== 'function' ||
+    selectedUtxos.size === 0
+  ) {
+    return UtxoCollection.createEmpty({ currency: asset.currency })
+  }
+
+  const selectedUtxosArray = selectedUtxos.toArray()
+
+  const parentTxsById = await fetchTxObjectsById({
+    insightClient,
+    txIds: new Set(selectedUtxosArray.map((utxo) => utxo.txId)),
+  })
+
+  const selectedUtxosWithSpentTxIds = selectedUtxosArray
+    .map((utxo) => {
+      const output = getOutputByVout({ tx: parentTxsById.get(utxo.txId), vout: utxo.vout })
+      return { utxo, spentTxId: output?.spentTxId }
+    })
+    .filter(({ spentTxId }) => spentTxId)
+
+  const spendingTxsById = await fetchTxObjectsById({
+    insightClient,
+    txIds: new Set(selectedUtxosWithSpentTxIds.map(({ spentTxId }) => spentTxId)),
+  })
+
+  const spentUtxos = selectedUtxosWithSpentTxIds
+    .filter(
+      ({ spentTxId }) => (spendingTxsById.get(spentTxId)?.confirmations || 0) >= minConfirmations
+    )
+    .map(({ utxo }) => utxo)
+
+  return UtxoCollection.fromArray(spentUtxos, { currency: asset.currency })
+}
+
+export async function repairConfirmedSpentInputs({
+  asset,
+  assetClientInterface,
+  assetName,
+  walletAccount,
+  selectedUtxos,
+}) {
+  const spentSelectedUtxos = await getConfirmedSpentSelectedUtxos({ asset, selectedUtxos })
+
+  if (spentSelectedUtxos.size === 0) return spentSelectedUtxos
+
+  const accountState = await assetClientInterface.getAccountState({ assetName, walletAccount })
+
+  const spentUtxoIds = new Set(
+    spentSelectedUtxos.toArray().map((utxo) => `${utxo.txId}:${utxo.vout}`.toLowerCase())
+  )
+
+  await assetClientInterface.updateAccountState({
+    assetName,
+    walletAccount,
+    newData: {
+      utxos: getUtxos({ accountState, asset }).difference(spentSelectedUtxos),
+      knownBalanceUtxoIds: accountState.knownBalanceUtxoIds?.filter(
+        (id) => !spentUtxoIds.has(id.toLowerCase())
+      ),
+    },
+  })
+
+  return spentSelectedUtxos
+}

package/src/tx-send/update-state.js

@@ -113,16 +113,16 @@ export async function updateAccountState({
   txId,
   changeUtxoIndex,
   script,
-  usableUtxos,
   selectedUtxos,
   replaceTx,
   changeAmount,
   ourAddress,
   rbfEnabled,
 }) {
-  // Update remaining UTXOs
   const knownBalanceUtxoIds = accountState.knownBalanceUtxoIds || []
-  let remainingUtxos = usableUtxos.difference(selectedUtxos)
+  // updateAccountState replaces the stored UTXO collection, so remove selected inputs
+  // from the full stored set.
+  let remainingUtxos = accountState.utxos.difference(selectedUtxos)
 
   // Add change UTXO if present
   if (changeUtxoIndex !== -1 && ourAddress) {