@vbyte/btc-dev 1.0.0

package/src/lib/taproot/parse.ts

@@ -0,0 +1,65 @@
+import { Buff, Stream }       from '@vbyte/buff'
+import { Assert, ECC }        from '@vbyte/micro-lib'
+import { parse_witness_data } from '@/lib/tx/witness.js'
+
+import {
+  encode_tapbranch,
+  encode_tapscript,
+  encode_taptweak,
+} from './encode.js'
+
+import type { ControlBlock } from '@/types/index.js'
+
+export function parse_taproot_witness (witness : string[]) {
+  const { cblock, params, script } = parse_witness_data(witness)
+
+  Assert.exists(cblock, 'cblock is null')
+  Assert.exists(script, 'script is null')
+
+  const cblk   = parse_cblock(cblock)
+  const target = encode_tapscript(script, cblk.version)
+
+  let branch = target.hex
+
+  for (const leaf of cblk.path) {
+    branch = encode_tapbranch(branch, leaf).hex
+  }
+
+  const tweak  = encode_taptweak(cblk.int_key, branch)
+  const tapkey = ECC.tweak_pubkey(cblk.int_key, tweak, 'bip340')
+
+  params.map(e => Buff.bytes(e).hex)
+
+  return { cblock: cblk, params, script, tapkey: tapkey.hex, tweak: tweak.hex }
+}
+
+export function parse_cblock (cblock : string | Uint8Array) : ControlBlock {
+  const buffer  = new Stream(cblock)
+  const cbyte   = buffer.read(1).num
+  const int_key = buffer.read(32).hex
+  const [ version, parity ] = parse_cblock_parity(cbyte)
+  const path = []
+  while (buffer.size >= 32) {
+    path.push(buffer.read(32).hex)
+  }
+  if (buffer.size !== 0) {
+    throw new Error('Non-empty buffer on control block: ' + String(buffer))
+  }
+  return { int_key, path, parity, version }
+}
+
+export function parse_cblock_parity (cbits : number) {
+  return (cbits % 2 === 0)
+    ? [ cbits - 0, 0x02 ]
+    : [ cbits - 1, 0x03 ]
+}
+
+export function parse_pubkey_parity (
+  pubkey : string | Uint8Array
+) : number {
+  Assert.size(pubkey, 33, 'invalid pubkey size')
+  const [ parity ] = Buff.bytes(pubkey)
+  if (parity === 0x02) return 0
+  if (parity === 0x03) return 1
+  throw new Error('Invalid parity bit: ' + String(parity))
+}

package/src/lib/taproot/tree.ts

