@bsv/wallet-toolbox 1.7.18 → 2.0.0-beta.0

package/src/storage/methods/generateChange.ts

@@ -1,556 +0,0 @@
-import { Validation, WalletLoggerInterface } from '@bsv/sdk'
-import { WalletError } from '../../sdk/WalletError'
-import { StorageFeeModel } from '../../sdk/WalletStorage.interfaces'
-import { WERR_INSUFFICIENT_FUNDS, WERR_INTERNAL, WERR_INVALID_PARAMETER } from '../../sdk/WERR_errors'
-import { validateStorageFeeModel } from '../StorageProvider'
-import { transactionSize } from './utils'
-import { Wallet, WalletLogger } from '../../index.client'
-
-/**
- * An output of this satoshis amount will be adjusted to the largest fundable amount.
- */
-export const maxPossibleSatoshis = 2099999999999999
-
-export interface GenerateChangeSdkResult {
-  allocatedChangeInputs: GenerateChangeSdkChangeInput[]
-  changeOutputs: GenerateChangeSdkChangeOutput[]
-  size: number
-  fee: number
-  satsPerKb: number
-  maxPossibleSatoshisAdjustment?: {
-    fixedOutputIndex: number
-    satoshis: number
-  }
-}
-
-/**
- * Simplifications:
- *  - only support one change type with fixed length scripts.
- *  - only support satsPerKb fee model.
- *
- * Confirms for each availbleChange output that it remains available as they are allocated and selects alternate if not.
- *
- * @param params
- * @returns
- */
-export async function generateChangeSdk(
-  params: GenerateChangeSdkParams,
-  allocateChangeInput: (
-    targetSatoshis: number,
-    exactSatoshis?: number
-  ) => Promise<GenerateChangeSdkChangeInput | undefined>,
-  releaseChangeInput: (outputId: number) => Promise<void>,
-  logger?: WalletLoggerInterface
-): Promise<GenerateChangeSdkResult> {
-  if (params.noLogging === false) logGenerateChangeSdkParams(params)
-
-  const r: GenerateChangeSdkResult = {
-    allocatedChangeInputs: [],
-    changeOutputs: [],
-    size: 0,
-    fee: 0,
-    satsPerKb: 0
-  }
-
-  // eslint-disable-next-line no-useless-catch
-  try {
-    const vgcpr = validateGenerateChangeSdkParams(params)
-
-    const satsPerKb = params.feeModel.value || 0
-
-    const randomVals = [...(params.randomVals || [])]
-    const randomValsUsed: number[] = []
-
-    const nextRandomVal = (): number => {
-      let val = 0
-      if (!randomVals || randomVals.length === 0) {
-        val = Math.random()
-      } else {
-        val = randomVals.shift() || 0
-        randomVals.push(val)
-      }
-      // Capture random sequence used if not supplied
-      randomValsUsed.push(val)
-      return val
-    }
-
-    /**
-     * @returns a random integer betweenn min and max, inclussive.
-     */
-    const rand = (min: number, max: number): number => {
-      if (max < min) throw new WERR_INVALID_PARAMETER('max', `less than min (${min}). max is (${max})`)
-      return Math.floor(nextRandomVal() * (max - min + 1) + min)
-    }
-
-    const fixedInputs = params.fixedInputs
-    const fixedOutputs = params.fixedOutputs
-
-    /**
-     * @returns sum of transaction fixedInputs satoshis and fundingInputs satoshis
-     */
-    const funding = (): number => {
-      return (
-        fixedInputs.reduce((a, e) => a + e.satoshis, 0) + r.allocatedChangeInputs.reduce((a, e) => a + e.satoshis, 0)
-      )
-    }
-
-    /**
-     * @returns sum of transaction fixedOutputs satoshis
-     */
-    const spending = (): number => {
-      return fixedOutputs.reduce((a, e) => a + e.satoshis, 0)
-    }
-
-    /**
-     * @returns sum of transaction changeOutputs satoshis
-     */
-    const change = (): number => {
-      return r.changeOutputs.reduce((a, e) => a + e.satoshis, 0)
-    }
-
-    const fee = (): number => funding() - spending() - change()
-
-    const size = (addedChangeInputs?: number, addedChangeOutputs?: number): number => {
-      const inputScriptLengths = [
-        ...fixedInputs.map(x => x.unlockingScriptLength),
-        ...Array(r.allocatedChangeInputs.length + (addedChangeInputs || 0)).fill(params.changeUnlockingScriptLength)
-      ]
-      const outputScriptLengths = [
-        ...fixedOutputs.map(x => x.lockingScriptLength),
-        ...Array(r.changeOutputs.length + (addedChangeOutputs || 0)).fill(params.changeLockingScriptLength)
-      ]
-      const size = transactionSize(inputScriptLengths, outputScriptLengths)
-      return size
-    }
-
-    /**
-     * @returns the target fee required for the transaction as currently configured under feeModel.
-     */
-    const feeTarget = (addedChangeInputs?: number, addedChangeOutputs?: number): number => {
-      const fee = Math.ceil((size(addedChangeInputs, addedChangeOutputs) / 1000) * satsPerKb)
-      return fee
-    }
-
-    /**
-     * @returns the current excess fee for the transaction as currently configured.
-     *
-     * This is funding() - spending() - change() - feeTarget()
-     *
-     * The goal is an excess fee of zero.
-     *
-     * A positive value is okay if the cost of an additional change output is greater.
-     *
-     * A negative value means the transaction is under funded, or over spends, and may be rejected.
-     */
-    const feeExcess = (addedChangeInputs?: number, addedChangeOutputs?: number): number => {
-      const fe = funding() - spending() - change() - feeTarget(addedChangeInputs, addedChangeOutputs)
-      if (!addedChangeInputs && !addedChangeOutputs) feeExcessNow = fe
-      return fe
-    }
-
-    // The most recent feeExcess()
-    let feeExcessNow = 0
-    feeExcess()
-
-    const hasTargetNetCount = params.targetNetCount !== undefined
-    const targetNetCount = params.targetNetCount || 0
-
-    // current net change in count of change outputs
-    const netChangeCount = (): number => {
-      return r.changeOutputs.length - r.allocatedChangeInputs.length
-    }
-
-    const addOutputToBalanceNewInput = (): boolean => {
-      if (!hasTargetNetCount) return false
-      return netChangeCount() - 1 < targetNetCount
-    }
-
-    const releaseAllocatedChangeInputs = async (): Promise<void> => {
-      while (r.allocatedChangeInputs.length > 0) {
-        const i = r.allocatedChangeInputs.pop()
-        if (i) {
-          await releaseChangeInput(i.outputId)
-        }
-      }
-      feeExcessNow = feeExcess()
-    }
-
-    // If we'd like to have more change outputs create them now.
-    // They may be removed if it turns out we can't fund them.
-    while (
-      (hasTargetNetCount && targetNetCount > netChangeCount()) ||
-      (r.changeOutputs.length === 0 && feeExcess() > 0)
-    ) {
-      r.changeOutputs.push({
-        satoshis: r.changeOutputs.length === 0 ? params.changeFirstSatoshis : params.changeInitialSatoshis,
-        lockingScriptLength: params.changeLockingScriptLength
-      })
-    }
-
-    const fundTransaction = async (): Promise<void> => {
-      let removingOutputs = false
-
-      const attemptToFundTransaction = async (): Promise<boolean> => {
-        if (feeExcess() > 0) return true
-
-        let exactSatoshis: number | undefined = undefined
-        if (!hasTargetNetCount && r.changeOutputs.length === 0) {
-          exactSatoshis = -feeExcess(1)
-        }
-        const ao = addOutputToBalanceNewInput() ? 1 : 0
-        const targetSatoshis = -feeExcess(1, ao) + (ao === 1 ? 2 * params.changeInitialSatoshis : 0)
-
-        const allocatedChangeInput = await allocateChangeInput(targetSatoshis, exactSatoshis)
-
-        if (!allocatedChangeInput) {
-          // Unable to add another funding change input
-          return false
-        }
-
-        r.allocatedChangeInputs.push(allocatedChangeInput)
-
-        if (!removingOutputs && feeExcess() > 0) {
-          if (ao == 1 || r.changeOutputs.length === 0) {
-            r.changeOutputs.push({
-              satoshis: Math.min(
-                feeExcess(),
-                r.changeOutputs.length === 0 ? params.changeFirstSatoshis : params.changeInitialSatoshis
-              ),
-              lockingScriptLength: params.changeLockingScriptLength
-            })
-          }
-        }
-        return true
-      }
-
-      for (;;) {
-        // This is the starvation loop, drops change outputs one at a time if unable to fund them...
-        await releaseAllocatedChangeInputs()
-
-        while (feeExcess() < 0) {
-          // This is the funding loop, add one change input at a time...
-          const ok = await attemptToFundTransaction()
-          if (!ok) break
-        }
-
-        // Done if blanced overbalanced or impossible (all funding applied, all change outputs removed).
-        if (feeExcess() >= 0 || r.changeOutputs.length === 0) break
-
-        removingOutputs = true
-        while (r.changeOutputs.length > 0 && feeExcess() < 0) {
-          r.changeOutputs.pop()
-        }
-        if (feeExcess() < 0)
-          // Not enough available funding even if no change outputs
-          break
-        // At this point we have a funded transaction, but there may be change outputs that are each costing as change input,
-        // resulting in pointless churn of change outputs.
-        // And remove change inputs that funded only a single change output (along with that output)...
-        const changeInputs = [...r.allocatedChangeInputs]
-        while (changeInputs.length > 1 && r.changeOutputs.length > 1) {
-          const lastOutput = r.changeOutputs.slice(-1)[0]
-          const i = changeInputs.findIndex(ci => ci.satoshis <= lastOutput.satoshis)
-          if (i < 0) break
-          r.changeOutputs.pop()
-          changeInputs.splice(i, 1)
-        }
-        // and try again...
-      }
-    }
-
-    /**
-     * Add funding to achieve a non-negative feeExcess value, if necessary.
-     */
-    await fundTransaction()
-
-    if (feeExcess() < 0 && vgcpr.hasMaxPossibleOutput !== undefined) {
-      // Reduce the fixed output with satoshis of maxPossibleSatoshis to what will just fund the transaction...
-      if (fixedOutputs[vgcpr.hasMaxPossibleOutput].satoshis !== maxPossibleSatoshis) throw new WERR_INTERNAL()
-      fixedOutputs[vgcpr.hasMaxPossibleOutput].satoshis += feeExcess()
-      r.maxPossibleSatoshisAdjustment = {
-        fixedOutputIndex: vgcpr.hasMaxPossibleOutput,
-        satoshis: fixedOutputs[vgcpr.hasMaxPossibleOutput].satoshis
-      }
-    }
-
-    /**
-     * Trigger an account funding event if we don't have enough to cover this transaction.
-     */
-    if (feeExcess() < 0) {
-      const werr = new WERR_INSUFFICIENT_FUNDS(spending() + feeTarget(), -feeExcessNow)
-      logger?.error(`throwing WERR_INSUFFICIENT_FUNDS moreSatoshisNeeded ${werr.moreSatoshisNeeded}`)
-      await releaseAllocatedChangeInputs()
-      throw werr
-    }
-
-    /**
-     * If needed, seek funding to avoid overspending on fees without a change output to recapture it.
-     */
-    if (r.changeOutputs.length === 0 && feeExcessNow > 0) {
-      await releaseAllocatedChangeInputs()
-      throw new WERR_INSUFFICIENT_FUNDS(spending() + feeTarget(), params.changeFirstSatoshis)
-    }
-
-    /**
-     * Distribute the excess fees across the changeOutputs added.
-     */
-    while (r.changeOutputs.length > 0 && feeExcessNow > 0) {
-      if (r.changeOutputs.length === 1) {
-        r.changeOutputs[0].satoshis += feeExcessNow
-        feeExcessNow = 0
-      } else if (r.changeOutputs[0].satoshis < params.changeInitialSatoshis) {
-        const sats = Math.min(feeExcessNow, params.changeInitialSatoshis - r.changeOutputs[0].satoshis)
-        feeExcessNow -= sats
-        r.changeOutputs[0].satoshis += sats
-      } else {
-        // Distribute a random percentage between 25% and 50% but at least one satoshi
-        const sats = Math.max(1, Math.floor((rand(2500, 5000) / 10000) * feeExcessNow))
-        feeExcessNow -= sats
-        const index = rand(0, r.changeOutputs.length - 1)
-        r.changeOutputs[index].satoshis += sats
-      }
-    }
-
-    r.size = size()
-    ;((r.fee = fee()), (r.satsPerKb = satsPerKb))
-
-    const { ok, log } = validateGenerateChangeSdkResult(params, r)
-    if (!ok) {
-      throw new WERR_INTERNAL(`generateChangeSdk error: ${log}`)
-    }
-
-    if (r.allocatedChangeInputs.length > 4 && r.changeOutputs.length > 4) {
-      console.log('generateChangeSdk_Capture_too_many_ins_and_outs')
-      logGenerateChangeSdkParams(params)
-    }
-
-    return r
-  } catch (eu: unknown) {
-    const e = WalletError.fromUnknown(eu)
-    if (e.code === 'WERR_INSUFFICIENT_FUNDS') throw eu
-
-    // Capture the params in cloud run log which has a 100k text length limit per line.
-    // logGenerateChangeSdkParams(params, eu)
-
-    throw eu
-  }
-}
-
-export function validateGenerateChangeSdkResult(
-  params: GenerateChangeSdkParams,
-  r: GenerateChangeSdkResult
-): { ok: boolean; log: string } {
-  let ok = true
-  let log = ''
-  const sumIn =
-    params.fixedInputs.reduce((a, e) => a + e.satoshis, 0) + r.allocatedChangeInputs.reduce((a, e) => a + e.satoshis, 0)
-  const sumOut =
-    params.fixedOutputs.reduce((a, e) => a + e.satoshis, 0) + r.changeOutputs.reduce((a, e) => a + e.satoshis, 0)
-  if (r.fee && Number.isInteger(r.fee) && r.fee < 0) {
-    log += `basic fee error ${r.fee};`
-    ok = false
-  }
-  const feePaid = sumIn - sumOut
-  if (feePaid !== r.fee) {
-    log += `exact fee error ${feePaid} !== ${r.fee};`
-    ok = false
-  }
-  const feeRequired = Math.ceil(((r.size || 0) / 1000) * (r.satsPerKb || 0))
-  if (feeRequired !== r.fee) {
-    log += `required fee error ${feeRequired} !== ${r.fee};`
-    ok = false
-  }
-
-  return { ok, log }
-}
-
-function logGenerateChangeSdkParams(params: GenerateChangeSdkParams, eu?: unknown) {
-  let s = JSON.stringify(params)
-  console.log(`generateChangeSdk params length ${s.length}${eu ? ` error: ${eu}` : ''}`)
-  let i = -1
-  const maxlen = 99900
-  for (;;) {
-    i++
-    console.log(`generateChangeSdk params ${i} XXX${s.slice(0, maxlen)}XXX`)
-    s = s.slice(maxlen)
-    if (!s || i > 100) break
-  }
-}
-
-export interface GenerateChangeSdkParams {
-  fixedInputs: GenerateChangeSdkInput[]
-  fixedOutputs: GenerateChangeSdkOutput[]
-
-  feeModel: StorageFeeModel
-
-  /**
-   * Target for number of new change outputs added minus number of funding change outputs consumed.
-   * If undefined, only a single change output will be added if excess fees must be recaptured.
-   */
-  targetNetCount?: number
-  /**
-   * Satoshi amount to initialize optional new change outputs.
-   */
-  changeInitialSatoshis: number
-  /**
-   * Lowest amount value to assign to a change output.
-   * Drop the output if unable to satisfy.
-   * default 285
-   */
-  changeFirstSatoshis: number
-
-  /**
-   * Fixed change locking script length.
-   *
-   * For P2PKH template, 25 bytes
-   */
-  changeLockingScriptLength: number
-  /**
-   * Fixed change unlocking script length.
-   *
-   * For P2PKH template, 107 bytes
-   */
-  changeUnlockingScriptLength: number
-
-  randomVals?: number[]
-  noLogging?: boolean
-  log?: string
-}
-
-export interface GenerateChangeSdkInput {
-  satoshis: number
-  unlockingScriptLength: number
-}
-
-export interface GenerateChangeSdkOutput {
-  satoshis: number
-  lockingScriptLength: number
-}
-
-export interface GenerateChangeSdkChangeInput {
-  outputId: number
-  satoshis: number
-}
-
-export interface GenerateChangeSdkChangeOutput {
-  satoshis: number
-  lockingScriptLength: number
-}
-
-export interface ValidateGenerateChangeSdkParamsResult {
-  hasMaxPossibleOutput?: number
-}
-
-export function validateGenerateChangeSdkParams(
-  params: GenerateChangeSdkParams
-): ValidateGenerateChangeSdkParamsResult {
-  if (!Array.isArray(params.fixedInputs)) throw new WERR_INVALID_PARAMETER('fixedInputs', 'an array of objects')
-
-  const r: ValidateGenerateChangeSdkParamsResult = {}
-
-  params.fixedInputs.forEach((x, i) => {
-    Validation.validateSatoshis(x.satoshis, `fixedInputs[${i}].satoshis`)
-    Validation.validateInteger(x.unlockingScriptLength, `fixedInputs[${i}].unlockingScriptLength`, undefined, 0)
-  })
-
-  if (!Array.isArray(params.fixedOutputs)) throw new WERR_INVALID_PARAMETER('fixedOutputs', 'an array of objects')
-  params.fixedOutputs.forEach((x, i) => {
-    Validation.validateSatoshis(x.satoshis, `fixedOutputs[${i}].satoshis`)
-    Validation.validateInteger(x.lockingScriptLength, `fixedOutputs[${i}].lockingScriptLength`, undefined, 0)
-    if (x.satoshis === maxPossibleSatoshis) {
-      if (r.hasMaxPossibleOutput !== undefined)
-        throw new WERR_INVALID_PARAMETER(
-          `fixedOutputs[${i}].satoshis`,
-          `valid satoshis amount. Only one 'maxPossibleSatoshis' output allowed.`
-        )
-      r.hasMaxPossibleOutput = i
-    }
-  })
-
-  params.feeModel = validateStorageFeeModel(params.feeModel)
-  if (params.feeModel.model !== 'sat/kb') throw new WERR_INVALID_PARAMETER('feeModel.model', `'sat/kb'`)
-
-  Validation.validateOptionalInteger(params.targetNetCount, `targetNetCount`)
-
-  Validation.validateSatoshis(params.changeFirstSatoshis, 'changeFirstSatoshis', 1)
-  Validation.validateSatoshis(params.changeInitialSatoshis, 'changeInitialSatoshis', 1)
-
-  Validation.validateInteger(params.changeLockingScriptLength, `changeLockingScriptLength`)
-  Validation.validateInteger(params.changeUnlockingScriptLength, `changeUnlockingScriptLength`)
-
-  return r
-}
-
-export interface GenerateChangeSdkStorageChange extends GenerateChangeSdkChangeInput {
-  spendable: boolean
-}
-
-export function generateChangeSdkMakeStorage(availableChange: GenerateChangeSdkChangeInput[]): {
-  allocateChangeInput: (
-    targetSatoshis: number,
-    exactSatoshis?: number
-  ) => Promise<GenerateChangeSdkChangeInput | undefined>
-  releaseChangeInput: (outputId: number) => Promise<void>
-  getLog: () => string
-} {
-  const change: GenerateChangeSdkStorageChange[] = availableChange.map(c => ({
-    ...c,
-    spendable: true
-  }))
-  change.sort((a, b) =>
-    a.satoshis < b.satoshis
-      ? -1
-      : a.satoshis > b.satoshis
-        ? 1
-        : a.outputId < b.outputId
-          ? -1
-          : a.outputId > b.outputId
-            ? 1
-            : 0
-  )
-
-  let log = ''
-  for (const c of change) log += `change ${c.satoshis} ${c.outputId}\n`
-
-  const getLog = (): string => log
-
-  const allocate = (c: GenerateChangeSdkStorageChange) => {
-    log += ` -> ${c.satoshis} sats, id ${c.outputId}\n`
-    c.spendable = false
-    return c
-  }
-
-  const allocateChangeInput = async (
-    targetSatoshis: number,
-    exactSatoshis?: number
-  ): Promise<GenerateChangeSdkChangeInput | undefined> => {
-    log += `allocate target ${targetSatoshis} exact ${exactSatoshis}`
-
-    if (exactSatoshis !== undefined) {
-      const exact = change.find(c => c.spendable && c.satoshis === exactSatoshis)
-      if (exact) return allocate(exact)
-    }
-    const over = change.find(c => c.spendable && c.satoshis >= targetSatoshis)
-    if (over) return allocate(over)
-    let under: GenerateChangeSdkStorageChange | undefined = undefined
-    for (let i = change.length - 1; i >= 0; i--) {
-      if (change[i].spendable) {
-        under = change[i]
-        break
-      }
-    }
-    if (under) return allocate(under)
-    log += `\n`
-    return undefined
-  }
-
-  const releaseChangeInput = async (outputId: number): Promise<void> => {
-    log += `release id ${outputId}\n`
-    const c = change.find(x => x.outputId === outputId)
-    if (!c) throw new WERR_INTERNAL(`unknown outputId ${outputId}`)
-    if (c.spendable) throw new WERR_INTERNAL(`release of spendable outputId ${outputId}`)
-    c.spendable = true
-  }
-
-  return { allocateChangeInput, releaseChangeInput, getLog }
-}

