@bsv/sdk 2.0.16 → 2.1.1

package/src/transaction/Beef.ts

@@ -4,15 +4,8 @@ import ChainTracker from './ChainTracker.js'
 import BeefTx from './BeefTx.js'
 import { Reader, Writer, toHex, toArray, verifyNotNull, ReaderUint8Array, WriterUint8Array, toUint8Array } from '../primitives/utils.js'
 import { hash256 } from '../primitives/Hash.js'
-
-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
-}
+import { BEEF_V1, BEEF_V2, ATOMIC_BEEF } from './BeefConstants.js'
+export { BEEF_V1, BEEF_V2, ATOMIC_BEEF, TX_DATA_FORMAT } from './BeefConstants.js'
 
 /*
  * BEEF standard: BRC-62: Background Evaluation Extended Format (BEEF) Transactions
@@ -95,7 +88,9 @@ export class Beef {
 
   private ensureSerializableState (): void {
     for (const tx of this.txs) {
-      void tx.txid
+      // Access txid to ensure it is computed before serialization
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      tx.txid
     }
   }
 
@@ -126,7 +121,7 @@ export class Beef {
     }
 
     // If the transaction is not the last one, clone and modify
-    const beef = (this.txs[this.txs.length - 1] === tx) ? this : this.clone()
+    const beef = (this.txs.at(-1) === tx) ? this : this.clone()
 
     if (beef !== this) {
       const i = this.txs.findIndex((t) => t.txid === txid)
@@ -195,7 +190,7 @@ export class Beef {
    */
   findBump (txid: string): MerklePath | undefined {
     return this.bumps.find((b) =>
-      b.path[0].some((leaf) => leaf.hash === txid) // ✅ Ensure boolean return with `.some()`
+      b.path[0].some((leaf) => leaf.hash === txid)
     )
   }
 
@@ -236,33 +231,42 @@ export class Beef {
     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)
-            }
-          }
-        }
+    this.addInputProof(beefTx.tx)
+
+    return beefTx.tx
+  }
+
+  /** Recursively attach merkle paths and source transactions to all inputs. */
+  private addInputProof (tx: Transaction): void {
+    const mp = this.findBump(tx.id('hex'))
+    if (mp != null) {
+      tx.merklePath = mp
+      return
+    }
+    for (const i of tx.inputs) {
+      this.resolveInputSource(i)
+      if (i.sourceTransaction != null) {
+        this.attachMerklePathOrRecurse(i.sourceTransaction)
       }
     }
+  }
 
-    addInputProof(this, beefTx.tx) // Safe because we checked that beefTx.tx exists
+  private resolveInputSource (i: Transaction['inputs'][number]): void {
+    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
+  private attachMerklePathOrRecurse (sourceTx: Transaction): void {
+    const mp = this.findBump(sourceTx.id('hex'))
+    if (mp != null) {
+      sourceTx.merklePath = mp
+    } else {
+      this.addInputProof(sourceTx)
+    }
   }
 
   /**
@@ -272,52 +276,48 @@ export class Beef {
    */
   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)
-    }
+    const bumpIndex = this.findOrInsertBump(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
-          }
-        }
+      if (tx.bumpIndex == null) {
+        this.tryMarkTxProvenByBump(tx, b, bumpIndex)
       }
     }
 
     return bumpIndex
   }
 
