@bsv/sdk 1.0.0 → 1.0.1

package/src/script/index.ts

@@ -1,7 +0,0 @@
-export { default as OP } from './OP.js'
-export { default as Script } from './Script.js'
-export { default as LockingScript } from './LockingScript.js'
-export { default as UnlockingScript } from './UnlockingScript.js'
-export { default as Spend } from './Spend.js'
-export type { default as ScriptTemplate } from './ScriptTemplate.js'
-export * from './templates/index.js'

package/src/script/templates/P2PKH.ts

@@ -1,109 +0,0 @@
-import OP from '../OP.js'
-import ScriptTemplate from '../ScriptTemplate.js'
-import LockingScript from '../LockingScript.js'
-import UnlockingScript from '../UnlockingScript.js'
-import Transaction from '../../transaction/Transaction.js'
-import PrivateKey from '../../primitives/PrivateKey.js'
-import TransactionSignature from '../../primitives/TransactionSignature.js'
-import { sha256 } from '../../primitives/Hash.js'
-
-/**
- * P2PKH (Pay To Public Key Hash) class implementing ScriptTemplate.
- *
- * This class provides methods to create Pay To Public Key Hash locking and unlocking scripts, including the unlocking of P2PKH UTXOs with the private key.
- */
-export default class P2PKH implements ScriptTemplate {
-  /**
-   * Creates a P2PKH locking script for a given public key hash.
-   *
-   * @param {number[]} pubkeyhash - An array representing the public key hash.
-   * @returns {LockingScript} - A P2PKH locking script.
-   */
-  lock(pubkeyhash: number[]): LockingScript {
-    return new LockingScript([
-      { op: OP.OP_DUP },
-      { op: OP.OP_HASH160 },
-      { op: pubkeyhash.length, data: pubkeyhash },
-      { op: OP.OP_EQUALVERIFY },
-      { op: OP.OP_CHECKSIG }
-    ])
-  }
-
-  /**
-   * Creates a function that generates a P2PKH unlocking script along with its signature and length estimation.
-   *
-   * The returned object contains:
-   * 1. `sign` - A function that, when invoked with a transaction and an input index,
-   *    produces an unlocking script suitable for a P2PKH locked output.
-   * 2. `estimateLength` - A function that returns the estimated length of the unlocking script in bytes.
-   *
-   * @param {PrivateKey} privateKey - The private key used for signing the transaction.
-   * @param {'all'|'none'|'single'} signOutputs - The signature scope for outputs.
-   * @param {boolean} anyoneCanPay - Flag indicating if the signature allows for other inputs to be added later.
-   * @returns {Object} - An object containing the `sign` and `estimateLength` functions.
-   */
-  unlock(
-    privateKey: PrivateKey,
-    signOutputs: 'all' | 'none' | 'single' = 'all',
-    anyoneCanPay: boolean = false
-  ): {
-    sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
-    estimateLength: () => Promise<106>
-  } {
-    return {
-      sign: async (tx: Transaction, inputIndex: number) => {
-        let signatureScope = TransactionSignature.SIGHASH_FORKID
-        if (signOutputs === 'all') {
-          signatureScope |= TransactionSignature.SIGHASH_ALL
-        }
-        if (signOutputs === 'none') {
-          signatureScope |= TransactionSignature.SIGHASH_NONE
-        }
-        if (signOutputs === 'single') {
-          signatureScope |= TransactionSignature.SIGHASH_SINGLE
-        }
-        if (anyoneCanPay) {
-          signatureScope |= TransactionSignature.SIGHASH_ANYONECANPAY
-        }
-        const otherInputs = [...tx.inputs]
-        const [input] = otherInputs.splice(inputIndex, 1)
-        if (typeof input.sourceTransaction !== 'object') {
-          // Question: Should the library support use-cases where the source transaction is not provided? This is to say, is it ever acceptable for someone to sign an input spending some output from a transaction they have not provided? Some elements (such as the satoshi value and output script) are always required. A merkle proof is also always required, and verifying it (while also verifying that the claimed output is contained within the claimed transaction) is also always required. This seems to require the entire input transaction.
-          throw new Error(
-            'The source transaction is needed for transaction signing.'
-          )
-        }
-        const preimage = TransactionSignature.format({
-          sourceTXID: input.sourceTransaction.id('hex') as string,
-          sourceOutputIndex: input.sourceOutputIndex,
-          sourceSatoshis: input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis,
-          transactionVersion: tx.version,
-          otherInputs,
-          inputIndex,
-          outputs: tx.outputs,
-          inputSequence: input.sequence,
-          subscript: input.sourceTransaction.outputs[input.sourceOutputIndex].lockingScript,
-          lockTime: tx.lockTime,
-          scope: signatureScope
-        })
-        const rawSignature = privateKey.sign(sha256(preimage))
-        const sig = new TransactionSignature(
-          rawSignature.r,
-          rawSignature.s,
-          signatureScope
-        )
-        const sigForScript = sig.toChecksigFormat()
-        const pubkeyForScript = privateKey.toPublicKey().encode(true) as number[]
-        return new UnlockingScript([
-          { op: sigForScript.length, data: sigForScript },
-          { op: pubkeyForScript.length, data: pubkeyForScript }
-        ])
-      },
-      estimateLength: async () => {
-        // public key (1+33) + signature (1+71)
-        // Note: We add 1 to each element's length because of the associated OP_PUSH
-        return 106
-      }
-    }
-  }
-}

