@vbyte/btc-dev 1.1.8 → 2.0.0

package/src/lib/meta/scribe.ts

@@ -1,256 +0,0 @@
-import { Buff, Bytes, Stream } from '@vbyte/buff'
-import { Assert }              from '@vbyte/micro-lib'
-import { encode_script }       from '@/lib/script/encode.js'
-import { decode_script }       from '@/lib/script/decode.js'
-
-import type { InscriptionData } from '@/types/index.js'
-
-const _0n  = BigInt(0)
-const _1n  = BigInt(1)
-const _26n = BigInt(26)
-
-export namespace InscriptionUtil {
-  export type Type    = InscriptionData
-  export const encode = encode_inscription
-  export const decode = decode_inscription
-}
-
-export function decode_inscription (
-  script : Bytes
-) : InscriptionData[] {
-  const envelopes = parse_envelopes(script)
-  return envelopes.map(parse_record)
-}
-
-export function encode_inscription (data : InscriptionData[]) : Buff {
-  return Buff.join(data.map(create_envelope))
-}
-
-function create_envelope (data : InscriptionData) : Buff {
-  let asm : string[] = [ 'OP_0', 'OP_IF', '6f7264' ]
-
-  if (typeof data.delegate === 'string') {
-    const id = encode_id(data.delegate)
-    asm.push('OP_11', id)
-  }
-
-  if (typeof data.ref === 'string') {
-    asm.push('OP_WITHIN', data.ref)
-  }
-
-  if (typeof data.parent === 'string') {
-    const id = encode_id(data.parent)
-    asm.push('OP_3', id)
-  }
-
-  if (typeof data.opcode === 'number') {
-    const code = encode_pointer(data.opcode)
-    asm.push('OP_NOP', code)
-  }
-
-  if (typeof data.pointer === 'number') {
-    const ptr = encode_pointer(data.pointer)
-    asm.push('OP_2', ptr)
-  }
-
-  if (typeof data.rune === 'string') {
-    const label = encode_rune_label(data.rune)
-    asm.push('OP_13', label)
-  }
-
-  if (typeof data.mimetype === 'string') {
-    const label = encode_label(data.mimetype)
-    asm.push('OP_1', label)
-  }
-
-  if (typeof data.content === 'string') {
-    const chunks = encode_content(data.content)
-    asm.push('OP_0', ...chunks)
-  }
-
-  asm.push('OP_ENDIF')
-
-  return encode_script(asm)
-}
-
-function parse_envelopes (
-  script : Bytes
-) : string[][] {
-
-  const words     = decode_script(script)
-  const start_idx = words.findIndex(e => e === 'OP_0')
-
-  Assert.ok(start_idx !== -1, 'inscription envelope not found')
-
-  const envelopes = []
-
-  for (let idx = start_idx; idx < words.length; idx++) {
-    Assert.ok(words[idx + 1] === 'OP_IF',  'OP_IF missing from envelope')
-    Assert.ok(words[idx + 2] === '6f7264', 'magic bytes missing from envelope')
-
-    const stop_idx = words.findIndex(e => e === 'OP_ENDIF')
-    Assert.ok(stop_idx !== -1, 'inscription envelope missing END_IF statement')
-
-    const env = words.slice(idx + 3, stop_idx)
-    envelopes.push(env)
-    idx += stop_idx
-  }
-
-  return envelopes
-}
-
-function parse_record (envelope : Bytes[]) {
-  const record : InscriptionData = {}
-
-  for (let i = 0; i < envelope.length; i++) {
-    switch (envelope[i]) {
-      case 'OP_1':
-        record.mimetype = decode_label(envelope[i+1])
-        i += 1
-        break
-      case 'OP_2':
-        record.pointer = decode_pointer(envelope[i+1])
-        i += 1
-        break
-      case 'OP_3':
-        record.parent = decode_id(envelope[i+1])
-        i += 1
-        break
-      case 'OP_11':
-        record.delegate = decode_id(envelope[i+1])
-        i += 1
-        break
-      case 'OP_13':
-        record.rune = decode_rune_label(envelope[i+1])
-        i += 1
-        break
-      case 'OP_WITHIN':
-        record.ref = decode_bytes(envelope[i+1])
-        i += 1
-        break;
-      case 'OP_NOP':
-        record.opcode = decode_pointer(envelope[i+1])
-        i += 1
-        break;
-      case 'OP_0':
-        record.content = decode_content(envelope.slice(i+1))
-        return record
-    }
-  }
-  return record
-}
-
-function decode_bytes (bytes : Bytes) : string {
-  return Buff.bytes(bytes).hex
-}
-
-function encode_id (
-  identifier : string
-) : string {
-  Assert.ok(identifier.includes('i'), 'identifier must include an index')
-  const parts = identifier.split('i')
-  const bytes = Buff.hex(parts[0])
-  const idx   = Number(parts[1])
-  const txid  = bytes.reverse().hex
-  return (idx !== 0) ? txid + Buff.num(idx).hex : txid
-}
-
-function decode_id (
-  identifier : Bytes
-) : string {
-  const bytes = Buff.bytes(identifier)
-  const idx   = bytes.at(-1) ?? 0
-  const txid  = bytes.slice(0, -1).reverse().hex
-  return txid + 'i' + String(idx)
-}
-
-function encode_pointer (
-  pointer : number
-) : string {
-  return Buff.num(pointer).reverse().hex
-}
-
-function decode_pointer (
-  bytes : Bytes
-) : number {
-  return Buff.bytes(bytes).reverse().num
-}
-
-function encode_label (
-  label : string
-) : string {
-  return Buff.str(label).hex
-}
-
-function decode_label (
-  label : Bytes
-) : string {
-  return Buff.bytes(label).str
-}
-
-function encode_content (
-  content : string
-) : string[] {
-  const bytes = Buff.is_hex(content)
-    ? Buff.hex(content)
-    : Buff.str(content)
-  const stream = new Stream(bytes)
-  const chunks : string[]= []
-  while (stream.size > 0) {
-    if (stream.size > 520) {
-      const chunk = stream.read(520)
-      chunks.push(chunk.hex)
-    } else {
-      const chunk = stream.read(stream.size)
-      chunks.push(chunk.hex)
-    }
-  }
-  return chunks
-}
-
-function decode_content (
-  chunks : Bytes[],
-  format : 'hex' | 'utf8' = 'hex'
-) : string {
-  const data = Buff.join(chunks)
-  return (format === 'hex')
-    ? data.hex
-    : data.str
-}
-
-function encode_rune_label (label : string) : string {
-  const str = label.toUpperCase()
-  let big = _0n
-  for (const char of str) {
-    if (char >= 'A' && char <= 'Z') {
-        big = big * _26n + BigInt(char.charCodeAt(0) - ('A'.charCodeAt(0) - 1))
-    } else { continue }
-  }
-  big = big - _1n
-  return Buff.big(big).reverse().hex
-}
-
-function decode_rune_label (label: Bytes): string {
-  // Convert hex to BigInt, with byte order reversed
-  let big = Buff.bytes(label).reverse().big
-  // Add 1 as per the encoding algorithm
-  big = big + _1n
-  // Initialize result string
-  let result = ''
-  // Convert the BigInt back to a string of alphabet characters
-  while (big > _0n) {
-    // Get remainder after division by 26
-    const mod = big % _26n
-    // Convert remainder to character (0 maps to 'Z', 1 to 'A', 2 to 'B', etc.)
-    if (mod === _0n) {
-      result = 'Z' + result
-      big = big / _26n - _1n // Adjust for special case of 'Z'
-    } else {
-      // Map 1 to 'A', 2 to 'B', etc.
-      const charCode = Number(mod) + 'A'.charCodeAt(0) - 1
-      result = String.fromCharCode(charCode) + result
-      big = big / _26n
-    }
-  }
-  return result
-}