+  /**
+   * Find an existing compatible bump or insert a new one; return its index.
+   */
+  private findOrInsertBump (bump: MerklePath): number {
+    for (let i = 0; i < this.bumps.length; i++) {
+      const b = this.bumps[i]
+      if (b === bump) return i
+      if (b.blockHeight !== bump.blockHeight) continue
+      if (b.computeRoot() === bump.computeRoot()) {
+        b.combine(bump)
+        return i
+      }
+    }
+    this.bumps.push(bump)
+    return this.bumps.length - 1
+  }
+
+  /** If bump's level-0 path contains tx's txid, record the bumpIndex on tx. */
+  private tryMarkTxProvenByBump (tx: BeefTx, b: MerklePath, bumpIndex: number): void {
+    const txid = tx.txid
+    for (const n of b.path[0]) {
+      if (n.hash === txid) {
+        tx.bumpIndex = bumpIndex
+        n.txid = true
+        break
+      }
+    }
+  }
+
   /**
    * Merge a serialized transaction.
    *
@@ -514,56 +514,72 @@ export class Beef {
     // 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
-      }
-    }
+    if (!this.collectTxidOnlyTxids(txids, allowTxidOnly)) return r
 
-    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
+    if (!this.collectBumpTxids(txids, r)) return r
+
+    if (!this.verifyBumpIndexLeaves()) return r
+
+    if (!this.verifyInputDependencies(txids)) return r
+
+    r.valid = true
+    return r
+  }
+
+  /** Add txidOnly transaction txids; return false if not allowed. */
+  private collectTxidOnlyTxids (txids: Record<string, boolean>, allowTxidOnly?: boolean): boolean {
+    for (const tx of this.txs) {
+      if (!tx.isTxidOnly) continue
+      if (allowTxidOnly !== true) return false
+      txids[tx.txid] = true
     }
+    return true
+  }
 
+  /**
+   * Record txids proven by bumps; validate all bump roots agree per block height.
+   * Returns false if any root conflict is detected.
+   */
+  private collectBumpTxids (txids: Record<string, boolean>, r: { valid: boolean, roots: Record<number, string> }): boolean {
     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
-          }
-        }
+        if (n.txid !== true || typeof n.hash !== 'string' || n.hash.length === 0) continue
+        txids[n.hash] = true
+        if (!this.confirmComputedRoot(b, n.hash, r)) return false
       }
     }
+    return true
+  }
 
-    // All txs with a bumpIndex have matching txid leaf at level zero of BUMP.
+  /** Verify that every tx with a bumpIndex has a matching txid leaf in its bump. */
+  private verifyBumpIndexLeaves (): boolean {
     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 }
-      }
+      if (t.bumpIndex === undefined) continue
+      const leaf = this.bumps[t.bumpIndex].path[0].find(l => l.hash === t.txid)
+      if (leaf == null) return false
     }
+    return true
+  }
 
+  /** Verify all input txids appear before the spending tx in sorted order. */
+  private verifyInputDependencies (txids: Record<string, boolean>): boolean {
     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
+        if (!txids[i]) return false
       }
       txids[t.txid] = true
     }
+    return true
+  }
 
-    r.valid = true
-    return r
+  /** Confirm the computed merkle root for txid in bump matches previously accepted root for that height. */
+  private confirmComputedRoot (b: MerklePath, txid: string, r: { valid: boolean, roots: Record<number, 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
+    }
+    return r.roots[b.blockHeight] === root
   }
 
   /**
@@ -747,14 +763,49 @@ export class Beef {
     // 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[] = []
 
+    // Partition into proven, txidOnly, and remaining queue
+    let queue = this.partitionTxs(txidToTx, validTxids, result, txidOnly)
+
+    // Separate queue entries that have missing inputs
+    const { txsMissingInputs, missingInputs, remaining } = this.separateMissingInputs(queue, txidToTx)
+    queue = remaining
+
+    // Topological sort of remaining queue
+    const txsNotValid = this.topoSort(queue, validTxids, result)
+
+    // 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)
+    }
+  }
+
+  /**
+   * Partition txs into proven (result), txidOnly, and a queue of the rest.
+   * Populates txidToTx and validTxids as side-effects.
+   */
+  private partitionTxs (
+    txidToTx: Record<string, BeefTx>,
+    validTxids: Record<string, boolean>,
+    result: BeefTx[],
+    txidOnly: BeefTx[]
+  ): BeefTx[] {
+    const queue: BeefTx[] = []
     for (const tx of this.txs) {
       txidToTx[tx.txid] = tx
       tx.isValid = tx.hasProof
@@ -768,43 +819,45 @@ export class Beef {
         queue.push(tx)
       }
     }
+    return queue
+  }
 