@@ -0,0 +1,94 @@
+import { Buff }             from '@vbyte/buff'
+import { encode_tapbranch } from './encode.js'
+
+import type { TapTree, MerkleProof } from '@/types/index.js'
+
+/**
+ * Get the root of a taproot tree.
+ * @param leaves - The leaves of the tree.
+ * @returns The root of the tree.
+ */
+export function get_merkle_root (leaves : TapTree) {
+  // Process the merkle tree, and return the root.
+  return merkleize(leaves)[0]
+}
+
+/**
+ * Process a taproot tree into a merkle proof.
+ * @param taptree - The leaves of the tree.
+ * @param target  - The target leaf of the tree.
+ * @param path    - The recursive path of the tree.
+ * @returns The root of the tree.
+ */
+export function merkleize (
+  taptree : TapTree,
+  target ?: string,
+  path    : string[] = []
+) : MerkleProof {
+  // Initialize the leaves and tree arrays.
+  const leaves : string[] = []
+  const tree   : string[] = []
+  // If there are no leaves, throw an error.
+  if (taptree.length < 1) {
+    throw new Error('Tree is empty!')
+  }
+  // Crawl through the tree, and find each leaf.
+  for (let i = 0; i < taptree.length; i++) {
+    // Get the current leaf as bytes.
+    const bytes = taptree[i]
+    // If the leaf is an array,
+    if (Array.isArray(bytes)) {
+      // Recursively process the nested tree.
+      let [ tapleaf, new_target, branches ] = merkleize(bytes, target)
+      // Update the target leaf.
+      target = new_target
+      // Add the nested tapleaf to the leaves array.
+      leaves.push(tapleaf)
+      // For each branch node,
+      for (const branch of branches) {
+        // Add the branch to the path.
+        path.push(branch)
+      }
+    } else {
+      // Convert the leaf to a hex string.
+      const leaf = Buff.bytes(bytes).hex
+      // Add the leaf to the leaves array.
+      leaves.push(leaf)
+    }
+  }
+
+  // If there is only one leaf,
+  if (leaves.length === 1) {
+    // Return the leaf as the root.
+    return [ leaves[0], target, path ]
+  }
+  // Ensure the tree is sorted at this point.
+  leaves.sort()
+  // Ensure the tree is balanced evenly.
+  if (leaves.length % 2 !== 0) {
+    // If uneven, duplicate the last leaf.
+    leaves.push(leaves[leaves.length - 1])
+  }
+  // Sort through the leaves (two at a time).
+  for (let i = 0; i < leaves.length - 1; i += 2) {
+    // Compute two leaves into a branch.
+    const branch = encode_tapbranch(leaves[i], leaves[i + 1]).hex
+    // Push our branch to the tree.
+    tree.push(branch)
+    // Check if a proof target is specified.
+    if (typeof target === 'string') {
+      // Check if this branch is part of our proofs.
+      if (target === leaves[i]) {
+        // If so, include right-side of branch.
+        path.push(leaves[i + 1])
+        target = branch
+      } else if (target === leaves[i + 1]) {
+        // If so, include left-side of branch.
+        path.push(leaves[i])
+        target = branch
+      }
+    }
+  }
+  // Recursively process the tree.
+  return merkleize(tree, target, path)
+}

package/src/lib/tx/create.ts

@@ -0,0 +1,82 @@
+import { Assert }              from '@vbyte/micro-lib'
+import { COINBASE, DEFAULT }   from '@/const.js'
+
+import {
+  assert_tx_output,
+  assert_tx_template,
+  assert_vin_template
+} from './validate.js'
+
+import type {
+  TxData,
+  TxInputTemplate,
+  TxInput,
+  TxOutput,
+  TxTemplate,
+  SpendInput,
+  CoinbaseInput
+} from '@/types/index.js'
+
+export function create_coinbase_input (
+  config : TxInputTemplate | TxInput
+) : CoinbaseInput {
+  assert_vin_template(config)
+  Assert.exists(config.coinbase, 'coinbase is required')
+  const coinbase   = config.coinbase
+  const prevout    = null
+  const script_sig = null
+  const sequence   = config.sequence ?? DEFAULT.SEQUENCE
+  const txid       = COINBASE.TXID
+  const vout       = COINBASE.VOUT
+  const witness    = config.witness  ?? []
+  return { coinbase, prevout, script_sig, sequence, witness, txid, vout }
+}
+
+export function create_spend_input (
+  config : TxInputTemplate | TxInput
+) : SpendInput {
+  assert_vin_template(config)
+  Assert.exists(config.prevout, 'prevout is required')
+  const prevout    = config.prevout
+  const coinbase   = null
+  const script_sig = config.script_sig ?? null
+  const sequence   = config.sequence   ?? DEFAULT.SEQUENCE
+  const witness    = config.witness    ?? []
+  return { ...config, coinbase, prevout, script_sig, sequence, witness }
+}
+
+export function create_tx_input (
+  config : TxInputTemplate | TxInput
+) : TxInput {
+  assert_vin_template(config)
+  Assert.exists(config.txid, 'txid is required')
+  Assert.exists(config.vout, 'vout is required')
+  const coinbase   = config.coinbase   ?? null
+  const prevout    = config.prevout    ?? null
+  const script_sig = config.script_sig ?? null
+  const sequence   = config.sequence   ?? DEFAULT.SEQUENCE
+  const witness    = config.witness    ?? []
+  if (coinbase !== null) return create_coinbase_input(config)
+  if (prevout  !== null) return create_spend_input(config)
+  return { ...config, coinbase, prevout, script_sig, sequence, witness }
+}
+
+export function create_tx_output (
+  config : TxOutput
+) : TxOutput {
+  assert_tx_output(config)
+  const { script_pk, value } = config
+  return { script_pk, value : BigInt(value) }
+}
+
+export function create_tx_data (
+  config: TxTemplate | TxData
+) : TxData {
+  assert_tx_template(config)
+  const { vin = [], vout = [] } = config
+  const locktime = config.locktime ?? DEFAULT.LOCKTIME
+  const version  = config.version  ?? DEFAULT.VERSION
+  const inputs   = vin.map(txin   => create_tx_input(txin))
+  const outputs  = vout.map(txout => create_tx_output(txout))
+  return { locktime, vin : inputs, vout : outputs, version }
+}

