@bsv/sdk 1.0.0

package/src/transaction/Transaction.ts

@@ -0,0 +1,602 @@
+import TransactionInput from './TransactionInput.js'
+import TransactionOutput from './TransactionOutput.js'
+import UnlockingScript from '../script/UnlockingScript.js'
+import LockingScript from '../script/LockingScript.js'
+import { Reader, Writer, toHex, toArray } from '../primitives/utils.js'
+import { hash256 } from '../primitives/Hash.js'
+import BigNumber from '../primitives/BigNumber.js'
+import FeeModel from './FeeModel.js'
+import SatoshisPerKilobyte from './fee-models/SatoshisPerKilobyte.js'
+import { Broadcaster, BroadcastResponse, BroadcastFailure } from './Broadcaster.js'
+import MerklePath from './MerklePath.js'
+import Spend from '../script/Spend.js'
+import ChainTracker from './ChainTracker.js'
+
+/**
+ * Represents a complete Bitcoin transaction. This class encapsulates all the details
+ * required for creating, signing, and processing a Bitcoin transaction, including
+ * inputs, outputs, and various transaction-related methods.
+ *
+ * @class Transaction
+ * @property {number} version - The version number of the transaction. Used to specify
+ *           which set of rules this transaction follows.
+ * @property {TransactionInput[]} inputs - An array of TransactionInput objects, representing
+ *           the inputs for the transaction. Each input references a previous transaction's output.
+ * @property {TransactionOutput[]} outputs - An array of TransactionOutput objects, representing
+ *           the outputs for the transaction. Each output specifies the amount of satoshis to be
+ *           transferred and the conditions under which they can be spent.
+ * @property {number} lockTime - The lock time of the transaction. If non-zero, it specifies the
+ *           earliest time or block height at which the transaction can be added to the block chain.
+ * @property {Record<string, any>} metadata - A key-value store for attaching additional data to
+ *           the transaction object, not included in the transaction itself. Useful for adding descriptions, internal reference numbers, or other information.
+ * @property {MerkleProof} [merkleProof] - Optional. A merkle proof demonstrating the transaction's
+ *           inclusion in a block. Useful for transaction verification using SPV.
+ *
+ * @example
+ * // Creating a new transaction
+ * let tx = new Transaction();
+ * tx.addInput(...);
+ * tx.addOutput(...);
+ * await tx.fee();
+ * await tx.sign();
+ * await tx.broadcast();
+ *
+ * @description
+ * The Transaction class provides comprehensive
+ * functionality to handle various aspects of transaction creation, including
+ * adding inputs and outputs, computing fees, signing the transaction, and
+ * generating its binary or hexadecimal representation.
+ */
+export default class Transaction {
+  version: number
+  inputs: TransactionInput[]
+  outputs: TransactionOutput[]
+  lockTime: number
+  metadata: Record<string, any>
+  merklePath?: MerklePath
+
+  /**
+   * Creates a new transaction, linked to its inputs and their associated merkle paths, from a BEEF (BRC-62) structure.
+   * @param beef A binary representation of a transaction in BEEF format.
+   * @returns An anchored transaction, linked to its associated inputs populated with merkle paths.
+   */
+  static fromBEEF(beef: number[]): Transaction {
+    const reader = new Reader(beef)
+    // Read the version
+    const version = reader.readUInt32LE()
+    if (version !== 4022206465) {
+      throw new Error(`Invalid BEEF version. Expected 4022206465, received ${version}.`)
+    }
+
+    // Read the BUMPs
+    const numberOfBUMPs = reader.readVarIntNum()
+    const BUMPs = []
+    for (let i = 0; i < numberOfBUMPs; i++) {
+      BUMPs.push(MerklePath.fromReader(reader))
+    }
+
+    // Read all transactions into an object
+    // The object has keys of TXIDs and values of objects with transactions and BUMP indexes
+    const numberOfTransactions = reader.readVarIntNum()
+    const transactions: Record<string, { pathIndex?: number, tx: Transaction }> = {}
+    let lastTXID: string
+    for (let i = 0; i < numberOfTransactions; i++) {
+      const tx = Transaction.fromReader(reader)
+      const obj: { pathIndex?: number, tx: Transaction } = { tx }
+      const txid = tx.id('hex') as string
+      if (i + 1 === numberOfTransactions) { // The last tXID is stored for later
+        lastTXID = txid
+      }
+      const hasBump = Boolean(reader.readUInt8())
+      if (hasBump) {
+        obj.pathIndex = reader.readVarIntNum()
+      }
+      transactions[txid] = obj
+    }
+
+    // Recursive function for adding merkle proofs or input transactions
+    const addPathOrInputs = (obj: { pathIndex?: number, tx: Transaction }): void => {
+      if (typeof obj.pathIndex === 'number') {
+        const path = BUMPs[obj.pathIndex]
+        if (typeof path !== 'object') {
+          throw new Error('Invalid merkle path index found in BEEF!')
+        }
+        obj.tx.merklePath = path
+      } else {
+        for (let i = 0; i < obj.tx.inputs.length; i++) {
+          const input = obj.tx.inputs[i]
+          const sourceObj = transactions[input.sourceTXID]
+          if (typeof sourceObj !== 'object') {
+            throw new Error(`Reference to unknown TXID in BUMP: ${input.sourceTXID}`)
+          }
+          input.sourceTransaction = sourceObj.tx
+          addPathOrInputs(sourceObj)
+        }
+      }
+    }
+
+    // Read the final transaction and Add inputs and merkle proofs to the final transaction, returning it
+    addPathOrInputs(transactions[lastTXID])
+    return transactions[lastTXID].tx
+  }
+
+  private static fromReader(br: Reader): Transaction {
+    const version = br.readUInt32LE()
+    const inputsLength = br.readVarIntNum()
+    const inputs: TransactionInput[] = []
+    for (let i = 0; i < inputsLength; i++) {
+      const sourceTXID = toHex(br.readReverse(32))
+      const sourceOutputIndex = br.readUInt32LE()
+      const scriptLength = br.readVarIntNum()
+      const scriptBin = br.read(scriptLength)
+      const unlockingScript = UnlockingScript.fromBinary(scriptBin)
+      const sequence = br.readUInt32LE()
+      inputs.push({
+        sourceTXID,
+        sourceOutputIndex,
+        unlockingScript,
+        sequence
+      })
+    }
+    const outputsLength = br.readVarIntNum()
+    const outputs: TransactionOutput[] = []
+    for (let i = 0; i < outputsLength; i++) {
+      const satoshis = br.readUInt64LEBn().toNumber()
+      const scriptLength = br.readVarIntNum()
+      const scriptBin = br.read(scriptLength)
+      const lockingScript = LockingScript.fromBinary(scriptBin)
+      outputs.push({
+        satoshis,
+        lockingScript
+      })
+    }
+    const lockTime = br.readUInt32LE()
+    return new Transaction(version, inputs, outputs, lockTime)
+  }
+
+  /**
+   * Creates a Transaction instance from a binary array.
+   *
+   * @static
+   * @param {number[]} bin - The binary array representation of the transaction.
+   * @returns {Transaction} - A new Transaction instance.
+   */
+  static fromBinary(bin: number[]): Transaction {
+    const br = new Reader(bin)
+    return Transaction.fromReader(br)
+  }
+
+  /**
+   * Creates a Transaction instance from a hexadecimal string.
+   *
+   * @static
+   * @param {string} hex - The hexadecimal string representation of the transaction.
+   * @returns {Transaction} - A new Transaction instance.
+   */
+  static fromHex(hex: string): Transaction {
+    return Transaction.fromBinary(toArray(hex, 'hex'))
+  }
+
+  /**
+   * Creates a Transaction instance from a hexadecimal string encoded BEEF.
+   *
+   * @static
+   * @param {string} hex - The hexadecimal string representation of the transaction BEEF.
+   * @returns {Transaction} - A new Transaction instance.
+   */
+  static fromHexBEEF(hex: string): Transaction {
+    return Transaction.fromBEEF(toArray(hex, 'hex'))
+  }
+
+  constructor(
+    version: number = 1,
+    inputs: TransactionInput[] = [],
+    outputs: TransactionOutput[] = [],
+    lockTime: number = 0,
+    metadata: Record<string, any> = {},
+    merklePath?: MerklePath
+  ) {
+    this.version = version
+    this.inputs = inputs
+    this.outputs = outputs
+    this.lockTime = lockTime
+    this.metadata = metadata
+    this.merklePath = merklePath
+  }
+
+  /**
+   * Adds a new input to the 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 {
+    if (
+      typeof input.sourceTXID === 'undefined' &&
+      typeof input.sourceTransaction === 'undefined'
+    ) {
+      throw new Error('A reference to an an input transaction is required. If the input transaction itself cannot be referenced, its TXID must still be provided.')
+    }
+    // If the input sequence number hasn't been set, the expectation is that it is final.
+    if (typeof input.sequence === 'undefined') {
+      input.sequence = 0xFFFFFFFF
+    }
+    this.inputs.push(input)
+  }
+
+  /**
+   * Adds a new output to the transaction.
+   *
+   * @param {TransactionOutput} output - The TransactionOutput object to add to the transaction.
+   */
+  addOutput(output: TransactionOutput): void {
+    this.outputs.push(output)
+  }
+
+  /**
+   * Updates the transaction's metadata.
+   *
+   * @param {Record<string, any>} metadata - The metadata object to merge into the existing metadata.
+   */
+  updateMetadata(metadata: Record<string, any>): void {
+    this.metadata = {
+      ...this.metadata,
+      ...metadata
+    }
+  }
+
+  /**
+   * Computes fees prior to signing.
+   * If no fee model is provided, uses a SatoshisPerKilobyte fee model that pays 10 sat/kb.
+   *
+   * @param model - The initialized fee model to use
+   * @param changeDistribution - Specifies how the change should be distributed
+   * amongst the change outputs
+   *
+   * TODO: Benford's law change distribution.
+   */
+  async fee(model?: FeeModel, changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
+    if (typeof model === 'undefined') {
+      model = new SatoshisPerKilobyte(10)
+    }
+    const fee = await model.computeFee(this)
+    // change = inputs - fee - non-change outputs
+    let change = 0
+    for (const input of this.inputs) {
+      if (typeof input.sourceTransaction !== 'object') {
+        throw new Error('Source transactions are required for all inputs during fee computation')
+      }
+      change += input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis
+    }
+    change -= fee
+    let changeCount = 0
+    for (const out of this.outputs) {
+      if (!out.change) {
+        change -= out.satoshis
+      } else {
+        changeCount++
+      }
+    }
+
+    if (change <= changeCount) {
+      // There is not enough change to distribute among the change outputs.
+      // We'll remove all change outputs and leave the extra for the miners.
+      for (let i = 0; i < this.outputs.length; i++) {
+        if (this.outputs[i].change) {
+          this.outputs.splice(i, 1)
+          i--
+        }
+      }
+      return
+    }
+
+    // Distribute change among change outputs
+    if (changeDistribution === 'random') {
+      // TODO
+      throw new Error('Not yet implemented')
+    } else if (changeDistribution === 'equal') {
+      const perOutput = Math.floor(change / changeCount)
+      for (const out of this.outputs) {
+        if (out.change) {
+          out.satoshis = perOutput
+        }
+      }
+    }
+  }
+
+  /**
+   * Signs a transaction, hydrating all its unlocking scripts based on the provided script templates where they are available.
+   */
+  async sign(): Promise<void> {
+    for (const out of this.outputs) {
+      if (typeof out.satoshis === 'undefined') {
+        if (out.change) {
+          throw new Error('There are still change outputs with uncomputed amounts. Use the fee() method to compute the change amounts and transaction fees prior to signing.')
+        } else {
+          throw new Error('One or more transaction outputs is missing an amount. Ensure all output amounts are provided before signing.')
+        }
+      }
+    }
+    for (let i = 0, l = this.inputs.length; i < l; i++) {
+      if (typeof this.inputs[i].unlockingScriptTemplate === 'object') {
+        this.inputs[i].unlockingScript = await this.inputs[i]
+          .unlockingScriptTemplate
+          .sign(this, i)
+      }
+    }
+  }
+
+  /**
+   * Broadcasts a transaction.
+   *
+   * @param broadcaster The Broadcaster instance wwhere the transaction will be sent
+   * @returns A BroadcastResponse or BroadcastFailure from the Broadcaster
+   */
+  async broadcast(broadcaster: Broadcaster): Promise<BroadcastResponse | BroadcastFailure> {
+    return await broadcaster.broadcast(this)
+  }
+
+  /**
+   * Converts the transaction to a binary array format.
+   *
+   * @returns {number[]} - The binary array representation of the transaction.
+   */
+  toBinary(): number[] {
+    const writer = new Writer()
+    writer.writeUInt32LE(this.version)
+    writer.writeVarIntNum(this.inputs.length)
+    for (const i of this.inputs) {
+      if (typeof i.sourceTransaction !== 'undefined') {
+        writer.write(i.sourceTransaction.hash() as number[])
+      } else {
+        writer.writeReverse(toArray(i.sourceTXID, 'hex'))
+      }
+      writer.writeUInt32LE(i.sourceOutputIndex)
+      const scriptBin = i.unlockingScript.toBinary()
+      writer.writeVarIntNum(scriptBin.length)
+      writer.write(scriptBin)
+      writer.writeUInt32LE(i.sequence)
+    }
+    writer.writeVarIntNum(this.outputs.length)
+    for (const o of this.outputs) {
+      writer.writeUInt64LE(o.satoshis)
+      const scriptBin = o.lockingScript.toBinary()
+      writer.writeVarIntNum(scriptBin.length)
+      writer.write(scriptBin)
+    }
+    writer.writeUInt32LE(this.lockTime)
+    return writer.toArray()
+  }
+
+  /**
+   * Converts the transaction to a BRC-30 EF format.
+   *
+   * @returns {number[]} - The BRC-30 EF representation of the transaction.
+   */
+  toEF(): number[] {
+    const writer = new Writer()
+    writer.writeUInt32LE(this.version)
+    writer.write([0, 0, 0, 0, 0, 0xef])
+    writer.writeVarIntNum(this.inputs.length)
+    for (const i of this.inputs) {
+      if (typeof i.sourceTransaction === 'undefined') {
+        throw new Error('All inputs must have source transactions when serializing to EF format')
+      }
+      writer.write(i.sourceTransaction.hash() as number[])
+      writer.writeUInt32LE(i.sourceOutputIndex)
+      const scriptBin = i.unlockingScript.toBinary()
+      writer.writeVarIntNum(scriptBin.length)
+      writer.write(scriptBin)
+      writer.writeUInt32LE(i.sequence)
+      writer.writeUInt64LE(i.sourceTransaction.outputs[i.sourceOutputIndex].satoshis)
+      const lockingScriptBin = i.sourceTransaction.outputs[i.sourceOutputIndex].lockingScript.toBinary()
+      writer.writeVarIntNum(lockingScriptBin.length)
+      writer.write(lockingScriptBin)
+    }
+    writer.writeVarIntNum(this.outputs.length)
+    for (const o of this.outputs) {
+      writer.writeUInt64LE(o.satoshis)
+      const scriptBin = o.lockingScript.toBinary()
+      writer.writeVarIntNum(scriptBin.length)
+      writer.write(scriptBin)
+    }
+    writer.writeUInt32LE(this.lockTime)
+    return writer.toArray()
+  }
+
+  /**
+   * Converts the transaction to a hexadecimal string EF.
+   *
+   * @returns {string} - The hexadecimal string representation of the transaction EF.
+   */
+  toHexEF(): string {
+    return toHex(this.toEF())
+  }
+
+  /**
+   * Converts the transaction to a hexadecimal string format.
+   *
+   * @returns {string} - The hexadecimal string representation of the transaction.
+   */
+  toHex(): string {
+    return toHex(this.toBinary())
+  }
+
+  /**
+   * Converts the transaction to a hexadecimal string BEEF.
+   *
+   * @returns {string} - The hexadecimal string representation of the transaction BEEF.
+   */
+  toHexBEEF(): string {
+    return toHex(this.toBEEF())
+  }
+
+  /**
+   * Calculates the transaction's hash.
+   *
+   * @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 {
+    return hash256(this.toBinary(), enc)
+  }
+
+  /**
+   * 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 {
+    const id = hash256(this.toBinary()) as number[]
+    id.reverse()
+    if (enc === 'hex') {
+      return toHex(id)
+    }
+    return id
+  }
+
+  /**
+   * Verifies the legitimacy of the Bitcoin transaction according to the rules of SPV by ensuring all the input transactions link back to valid block headers, the chain of spends for all inputs are valid, and the sum of inputs is not less than the sum of outputs.
+   *
+   * @param chainTracker - An instance of ChainTracker, a Bitcoin block header tracker. If the value is set to 'scripts only', headers will not be verified.
+   *
+   * @returns Whether the transaction is valid according to the rules of SPV.
+   */
+  async verify(chainTracker: ChainTracker | 'scripts only'): Promise<boolean> {
+    // If the transaction has a valid merkle path, verification is complete.
+    if (typeof this.merklePath === 'object' && chainTracker !== 'scripts only') {
+      const proofValid = await this.merklePath.verify(
+        this.id('hex') as string,
+        chainTracker
+      )
+      // Note that if the proof is provided but not valid, the transaction could still be verified by proving all inputs (if they are available) and checking the associated spends.
+      if (proofValid) {
+        return true
+      }
+    }
+
+    // Verify each input transaction and evaluate the spend events.
+    // Also, keep a total of the input amounts for later.
+    let inputTotal = 0
+    for (let i = 0; i < this.inputs.length; i++) {
+      const input = this.inputs[i]
+      if (typeof input.sourceTransaction !== 'object') {
+        throw new Error(`Verification failed because the input at index ${i} of transaction ${this.id('hex') as string} is missing an associated source transaction. This source transaction is required for transaction verification because there is no merkle proof for the transaction spending a UTXO it contains.`)
+      }
+      if (typeof input.unlockingScript !== 'object') {
+        throw new Error(`Verification failed because the input at index ${i} of transaction ${this.id('hex') as string} is missing an associated unlocking script. This script is required for transaction verification because there is no merkle proof for the transaction spending the UTXO.`)
+      }
+      const sourceOutput = input.sourceTransaction.outputs[input.sourceOutputIndex]
+      inputTotal += sourceOutput.satoshis
+      const inputVerified = await input.sourceTransaction.verify(chainTracker)
+      if (!inputVerified) {
+        return false
+      }
+      const otherInputs = [...this.inputs]
+      otherInputs.splice(i, 1)
+      const spend = new Spend({
+        sourceTXID: input.sourceTransaction.id('hex') as string,
+        sourceOutputIndex: input.sourceOutputIndex,
+        lockingScript: sourceOutput.lockingScript,
+        sourceSatoshis: sourceOutput.satoshis,
+        transactionVersion: this.version,
+        otherInputs,
+        unlockingScript: input.unlockingScript,
+        inputSequence: input.sequence,
+        inputIndex: i,
+        outputs: this.outputs,
+        lockTime: this.lockTime
+      })
+      const spendValid = spend.validate()
+      if (!spendValid) {
+        return false
+      }
+    }
+
+    // Total the outputs to ensure they don't amount to more than the inputs
+    let outputTotal = 0
+    for (const out of this.outputs) {
+      if (typeof out.satoshis !== 'number') {
+        throw new Error('Every output must have a defined amount during transaction verification.')
+      }
+      outputTotal += out.satoshis
+    }
+
+    return outputTotal <= inputTotal
+  }
+
+  /**
+   * 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.
+   *
+   * @returns The serialized BEEF structure
+   */
+  toBEEF(): number[] {
+    const writer = new Writer()
+    writer.writeUInt32LE(4022206465)
+    const BUMPs: MerklePath[] = []
+    const txs: Array<{ tx: Transaction, pathIndex?: number }> = []
+
+    // Recursive function to add paths and input transactions for a TX
+    const addPathsAndInputs = (tx: Transaction): void => {
+      const obj: { tx: Transaction, pathIndex?: number } = { tx }
+      const hasProof = typeof tx.merklePath === 'object'
+      if (hasProof) {
+        let added = false
+        // If this proof is identical to another one previously added, we use that first. Otherwise, we try to merge it with proofs from the same block.
+        for (let i = 0; i < BUMPs.length; i++) {
+          if (BUMPs[i] === tx.merklePath) { // Literally the same
+            obj.pathIndex = i
+            added = true
+            break
+          }
+          if (BUMPs[i].blockHeight === tx.merklePath.blockHeight) {
+            // Probably the same...
+            const rootA = BUMPs[i].computeRoot()
+            const rootB = tx.merklePath.computeRoot()
+            if (rootA === rootB) {
+              // Definitely the same... combine them to save space
+              BUMPs[i].combine(tx.merklePath)
+              obj.pathIndex = i
+              added = true
+              break
+            }
+          }
+        }
+        // Finally, if the proof is not yet added, add a new path.
+        if (!added) {
+          obj.pathIndex = BUMPs.length
+          BUMPs.push(tx.merklePath)
+        }
+      }
+      txs.unshift(obj)
+      if (!hasProof) {
+        for (let i = 0; i < tx.inputs.length; i++) {
+          const input = tx.inputs[i]
+          if (typeof input.sourceTransaction !== 'object') {
+            throw new Error('A required source transaction is missing!')
+          }
+          addPathsAndInputs(input.sourceTransaction)
+        }
+      }
+    }
+
+    addPathsAndInputs(this)
+
+    writer.writeVarIntNum(BUMPs.length)
+    for (const b of BUMPs) {
+      writer.write(b.toBinary())
+    }
+    writer.writeVarIntNum(txs.length)
+    for (const t of txs) {
+      writer.write(t.tx.toBinary())
+      if (typeof t.pathIndex === 'number') {
+        writer.writeUInt8(1)
+        writer.writeVarIntNum(t.pathIndex)
+      } else {
+        writer.writeUInt8(0)
+      }
+    }
+    return writer.toArray()
+  }
+}

