@vbyte/btc-dev 1.0.0

package/src/lib/address/p2wpkh.ts

@@ -0,0 +1,67 @@
+import { Buff }           from '@vbyte/buff'
+import { Assert }         from '@vbyte/micro-lib'
+import { hash160 }        from '@vbyte/micro-lib/hash'
+import { encode_address } from './encode.js'
+
+import {
+  get_address_config,
+  parse_address
+} from './util.js'
+
+import type {
+  AddressData,
+  ChainNetwork
+} from '@/types/index.js'
+
+const ADDR_TYPE = 'p2w-pkh'
+
+export namespace P2WPKH {
+  export const create = create_p2wpkh_address
+  export const encode = encode_p2wpkh_address
+  export const decode = decode_p2wpkh_address
+}
+
+function create_p2wpkh_address (
+  pubkey  : string | Uint8Array,
+  network : ChainNetwork = 'main',
+) : string {
+  // Convert the public key into bytes.
+  const bytes = Buff.bytes(pubkey)
+  // Assert the payload size is correct.
+  Assert.size(bytes, 33, `invalid payload size: ${bytes.length} !== 33` )
+  // Convert the bytes into a hash.
+  const hash = hash160(bytes)
+  // Encode the address.
+  return encode_p2wpkh_address(hash, network)
+}
+
+function encode_p2wpkh_address (
+  pk_hash : string | Uint8Array,
+  network : ChainNetwork = 'main',
+) : string {
+  // Convert the public key hash into bytes.
+  const bytes  = Buff.bytes(pk_hash)
+  // Get the address configuration.
+  const config = get_address_config(network, ADDR_TYPE)
+  // Assert the configuration exists.
+  Assert.exists(config, `unrecognized address config: ${ADDR_TYPE} on ${network}` )
+  // Assert the payload size is correct.
+  Assert.size(bytes, config.size, `invalid payload size: ${bytes.length} !== ${config.size}` )
+  // Encode the address.
+  return encode_address({
+    data   : bytes,
+    format : 'bech32',
+    prefix : config.prefix
+  })
+}
+
+function decode_p2wpkh_address (
+  address : string
+) : AddressData {
+  // Parse the address.
+  const parsed = parse_address(address)
+  // Assert the address type is correct.
+  Assert.ok(parsed.type === 'p2w-pkh', `address type mismatch: ${parsed.type} !== ${ADDR_TYPE}`)
+  // Return the parsed address.
+  return parsed
+}

package/src/lib/address/p2wsh.ts

@@ -0,0 +1,65 @@
+import { Buff }           from '@vbyte/buff'
+import { Assert }         from '@vbyte/micro-lib'
+import { sha256 }         from '@vbyte/micro-lib/hash'
+import { encode_address } from './encode.js'
+
+import {
+  get_address_config,
+  parse_address
+} from './util.js'
+
+import type {
+  ChainNetwork,
+  AddressData
+} from '@/types/index.js'
+
+const ADDR_TYPE = 'p2w-sh'
+
+export namespace P2WSH {
+  export const create = create_p2wsh_address
+  export const encode = encode_p2wsh_address
+  export const decode = decode_p2wsh_address
+}
+
+function create_p2wsh_address (
+  script  : string | Uint8Array,
+  network : ChainNetwork = 'main',
+) : string {
+  // Convert the script into bytes.
+  const bytes = Buff.bytes(script)
+  // Convert the bytes into a hash.
+  const hash  = sha256(bytes)
+  // Encode the address.
+  return encode_p2wsh_address(hash, network)
+}
+
+function encode_p2wsh_address (
+  script_hash : string | Uint8Array,
+  network     : ChainNetwork = 'main',
+) : string {
+  // Convert the script hash into bytes.
+  const bytes  = Buff.bytes(script_hash)
+  // Get the address configuration.
+  const config = get_address_config(network, ADDR_TYPE)
+  // Assert the configuration exists.
+  Assert.exists(config, `unrecognized address config: ${ADDR_TYPE} on ${network}` )
+  // Assert the payload size is correct.
+  Assert.size(bytes, config.size, `invalid payload size: ${bytes.length} !== ${config.size}` )
+  // Encode the address.
+  return encode_address({
+    data   : bytes,
+    format : 'bech32',
+    prefix : config.prefix
+  })
+}
+
+function decode_p2wsh_address (
+  address : string
+) : AddressData {
+  // Parse the address.
+  const parsed = parse_address(address)
+  // Assert the address type is correct.
+  Assert.ok(parsed.type === 'p2w-sh', `address type mismatch: ${parsed.type} !== ${ADDR_TYPE}`)
+  // Return the parsed address.
+  return parsed
+}