package/src/storage/methods/getBeefForTransaction.ts

@@ -1,139 +0,0 @@
-import { Beef } from '@bsv/sdk'
-import { StorageProvider } from '../StorageProvider'
-import { ProvenOrRawTx, StorageGetBeefOptions } from '../../sdk/WalletStorage.interfaces'
-import { EntityProvenTx } from '../schema/entities/EntityProvenTx'
-import { WERR_INVALID_MERKLE_ROOT, WERR_INVALID_OPERATION, WERR_INVALID_PARAMETER } from '../../sdk/WERR_errors'
-import { asBsvSdkTx, verifyTruthy } from '../../utility/utilityHelpers'
-
-/**
- * Creates a `Beef` to support the validity of a transaction identified by its `txid`.
- *
- * `storage` is used to retrieve proven transactions and their merkle paths,
- * or proven_tx_req record with beef of external inputs (internal inputs meged by recursion).
- * Otherwise external services are used.
- *
- * `options.maxRecursionDepth` can be set to prevent overly deep chained dependencies. Will throw ERR_EXTSVS_ENVELOPE_DEPTH if exceeded.
- *
- * If `trustSelf` is true, a partial `Beef` will be returned where transactions known by `storage` to
- * be valid by verified proof are represented solely by 'txid'.
- *
- * If `knownTxids` is defined, any 'txid' required by the `Beef` that appears in the array is represented solely as a 'known' txid.
- *
- * @param storage the chain on which txid exists.
- * @param txid the transaction hash for which an envelope is requested.
- * @param options
- */
-export async function getBeefForTransaction(
-  storage: StorageProvider,
-  txid: string,
-  options: StorageGetBeefOptions
-): Promise<Beef> {
-  const beef =
-    // deserialize mergeToBeef if it is an array
-    Array.isArray(options.mergeToBeef)
-      ? Beef.fromBinary(options.mergeToBeef)
-      : // otherwise if undefined create a new Beef
-        options.mergeToBeef || new Beef()
-
-  await mergeBeefForTransactionRecurse(beef, storage, txid, options, 0)
-
-  return beef
-}
-
-/**
- * @returns rawTx if txid known to network, if merkle proof available then also proven result is valid.
- */
-async function getProvenOrRawTxFromServices(
-  storage: StorageProvider,
-  txid: string,
-  options: StorageGetBeefOptions
-): Promise<ProvenOrRawTx> {
-  const services = storage.getServices()
-  const por = await EntityProvenTx.fromTxid(txid, await storage.getServices())
-  if (por.proven && !options.ignoreStorage && !options.ignoreNewProven) {
-    por.proven.provenTxId = await storage.insertProvenTx(por.proven.toApi())
-  }
-  return { proven: por.proven?.toApi(), rawTx: por.rawTx }
-}
-
-async function mergeBeefForTransactionRecurse(
-  beef: Beef,
-  storage: StorageProvider,
-  txid: string,
-  options: StorageGetBeefOptions,
-  recursionDepth: number
-): Promise<Beef> {
-  const maxDepth = storage.maxRecursionDepth
-  if (maxDepth && maxDepth <= recursionDepth)
-    throw new WERR_INVALID_OPERATION(`Maximum BEEF depth exceeded. Limit is ${storage.maxRecursionDepth}`)
-
-  if (options.knownTxids && options.knownTxids.indexOf(txid) > -1) {
-    // This txid is one of the txids the caller claims to already know are valid...
-    beef.mergeTxidOnly(txid)
-    return beef
-  }
-
-  if (!options.ignoreStorage) {
-    // if we can use storage, ask storage if it has the txid
-    const requiredLevels = options.minProofLevel === undefined ? undefined : options.minProofLevel + recursionDepth
-    const knownBeef = await storage.getValidBeefForTxid(
-      txid,
-      beef,
-      options.trustSelf,
-      options.knownTxids,
-      undefined,
-      requiredLevels
-    )
-    if (knownBeef) return knownBeef
-  }
-
-  if (options.ignoreServices)
-    throw new WERR_INVALID_PARAMETER(`txid ${txid}`, `valid transaction on chain ${storage.chain}`)
-
-  // if storage doesn't know about txid, use services
-  // to find it and if it has a proof, remember it.
-  const r = await getProvenOrRawTxFromServices(storage, txid, options)
-
-  if (r.proven && options.minProofLevel !== undefined && options.minProofLevel > recursionDepth) {
-    // ignore proof at this recursion depth
-    r.proven = undefined
-  }
-
-  if (r.proven) {
-    // storage has proven this txid,
-    // merge both the raw transaction and its merkle path
-    const mp = new EntityProvenTx(r.proven).getMerklePath()
-    if (options.chainTracker) {
-      const root = mp.computeRoot()
-      const isValid = await options.chainTracker.isValidRootForHeight(root, r.proven.height)
-      if (!isValid) {
-        if (!options.skipInvalidProofs) {
-          throw new WERR_INVALID_MERKLE_ROOT(r.proven.blockHash, r.proven.height, root, txid)
-        }
-        // ignore this currently invalid proof and try to recurse deeper
-        r.proven = undefined
-      }
-    }
-    if (r.proven) {
-      beef.mergeRawTx(r.proven.rawTx)
-      beef.mergeBump(mp)
-      return beef
-    }
-  }
-
-  if (!r.rawTx) throw new WERR_INVALID_PARAMETER(`txid ${txid}`, `valid transaction on chain ${storage.chain}`)
-
-  // merge the raw transaction and recurse over its inputs.
-  beef.mergeRawTx(r.rawTx!)
-  // recurse inputs
-  const tx = asBsvSdkTx(r.rawTx!)
-  for (const input of tx.inputs) {
-    const inputTxid = verifyTruthy(input.sourceTXID)
-    if (!beef.findTxid(inputTxid)) {
-      // Only if the txid is not already in the list of beef transactions.
-      await mergeBeefForTransactionRecurse(beef, storage, inputTxid, options, recursionDepth + 1)
-    }
-  }
-
-  return beef
-}