@bsv/sdk 2.0.16 → 2.1.1

package/dist/esm/src/transaction/Beef.js

@@ -2,15 +2,8 @@ import MerklePath from './MerklePath.js';
 import BeefTx from './BeefTx.js';
 import { 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 var TX_DATA_FORMAT;
-(function (TX_DATA_FORMAT) {
-    TX_DATA_FORMAT[TX_DATA_FORMAT["RAWTX"] = 0] = "RAWTX";
-    TX_DATA_FORMAT[TX_DATA_FORMAT["RAWTX_AND_BUMP_INDEX"] = 1] = "RAWTX_AND_BUMP_INDEX";
-    TX_DATA_FORMAT[TX_DATA_FORMAT["TXID_ONLY"] = 2] = "TXID_ONLY";
-})(TX_DATA_FORMAT || (TX_DATA_FORMAT = {}));
+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
  * https://github.com/bsv-blockchain/BRCs/blob/master/transactions/0062.md
@@ -88,7 +81,9 @@ export class Beef {
     }
     ensureSerializableState() {
         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;
         }
     }
     ensureSortedForSerialization() {
@@ -115,7 +110,7 @@ export class Beef {
             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();
+        const beef = (this.txs.at(-1) === tx) ? this : this.clone();
         if (beef !== this) {
             const i = this.txs.findIndex((t) => t.txid === txid);
             beef.txs.splice(i + 1);
@@ -175,8 +170,7 @@ export class Beef {
      * @returns `MerklePath` with level zero hash equal to txid or undefined.
      */
     findBump(txid) {
-        return this.bumps.find((b) => b.path[0].some((leaf) => leaf.hash === txid) // ✅ Ensure boolean return with `.some()`
-        );
+        return this.bumps.find((b) => b.path[0].some((leaf) => leaf.hash === txid));
     }
     /**
      * Finds a Transaction in this `Beef`
@@ -213,33 +207,39 @@ 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, tx) => {
-            const mp = beef.findBump(tx.id('hex'));
-            if (mp != null) {
-                tx.merklePath = mp;
+        this.addInputProof(beefTx.tx);
+        return beefTx.tx;
+    }
+    /** Recursively attach merkle paths and source transactions to all inputs. */
+    addInputProof(tx) {
+        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);
             }
-            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);
-                        }
-                    }
-                }
+        }
+    }
+    resolveInputSource(i) {
+        if (i.sourceTransaction == null) {
+            const itx = this.findTxid(verifyNotNull(i.sourceTXID, 'sourceTXID must be valid'));
+            if (itx != null) {
+                i.sourceTransaction = itx.tx;
             }
-        };
-        addInputProof(this, beefTx.tx); // Safe because we checked that beefTx.tx exists
-        return beefTx.tx;
+        }
+    }
+    attachMerklePathOrRecurse(sourceTx) {
+        const mp = this.findBump(sourceTx.id('hex'));
+        if (mp != null) {
+            sourceTx.merklePath = mp;
+        }
+        else {
+            this.addInputProof(sourceTx);
+        }
     }
     /**
      * Merge a MerklePath that is assumed to be fully valid.
@@ -248,46 +248,44 @@ export class Beef {
      */
     mergeBump(bump) {
         this.markMutated(false);
-        let bumpIndex;
-        // 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.
+        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) {
+            if (tx.bumpIndex == null) {
+                this.tryMarkTxProvenByBump(tx, b, bumpIndex);
+            }
+        }
+        return bumpIndex;
+    }
+    /**
+     * Find an existing compatible bump or insert a new one; return its index.
+     */
+    findOrInsertBump(bump) {
         for (let i = 0; i < this.bumps.length; i++) {
             const b = this.bumps[i];
-            if (b === bump) {
-                // Literally the same
+            if (b === bump)
+                return i;
+            if (b.blockHeight !== bump.blockHeight)
+                continue;
+            if (b.computeRoot() === bump.computeRoot()) {
+                b.combine(bump);
                 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;
-                    }
-                }
+        this.bumps.push(bump);
+        return this.bumps.length - 1;
+    }
+    /** If bump's level-0 path contains tx's txid, record the bumpIndex on tx. */
+    tryMarkTxProvenByBump(tx, b, bumpIndex) {
+        const txid = tx.txid;
+        for (const n of b.path[0]) {
+            if (n.hash === txid) {
+                tx.bumpIndex = bumpIndex;
+                n.txid = true;
+                break;
             }
         }
-        return bumpIndex;
     }
     /**
      * Merge a serialized transaction.
@@ -462,54 +460,74 @@ export class Beef {
         }
         // valid txids: only txids if allowed, bump txids, then txids with input's in txids
         const txids = {};
+        if (!this.collectTxidOnlyTxids(txids, allowTxidOnly))
+            return r;
+        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. */
+    collectTxidOnlyTxids(txids, allowTxidOnly) {
         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, txid) => {
-            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) {
+            if (!tx.isTxidOnly)
+                continue;
+            if (allowTxidOnly !== true)
                 return false;
-            }
-            return true;
-        };
+            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.
+     */
+    collectBumpTxids(txids, r) {
         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;
             }
         }
