@exodus/bitcoin-api 4.2.2 → 4.4.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 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)
+
+
+### Features
+
+
+* feat: add PSBT builder infrastructure (#6822)
+
+
+
 ## [4.2.2](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.2.1...@exodus/bitcoin-api@4.2.2) (2025-11-10)
 
 **Note:** Version bump only for package @exodus/bitcoin-api

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bitcoin-api",
-  "version": "4.2.2",
+  "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": "ba11d8958a6416d939b43f5297930f4069f7daa8"
+  "gitHead": "5bc77cf38ec6fbd32d9e286d5bda25ea7366854d"
 }

package/src/psbt-builder.js

@@ -0,0 +1,248 @@
+import { payments, Psbt, Transaction } from '@exodus/bitcoinjs'
+import { publicKeyToX } from '@exodus/crypto/secp256k1'
+import assert from 'minimalistic-assert'
+
+import { SubType, writePsbtGlobalField, writePsbtOutputField } from './psbt-proprietary-types.js'
+import { getAddressType, getPurposeXPubs, validatePurpose } from './psbt-utils.js'
+
+function canParseTx(rawTxBuffer) {
+  try {
+    Transaction.fromBuffer(rawTxBuffer)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function getWrappedSegwitRedeemScript({ publicKey, address, context = '' }) {
+  const p2wpkh = payments.p2wpkh({ pubkey: publicKey })
+  const p2sh = payments.p2sh({ redeem: p2wpkh })
+
+  if (address !== p2sh.address) {
+    throw new Error(`Expected P2SH script to be a nested p2wpkh${context ? ' for ' + context : ''}`)
+  }
+
+  return p2sh.redeem.output
+}
+
+function addBip32Derivation({ isTaprootAddress, publicKey, path, masterFingerprint }) {
+  if (isTaprootAddress) {
+    const pubkey = publicKeyToX({ publicKey, format: 'buffer' })
+    return {
+      tapBip32Derivation: [
+        {
+          path,
+          leafHashes: [],
+          masterFingerprint,
+          pubkey,
+        },
+      ],
+      tapInternalKey: pubkey,
+    }
+  }
+
+  return {
+    bip32Derivation: [
+      {
+        path,
+        masterFingerprint,
+        pubkey: publicKey,
+      },
+    ],
+  }
+}
+
+function writeGlobalMetadata(psbt, metadata) {
+  if (metadata.blockHeight !== undefined) {
+    writePsbtGlobalField(psbt, SubType.BlockHeight, metadata.blockHeight)
+  }
+
+  if (metadata.rbfEnabled) {
+    writePsbtGlobalField(psbt, SubType.RbfEnabled, metadata.rbfEnabled)
+  }
+
+  if (metadata.bumpTxId) {
+    writePsbtGlobalField(psbt, SubType.BumpTxId, metadata.bumpTxId)
+  }
+
+  if (metadata.txType) {
+    writePsbtGlobalField(psbt, SubType.TxType, metadata.txType)
+  }
+}
+
+function createPsbtInput({
+  input,
+  asset,
+  addressPathsMap,
+  purposeXPubs,
+  nonWitnessTxs,
+  allowedPurposes,
+}) {
+  const psbtInput = {
+    hash: input.txId,
+    index: input.vout,
+    sequence: input.sequence,
+  }
+
+  const purpose = asset.address.resolvePurpose(input.address)
+  validatePurpose(purpose, allowedPurposes, `address ${input.address}`)
+
+  const { isSegwitAddress, isTaprootAddress, isWrappedSegwitAddress } = getAddressType(purpose)
+
+  const path = addressPathsMap[input.address]
+  assert(path, `Derivation path is missing for address ${input.address}`)
+
+  const publicKey = purposeXPubs[purpose].hdkey.derive(path).publicKey
+  const masterFingerprint = purposeXPubs[purpose].masterFingerprint
+
+  if (isWrappedSegwitAddress) {
+    psbtInput.redeemScript = getWrappedSegwitRedeemScript({
+      publicKey,
+      address: input.address,
+      context: `input address ${input.address}`,
+    })
+  }
+
+  if (isWrappedSegwitAddress || isSegwitAddress || isTaprootAddress) {
+    psbtInput.witnessUtxo = {
+      value: input.value,
+      script: Buffer.from(input.script, 'hex'),
+    }
+  }
+
+  if (!isTaprootAddress) {
+    const rawTx = (nonWitnessTxs || []).find((t) => t.txId === input.txId)
+    assert(
+      !!rawTx?.rawData,
+      `Non-taproot outputs require the full previous transaction for address ${input.address}`
+    )
+
+    const rawTxBuffer = Buffer.from(rawTx.rawData, 'hex')
+    if (canParseTx(rawTxBuffer)) {
+      psbtInput.nonWitnessUtxo = rawTxBuffer
+    } else {
+      // bitcoinjs can’t parse a handful of edge-case transactions (Litecoin MWEB, odd
+      // vendor forks, malformed historical data). When that happens we fall back to a
+      // witness-only record and rely on the signer to opt-in to __UNSAFE_SIGN_NONSEGWIT.
+      psbtInput.witnessUtxo = {
+        value: input.value,
+        script: Buffer.from(input.script, 'hex'),
+      }
+    }
+  }
+
+  const derivationData = addBip32Derivation({
+    isTaprootAddress,
+    publicKey,
+    path,
+    masterFingerprint,
+  })
+
+  return { ...psbtInput, ...derivationData }
+}
+
+function createPsbtOutput({
+  address,
+  amount,
+  asset,
+  addressPathsMap,
+  purposeXPubs,
+  allowedPurposes,
+}) {
+  const psbtOutput = {
+    address,
+    value: amount,
+  }
+
+  const path = addressPathsMap[address]
+  if (!path) {
+    return psbtOutput
+  }
+
+  const purpose = asset.address.resolvePurpose(address)
+  validatePurpose(purpose, allowedPurposes, `output address ${address}`)
+
+  const { isTaprootAddress, isWrappedSegwitAddress } = getAddressType(purpose)
+
+  const publicKey = purposeXPubs[purpose].hdkey.derive(path).publicKey
+  const masterFingerprint = purposeXPubs[purpose].masterFingerprint
+
+  if (isWrappedSegwitAddress) {
+    psbtOutput.redeemScript = getWrappedSegwitRedeemScript({
+      publicKey,
+      address,
+      context: `output address ${address}`,
+    })
+  }
+
+  const derivationData = addBip32Derivation({
+    isTaprootAddress,
+    publicKey,
+    path,
+    masterFingerprint,
+  })
+
+  return { ...psbtOutput, ...derivationData }
+}
+
+export async function createPsbtWithMetadata({
+  inputs,
+  outputs,
+  asset,
+  assetClientInterface,
+  walletAccount,
+  nonWitnessTxs,
+  addressPathsMap,
+  metadata,
+  allowedPurposes,
+}) {
+  assert(inputs, 'inputs is required')
+  assert(outputs, 'outputs is required')
+  assert(asset, 'asset is required')
+  assert(assetClientInterface, 'assetClientInterface is required')
+  assert(walletAccount, 'walletAccount is required')
+  assert(addressPathsMap, 'addressPathsMap is required')
+  assert(metadata, 'metadata is required')
+
+  const psbt = new Psbt({ network: asset.coinInfo.toBitcoinJS() })
+
+  const purposeXPubs = await getPurposeXPubs({
+    assetClientInterface,
+    walletAccount,
+    asset,
+    allowedPurposes,
+  })
+
+  writeGlobalMetadata(psbt, metadata)
+
+  for (const input of inputs) {
+    const psbtInput = createPsbtInput({
+      input,
+      asset,
+      addressPathsMap,
+      purposeXPubs,
+      nonWitnessTxs,
+      allowedPurposes,
+    })
+    psbt.addInput(psbtInput)
+  }
+
+  outputs.forEach(([address, amount]) => {
+    const psbtOutput = createPsbtOutput({
+      address,
+      amount,
+      asset,
+      addressPathsMap,
+      purposeXPubs,
+      allowedPurposes,
+    })
+    psbt.addOutput(psbtOutput)
+  })
+
+  // sendOutputIndexes is optional (e.g., bump transactions).
+  for (const sendOutputIndex of metadata.sendOutputIndexes || []) {
+    writePsbtOutputField(psbt, sendOutputIndex, SubType.OutputRole, 'primary')
+  }
+
+  return psbt.toBase64()
+}

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,
+  }
+}

