bolt12-utils 0.1.0

package/src/tlv.ts

@@ -0,0 +1,75 @@
+/**
+ * TLV (Type-Length-Value) stream parsing for BOLT12.
+ *
+ * A TLV stream is a sequence of records, each consisting of:
+ *   - type: BigSize
+ *   - length: BigSize
+ *   - value: `length` bytes
+ *
+ * Records MUST appear in strictly ascending type order.
+ */
+
+import { readBigSize, writeBigSize } from './bigsize.js';
+
+export interface TlvRecord {
+  type: bigint;
+  length: bigint;
+  value: Uint8Array;
+}
+
+/**
+ * Parse a TLV stream from raw bytes.
+ * Returns an array of TLV records.
+ * Throws if types are not in ascending order.
+ */
+export function parseTlvStream(data: Uint8Array): TlvRecord[] {
+  const records: TlvRecord[] = [];
+  let offset = 0;
+  let lastType = -1n;
+
+  while (offset < data.length) {
+    // Read type
+    const typeResult = readBigSize(data, offset);
+    offset += typeResult.bytesRead;
+    const tlvType = typeResult.value;
+
+    // Check ascending order
+    if (tlvType <= lastType) {
+      throw new Error('TLV fields not in ascending order');
+    }
+    lastType = tlvType;
+
+    // Read length
+    if (offset >= data.length) {
+      throw new Error('Truncated TLV: missing length');
+    }
+    const lengthResult = readBigSize(data, offset);
+    offset += lengthResult.bytesRead;
+    const tlvLength = lengthResult.value;
+
+    // Read value
+    const len = Number(tlvLength);
+    if (offset + len > data.length) {
+      throw new Error('Truncated TLV: value extends beyond data');
+    }
+    const value = data.slice(offset, offset + len);
+    offset += len;
+
+    records.push({ type: tlvType, length: tlvLength, value });
+  }
+
+  return records;
+}
+
+/**
+ * Serialize a TLV record to bytes (type + length + value).
+ */
+export function serializeTlvRecord(record: TlvRecord): Uint8Array {
+  const typeBytes = writeBigSize(record.type);
+  const lengthBytes = writeBigSize(record.length);
+  const result = new Uint8Array(typeBytes.length + lengthBytes.length + record.value.length);
+  result.set(typeBytes, 0);
+  result.set(lengthBytes, typeBytes.length);
+  result.set(record.value, typeBytes.length + lengthBytes.length);
+  return result;
+}

package/src/utils.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared utility functions for BOLT12 modules.
+ */
+
+/** Read a truncated big-endian unsigned integer from bytes. Empty = 0. */
+export function readTruncatedUint(data: Uint8Array): bigint {
+  if (data.length === 0) {
+    return 0n;
+  }
+  let val = 0n;
+  for (let i = 0; i < data.length; i++) {
+    val = (val << 8n) | BigInt(data[i]);
+  }
+  return val;
+}
+
+/** Convert bytes to lowercase hex string. */
+export function toHex(buf: Uint8Array): string {
+  let hex = '';
+  for (let i = 0; i < buf.length; i++) {
+    hex += buf[i].toString(16).padStart(2, '0');
+  }
+  return hex;
+}
+
+/** Check if a TLV type is a signature element (240-1000 inclusive). */
+export function isSignatureType(type: bigint): boolean {
+  return type >= 240n && type <= 1000n;
+}
+
+/** Compare two byte arrays lexicographically. */
+export function compareBytes(a: Uint8Array, b: Uint8Array): number {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    if (a[i] < b[i]) {
+      return -1;
+    }
+    if (a[i] > b[i]) {
+      return 1;
+    }
+  }
+  if (a.length < b.length) {
+    return -1;
+  }
+  if (a.length > b.length) {
+    return 1;
+  }
+  return 0;
+}