-    // Hashtable of unknown input txids used to fund transactions without their own proof.
+  /**
+   * Separate queue entries that have at least one input txid not present in txidToTx.
+   */
+  private separateMissingInputs (
+    candidates: BeefTx[],
+    txidToTx: Record<string, BeefTx>
+  ): { txsMissingInputs: BeefTx[], missingInputs: Record<string, boolean>, remaining: BeefTx[] } {
     const missingInputs: Record<string, boolean> = {}
-    // transactions with one or more missing inputs
     const txsMissingInputs: BeefTx[] = []
+    const remaining: BeefTx[] = []
 
-    const possiblyMissingInputs = queue
-    queue = []
-
-    // all tx are isValid false, hasProof false.
-    // if isTxidOnly then has inputTxids
-    for (const tx of possiblyMissingInputs) {
+    for (const tx of candidates) {
       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
+        if (txidToTx[inputTxid] === undefined) {
           missingInputs[inputTxid] = true
           hasMissingInput = true
         }
       }
-
       if (hasMissingInput) {
         txsMissingInputs.push(tx)
       } else {
-        queue.push(tx)
+        remaining.push(tx)
       }
     }
 
-    // As long as we have unsorted transactions...
+    return { txsMissingInputs, missingInputs, remaining }
+  }
+
+  /**
+   * Topologically sort queue into result; return anything that cannot be sorted.
+   */
+  private topoSort (queue: BeefTx[], validTxids: Record<string, boolean>, result: BeefTx[]): BeefTx[] {
     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
@@ -813,30 +866,9 @@ export class Beef {
           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)
+      if (oldQueue.length === queue.length) break
     }
+    return queue
   }
 
   /**
@@ -859,6 +891,15 @@ export class Beef {
    * @param knownTxids
    */
   trimKnownTxids (knownTxids: string[]): void {
+    let mutated = this.removeKnownTxidOnlyTxs(knownTxids)
+    mutated = this.reindexBumps() || mutated
+    if (mutated) {
+      this.markMutated(true)
+    }
+  }
+
+  /** Remove txidOnly entries that appear in knownTxids; return true if any were removed. */
+  private removeKnownTxidOnlyTxs (knownTxids: string[]): boolean {
     let mutated = false
     for (let i = 0; i < this.txs.length;) {
       const tx = this.txs[i]
@@ -870,8 +911,14 @@ export class Beef {
         i++
       }
     }
+    return mutated
+  }
 
