@vbyte/btc-dev 1.0.0

package/src/lib/tx/sequence.ts

@@ -0,0 +1,146 @@
+/**
+ * Bitcoin Transaction Sequence Field Manipulation
+ * 
+ * This module provides functionality for encoding and decoding the sequence field in Bitcoin transactions.
+ * The sequence field is a 32-bit integer that can be used for various purposes:
+ * 
+ * 1. Relative timelocks (BIP-68).
+ * 2. Custom protocol data.
+ * 
+ * The implementation follows BIP-68 for timelock functionality, and extends it with a custom protocol
+ * that allows additional metadata to be encoded in the sequence field (to be used by on-chain indexers).
+ */
+
+import type { SequenceConfig, SequenceInfo } from '@/types/index.js'
+
+/* ===== [ Constants ] ===================================================== */
+
+const TIMELOCK_DISABLE     = 0x80000000  // Bit 31: When set, disables relative timelock per BIP-68.
+const TIMELOCK_TYPE        = 0x00400000  // Bit 22: When set, indicates timestamp-based lock; when clear, indicates block-height-based lock.
+const TIMELOCK_VALUE_MASK  = 0x0000FFFF  // Bits 0-15: Mask for extracting timelock value (16 bits).
+const TIMELOCK_VALUE_MAX   = 0xFFFF      // Maximum value for timelock (2^16 - 1).
+const TIMELOCK_GRANULARITY = 512         // Seconds per timestamp unit (BIP-68 specification).
+
+/* ===== [ API ] ============================================================ */
+
+export namespace Sequence {
+  export const encode = encode_sequence
+  export const decode = decode_sequence
+}
+
+/* ===== [ Encoder ] ======================================================== */
+
+/**
+ * Encodes a SequenceData object into a 32-bit integer sequence value
+ * 
+ * @param data - The sequence data to encode
+ * @returns A 32-bit integer representing the encoded sequence
+ * @throws Error if the input data is invalid or exceeds maximum values
+ */
+export function encode_sequence (data : SequenceConfig): number {
+  // If the timelock is based on a block height,
+  if (data.mode === 'height') {
+    // Validate the height value.
+    const height = parse_height(data.height)
+    // For heightlock, only encode the height value (TIMELOCK_TYPE bit remains clear)
+    return (height & TIMELOCK_VALUE_MASK) >>> 0
+  }
+  // If the timelock is based on a timestamp,
+  if (data.mode === 'stamp') {
+    // Convert timestamp to 512-second granularity units as per BIP-68.
+    const stamp = parse_stamp(data.stamp)
+    // Set the TIMELOCK_TYPE bit and encode the timestamp value.
+    return (TIMELOCK_TYPE | (stamp & TIMELOCK_VALUE_MASK)) >>> 0
+  }
+  // Throw an error if the mode is unrecognized.
+  throw new Error('invalid timelock mode: ' + data.mode)
+}
+
+/* ===== [ Decoder ] ========================================================= */
+
+/**
+ * Decodes a 32-bit sequence value into a SequenceData object
+ * 
+ * @param sequence - The 32-bit sequence value to decode
+ * @returns A SequenceData object or null if the sequence doesn't represent special data
+ * @throws Error if the sequence value is invalid or exceeds maximum values
+ */
+export function decode_sequence (sequence: number | string) : SequenceInfo | null {
+  // Parse and validate the sequence value.
+  const seq = parse_sequence(sequence)
+  // If the sequence is disabled, return null.
+  if (seq & TIMELOCK_DISABLE) return null
+  // Extract the value.
+  const value = seq & TIMELOCK_VALUE_MASK
+  // Check for timestamp-based lock (TIMELOCK_TYPE bit is set).
+  if (seq & TIMELOCK_TYPE) {
+    // Convert granularity units back to seconds for timestamp.
+    const stamp = value * TIMELOCK_GRANULARITY
+    // Validate the timestamp value.
+    if (stamp > 0xFFFFFFFF) {
+      throw new Error('Decoded timestamp exceeds 32-bit limit')
+    }
+    // Return the decoded timelock.
+    return { mode: 'stamp', stamp }
+  } else {
+    // Validate the height value.
+    if (value > TIMELOCK_VALUE_MAX) {
+      throw new Error('Decoded height exceeds maximum')
+    }
+    // Return the decoded heightlock.
+    return { mode: 'height', height: value }
+  }
+}
+
+/* ===== [ Helpers ] ========================================================= */
+
+/**
+ * Parses a sequence value into a number.
+ * 
+ * @param sequence - The sequence value to parse.
+ * @returns The parsed sequence value.
+ * @throws Error if the sequence value is invalid.
+ */
+function parse_sequence (sequence: number | string): number {
+  const seq = (typeof sequence === 'string')
+    ? parseInt(sequence, 16)
+    : sequence
+  if (!Number.isInteger(seq) || seq < 0 || seq > 0xFFFFFFFF) {
+    throw new Error(`invalid sequence value: ${seq}`)
+  }
+  return seq
+}
+
+/**
+ * Parses a timestamp value into a 512-second granularity units.
+ * 
+ * @param stamp - The timestamp value to parse.
+ * @returns The parsed timestamp value.
+ * @throws Error if the timestamp value is invalid.
+ */
+function parse_stamp (stamp? : number) : number {
+  if (stamp === undefined || !Number.isInteger(stamp)) {
+    throw new Error(`timestamp must be a number`)
+  }
+  // Convert timestamp to 512-second granularity units as per BIP-68.
+  const ts = Math.floor(stamp / TIMELOCK_GRANULARITY)
+  // Validate the timestamp value.
+  if (!Number.isInteger(ts) || ts < 0 || ts > TIMELOCK_VALUE_MAX) {
+    throw new Error(`timelock value must be an integer between 0 and ${TIMELOCK_VALUE_MAX} (in 512-second increments)`)
+  }
+  return ts
+}
+
+/**
+ * Parses a height value into a number.
+ * 
+ * @param height - The height value to parse.
+ * @returns The parsed height value.
+ * @throws Error if the height value is invalid.
+ */
+function parse_height (height? : number) : number {
+  if (height === undefined || !Number.isInteger(height) || height < 0 || height > TIMELOCK_VALUE_MAX) {
+    throw new Error(`Heightlock value must be an integer between 0 and ${TIMELOCK_VALUE_MAX}`)
+  }
+  return height
+}

