@bsv/wallet-toolbox 1.7.14 → 1.7.16

package/mobile/node_modules/@bsv/sdk/src/transaction/BeefParty.ts

@@ -0,0 +1,123 @@
+import { Beef } from './Beef.js'
+
+/**
+ * Extends `Beef` that is used to exchange transaction validity data with more than one external party.
+ *
+ * Use `addKnownTxidsForParty` to keep track of who knows what to reduce re-transmission of potentially large transactions.
+ *
+ * Use `getTrimmedBeefForParty` to obtain a `Beef` trimmed of transaction validity data known to a specific party.
+ *
+ * Typical usage scenario:
+ *
+ * 1. Query a wallet storage provider for spendable outputs.
+ * 2. The provider replies with a Beef validating the returned outputs.
+ * 3. Construct a new transaction using some of the queried outputs as inputs, including Beef validating all the inputs.
+ * 4. Receive new valid raw transaction after processing and Beef validating change outputs added to original inputs.
+ * 5. Return to step 1, continuing to build on old and new spendable outputs.
+ *
+ * By default, each Beef is required to be complete and valid: All transactions appear as full serialized bitcoin transactions and
+ * each transaction either has a merkle path proof (it has been mined) or all of its input transactions are included.
+ *
+ * The size and redundancy of these Beefs becomes a problem when chained transaction creation out-paces the block mining rate.
+ *
+ */
+export class BeefParty extends Beef {
+  /**
+   * keys are party identifiers.
+   * values are records of txids with truthy value for which the party already has validity proof.
+   */
+  knownTo: Record<string, Record<string, boolean>> = {}
+
+  /**
+   *
+   * @param parties Optional array of initial unique party identifiers.
+   */
+  constructor (parties?: string[]) {
+    super()
+    if (parties != null) {
+      for (const party of parties) {
+        this.addParty(party)
+      }
+    }
+  }
+
+  /**
+   * @param party
+   * @returns `true` if `party` has already been added to this `BeefParty`.
+   */
+  isParty (party: string): boolean {
+    const r = Object.keys(this.knownTo).includes(party)
+    return r
+  }
+
+  /**
+   * Adds a new unique party identifier to this `BeefParty`.
+   * @param party
+   */
+  addParty (party: string): void {
+    if (this.isParty(party)) {
+      throw new Error(`Party ${party} already exists.`)
+    }
+    this.knownTo[party] = {}
+  }
+
+  /**
+   * @param party
+   * @returns Array of txids "known" to `party`.
+   */
+  getKnownTxidsForParty (party: string): string[] {
+    const knownTxids = this.knownTo[party]
+
+    if (knownTxids === undefined) { // ✅ Explicitly check for undefined
+      throw new Error(`Party ${party} is unknown.`)
+    }
+
+    return Object.keys(knownTxids)
+  }
+
+  /**
+   * @param party
+   * @returns trimmed beef of unknown transactions and proofs for `party`
+   */
+  getTrimmedBeefForParty (party: string): Beef {
+    const knownTxids = this.getKnownTxidsForParty(party)
+    const prunedBeef = this.clone()
+    prunedBeef.trimKnownTxids(knownTxids)
+    return prunedBeef
+  }
+
+  /**
+   * Make note of additional txids "known" to `party`.
+   * @param party unique identifier, added if new.
+   * @param knownTxids
+   */
+  addKnownTxidsForParty (party: string, knownTxids: string[]): void {
+    if (!this.isParty(party)) {
+      this.addParty(party)
+    }
+    const kts = this.knownTo[party]
+    for (const txid of knownTxids) {
+      kts[txid] = true
+      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): void {
+    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/mobile/node_modules/@bsv/sdk/src/transaction/BeefTx.ts

@@ -0,0 +1,194 @@
+import { hash256 } from '../primitives/Hash.js'
+import { Reader, Writer, toHex, toArray } from '../primitives/utils.js'
+import Transaction from './Transaction.js'
+import { BEEF_V2, TX_DATA_FORMAT } from './Beef.js'
+
+/**
+ * A single bitcoin transaction associated with a `Beef` validity proof set.
+ *
+ * Simple case is transaction data included directly, either as raw bytes or fully parsed data, or both.
+ *
+ * Supports 'known' transactions which are represented by just their txid.
+ * It is assumed that intended consumer of this beef already has validity proof for such a transaction,
+ * which they can merge if necessary to create a valid beef.
+ */
+export default class BeefTx {
+  _bumpIndex?: number
+  _tx?: Transaction
+  _rawTx?: number[]
+  _txid?: string
+  inputTxids: string[] = []
+  /**
+   * 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
+  }
+
+  set bumpIndex (v: number | undefined) {
+    this._bumpIndex = v
+    this.updateInputTxids()
+  }
+
+  get hasProof (): boolean {
+    return this._bumpIndex !== undefined
+  }
+
+  get isTxidOnly (): boolean {
+    return this._txid !== undefined && this._txid !== null && (this._rawTx == null) && (this._tx == null)
+  }
+
+  get txid (): string {
+    if (this._txid !== undefined && this._txid !== null && this._txid !== '') return this._txid
+    if (this._tx != null) {
+      this._txid = this._tx.id('hex')
+      return this._txid
+    }
+    if (this._rawTx != null) {
+      this._txid = toHex(hash256(this._rawTx))
+      return this._txid
+    }
+    throw new Error('Internal')
+  }
+
+  get tx (): Transaction | undefined {
+    if (this._tx != null) return this._tx
+    if (this._rawTx != null) {
+      this._tx = Transaction.fromBinary(this._rawTx)
+      return this._tx
+    }
+    return undefined
+  }
+
+  get rawTx (): number[] | undefined {
+    if (this._rawTx != null) return this._rawTx
+    if (this._tx != null) {
+      this._rawTx = this._tx.toBinary()
+      return this._rawTx
+    }
+    return undefined
+  }
+
+  /**
+   * @param tx If string, must be a valid txid. If `number[]` must be a valid serialized transaction.
+   * @param bumpIndex If transaction already has a proof in the beef to which it will be added.
+   */
+  constructor (tx: Transaction | number[] | string, bumpIndex?: number) {
+    if (typeof tx === 'string') {
+      this._txid = tx
+    } else if (Array.isArray(tx)) {
+      this._rawTx = tx
+    } else {
+      this._tx = tx
+    }
+    this.bumpIndex = bumpIndex
+    this.updateInputTxids()
+  }
+
+  static fromTx (tx: Transaction, bumpIndex?: number): BeefTx {
+    return new BeefTx(tx, bumpIndex)
+  }
+
+  static fromRawTx (rawTx: number[], bumpIndex?: number): BeefTx {
+    return new BeefTx(rawTx, bumpIndex)
+  }
+
+  static fromTxid (txid: string, bumpIndex?: number): BeefTx {
+    return new BeefTx(txid, bumpIndex)
+  }
+
+  private updateInputTxids (): void {
+    if (this.hasProof || (this.tx == null)) {
+      // If we have a proof, or don't have a parsed transaction
+      this.inputTxids = []
+    } else {
+      const inputTxids: Record<string, boolean> = {} // ✅ Explicit object type
+      for (const input of this.tx.inputs) {
+        if (input.sourceTXID !== undefined && input.sourceTXID !== null && input.sourceTXID !== '') {
+          // ✅ Ensure sourceTXID is defined
+          inputTxids[input.sourceTXID] = true
+        }
+      }
+      this.inputTxids = Object.keys(inputTxids)
+    }
+  }
+
+  toWriter (writer: Writer, version: number): void {
+    const writeByte = (bb: number): void => {
+      writer.writeUInt8(bb)
+    }
+
+    const writeTxid = (): void => {
+      if (this._txid == null) {
+        throw new Error('Transaction ID (_txid) is undefined')
+      }
+      writer.writeReverse(toArray(this._txid, 'hex'))
+    }
+
+    const writeTx = (): void => {
+      if (this._rawTx != null) {
+        writer.write(this._rawTx)
+      } else if (this._tx != null) {
+        writer.write(this._tx.toUint8Array())
+      } else {
+        throw new Error('a valid serialized Transaction is expected')
+      }
+    }
+
+    const writeBumpIndex = (): void => {
+      if (this.bumpIndex === undefined) {
+        writeByte(TX_DATA_FORMAT.RAWTX) // 0
+      } else {
+        writeByte(TX_DATA_FORMAT.RAWTX_AND_BUMP_INDEX) // 1
+        writer.writeVarIntNum(this.bumpIndex) // the index of the associated bump
+      }
+    }
+
+    if (version === BEEF_V2) {
+      if (this.isTxidOnly) {
+        writeByte(TX_DATA_FORMAT.TXID_ONLY)
+        writeTxid()
+      } else if (this.bumpIndex !== undefined) {
+        writeByte(TX_DATA_FORMAT.RAWTX_AND_BUMP_INDEX)
+        writer.writeVarIntNum(this.bumpIndex)
+        writeTx()
+      } else {
+        writeByte(TX_DATA_FORMAT.RAWTX)
+        writeTx()
+      }
+    } else {
+      writeTx()
+      writeBumpIndex()
+    }
+  }
+
+  static fromReader (br: Reader, version: number): BeefTx {
+    let data: Transaction | number[] | string | undefined
+    let bumpIndex: number | undefined
+    let beefTx: BeefTx | undefined
+    if (version === BEEF_V2) {
+      // V2
+      const format = br.readUInt8()
+      if (format === TX_DATA_FORMAT.TXID_ONLY) {
+        beefTx = BeefTx.fromTxid(toHex(br.readReverse(32)))
+      } else {
+        if (format === TX_DATA_FORMAT.RAWTX_AND_BUMP_INDEX) {
+          bumpIndex = br.readVarIntNum()
+        }
+        data = Transaction.fromReader(br)
+        beefTx = BeefTx.fromTx(data, bumpIndex)
+      }
+    } else {
+      // V1
+      data = Transaction.fromReader(br)
+      bumpIndex = br.readUInt8() !== 0 ? br.readVarIntNum() : undefined
+      beefTx = BeefTx.fromTx(data, bumpIndex)
+    }
+
+    return beefTx
+  }
+}

package/mobile/node_modules/@bsv/sdk/src/transaction/Broadcaster.ts

@@ -0,0 +1,69 @@
+import Transaction from './Transaction.js'
+
+/**
+ * Defines the structure of a successful broadcast response.
+ *
+ * @interface
+ * @property {string} status - The status of the response, indicating success.
+ * @property {string} txid - The transaction ID of the broadcasted transaction.
+ * @property {string} message - A human-readable success message.
+ */
+export interface BroadcastResponse {
+  status: 'success'
+  txid: string
+  message: string
+  competingTxs?: string[]
+}
+
+/**
+ * Defines the structure of a failed broadcast response.
+ *
+ * @interface
+ * @property {string} status - The status of the response, indicating an error.
+ * @property {string} code - A machine-readable error code representing the type of error encountered.
+ * @property {string} txid - The transaction ID of the broadcasted transaction.
+ * @property {string} description - A detailed description of the error.
+ * @property {object} more - The unparsed response data from the underlying broadcast service.
+ */
+export interface BroadcastFailure {
+  status: 'error'
+  code: string
+  txid?: string
+  description: string
+  more?: object
+}
+
+/**
+ * Represents the interface for a transaction broadcaster.
+ * This interface defines a standard method for broadcasting transactions.
+ *
+ * @interface
+ * @property {function} broadcast - A function that takes a Transaction object and returns a promise.
+ *                                  The promise resolves to either a BroadcastResponse or a BroadcastFailure.
+ * @property {function} broadcastMany - A function that takes an array of Transaction objects and returns a promise.
+ *                                  The promise resolves to an array of broadcast result response objects.
+ */
+export interface Broadcaster {
+  broadcast: (
+    transaction: Transaction
+  ) => Promise<BroadcastResponse | BroadcastFailure>
+  broadcastMany?: (txs: Transaction[]) => Promise<object[]>
+}
+
+/**
+ * Convenience type guard for response from `Broadcaster.broadcast`
+ */
+export function isBroadcastResponse (
+  r: BroadcastResponse | BroadcastFailure
+): r is BroadcastResponse {
+  return r.status === 'success'
+}
+
+/**
+ * Convenience type guard for response from `Broadcaster.broadcast`
+ */
+export function isBroadcastFailure (
+  r: BroadcastResponse | BroadcastFailure
+): r is BroadcastFailure {
+  return r.status === 'error'
+}

package/mobile/node_modules/@bsv/sdk/src/transaction/ChainTracker.ts

@@ -0,0 +1,28 @@
+/**
+ * The Chain Tracker is responsible for verifying the validity of a given Merkle root
+ * for a specific block height within the blockchain.
+ *
+ * Chain Trackers ensure the integrity of the blockchain by
+ * validating new headers against the chain's history. They use accumulated
+ * proof-of-work and protocol adherence as metrics to assess the legitimacy of blocks.
+ *
+ * @interface ChainTracker
+ * @function isValidRootForHeight - A method to verify the validity of a Merkle root
+ *          for a given block height.
+ *
+ * @function currentHeight - A method to get the current block height.
+ *
+ * @example
+ * const chainTracker = {
+ *   isValidRootForHeight: async (root, height) => {
+ *     // Implementation to check if the Merkle root is valid for the specified block height.
+ *   }
+ *  currentHeight: async () => {
+ *     // Implementation to get the current block height.
+ *   }
+ * };
+ */
+export default interface ChainTracker {
+  isValidRootForHeight: (root: string, height: number) => Promise<boolean>
+  currentHeight: () => Promise<number>
+}

package/mobile/node_modules/@bsv/sdk/src/transaction/FeeModel.ts

@@ -0,0 +1,12 @@
+import Transaction from './Transaction.js'
+
+/**
+ * Represents the interface for a transaction fee model.
+ * This interface defines a standard method for computing a fee when given a transaction.
+ *
+ * @interface
+ * @property {function} computeFee - A function that takes a Transaction object and returns a BigNumber representing the number of satoshis the transaction should cost.
+ */
+export default interface FeeModel {
+  computeFee: (transaction: Transaction) => Promise<number>
+}