package/src/lib/tx/decode.ts

@@ -0,0 +1,145 @@
+import { Bytes, Stream } from '@vbyte/buff'
+import { Assert }              from '@vbyte/micro-lib'
+import { parse_error }         from '@vbyte/micro-lib/util'
+import { COINBASE }            from '@/const.js'
+
+import {
+  TxData,
+  TxInput,
+  TxOutput,
+  CoinbaseInput,
+  VirtualInput,
+  SpendInput
+} from '@/types/index.js'
+
+interface TxEncoderConfig {
+  prevouts : TxOutput[]
+  segwit   : boolean
+}
+
+const DEFAULT_CONFIG : TxEncoderConfig = {
+  prevouts : [],
+  segwit   : true
+}
+
+export function decode_tx_data (
+  txbytes : Bytes,
+  options : Partial<TxEncoderConfig> = {}
+) : TxData {
+  // Merge the options with the default config.
+  const config = { ...DEFAULT_CONFIG, ...options }
+  // Assert the txhex is a bytes object.
+  Assert.is_bytes(txbytes, 'txbytes must be hex or a unit array')
+  // Setup a byte-stream.
+  const stream = new Stream(txbytes)
+  // Parse tx version.
+  const version = read_version(stream)
+  // Check and enable any flags that are set.
+  const has_witness = (config.segwit)
+    ? check_witness_flag(stream)
+    : false
+  // Parse our inputs and outputs.
+  const vin  = read_inputs(stream, config.prevouts)
+  const vout = read_outputs(stream)
+  // If witness flag is set, parse witness data.
+  if (has_witness) {
+    for (const txin of vin) {
+      txin.witness = read_witness(stream)
+    }
+  }
+  // Parse locktime.
+  const locktime = read_locktime(stream)
+  // Return transaction object with calculated fields.
+  return { version, vin, vout, locktime }
+}
+
+function read_version (stream : Stream) : number {
+  return stream.read(4).reverse().to_num()
+}
+
+function check_witness_flag (stream : Stream) : boolean {
+  const [ marker, flag ] : number[] = [ ...stream.peek(2) ]
+  if (marker === 0) {
+    stream.read(2)
+    if (flag === 1) {
+      return true
+    } else {
+      throw new Error(`Invalid witness flag: ${flag}`)
+    }
+  }
+  return false
+}
+
+function read_inputs (stream : Stream, prevouts : TxOutput[]) : TxInput[] {
+  const inputs = []
+  const vinCount = stream.varint()
+  for (let i = 0; i < vinCount; i++) {
+    const txinput = read_vin(stream, prevouts.at(i))
+    inputs.push(txinput)
+  }
+  return inputs
+}
+
+function read_vin (stream : Stream, prevout : TxOutput | null = null) : TxInput {
+  const txid       = stream.read(32).reverse().hex
+  const vout       = stream.read(4).reverse().num
+  const script_sig = read_script(stream, true)
+  const sequence   = stream.read(4).reverse().num
+  const witness : string[] = []
+  if (txid === COINBASE.TXID && vout === COINBASE.VOUT) {
+    return { coinbase : script_sig, prevout: null, script_sig : null, sequence, txid, vout, witness } as CoinbaseInput
+  } else if (prevout !== null) {
+    return { coinbase : null, prevout, script_sig, sequence, txid, vout, witness } as SpendInput
+  } else {
+    return { coinbase : null, prevout, script_sig, sequence, txid, vout, witness } as VirtualInput
+  }
+}
+
+function read_outputs (stream : Stream) : TxOutput[] {
+  const outputs = []
+  const vcount  = stream.varint()
+  for (let i = 0; i < vcount; i++) {
+    try {
+      outputs.push(read_vout(stream))
+    } catch (error) {
+      throw new Error(`failed to decode output: ${i}: ${parse_error(error)}`)
+    }
+  }
+  return outputs
+}
+
+function read_vout (stream : Stream) : TxOutput {
+  const value     = stream.read(8).reverse().big
+  const script_pk = read_script(stream, true)
+  Assert.exists(script_pk, 'failed to decode script_pk')
+  return { value, script_pk }
+}
+
+function read_witness (stream : Stream) : string[] {
+  const stack = []
+  const count = stream.varint()
+  for (let i = 0; i < count; i++) {
+    const element = read_script(stream, true)
+    if (element === null) {
+      throw new Error('failed to decode witness element: ' + i)
+    }
+    stack.push(element)
+  }
+  return stack
+}
+
+export function read_script (
+  stream  : Stream,
+  varint ?: boolean
+) : string | null {
+  const size = (varint === true)
+    ? stream.varint('le')
+    : stream.size
+  return size > 0
+    ? stream.read(size).hex
+    : null
+}
+
+function read_locktime (stream : Stream) : number {
+  return stream.read(4).reverse().to_num()
+}