package/src/psbt-proprietary-types.js

@@ -11,6 +11,10 @@ const PROP_TYPE_MARKER = 0xfc
 
 export const SubType = Object.freeze({
   BlockHeight: 0x01,
+  BumpTxId: 0x03,
+  RbfEnabled: 0x04,
+  TxType: 0x05,
+  OutputRole: 0x06,
 })
 
 const buildPropKey = (subType) => {
@@ -51,3 +55,97 @@ export const readPsbtBlockHeight = (psbt) => {
   const kv = findProprietaryVal(psbt.data.globalMap.unknownKeyVals, SubType.BlockHeight)
   return kv ? kv.value.readUInt32LE(0) : undefined
 }
+
+const encodeProprietaryValue = (subType, value) => {
+  switch (subType) {
+    case SubType.BlockHeight:
+      assert(
+        Number.isInteger(value) && value >= 0 && value <= 4_294_967_295,
+        'blockHeight must be a positive integer between 0 and 4294967295'
+      )
+      return u32LE(value)
+    case SubType.RbfEnabled:
+      return Buffer.from([value ? 1 : 0])
+    case SubType.BumpTxId:
+    case SubType.TxType:
+    case SubType.OutputRole:
+      return Buffer.from(value, 'utf8')
+    default:
+      throw new Error(`Unknown proprietary field subType: ${subType}`)
+  }
+}
+
+const decodeProprietaryValue = (subType, buffer) => {
+  switch (subType) {
+    case SubType.BlockHeight:
+      return buffer.readUInt32LE(0)
+    case SubType.RbfEnabled:
+      return buffer[0] === 1
+    case SubType.BumpTxId:
+    case SubType.TxType:
+    case SubType.OutputRole:
+      return buffer.toString('utf8')
+    default:
+      throw new Error(`Unknown proprietary field subType: ${subType}`)
+  }
+}
+
+export const writePsbtGlobalField = (psbt, subType, value) => {
+  assert(psbt, 'psbt is required')
+  assert(Number.isInteger(subType), 'subType must be an integer')
+  assert(value !== undefined, 'value is required')
+
+  const encodedValue = encodeProprietaryValue(subType, value)
+  psbt.addUnknownKeyValToGlobal({
+    key: buildPropKey(subType),
+    value: encodedValue,
+  })
+}
+
+export const writePsbtOutputField = (psbt, outputIndex, subType, value) => {
+  assert(psbt, 'psbt is required')
+  assert(
+    Number.isInteger(outputIndex) && outputIndex >= 0,
+    'outputIndex must be a non-negative integer'
+  )
+  assert(Number.isInteger(subType), 'subType must be an integer')
+  assert(value !== undefined, 'value is required')
+
+  const encodedValue = encodeProprietaryValue(subType, value)
+  psbt.addUnknownKeyValToOutput(outputIndex, {
+    key: buildPropKey(subType),
+    value: encodedValue,
+  })
+}
+
+export const readPsbtGlobalField = (psbt, subType) => {
+  assert(psbt, 'psbt is required')
+  assert(Number.isInteger(subType), 'subType must be an integer')
+
+  const kv = findProprietaryVal(psbt.data.globalMap.unknownKeyVals, subType)
+  return kv ? decodeProprietaryValue(subType, kv.value) : undefined
+}
+
+export const readPsbtOutputField = (psbt, outputIndex) => {
+  assert(psbt, 'psbt is required')
+  assert(
+    Number.isInteger(outputIndex) && outputIndex >= 0,
+    'outputIndex must be a non-negative integer'
+  )
+
+  const output = psbt.data.outputs[outputIndex]
+  if (!output) return Object.create(null)
+
+  const result = Object.create(null)
+  for (const [key, subTypeVal] of Object.entries(SubType)) {
+    const kv = findProprietaryVal(output.unknownKeyVals, subTypeVal)
+    if (kv) {
+      result[key.charAt(0).toLowerCase() + key.slice(1)] = decodeProprietaryValue(
+        subTypeVal,
+        kv.value
+      )
+    }
+  }
+
+  return result
+}

package/src/psbt-utils.js

@@ -1,10 +1,62 @@
+import BIP32 from '@exodus/bip32'
 import BipPath from 'bip32-path'
 import lodash from 'lodash'
+import assert from 'minimalistic-assert'
+
+export const PURPOSE_TYPES = {
+  LEGACY: 44, // P2PKH
+  WRAPPED_SEGWIT: 49, // P2SH-P2WPKH
+  SEGWIT: 84, // P2WPKH
+  TAPROOT: 86, // P2TR
+}
+
+export function getAddressType(purpose) {
+  return {
+    isLegacyAddress: purpose === PURPOSE_TYPES.LEGACY,
+    isWrappedSegwitAddress: purpose === PURPOSE_TYPES.WRAPPED_SEGWIT,
+    isSegwitAddress: purpose === PURPOSE_TYPES.SEGWIT,
+    isTaprootAddress: purpose === PURPOSE_TYPES.TAPROOT,
+  }
+}
+
+export async function getPurposeXPubs({
+  assetClientInterface,
+  walletAccount,
+  asset,
+  allowedPurposes,
+}) {
+  assert(allowedPurposes, 'allowedPurposes is required')
+  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,
+    }
+  }
+
+  return purposeXPubs
+}
+
+export function validatePurpose(purpose, allowedPurposes, context = '') {
+  assert(allowedPurposes, 'allowedPurposes is required')
+  if (!allowedPurposes.includes(purpose)) {
+    throw new Error(`Purpose ${purpose} not found${context ? ' for ' + context : ''}`)
+  }
+}
 
 export const createPsbtToUnsignedTx =
   ({ assetClientInterface, assetName }) =>
   async ({ psbt, walletAccount, purpose = 86 }) => {
-    const addressPathsMap = {}
+    const addressPathsMap = Object.create(null)
     const inputsToSign = []
 
     const addressOpts = {
@@ -59,3 +111,18 @@ export const createPsbtToUnsignedTx =
       },
     }
   }
+
+/**
+ * Temporarily turns on __UNSAFE_SIGN_NONSEGWIT so we can sign or validate PSBTs
+ * whose legacy inputs are missing nonWitnessUtxo.
+ */
+export async function withUnsafeNonSegwit({ psbt, fn, unsafe = true }) {
+  const cache = psbt.__CACHE
+  const prevValue = cache.__UNSAFE_SIGN_NONSEGWIT
+  cache.__UNSAFE_SIGN_NONSEGWIT = unsafe
+  try {
+    return await fn()
+  } finally {
+    cache.__UNSAFE_SIGN_NONSEGWIT = prevValue
+  }
+}