package/src/transaction/TransactionInput.ts

@@ -0,0 +1,63 @@
+import UnlockingScript from '../script/UnlockingScript.js'
+import Transaction from './Transaction.js'
+
+/**
+ * Represents an input to a Bitcoin transaction.
+ * This interface defines the structure and components required to construct
+ * a transaction input in the Bitcoin blockchain.
+ *
+ * @interface TransactionInput
+ * @property {Transaction} [sourceTransaction] - Optional. The source transaction
+ *           from which this input is derived. This is the transaction whose output
+ *           is being spent by this input. Preferably provided if available.
+ * @property {string} [sourceTXID] - Optional. The transaction ID (TXID) of the source
+ *           transaction. Required if the source transaction itself is not provided.
+ *           This uniquely identifies the transaction within the blockchain.
+ * @property {number} sourceOutputIndex - The index of the output in the source transaction
+ *           that this input is spending. It is zero-based, indicating the position of the
+ *           output in the array of outputs of the source transaction.
+ * @property {UnlockingScript} [unlockingScript] - Optional. The script that 'unlocks' the
+ *           source output for spending. This script typically contains signatures and
+ *           public keys that evidence the ownership of the output.
+ * @property {Object} [unlockingScriptTemplate] - Optional. A template for generating the
+ *           unlocking script. Useful when the unlocking script needs to be generated
+ *           dynamically.
+ *    @property {Function} unlockingScriptTemplate.sign - A function that, when given the
+ *              current transaction and the index of this input, returns a Promise that
+ *              resolves to the UnlockingScript.
+ *    @property {Function} unlockingScriptTemplate.estimateLength - A function that estimates
+ *              the length of the unlocking script, given the transaction and the input index.
+ * @property {number} sequence - A sequence number for the input. Used to enable
+ *           updates to this input. If set to a non-final value (less than 0xFFFFFFFF),
+ *           it indicates that the input may be replaced in the future.
+ *
+ * @example
+ * // Creating a simple transaction input
+ * let txInput = {
+ *   sourceTXID: '123abc...',
+ *   sourceOutputIndex: 0,
+ *   sequence: 0xFFFFFFFF
+ * };
+ *
+ * // Using an unlocking script template
+ * txInput.unlockingScriptTemplate = {
+ *   sign: async (tx, index) => { ... },
+ *   estimateLength: async (tx, index) => { ... }
+ * };
+ *
+ * @description
+ * This interface links an input to a
+ * previous output and provides mechanisms (through unlocking scripts) to authorize the
+ * spending of that output.
+ */
+export default interface TransactionInput {
+  sourceTransaction?: Transaction
+  sourceTXID?: string
+  sourceOutputIndex: number
+  unlockingScript?: UnlockingScript
+  unlockingScriptTemplate?: {
+    sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
+    estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>
+  }
+  sequence: number
+}

