@bsv/wallet-toolbox 1.7.15 → 1.7.17

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

@@ -1,455 +0,0 @@
-
-import { Reader, Writer, toHex, toArray } from '../primitives/utils.js'
-import { hash256 } from '../primitives/Hash.js'
-import ChainTracker from './ChainTracker.js'
-
-export interface MerklePathLeaf {
-  offset: number
-  hash?: string
-  txid?: boolean
-  duplicate?: boolean
-}
-
-/**
- * Represents a Merkle Path, which is used to provide a compact proof of inclusion for a
- * transaction in a block. This class encapsulates all the details required for creating
- * and verifying Merkle Proofs.
- *
- * @class MerklePath
- * @property {number} blockHeight - The height of the block in which the transaction is included.
- * @property {Array<Array<{offset: number, hash?: string, txid?: boolean, duplicate?: boolean}>>} path -
- *           A tree structure representing the Merkle Path, with each level containing information
- *           about the nodes involved in constructing the proof.
- *
- * @example
- * // Creating and verifying a Merkle Path
- * const merklePath = MerklePath.fromHex('...');
- * const isValid = merklePath.verify(txid, chainTracker);
- *
- * @description
- * The MerklePath class is useful for verifying transactions in a lightweight and efficient manner without
- * needing the entire block data. This class offers functionalities for creating, converting,
- * and verifying these proofs.
- */
-export default class MerklePath {
-  blockHeight: number
-  path: Array<
-  Array<{
-    offset: number
-    hash?: string
-    txid?: boolean
-    duplicate?: boolean
-  }>
-  >
-
-  /**
-   * Creates a MerklePath instance from a hexadecimal string.
-   *
-   * @static
-   * @param {string} hex - The hexadecimal string representation of the Merkle Path.
-   * @returns {MerklePath} - A new MerklePath instance.
-   */
-  static fromHex (hex: string): MerklePath {
-    return MerklePath.fromBinary(toArray(hex, 'hex'))
-  }
-
-  static fromReader (
-    reader: Reader,
-    legalOffsetsOnly: boolean = true
-  ): MerklePath {
-    const blockHeight = reader.readVarIntNum()
-    const treeHeight = reader.readUInt8()
-    // Explicitly define the type of path as an array of arrays of leaf objects
-    const path: Array<Array<{ offset: number, hash?: string, txid?: boolean, duplicate?: boolean }>> = Array(treeHeight)
-      .fill(null)
-      .map(() => [])
-    let flags: number, offset: number, nLeavesAtThisHeight: number
-    for (let level = 0; level < treeHeight; level++) {
-      nLeavesAtThisHeight = reader.readVarIntNum()
-      while (nLeavesAtThisHeight > 0) {
-        offset = reader.readVarIntNum()
-        flags = reader.readUInt8()
-        const leaf: {
-          offset: number
-          hash?: string
-          txid?: boolean
-          duplicate?: boolean
-        } = { offset }
-        if ((flags & 1) !== 0) {
-          leaf.duplicate = true
-        } else {
-          if ((flags & 2) !== 0) {
-            leaf.txid = true
-          }
-          leaf.hash = toHex(reader.read(32).reverse())
-        }
-        // Ensure path[level] exists before pushing
-        if (!Array.isArray(path[level]) || path[level].length === 0) {
-          path[level] = []
-        }
-        path[level].push(leaf)
-        nLeavesAtThisHeight--
-      }
-      // Sort the array based on the offset property
-      path[level].sort((a, b) => a.offset - b.offset)
-    }
-    return new MerklePath(blockHeight, path, legalOffsetsOnly)
-  }
-
-  /**
-   * Creates a MerklePath instance from a binary array.
-   *
-   * @static
-   * @param {number[]} bump - The binary array representation of the Merkle Path.
-   * @returns {MerklePath} - A new MerklePath instance.
-   */
-  static fromBinary (bump: number[]): MerklePath {
-    const reader = new Reader(bump)
-    return MerklePath.fromReader(reader)
-  }
-
-  /**
-   *
-   * @static fromCoinbaseTxid
-   *
-   * Creates a MerklePath instance for a coinbase transaction in an empty block.
-   * This edge case is difficult to retrieve from standard APIs.
-   *
-   * @param {string} txid - The coinbase txid.
-   * @param {number} height - The height of the block.
-   * @returns {MerklePath} - A new MerklePath instance which assumes the tx is in a block with no other transactions.
-   */
-  static fromCoinbaseTxidAndHeight (txid: string, height: number): MerklePath {
-    return new MerklePath(height, [[{ offset: 0, hash: txid, txid: true }]])
-  }
-
-  constructor (
-    blockHeight: number,
-    path: Array<
-    Array<{
-      offset: number
-      hash?: string
-      txid?: boolean
-      duplicate?: boolean
-    }>
-    >,
-    legalOffsetsOnly: boolean = true
-  ) {
-    this.blockHeight = blockHeight
-    this.path = path
-
-    // store all of the legal offsets which we expect given the txid indices.
-    const legalOffsets = Array(this.path.length)
-      .fill(0)
-      .map(() => new Set())
-    this.path.forEach((leaves, height) => {
-      if (leaves.length === 0 && height === 0) {
-        throw new Error(`Empty level at height: ${height}`)
-      }
-      const offsetsAtThisHeight = new Set()
-      leaves.forEach((leaf) => {
-        if (offsetsAtThisHeight.has(leaf.offset)) {
-          throw new Error(
-            `Duplicate offset: ${leaf.offset}, at height: ${height}`
-          )
-        }
-        offsetsAtThisHeight.add(leaf.offset)
-        if (height === 0) {
-          if (leaf.duplicate !== true) {
-            for (let h = 1; h < this.path.length; h++) {
-              legalOffsets[h].add((leaf.offset >> h) ^ 1)
-            }
-          }
-        } else {
-          if (legalOffsetsOnly && !legalOffsets[height].has(leaf.offset)) {
-            throw new Error(
-              `Invalid offset: ${leaf.offset}, at height: ${height}, with legal offsets: ${Array.from(legalOffsets[height]).join(', ')}`
-            )
-          }
-        }
-      })
-    })
-
-    // every txid must calculate to the same root.
-    let root: string
-    this.path[0].forEach((leaf, idx) => {
-      if (idx === 0) root = this.computeRoot(leaf.hash)
-      if (root !== this.computeRoot(leaf.hash)) {
-        throw new Error('Mismatched roots')
-      }
-    })
-  }
-
-  /**
-   * Converts the MerklePath to a binary array format.
-   *
-   * @returns {number[]} - The binary array representation of the Merkle Path.
-   */
-  toBinary (): number[] {
-    const writer = new Writer()
-    writer.writeVarIntNum(this.blockHeight)
-    const treeHeight = this.path.length
-    writer.writeUInt8(treeHeight)
-    for (let level = 0; level < treeHeight; level++) {
-      const nLeaves = Object.keys(this.path[level]).length
-      writer.writeVarIntNum(nLeaves)
-      for (const leaf of this.path[level]) {
-        writer.writeVarIntNum(leaf.offset)
-        let flags = 0
-        if (leaf?.duplicate === true) {
-          flags |= 1
-        }
-        if (leaf?.txid !== undefined && leaf.txid !== null) {
-          flags |= 2
-        }
-        writer.writeUInt8(flags)
-        if ((flags & 1) === 0) {
-          writer.write(toArray(leaf.hash, 'hex').reverse())
-        }
-      }
-    }
-    return writer.toArray()
-  }
-
-  /**
-   * Converts the MerklePath to a hexadecimal string format.
-   *
-   * @returns {string} - The hexadecimal string representation of the Merkle Path.
-   */
-  toHex (): string {
-    return toHex(this.toBinary())
-  }
-
-  //
-  private indexOf (txid: string): number {
-    const leaf = this.path[0].find((l) => l.hash === txid)
-    if (leaf === null || leaf === undefined) {
-      throw new Error(`Transaction ID ${txid} not found in the Merkle Path`)
-    }
-    return leaf.offset
-  }
-
-  /**
-   * Computes the Merkle root from the provided transaction ID.
-   *
-   * @param {string} txid - The transaction ID to compute the Merkle root for. If not provided, the root will be computed from an unspecified branch, and not all branches will be validated!
-   * @returns {string} - The computed Merkle root as a hexadecimal string.
-   * @throws {Error} - If the transaction ID is not part of the Merkle Path.
-   */
-  computeRoot (txid?: string): string {
-    if (typeof txid !== 'string') {
-      const foundLeaf = this.path[0].find((leaf) => Boolean(leaf?.hash))
-      if (foundLeaf === null || foundLeaf === undefined) {
-        throw new Error('No valid leaf found in the Merkle Path')
-      }
-      txid = foundLeaf.hash
-    }
-    // Find the index of the txid at the lowest level of the Merkle tree
-    if (typeof txid !== 'string') {
-      throw new Error('Transaction ID is undefined')
-    }
-    const index = this.indexOf(txid)
-    if (typeof index !== 'number') {
-      throw new Error(`This proof does not contain the txid: ${txid ?? 'undefined'}`)
-    }
-    // Calculate the root using the index as a way to determine which direction to concatenate.
-    const hash = (m: string): string =>
-      toHex(hash256(toArray(m, 'hex').reverse()).reverse())
-    let workingHash = txid
-
-    // special case for blocks with only one transaction
-    if (this.path.length === 1 && this.path[0].length === 1) return workingHash
-
-    for (let height = 0; height < this.path.length; height++) {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const leaves = this.path[height]
-      const offset = (index >> height) ^ 1
-      const leaf = this.findOrComputeLeaf(height, offset)
-      if (typeof leaf !== 'object') {
-        throw new Error(`Missing hash for index ${index} at height ${height}`)
-      }
-      if (leaf.duplicate === true) {
-        workingHash = hash((workingHash ?? '') + (workingHash ?? ''))
-      } else if (offset % 2 !== 0) {
-        workingHash = hash((leaf.hash ?? '') + (workingHash ?? ''))
-      } else {
-        workingHash = hash((workingHash ?? '') + (leaf.hash ?? ''))
-      }
-    }
-    return workingHash
-  }
-
-  /**
-   * Find leaf with `offset` at `height` or compute from level below, recursively.
-   *
-   * Does not add computed leaves to path.
-   *
-   * @param height
-   * @param offset
-   */
-  findOrComputeLeaf (
-    height: number,
-    offset: number
-  ): MerklePathLeaf | undefined {
-    const hash = (m: string): string =>
-      toHex(hash256(toArray(m, 'hex').reverse()).reverse())
-
-    let leaf: MerklePathLeaf | undefined = this.path[height].find(
-      (l) => l.offset === offset
-    )
-
-    if (leaf != null) return leaf
-
-    if (height === 0) return undefined
-
-    const h = height - 1
-    const l = offset << 1
-
-    const leaf0 = this.findOrComputeLeaf(h, l)
-    if (leaf0 == null || leaf0.hash == null || leaf0.hash === '') return undefined
-
-    const leaf1 = this.findOrComputeLeaf(h, l + 1)
-    if (leaf1 == null) return undefined
-
-    let workinghash: string
-    if (leaf1.duplicate === true) {
-      workinghash = hash(leaf0.hash + leaf0.hash)
-    } else {
-      workinghash = hash((leaf1.hash ?? '') + (leaf0.hash ?? ''))
-    }
-    leaf = {
-      offset,
-      hash: workinghash
-    }
-
-    return leaf
-  }
-
-  /**
-   * Verifies if the given transaction ID is part of the Merkle tree at the specified block height.
-   *
-   * @param {string} txid - The transaction ID to verify.
-   * @param {ChainTracker} chainTracker - The ChainTracker instance used to verify the Merkle root.
-   * @returns {boolean} - True if the transaction ID is valid within the Merkle Path at the specified block height.
-   */
-  async verify (txid: string, chainTracker: ChainTracker): Promise<boolean> {
-    const root = this.computeRoot(txid)
-    if (this.indexOf(txid) === 0) {
-      // Coinbase transaction outputs can only be spent once they're 100 blocks deep.
-      const height = await chainTracker.currentHeight()
-      if (this.blockHeight + 100 < height) {
-        return false
-      }
-    }
-    // Use the chain tracker to determine whether this is a valid merkle root at the given block height
-    return await chainTracker.isValidRootForHeight(root, this.blockHeight)
-  }
-
-  /**
-   * Combines this MerklePath with another to create a compound proof.
-   *
-   * @param {MerklePath} other - Another MerklePath to combine with this path.
-   * @throws {Error} - If the paths have different block heights or roots.
-   */
-  combine (other: MerklePath): void {
-    if (this.blockHeight !== other.blockHeight) {
-      throw new Error(
-        'You cannot combine paths which do not have the same block height.'
-      )
-    }
-    const root1 = this.computeRoot()
-    const root2 = other.computeRoot()
-    if (root1 !== root2) {
-      throw new Error(
-        'You cannot combine paths which do not have the same root.'
-      )
-    }
-    const combinedPath: Array<Array<{ offset: number, hash?: string, txid?: boolean, duplicate?: boolean }>> = []
-    for (let h = 0; h < this.path.length; h++) {
-      combinedPath.push([])
-      for (let l = 0; l < this.path[h].length; l++) {
-        combinedPath[h].push(this.path[h][l])
-      }
-      for (let l = 0; l < other.path[h].length; l++) {
-        if (
-          combinedPath[h].find(
-            (leaf) => leaf.offset === other.path[h][l].offset
-          ) === undefined
-        ) {
-          combinedPath[h].push(other.path[h][l])
-        } else {
-          // Ensure that any elements which appear in both are not downgraded to a non txid.
-          if (other.path[h][l]?.txid !== undefined && other.path[h][l]?.txid !== null) {
-            const target = combinedPath[h].find(
-              (leaf) => leaf.offset === other.path[h][l].offset
-            )
-            if (target !== null && target !== undefined) {
-              target.txid = true
-            }
-          }
-        }
-      }
-    }
-    this.path = combinedPath
-    this.trim()
-  }
-
-  /**
-   * Remove all internal nodes that are not required by level zero txid nodes.
-   * Assumes that at least all required nodes are present.
-   * Leaves all levels sorted by increasing offset.
-   */
-  trim (): void {
-    const pushIfNew = (v: number, a: number[]): void => {
-      if (a.length === 0 || a.slice(-1)[0] !== v) {
-        a.push(v)
-      }
-    }
-
-    const dropOffsetsFromLevel = (dropOffsets: number[], level: number): void => {
-      for (let i = dropOffsets.length; i >= 0; i--) {
-        const l = this.path[level].findIndex(
-          (n) => n.offset === dropOffsets[i]
-        )
-        if (l >= 0) {
-          this.path[level].splice(l, 1)
-        }
-      }
-    }
-
-    const nextComputedOffsets = (cos: number[]): number[] => {
-      const ncos: number[] = []
-      for (const o of cos) {
-        pushIfNew(o >> 1, ncos)
-      }
-      return ncos
-    }
-
-    let computedOffsets: number[] = [] // in next level
-    let dropOffsets: number[] = []
-    for (let h = 0; h < this.path.length; h++) {
-      // Sort each level by increasing offset order
-      this.path[h].sort((a, b) => a.offset - b.offset)
-    }
-    for (let l = 0; l < this.path[0].length; l++) {
-      const n = this.path[0][l]
-      if (n.txid === true) {
-        // level 0 must enable computing level 1 for txid nodes
-        pushIfNew(n.offset >> 1, computedOffsets)
-      } else {
-        const isOdd = n.offset % 2 === 1
-        const peer = this.path[0][l + (isOdd ? -1 : 1)]
-        if (peer.txid === undefined || peer.txid === null || !peer.txid) {
-          // drop non-txid level 0 nodes without a txid peer
-          pushIfNew(peer.offset, dropOffsets)
-        }
-      }
-    }
-    dropOffsetsFromLevel(dropOffsets, 0)
-    for (let h = 1; h < this.path.length; h++) {
-      dropOffsets = computedOffsets
-      computedOffsets = nextComputedOffsets(computedOffsets)
-      dropOffsetsFromLevel(dropOffsets, h)
-    }
-  }
-}