package/src/lib/meta/sequence.ts

@@ -1,146 +0,0 @@
-/**
- * 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, SequenceData } 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 SequenceField {
-  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) : SequenceData | 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/script/decode.ts

@@ -1,85 +0,0 @@
-import { Buff, Bytes, Stream } from '@vbyte/buff'
-
-import {
-  get_op_code,
-  get_op_type,
-  is_valid_op
-} from './words.js'
-
-import type { ScriptInfo } from '@/types/script.js'
-
-export function parse_script (script: Bytes): ScriptInfo {
-  const bytes = Buff.bytes(script)
-  return {
-    asm: decode_script(bytes),
-    hex: bytes.hex
-  }
-}
-
-/**
- * Decode a bitcoin script into asm instructions.
- */
-export function decode_script (
-  script : Bytes
-) : string[] {
-  const stream = new Stream(script)
-
-  const stack : string[] = []
-  const stack_size = stream.size
-
-  let word      : number
-  let word_type : string
-  let word_size : number
-
-  let count = 0
-
-  while (count < stack_size) {
-    word = stream.read(1).num
-    word_type = get_op_type(word)
-    count++
-    switch (word_type) {
-      case 'varint':
-        stack.push(stream.read(word).hex)
-        count += word
-        break
-      case 'pushdata1':
-        word_size = stream.read(1).reverse().num
-        stack.push(stream.read(word_size).hex)
-        count += word_size + 1
-        break
-      case 'pushdata2':
-        word_size = stream.read(2).reverse().num
-        stack.push(stream.read(word_size).hex)
-        count += word_size + 2
-        break
-      case 'pushdata4':
-        word_size = stream.read(4).reverse().num
-        stack.push(stream.read(word_size).hex)
-        count += word_size + 4
-        break
-      case 'opcode':
-        if (!is_valid_op(word)) {
-          throw new Error(`Invalid OPCODE: ${word}`)
-        }
-        stack.push(get_op_code(word))
-        break
-      default:
-        throw new Error(`Word type undefined: ${word}`)
-    }
-  }
-  return stack
-}
-
-/**
- * Check if a script is valid.
- */
-export function is_valid_script (
-  script : string | Uint8Array
-) : boolean {
-  try {
-    const stack = decode_script(script)
-    return stack.length > 0
-  } catch {
-    return false
-  }
-}

