@teleportdao/bitcoin 3.0.3 → 4.0.0-alpha.0

package/src/transaction-builder/coin-select.ts

@@ -0,0 +1,633 @@
+import * as bitcoin from "bitcoinjs-lib"
+import { ExtendedUtxo, Target } from "./transaction-builder"
+import { getAddressType } from "../bitcoin-utils"
+
+export const componentBytes = {
+  bytePerInput: {
+    p2pkh: 152, // 149
+    p2wpkh: 72, // 68
+    "p2sh-p2wpkh": 92, // 91
+    p2tr: 62, //  58
+    default: 92,
+  },
+  baseTxBytes: 10 + 5, // +5 extra bytes to be sure
+  bytePerOutput: {
+    p2pkh: 34, // 33
+    p2wpkh: 31, // 30
+    p2sh: 32, // 31
+    p2tr: 43, // 42
+    p2wsh: 44, // 43
+    default: 35,
+    max: 45,
+  },
+
+  scriptExtraBytes: {
+    lessThan255: 12,
+    moreThan255: 15,
+  },
+}
+
+// https://bitcoin.stackexchange.com/questions/84004/how-do-virtual-size-stripped-size-and-raw-size-compare-between-legacy-address-f
+// export const componentBytes = {
+//   bytePerInput: {
+//     p2pkh: 148,
+//     p2wpkh: 70, // 68
+//     "p2sh-p2wpkh": 91,
+//     p2tr: 60, // actual 58
+//   },
+//   baseTxBytes: 10 + 5, // +5 extra bytes to be sure
+//   bytePerOutput: {
+//     p2pkh: 35, // 34
+//     p2wpkh: 35, // 31
+//     p2sh: 35, // 32
+//     p2tr: 45, // 43
+//     p2tr: 45, // 43
+//     default: 35,
+//   },
+//
+// }
+
+// P2SH | 46 + 74n + 34m
+// P2SH-P2WSH | (306 + 76n + 34m) / 4
+// P2WSH | (166 + 76n + 34m) / 4
+
+export const DUST = 600
+
+export function getInputSize(
+  addressType: string,
+  details?: {
+    // op return or other script
+    script?: string
+    // n of m multisig
+    n?: number
+    m?: number
+  },
+) {
+  let { m = 3 } = details || {}
+  const n = details?.n || m || 2
+  if (addressType === "p2sh") {
+    return 46 + 74 * n + 34 * m
+  }
+  if (addressType === "p2sh-p2wsh") {
+    return +((306 + 76 * n + 34 * m) / 4).toFixed()
+  }
+  if (addressType === "p2wsh") {
+    return +((166 + 76 * n + 34 * m) / 4).toFixed()
+  }
+
+  return (
+    componentBytes.bytePerInput[addressType as keyof typeof componentBytes.bytePerInput] ||
+    componentBytes.bytePerInput.default
+  )
+}
+
+export function getOutputSize(
+  output: {
+    addressType?: string
+    address?: string
+    script?: Buffer
+  },
+  // use network to decode address
+  network: bitcoin.Network = bitcoin.networks.bitcoin,
+) {
+  if (output.addressType) {
+    return (
+      componentBytes.bytePerOutput[
+        output.addressType as keyof typeof componentBytes.bytePerOutput
+      ] || componentBytes.bytePerOutput.default
+    )
+  }
+  if (output.address) {
+    let addressType = "max"
+    try {
+      addressType = getAddressType(output.address, network)
+    } catch {
+      addressType = "max"
+    }
+    return (
+      componentBytes.bytePerOutput[addressType as keyof typeof componentBytes.bytePerOutput] ||
+      componentBytes.bytePerOutput.max
+    )
+  }
+
+  if (output.script) {
+    if (output.script.byteLength < 255) {
+      return output.script.byteLength + componentBytes.scriptExtraBytes.lessThan255
+    }
+    return output.script.byteLength + componentBytes.scriptExtraBytes.moreThan255
+  }
+  throw new Error("invalid output")
+}
+
+export function calculateTxSize(
+  inputTypes: {
+    addressType: string
+    n?: number
+    m?: number
+    script?: string
+  }[],
+  outputs: {
+    script?: Buffer
+    address?: string
+    value: number
+  }[],
+  changeAddressType = "default",
+  network: bitcoin.Network = bitcoin.networks.bitcoin,
+) {
+  const inputsSizes = inputTypes.map(({ addressType, n, m }) => getInputSize(addressType, { n, m }))
+  const outputSizes = outputs.map((outP: any) => {
+    if (!outP.address && !outP.script) {
+      return getOutputSize(
+        {
+          addressType: changeAddressType,
+        },
+        network,
+      )
+    }
+    return getOutputSize(outP, network)
+  })
+
+  const txSize: number =
+    componentBytes.baseTxBytes +
+    inputsSizes.reduce((a, c) => a + c, 0) +
+    outputSizes.reduce((a, c) => a + c, 0)
+
+  return txSize
+}
+
+function sumValues(outputs: { value: number }[]): number {
+  return outputs.reduce((sum: number, o) => sum + o.value, 0)
+}
+
+function fixNumberToInteger(value: number): number {
+  return Math.ceil(value)
+}
+
+function finalCheckAndAddChangeAndExtraInput(
+  inputs: ExtendedUtxo[],
+  outputs: Target[],
+  outputValue: number,
+  outputSize: number,
+  feeRate: number,
+  changeSize: number,
+  highFeeThd: number,
+  // for optimization
+  extraInput?: ExtendedUtxo,
+  smallUtxoAggregate?: ExtendedUtxo[],
+) {
+  const selectedInputs = inputs.concat(smallUtxoAggregate || [])
+  let selectedInputsValue = sumValues(selectedInputs)
+  const selectedInputsSize = selectedInputs.reduce(
+    (sum, i) =>
+      sum +
+      getInputSize(i.signerInfo.addressType, {
+        n: i.signerInfo.numberOfSigners,
+        m: i.signerInfo.publicKeys?.length,
+      }),
+    0,
+  )
+  let txSize = selectedInputsSize + outputSize + componentBytes.baseTxBytes
+  let txFee = fixNumberToInteger(txSize * feeRate)
+
+  let totalNeeded = txFee + outputValue
+  let changeValue = 0
+  const changeFee = fixNumberToInteger(changeSize * feeRate)
+
+  if (extraInput && (!smallUtxoAggregate || smallUtxoAggregate.length === 0)) {
+    const extraInputSize = fixNumberToInteger(
+      getInputSize(extraInput.signerInfo.addressType, {
+        n: extraInput.signerInfo.numberOfSigners,
+        m: extraInput.signerInfo.publicKeys?.length,
+      }),
+    )
+    const extraInputFee = fixNumberToInteger(extraInputSize * feeRate)
+    if (
+      selectedInputsValue - totalNeeded > extraInputFee + changeFee &&
+      selectedInputsValue - totalNeeded < (feeRate > highFeeThd ? DUST : 2 * DUST)
+    ) {
+      selectedInputs.push(extraInput)
+      selectedInputsValue += extraInput.value
+      txSize = txSize + extraInputSize
+      txFee = fixNumberToInteger(txSize * feeRate)
+      totalNeeded = txFee + outputValue
+    }
+  }
+
+  if (selectedInputsValue - totalNeeded > DUST) {
+    txSize = txSize + changeSize
+    txFee = fixNumberToInteger(txSize * feeRate)
+    totalNeeded = txFee + outputValue
+    changeValue = selectedInputsValue - totalNeeded
+  }
+  let needed = totalNeeded - selectedInputsValue
+
+  // fee absorption for feeRate > 2
+  // for feeRate < 2, it could cause the tx to be rejected by the mempool (due to small tx fee per byte)
+  if (feeRate >= 2 && needed > 0) {
+    // If needed amount is < 10% of fee, absorb it into fee instead of failing
+    if (needed < txFee * 0.1) {
+      txFee -= needed
+      needed = 0
+    }
+  }
+  return {
+    success: needed <= 0,
+    inputs: selectedInputs,
+    outputs,
+    change: changeValue > 0 ? { value: changeValue } : undefined,
+    fee: txFee,
+    bytes: txSize,
+    totalInputValue: selectedInputsValue,
+    totalOutputValue: outputValue + changeValue,
+    needed: needed > 0 ? needed : 0,
+    feeRate,
+    effectiveFeeRate: +(txFee / txSize).toFixed(2),
+  }
+}
+
+export function coinSelectNormal(
+  inputs: ExtendedUtxo[],
+  outputs: Target[],
+  feeRate: number,
+  changeAddressType = "max",
+  network: bitcoin.Network = bitcoin.networks.bitcoin,
+  highFeeThd = 5,
+  requiredUtxo?: ExtendedUtxo[],
+  smallUtxoAggregate?: {
+    minInputCount: number
+    maxInputValue: number
+  },
+): {
+  success: boolean
+  inputs: ExtendedUtxo[]
+  outputs: Target[]
+  fee: number
+  bytes: number
+  totalInputValue: number
+  totalOutputValue: number
+  needed: number
+  change?: { value: number }
+} {
+  // Sort inputs descending
+  const totalOutputValue = sumValues(outputs)
+  const sortedInputs = [...inputs].sort((a, b) => b.value - a.value)
+  const numberOfInputsPerOutputs = feeRate > highFeeThd ? 1 : 2
+  const minRequiredInputCount = requiredUtxo ? requiredUtxo.length : 1
+
+  // randomize priority inputs to another array
+  let priorityInputs = sortedInputs.filter(
+    (inp) => inp.value >= totalOutputValue / outputs.length / numberOfInputsPerOutputs,
+  )
+
+  priorityInputs = priorityInputs.sort(() => Math.random() - 0.5)
+
+  // select rest of the inputs from sorted inputs
+  const otherInputs = sortedInputs.slice(priorityInputs.length)
+  let allInputs = priorityInputs.concat(otherInputs)
+
+  if (requiredUtxo) {
+    // remove required utxo from all inputs
+    allInputs = allInputs.filter(
+      (inp) => !requiredUtxo.some((r) => r.hash === inp.hash && r.index === inp.index),
+    )
+
+    // check if its better to put require utxo in utxo list or not
+    // if (sortedInputs.length - allInputs.length !== requiredUtxo.length) {
+    //   throw new Error("required utxo is not exist in utxo list")
+    // }
+    //
+    allInputs = requiredUtxo.concat(allInputs)
+  }
+
+  const outputSize = outputs.reduce((sum, o) => sum + getOutputSize(o, network), 0)
+  const changeSize = getOutputSize({ addressType: changeAddressType }, network)
+  const baseTxSize = componentBytes.baseTxBytes
+
+  let txSize = outputSize + baseTxSize
+  let txFee = fixNumberToInteger(txSize * feeRate)
+  const selected: ExtendedUtxo[] = []
+
+  for (let index = 0; index < allInputs.length; index += 1) {
+    const input = allInputs[index]
+    selected.push(input)
+    const inputSize = getInputSize(input.signerInfo.addressType, {
+      n: input.signerInfo.numberOfSigners,
+      m: input.signerInfo.publicKeys?.length,
+    })
+    const selectedValue = sumValues(selected)
+
+    txSize += inputSize
+    txFee = txSize * feeRate
+    let totalNeeded = txFee + totalOutputValue
+
+    if (selectedValue >= totalNeeded && selected.length >= minRequiredInputCount) {
+      let smallUtxo: ExtendedUtxo[] | undefined
+
+      if (
+        feeRate < 1.3 &&
+        smallUtxoAggregate &&
+        selected.length < smallUtxoAggregate.minInputCount
+      ) {
+        const selectedInputIds = new Set(selected.map((inp) => `${inp.hash}:${inp.index}`))
+        smallUtxo = allInputs
+          .filter((_, inpIndex) => inpIndex > index)
+          .filter((inp) => inp.value < smallUtxoAggregate.maxInputValue)
+          // todo: check if we need check if the input is already selected because we already filter it using index
+          .filter((inp) => !selectedInputIds.has(`${inp.hash}:${inp.index}`))
+
+        smallUtxo = smallUtxo.sort((a, b) => a.value - b.value)
+        smallUtxo = smallUtxo.slice(0, smallUtxoAggregate.minInputCount - selected.length)
+      }
+
+      return finalCheckAndAddChangeAndExtraInput(
+        selected,
+        outputs,
+        totalOutputValue,
+        outputSize,
+        feeRate,
+        changeSize,
+        highFeeThd,
+        smallUtxo && smallUtxo.length > 0 ? undefined : allInputs[index + 1],
+        smallUtxo, // if there is small utxo, extraInput will be ignored so its ok if extraInput exists in small utxo
+      )
+    }
+  }
+  return finalCheckAndAddChangeAndExtraInput(
+    allInputs,
+    outputs,
+    totalOutputValue,
+    outputSize,
+    feeRate,
+    changeSize,
+    highFeeThd,
+    undefined,
+  )
+}
+
+//  Branch & Bound coin selection
+export function coinSelectBnB(
+  inputs: ExtendedUtxo[],
+  outputs: Target[],
+  feeRate: number,
+  changeAddressType = "max",
+  network: bitcoin.Network = bitcoin.networks.bitcoin,
+  highFeeThd = 5,
+  smallUtxoAggregate?: {
+    minInputCount: number
+    maxInputValue: number
+  },
+): {
+  success: boolean
+  inputs: ExtendedUtxo[]
+  outputs: Target[]
+  fee: number
+  bytes: number
+  totalInputValue: number
+  totalOutputValue: number
+  needed: number
+  change?: { value: number }
+} {
+  if (inputs.length > 20) {
+    return coinSelectNormal(
+      inputs,
+      outputs,
+      feeRate,
+      changeAddressType,
+      network,
+      highFeeThd,
+      undefined,
+      smallUtxoAggregate,
+    )
+  }
+
+  // Sort inputs descending
+  const totalOutputValue = sumValues(outputs)
+
+  const outputSize = outputs.reduce((sum, o) => sum + getOutputSize(o, network), 0)
+  const changeSize = getOutputSize({ addressType: changeAddressType }, network)
+  const baseTxSize = componentBytes.baseTxBytes
+
+  const sortedInputs = [...inputs].sort((a, b) => b.value - a.value)
+  const numberOfInputsPerOutputs = feeRate > highFeeThd ? 1 : 2
+
+  let lastInput: ExtendedUtxo | undefined = sortedInputs[sortedInputs.length - 1]
+  let bnbInputs = sortedInputs
+    .slice(0, -1)
+    .filter((inp) => inp.value > totalOutputValue / outputs.length / numberOfInputsPerOutputs)
+
+  let bestWaste = Infinity
+  let bestSelection: ExtendedUtxo[] | null = null
+  function bnb(idx: number, selected: ExtendedUtxo[]) {
+    const selectedValue = sumValues(selected)
+    const inputSize = selected.reduce(
+      (sum, i) =>
+        sum +
+        getInputSize(i.signerInfo.addressType, {
+          n: i.signerInfo.numberOfSigners,
+          m: i.signerInfo.publicKeys?.length,
+        }),
+      0,
+    )
+    const txSize = outputSize + baseTxSize + inputSize
+    const txFee = fixNumberToInteger(txSize * feeRate)
+    let totalNeeded = txFee + totalOutputValue
+
+    if (selectedValue - totalNeeded > DUST) {
+      totalNeeded = totalNeeded + fixNumberToInteger(changeSize * feeRate)
+    }
+
+    // Return if over target+fee+bestWaste
+    if (selectedValue > totalNeeded + bestWaste) return
+
+    // If enough, check if best
+    if (selectedValue >= totalNeeded) {
+      const waste = selectedValue - totalNeeded
+      if (waste < bestWaste) {
+        bestWaste = waste
+        bestSelection = selected.slice()
+      }
+      return
+    }
+    // If out of inputs, stop
+    if (idx >= bnbInputs.length) return
+    // Branch: include current input
+    bnb(idx + 1, [...selected, bnbInputs[idx]])
+    // Branch: exclude current input
+    bnb(idx + 1, selected)
+  }
+  bnb(0, [])
+
+  if (!bestSelection) {
+    bnbInputs = sortedInputs
+    bestWaste = Infinity
+    bestSelection = null
+    bnb(0, [])
+  }
+
+  // aggregate small utxo
+  const selectedInputs = bestSelection || inputs
+  let smallUtxo: ExtendedUtxo[] | undefined
+  if (
+    feeRate < 1.3 &&
+    smallUtxoAggregate &&
+    selectedInputs.length < smallUtxoAggregate.minInputCount
+  ) {
+    const selectedInputIds = new Set(selectedInputs.map((input) => `${input.hash}:${input.index}`))
+    smallUtxo = inputs
+      .filter((input) => !selectedInputIds.has(`${input.hash}:${input.index}`))
+      .filter((input) => input.value < smallUtxoAggregate.maxInputValue)
+    smallUtxo = smallUtxo.sort((a, b) => a.value - b.value)
+    smallUtxo = smallUtxo.slice(0, smallUtxoAggregate.minInputCount - selectedInputs.length)
+  }
+
+  return finalCheckAndAddChangeAndExtraInput(
+    selectedInputs,
+    outputs,
+    totalOutputValue,
+    outputSize,
+    feeRate,
+    changeSize,
+    highFeeThd,
+    lastInput,
+    smallUtxo,
+  )
+}
+
+export function coinSelectAccumulative(
+  inputs: ExtendedUtxo[],
+  outputs: Target[],
+  feeRate: number,
+  changeAddressType = "max",
+  network: bitcoin.Network = bitcoin.networks.bitcoin,
+  highFeeThd = 5,
+): {
+  success: boolean
+  inputs: ExtendedUtxo[]
+  outputs: Target[]
+  fee: number
+  totalInputValue: number
+  totalOutputValue: number
+  needed: number
+  change?: { value: number }
+} {
+  const totalOutputValue = sumValues(outputs)
+
+  const outputSize = outputs.reduce((sum, o) => sum + getOutputSize(o, network), 0)
+  const changeSize = getOutputSize({ addressType: changeAddressType }, network)
+  const baseTxSize = componentBytes.baseTxBytes
+
+  const selected: ExtendedUtxo[] = []
+
+  let txSize = outputSize + baseTxSize
+  let txFee = fixNumberToInteger(txSize * feeRate)
+  for (let index = 0; index < inputs.length; index += 1) {
+    const input = inputs[index]
+    selected.push(input)
+    const inputSize = getInputSize(input.signerInfo.addressType, {
+      n: input.signerInfo.numberOfSigners,
+      m: input.signerInfo.publicKeys?.length,
+    })
+    const selectedValue = sumValues(selected)
+
+    txSize += inputSize
+    txFee = txSize * feeRate
+
+    let totalNeeded = txFee + totalOutputValue
+
+    if (selectedValue >= totalNeeded) {
+      return finalCheckAndAddChangeAndExtraInput(
+        selected,
+        outputs,
+        totalOutputValue,
+        outputSize,
+        feeRate,
+        changeSize,
+        highFeeThd,
+        inputs[index + 1] || undefined,
+      )
+    }
+  }
+  return finalCheckAndAddChangeAndExtraInput(
+    selected,
+    outputs,
+    totalOutputValue,
+    outputSize,
+    feeRate,
+    changeSize,
+    highFeeThd,
+    undefined,
+  )
+}
+
+export function coinSelectAll(
+  inputs: ExtendedUtxo[],
+  targets: Target[],
+  feeRate: number,
+  changeAddressType = "max",
+  network: bitcoin.Network = bitcoin.networks.bitcoin,
+): {
+  success: boolean
+  inputs: ExtendedUtxo[]
+  outputs: Target[]
+  fee: number
+  totalInputValue: number
+  totalOutputValue: number
+  needed: number
+  change?: { value: number }
+} {
+  if (!targets[0].address) {
+    throw new Error("target address is required")
+  }
+  const changeSize = getOutputSize({ addressType: changeAddressType }, network)
+  return finalCheckAndAddChangeAndExtraInput(inputs, [], 0, 0, feeRate, changeSize, 0)
+}
+
+// todo : remove --- Sample usage/demo ---
+if (require.main === module) {
+  let utxos: ExtendedUtxo[] = [
+    {
+      signerInfo: { address: "A", publicKey: "", addressType: "p2pkh" },
+      hash: "h1",
+      value: 50000,
+      index: 0,
+    },
+    {
+      signerInfo: { address: "B", publicKey: "", addressType: "p2pkh" },
+      hash: "h2",
+      value: 30000,
+      index: 1,
+    },
+    {
+      signerInfo: { address: "C", publicKey: "", addressType: "p2pkh" },
+      hash: "h3",
+      value: 4000,
+      index: 2,
+    },
+    {
+      signerInfo: { address: "D", publicKey: "", addressType: "p2pkh" },
+      hash: "h4",
+      value: 10000,
+      index: 3,
+    },
+  ]
+  // Mock outputs
+
+  const outputs: Target[] = [
+    { address: "X", value: 6640 },
+    // { address: "Y", value: 15000 },
+    // { address: "Y", value: 15000 },
+  ]
+  const outputs2: Target[] = [
+    { address: "X", value: 40150 },
+    { address: "Y", value: 2484 },
+    { address: "Z", value: 50000 },
+  ]
+  const feeRate = 2 // sats/byte
+
+  console.log("Coin selection result:", coinSelectBnB(utxos, outputs, feeRate))
+  console.log("Coin selection result:", coinSelectAccumulative(utxos, outputs, feeRate))
+  console.log("Coin selection result:", coinSelectAll(utxos, outputs, feeRate))
+
+  console.log("Selection failed:", coinSelectBnB(utxos, outputs2, feeRate))
+  console.log("Selection failed:", coinSelectAccumulative(utxos, outputs2, feeRate))
+}

package/src/transaction-builder/index.ts

@@ -1,3 +1,4 @@
 export * from "./bitcoin-transaction-builder"
 export * from "./ordinal-transaction-builder"
 export * from "./transaction-builder"
+export * from "./coin-select"