package/src/script/templates/RPuzzle.ts

@@ -1,140 +0,0 @@
-import OP from '../OP.js'
-import ScriptTemplate from '../ScriptTemplate.js'
-import LockingScript from '../LockingScript.js'
-import UnlockingScript from '../UnlockingScript.js'
-import Transaction from '../../transaction/Transaction.js'
-import PrivateKey from '../../primitives/PrivateKey.js'
-import TransactionSignature from '../../primitives/TransactionSignature.js'
-import { sha256 } from '../../primitives/Hash.js'
-import ScriptChunk from '../ScriptChunk.js'
-import BigNumber from '../../primitives/BigNumber.js'
-
-/**
- * RPuzzle class implementing ScriptTemplate.
- *
- * This class provides methods to create R Puzzle and R Puzzle Hash locking and unlocking scripts, including the unlocking of UTXOs with the correct K value.
- */
-export default class RPuzzle implements ScriptTemplate {
-  type: 'raw' | 'SHA1' | 'SHA256' | 'HASH256' | 'RIPEMD160' | 'HASH160' = 'raw'
-
-  /**
-   * @constructor
-   * Constructs an R Puzzle template instance for a given puzzle type
-   *
-   * @param {'raw'|'SHA1'|'SHA256'|'HASH256'|'RIPEMD160'|'HASH160'} type Denotes the type of puzzle to create
-   */
-  constructor (type: 'raw' | 'SHA1' | 'SHA256' | 'HASH256' | 'RIPEMD160' | 'HASH160' = 'raw') {
-    this.type = type
-  }
-
-  /**
-   * Creates an R puzzle locking script for a given R value or R value hash.
-   *
-   * @param {number[]} value - An array representing the R value or its hash.
-   * @returns {LockingScript} - An R puzzle locking script.
-   */
-  lock (value: number[]): LockingScript {
-    const chunks: ScriptChunk[] = [
-      { op: OP.OP_OVER },
-      { op: OP.OP_3 },
-      { op: OP.OP_SPLIT },
-      { op: OP.OP_NIP },
-      { op: OP.OP_1 },
-      { op: OP.OP_SPLIT },
-      { op: OP.OP_SWAP },
-      { op: OP.OP_SPLIT },
-      { op: OP.OP_DROP }
-    ]
-    if (this.type !== 'raw') {
-      chunks.push({
-        op: OP['OP_' + this.type]
-      })
-    }
-    chunks.push({ op: value.length, data: value })
-    chunks.push({ op: OP.OP_EQUALVERIFY })
-    chunks.push({ op: OP.OP_CHECKSIG })
-    return new LockingScript(chunks)
-  }
-
-  /**
-   * Creates a function that generates an R puzzle unlocking script along with its signature and length estimation.
-   *
-   * The returned object contains:
-   * 1. `sign` - A function that, when invoked with a transaction and an input index,
-   *    produces an unlocking script suitable for an R puzzle locked output.
-   * 2. `estimateLength` - A function that returns the estimated length of the unlocking script in bytes.
-   *
-   * @param {BigNumber} k — The K-value used to unlock the R-puzzle.
-   * @param {PrivateKey} privateKey - The private key used for signing the transaction. If not provided, a random key will be generated.
-   * @param {'all'|'none'|'single'} signOutputs - The signature scope for outputs.
-   * @param {boolean} anyoneCanPay - Flag indicating if the signature allows for other inputs to be added later.
-   * @returns {Object} - An object containing the `sign` and `estimateLength` functions.
-   */
-  unlock (
-    k: BigNumber,
-    privateKey: PrivateKey,
-    signOutputs: 'all' | 'none' | 'single' = 'all',
-    anyoneCanPay: boolean = false
-  ): {
-      sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
-      estimateLength: () => Promise<106>
-    } {
-    return {
-      sign: async (tx: Transaction, inputIndex: number) => {
-        if (typeof privateKey === 'undefined') {
-          privateKey = PrivateKey.fromRandom()
-        }
-        let signatureScope = TransactionSignature.SIGHASH_FORKID
-        if (signOutputs === 'all') {
-          signatureScope |= TransactionSignature.SIGHASH_ALL
-        }
-        if (signOutputs === 'none') {
-          signatureScope |= TransactionSignature.SIGHASH_NONE
-        }
-        if (signOutputs === 'single') {
-          signatureScope |= TransactionSignature.SIGHASH_SINGLE
-        }
-        if (anyoneCanPay) {
-          signatureScope |= TransactionSignature.SIGHASH_ANYONECANPAY
-        }
-        const otherInputs = [...tx.inputs]
-        const [input] = otherInputs.splice(inputIndex, 1)
-        if (typeof input.sourceTransaction !== 'object') {
-          throw new Error(
-            'The source transaction is needed for transaction signing.'
-          )
-        }
-        const preimage = TransactionSignature.format({
-          sourceTXID: input.sourceTransaction.id('hex') as string,
-          sourceOutputIndex: input.sourceOutputIndex,
-          sourceSatoshis: input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis,
-          transactionVersion: tx.version,
-          otherInputs,
-          inputIndex,
-          outputs: tx.outputs,
-          inputSequence: input.sequence,
-          subscript: input.sourceTransaction.outputs[input.sourceOutputIndex].lockingScript,
-          lockTime: tx.lockTime,
-          scope: signatureScope
-        })
-        const rawSignature = privateKey.sign(sha256(preimage), undefined, true, k)
-        const sig = new TransactionSignature(
-          rawSignature.r,
-          rawSignature.s,
-          signatureScope
-        )
-        const sigForScript = sig.toChecksigFormat()
-        const pubkeyForScript = privateKey.toPublicKey().encode(true) as number[]
-        return new UnlockingScript([
-          { op: sigForScript.length, data: sigForScript },
-          { op: pubkeyForScript.length, data: pubkeyForScript }
-        ])
-      },
-      estimateLength: async () => {
-        // public key (1+33) + signature (1+71)
-        // Note: We add 1 to each element's length because of the associated OP_PUSH
-        return 106
-      }
-    }
-  }
-}

