@exodus/bitcoin-api 4.4.0 → 4.5.0

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bitcoin-api",
-  "version": "4.4.0",
+  "version": "4.5.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": "5bc77cf38ec6fbd32d9e286d5bda25ea7366854d"
+  "gitHead": "482aa1dda8d9273c4f1a477ffcef2310f1df9884"
 }

package/src/psbt-builder.js

@@ -70,14 +70,7 @@ function writeGlobalMetadata(psbt, metadata) {
   }
 }
 
-function createPsbtInput({
-  input,
-  asset,
-  addressPathsMap,
-  purposeXPubs,
-  nonWitnessTxs,
-  allowedPurposes,
-}) {
+function createPsbtInput({ input, asset, addressPathsMap, purposeXPubs, nonWitnessTxs }) {
   const psbtInput = {
     hash: input.txId,
     index: input.vout,
@@ -85,7 +78,7 @@ function createPsbtInput({
   }
 
   const purpose = asset.address.resolvePurpose(input.address)
-  validatePurpose(purpose, allowedPurposes, `address ${input.address}`)
+  validatePurpose(purpose, purposeXPubs, `address ${input.address}`)
 
   const { isSegwitAddress, isTaprootAddress, isWrappedSegwitAddress } = getAddressType(purpose)
 
@@ -141,14 +134,7 @@ function createPsbtInput({
   return { ...psbtInput, ...derivationData }
 }
 
-function createPsbtOutput({
-  address,
-  amount,
-  asset,
-  addressPathsMap,
-  purposeXPubs,
-  allowedPurposes,
-}) {
+function createPsbtOutput({ address, amount, asset, addressPathsMap, purposeXPubs }) {
   const psbtOutput = {
     address,
     value: amount,
@@ -160,7 +146,7 @@ function createPsbtOutput({
   }
 
   const purpose = asset.address.resolvePurpose(address)
-  validatePurpose(purpose, allowedPurposes, `output address ${address}`)
+  validatePurpose(purpose, purposeXPubs, `output address ${address}`)
 
   const { isTaprootAddress, isWrappedSegwitAddress } = getAddressType(purpose)
 
@@ -244,5 +230,5 @@ export async function createPsbtWithMetadata({
     writePsbtOutputField(psbt, sendOutputIndex, SubType.OutputRole, 'primary')
   }
 
-  return psbt.toBase64()
+  return psbt.toBuffer()
 }

package/src/psbt-parser.js

@@ -34,7 +34,7 @@ function extractInputUtxoData(psbtInput, txInput, index) {
   throw new Error(`Input ${index} has no witnessUtxo or nonWitnessUtxo`)
 }
 
-function parseSingleInput({ txInput, psbtInput, index, asset, purposeXPubs, allowedPurposes }) {
+function parseSingleInput({ txInput, psbtInput, index, asset, purposeXPubs }) {
   const input = {
     txId: Buffer.from(txInput.hash).reverse().toString('hex'),
     vout: txInput.index,
@@ -53,7 +53,7 @@ function parseSingleInput({ txInput, psbtInput, index, asset, purposeXPubs, allo
 
   const address = asset.address.fromScriptPubKey(inputUtxoData.scriptBuffer)
   const purpose = asset.address.resolvePurpose(address)
-  validatePurpose(purpose, allowedPurposes, `input ${index}`)
+  validatePurpose(purpose, purposeXPubs, `input ${index}`)
 
   const { isTaprootAddress } = getAddressType(purpose)
 
@@ -75,15 +75,7 @@ function parseSingleInput({ txInput, psbtInput, index, asset, purposeXPubs, allo
   return input
 }
 
-function parseSingleOutput({
-  txOutput,
-  psbtOutput,
-  index,
-  asset,
-  purposeXPubs,
-  psbt,
-  allowedPurposes,
-}) {
+function parseSingleOutput({ txOutput, psbtOutput, index, asset, purposeXPubs, psbt }) {
   const address = txOutput.address ?? asset.address.fromScriptPubKey(txOutput.script)
   const output = { amount: txOutput.value }
 
@@ -94,7 +86,7 @@ function parseSingleOutput({
 
   const purpose = asset.address.resolvePurpose(address)
   try {
-    validatePurpose(purpose, allowedPurposes)
+    validatePurpose(purpose, purposeXPubs)
   } catch {
     output.address = { address }
     return output
@@ -332,13 +324,13 @@ function extractRawTransactions(parsedInputs) {
 }
 
 export async function parsePsbt({
-  psbtBase64,
+  psbtBuffer,
   asset,
   assetClientInterface,
   walletAccount,
   allowedPurposes,
 }) {
-  assert(psbtBase64, 'psbtBase64 is required')
+  assert(psbtBuffer, 'psbtBuffer is required')
   assert(asset, 'asset is required')
   assert(assetClientInterface, 'assetClientInterface is required')
   assert(walletAccount, 'walletAccount is required')
@@ -350,8 +342,7 @@ export async function parsePsbt({
     allowedPurposes,
   })
 
-  // TBD: change it to fromBuffer
-  const psbt = Psbt.fromBase64(psbtBase64, { network: asset.coinInfo.toBitcoinJS() })
+  const psbt = Psbt.fromBuffer(psbtBuffer, { network: asset.coinInfo.toBitcoinJS() })
 
   const inputs = []
   for (let i = 0; i < psbt.inputCount; i++) {
@@ -392,13 +383,13 @@ export async function parsePsbt({
 }
 
 export async function extractTransactionContext({
-  psbtBase64,
+  psbtBuffer,
   asset,
   assetClientInterface,
   walletAccount,
   allowedPurposes,
 }) {
-  assert(psbtBase64, 'psbtBase64 is required')
+  assert(psbtBuffer, 'psbtBuffer is required')
   assert(asset, 'asset is required')
   assert(assetClientInterface, 'assetClientInterface is required')
   assert(walletAccount, 'walletAccount is required')
@@ -409,7 +400,7 @@ export async function extractTransactionContext({
     fee: calculatedFee,
     globalMetadata,
   } = await parsePsbt({
-    psbtBase64,
+    psbtBuffer,
     asset,
     assetClientInterface,
     walletAccount,

package/src/psbt-utils.js

@@ -29,26 +29,31 @@ export async function getPurposeXPubs({
   const purposeXPubs = Object.create(null)
 
   for (const purpose of allowedPurposes) {
-    const xpub = await assetClientInterface.getExtendedPublicKey({
-      walletAccount,
-      assetName: asset.name,
-      purpose,
-    })
-    const hdkey = BIP32.fromXPub(xpub)
-    const masterFingerprint = Buffer.alloc(4)
-    masterFingerprint.writeUint32BE(hdkey.fingerprint)
-    purposeXPubs[purpose] = {
-      hdkey,
-      masterFingerprint,
+    try {
+      const xpub = await assetClientInterface.getExtendedPublicKey({
+        walletAccount,
+        assetName: asset.name,
+        purpose,
+      })
+      const hdkey = BIP32.fromXPub(xpub)
+      const masterFingerprint = Buffer.alloc(4)
+      masterFingerprint.writeUint32BE(hdkey.fingerprint)
+      purposeXPubs[purpose] = {
+        hdkey,
+        masterFingerprint,
+      }
+    } catch {
+      // ignore any error that happened while we are getting the extended public key to handle cases where the extended public key is not available
+      // Eg. Ledger/Trezor doesn't support getting extended public keys for certain purposes
     }
   }
 
   return purposeXPubs
 }
 
-export function validatePurpose(purpose, allowedPurposes, context = '') {
-  assert(allowedPurposes, 'allowedPurposes is required')
-  if (!allowedPurposes.includes(purpose)) {
+export function validatePurpose(purpose, purposeXPubs, context = '') {
+  assert(purposeXPubs, 'purposeXPubs is required')
+  if (!purposeXPubs[purpose]) {
     throw new Error(`Purpose ${purpose} not found${context ? ' for ' + context : ''}`)
   }
 }

package/src/tx-create/create-tx.js

@@ -5,6 +5,7 @@ import assert from 'minimalistic-assert'
 import { getChangeDustValue } from '../dust.js'
 import { parseCurrency, serializeCurrency } from '../fee/fee-utils.js'
 import { selectUtxos } from '../fee/utxo-selector.js'
+import { createPsbtWithMetadata } from '../psbt-builder.js'
 import { findUnconfirmedSentRbfTxs } from '../tx-utils.js'
 import { getUnconfirmedTxAncestorMap } from '../unconfirmed-ancestor-data.js'
 import { getUsableUtxos, getUtxos } from '../utxos-utils.js'
@@ -267,10 +268,18 @@ async function createUnsignedTx({
   asset,
   selectedUtxos,
   insightClient,
+  assetClientInterface,
+  walletAccount,
+  bumpTxId,
+  rbfEnabled,
+  txType = 'transfer',
+  sendOutputIndex,
+  changeOutputIndex,
+  allowedPurposes,
 }) {
   const nonWitnessTxs = await getNonWitnessTxs(asset, selectedUtxos, insightClient)
 
-  return {
+  const result = {
     txData: {
       inputs,
       outputs,
@@ -282,6 +291,34 @@ async function createUnsignedTx({
       rawTxs: nonWitnessTxs,
     },
   }
+
+  // Only attach PSBT metadata for Bitcoin transfer flows for now; support for other coins and
+  // transaction types will come later.
+  const isBitcoin = ['bitcoin', 'bitcoinregtest', 'bitcointestnet'].includes(asset.name)
+  if (isBitcoin) {
+    const psbtBuffer = await createPsbtWithMetadata({
+      inputs,
+      outputs,
+      asset,
+      assetClientInterface,
+      walletAccount,
+      nonWitnessTxs,
+      addressPathsMap,
+      allowedPurposes,
+      metadata: {
+        rbfEnabled,
+        txType,
+        sendOutputIndexes: [sendOutputIndex],
+        changeOutputIndex,
+        bumpTxId,
+        blockHeight,
+      },
+    })
+
+    result.txData.psbtBuffer = psbtBuffer
+  }
+
+  return result
 }
 
 const getTxHandler = (type) => {
@@ -309,6 +346,7 @@ const transferHandler = {
     utxosDescendingOrder,
     assetClientInterface,
     changeAddressType,
+    allowedPurposes,
   }) => {
     const assetName = asset.name
     const insightClient = asset.baseAsset.insightClient
@@ -437,12 +475,20 @@ const transferHandler = {
       asset,
       selectedUtxos,
       insightClient,
+      assetClientInterface,
+      walletAccount,
+      bumpTxId,
+      rbfEnabled: context.rbfEnabled,
+      txType: 'transfer',
+      sendOutputIndex: sendOutput ? outputs.indexOf(sendOutput) : undefined,
+      changeOutputIndex: changeOutput ? outputs.indexOf(changeOutput) : undefined,
+      allowedPurposes,
     })
 
     return {
       unsignedTx,
-      fee: adjustedFee,
       metadata: {
+        fee: adjustedFee,
         amount,
         change: selectedUtxos.value.sub(totalAmount).sub(adjustedFee),
         totalAmount,
@@ -469,6 +515,7 @@ export const createTxFactory =
     utxosDescendingOrder,
     assetClientInterface,
     changeAddressType,
+    allowedPurposes,
   }) =>
   async ({
     asset,
@@ -514,5 +561,6 @@ export const createTxFactory =
       utxosDescendingOrder,
       assetClientInterface,
       changeAddressType,
+      allowedPurposes,
     })
   }

package/src/tx-send/index.js

@@ -1,6 +1,7 @@
 import * as defaultBitcoinjsLib from '@exodus/bitcoinjs'
 import assert from 'minimalistic-assert'
 
+import { extractTransactionContext } from '../psbt-parser.js'
 import { createTxFactory } from '../tx-create/create-tx.js'
 import { broadcastTransaction } from './broadcast-tx.js'
 import { updateAccountState, updateTransactionLog } from './update-state.js'
@@ -108,6 +109,7 @@ const getPrepareSendTransaction = async ({
   options,
   utxosDescendingOrder,
   walletAccount,
+  allowedPurposes,
 }) => {
   const createTx = createTxFactory({
     getFeeEstimator,
@@ -115,6 +117,7 @@ const getPrepareSendTransaction = async ({
     utxosDescendingOrder,
     assetClientInterface,
     changeAddressType,
+    allowedPurposes,
   })
 
   // Set default values for options
@@ -131,6 +134,59 @@ const getPrepareSendTransaction = async ({
   })
 }
 
+function toTransactionDescriptor(txContext, psbtBuffer) {
+  const {
+    inputs,
+    outputs,
+    addressPathsMap,
+    blockHeight,
+    rawTxs,
+    fee,
+    totalSendAmount,
+    changeAmount,
+    totalAmount,
+    primaryAddresses,
+    ourAddress,
+    usableUtxos,
+    selectedUtxos,
+    replaceTx,
+    sendOutputs,
+    changeOutput,
+    rbfEnabled,
+  } = txContext
+
+  return {
+    unsignedTx: {
+      txData: {
+        inputs,
+        outputs,
+        psbtBuffer,
+      },
+      txMeta: {
+        addressPathsMap,
+        blockHeight,
+        rawTxs,
+      },
+    },
+    metadata: {
+      fee,
+      amount: totalSendAmount.isZero ? undefined : totalSendAmount,
+      sendAmount: totalSendAmount,
+      change: changeAmount,
+      totalAmount,
+      address: primaryAddresses[0]?.address,
+      ourAddress,
+      usableUtxos,
+      selectedUtxos,
+      replaceTx,
+      sendOutput: sendOutputs[0],
+      changeOutput,
+      rbfEnabled,
+      blockHeight,
+    },
+  }
+}
+
 // not ported from Exodus; but this demos signing / broadcasting
 // NOTE: this will be ripped out in the coming weeks
 export const createAndBroadcastTXFactory =
@@ -141,6 +197,7 @@ export const createAndBroadcastTXFactory =
     utxosDescendingOrder,
     assetClientInterface,
     changeAddressType,
+    allowedPurposes,
   }) =>
   async ({ asset, walletAccount, address, amount, options }) => {
     // Prepare transaction
@@ -149,7 +206,7 @@ export const createAndBroadcastTXFactory =
     const assetName = asset.name
     const accountState = await assetClientInterface.getAccountState({ assetName, walletAccount })
 
-    const transactionDescriptor = await getPrepareSendTransaction({
+    let transactionDescriptor = await getPrepareSendTransaction({
       address,
       allowUnconfirmedRbfEnabledUtxos,
       amount,
@@ -160,22 +217,31 @@ export const createAndBroadcastTXFactory =
       options,
       utxosDescendingOrder,
       walletAccount,
+      allowedPurposes,
     })
 
-    const { unsignedTx, fee, metadata } = transactionDescriptor
-    const {
-      sendAmount,
-      usableUtxos,
-      replaceTx,
-      sendOutput,
-      changeOutput,
-      blockHeight,
-      rbfEnabled,
-    } = metadata
-
-    const outputs = unsignedTx.txData.outputs
+    // If we already created a PSBT for Bitcoin, hydrate the full transaction
+    // context from it before signing.
+    let unsignedTx, metadata
+    if (transactionDescriptor.unsignedTx?.txData?.psbtBuffer) {
+      const psbtBuffer = transactionDescriptor.unsignedTx.txData.psbtBuffer
+      const txContext = await extractTransactionContext({
+        psbtBuffer,
+        asset,
+        assetClientInterface,
+        walletAccount,
+        allowedPurposes,
+      })
+      transactionDescriptor = toTransactionDescriptor(txContext, psbtBuffer)
+      unsignedTx = transactionDescriptor.unsignedTx
+      metadata = transactionDescriptor.metadata
+    } else {
+      // Legacy/non-PSBT flows stick with the original descriptor shape.
+      unsignedTx = transactionDescriptor.unsignedTx
+      metadata = transactionDescriptor.metadata
+    }
 
-    address = metadata.address
+    const { sendAmount, usableUtxos, replaceTx, sendOutput, changeOutput } = metadata
 
     // Sign transaction
     const { rawTx, txId, tx } = await signTransaction({
@@ -192,7 +258,7 @@ export const createAndBroadcastTXFactory =
       if (/insight broadcast http error.*missing inputs/i.test(err.message)) {
         err.txInfo = JSON.stringify({
           amount: sendAmount.toDefaultString({ unit: true }),
-          fee: ((fee && fee.toDefaultString({ unit: true })) || 0).toString(),
+          fee: ((metadata.fee && metadata.fee.toDefaultString({ unit: true })) || 0).toString(),
           allUtxos: usableUtxos.toJSON(),
         })
       }
@@ -203,7 +269,7 @@ export const createAndBroadcastTXFactory =
     function findUtxoIndex(output) {
       let utxoIndex = -1
       if (output) {
-        for (const [i, [address, amount]] of outputs.entries()) {
+        for (const [i, [address, amount]] of unsignedTx.txData.outputs.entries()) {
           if (output[0] === address && output[1] === amount) {
             utxoIndex = i
             break
@@ -228,7 +294,6 @@ export const createAndBroadcastTXFactory =
       rawTx,
       changeUtxoIndex,
       getSizeAndChangeScript,
-      rbfEnabled,
     })
 
     await updateTransactionLog({
@@ -236,14 +301,9 @@ export const createAndBroadcastTXFactory =
       assetClientInterface,
       walletAccount,
       txId,
-      fee,
       metadata,
-      address,
-      amount,
       bumpTxId,
       size,
-      blockHeight,
-      rbfEnabled,
     })
 
     return {

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

@@ -16,7 +16,6 @@ import { serializeCurrency } from '../fee/fee-utils.js'
  * @param {number} params.changeUtxoIndex - Index of change output
  * @param {Object} params.changeOutput - Change output details
  * @param {Object} params.getSizeAndChangeScript - Function to get size and script
- * @param {boolean} params.rbfEnabled - Whether RBF is enabled
  */
 export async function updateAccountState({
   assetClientInterface,
@@ -29,9 +28,8 @@ export async function updateAccountState({
   rawTx,
   changeUtxoIndex,
   getSizeAndChangeScript,
-  rbfEnabled,
 }) {
-  const { usableUtxos, selectedUtxos, replaceTx, change, ourAddress } = metadata
+  const { usableUtxos, selectedUtxos, replaceTx, change, ourAddress, rbfEnabled } = metadata
 
   // Get change script and size
   const { script, size } = getSizeAndChangeScript({
@@ -88,30 +86,31 @@ export async function updateAccountState({
  * @param {Object} params.assetClientInterface - Asset client interface
  * @param {Object} params.walletAccount - Wallet account
  * @param {string} params.txId - Transaction ID
- * @param {Object} params.fee - Transaction fee
  * @param {Object} params.metadata - Transaction metadata
- * @param {string} params.address - Recipient address
- * @param {Object} params.amount - Transaction amount (for regular sends)
  * @param {string} params.bumpTxId - ID of transaction being bumped (if applicable)
  * @param {number} params.size - Transaction size
- * @param {number} params.blockHeight - Block height
- * @param {boolean} params.rbfEnabled - Whether RBF is enabled
  */
 export async function updateTransactionLog({
   asset,
   assetClientInterface,
   walletAccount,
   txId,
-  fee,
   metadata,
-  address,
-  amount,
   bumpTxId,
   size,
-  blockHeight,
-  rbfEnabled,
 }) {
-  const { totalAmount, selectedUtxos, replaceTx, changeOutput, ourAddress } = metadata
+  const {
+    totalAmount,
+    selectedUtxos,
+    replaceTx,
+    changeOutput,
+    ourAddress,
+    fee,
+    blockHeight,
+    rbfEnabled,
+    address,
+    amount,
+  } = metadata
   const assetName = asset.name
 
   // Check if this is a self-send

package/src/tx-sign/create-sign-with-wallet.js

@@ -1,6 +1,7 @@
 import { bip371, payments, Transaction } from '@exodus/bitcoinjs'
 import { publicKeyToX } from '@exodus/crypto/secp256k1'
 
+import { withUnsafeNonSegwit } from '../psbt-utils.js'
 import { createGetKeyWithMetadata } from './create-get-key-and-purpose.js'
 import { toAsyncBufferSigner, toAsyncSigner } from './taproot.js'
 
@@ -82,9 +83,12 @@ export function createSignWithWallet({
         : toAsyncSigner({ privateKey, publicKey, isTaprootKeySpend })
 
       // desktop / BE / mobile with bip-schnorr signing
-      signingPromises.push(psbt.signInputAsync(index, asyncSigner, allowedSigHashTypes))
+      signingPromises.push(() => psbt.signInputAsync(index, asyncSigner, allowedSigHashTypes))
     }
 
-    await Promise.all(signingPromises)
+    await withUnsafeNonSegwit({
+      psbt,
+      fn: () => Promise.all(signingPromises.map((sign) => sign())),
+    })
   }
 }

package/src/tx-sign/default-create-tx.js

@@ -57,7 +57,11 @@ export const signTxFactory = ({
       },
     })
 
-    const skipFinalize = !!unsignedTx.txData.psbtBuffer || unsignedTx.txMeta.returnPsbt
+    const isExternalPsbt =
+      unsignedTx.txData.psbtBuffer &&
+      unsignedTx.txMeta.addressPathsMap &&
+      unsignedTx.txMeta.inputsToSign
+    const skipFinalize = isExternalPsbt || unsignedTx.txMeta.returnPsbt
     await signWithWallet(psbt, inputsToSign, skipFinalize)
     return extractTransaction({ psbt, skipFinalize })
   }

package/src/tx-sign/default-prepare-for-signing.js

@@ -27,17 +27,8 @@ export function createPrepareForSigning({
   return ({ unsignedTx }) => {
     const networkInfo = coinInfo.toBitcoinJS()
 
-    const isPsbtBufferPassed =
-      unsignedTx.txData.psbtBuffer &&
-      unsignedTx.txMeta.addressPathsMap &&
-      unsignedTx.txMeta.inputsToSign
-    if (isPsbtBufferPassed) {
-      // PSBT created externally (Web3, etc..)
-      return createPsbtFromBuffer({
-        Psbt,
-        psbtBuffer: unsignedTx.txData.psbtBuffer,
-        networkInfo,
-      })
+    if (unsignedTx.txData.psbtBuffer) {
+      return createPsbtFromBuffer({ Psbt, psbtBuffer: unsignedTx.txData.psbtBuffer, networkInfo })
     }
 
     // Create PSBT based on internal Exodus data structure

package/src/tx-sign/default-sign-hardware.js

@@ -40,7 +40,11 @@ export const signHardwareFactory = ({ assetName, resolvePurpose, keys, coinInfo
       multisigData,
     })
 
-    const skipFinalize = !!unsignedTx.txData.psbtBuffer || unsignedTx.txMeta.returnPsbt
+    const isExternalPsbt =
+      unsignedTx.txData.psbtBuffer &&
+      unsignedTx.txMeta.addressPathsMap &&
+      unsignedTx.txMeta.inputsToSign
+    const skipFinalize = isExternalPsbt || unsignedTx.txMeta.returnPsbt
     return extractTransaction({ psbt, skipFinalize })
   }
 }