package/src/lib/tx/size.ts

@@ -0,0 +1,77 @@
+import { Buff, Bytes }   from '@vbyte/buff'
+import { parse_tx_data } from './parse.js'
+
+import {
+  encode_tx_data,
+  encode_tx_inputs,
+  encode_tx_outputs,
+  encode_tx_vout,
+  encode_vin,
+  encode_vin_witness
+} from './encode.js'
+
+import type {
+  TxData,
+  TxInput,
+  TxOutput,
+  TxSize,
+  WitnessSize,
+} from '@/types/index.js'
+
+const WIT_FLAG_BYTES  = 2
+const WIT_LENGTH_BYTE = 1
+
+export function get_vsize (
+  bytes : Bytes
+) : number {
+  const weight = Buff.bytes(bytes).length
+  const remain = (weight % 4 > 0) ? 1 : 0
+  return Math.floor(weight / 4) + remain
+}
+
+export function get_txsize (
+  txdata : string | TxData
+) : TxSize {
+  const json   = parse_tx_data(txdata)
+  const base   = encode_tx_data(json, false).length
+  const size   = encode_tx_data(json, true).length
+  const weight = base * 3 + size
+  const remain = (weight % 4 > 0) ? 1 : 0
+  const vsize  = Math.floor(weight / 4) + remain
+  return { base, real: size, vsize, weight }
+}
+
+export function get_vin_size (vin : TxInput[]) : number {
+  const bytes = encode_tx_inputs(vin)
+  return bytes.length
+}
+
+export function get_vout_size (vout : TxOutput[]) : number {
+  const bytes = encode_tx_outputs(vout)
+  return bytes.length
+}
+
+export function get_segwit_size (txinputs : TxInput[]) : number {
+  const segwit_data = txinputs
+    .filter(e => e.witness.length > 0)
+    .map(e => e.witness)
+  return WIT_FLAG_BYTES + segwit_data
+    .reduce((acc, e) => acc + encode_vin_witness(e).length, 0)
+}
+
+export function get_txin_size (txinput : TxInput) : number {
+  const bytes = encode_vin(txinput)
+  return bytes.length
+}
+
+export function get_txout_size (txoutput : TxOutput) : number {
+  const bytes = encode_tx_vout(txoutput)
+  return bytes.length
+}
+
+export function get_witness_size (witness : Bytes[]) : WitnessSize {
+  const stack = witness.map(e => Buff.bytes(e))
+  const size  = stack.reduce((prev, next) => prev + next.length, 0)
+  const vsize = Math.ceil(WIT_LENGTH_BYTE + size / 4) 
+  return { size, vsize }
+}

