@bsv/wallet-toolbox 1.7.14 → 1.7.16

package/mobile/node_modules/@bsv/sdk/src/transaction/Beef.ts

@@ -0,0 +1,935 @@
+import MerklePath from './MerklePath.js'
+import Transaction from './Transaction.js'
+import ChainTracker from './ChainTracker.js'
+import BeefTx from './BeefTx.js'
+import { Reader, Writer, toHex, toArray, verifyNotNull } from '../primitives/utils.js'
+import { hash256 } from '../primitives/Hash.js'
+
+const BufferCtor =
+  typeof globalThis !== 'undefined' ? (globalThis as any).Buffer : undefined
+
+export const BEEF_V1 = 4022206465 // 0100BEEF in LE order
+export const BEEF_V2 = 4022206466 // 0200BEEF in LE order
+export const ATOMIC_BEEF = 0x01010101 // 01010101
+export enum TX_DATA_FORMAT {
+  RAWTX = 0, // rawtx without BUMP
+  RAWTX_AND_BUMP_INDEX = 1, // rawtx with bump index
+  TXID_ONLY = 2, // txid only
+}
+
+/*
+ * BEEF standard: BRC-62: Background Evaluation Extended Format (BEEF) Transactions
+ * https://github.com/bsv-blockchain/BRCs/blob/master/transactions/0062.md
+ *
+ * BUMP standard: BRC-74: BSV Unified Merkle Path (BUMP) Format
+ * https://github.com/bsv-blockchain/BRCs/blob/master/transactions/0074.md
+ *
+ * BRC-95: Atomic BEEF Transactions
+ * https://github.com/bsv-blockchain/BRCs/blob/master/transactions/0095.md
+ *
+ * The Atomic BEEF format is supported by the binary deserialization static method `fromBinary`.
+ *
+ * BRC-96: BEEF V2, Txid Only Extension
+ * https://github.com/bsv-blockchain/BRCs/blob/master/transactions/0096.md
+ *
+ * A valid serialized BEEF is the cornerstone of Simplified Payment Validation (SPV)
+ * where they are exchanged between two non-trusting parties to establish the
+ * validity of a newly constructed bitcoin transaction and its inputs from prior
+ * transactions.
+ *
+ * A `Beef` is fundamentally an list of `BUMP`s and a list of transactions.
+ *
+ * A `BUMP` is a partial merkle tree for a 'mined' bitcoin block.
+ * It can therefore be used to prove the validity of transaction data
+ * for each transaction txid whose merkle path is included in the tree.
+ *
+ * To be valid, the list of transactions must be sorted in dependency order:
+ * oldest transaction first;
+ * and each transaction must either
+ * have a merkle path in one of the BUMPs, or
+ * have all of its input transactions included in the list of transactions.
+ *
+ * The `Beef` class supports the construction of valid BEEFs by allowing BUMPs
+ * (merkle paths) and transactions to be merged sequentially.
+ *
+ * The `Beef` class also extends the standard by supporting 'known' transactions.
+ * A 'known' transaction is represented solely by its txid.
+ * To become valid, all the 'known' transactions in a `Beef` must be replaced by full
+ * transactions and merkle paths, if they are mined.
+ *
+ * The purpose of supporting 'known' transactions is that one or both parties
+ * generating and exchanging BEEFs often possess partial knowledge of valid transactions
+ * due to their history.
+ *
+ * A valid `Beef` is only required when sent to a party with no shared history,
+ * such as a transaction processor.
+ *
+ * IMPORTANT NOTE:
+ * It is fundamental to the BEEF value proposition that only valid transactions and valid
+ * merkle path (BUMP) data be added to it. Merging invalid data breaks the `verify` and `isValid`
+ * functions. There is no support for removing invalid data. A `Beef` that becomes invalid
+ * must be discarded.
+ */
+export class Beef {
+  bumps: MerklePath[] = []
+  txs: BeefTx[] = []
+  version: number = BEEF_V2
+  atomicTxid: string | undefined = undefined
+  private txidIndex: Map<string, BeefTx> | undefined = undefined
+  private rawBytesCache?: Uint8Array
+  private hexCache?: string
+  private needsSort: boolean = true
+
+  constructor (version: number = BEEF_V2) {
+    this.version = version
+  }
+
+  private invalidateSerializationCaches (): void {
+    this.rawBytesCache = undefined
+    this.hexCache = undefined
+  }
+
+  private markMutated (requiresSort: boolean = true): void {
+    this.invalidateSerializationCaches()
+    if (requiresSort) {
+      this.needsSort = true
+    }
+  }
+
+  private ensureSerializableState (): void {
+    for (const tx of this.txs) {
+      void tx.txid
+    }
+  }
+
+  private ensureSortedForSerialization (): void {
+    if (this.needsSort) {
+      this.sortTxs()
+    }
+  }
+
+  private getSerializedBytes (): Uint8Array {
+    this.ensureSerializableState()
+    if (this.rawBytesCache == null) {
+      this.ensureSortedForSerialization()
+      const writer = new Writer()
+      this.toWriter(writer)
+      this.rawBytesCache = writer.toUint8Array()
+    }
+    return this.rawBytesCache
+  }
+
+  /**
+   * @param txid of `beefTx` to find
+   * @returns `BeefTx` in `txs` with `txid`.
+   */
+  findTxid (txid: string): BeefTx | undefined {
+    return this.ensureTxidIndex().get(txid)
+  }
+
+  private ensureTxidIndex (): Map<string, BeefTx> {
+    if (this.txidIndex == null) {
+      this.txidIndex = new Map<string, BeefTx>()
+      for (const tx of this.txs) {
+        this.txidIndex.set(tx.txid, tx)
+      }
+    }
+    return this.txidIndex
+  }
+
+  private deleteFromIndex (txid: string): void {
+    this.txidIndex?.delete(txid)
+  }
+
+  private addToIndex (tx: BeefTx): void {
+    this.txidIndex?.set(tx.txid, tx)
+  }
+
+  /**
+   * Replaces `BeefTx` for this txid with txidOnly.
+   *
+   * Replacement is done so that a `clone()` can be
+   * updated by this method without affecting the
+   * original.
+   *
+   * @param txid
+   * @returns undefined if txid is unknown.
+   */
+  makeTxidOnly (txid: string): BeefTx | undefined {
+    const i = this.txs.findIndex((tx) => tx.txid === txid)
+    if (i === -1) return undefined
+    let btx = this.txs[i]
+    if (btx.isTxidOnly) {
+      return btx
+    }
+    this.deleteFromIndex(txid)
+    this.txs.splice(i, 1)
+    this.markMutated(true)
+    btx = this.mergeTxidOnly(txid)
+    return btx
+  }
+
+  /**
+   * @returns `MerklePath` with level zero hash equal to txid or undefined.
+   */
+  findBump (txid: string): MerklePath | undefined {
+    return this.bumps.find((b) =>
+      b.path[0].some((leaf) => leaf.hash === txid) // ✅ Ensure boolean return with `.some()`
+    )
+  }
+
+  /**
+   * Finds a Transaction in this `Beef`
+   * and adds any missing input SourceTransactions from this `Beef`.
+   *
+   * The result is suitable for signing.
+   *
+   * @param txid The id of the target transaction.
+   * @returns Transaction with all available input `SourceTransaction`s from this Beef.
+   */
+  findTransactionForSigning (txid: string): Transaction | undefined {
+    const beefTx = this.findTxid(txid)
+    if ((beefTx == null) || (beefTx.tx == null)) return undefined // Ensure beefTx.tx exists before using it
+
+    for (const i of beefTx.tx.inputs) {
+      if (i.sourceTransaction == null) {
+        const itx = this.findTxid(verifyNotNull(i.sourceTXID, 'sourceTXID must be valid'))
+        if (itx != null) {
+          i.sourceTransaction = itx.tx
+        }
+      }
+    }
+
+    return beefTx.tx
+  }
+
+  /**
+   * Builds the proof tree rooted at a specific `Transaction`.
+   *
+   * To succeed, the Beef must contain all the required transaction and merkle path data.
+   *
+   * @param txid The id of the target transaction.
+   * @returns Transaction with input `SourceTransaction` and `MerklePath` populated from this Beef.
+   */
+  findAtomicTransaction (txid: string): Transaction | undefined {
+    const beefTx = this.findTxid(txid)
+    if ((beefTx == null) || (beefTx.tx == null)) return undefined // Ensure beefTx.tx exists before using it
+
+    const addInputProof = (beef: Beef, tx: Transaction): void => {
+      const mp = beef.findBump(tx.id('hex'))
+      if (mp != null) {
+        tx.merklePath = mp
+      } else {
+        for (const i of tx.inputs) {
+          if (i.sourceTransaction == null) {
+            const itx = beef.findTxid(verifyNotNull(i.sourceTXID, 'sourceTXID must be valid'))
+            if (itx != null) {
+              i.sourceTransaction = itx.tx
+            }
+          }
+          if (i.sourceTransaction != null) {
+            const mp = beef.findBump(i.sourceTransaction.id('hex'))
+            if (mp != null) {
+              i.sourceTransaction.merklePath = mp
+            } else {
+              addInputProof(beef, i.sourceTransaction)
+            }
+          }
+        }
+      }
+    }
+
+    addInputProof(this, beefTx.tx) // Safe because we checked that beefTx.tx exists
+
+    return beefTx.tx
+  }
+
+  /**
+   * Merge a MerklePath that is assumed to be fully valid.
+   * @param bump
+   * @returns index of merged bump
+   */
+  mergeBump (bump: MerklePath): number {
+    this.markMutated(false)
+    let bumpIndex: number | undefined
+    // If this proof is identical to another one previously added, we use that first. Otherwise, we try to merge it with proofs from the same block.
+    for (let i = 0; i < this.bumps.length; i++) {
+      const b = this.bumps[i]
+      if (b === bump) {
+        // Literally the same
+        return i
+      }
+      if (b.blockHeight === bump.blockHeight) {
+        // Probably the same...
+        const rootA = b.computeRoot()
+        const rootB = bump.computeRoot()
+        if (rootA === rootB) {
+          // Definitely the same... combine them to save space
+          b.combine(bump)
+          bumpIndex = i
+          break
+        }
+      }
+    }
+
+    // if the proof is not yet added, add a new path.
+    if (bumpIndex === undefined) {
+      bumpIndex = this.bumps.length
+      this.bumps.push(bump)
+    }
+
+    // Review if any transactions are proven by this bump
+    const b = this.bumps[bumpIndex]
+    for (const tx of this.txs) {
+      const txid = tx.txid
+
+      if (tx.bumpIndex == null) { // ✅ Explicitly check for null or undefined
+        for (const n of b.path[0]) {
+          if (n.hash === txid) {
+            tx.bumpIndex = bumpIndex
+            n.txid = true
+            break
+          }
+        }
+      }
+    }
+
+    return bumpIndex
+  }
+
+  /**
+   * Merge a serialized transaction.
+   *
+   * Checks that a transaction with the same txid hasn't already been merged.
+   *
+   * Replaces existing transaction with same txid.
+   *
+   * @param rawTx
+   * @param bumpIndex Optional. If a number, must be valid index into bumps array.
+   * @returns txid of rawTx
+   */
+  mergeRawTx (rawTx: number[], bumpIndex?: number): BeefTx {
+    this.markMutated(true)
+    const newTx: BeefTx = new BeefTx(rawTx, bumpIndex)
+    this.removeExistingTxid(newTx.txid)
+    this.txs.push(newTx)
+    this.addToIndex(newTx)
+    this.tryToValidateBumpIndex(newTx)
+    return newTx
+  }
+
+  /**
+   * Merge a `Transaction` and any referenced `merklePath` and `sourceTransaction`, recursifely.
+   *
+   * Replaces existing transaction with same txid.
+   *
+   * Attempts to match an existing bump to the new transaction.
+   *
+   * @param tx
+   * @returns txid of tx
+   */
+  mergeTransaction (tx: Transaction): BeefTx {
+    this.markMutated(true)
+    const txid = tx.id('hex')
+    this.removeExistingTxid(txid)
+    let bumpIndex: number | undefined
+    if (tx.merklePath != null) {
+      bumpIndex = this.mergeBump(tx.merklePath)
+    }
+    const newTx = new BeefTx(tx, bumpIndex)
+    this.txs.push(newTx)
+    this.addToIndex(newTx)
+    this.tryToValidateBumpIndex(newTx)
+    bumpIndex = newTx.bumpIndex
+    if (bumpIndex === undefined) {
+      for (const input of tx.inputs) {
+        if (input.sourceTransaction != null) {
+          this.mergeTransaction(input.sourceTransaction)
+        }
+      }
+    }
+    return newTx
+  }
+
+  /**
+   * Removes an existing transaction from the BEEF, given its TXID
+   * @param txid TXID of the transaction to remove
+   */
+  removeExistingTxid (txid: string): void {
+    const existingTxIndex = this.txs.findIndex((t) => t.txid === txid)
+    if (existingTxIndex >= 0) {
+      this.deleteFromIndex(txid)
+      this.txs.splice(existingTxIndex, 1)
+      this.markMutated(true)
+    }
+  }
+
+  mergeTxidOnly (txid: string): BeefTx {
+    let tx = this.findTxid(txid)
+    if (tx == null) {
+      tx = new BeefTx(txid)
+      this.txs.push(tx)
+      this.addToIndex(tx)
+      this.tryToValidateBumpIndex(tx)
+      this.markMutated(true)
+    }
+    return tx
+  }
+
+  mergeBeefTx (btx: BeefTx): BeefTx {
+    let beefTx = this.findTxid(btx.txid)
+
+    if (btx.isTxidOnly && (beefTx == null)) {
+      beefTx = this.mergeTxidOnly(btx.txid)
+    } else if ((btx._tx != null) && ((beefTx == null) || beefTx.isTxidOnly)) {
+      beefTx = this.mergeTransaction(btx._tx)
+    } else if ((btx._rawTx != null) && ((beefTx == null) || beefTx.isTxidOnly)) {
+      beefTx = this.mergeRawTx(btx._rawTx)
+    }
+
+    if (beefTx == null) {
+      throw new Error(`Failed to merge BeefTx for txid: ${btx.txid}`)
+    }
+
+    return beefTx
+  }
+
+  mergeBeef (beef: number[] | Beef): void {
+    const b: Beef = Array.isArray(beef) ? Beef.fromBinary(beef) : beef
+
+    for (const bump of b.bumps) {
+      this.mergeBump(bump)
+    }
+
+    for (const tx of b.txs) {
+      this.mergeBeefTx(tx)
+    }
+  }
+
+  /**
+   * Sorts `txs` and checks structural validity of beef.
+   *
+   * Does NOT verify merkle roots.
+   *
+   * Validity requirements:
+   * 1. No 'known' txids, unless `allowTxidOnly` is true.
+   * 2. All transactions have bumps or their inputs chain back to bumps (or are known).
+   * 3. Order of transactions satisfies dependencies before dependents.
+   * 4. No transactions with duplicate txids.
+   *
+   * @param allowTxidOnly optional. If true, transaction txid only is assumed valid
+   */
+  isValid (allowTxidOnly?: boolean): boolean {
+    return this.verifyValid(allowTxidOnly).valid
+  }
+
+  /**
+   * Sorts `txs` and confirms validity of transaction data contained in beef
+   * by validating structure of this beef and confirming computed merkle roots
+   * using `chainTracker`.
+   *
+   * Validity requirements:
+   * 1. No 'known' txids, unless `allowTxidOnly` is true.
+   * 2. All transactions have bumps or their inputs chain back to bumps (or are known).
+   * 3. Order of transactions satisfies dependencies before dependents.
+   * 4. No transactions with duplicate txids.
+   *
+   * @param chainTracker Used to verify computed merkle path roots for all bump txids.
+   * @param allowTxidOnly optional. If true, transaction txid is assumed valid
+   */
+  async verify (
+    chainTracker: ChainTracker,
+    allowTxidOnly?: boolean
+  ): Promise<boolean> {
+    const r = this.verifyValid(allowTxidOnly)
+    if (!r.valid) return false
+
+    for (const height of Object.keys(r.roots)) {
+      const isValid = await chainTracker.isValidRootForHeight(
+        r.roots[height],
+        Number(height)
+      )
+      if (!isValid) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Sorts `txs` and confirms validity of transaction data contained in beef
+   * by validating structure of this beef.
+   *
+   * Returns block heights and merkle root values to be confirmed by a chaintracker.
+   *
+   * Validity requirements:
+   * 1. No 'known' txids, unless `allowTxidOnly` is true.
+   * 2. All transactions have bumps or their inputs chain back to bumps (or are known).
+   * 3. Order of transactions satisfies dependencies before dependents.
+   * 4. No transactions with duplicate txids.
+   *
+   * @param allowTxidOnly optional. If true, transaction txid is assumed valid
+   * @returns {{valid: boolean, roots: Record<number, string>}}
+   * `valid` is true iff this Beef is structuraly valid.
+   * `roots` is a record where keys are block heights and values are the corresponding merkle roots to be validated.
+   */
+  verifyValid (allowTxidOnly?: boolean): {
+    valid: boolean
+    roots: Record<number, string>
+  } {
+    const r: { valid: boolean, roots: Record<number, string> } = {
+      valid: false,
+      roots: {}
+    }
+
+    const sr = this.sortTxs()
+    if (sr.missingInputs.length > 0 ||
+      sr.notValid.length > 0 ||
+      (sr.txidOnly.length > 0 && allowTxidOnly !== true) ||
+      sr.withMissingInputs.length > 0
+    ) { return r }
+
+    // valid txids: only txids if allowed, bump txids, then txids with input's in txids
+    const txids: Record<string, boolean> = {}
+
+    for (const tx of this.txs) {
+      if (tx.isTxidOnly) {
+        if (allowTxidOnly !== true) return r // ✅ Explicit check for `true`
+        txids[tx.txid] = true
+      }
+    }
+
+    const confirmComputedRoot = (b: MerklePath, txid: string): boolean => {
+      const root = b.computeRoot(txid)
+      if (r.roots[b.blockHeight] === undefined || r.roots[b.blockHeight] === '') {
+        // accept the root as valid for this block and reuse for subsequent txids
+        r.roots[b.blockHeight] = root
+      }
+      if (r.roots[b.blockHeight] !== root) {
+        return false
+      }
+      return true
+    }
+
+    for (const b of this.bumps) {
+      for (const n of b.path[0]) {
+        if (n.txid === true && typeof n.hash === 'string' && n.hash.length > 0) {
+          txids[n.hash] = true
+
+          // All txid hashes in all bumps must agree on computed merkle path roots
+          if (!confirmComputedRoot(b, n.hash)) {
+            return r
+          }
+        }
+      }
+    }
+
+    // All txs with a bumpIndex have matching txid leaf at level zero of BUMP.
+    for (const t of this.txs) {
+      if (t.bumpIndex !== undefined) {
+        const leaf = this.bumps[t.bumpIndex].path[0].find(l => l.hash === t.txid)
+        if (leaf == null) { return r }
+      }
+    }
+
+    for (const t of this.txs) {
+      // all input txids must be included before they are referenced
+      for (const i of t.inputTxids) {
+        if (!txids[i]) return r
+      }
+      txids[t.txid] = true
+    }
+
+    r.valid = true
+    return r
+  }
+
+  /**
+   * Serializes this data to `writer`
+   * @param writer
+   */
+  toWriter (writer: Writer): void {
+    writer.writeUInt32LE(this.version)
+
+    writer.writeVarIntNum(this.bumps.length)
+    for (const b of this.bumps) {
+      writer.write(b.toBinary())
+    }
+
+    writer.writeVarIntNum(this.txs.length)
+    for (const tx of this.txs) {
+      tx.toWriter(writer, this.version)
+    }
+  }
+
+  /**
+   * Returns a binary array representing the serialized BEEF
+   * @returns A binary array representing the BEEF
+   */
+  toBinary (): number[] {
+    return Array.from(this.getSerializedBytes())
+  }
+
+  toUint8Array (): Uint8Array {
+    return this.getSerializedBytes()
+  }
+
+  /**
+   * Serialize this Beef as AtomicBEEF.
+   *
+   * `txid` must exist
+   *
+   * after sorting, if txid is not last txid, creates a clone and removes newer txs
+   *
+   * @param txid
+   * @returns serialized contents of this Beef with AtomicBEEF prefix.
+   */
+  toBinaryAtomic (txid: string): number[] {
+    if (this.needsSort) {
+      this.sortTxs()
+    }
+    const tx = this.findTxid(txid)
+    if (tx == null) {
+      throw new Error(`${txid} does not exist in this Beef`)
+    }
+
+    // If the transaction is not the last one, clone and modify
+    const beef = (this.txs[this.txs.length - 1] === tx) ? this : this.clone()
+
+    if (beef !== this) {
+      const i = this.txs.findIndex((t) => t.txid === txid)
+      beef.txs.splice(i + 1)
+    }
+
+    const writer = new Writer()
+    writer.writeUInt32LE(ATOMIC_BEEF)
+    writer.writeReverse(toArray(txid, 'hex'))
+    beef.toWriter(writer)
+
+    return writer.toArray()
+  }
+
+  /**
+   * Returns a hex string representing the serialized BEEF
+   * @returns A hex string representing the BEEF
+   */
+  toHex (): string {
+    if (this.hexCache != null) {
+      return this.hexCache
+    }
+    const bytes = this.getSerializedBytes()
+    const hex =
+      BufferCtor != null
+        ? BufferCtor.from(bytes).toString('hex')
+        : toHex(Array.from(bytes))
+    this.hexCache = hex
+    return hex
+  }
+
+  static fromReader (br: Reader): Beef {
+    let version = br.readUInt32LE()
+    let atomicTxid: string | undefined
+    if (version === ATOMIC_BEEF) {
+      // Skip the txid and re-read the BEEF version
+      atomicTxid = toHex(br.readReverse(32))
+      version = br.readUInt32LE()
+    }
+    if (version !== BEEF_V1 && version !== BEEF_V2) {
+      throw new Error(
+        `Serialized BEEF must start with ${BEEF_V1} or ${BEEF_V2} but starts with ${version}`
+      )
+    }
+    const beef = new Beef(version)
+    const bumpsLength = br.readVarIntNum()
+    for (let i = 0; i < bumpsLength; i++) {
+      const bump = MerklePath.fromReader(br, false)
+      beef.bumps.push(bump)
+    }
+    const txsLength = br.readVarIntNum()
+    for (let i = 0; i < txsLength; i++) {
+      const beefTx = BeefTx.fromReader(br, version)
+      beef.txs.push(beefTx)
+    }
+    beef.atomicTxid = atomicTxid
+    return beef
+  }
+
+  /**
+   * Constructs an instance of the Beef class based on the provided binary array
+   * @param bin The binary array from which to construct BEEF
+   * @returns An instance of the Beef class constructed from the binary data
+   */
+  static fromBinary (bin: number[]): Beef {
+    const br = new Reader(bin)
+    return Beef.fromReader(br)
+  }
+
+  /**
+   * Constructs an instance of the Beef class based on the provided string
+   * @param s The string value from which to construct BEEF
+   * @param enc The encoding of the string value from which BEEF should be constructed
+   * @returns An instance of the Beef class constructed from the string
+   */
+  static fromString (s: string, enc: 'hex' | 'utf8' | 'base64' = 'hex'): Beef {
+    const bin = toArray(s, enc)
+    const br = new Reader(bin)
+    return Beef.fromReader(br)
+  }
+
+  /**
+   * Try to validate newTx.bumpIndex by looking for an existing bump
+   * that proves newTx.txid
+   *
+   * @param newTx A new `BeefTx` that has been added to this.txs
+   * @returns true if a bump was found, false otherwise
+   */
+  private tryToValidateBumpIndex (newTx: BeefTx): boolean {
+    if (newTx.bumpIndex !== undefined) {
+      return true
+    }
+    const txid = newTx.txid
+    for (let i = 0; i < this.bumps.length; i++) {
+      const j = this.bumps[i].path[0].findIndex((b) => b.hash === txid)
+      if (j >= 0) {
+        newTx.bumpIndex = i
+        this.bumps[i].path[0][j].txid = true
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * Sort the `txs` by input txid dependency order:
+   * - Oldest Tx Anchored by Path or txid only
+   * - Newer Txs depending on Older parents
+   * - Newest Tx
+   *
+   * with proof (MerklePath) last, longest chain of dependencies first
+   *
+   * @returns `{ missingInputs, notValid, valid, withMissingInputs }`
+   */
+  sortTxs (): {
+    missingInputs: string[]
+    notValid: string[]
+    valid: string[]
+    withMissingInputs: string[]
+    txidOnly: string[]
+  } {
+    // Hashtable of valid txids (with proof or all inputs chain to proof)
+    const validTxids: Record<string, boolean> = {}
+
+    // Hashtable of all transaction txids to transaction
+    const txidToTx: Record<string, BeefTx> = {}
+
+    // queue of unsorted transactions ...
+    let queue: BeefTx[] = []
+
+    // sorted transactions: hasProof to with longest dependency chain
+    const result: BeefTx[] = []
+
+    const txidOnly: BeefTx[] = []
+
+    for (const tx of this.txs) {
+      txidToTx[tx.txid] = tx
+      tx.isValid = tx.hasProof
+      if (tx.isValid) {
+        validTxids[tx.txid] = true
+        result.push(tx)
+      } else if (tx.isTxidOnly && tx.inputTxids.length === 0) {
+        validTxids[tx.txid] = true
+        txidOnly.push(tx)
+      } else {
+        queue.push(tx)
+      }
+    }
+
+    // Hashtable of unknown input txids used to fund transactions without their own proof.
+    const missingInputs: Record<string, boolean> = {}
+    // transactions with one or more missing inputs
+    const txsMissingInputs: BeefTx[] = []
+
+    const possiblyMissingInputs = queue
+    queue = []
+
+    // all tx are isValid false, hasProof false.
+    // if isTxidOnly then has inputTxids
+    for (const tx of possiblyMissingInputs) {
+      let hasMissingInput = false
+
+      // For all the unproven transactions,
+      // link their inputs that exist in this beef,
+      // make a note of missing inputs.
+      for (const inputTxid of tx.inputTxids) {
+        if (txidToTx[inputTxid] === undefined) { // Explicitly check for undefined
+          missingInputs[inputTxid] = true
+          hasMissingInput = true
+        }
+      }
+
+      if (hasMissingInput) {
+        txsMissingInputs.push(tx)
+      } else {
+        queue.push(tx)
+      }
+    }
+
+    // As long as we have unsorted transactions...
+    while (queue.length > 0) {
+      const oldQueue = queue
+      queue = []
+      // all tx are isValid false, hasProof false.
+      // if isTxidOnly then has inputTxids
+      for (const tx of oldQueue) {
+        if (tx.inputTxids.every((txid) => validTxids[txid])) {
+          validTxids[tx.txid] = true
+          result.push(tx)
+        } else {
+          queue.push(tx)
+        }
+      }
+      if (oldQueue.length === queue.length) {
+        break
+      }
+    }
+
+    // transactions that don't have proofs and don't chain to proofs
+    const txsNotValid = queue
+
+    // New order of txs is unsortable (missing inputs or depends on missing inputs), txidOnly, sorted (so newest sorted is last)
+    this.txs = txsMissingInputs
+      .concat(txsNotValid)
+      .concat(txidOnly)
+      .concat(result)
+
+    this.needsSort = false
+    this.invalidateSerializationCaches()
+
+    return {
+      missingInputs: Object.keys(missingInputs),
+      notValid: txsNotValid.map((tx) => tx.txid),
+      valid: Object.keys(validTxids),
+      withMissingInputs: txsMissingInputs.map((tx) => tx.txid),
+      txidOnly: txidOnly.map((tx) => tx.txid)
+    }
+  }
+
+  /**
+   * @returns a shallow copy of this beef
+   */
+  clone (): Beef {
+    const c = new Beef()
+    c.version = this.version
+    c.bumps = Array.from(this.bumps)
+    c.txs = Array.from(this.txs)
+    c.txidIndex = undefined
+    c.needsSort = this.needsSort
+    return c
+  }
+
+  /**
+   * Ensure that all the txids in `knownTxids` are txidOnly
+   * @param knownTxids
+   */
+  trimKnownTxids (knownTxids: string[]): void {
+    let mutated = false
+    for (let i = 0; i < this.txs.length;) {
+      const tx = this.txs[i]
+      if (tx.isTxidOnly && knownTxids.includes(tx.txid)) {
+        this.deleteFromIndex(tx.txid)
+        this.txs.splice(i, 1)
+        mutated = true
+      } else {
+        i++
+      }
+    }
+    // TODO: bumps could be trimmed to eliminate unreferenced proofs.
+    if (mutated) {
+      this.markMutated(true)
+    }
+  }
+
+  /**
+   * @returns array of transaction txids that either have a proof or whose inputs chain back to a proven transaction.
+   */
+  getValidTxids (): string[] {
+    const r = this.sortTxs()
+    return r.valid
+  }
+
+  /**
+   * @returns Summary of `Beef` contents as multi-line string.
+   */
+  toLogString (): string {
+    let log = ''
+    log += `BEEF with ${this.bumps.length} BUMPS and ${this.txs.length} Transactions, isValid ${this.isValid().toString()}\n`
+    let i = -1
+
+    for (const b of this.bumps) {
+      i++
+      log += `  BUMP ${i}\n    block: ${b.blockHeight}\n    txids: [\n${b.path[0]
+        .filter((n) => n.txid === true) // ✅ Explicitly check if txid is `true`
+        .map((n) => `      '${n.hash ?? ''}'`)
+        .join(',\n')}\n    ]\n`
+    }
+
+    i = -1
+    for (const t of this.txs) {
+      i++
+      log += `  TX ${i}\n    txid: ${t.txid}\n`
+      if (t.bumpIndex !== undefined) {
+        log += `    bumpIndex: ${t.bumpIndex}\n`
+      }
+      if (t.isTxidOnly) {
+        log += '    txidOnly\n'
+      } else {
+        log += `    rawTx length=${t.rawTx?.length ?? 0}\n` // ✅ Fix applied here
+      }
+      if (t.inputTxids.length > 0) {
+        log += `    inputs: [\n${t.inputTxids
+          .map((it) => `      '${it}'`)
+          .join(',\n')}\n    ]\n`
+      }
+    }
+
+    return log
+  }
+
+  /**
+ * In some circumstances it may be helpful for the BUMP MerklePaths to include
+ * leaves that can be computed from row zero.
+ */
+  addComputedLeaves (): void {
+    const hash = (m: string): string =>
+      toHex(hash256(toArray(m, 'hex').reverse()).reverse())
+
+    for (const bump of this.bumps) { // ✅ Use `this` instead of `beef`
+      for (let row = 1; row < bump.path.length; row++) {
+        for (const leafL of bump.path[row - 1]) {
+          if (typeof leafL.hash === 'string' && (leafL.offset & 1) === 0) {
+            const leafR = bump.path[row - 1].find(
+              (l) => l.offset === leafL.offset + 1
+            )
+            const offsetOnRow = leafL.offset >> 1
+
+            if (
+              leafR !== undefined &&
+              typeof leafR.hash === 'string' &&
+              bump.path[row].every((l) => l.offset !== offsetOnRow)
+            ) {
+              // Computable leaf is missing... add it.
+              bump.path[row].push({
+                offset: offsetOnRow,
+                // String concatenation puts the right leaf on the left of the left leaf hash
+                hash: hash(leafR.hash + leafL.hash)
+              })
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+export default Beef