package/src/lib/tx/encode.ts

@@ -0,0 +1,154 @@
+import { Buff }          from '@vbyte/buff'
+import { Assert }        from '@vbyte/micro-lib'
+import { parse_tx_data } from './parse.js'
+import { COINBASE }      from '@/const.js'
+
+import {
+  TxInput,
+  TxOutput,
+  TxData
+} from '@/types/index.js'
+
+export function encode_tx_data (
+  txdata : TxData,
+  segwit = true
+) : Buff {
+  const tx = parse_tx_data(txdata)
+  // Unpack the transaction data.
+  const { version, vin, vout, locktime } = tx
+  // Create a buffer for the transaction.
+  const buffer : Buff[] = [ encode_tx_version(version) ]
+  // If the transaction is a segwit transaction,
+  if (segwit) {
+    // Add the segwit marker to the buffer.
+    buffer.push(Buff.hex('0001'))
+  }
+  // Add the inputs to the buffer.
+  buffer.push(encode_tx_inputs(vin))
+  // Add the outputs to the buffer.
+  buffer.push(encode_tx_outputs(vout))
+  // If the transaction is a segwit transaction,
+  if (segwit) {
+    // For each input in the transaction,
+    for (const input of vin) {
+      // Add the witness data to the buffer.
+      buffer.push(encode_vin_witness(input.witness))
+    }
+  }
+  // Add the locktime to the buffer.
+  buffer.push(encode_tx_locktime(locktime))
+  // Return the buffer as a single payload. 
+  return Buff.join(buffer)
+}
+
+export function encode_tx_version (num : number) : Buff {
+  // Encode the transaction version as a 4-byte little-endian number.
+  return Buff.num(num, 4).reverse()
+}
+
+export function encode_txin_txid (txid : string) : Buff {
+  // Encode the transaction ID as a 32-byte little-endian number.
+  return Buff.hex(txid, 32).reverse()
+}
+
+export function encode_txin_vout (vout : number) : Buff {
+  // Encode the output index as a 4-byte little-endian number.
+  return Buff.num(vout, 4).reverse()
+}
+
+export function encode_txin_sequence (sequence : number) : Buff {
+  // Encode the sequence number as a 4-byte little-endian number.
+  return Buff.num(sequence, 4).reverse()
+}
+
+export function encode_tx_inputs (vin : TxInput[]) : Buff {
+  // Create a buffer for the inputs, starting with the array length.
+  const raw : Buff[] = [ Buff.varint(vin.length, 'le') ]
+  // For each input in the array,
+  for (const input of vin) {
+    // Encode the input, and add it to the buffer.
+    raw.push(encode_vin(input))
+  }
+  // Return the buffer as a single payload.
+  return Buff.join(raw)
+}
+
+export function encode_vin (txin : TxInput) : Buff {
+  // If the input is a coinbase,
+  if (txin.coinbase !== null) {
+    // Encode and return the coinbase as a single payload.
+    return Buff.join([
+      encode_txin_txid(COINBASE.TXID),
+      encode_txin_vout(COINBASE.VOUT),
+      encode_script_data(txin.coinbase),
+      encode_txin_sequence(txin.sequence)
+    ])
+  } else {
+    // Encode and return the input as a single payload.
+    return Buff.join([
+      encode_txin_txid(txin.txid),
+      encode_txin_vout(txin.vout),
+      encode_script_data(txin.script_sig),
+      encode_txin_sequence(txin.sequence)
+    ])
+    }
+}
+
+export function encode_vout_value (value : bigint) : Buff {
+  // Encode the value as an 8-byte little-endian number.
+  return Buff.big(value, 8).reverse()
+}
+
+export function encode_tx_outputs (vout : TxOutput[]) : Buff {
+  // Create a buffer for the outputs, starting with the array length.
+  const buffer : Buff[] = [ Buff.varint(vout.length, 'le') ]
+  // For each output in the array,
+  for (const output of vout) {
+    // Encode the output, and add it to the buffer.
+    buffer.push(encode_tx_vout(output))
+  }
+  // Return the buffer as a single payload.
+  return Buff.join(buffer)
+}
+
+export function encode_tx_vout (txout : TxOutput) : Buff {
+  // Get the value and script pubkey from the output.
+  const { value, script_pk } = txout
+  // Return the data encoded as a single payload.
+  return Buff.join([
+    encode_vout_value(value),
+    encode_script_data(script_pk)
+  ])
+}
+
+export function encode_vin_witness (data : string[]) : Buff {
+  // Create a buffer for the witness data, starting with the array length.
+  const buffer : Buff[] = [ Buff.varint(data.length) ]
+  // For each parameter in the witness array,
+  for (const param of data) {
+    // Encode the parameter, and add it to the buffer.
+    buffer.push(encode_script_data(param))
+  }
+  // Return the buffer as a single payload.
+  return Buff.join(buffer)
+}
+
+export function encode_tx_locktime (locktime : number) : Buff {
+  // Encode the locktime as a 4-byte little-endian number.
+  return Buff.num(locktime, 4).reverse()
+}
+
+export function encode_script_data (
+  script : string | null
+) : Buff {
+  // If the script is not null,
+  if (script !== null) {
+    // Assert that the script is a hex string.
+    Assert.is_hex(script)
+    // Encode the script, and add it to the buffer.
+    return Buff.hex(script).prefix_varint('le')
+  } else {
+    // Return a single byte of zero.
+    return Buff.hex('00')
+  }
+}