package/src/lib/script/encode.ts

@@ -1,129 +0,0 @@
-import { Buff, Stream }  from '@vbyte/buff'
-import { get_asm_code, } from './words.js'
-
-// The maximum size of a word in bytes.
-const MAX_WORD_SIZE = 520
-
-/**
- * Encode script asm instructions into a hex string.
- */
-export function encode_script (
-  words : (string | number | Uint8Array)[],
-  varint = false
-) : Buff {
-  if (words.length === 0) return Buff.num(0, 1)
-
-  const bytes = []
-
-  for (const word of words) {
-
-    bytes.push(encode_script_word(word))
-  }
-
-  const buffer = Buff.join(bytes)
-
-  return (varint)
-    ? buffer.prepend(Buff.varint(buffer.length, 'le'))
-    : buffer
-}
-
-/** Check if the word is a valid opcode,
- *  and return its integer value.
- */
-export function encode_script_word (word : string | number | Uint8Array) : Uint8Array {
-  let buff : Buff
-
-  // If word is a string:
-  if (typeof (word) === 'string') {
-    // If word is an opcode:
-    if (word.startsWith('OP_')) {
-      // Get the opcode number value.
-      const asm_code = get_asm_code(word)
-      // Return the opcode as a single byte.
-      return Buff.num(asm_code, 1)
-    // If word is valid hex:
-    } else if (Buff.is_hex(word)) {
-      // Encode as hex.
-      buff = Buff.hex(word)
-    } else {
-      // Encode as UTF8 string.
-      buff = Buff.str(word)
-    }
-  // If word is a number:
-  } else if (typeof (word) === 'number') {
-    // Encode the number value.
-    buff = Buff.num(word)
-  // If word is a Uint8Array:
-  } else if (word instanceof Uint8Array) {
-    // Encode as bytes.
-    buff = new Buff(word)
-  } else {
-    // If word is not a string, number, or Uint8Array, throw an error.
-    throw new Error('invalid word type:' + typeof (word))
-  }
-
-  // Format and return the word based on its size.
-  if (buff.length === 1 && buff[0] <= 16) {
-    // Number values 0-16 must be treated as opcodes.
-    if (buff[0] !== 0) buff[0] += 0x50
-  } else if (buff.length > MAX_WORD_SIZE) {
-    // Number values larger than max size must be split into chunks.
-    let words : Buff[]
-    // Split bytes into chunks, based on max word size.
-    words = split_script_word(buff)
-    // Prefix a varint length byte for each chunk.
-    words = words.map(e => prefix_word_size(e))
-    // Concatenate the chunks
-    buff = Buff.join(words)
-  } else {
-    // Else, return the word with a varint prefix.
-    buff = prefix_word_size(buff)
-  }
-  // Return the final result.
-  return buff
-}
-
-/**
- * Split a word into smaller chunks.
- */
-export function split_script_word (
-  word : Uint8Array
-) : Buff[] {
-  const words = []
-  const buff  = new Stream(word)
-  while (buff.size > MAX_WORD_SIZE) {
-    // Push a word chunk to the array.
-    words.push(buff.read(MAX_WORD_SIZE))
-  }
-  // Push the remainder to the array.
-  words.push(buff.read(buff.size))
-  return words
-}
-
-/**
- * Prefix a word with its size, encoded as a varint.
- */
-export function prefix_word_size (
-  word : Uint8Array
-) : Buff {
-  const varint = get_size_varint(word.length)
-  return Buff.join([ varint, word ])
-}
-
-/**
- * Return a varint that encodes a size value.
- */
-export function get_size_varint (size : number) : Buff {
-  const OP_PUSHDATA1 = Buff.num(0x4c, 1)
-  const OP_PUSHDATA2 = Buff.num(0x4d, 1)
-  switch (true) {
-    case (size <= 0x4b):
-      return Buff.num(size)
-    case (size > 0x4b && size < 0x100):
-      return Buff.join([ OP_PUSHDATA1, Buff.num(size, 1, 'le') ])
-    case (size >= 0x100 && size <= MAX_WORD_SIZE):
-      return Buff.join([ OP_PUSHDATA2, Buff.num(size, 2, 'le') ])
-    default:
-      throw new Error('Invalid word size:' + size.toString())
-  }
-}

