@bsv/sdk 1.1.29 → 1.1.32

package/src/transaction/Transaction.ts

@@ -67,7 +67,7 @@ export default class Transaction {
    * @param txid Optional TXID of the transaction to retrieve from the BEEF data.
    * @returns An anchored transaction, linked to its associated inputs populated with merkle paths.
    */
-  static fromBEEF(beef: number[], txid?: string): Transaction {
+  static fromBEEF (beef: number[], txid?: string): Transaction {
     const reader = new Reader(beef)
     const { transactions, BUMPs } = Transaction.parseBEEFData(reader)
 
@@ -115,7 +115,7 @@ export default class Transaction {
    * @param beef A binary representation of an Atomic BEEF structure.
    * @returns The subject transaction, linked to its associated inputs populated with merkle paths.
    */
-  static fromAtomicBEEF(beef: number[]): Transaction {
+  static fromAtomicBEEF (beef: number[]): Transaction {
     const reader = new Reader(beef)
     // Read the Atomic BEEF prefix
     const prefix = reader.readUInt32LE()
@@ -194,7 +194,7 @@ export default class Transaction {
    * @param reader The Reader positioned at the start of BEEF data.
    * @returns An object containing the transactions and BUMPs.
    */
-  private static parseBEEFData(reader: Reader): { transactions: Record<string, { pathIndex?: number, tx: Transaction }>, BUMPs: MerklePath[] } {
+  private static parseBEEFData (reader: Reader): { transactions: Record<string, { pathIndex?: number, tx: Transaction }>, BUMPs: MerklePath[] } {
     // Read the version
     const version = reader.readUInt32LE()
     if (version !== BEEF_MAGIC) {
@@ -231,7 +231,7 @@ export default class Transaction {
    * @param ef A binary representation of a transaction in EF format.
    * @returns An extended transaction, linked to its associated inputs by locking script and satoshis amounts only.
    */
-  static fromEF(ef: number[]): Transaction {
+  static fromEF (ef: number[]): Transaction {
     const br = new Reader(ef)
     const version = br.readUInt32LE()
     if (toHex(br.read(6)) !== '0000000000ef') throw new Error('Invalid EF marker')
@@ -293,7 +293,7 @@ export default class Transaction {
    *   outputs: { vout: number, offset: number, length: number }[]
    * }
    */
-  static parseScriptOffsets(bin: number[]): {
+  static parseScriptOffsets (bin: number[]): {
     inputs: Array<{ vin: number, offset: number, length: number }>
     outputs: Array<{ vout: number, offset: number, length: number }>
   } {
@@ -319,7 +319,7 @@ export default class Transaction {
     return { inputs, outputs }
   }
 
-  static fromReader(br: Reader): Transaction {
+  static fromReader (br: Reader): Transaction {
     const version = br.readUInt32LE()
     const inputsLength = br.readVarIntNum()
     const inputs: TransactionInput[] = []
@@ -360,7 +360,7 @@ export default class Transaction {
    * @param {number[]} bin - The binary array representation of the transaction.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromBinary(bin: number[]): Transaction {
+  static fromBinary (bin: number[]): Transaction {
     const br = new Reader(bin)
     return Transaction.fromReader(br)
   }
@@ -372,7 +372,7 @@ export default class Transaction {
    * @param {string} hex - The hexadecimal string representation of the transaction.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromHex(hex: string): Transaction {
+  static fromHex (hex: string): Transaction {
     return Transaction.fromBinary(toArray(hex, 'hex'))
   }
 
@@ -383,7 +383,7 @@ export default class Transaction {
    * @param {string} hex - The hexadecimal string representation of the transaction EF.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromHexEF(hex: string): Transaction {
+  static fromHexEF (hex: string): Transaction {
     return Transaction.fromEF(toArray(hex, 'hex'))
   }
 
@@ -398,11 +398,11 @@ export default class Transaction {
    * @param {string} [txid] - Optional TXID of the transaction to retrieve from the BEEF data.
    * @returns {Transaction} - A new Transaction instance.
    */
-  static fromHexBEEF(hex: string, txid?: string): Transaction {
+  static fromHexBEEF (hex: string, txid?: string): Transaction {
     return Transaction.fromBEEF(toArray(hex, 'hex'), txid)
   }
 
-  constructor(
+  constructor (
     version: number = 1,
     inputs: TransactionInput[] = [],
     outputs: TransactionOutput[] = [],
@@ -424,7 +424,7 @@ export default class Transaction {
    * @param {TransactionInput} input - The TransactionInput object to add to the transaction.
    * @throws {Error} - If the input does not have a sourceTXID or sourceTransaction defined.
    */
-  addInput(input: TransactionInput): void {
+  addInput (input: TransactionInput): void {
     if (
       typeof input.sourceTXID === 'undefined' &&
       typeof input.sourceTransaction === 'undefined'
@@ -444,7 +444,7 @@ export default class Transaction {
    *
    * @param {TransactionOutput} output - The TransactionOutput object to add to the transaction.
    */
-  addOutput(output: TransactionOutput): void {
+  addOutput (output: TransactionOutput): void {
     this.cachedHash = undefined
     this.outputs.push(output)
   }
@@ -454,7 +454,7 @@ export default class Transaction {
    *
    * @param {Record<string, any>} metadata - The metadata object to merge into the existing metadata.
    */
-  updateMetadata(metadata: Record<string, any>): void {
+  updateMetadata (metadata: Record<string, any>): void {
     this.metadata = {
       ...this.metadata,
       ...metadata
@@ -472,7 +472,7 @@ export default class Transaction {
    *
    * TODO: Benford's law change distribution.
    */
-  async fee(modelOrFee?: FeeModel | number, changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
+  async fee (modelOrFee?: FeeModel | number, changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
     this.cachedHash = undefined
     if (typeof modelOrFee === 'undefined') {
       modelOrFee = new SatoshisPerKilobyte(10)
@@ -533,7 +533,7 @@ export default class Transaction {
    *
    * @returns The current transaction fee
    */
-  getFee(): number {
+  getFee (): number {
     let totalIn = 0
     for (const input of this.inputs) {
       if (typeof input.sourceTransaction !== 'object') {
@@ -551,7 +551,7 @@ export default class Transaction {
   /**
    * Signs a transaction, hydrating all its unlocking scripts based on the provided script templates where they are available.
    */
-  async sign(): Promise<void> {
+  async sign (): Promise<void> {
     this.cachedHash = undefined
     for (const out of this.outputs) {
       if (typeof out.satoshis === 'undefined') {
@@ -582,7 +582,7 @@ export default class Transaction {
    * @param broadcaster The Broadcaster instance wwhere the transaction will be sent
    * @returns A BroadcastResponse or BroadcastFailure from the Broadcaster
    */
-  async broadcast(broadcaster: Broadcaster = defaultBroadcaster()): Promise<BroadcastResponse | BroadcastFailure> {
+  async broadcast (broadcaster: Broadcaster = defaultBroadcaster()): Promise<BroadcastResponse | BroadcastFailure> {
     return await broadcaster.broadcast(this)
   }
 
@@ -591,7 +591,7 @@ export default class Transaction {
    *
    * @returns {number[]} - The binary array representation of the transaction.
    */
-  toBinary(): number[] {
+  toBinary (): number[] {
     const writer = new Writer()
     writer.writeUInt32LE(this.version)
     writer.writeVarIntNum(this.inputs.length)
@@ -623,7 +623,7 @@ export default class Transaction {
    *
    * @returns {number[]} - The BRC-30 EF representation of the transaction.
    */
-  toEF(): number[] {
+  toEF (): number[] {
     const writer = new Writer()
     writer.writeUInt32LE(this.version)
     writer.write([0, 0, 0, 0, 0, 0xef])
@@ -663,7 +663,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction EF.
    */
-  toHexEF(): string {
+  toHexEF (): string {
     return toHex(this.toEF())
   }
 
@@ -672,7 +672,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction.
    */
-  toHex(): string {
+  toHex (): string {
     return toHex(this.toBinary())
   }
 
@@ -681,7 +681,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction BEEF.
    */
-  toHexBEEF(): string {
+  toHexBEEF (): string {
     return toHex(this.toBEEF())
   }
 
@@ -690,7 +690,7 @@ export default class Transaction {
    *
    * @returns {string} - The hexadecimal string representation of the transaction Atomic BEEF.
    */
-  toHexAtomicBEEF(): string {
+  toHexAtomicBEEF (): string {
     return toHex(this.toAtomicBEEF())
   }
 
@@ -700,7 +700,7 @@ export default class Transaction {
    * @param {'hex' | undefined} enc - The encoding to use for the hash. If 'hex', returns a hexadecimal string; otherwise returns a binary array.
    * @returns {string | number[]} - The hash of the transaction in the specified format.
    */
-  hash(enc?: 'hex'): number[] | string {
+  hash (enc?: 'hex'): number[] | string {
     let hash
     if (this.cachedHash) {
       hash = this.cachedHash
@@ -719,21 +719,21 @@ export default class Transaction {
    *
    * @returns {number[]} - The ID of the transaction in the binary array format.
    */
-  id(): number[]
+  id (): number[]
   /**
    * Calculates the transaction's ID in hexadecimal format.
    *
    * @param {'hex'} enc - The encoding to use for the ID. If 'hex', returns a hexadecimal string.
    * @returns {string} - The ID of the transaction in the hex format.
    */
-  id(enc: 'hex'): string
+  id (enc: 'hex'): string
   /**
    * Calculates the transaction's ID.
    *
    * @param {'hex' | undefined} enc - The encoding to use for the ID. If 'hex', returns a hexadecimal string; otherwise returns a binary array.
    * @returns {string | number[]} - The ID of the transaction in the specified format.
    */
-  id(enc?: 'hex'): number[] | string {
+  id (enc?: 'hex'): number[] | string {
     const id = [...this.hash() as number[]]
     id.reverse()
     if (enc === 'hex') {
@@ -751,7 +751,7 @@ export default class Transaction {
    *
    * @example tx.verify(new WhatsOnChain(), new SatoshisPerKilobyte(1))
    */
-  async verify(
+  async verify (
     chainTracker: ChainTracker | 'scripts only' = defaultChainTracker(),
     feeModel?: FeeModel
   ): Promise<boolean> {
@@ -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() as number[])
+    writer.write(this.id())
     // Append the BEEF data
-    const beefData = this.toBEEF()
+    const beefData = this.toBEEF(allowPartial)
     writer.write(beefData)
     return writer.toArray()
   }

package/src/transaction/__tests/Beef.test.ts

@@ -1,9 +1,17 @@
+// The following imports allow flag a large number type checking errors by the VsCode editor due to missing type information:
 import BeefTx from "../../../dist/cjs/src/transaction/BeefTx"
 import Beef from "../../../dist/cjs/src/transaction/Beef"
 import BeefParty from "../../../dist/cjs/src/transaction/BeefParty"
 import { BEEF_MAGIC, BEEF_MAGIC_V2 } from "../../../dist/cjs/src/transaction/Beef"
 import Transaction from "../../../dist/cjs/src/transaction/Transaction"
 
+// The following imports allow full type checking by the VsCode editor, but tests will fail to run:
+//import BeefTx from '../BeefTx'
+//import Beef from '../Beef'
+//import BeefParty from "../BeefParty"
+//import { BEEF_MAGIC, BEEF_MAGIC_V2 } from "../Beef"
+//import Transaction from "../Transaction"
+
 describe('Beef tests', () => {
     jest.setTimeout(99999999)
 
@@ -56,8 +64,8 @@ describe('Beef tests', () => {
           expect(btx.rawTx).toBe(undefined)
         }
 
-        const missing = beef.sortTxs()
-        expect(missing.length).toBe(0)
+        const r = beef.sortTxs()
+        expect(r.missingInputs.length).toBe(0)
         expect(beef.toLogString()).toBe(log2)
 
         {
@@ -72,8 +80,8 @@ describe('Beef tests', () => {
         {
           const beef = new Beef()
           beef.mergeTransaction(Transaction.fromHex(txs[0]))
-          const missing = beef.sortTxs()
-          expect(missing).toEqual(['bd4a39c6dce3bdd982be3c67eb04b83934fd431f8bcb64f9da4413c91c634d07'])
+          const { missingInputs } = beef.sortTxs()
+          expect(missingInputs).toEqual(['bd4a39c6dce3bdd982be3c67eb04b83934fd431f8bcb64f9da4413c91c634d07'])
           const beef0 = Beef.fromString(beefs[0])
           beef.mergeBump(beef0.bumps[0])
           beef.mergeRawTx(beef0.txs[0].rawTx!, undefined)
@@ -215,10 +223,10 @@ describe('Beef tests', () => {
         const v = bp.getTrimmedBeefForParty('a').toLogString()
         expect(v).toBe(`BEEF with 0 BUMPS and 2 Transactions, isValid false
   TX 0
-    txid: 4
+    txid: 3
     txidOnly
   TX 1
-    txid: 3
+    txid: 4
     txidOnly
 `)
       }
@@ -226,10 +234,10 @@ describe('Beef tests', () => {
         const v = bp.getTrimmedBeefForParty('b').toLogString()
         expect(v).toBe(`BEEF with 0 BUMPS and 2 Transactions, isValid false
   TX 0
-    txid: 2
+    txid: 1
     txidOnly
   TX 1
-    txid: 1
+    txid: 2
     txidOnly
 `)
       }
@@ -237,15 +245,52 @@ describe('Beef tests', () => {
         const v = bp.getTrimmedBeefForParty('c').toLogString()
         expect(v).toBe(`BEEF with 0 BUMPS and 2 Transactions, isValid false
   TX 0
-    txid: 4
+    txid: 1
     txidOnly
   TX 1
-    txid: 1
+    txid: 4
     txidOnly
 `)
       }
     })
 
+    test('5_AtomicBeef', async () => {
+      {
+        const beef = Beef.fromString(beefs[0])
+        expect(beef.toHex()).toBe(beefs[0])
+        const sr = beef.sortTxs()
+        const beefHex = beef.toHex()
+        const tx = beef.txs[beef.txs.length - 1].tx!
+        expect(tx).toBeTruthy()
+        const atomic = tx.toAtomicBEEF(true)
+        // Verify that atomic BEEF can be deserialized.
+        const beef2 = Beef.fromBinary(atomic)
+        // The merkle path isn't linked to tx by default.
+        expect(beef2.toHex()).not.toBe(beefHex)
+        {
+          const atx = beef.findAtomicTransaction(tx.id('hex'))
+          const atomic = atx.toAtomicBEEF(true)
+          // Verify that atomic BEEF can be deserialized.
+          const beef2 = Beef.fromBinary(atomic)
+          // The merkle path now is linked to tx by default.
+          expect(beef2.toHex()).toBe(beefHex)
+        }
+      }
+      {
+        const beef = Beef.fromString(beefs[0])
+        expect(beef.toHex()).toBe(beefs[0])
+        beef.mergeTransaction(Transaction.fromHex(txs[0]))
+        const sr = beef.sortTxs()
+        const beefHex = beef.toHex()
+        const tx = beef.txs[beef.txs.length - 1].tx!
+        expect(tx).toBeTruthy()
+        const atx = beef.findAtomicTransaction(tx.id('hex'))
+        const atomic = atx.toAtomicBEEF()
+        // Verify that atomic BEEF can be deserialized.
+        const beef2 = Beef.fromBinary(atomic)
+        expect(beef2.toHex()).toBe(beefHex)
+      }
+    })
 })
 
 const txs: string[] = [