package/src/lib/tx/index.ts

@@ -0,0 +1,10 @@
+export * from './create.js'
+export * from './decode.js'
+export * from './encode.js'
+export * from './locktime.js'
+export * from './meta.js'
+export * from './parse.js'
+export * from './sequence.js'
+export * from './size.js'
+export * from './validate.js'
+export * from './witness.js'

package/src/lib/tx/locktime.ts

@@ -0,0 +1,57 @@
+import { Assert } from '@vbyte/micro-lib'
+
+import type { LocktimeInfo } from '@/types/index.js'
+
+// The threshold between block height and timestamp.
+const LOCKTIME_THRESHOLD = 500000000
+
+export namespace Locktime {
+  export const encode = encode_locktime
+  export const decode = decode_locktime
+}
+
+/**
+ * Encodes a LockTimeData object into a string representation.
+ * According to BIP-65, the value is simply the numeric value as a string.
+ */
+export function encode_locktime (
+  locktime : LocktimeInfo
+) : number {
+  switch (locktime.type) {
+    case 'timelock':
+      Assert.ok(locktime.stamp >= LOCKTIME_THRESHOLD, 'Invalid timestamp')
+      return locktime.stamp
+    case 'heightlock':
+      Assert.ok(locktime.height > 0,                  'height must be greater than 0')
+      Assert.ok(locktime.height < LOCKTIME_THRESHOLD, 'invalid block height')
+      return locktime.height
+    default:
+      throw new Error('Invalid locktime type')
+  }
+}
+
+/**
+ * Parses a string or number into a LockTimeData object.
+ * According to BIP-65, values below LOCKTIME_THRESHOLD are interpreted as block heights,
+ * while values at or above this threshold are interpreted as timestamps.
+ */
+export function decode_locktime (
+  locktime : number
+) : LocktimeInfo | null {
+  // Check if the value is valid (non-negative)
+  if (isNaN(locktime) || locktime <= 0) {
+    return null
+  }
+  // Return the appropriate locktime type.
+  if (locktime < LOCKTIME_THRESHOLD) {
+    return {
+      type   : 'heightlock',
+      height : locktime
+    }
+  } else {
+    return {
+      type  : 'timelock',
+      stamp : locktime
+    }
+  }
+}