package/src/lib/address/script.ts

@@ -0,0 +1,63 @@
+import type { AddressType } from '@/types/index.js'
+
+/**
+ * Get the address script.
+ * 
+ * @param script_key  - The script key.
+ * @param script_type - The script type.
+ * @returns The address script.
+ */
+export function get_address_script (
+  script_key  : string,
+  script_type : AddressType
+) {
+  switch (script_type) {
+    case 'p2pkh':
+      return get_p2pkh_script(script_key)
+    case 'p2sh':
+      return get_p2sh_script(script_key)
+    case 'p2w-pkh':
+      return get_p2w_pkh_script(script_key)
+    case 'p2w-sh':
+      return get_p2w_sh_script(script_key)
+    case 'p2tr':
+      return get_p2tr_script(script_key)
+    default:
+      throw new Error('unrecognized script type: ' + script_type)
+  }
+}
+
+function get_p2pkh_script (script_key : string) {
+  return {
+    script_hex : '76a914' + script_key + '88ac',
+    script_asm : [ 'OP_DUP', 'OP_HASH160', script_key, 'OP_EQUALVERIFY', 'OP_CHECKSIG' ]
+  }
+}
+
+function get_p2sh_script (script_key : string) {
+  return {
+    script_hex : 'a914' + script_key + '87',
+    script_asm : [ 'OP_HASH160', script_key, 'OP_EQUAL' ]
+  }
+}
+
+function get_p2w_pkh_script (script_key : string) {
+  return {
+    script_hex : '0014' + script_key,
+    script_asm : [ 'OP_0', script_key ]
+  }
+}
+
+function get_p2w_sh_script (script_key : string) {
+  return {
+    script_hex : '0020' + script_key,
+    script_asm : [ 'OP_0', script_key ]
+  }
+}
+
+function get_p2tr_script (script_key : string) {
+  return {
+    script_hex : '5120' + script_key,
+    script_asm : [ 'OP_1', script_key ]
+  }
+}

package/src/lib/address/util.ts