package/src/transaction/TransactionOutput.ts

@@ -0,0 +1,37 @@
+import BigNumber from '../primitives/BigNumber.js'
+import LockingScript from '../script/LockingScript.js'
+
+/**
+ * Represents an output in a Bitcoin transaction.
+ * This interface defines the structure and components necessary to construct
+ * a transaction output, which secures owned Bitcoins to be unlocked later.
+ *
+ * @interface TransactionOutput
+ * @property {number} [satoshis] - Optional. The amount of satoshis (the smallest unit of Bitcoin) to be transferred by this output.
+ * @property {LockingScript} lockingScript - The script that 'locks' the satoshis,
+ *           specifying the conditions under which they can be spent. This script is
+ *           essential for securing the funds and typically contains cryptographic
+ *           puzzles that need to be solved to spend the output.
+ * @property {boolean} [change] - Optional. A flag that indicates whether this output
+ *           is a change output. If true, it means this output is returning funds back
+ *           to the sender, usually as the 'change' from the transaction inputs.
+ *
+ * @example
+ * // Creating a simple transaction output
+ * let txOutput = {
+ *   satoshis: 1000,
+ *   lockingScript: LockingScript.fromASM('OP_DUP OP_HASH160 ... OP_EQUALVERIFY OP_CHECKSIG'),
+ *   change: false
+ * };
+ *
+ * @description
+ * The TransactionOutput interface defines how bitcoins are to be distributed in a transaction, either to a recipient or
+ * back to the sender as change. The lockingScript is critical as it determines the conditions
+ * under which the output can be spent, typically requiring a digital signature matching the
+ * intended recipient's public key.
+ */
+export default interface TransactionOutput {
+  satoshis?: number
+  lockingScript: LockingScript
+  change?: boolean
+}