@exodus/bitcoin-api 4.2.2 → 4.3.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.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.3.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": "7a2a429c2a182a889e550761d9106da3296815ca"
 }

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