@@ -0,0 +1,102 @@
+import { Buff }               from '@vbyte/buff'
+import { decode_address }     from './encode.js'
+import { get_address_script } from './script.js'
+
+import type {
+  AddressConfig,
+  AddressConfigEntry,
+  AddressType,
+  ChainNetwork,
+  AddressContext,
+  AddressData
+} from '@/types/index.js'
+
+const CONFIG_TABLE : AddressConfigEntry[] = [
+  [ '1',      'p2pkh',   'main',    20, 'base58',  0x00 ],
+  [ '3',      'p2sh',    'main',    20, 'base58',  0x05 ],
+  [ 'm',      'p2pkh',   'testnet', 20, 'base58',  0x6F ],
+  [ 'n',      'p2pkh',   'testnet', 20, 'base58',  0x6F ],
+  [ '2',      'p2sh',    'testnet', 20, 'base58',  0xC4 ],
+  [ 'm',      'p2pkh',   'regtest', 20, 'base58',  0x6F ],
+  [ 'n',      'p2pkh',   'regtest', 20, 'base58',  0x6F ],
+  [ '2',      'p2sh',    'regtest', 20, 'base58',  0xC4 ],
+  [ 'bc',     'p2w-pkh', 'main',    20, 'bech32',  0    ],
+  [ 'tb',     'p2w-pkh', 'testnet', 20, 'bech32',  0    ],
+  [ 'bcrt',   'p2w-pkh', 'regtest', 20, 'bech32',  0    ],
+  [ 'bc',     'p2w-sh',  'main',    32, 'bech32',  0    ],
+  [ 'tb',     'p2w-sh',  'testnet', 32, 'bech32',  0    ],
+  [ 'bcrt',   'p2w-sh',  'regtest', 32, 'bech32',  0    ],
+  [ 'bc',     'p2tr',    'main',    32, 'bech32m', 1    ],
+  [ 'tb',     'p2tr',    'testnet', 32, 'bech32m', 1    ],
+  [ 'bcrt',   'p2tr',    'regtest', 32, 'bech32m', 1    ]
+]
+
+/**
+ * Lookup an address configuration by its type and network.
+ * 
+ * @param address_network - The network of the address.
+ * @param address_type    - The type of the address.
+ * @returns The address information, or null if the address is not recognized.
+ */
+export function get_address_config (
+  address_network : ChainNetwork,
+  address_type    : AddressType
+) : AddressConfig | null {
+  // For each configuration in the table,
+  for (const [ prefix, type, network, size, format, version ] of CONFIG_TABLE) {
+    // Check if the address matches the configuration
+    if (type === address_type && network === address_network) {
+      // Return the address configuration.
+      return { type, prefix, network, size, format, version }
+    }
+  }
+  // If no configuration matches the address, return null.
+  return null
+}
+
+/**
+ * Get the address context.
+ * 
+ * @param address - The address to get the context for.
+ * @returns The address context.
+ */
+export function get_address_ctx (address : string) : AddressContext {
+  // Decode the address.
+  const dec = decode_address(address)
+  // For each configuration in the table,
+  for (const [ prefix, type, network, size, format, version ] of CONFIG_TABLE) {
+
+    // Check if the address matches the configuration
+    if (format  !== dec.format)      continue
+    if (size    !== dec.data.length) continue
+    if (version !== dec.version)     continue
+
+    if (dec.prefix) {
+      if (prefix !== dec.prefix) continue
+    } else {
+      if (!address.startsWith(prefix)) continue
+    }
+
+    // Convert the decoded data into a hex string.
+    const hex = Buff.uint(dec.data).hex
+    // Return the address configuration and data.
+    return { data: dec.data, hex, type, prefix, network, size, format, version }
+  }
+  // Otherwise, throw an error
+  throw new Error('address configuration is invalid')
+}
+
+/**
+ * Parse an address into its data and script.
+ * 
+ * @param address - The address to parse.
+ * @returns The address data and script.
+ */
+export function parse_address (address : string) : AddressData {
+  // Get the address context.
+  const ctx    = get_address_ctx(address)
+  // Get the address script.
+  const script = get_address_script(ctx.hex, ctx.type)
+  // Return the address data.
+  return { ...ctx, ...script }
+}

package/src/lib/meta/index.ts

@@ -0,0 +1,2 @@
+export * from './pointer.js'
+export * from './scribe.js'

package/src/lib/meta/pointer.ts

@@ -0,0 +1,107 @@
+export namespace TxPointer {
+  export const outpoint = {
+    encode : encode_outpoint,
+    decode : decode_outpoint,
+    verify : verify_outpoint, 
+    assert : assert_outpoint,
+  }
+  export const record_id = {
+    encode : encode_inscription_id,
+    decode : decode_inscription_id,
+    verify : verify_inscription_id,
+    assert : assert_inscription_id,
+  }
+  export const rune_id = {
+    encode : encode_rune_id,
+    decode : decode_rune_id,
+    verify : verify_rune_id,
+    assert : assert_rune_id,
+  }
+}
+
+function encode_inscription_id (
+  txid  : string,
+  order : number = 0
+) : string {
+  return `${txid}i${order}`
+}
+
+function decode_inscription_id (
+  inscription_id : string
+) : { txid : string, order : number } {
+  assert_inscription_id(inscription_id)
+  const [ txid, order ] = inscription_id.split('i')
+  return { txid, order : parseInt(order) }
+}
+
+function verify_inscription_id (
+  inscription_id : string
+) : boolean {
+  return inscription_id.match(/^[a-f0-9]{64}i\d+$/) !== null
+}
+
+function assert_inscription_id (
+  inscription_id : string
+) : void {
+  if (!verify_inscription_id(inscription_id)) {
+    throw new Error(`invalid inscription id: ${inscription_id}`)
+  }
+}
+
+function encode_rune_id (
+  block_height : number,
+  block_index  : number
+) : string {
+  return `${block_height}:${block_index}`
+}
+
+function decode_rune_id (
+  rune_id : string
+) : { block_height : number, block_index : number } {
+  assert_rune_id(rune_id)
+  const [ block_height, block_index ] = rune_id.split(':')
+  return { block_height : parseInt(block_height), block_index : parseInt(block_index) }
+}
+
+function verify_rune_id (
+  rune_id : string
+) : boolean {
+  return rune_id.match(/^\d+:\d+$/) !== null
+}
+
+function assert_rune_id (
+  rune_id : string
+) : void {
+  if (!verify_rune_id(rune_id)) {
+    throw new Error(`invalid rune id: ${rune_id}`)
+  }
+}
+
+function encode_outpoint (
+  txid  : string,
+  vout  : number
+) : string {
+  return `${txid}:${vout}`
+}
+
+function decode_outpoint (
+  outpoint : string
+) : { txid : string, vout : number } {
+  assert_outpoint(outpoint)
+  const [ txid, vout ] = outpoint.split(':')
+  return { txid, vout : parseInt(vout) }
+}
+
+function verify_outpoint (
+  outpoint : string
+) : boolean {
+  return outpoint.match(/^[a-f0-9]{64}:[0-9]+$/) !== null
+}
+
+function assert_outpoint (
+  outpoint : string
+) : void {
+  if (!verify_outpoint(outpoint)) {
+    throw new Error(`invalid outpoint: ${outpoint}`)
+  }
+}