package/src/lib/tx/meta.ts

@@ -0,0 +1,73 @@
+import { hash256 }             from '@vbyte/micro-lib/hash'
+import { LOCK_SCRIPT_REGEX }   from '@/const.js'
+import { encode_tx_data }      from './encode.js'
+import { parse_tx_data }       from './parse.js'
+
+import type {
+  TxData,
+  TxOutput,
+  TxOutputInfo,
+  TxOutputType,
+  TxValue,
+  WitnessVersion
+} from '@/types/index.js'
+
+export function is_return_script (script : string) : boolean {
+  return script.startsWith('6a')
+}
+
+export function get_vout_info (txout : TxOutput) : TxOutputInfo {
+  return {
+    type    : get_vout_type(txout.script_pk),
+    version : get_vout_version(txout.script_pk)
+  }
+}
+
+export function get_vout_type (
+  script : string
+) : TxOutputType {
+  for (const [ type, regex ] of Object.entries(LOCK_SCRIPT_REGEX)) {
+    if (regex.test(script)) return type as TxOutputType
+  }
+  return 'unknown'
+}
+
+export function get_vout_version (
+  script : string
+) : WitnessVersion {
+  const wit_ver = script.slice(0, 4)
+  switch (wit_ver) {
+    case '0014':
+      return 0
+    case '5120':
+      return 1
+    default:
+      return null
+  }
+}
+
+export function get_txid (
+  txdata : string | TxData
+) : string {
+  const json = parse_tx_data(txdata)
+  const data = encode_tx_data(json, false)
+  return hash256(data).reverse().hex
+}
+
+export function get_txhash (
+  txdata : string | TxData
+) : string {
+  const json = parse_tx_data(txdata)
+  const data = encode_tx_data(json, true)
+  return hash256(data).reverse().hex
+}
+
+export function get_tx_value (
+  txdata : string | TxData
+) : TxValue {
+  const tx   = parse_tx_data(txdata)
+  const vin  = tx.vin.reduce((acc, txin) => acc + (txin.prevout?.value ?? 0n), 0n)
+  const vout = tx.vout.reduce((acc, txout) => acc + txout.value, 0n)
+  const fees = (vin > vout) ? (vin - vout) : 0n
+  return { fees, vin, vout }
+}

package/src/lib/tx/parse.ts

@@ -0,0 +1,16 @@
+import { decode_tx_data }     from './decode.js'
+import { create_tx_data }     from './create.js'
+import { assert_tx_template } from './validate.js'
+
+import type { TxData } from '@/types/index.js'
+
+export function parse_tx_data (
+  txdata : unknown
+) : TxData {
+  if (typeof txdata === 'string') {
+    return decode_tx_data(txdata)
+  } else {
+    assert_tx_template(txdata)
+    return create_tx_data(txdata)
+  }
+}