-        // All txs with a bumpIndex have matching txid leaf at level zero of BUMP.
+        return true;
+    }
+    /** Verify that every tx with a bumpIndex has a matching txid leaf in its bump. */
+    verifyBumpIndexLeaves() {
         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. */
+    verifyInputDependencies(txids) {
         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;
+                    return false;
             }
             txids[t.txid] = true;
         }
-        r.valid = true;
-        return r;
+        return true;
+    }
+    /** Confirm the computed merkle root for txid in bump matches previously accepted root for that height. */
+    confirmComputedRoot(b, txid, r) {
+        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;
     }
     /**
      * Serializes this data to `writer`
@@ -670,11 +688,37 @@ export class Beef {
         const validTxids = {};
         // Hashtable of all transaction txids to transaction
         const txidToTx = {};
-        // queue of unsorted transactions ...
-        let queue = [];
         // sorted transactions: hasProof to with longest dependency chain
         const result = [];
         const txidOnly = [];
+        // 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.
+     */
+    partitionTxs(txidToTx, validTxids, result, txidOnly) {
+        const queue = [];
         for (const tx of this.txs) {
             txidToTx[tx.txid] = tx;
             tx.isValid = tx.hasProof;
@@ -690,21 +734,19 @@ export class Beef {
                 queue.push(tx);
             }
         }
-        // Hashtable of unknown input txids used to fund transactions without their own proof.
+        return queue;
+    }
+    /**
+     * Separate queue entries that have at least one input txid not present in txidToTx.
+     */
+    separateMissingInputs(candidates, txidToTx) {
         const missingInputs = {};
-        // transactions with one or more missing inputs
         const txsMissingInputs = [];
-        const possiblyMissingInputs = queue;
-        queue = [];
-        // all tx are isValid false, hasProof false.
-        // if isTxidOnly then has inputTxids
-        for (const tx of possiblyMissingInputs) {
+        const remaining = [];
+        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;
                 }
@@ -713,15 +755,18 @@ export class Beef {
                 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.
+     */
+    topoSort(queue, validTxids, result) {
         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;
@@ -731,26 +776,10 @@ export class Beef {
                     queue.push(tx);
                 }
             }
-            if (oldQueue.length === queue.length) {
+            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)
-        };
+        return queue;
     }
     /**
      * @returns a shallow copy of this beef
@@ -771,6 +800,14 @@ export class Beef {
      * @param knownTxids
      */
     trimKnownTxids(knownTxids) {
+        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. */
+    removeKnownTxidOnlyTxs(knownTxids) {
         let mutated = false;
         for (let i = 0; i < this.txs.length;) {
             const tx = this.txs[i];
@@ -783,41 +820,43 @@ export class Beef {
                 i++;
             }
         }
-        // Trim unreferenced bumps after removing known txids
+        return mutated;
+    }
+    /**
+     * Remove bumps that are no longer referenced by any tx and update bumpIndex references.
+     * Returns true if any bumps were removed.
+     */
+    reindexBumps() {
         const referencedBumpIndices = new Set();
         for (const tx of this.txs) {
             if (tx.bumpIndex !== undefined) {
                 referencedBumpIndices.add(tx.bumpIndex);
             }
         }
-        // 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();
-            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));
-            // 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;
-                }
+        if (referencedBumpIndices.size >= this.bumps.length)
+            return false;
+        // Build mapping of old indices to new indices after removal
+        const indexMap = new Map();
+        let newIndex = 0;
+        for (let i = 0; i < this.bumps.length; i++) {
+            if (referencedBumpIndices.has(i)) {
+                indexMap.set(i, newIndex);
+                newIndex++;
             }
-            mutated = true;
         }
-        if (mutated) {
-            this.markMutated(true);
+        // 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)
+                continue;
+            const mapped = indexMap.get(tx.bumpIndex);
+            if (mapped === undefined) {
+                throw new Error(`Internal error: bumpIndex ${tx.bumpIndex} not found in indexMap`);
+            }
+            tx.bumpIndex = mapped;
         }
+        return true;
     }
     /**
      * @returns array of transaction txids that either have a proof or whose inputs chain back to a proven transaction.
@@ -836,7 +875,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`;
         }
@@ -851,7 +890,7 @@ export class Beef {
                 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
@@ -866,25 +905,29 @@ export class Beef {
    * leaves that can be computed from row zero.
    */
     addComputedLeaves() {
-        const hash = (m) => 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`. */
+    addComputedLeavesForRow(bump, row) {
+        const hashPair = (m) => 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)
+                });
             }
         }
     }