package/src/lib/meta/scribe.ts

@@ -0,0 +1,251 @@
+import { Buff, 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 Inscription {
+  export const encode = encode_inscription
+  export const decode = decode_inscription
+}
+
+export function decode_inscription (
+  script : string
+) : InscriptionData[] {
+  const envelopes = parse_envelopes(script)
+  return envelopes.map(parse_record)
+}
+
+export function encode_inscription (data : InscriptionData[]) : string {
+  return data.map(create_envelope).join('')
+}
+
+function create_envelope (data : InscriptionData) : string {
+  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 : string
+) : 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 : string[]) {
+  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 = 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 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 (
+  hexstr : string
+) : string {
+  const bytes = Buff.hex(hexstr)
+  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 (
+  hexstr : string
+) : number {
+  return Buff.hex(hexstr).reverse().num
+}
+
+function encode_label (
+  label : string
+) : string {
+  return Buff.str(label).hex
+}
+
+function decode_label (
+  hexstr : string
+) : string {
+  return Buff.hex(hexstr).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 (
+  hexstrs : string[],
+  type    : 'hex' | 'utf8' = 'hex'
+) : string {
+  const data = Buff.join(hexstrs)
+  return (type === '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 (hex: string): string {
+  // Convert hex to BigInt, with byte order reversed
+  let big = Buff.hex(hex).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/psbt/encoder.ts

@@ -0,0 +1,24 @@
+import { Base64 }      from '@vbyte/micro-lib'
+import { Transaction } from '@scure/btc-signer'
+
+import type { PSBTData } from '@/types/index.js'
+
+export function decode_psbt (b64str : string) : Transaction {
+  const psbt = Base64.decode(b64str)
+  return Transaction.fromPSBT(psbt, { allowUnknownOutputs: true })
+}
+
+export function encode_psbt (psbt : PSBTData) : string {
+  const psbt_bytes = psbt.toPSBT(0)
+  return Base64.encode(psbt_bytes)
+}
+
+export function parse_psbt (psbt : string | PSBTData) : Transaction {
+  if (psbt instanceof Transaction) {
+    return psbt
+  } else if (typeof psbt === 'string') {
+    return decode_psbt(psbt)
+  } else {
+    throw new Error('invalid psbt input: ' + psbt)
+  }
+}

package/src/lib/psbt/index.ts

@@ -0,0 +1,4 @@
+export * from './encoder.js'
+export * from './meta.js'
+export * from './util.js'
+export * from './validate.js'

package/src/lib/psbt/meta.ts

@@ -0,0 +1,15 @@
+import { parse_psbt }             from './encoder.js'
+import { finalize_legacy_inputs } from './util.js'
+
+import { PSBTData } from '@/types/index.js'
+
+export function get_vsize (psbt : string | PSBTData) : number {
+  const pdata = parse_psbt(psbt)
+  return pdata.vsize
+}
+
+export function get_txhex (psbt : PSBTData) : string {
+  let pdata = parse_psbt(psbt)
+      pdata = finalize_legacy_inputs(pdata)
+  return pdata.hex
+}