-    // Trim unreferenced bumps after removing known txids
+  /**
+   * Remove bumps that are no longer referenced by any tx and update bumpIndex references.
+   * Returns true if any bumps were removed.
+   */
+  private reindexBumps (): boolean {
     const referencedBumpIndices = new Set<number>()
     for (const tx of this.txs) {
       if (tx.bumpIndex !== undefined) {
@@ -879,38 +926,32 @@ export class Beef {
       }
     }
 
-    // Check if there are any unreferenced bumps to remove
-    if (referencedBumpIndices.size < this.bumps.length) {
-      // Build mapping of old indices to new indices after removal
-      const indexMap = new Map<number, number>()
-      let newIndex = 0
-      for (let i = 0; i < this.bumps.length; i++) {
-        if (referencedBumpIndices.has(i)) {
-          indexMap.set(i, newIndex)
-          newIndex++
-        }
+    if (referencedBumpIndices.size >= this.bumps.length) return false
+
+    // Build mapping of old indices to new indices after removal
+    const indexMap = new Map<number, number>()
+    let newIndex = 0
+    for (let i = 0; i < this.bumps.length; i++) {
+      if (referencedBumpIndices.has(i)) {
+        indexMap.set(i, newIndex)
+        newIndex++
       }
+    }
 
-      // Remove unreferenced bumps
-      this.bumps = this.bumps.filter((_, i) => referencedBumpIndices.has(i))
+    // Remove unreferenced bumps
+    this.bumps = this.bumps.filter((_, i) => referencedBumpIndices.has(i))
 
-      // Update all transaction bumpIndex references
-      for (const tx of this.txs) {
-        if (tx.bumpIndex !== undefined) {
-          const newIndex = indexMap.get(tx.bumpIndex)
-          if (newIndex === undefined) {
-            throw new Error(`Internal error: bumpIndex ${tx.bumpIndex} not found in indexMap`)
-          }
-          tx.bumpIndex = newIndex
-        }
+    // Update all transaction bumpIndex references
+    for (const tx of this.txs) {
+      if (tx.bumpIndex === undefined) continue
+      const mapped = indexMap.get(tx.bumpIndex)
+      if (mapped === undefined) {
+        throw new Error(`Internal error: bumpIndex ${tx.bumpIndex} not found in indexMap`)
       }
-
-      mutated = true
+      tx.bumpIndex = mapped
     }
 
-    if (mutated) {
-      this.markMutated(true)
-    }
+    return true
   }
 
   /**
@@ -932,7 +973,7 @@ export class Beef {
     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`
+        .filter((n) => n.txid === true)
         .map((n) => `      '${n.hash ?? ''}'`)
         .join(',\n')}\n    ]\n`
     }
@@ -947,7 +988,7 @@ export class Beef {
       if (t.isTxidOnly) {
         log += '    txidOnly\n'
       } else {
-        log += `    rawTx length=${t.rawTx?.length ?? 0}\n` // ✅ Fix applied here
+        log += `    rawTx length=${t.rawTx?.length ?? 0}\n`
       }
       if (t.inputTxids.length > 0) {
         log += `    inputs: [\n${t.inputTxids
@@ -964,32 +1005,29 @@ export class Beef {
  * 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 (const bump of this.bumps) {
       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)
-              })
-            }
-          }
-        }
+        this.addComputedLeavesForRow(bump, row)
+      }
+    }
+  }
+
+  /** Add any missing computable leaf at `row` derived from two known leaves at `row - 1`. */
+  private addComputedLeavesForRow (bump: MerklePath, row: number): void {
+    const hashPair = (m: string): string =>
+      toHex(hash256(toArray(m, 'hex').reverse()).reverse())
+    for (const leafL of bump.path[row - 1]) {
+      if (typeof leafL.hash !== 'string' || (leafL.offset & 1) !== 0) continue
+      const leafR = bump.path[row - 1].find((l) => l.offset === leafL.offset + 1)
+      if (leafR === undefined || typeof leafR.hash !== 'string') continue
+      const offsetOnRow = leafL.offset >> 1
+      if (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: hashPair(leafR.hash + leafL.hash)
+        })
       }
     }
   }

package/src/transaction/BeefConstants.ts

@@ -0,0 +1,16 @@
+/**
+ * BEEF format constants extracted to avoid the Beef.ts <-> BeefTx.ts circular import.
+ *
+ * BEEF standard: BRC-62: Background Evaluation Extended Format (BEEF) Transactions
+ * https://github.com/bsv-blockchain/BRCs/blob/master/transactions/0062.md
+ */
+
+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
+}

package/src/transaction/BeefTx.ts

@@ -1,7 +1,7 @@
 import { hash256 } from '../primitives/Hash.js'
 import { Reader, Writer, toHex, toArray, ReaderUint8Array, WriterUint8Array } from '../primitives/utils.js'
 import Transaction from './Transaction.js'
-import { BEEF_V2, TX_DATA_FORMAT } from './Beef.js'
+import { BEEF_V2, TX_DATA_FORMAT } from './BeefConstants.js'
 
 /**
  * A single bitcoin transaction associated with a `Beef` validity proof set.
@@ -105,7 +105,7 @@ export default class BeefTx {
     } else if (tx instanceof Transaction) {
       this._tx = tx
     } else {
-      throw new Error('Invalid transaction data type')
+      throw new TypeError('Invalid transaction data type')
     }
     this.bumpIndex = bumpIndex
     this.updateInputTxids()
@@ -204,7 +204,7 @@ export default class BeefTx {
     } else {
       // V1
       data = Transaction.fromReader(br)
-      bumpIndex = br.readUInt8() !== 0 ? br.readVarIntNum() : undefined
+      bumpIndex = br.readUInt8() === 0 ? undefined : br.readVarIntNum()
       beefTx = BeefTx.fromTx(data, bumpIndex)
     }