package/src/lib/tx/validate.ts

@@ -0,0 +1,36 @@
+import * as Schema from '@/schema/index.js'
+
+import {
+  SpendInput,
+  TxData,
+  TxInput,
+  TxInputTemplate,
+  TxOutput,
+  TxTemplate,
+} from '@/types/index.js'
+
+export function assert_tx_template (txdata : unknown) : asserts txdata is TxTemplate {
+  Schema.tx.tx_template.parse(txdata)
+}
+
+export function assert_has_prevouts (vin : TxInput[]) : asserts vin is SpendInput[] {
+  if (vin.some(txin => txin.prevout === null)) {
+    throw new Error('transaction missing prevouts')
+  }
+}
+
+export function assert_tx_data (txdata : unknown) : asserts txdata is TxData {
+  Schema.tx.tx_data.parse(txdata)
+}
+
+export function assert_tx_input (tx_input : unknown) : asserts tx_input is TxInput {
+  Schema.tx.tx_input.parse(tx_input)
+}
+
+export function assert_tx_output (tx_output : unknown) : asserts tx_output is TxOutput {
+  Schema.tx.tx_output.parse(tx_output)
+}
+
+export function assert_vin_template (vin_template : unknown) : asserts vin_template is TxInputTemplate {
+  Schema.tx.vin_template.parse(vin_template)
+}

package/src/lib/tx/witness.ts

@@ -0,0 +1,122 @@
+import { Buff, Bytes }      from '@vbyte/buff'
+import { is_valid_script }  from '@/lib/script/decode.js'
+import { TAPLEAF_VERSIONS } from '@/const.js'
+
+import type {
+  WitnessInfo,
+  WitnessType
+} from '@/types/index.js'
+
+export function parse_witness_data (
+  witness : Bytes[]
+) : WitnessInfo {
+  // Parse the witness data.
+  const elems   = witness.map(e => Buff.bytes(e))
+  const annex   = parse_annex_data(elems)
+  if (annex !== null) elems.pop()
+  const cblock  = parse_cblock_data(elems)
+  if (cblock !== null) elems.pop()
+  const type    = parse_witness_type(elems, cblock)
+  const version = parse_witness_version(type)
+  const script  = parse_witness_script(elems, type)
+  if (script !== null) elems.pop()
+  const params  = elems.map(e => e.hex)
+  return { annex, cblock, params, script, type, version }
+}
+
+function parse_annex_data (
+  data : Uint8Array[]
+) : string | null {
+  // Get the last element of the array.
+  let elem = data.at(-1)
+  // Check if the element fits the annex format.
+  if (
+    data.length > 1            &&
+    elem instanceof Uint8Array &&
+    elem[0] === 0x50
+  ) {
+    // Return the element.
+    return new Buff(elem).hex
+  } else {
+    // Return null.
+    return null
+  }
+}
+
+function parse_cblock_data (
+  data : Uint8Array[]
+) : string | null {
+  let elem = data.at(-1)
+  if (
+    data.length > 1            &&
+    elem instanceof Uint8Array &&
+    elem.length > 32           &&
+    TAPLEAF_VERSIONS.includes(elem[0] & 0xfe)
+  ) {
+    // Return the element.
+    return new Buff(elem).hex
+  } else {
+    // Return null.
+    return null
+  }
+}
+
+function parse_witness_script (
+  elems : Uint8Array[],
+  type  : WitnessType
+) {
+  let script : Uint8Array | undefined
+  switch (type) {
+    case 'p2tr-ts':
+      script = elems.at(-1)
+    case 'p2w-sh':
+      script = elems.at(-1)
+  }
+  return (script !== undefined) ? new Buff(script).hex : null
+}
+
+function parse_witness_type (
+  elems  : Uint8Array[],
+  cblock : string | null
+) : WitnessType {
+  // Get the important elements of the witness.
+  let param_0 = elems.at(0),
+      param_1 = elems.at(1),
+      param_x = elems.at(-1)
+  // If the cblock is present and the last element exists:
+  if (cblock !== null && param_x !== undefined) {
+    return 'p2tr-ts'
+  // If the witness elements match the profile of a p2w-pkh:
+  } else if (
+    elems.length === 2    &&
+    param_0 !== undefined &&
+    param_1 !== undefined &&
+    param_0.length >=  64 &&
+    param_1.length === 33
+  ) {
+    return 'p2w-pkh'
+  // If the witness elements match the profile of a p2tr-pk:
+  } else if (
+    elems.length === 1    &&
+    param_0 !== undefined &&
+    param_0.length === 64
+  ) {
+    return 'p2tr-pk'
+  // If there is at least two witness elements:
+  } else if (
+    elems.length > 1      && 
+    param_x !== undefined &&
+    is_valid_script(param_x)
+  ) {
+    return 'p2w-sh'
+  // If the witness elements don't match any known profile:
+  } else {
+    return 'unknown'
+  }
+}
+
+function parse_witness_version (type : WitnessType) : number | null {
+  if (type.startsWith('p2tr')) return 1
+  if (type.startsWith('p2w'))  return 0
+  return null
+}

