@bsv/sdk 1.1.30 → 1.1.32

package/docs/transaction.md

@@ -857,7 +857,7 @@ export default class BeefTx {
     _rawTx?: number[];
     _txid?: string;
     inputTxids: string[] = [];
-    degree: number = 0;
+    isValid?: boolean = undefined;
     get bumpIndex(): number | undefined 
     set bumpIndex(v: number | undefined) 
     get hasProof(): boolean 
@@ -888,6 +888,16 @@ Argument Details
 + **bumpIndex**
   + If transaction already has a proof in the beef to which it will be added.
 
+#### Property isValid
+
+true if `hasProof` or all inputs chain to `hasProof`.
+
+Typically set by sorting transactions by proven dependency chains.
+
+```ts
+isValid?: boolean = undefined
+```
+
 </details>
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
@@ -900,9 +910,13 @@ export class Beef {
     bumps: MerklePath[] = [];
     txs: BeefTx[] = [];
     version: BeefVersion = undefined;
+    atomicTxid: string | undefined = undefined;
     constructor(version?: BeefVersion) 
     get magic(): number 
     findTxid(txid: string): BeefTx | undefined 
+    findBump(txid: string): MerklePath | undefined 
+    findTransactionForSigning(txid: string): Transaction | undefined 
+    findAtomicTransaction(txid: string): Transaction | undefined 
     mergeBump(bump: MerklePath): number 
     mergeRawTx(rawTx: number[], bumpIndex?: number): BeefTx 
     mergeTransaction(tx: Transaction): BeefTx 
@@ -917,9 +931,16 @@ export class Beef {
     static fromReader(br: Reader): Beef 
     static fromBinary(bin: number[]): Beef 
     static fromString(s: string, enc?: "hex" | "utf8" | "base64"): Beef 
-    sortTxs(): string[] 
+    sortTxs(): {
+        missingInputs: string[];
+        notValid: string[];
+        valid: string[];
+        withMissingInputs: string[];
+        txidOnly: string[];
+    } 
     clone(): Beef 
     trimKnownTxids(knownTxids: string[]) 
+    getValidTxids(): string[] 
     toLogString(): string 
 }
 ```
@@ -938,6 +959,55 @@ Returns
 
 a shallow copy of this beef
 
+#### Method findAtomicTransaction
+
+Builds the proof tree rooted at a specific `Transaction`.
+
+To succeed, the Beef must contain all the required transaction and merkle path data.
+
+```ts
+findAtomicTransaction(txid: string): Transaction | undefined 
+```
+
+Returns
+
+Transaction with input `SourceTransaction` and `MerklePath` populated from this Beef.
+
+Argument Details
+
++ **txid**
+  + The id of the target transaction.
+
+#### Method findBump
+
+```ts
+findBump(txid: string): MerklePath | undefined 
+```
+
+Returns
+
+`MerklePath` with level zero hash equal to txid or undefined.
+
+#### Method findTransactionForSigning
+
+Finds a Transaction in this `Beef`
+and adds any missing input SourceTransactions from this `Beef`.
+
+The result is suitable for signing.
+
+```ts
+findTransactionForSigning(txid: string): Transaction | undefined 
+```
+
+Returns
+
+Transaction with all available input `SourceTransaction`s from this Beef.
+
+Argument Details
+
++ **txid**
+  + The id of the target transaction.
+
 #### Method findTxid
 
 ```ts
@@ -989,6 +1059,16 @@ Argument Details
 + **enc**
   + The encoding of the string value from which BEEF should be constructed
 
+#### Method getValidTxids
+
+```ts
+getValidTxids(): string[] 
+```
+
+Returns
+
+array of transaction txids that either have a proof or whose inputs chain back to a proven transaction.
+
 #### Method isValid
 
 Sorts `txs` and checks structural validity of beef.
@@ -1074,15 +1154,26 @@ Argument Details
 
 #### Method sortTxs
 
-Sort the `txs` by input txid dependency order.
+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
 
 ```ts
-sortTxs(): string[] 
+sortTxs(): {
+    missingInputs: string[];
+    notValid: string[];
+    valid: string[];
+    withMissingInputs: string[];
+    txidOnly: string[];
+} 
 ```
 
 Returns
 
-array of input txids of unproven transactions that aren't included in txs.
+`{ missingInputs, notValid, valid, withMissingInputs }`
 
 #### Method toBinary
 
@@ -1219,8 +1310,8 @@ export default class Transaction {
     id(enc: "hex"): string;
     id(enc?: "hex"): number[] | string 
     async verify(chainTracker: ChainTracker | "scripts only" = defaultChainTracker(), feeModel?: FeeModel): Promise<boolean> 
-    toBEEF(): number[] 
-    toAtomicBEEF(): number[] 
+    toBEEF(allowPartial?: boolean): number[] 
+    toAtomicBEEF(allowPartial?: boolean): number[] 
 }
 ```
 
@@ -1554,25 +1645,43 @@ and then the BEEF data containing only the subject transaction and its dependenc
 This format ensures that the BEEF structure is atomic and contains no unrelated transactions.
 
 ```ts
-toAtomicBEEF(): number[] 
+toAtomicBEEF(allowPartial?: boolean): number[] 
 ```
 
 Returns
 
 - The serialized Atomic BEEF structure.
 
+Argument Details
+
++ **allowPartial**
+  + If true, error will not be thrown if there are any missing sourceTransactions.
+
+Throws
+
+Error if there are any missing sourceTransactions unless `allowPartial` is true.
+
 #### Method toBEEF
 
 Serializes this transaction, together with its inputs and the respective merkle proofs, into the BEEF (BRC-62) format. This enables efficient verification of its compliance with the rules of SPV.
 
 ```ts
-toBEEF(): number[] 
+toBEEF(allowPartial?: boolean): number[] 
 ```
 
 Returns
 
 The serialized BEEF structure
 
+Argument Details
+
++ **allowPartial**
+  + If true, error will not be thrown if there are any missing sourceTransactions.
+
+Throws
+
+Error if there are any missing sourceTransactions unless `allowPartial` is true.
+
 #### Method toBinary
 
 Converts the transaction to a binary array format.
@@ -1716,6 +1825,7 @@ export class BeefParty extends Beef {
     getKnownTxidsForParty(party: string): string[] 
     getTrimmedBeefForParty(party: string): Beef 
     addKnownTxidsForParty(party: string, knownTxids: string[]) 
+    mergeBeefFromParty(party: string, beef: number[] | Beef) 
 }
 ```
 
@@ -1794,6 +1904,18 @@ Returns
 
 `true` if `party` has already beed added to this `BeefParty`.
 
+#### Method mergeBeefFromParty
+
+Merge a `beef` received from a specific `party`.
+
+Updates this `BeefParty` to track all the txids
+corresponding to transactions for which `party`
+has raw transaction and validity proof data.
+
+```ts
+mergeBeefFromParty(party: string, beef: number[] | Beef) 
+```
+
 </details>
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
@@ -1925,6 +2047,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | |
 | --- |
+| [ATOMIC_BEEF](#variable-atomic_beef) |
 | [BEEF_MAGIC](#variable-beef_magic) |
 | [BEEF_MAGIC_TXID_ONLY_EXTENSION](#variable-beef_magic_txid_only_extension) |
 | [BEEF_MAGIC_V2](#variable-beef_magic_v2) |
@@ -1960,3 +2083,12 @@ BEEF_MAGIC_TXID_ONLY_EXTENSION = 4022206465
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
+### Variable: ATOMIC_BEEF
+
+```ts
+ATOMIC_BEEF = 16843009
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.1.30",
+  "version": "1.1.32",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/transaction/Beef.ts

@@ -7,6 +7,7 @@ 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
 
 export type BeefVersion = undefined | 'V1' | 'V2'
 
@@ -16,6 +17,14 @@ export type BeefVersion = undefined | 'V1' | 'V2'
  *
  * 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
@@ -48,11 +57,18 @@ export type BeefVersion = undefined | 'V1' | 'V2'
  *
  * 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: BeefVersion = undefined
+  atomicTxid: string | undefined = undefined
 
   constructor (version?: BeefVersion) {
     this.version = version
@@ -82,6 +98,81 @@ export class Beef {
     return this.txs.find(tx => tx.txid === txid)
   }
 
+  /**
+   * @returns `MerklePath` with level zero hash equal to txid or undefined.
+   */
+  findBump (txid: string): MerklePath | undefined {
+    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: string): Transaction | undefined {
+
+    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: string): Transaction | undefined {
+
+    const beefTx = this.findTxid(txid)
+    if (!beefTx) return undefined
+
+    const addInputProof = (beef: Beef, tx: Transaction) => {
+      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
@@ -334,7 +425,13 @@ export class Beef {
   }
 
   static fromReader (br: Reader): Beef {
-    const version = br.readUInt32LE()
+    let version = br.readUInt32LE()
+    let atomicTxid: string | undefined = 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()
@@ -347,6 +444,7 @@ export class Beef {
       const beefTx = BeefTx.fromReader(br, version)
       beef.txs.push(beefTx)
     }
+    beef.atomicTxid = atomicTxid
     return beef
   }
 
@@ -395,71 +493,104 @@ export class Beef {
   }
 
   /**
-     * 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 (): string[] {
-    const missingInputs: Record<string, boolean> = {}
-
+  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
-      // 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: Record<string, boolean> = {}
+    // transactions with one or more missing inputs
+    const txsMissingInputs: BeefTx[] = []
+
+    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]) { missingInputs[inputTxid] = true }
+          if (!txidToTx[inputTxid]) {
+            missingInputs[inputTxid] = true
+            hasMissingInput = true
+          }
         }
       }
-    }
-
-    // queue of transactions that no unsorted transactions depend upon...
-    const queue: BeefTx[] = []
-    // sorted transactions
-    const result: BeefTx[] = []
-
-    // 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...
+
+    // As long as we have unsorted transactions...
     while (queue.length > 0) {
-      const 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)
-          }
-        }
+      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)
+    }
   }
 
   /**
@@ -488,6 +619,14 @@ export class Beef {
     // TODO: bumps could be trimmed to eliminate unreferenced proofs.
   }
 
+  /**
+   * @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.
      */

package/src/transaction/BeefParty.ts

@@ -91,6 +91,23 @@ export class BeefParty extends Beef {
       this.mergeTxidOnly(txid)
     }
   }
+
+  /**
+   * Merge a `beef` received from a specific `party`.
+   * 
+   * Updates this `BeefParty` to track all the txids
+   * corresponding to transactions for which `party`
+   * has raw transaction and validity proof data.
+   * 
+   * @param party 
+   * @param beef 
+   */
+  mergeBeefFromParty (party: string, beef: number[] | Beef) {
+    const b: Beef = Array.isArray(beef) ? Beef.fromBinary(beef) : beef
+    const knownTxids = b.getValidTxids()
+    this.mergeBeef(b)
+    this.addKnownTxidsForParty(party, knownTxids)
+  }
 }
 
 export default BeefParty

package/src/transaction/BeefTx.ts

@@ -18,7 +18,12 @@ export default class BeefTx {
   _rawTx?: number[]
   _txid?: string
   inputTxids: string[] = []
-  degree: number = 0
+  /**
+   * true if `hasProof` or all inputs chain to `hasProof`.
+   * 
+   * Typically set by sorting transactions by proven dependency chains.
+   */
+  isValid?: boolean = undefined
 
   get bumpIndex (): number | undefined { return this._bumpIndex }
 

package/src/transaction/Transaction.ts

@@ -859,10 +859,13 @@ export default class Transaction {
 
   /**
    * Serializes this transaction, together with its inputs and the respective merkle proofs, into the BEEF (BRC-62) format. This enables efficient verification of its compliance with the rules of SPV.
+   * 
+   * @param allowPartial If true, error will not be thrown if there are any missing sourceTransactions.
    *
    * @returns The serialized BEEF structure
+   * @throws Error if there are any missing sourceTransactions unless `allowPartial` is true.
    */
-  toBEEF (): number[] {
+  toBEEF (allowPartial?: boolean): number[] {
     const writer = new Writer()
     writer.writeUInt32LE(4022206465)
     const BUMPs: MerklePath[] = []
@@ -907,10 +910,10 @@ export default class Transaction {
       if (!hasProof) {
         for (let i = 0; i < tx.inputs.length; i++) {
           const input = tx.inputs[i]
-          if (typeof input.sourceTransaction !== 'object') {
+          if (typeof input.sourceTransaction === 'object')
+            addPathsAndInputs(input.sourceTransaction)
+          else if (!allowPartial)
             throw new Error('A required source transaction is missing!')
-          }
-          addPathsAndInputs(input.sourceTransaction)
         }
       }
     }
@@ -940,16 +943,19 @@ export default class Transaction {
    * and then the BEEF data containing only the subject transaction and its dependencies.
    * This format ensures that the BEEF structure is atomic and contains no unrelated transactions.
    *
+   * @param allowPartial If true, error will not be thrown if there are any missing sourceTransactions.
+   *
    * @returns {number[]} - The serialized Atomic BEEF structure.
+   * @throws Error if there are any missing sourceTransactions unless `allowPartial` is true.
    */
-  toAtomicBEEF (): number[] {
+  toAtomicBEEF (allowPartial?: boolean): number[] {
     const writer = new Writer()
     // Write the Atomic BEEF prefix
     writer.writeUInt32LE(0x01010101)
     // Write the subject TXID (big-endian)
     writer.write(this.id())
     // Append the BEEF data
-    const beefData = this.toBEEF()
+    const beefData = this.toBEEF(allowPartial)
     writer.write(beefData)
     return writer.toArray()
   }