package/src/script/templates/index.ts

@@ -1,2 +0,0 @@
-export { default as P2PKH } from './P2PKH.js'
-export { default as RPuzzle } from './RPuzzle.js'

package/src/transaction/Broadcaster.ts

@@ -1,42 +0,0 @@
-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
-}
-
-/**
- * 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} description - A detailed description of the error.
- */
-export interface BroadcastFailure {
-  status: 'error'
-  code: string
-  description: string
-}
-
-/**
- * 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.
- */
-export interface Broadcaster {
-  broadcast: (transaction: Transaction) =>
-  Promise<BroadcastResponse | BroadcastFailure>
-}

package/src/transaction/ChainTracker.ts

@@ -1,22 +0,0 @@
-/**
- * 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.
- *
- * @example
- * const chainTracker = {
- *   isValidRootForHeight: async (root, height) => {
- *     // Implementation to check if the Merkle root is valid for the specified block height.
- *   }
- * };
- */
-export default interface ChainTracker {
-  isValidRootForHeight: (root: string, height: number) => Promise<boolean>
-}

package/src/transaction/FeeModel.ts

@@ -1,13 +0,0 @@
-import Transaction from './Transaction.js'
-import BigNumber from '../primitives/BigNumber.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>
-}

package/src/transaction/MerklePath.ts