package/src/schema/index.ts

@@ -0,0 +1,2 @@
+export * as taproot from './taproot.js'
+export * as tx      from './tx.js'

package/src/schema/taproot.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod'
+
+import { byte32, uint } from '@vbyte/micro-lib/schema'
+
+export const taptree = z.union([ z.array(byte32), byte32 ])
+
+export const config = z.object({
+  pubkey  : byte32,
+  leaves  : taptree.array().optional(),
+  target  : byte32.optional(),
+  version : uint.optional(),
+})

package/src/schema/tx.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+
+import { big, hex, hex32, uint } from '@vbyte/micro-lib/schema'
+
+export const sats = big.max(2_100_000_000_000_000n)
+
+export const tx_output = z.object({
+  value     : sats,
+  script_pk : hex,
+})
+
+export const tx_input = z.object({
+  coinbase   : hex.nullable(),
+  txid       : hex32,
+  vout       : uint,
+  prevout    : tx_output.nullable(),
+  script_sig : hex.nullable(),
+  sequence   : uint,
+  witness    : z.array(hex)
+})
+
+export const tx_data = z.object({
+  version  : uint,
+  vin      : z.array(tx_input),
+  vout     : z.array(tx_output),
+  locktime : uint,
+})
+
+export const vin_template = tx_input.extend({
+  coinbase   : hex.nullable().optional(),
+  prevout    : tx_output.nullable().optional(),
+  script_sig : hex.nullable().optional(),
+  sequence   : uint.optional(),
+  witness    : z.array(hex).optional(),
+})
+
+export const tx_template = z.object({
+  version  : uint.optional(),
+  vin      : z.array(vin_template).default([]),
+  vout     : z.array(tx_output).default([]),
+  locktime : uint.optional(),
+})

package/src/types/address.ts

@@ -0,0 +1,39 @@
+export type AddressFormat = 'base58' | 'bech32'  | 'bech32m'
+export type AddressType   = 'p2pkh'  | 'p2sh'    | 'p2w-pkh' | 'p2w-sh' | 'p2tr'
+export type ChainNetwork  = 'main'   | 'testnet' | 'regtest'
+export type AddressData   = AddressContext & ScriptData
+
+export type AddressConfigEntry = [
+  prefix  : string,
+  type    : AddressType,
+  network : ChainNetwork,
+  size    : number,
+  format  : AddressFormat,
+  version : number
+]
+
+export interface DecodedAddress {
+  format   : AddressFormat
+  data     : Uint8Array
+  prefix?  : string
+  version? : number
+}
+
+export interface AddressConfig {
+  format  : AddressFormat
+  network : ChainNetwork
+  prefix  : string
+  size    : number
+  type    : AddressType
+  version : number
+}
+
+export interface AddressContext extends AddressConfig {
+  data : Uint8Array
+  hex  : string
+}
+
+export interface ScriptData {
+  script_asm : string[]
+  script_hex : string
+}

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from './address.js'
+export * from './meta.js'
+export * from './psbt.js'
+export * from './sighash.js'
+export * from './taproot.js'
+export * from './transaction.js'
+export * from './txdata.js'
+export * from './txmeta.js'
+export * from './witness.js'

package/src/types/meta.ts

@@ -0,0 +1,10 @@
+export interface InscriptionData {
+  content  ?: string
+  delegate ?: string
+  mimetype ?: string
+  opcode   ?: number
+  parent   ?: string
+  pointer  ?: number
+  ref      ?: string
+  rune     ?: string
+}

package/src/types/psbt.ts