package/src/lib/script/index.ts

@@ -1,20 +0,0 @@
-import { encode_script } from './encode.js'
-
-import {
-  decode_script,
-  is_valid_script,
-  parse_script
-} from './decode.js'
-
-export * from './decode.js'
-export * from './encode.js'
-export * from './lock.js'
-export * from './util.js'
-export * from './words.js'
-
-export namespace ScriptUtil {
-  export const parse    = parse_script
-  export const decode   = decode_script
-  export const encode   = encode_script
-  export const is_valid = is_valid_script
-}

package/src/lib/script/lock.ts

@@ -1,73 +0,0 @@
-import { Buff, Bytes }       from '@vbyte/buff'
-import { LOCK_SCRIPT_REGEX } from '@/const.js'
-
-import type {
-  LockScriptInfo,
-  LockScriptType,
-  WitnessVersion
-} from '@/types/index.js'
-
-export function is_return_script (script : Bytes) : boolean {
-  const bytes = Buff.bytes(script)
-  return bytes.at(0) === 0x6a
-}
-
-export function get_lock_script_info (script : Bytes) : LockScriptInfo {
-  return {
-    type    : get_lock_script_type(script),
-    version : get_lock_script_version(script)
-  }
-}
-
-export function get_lock_script_type (script : Bytes) : LockScriptType | null {
-  // Get the hex string of the script.
-  const hex = Buff.bytes(script).hex
-  // Iterate over the lock script regexes.
-  for (const [ type, regex ] of Object.entries(LOCK_SCRIPT_REGEX)) {
-    // If the script matches the regex, return the type.
-    if (regex.test(hex)) return type as LockScriptType
-  }
-  // If the script does not match any regex, return null.
-  return null
-}
-
-export function get_lock_script_version (script : Bytes) : WitnessVersion | null {
-  // Get the version of the script.
-  const version = Buff.bytes(script)
-  // Return the version of the script.
-  switch (version.at(0)) {
-    case 0x00 : return 0
-    case 0x51 : return 1
-    default   : return null
-  }
-}
-
-export function is_p2pkh_script (script : Bytes) : boolean {
-  const hex = Buff.bytes(script).hex
-  return LOCK_SCRIPT_REGEX['p2pkh'].test(hex)
-}
-
-export function is_p2sh_script (script : Bytes) : boolean {
-  const hex = Buff.bytes(script).hex
-  return LOCK_SCRIPT_REGEX['p2sh'].test(hex)
-}
-
-export function is_p2wpkh_script (script : Bytes) : boolean {
-  const hex = Buff.bytes(script).hex
-  return LOCK_SCRIPT_REGEX['p2wpkh'].test(hex)
-}
-
-export function is_p2wsh_script (script : Bytes) : boolean {
-  const hex = Buff.bytes(script).hex
-  return LOCK_SCRIPT_REGEX['p2wsh'].test(hex)
-}
-
-export function is_p2tr_script (script : Bytes) : boolean {
-  const hex = Buff.bytes(script).hex
-  return LOCK_SCRIPT_REGEX['p2tr'].test(hex)
-}
-
-export function is_opreturn_script (script : Bytes) : boolean {
-  const hex = Buff.bytes(script).hex
-  return LOCK_SCRIPT_REGEX['opreturn'].test(hex)
-}