@@ -1,259 +0,0 @@
-import { Reader, Writer, toHex, toArray } from '../primitives/utils.js'
-import { hash256 } from '../primitives/Hash.js'
-import ChainTracker from './ChainTracker.js'
-
-/**
- * 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): MerklePath {
-    const blockHeight = reader.readVarIntNum()
-    const treeHeight = reader.readUInt8()
-    const path = Array(treeHeight).fill(0).map(() => ([]))
-    let flags, offset, nLeavesAtThisHeight
-    for (let level = 0; level < treeHeight; level++) {
-      nLeavesAtThisHeight = reader.readVarIntNum()
-      while (nLeavesAtThisHeight) {
-        offset = reader.readVarIntNum()
-        flags = reader.readUInt8()
-        const leaf: {
-          offset: number
-          hash?: string
-          txid?: boolean
-          duplicate?: boolean
-        } = { offset }
-        if (flags & 1) {
-          leaf.duplicate = true
-        } else {
-          if (flags & 2) {
-            leaf.txid = true
-          }
-          leaf.hash = toHex(reader.read(32).reverse())
-        }
-        path[level].push(leaf)
-        nLeavesAtThisHeight--
-      }
-      path[level].sort((a, b) => a.offset - b.offset)
-    }
-    return new MerklePath(blockHeight, path)
-  }
-
-  /**
-   * 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)
-  }
-
-  constructor (blockHeight: number, path: Array<Array<{
-    offset: number
-    hash?: string
-    txid?: boolean
-    duplicate?: boolean
-  }>>) {
-    this.blockHeight = blockHeight
-    this.path = path
-
-    // store all of the legal offsets which we expect given the txid indices.
-    let legalOffsets = Array(this.path.length).fill(0).map(() => new Set())
-    this.path.map((leaves, height) => {
-      if (leaves.length === 0) {
-        throw new Error(`Empty level at height: ${height}`)
-      }
-      const offsetsAtThisHeight = new Set()
-      leaves.map(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 (!legalOffsets[height].has(leaf.offset)) {
-            throw new Error(`Invalid offset: ${leaf.offset}, at height: ${height}, with legal offsets: ${Array.from(legalOffsets[height]).join(', ')}`)
-          }
-        }
-      })
-    })
-
-    let root: string
-    // every txid must calculate to the same root.
-    this.path[0].map((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) {
-          flags |= 1
-        }
-        if (leaf?.txid) {
-          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())
-  }
-
-  /**
-   * 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') {
-      txid = this.path[0].find(leaf => Boolean(leaf?.hash)).hash
-    }
-    // Find the index of the txid at the lowest level of the Merkle tree
-    const index = this.path[0].find(l => l.hash === txid).offset
-    if (typeof index !== 'number') {
-      throw Error(`This proof does not contain the txid: ${txid}`)
-    }
-    // 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()) as number[]
-    ).reverse())
-    let workingHash = txid
-    for (let height = 0; height < this.path.length; height++) {
-      const leaves = this.path[height]
-      const offset = index >> height ^ 1
-      const leaf = leaves.find(l => l.offset === offset)
-      if (typeof leaf !== 'object') {
-        throw new Error(`Missing hash for index ${index} at height ${height}`)
-      }
-      if (leaf.duplicate) {
-        workingHash = hash(workingHash + workingHash)
-      } else if (offset % 2 !== 0) {
-        workingHash = hash(leaf.hash + workingHash)
-      } else {
-        workingHash = hash(workingHash + leaf.hash)
-      }
-    }
-    return workingHash
-  }
-
-  /**
-   * 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)
-    // 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 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 Error('You cannot combine paths which do not have the same root.')
-    }
-    const combinedPath = []
-    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) as boolean)) {
-          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) {
-            combinedPath[h].find(leaf => leaf.offset === other.path[h][l]).txid = true
-          }
-        }
-      }
-    }
-    this.path = combinedPath
-  }
-}