@@ -0,0 +1,15 @@
+import type { Transaction } from '@scure/btc-signer'
+
+import type {
+  TransactionInput,
+  TransactionOutput
+} from '@scure/btc-signer/psbt'
+
+export type PSBTData   = Transaction
+export type PSBTInput  = TransactionInput
+export type PSBTOutput = TransactionOutput
+
+export interface PSBTPrevouts {
+  amounts : bigint[]
+  scripts : Uint8Array[]
+}

package/src/types/sighash.ts

@@ -0,0 +1,16 @@
+import { TxInput } from './txdata.js'
+
+export type SigHashType = 'segwit' | 'taproot'
+
+export interface SigHashOptions {
+  extension     ?: string      // Extend hash with additional commitment (for taproot).
+  extflag       ?: number      // Set the extention version flag (future use).
+  txindex       ?: number      // Index value of the input you wish to sign for.
+  key_version   ?: number      // Set the key version flag (future use).
+  pubkey        ?: string      // Verify using this pubkey instead of the tapkey.
+  script        ?: string      // Use this script for signing and validation.
+  separator_pos ?: number      // If using OP_CODESEPARATOR, specify the latest opcode position.
+  sigflag       ?: number      // Set the signature type flag.
+  throws        ?: boolean     // Should throw an exception on failure.
+  txinput       ?: TxInput     // Use this txinput for signing and validation.
+}

package/src/types/taproot.ts

@@ -0,0 +1,40 @@
+type Bytes = string | Uint8Array
+
+export type TapTree = Array<Bytes | Bytes[]>
+
+export type MerkleProof = [
+  root   : string,
+  target : string | undefined,
+  path   : string[]
+]
+
+export interface TaprootConfig {
+  pubkey   : Bytes
+  leaves  ?: TapTree
+  target  ?: Bytes
+  version ?: number
+}
+
+export interface TaprootContext {
+  cblock   : string
+  int_key  : string
+  parity   : number
+  taproot  : string | null
+  tapkey   : string
+  taptweak : string
+}
+
+export interface ControlBlock {
+  int_key  : string
+  parity   : number
+  path     : string[]
+  version  : number
+}
+
+export interface ProofData {
+  cblock : ControlBlock
+  params : string[]
+  script : string
+  tapkey : string
+  tweak  : string
+}

package/src/types/transaction.ts

@@ -0,0 +1,98 @@
+import { TxOutput } from './txdata.js'
+import { LocktimeInfo, SequenceInfo } from './txmeta.js'
+
+import type {
+  WitnessType,
+  WitnessVersion
+} from './witness.js'
+
+export type TxOutputType = WitnessType | 'p2pkh' | 'p2sh' | 'opreturn'
+
+export interface TxOutputInfo {
+  type    : TxOutputType
+  version : WitnessVersion
+}
+
+export interface TxInputInfo {
+  type    : WitnessType
+  version : WitnessVersion
+}
+
+export interface LocktimeField {
+  hex   : string
+  data  : LocktimeInfo | null
+  value : number
+}
+
+export interface SequenceField {
+  hex   : string
+  data  : SequenceInfo | null
+  value : number
+}
+
+export interface ScriptField {
+  asm : string[]
+  hex : string
+}
+
+export interface TxSize {
+  base   : number
+  real   : number
+  weight : number
+  vsize  : number
+}
+
+export interface TxValue {
+  fees : bigint
+  vin  : bigint
+  vout : bigint
+}
+
+export interface WitnessSize {
+  size  : number
+  vsize : number
+}
+
+export interface TransactionData {
+  hash     : string
+  locktime : LocktimeField
+  return   : TxOutput | null
+  size     : TxSize
+  spends   : TxOutputField[]
+  txid     : string
+  value    : TxValue
+  version  : number
+  vin      : TxInputField[]
+  vout     : TxOutputField[]
+}
+
+export interface WitnessField {
+  annex   : string | null
+  cblock  : string | null
+  params  : string[]
+  script  : ScriptField | null
+  size    : number
+  stack   : string[]
+  type    : WitnessType
+  version : WitnessVersion
+  vsize   : number
+}
+
+export interface TxInputField {
+  coinbase?   : string        | null
+  prevout?    : TxOutputField | null
+  script_sig? : ScriptField   | null
+  sequence    : SequenceField
+  size        : number
+  txid        : string
+  vout        : number
+  witness?    : WitnessField | null
+}
+
+export interface TxOutputField {
+  script_pk : ScriptField
+  size      : number
+  type      : TxOutputType
+  value     : bigint
+  version   : WitnessVersion | null
+}