@bsv/sdk 1.1.29 → 1.1.32

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

@@ -1,9 +1,10 @@
-import MerklePath from "./MerklePath.js";
-import BeefTx from "./BeefTx.js";
-import { Reader, Writer, toHex, toArray } from "../primitives/utils.js";
+import MerklePath from './MerklePath.js';
+import BeefTx from './BeefTx.js';
+import { Reader, Writer, toHex, toArray } from '../primitives/utils.js';
 export const BEEF_MAGIC = 4022206465; // 0100BEEF in LE order
 export const BEEF_MAGIC_V2 = 4022206466; // 0200BEEF in LE order
 export const BEEF_MAGIC_TXID_ONLY_EXTENSION = 4022206465; // 0100BEEF in LE order
+export const ATOMIC_BEEF = 0x01010101; // Atomic Beef serialization prefix
 /*
  * BEEF standard: BRC-62: Background Evaluation Extended Format (BEEF) Transactions
  * https://github.com/bitcoin-sv/BRCs/blob/master/transactions/0062.md
@@ -11,6 +12,14 @@ export const BEEF_MAGIC_TXID_ONLY_EXTENSION = 4022206465; // 0100BEEF in LE orde
  * BUMP standard: BRC-74: BSV Unified Merkle Path (BUMP) Format
  * https://github.com/bitcoin-sv/BRCs/blob/master/transactions/0074.md
  *
+ * BRC-95: Atomic BEEF Transactions
+ * https://github.com/bitcoin-sv/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/bitcoin-sv/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
@@ -42,43 +51,121 @@ export const BEEF_MAGIC_TXID_ONLY_EXTENSION = 4022206465; // 0100BEEF in LE orde
  *
  * 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 = [];
     txs = [];
     version = undefined;
+    atomicTxid = undefined;
     constructor(version) {
         this.version = version;
     }
     /**
-     * BEEF_MAGIC is the original V1 version.
-     * BEEF_MAGIC_V2 includes support for txidOnly transactions in serialized beefs.
-     * @returns version magic value based on current contents and constructor version parameter.
-     */
+       * BEEF_MAGIC is the original V1 version.
+       * BEEF_MAGIC_V2 includes support for txidOnly transactions in serialized beefs.
+       * @returns version magic value based on current contents and constructor version parameter.
+       */
     get magic() {
-        if (this.version === 'V1')
+        if (this.version === 'V1') {
             return BEEF_MAGIC;
-        if (this.version === 'V2')
+        }
+        if (this.version === 'V2') {
             return BEEF_MAGIC_V2;
-        const hasTxidOnly = -1 < this.txs.findIndex(tx => tx.isTxidOnly);
-        if (hasTxidOnly)
+        }
+        const hasTxidOnly = this.txs.findIndex(tx => tx.isTxidOnly) > -1;
+        if (hasTxidOnly) {
             return BEEF_MAGIC_V2;
+        }
         return BEEF_MAGIC;
     }
     /**
-     * @param txid of `beefTx` to find
-     * @returns `BeefTx` in `txs` with `txid`.
-     */
+       * @param txid of `beefTx` to find
+       * @returns `BeefTx` in `txs` with `txid`.
+       */
     findTxid(txid) {
         return this.txs.find(tx => tx.txid === txid);
     }
     /**
-     * Merge a MerklePath that is assumed to be fully valid.
-     * @param bump
-     * @returns index of merged bump
+     * @returns `MerklePath` with level zero hash equal to txid or undefined.
+     */
+    findBump(txid) {
+        return this.bumps.find(b => b.path[0].find(leaf => leaf.hash === txid));
+    }
+    /**
+     * 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) {
+        const beefTx = this.findTxid(txid);
+        if (!beefTx)
+            return undefined;
+        for (const i of beefTx.tx.inputs) {
+            if (!i.sourceTransaction) {
+                const itx = this.findTxid(i.sourceTXID);
+                if (itx) {
+                    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) {
+        const beefTx = this.findTxid(txid);
+        if (!beefTx)
+            return undefined;
+        const addInputProof = (beef, tx) => {
+            const mp = beef.findBump(tx.id('hex'));
+            if (mp)
+                tx.merklePath = mp;
+            else {
+                for (const i of tx.inputs) {
+                    if (!i.sourceTransaction) {
+                        const itx = beef.findTxid(i.sourceTXID);
+                        if (itx) {
+                            i.sourceTransaction = itx.tx;
+                        }
+                    }
+                    if (i.sourceTransaction) {
+                        const mp = beef.findBump(i.sourceTransaction.id('hex'));
+                        if (mp) {
+                            i.sourceTransaction.merklePath = mp;
+                        }
+                        else {
+                            addInputProof(beef, i.sourceTransaction);
+                        }
+                    }
+                }
+            }
+        };
+        addInputProof(this, beefTx.tx);
+        return beefTx.tx;
+    }
+    /**
+       * Merge a MerklePath that is assumed to be fully valid.
+       * @param bump
+       * @returns index of merged bump
+       */
     mergeBump(bump) {
-        let bumpIndex = undefined;
+        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.
         for (let i = 0; i < this.bumps.length; i++) {
             const b = this.bumps[i];
@@ -119,16 +206,16 @@ export class Beef {
         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
-     */
+       * 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, bumpIndex) {
         const newTx = new BeefTx(rawTx, bumpIndex);
         this.removeExistingTxid(newTx.txid);
@@ -137,45 +224,49 @@ export class Beef {
         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
-     */
+       * 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) {
         const txid = tx.id('hex');
         this.removeExistingTxid(txid);
-        let bumpIndex = undefined;
-        if (tx.merklePath)
+        let bumpIndex;
+        if (tx.merklePath) {
             bumpIndex = this.mergeBump(tx.merklePath);
+        }
         const newTx = new BeefTx(tx, bumpIndex);
         this.txs.push(newTx);
         this.tryToValidateBumpIndex(newTx);
         bumpIndex = newTx.bumpIndex;
         if (bumpIndex === undefined) {
             for (const input of tx.inputs) {
-                if (input.sourceTransaction)
+                if (input.sourceTransaction) {
                     this.mergeTransaction(input.sourceTransaction);
+                }
             }
         }
         return newTx;
     }
     /**
-     * Removes an existing transaction from the BEEF, given its TXID
-     * @param txid TXID of the transaction to remove
-     */
+       * Removes an existing transaction from the BEEF, given its TXID
+       * @param txid TXID of the transaction to remove
+       */
     removeExistingTxid(txid) {
         const existingTxIndex = this.txs.findIndex(t => t.txid === txid);
-        if (existingTxIndex >= 0)
+        if (existingTxIndex >= 0) {
             this.txs.splice(existingTxIndex, 1);
+        }
     }
     mergeTxidOnly(txid) {
-        if (this.version === 'V1')
-            throw new Error(`BEEF V1 format does not support txid only transactions.`);
+        if (this.version === 'V1') {
+            throw new Error('BEEF V1 format does not support txid only transactions.');
+        }
         let tx = this.txs.find(t => t.txid === txid);
         if (!tx) {
             tx = new BeefTx(txid);
@@ -186,61 +277,67 @@ export class Beef {
     }
     mergeBeefTx(btx) {
         let beefTx = this.findTxid(btx.txid);
-        if (!beefTx && btx.isTxidOnly)
+        if (!beefTx && btx.isTxidOnly) {
             beefTx = this.mergeTxidOnly(btx.txid);
+        }
         else if (!beefTx || beefTx.isTxidOnly) {
-            if (btx._tx)
+            if (btx._tx) {
                 beefTx = this.mergeTransaction(btx._tx);
-            else
+            }
+            else {
                 beefTx = this.mergeRawTx(btx._rawTx);
+            }
         }
         return beefTx;
     }
     mergeBeef(beef) {
         const b = Array.isArray(beef) ? Beef.fromBinary(beef) : beef;
-        for (const bump of b.bumps)
+        for (const bump of b.bumps) {
             this.mergeBump(bump);
-        for (const tx of b.txs)
+        }
+        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
-     */
+       * 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) {
         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
-     */
+       * 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, allowTxidOnly) {
         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)
+            if (!isValid) {
                 return false;
+            }
         }
         return true;
     }
@@ -262,8 +359,9 @@ export class Beef {
                 // 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 (r.roots[b.blockHeight] !== root) {
                 return false;
+            }
             return true;
         };
         for (const b of this.bumps) {
@@ -271,25 +369,28 @@ export class Beef {
                 if (n.txid && n.hash) {
                     txids[n.hash] = true;
                     // all txid hashes in all bumps must have agree on computed merkle path roots
-                    if (!confirmComputedRoot(b, n.hash))
+                    if (!confirmComputedRoot(b, n.hash)) {
                         return r;
+                    }
                 }
             }
         }
         for (const t of this.txs) {
-            for (const i of t.inputTxids)
-                // all input txids must be included before they are referenced
+            for (const i of t.inputTxids) 
+            // all input txids must be included before they are referenced
+            {
                 if (!txids[i])
                     return r;
+            }
             txids[t.txid] = true;
         }
         r.valid = true;
         return r;
     }
     /**
-     * Returns a binary array representing the serialized BEEF
-     * @returns A binary array representing the BEEF
-     */
+       * Returns a binary array representing the serialized BEEF
+       * @returns A binary array representing the BEEF
+       */
     toBinary() {
         const writer = new Writer();
         writer.writeUInt32LE(this.magic);
@@ -304,16 +405,23 @@ export class Beef {
         return writer.toArray();
     }
     /**
-     * Returns a hex string representing the serialized BEEF
-     * @returns A hex string representing the BEEF
-     */
+       * Returns a hex string representing the serialized BEEF
+       * @returns A hex string representing the BEEF
+       */
     toHex() {
         return toHex(this.toBinary());
     }
     static fromReader(br) {
-        const version = br.readUInt32LE();
-        if (version !== BEEF_MAGIC && version !== BEEF_MAGIC_V2)
+        let version = br.readUInt32LE();
+        let atomicTxid = 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_MAGIC && version !== BEEF_MAGIC_V2) {
             throw new Error(`Serialized BEEF must start with ${BEEF_MAGIC} or ${BEEF_MAGIC_V2} but starts with ${version}`);
+        }
         const beef = new Beef(version === BEEF_MAGIC_V2 ? 'V2' : undefined);
         const bumpsLength = br.readVarIntNum();
         for (let i = 0; i < bumpsLength; i++) {
@@ -325,23 +433,24 @@ export class Beef {
             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
-     */
+       * 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) {
         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
-     */
+       * 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, enc) {
         enc ||= 'hex';
         const bin = toArray(s, enc);
@@ -349,15 +458,16 @@ export class Beef {
         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
-     */
+       * 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
+       */
     tryToValidateBumpIndex(newTx) {
-        if (newTx.bumpIndex !== undefined)
+        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);
@@ -370,71 +480,91 @@ export class Beef {
         return false;
     }
     /**
-     * Sort the `txs` by input txid dependency order.
-     * @returns array of input txids of unproven transactions that aren't included in txs.
-     */
+       * Sort the `txs` by input txid dependency order:
+       * - Oldest Tx Anchored by Path
+       * - Newer Txs depending on Older parents
+       * - Newest Tx
+       *
+       * with proof (MerklePath) last, longest chain of dependencies first
+       *
+       * @returns `{ missingInputs, notValid, valid, withMissingInputs }`
+       */
     sortTxs() {
-        const missingInputs = {};
+        // Hashtable of valid txids (with proof or all inputs chain to proof)
+        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 = [];
         for (const tx of this.txs) {
             txidToTx[tx.txid] = tx;
-            // All transactions in this beef start at degree zero.
-            tx.degree = 0;
+            tx.isValid = tx.hasProof;
+            if (tx.isValid) {
+                validTxids[tx.txid] = true;
+                result.push(tx);
+            }
+            else if (tx.isTxidOnly)
+                txidOnly.push(tx);
+            else
+                queue.push(tx);
         }
-        for (const tx of this.txs) {
-            if (tx.bumpIndex === undefined) {
+        // Hashtable of unknown input txids used to fund transactions without their own proof.
+        const missingInputs = {};
+        // transactions with one or more missing inputs
+        const txsMissingInputs = [];
+        const possiblyMissingInputs = queue;
+        queue = [];
+        for (const tx of possiblyMissingInputs) {
+            let hasMissingInput = false;
+            if (!tx.isValid) {
                 // 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])
+                    if (!txidToTx[inputTxid]) {
                         missingInputs[inputTxid] = true;
+                        hasMissingInput = true;
+                    }
                 }
             }
-        }
-        // queue of transactions that no unsorted transactions depend upon...
-        const queue = [];
-        // sorted transactions
-        const result = [];
-        // Increment each txid's degree for every input reference to it by another txid
-        for (const tx of this.txs) {
-            for (const inputTxid of tx.inputTxids) {
-                const tx = txidToTx[inputTxid];
-                if (tx)
-                    tx.degree++;
-            }
-        }
-        // Since circular dependencies aren't possible, start with the txids no one depends on.
-        // These are the transactions that should be sent last...
-        for (const tx of this.txs) {
-            if (tx.degree === 0) {
+            if (hasMissingInput)
+                txsMissingInputs.push(tx);
+            else
                 queue.push(tx);
-            }
         }
-        // As long as we have transactions to send...
-        while (queue.length) {
-            let tx = queue.shift();
-            // Add it as new first to send
-            result.unshift(tx);
-            // And remove its impact on degree
-            // noting that any tx achieving a
-            // value of zero can be sent...
-            for (const inputTxid of tx.inputTxids) {
-                const inputTx = txidToTx[inputTxid];
-                if (inputTx) {
-                    inputTx.degree--;
-                    if (inputTx.degree === 0) {
-                        queue.push(inputTx);
-                    }
+        // As long as we have unsorted transactions...
+        while (queue.length > 0) {
+            const oldQueue = queue;
+            queue = [];
+            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;
         }
-        this.txs = result;
-        return Object.keys(missingInputs);
+        // transactions that don't have proofs and don't chain to proofs
+        const txsNotValid = queue;
+        // New order of txs is sorted, unsortable, txidOnly (no raw transaction)
+        this.txs = result.concat(queue).concat(txidOnly).concat(txsMissingInputs);
+        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
-     */
+       * @returns a shallow copy of this beef
+       */
     clone() {
         const c = new Beef();
         c.bumps = Array.from(this.bumps);
@@ -442,13 +572,13 @@ export class Beef {
         return c;
     }
     /**
-     * Ensure that all the txids in `knownTxids` are txidOnly
-     * @param knownTxids
-     */
+       * Ensure that all the txids in `knownTxids` are txidOnly
+       * @param knownTxids
+       */
     trimKnownTxids(knownTxids) {
         for (let i = 0; i < this.txs.length;) {
             const tx = this.txs[i];
-            if (tx.isTxidOnly && -1 < knownTxids.indexOf(tx.txid)) {
+            if (tx.isTxidOnly && knownTxids.includes(tx.txid)) {
                 this.txs.splice(i, 1);
             }
             else {
@@ -458,8 +588,15 @@ export class Beef {
         // TODO: bumps could be trimmed to eliminate unreferenced proofs.
     }
     /**
-     * @returns Summary of `Beef` contents as multi-line string.
+     * @returns array of transaction txids that either have a proof or whose inputs chain back to a proven transaction.
      */
+    getValidTxids() {
+        const r = this.sortTxs();
+        return r.valid;
+    }
+    /**
+       * @returns Summary of `Beef` contents as multi-line string.
+       */
     toLogString() {
         let log = '';
         log += `BEEF with ${this.bumps.length} BUMPS and ${this.txs.length} Transactions, isValid ${this.isValid()}\n`;
@@ -476,7 +613,7 @@ export class Beef {
                 log += `    bumpIndex: ${t.bumpIndex}\n`;
             }
             if (t.isTxidOnly) {
-                log += `    txidOnly\n`;
+                log += '    txidOnly\n';
             }
             else {
                 log += `    rawTx length=${t.rawTx.length}\n`;