@exodus/bitcoin-api 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.4.0](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.2.1...@exodus/bitcoin-api@4.4.0) (2025-11-12)
+
+
+### Features
+
+
+* feat: add PSBT builder infrastructure (#6822)
+
+* feat: add PSBT parser functionality (#6823)
+
+
+
 ## [4.3.0](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.2.1...@exodus/bitcoin-api@4.3.0) (2025-11-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bitcoin-api",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Bitcoin transaction and fee monitors, RPC with the blockchain node, other networking code.",
   "type": "module",
   "main": "src/index.js",
@@ -60,5 +60,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "7a2a429c2a182a889e550761d9106da3296815ca"
+  "gitHead": "5bc77cf38ec6fbd32d9e286d5bda25ea7366854d"
 }

package/src/psbt-parser.js

@@ -0,0 +1,502 @@
+import { Psbt, Transaction } from '@exodus/bitcoinjs'
+import { publicKeyToX } from '@exodus/crypto/secp256k1'
+import { UtxoCollection } from '@exodus/models'
+import BipPath from 'bip32-path'
+import assert from 'minimalistic-assert'
+
+import { readPsbtGlobalField, readPsbtOutputField, SubType } from './psbt-proprietary-types.js'
+import { getAddressType, getPurposeXPubs, validatePurpose } from './psbt-utils.js'
+import { createInputs, createOutput } from './tx-create/tx-create-utils.js'
+import { findUnconfirmedSentRbfTxs } from './tx-utils.js'
+import { getUnconfirmedTxAncestorMap } from './unconfirmed-ancestor-data.js'
+import { getUsableUtxos, getUtxos } from './utxos-utils.js'
+
+function extractInputUtxoData(psbtInput, txInput, index) {
+  if (psbtInput.nonWitnessUtxo) {
+    const prevTx = Transaction.fromBuffer(psbtInput.nonWitnessUtxo)
+    const prevOutput = prevTx.outs[txInput.index]
+
+    return {
+      scriptBuffer: prevOutput.script,
+      value: prevOutput.value,
+      prevTxHex: prevTx.toHex(),
+      prevTxId: prevTx.getId(),
+    }
+  }
+
+  if (psbtInput.witnessUtxo) {
+    return {
+      scriptBuffer: psbtInput.witnessUtxo.script,
+      value: psbtInput.witnessUtxo.value,
+    }
+  }
+
+  throw new Error(`Input ${index} has no witnessUtxo or nonWitnessUtxo`)
+}
+
+function parseSingleInput({ txInput, psbtInput, index, asset, purposeXPubs, allowedPurposes }) {
+  const input = {
+    txId: Buffer.from(txInput.hash).reverse().toString('hex'),
+    vout: txInput.index,
+    sequence: txInput.sequence,
+  }
+
+  const inputUtxoData = extractInputUtxoData(psbtInput, txInput, index)
+
+  input.value = inputUtxoData.value
+  input.script = Buffer.from(inputUtxoData.scriptBuffer).toString('hex')
+
+  if (inputUtxoData.prevTxHex) {
+    input.prevTxHex = inputUtxoData.prevTxHex
+    input.prevTxId = inputUtxoData.prevTxId
+  }
+
+  const address = asset.address.fromScriptPubKey(inputUtxoData.scriptBuffer)
+  const purpose = asset.address.resolvePurpose(address)
+  validatePurpose(purpose, allowedPurposes, `input ${index}`)
+
+  const { isTaprootAddress } = getAddressType(purpose)
+
+  if (!isTaprootAddress && !psbtInput.nonWitnessUtxo) {
+    input.missingNonWitnessUtxo = true
+  }
+
+  const derivation = getBip32Derivation(
+    purposeXPubs[purpose].hdkey,
+    isTaprootAddress ? psbtInput.tapBip32Derivation : psbtInput.bip32Derivation,
+    isTaprootAddress
+  )
+
+  if (!derivation) {
+    throw new Error(`Input ${index} has no derivation path`)
+  }
+
+  input.address = { address, meta: { path: derivation.path, purpose } }
+  return input
+}
+
+function parseSingleOutput({
+  txOutput,
+  psbtOutput,
+  index,
+  asset,
+  purposeXPubs,
+  psbt,
+  allowedPurposes,
+}) {
+  const address = txOutput.address ?? asset.address.fromScriptPubKey(txOutput.script)
+  const output = { amount: txOutput.value }
+
+  const outputMetadata = readPsbtOutputField(psbt, index)
+  if (outputMetadata) {
+    output.metadata = outputMetadata
+  }
+
+  const purpose = asset.address.resolvePurpose(address)
+  try {
+    validatePurpose(purpose, allowedPurposes)
+  } catch {
+    output.address = { address }
+    return output
+  }
+
+  const { isTaprootAddress } = getAddressType(purpose)
+
+  const derivation = getBip32Derivation(
+    purposeXPubs[purpose].hdkey,
+    isTaprootAddress ? psbtOutput.tapBip32Derivation : psbtOutput.bip32Derivation,
+    isTaprootAddress
+  )
+
+  output.address = derivation
+    ? { address, meta: { path: derivation.path, purpose } }
+    : { address, meta: { purpose } }
+
+  return output
+}
+
+function readGlobalMetadata(psbt) {
+  return {
+    blockHeight: readPsbtGlobalField(psbt, SubType.BlockHeight),
+    rbfEnabled: readPsbtGlobalField(psbt, SubType.RbfEnabled),
+    bumpTxId: readPsbtGlobalField(psbt, SubType.BumpTxId),
+    txType: readPsbtGlobalField(psbt, SubType.TxType),
+  }
+}
+
+function calculateFee(inputs, outputs) {
+  const inputSum = inputs.reduce((sum, input) => sum + (input.value || 0), 0)
+  const outputSum = outputs.reduce((sum, output) => sum + (output.amount || 0), 0)
+  return inputSum - outputSum
+}
+
+function getBip32Derivation(hdkey, bip32Derivations, ignoreY) {
+  const fingerprintBuffer = Buffer.alloc(4)
+  fingerprintBuffer.writeUInt32BE(hdkey.fingerprint, 0)
+
+  const matchingDerivations = bip32Derivations?.filter((bipDv) => {
+    return bipDv.masterFingerprint.equals(fingerprintBuffer)
+  })
+
+  if (!matchingDerivations?.length) {
+    // No derivation matched our fingerprint; the output isn’t ours.
+    return null
+  }
+
+  if (matchingDerivations.length !== 1) {
+    // Multiple matches imply the input/output carries several keys from the same wallet xpub.
+    // That’s outside our wallet model, so we fail fast.
+    throw new Error(
+      `more than one matching derivation for fingerprint ${fingerprintBuffer.toString('hex')}: ${
+        matchingDerivations.length
+      }`
+    )
+  }
+
+  const [derivation] = matchingDerivations
+  const publicKey = hdkey.derive(derivation.path).publicKey
+
+  const publicKeyToCompare = ignoreY ? publicKeyToX({ publicKey, format: 'buffer' }) : publicKey
+
+  if (publicKeyToCompare.equals(derivation.pubkey)) {
+    return derivation
+  }
+
+  throw new Error('pubkey did not match bip32Derivation')
+}
+
+function getSelectedUtxos({ parsedInputs, utxos, asset, txSet }) {
+  const utxoId = (txId, vout) => txId + ':' + vout
+  const utxosArray = Array.isArray(utxos) ? utxos : utxos.toArray()
+  const utxosMap = new Map(utxosArray.map((u) => [utxoId(u.txId, u.vout), u]))
+
+  const inputIds = new Set(parsedInputs.map((inp) => utxoId(inp.txId, inp.vout)))
+  let detectedReplaceTx = null
+
+  const replaceableTxs = findUnconfirmedSentRbfTxs(txSet)
+  for (const replaceableTx of replaceableTxs) {
+    if (replaceableTx.data?.inputs) {
+      const txInputs = UtxoCollection.fromJSON(replaceableTx.data.inputs, {
+        currency: asset.currency,
+      })
+
+      const txInputsArray = txInputs.toArray()
+
+      const txInputIds = txInputsArray.map((u) => utxoId(u.txId, u.vout))
+      const isReplacement = txInputIds.some((id) => inputIds.has(id))
+
+      if (isReplacement) {
+        detectedReplaceTx = replaceableTx
+
+        for (const utxo of txInputsArray) {
+          const id = utxoId(utxo.txId, utxo.vout)
+          if (!utxosMap.has(id)) {
+            utxosMap.set(id, utxo)
+          }
+        }
+
+        // Exodus only handles a single replaceable transaction at a time, so bail once we’ve tagged one.
+        break
+      }
+    }
+  }
+
+  const inputUtxos = []
+  const missingInputIds = []
+
+  for (const parsedInput of parsedInputs) {
+    const id = utxoId(parsedInput.txId, parsedInput.vout)
+    const ourUtxo = utxosMap.get(id)
+
+    if (ourUtxo) {
+      inputUtxos.push(ourUtxo)
+    } else {
+      missingInputIds.push(id)
+    }
+  }
+
+  return {
+    selectedUtxos: UtxoCollection.fromArray(inputUtxos, { currency: asset.currency }),
+    replaceTx: detectedReplaceTx,
+    missingInputIds,
+  }
+}
+
+async function getChangeOutputData({ outputs, assetClientInterface, walletAccount, asset }) {
+  let changeOutputData = null
+  for (const [i, output] of outputs.entries()) {
+    // Outputs marked “primary” are treated as sends even if they use one of our paths
+    // (common for self‑sends, consolidations, etc.), so skip them during change detection.
+    if (output.metadata?.outputRole === 'primary') {
+      continue
+    }
+
+    // We only treat addresses we can re-derive from the wallet xpub as potential
+    // change outputs.
+    if (!output.address?.meta?.path) {
+      continue
+    }
+
+    // At this point we already know the output was derived by our wallet and it is
+    // not explicitly flagged as a primary/send output, so we tentatively treat it as
+    // change and confirm by re-deriving the on-chain address.
+    if (changeOutputData) {
+      // Multiple change outputs are a smell. This can happen if an external PSBT
+      // marks a send output of the same wallet with its derivation path, so we fail fast instead of
+      // silently mislabelling funds.
+      throw new Error('Multiple change outputs are not allowed')
+    }
+
+    const { path, purpose } = output.address.meta
+    const [chainIndex, addressIndex] = BipPath.fromString(path).toPathArray()
+
+    const verifyAddr = await assetClientInterface.getAddress({
+      assetName: asset.name,
+      walletAccount: walletAccount.toString(),
+      purpose,
+      chainIndex,
+      addressIndex,
+    })
+
+    if (verifyAddr.toString() === output.address.address) {
+      changeOutputData = {
+        address: verifyAddr,
+        amount: output.amount,
+        index: i,
+      }
+    } else {
+      throw new Error(`Invalid change output address ${output.address.address}`)
+    }
+  }
+
+  return changeOutputData
+}
+
+function findPrimaryOutputIndexes(outputs) {
+  return outputs
+    .map((output, index) => (output.metadata?.outputRole === 'primary' ? index : null))
+    .filter((index) => index !== null)
+}
+
+function processReplacementTransaction(replaceTx, asset) {
+  if (!replaceTx) return null
+
+  const clonedTx = replaceTx.clone()
+  const updatedTx = clonedTx.update({ data: { ...clonedTx.data } })
+
+  updatedTx.data.sent = updatedTx?.data?.sent.map((to) => ({
+    ...to,
+    amount: asset.currency.baseUnit(to.amount),
+  }))
+
+  return updatedTx
+}
+
+function calculateAmounts({ primaryOutputs, changeOutputData, processedReplaceTx, asset }) {
+  const sendAmounts = primaryOutputs.map((primaryOutput) =>
+    asset.currency.baseUnit(primaryOutput.amount)
+  )
+  const totalSendAmount = sendAmounts.reduce((sum, amount) => sum.add(amount), asset.currency.ZERO)
+
+  const changeAmount = changeOutputData
+    ? asset.currency.baseUnit(changeOutputData.amount)
+    : asset.currency.ZERO
+
+  const totalAmount = processedReplaceTx
+    ? processedReplaceTx.data.sent.reduce((total, { amount }) => total.add(amount), totalSendAmount)
+    : totalSendAmount
+
+  return { sendAmounts, totalSendAmount, changeAmount, totalAmount }
+}
+
+function buildAddressPathsMap(selectedUtxos, changeOutputData) {
+  const addressPathsMap = selectedUtxos.getAddressPathsMap()
+
+  if (changeOutputData) {
+    addressPathsMap[changeOutputData.address.address] = changeOutputData.address.meta.path
+  }
+
+  return addressPathsMap
+}
+
+function extractRawTransactions(parsedInputs) {
+  const rawTxsData = parsedInputs
+    .filter((parsedInput) => parsedInput.prevTxId)
+    .map((parsedInput) => ({
+      txId: parsedInput.prevTxId,
+      rawData: parsedInput.prevTxHex,
+    }))
+
+  const rawTxsMap = new Map(rawTxsData.map((tx) => [tx.txId, tx.rawData]))
+  return [...rawTxsMap].map(([txId, rawData]) => ({ txId, rawData }))
+}
+
+export async function parsePsbt({
+  psbtBase64,
+  asset,
+  assetClientInterface,
+  walletAccount,
+  allowedPurposes,
+}) {
+  assert(psbtBase64, 'psbtBase64 is required')
+  assert(asset, 'asset is required')
+  assert(assetClientInterface, 'assetClientInterface is required')
+  assert(walletAccount, 'walletAccount is required')
+
+  const purposeXPubs = await getPurposeXPubs({
+    assetClientInterface,
+    walletAccount,
+    asset,
+    allowedPurposes,
+  })
+
+  // TBD: change it to fromBuffer
+  const psbt = Psbt.fromBase64(psbtBase64, { network: asset.coinInfo.toBitcoinJS() })
+
+  const inputs = []
+  for (let i = 0; i < psbt.inputCount; i++) {
+    const input = parseSingleInput({
+      txInput: psbt.txInputs[i],
+      psbtInput: psbt.data.inputs[i],
+      index: i,
+      asset,
+      purposeXPubs,
+      allowedPurposes,
+    })
+    inputs.push(input)
+  }
+
+  const outputs = []
+  for (let i = 0; i < psbt.data.outputs.length; i++) {
+    const output = parseSingleOutput({
+      txOutput: psbt.txOutputs[i],
+      psbtOutput: psbt.data.outputs[i],
+      index: i,
+      asset,
+      purposeXPubs,
+      psbt,
+      allowedPurposes,
+    })
+    outputs.push(output)
+  }
+
+  const globalMetadata = readGlobalMetadata(psbt)
+  const fee = calculateFee(inputs, outputs)
+
+  return {
+    inputs,
+    outputs,
+    fee,
+    globalMetadata,
+  }
+}
+
+export async function extractTransactionContext({
+  psbtBase64,
+  asset,
+  assetClientInterface,
+  walletAccount,
+  allowedPurposes,
+}) {
+  assert(psbtBase64, 'psbtBase64 is required')
+  assert(asset, 'asset is required')
+  assert(assetClientInterface, 'assetClientInterface is required')
+  assert(walletAccount, 'walletAccount is required')
+
+  const {
+    inputs: parsedInputs,
+    outputs: parsedOutputs,
+    fee: calculatedFee,
+    globalMetadata,
+  } = await parsePsbt({
+    psbtBase64,
+    asset,
+    assetClientInterface,
+    walletAccount,
+    allowedPurposes,
+  })
+
+  const changeOutputData = await getChangeOutputData({
+    outputs: parsedOutputs,
+    assetClientInterface,
+    walletAccount,
+    asset,
+  })
+
+  const assetName = asset.name
+  const accountState = await assetClientInterface.getAccountState({
+    assetName,
+    walletAccount,
+  })
+
+  const utxos = getUtxos({ accountState, asset })
+  const txSet = await assetClientInterface.getTxLog({ assetName, walletAccount })
+
+  const { selectedUtxos, replaceTx, missingInputIds } = getSelectedUtxos({
+    parsedInputs,
+    utxos,
+    txSet,
+    asset,
+  })
+
+  if (missingInputIds.length > 0) {
+    // Missing inputs mean we no longer control some UTXOs referenced in the PSBT.
+    // Typical causes: they’ve already been spent from another device, or the RBF
+    // transaction we planned to replace has since confirmed and dropped out of the
+    // replaceable set.
+    throw new Error(`Unknown inputs: ${missingInputIds.join(', ')}`)
+  }
+
+  const processedReplaceTx = processReplacementTransaction(replaceTx, asset)
+
+  const primaryOutputIndexes = findPrimaryOutputIndexes(parsedOutputs)
+  const primaryOutputs = primaryOutputIndexes.map((v) => parsedOutputs[v])
+
+  const { sendAmounts, totalSendAmount, changeAmount, totalAmount } = calculateAmounts({
+    primaryOutputs,
+    changeOutputData,
+    processedReplaceTx,
+    asset,
+  })
+
+  const unconfirmedTxAncestor = getUnconfirmedTxAncestorMap({ accountState })
+  const feeData = await assetClientInterface.getFeeConfig({ assetName })
+  const usableUtxos = getUsableUtxos({
+    asset,
+    utxos,
+    feeData,
+    txSet,
+    unconfirmedTxAncestor,
+  })
+
+  const inputs = createInputs(assetName, selectedUtxos.toArray(), globalMetadata.rbfEnabled)
+  const outputs = parsedOutputs.map((output) =>
+    createOutput(assetName, output.address.address, asset.currency.baseUnit(output.amount))
+  )
+
+  const addressPathsMap = buildAddressPathsMap(selectedUtxos, changeOutputData)
+  const rawTxs = extractRawTransactions(parsedInputs)
+
+  return {
+    inputs,
+    outputs,
+    addressPathsMap,
+    rawTxs,
+    fee: asset.currency.baseUnit(calculatedFee),
+    sendOutputIndexes: primaryOutputIndexes,
+    changeOutputIndex: changeOutputData?.index,
+    sendAmounts,
+    changeAmount,
+    totalSendAmount,
+    totalAmount,
+    primaryAddresses: primaryOutputs.map((primaryOutput) => primaryOutput.address),
+    ourAddress: changeOutputData?.address,
+    usableUtxos,
+    selectedUtxos,
+    replaceTx: processedReplaceTx,
+    sendOutputs: primaryOutputIndexes.map((primaryOutputIndex) => outputs[primaryOutputIndex]),
+    changeOutput: changeOutputData ? outputs[changeOutputData.index] : undefined,
+    rbfEnabled: globalMetadata.rbfEnabled,
+    blockHeight: globalMetadata.blockHeight,
+  }
+}