@bcts/uniform-resources 1.0.0-alpha.10

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@bcts/uniform-resources",
+  "version": "1.0.0-alpha.10",
+  "type": "module",
+  "description": "Blockchain Commons Uniform Resources (UR) for TypeScript",
+  "license": "BSD-2-Clause-Patent",
+  "author": "Leonardo Custodio <leonardo@custodio.me>",
+  "homepage": "https://bcts.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leonardocustodio/bcts",
+    "directory": "packages/uniform-resources"
+  },
+  "bugs": {
+    "url": "https://github.com/leonardocustodio/bcts/issues"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "browser": "dist/index.iife.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs": "typedoc"
+  },
+  "keywords": [
+    "uniform-resources",
+    "ur",
+    "blockchain-commons",
+    "cbor",
+    "dcbor",
+    "encoding",
+    "deterministic"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@bcts/dcbor": "^1.0.0-alpha.10"
+  },
+  "devDependencies": {
+    "@bcts/eslint": "^0.1.0",
+    "@bcts/tsconfig": "^0.1.0",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.3",
+    "@types/pako": "^2.0.4",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "ts-node": "^10.9.2",
+    "tsdown": "^0.18.3",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

package/src/error.ts

@@ -0,0 +1,88 @@
+/**
+ * Error type for UR encoding/decoding operations.
+ */
+export class URError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "URError";
+  }
+}
+
+/**
+ * Error type for invalid UR schemes.
+ */
+export class InvalidSchemeError extends URError {
+  constructor() {
+    super("Invalid UR scheme");
+    this.name = "InvalidSchemeError";
+  }
+}
+
+/**
+ * Error type for unspecified UR types.
+ */
+export class TypeUnspecifiedError extends URError {
+  constructor() {
+    super("No UR type specified");
+    this.name = "TypeUnspecifiedError";
+  }
+}
+
+/**
+ * Error type for invalid UR types.
+ */
+export class InvalidTypeError extends URError {
+  constructor() {
+    super("Invalid UR type");
+    this.name = "InvalidTypeError";
+  }
+}
+
+/**
+ * Error type for non-single-part URs.
+ */
+export class NotSinglePartError extends URError {
+  constructor() {
+    super("UR is not a single-part");
+    this.name = "NotSinglePartError";
+  }
+}
+
+/**
+ * Error type for unexpected UR types.
+ */
+export class UnexpectedTypeError extends URError {
+  constructor(expected: string, found: string) {
+    super(`Expected UR type ${expected}, but found ${found}`);
+    this.name = "UnexpectedTypeError";
+  }
+}
+
+/**
+ * Error type for Bytewords encoding/decoding errors.
+ */
+export class BytewordsError extends URError {
+  constructor(message: string) {
+    super(`Bytewords error: ${message}`);
+    this.name = "BytewordsError";
+  }
+}
+
+/**
+ * Error type for CBOR encoding/decoding errors.
+ */
+export class CBORError extends URError {
+  constructor(message: string) {
+    super(`CBOR error: ${message}`);
+    this.name = "CBORError";
+  }
+}
+
+export type Result<T> = T | Error;
+
+/**
+ * Helper function to check if a result is an error.
+ */
+export function isError(result: unknown): result is Error {
+  return result instanceof Error;
+}

package/src/fountain.ts

@@ -0,0 +1,397 @@
+/**
+ * Fountain code implementation for multipart URs.
+ *
+ * This implements a hybrid fixed-rate and rateless fountain code system
+ * as specified in BCR-2020-005 and BCR-2024-001.
+ *
+ * Key concepts:
+ * - Parts 1-seqLen are "pure" fragments (fixed-rate)
+ * - Parts > seqLen are "mixed" fragments using XOR (rateless)
+ * - Xoshiro256** PRNG ensures encoder/decoder agree on mixing
+ */
+
+import { Xoshiro256, createSeed } from "./xoshiro.js";
+import { crc32 } from "./utils.js";
+
+/**
+ * Represents a fountain code part with metadata.
+ */
+export interface FountainPart {
+  /** Sequence number (1-based) */
+  seqNum: number;
+  /** Total number of pure fragments */
+  seqLen: number;
+  /** Length of original message */
+  messageLen: number;
+  /** CRC32 checksum of original message */
+  checksum: number;
+  /** Fragment data */
+  data: Uint8Array;
+}
+
+/**
+ * Splits data into fragments of the specified size.
+ */
+export function splitMessage(message: Uint8Array, fragmentLen: number): Uint8Array[] {
+  const fragments: Uint8Array[] = [];
+  const fragmentCount = Math.ceil(message.length / fragmentLen);
+
+  for (let i = 0; i < fragmentCount; i++) {
+    const start = i * fragmentLen;
+    const end = Math.min(start + fragmentLen, message.length);
+    const fragment = new Uint8Array(fragmentLen);
+
+    // Copy data and pad with zeros if needed
+    const sourceSlice = message.slice(start, end);
+    fragment.set(sourceSlice);
+
+    fragments.push(fragment);
+  }
+
+  return fragments;
+}
+
+/**
+ * XOR two Uint8Arrays together.
+ */
+export function xorBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const len = Math.max(a.length, b.length);
+  const result = new Uint8Array(len);
+
+  for (let i = 0; i < len; i++) {
+    result[i] = (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+
+  return result;
+}
+
+/**
+ * Chooses which fragments to mix for a given sequence number.
+ *
+ * This uses a seeded Xoshiro256** PRNG to deterministically select fragments,
+ * ensuring encoder and decoder agree without explicit coordination.
+ *
+ * @param seqNum - The sequence number (1-based)
+ * @param seqLen - Total number of pure fragments
+ * @param checksum - CRC32 checksum of the message
+ * @returns Array of fragment indices (0-based)
+ */
+export function chooseFragments(seqNum: number, seqLen: number, checksum: number): number[] {
+  // Pure parts (seqNum <= seqLen) contain exactly one fragment
+  if (seqNum <= seqLen) {
+    return [seqNum - 1];
+  }
+
+  // Mixed parts use PRNG to select fragments
+  const seed = createSeed(checksum, seqNum);
+  const rng = new Xoshiro256(seed);
+
+  // Choose degree (number of fragments to mix)
+  // Uses a simplified soliton distribution
+  const degree = chooseDegree(rng, seqLen);
+
+  // Choose which fragments to include
+  const indices = new Set<number>();
+  while (indices.size < degree) {
+    const index = rng.nextInt(0, seqLen);
+    indices.add(index);
+  }
+
+  return Array.from(indices).sort((a, b) => a - b);
+}
+
+/**
+ * Chooses the degree (number of fragments to mix) using a simplified
+ * robust soliton distribution.
+ *
+ * This ensures good coverage of fragments for efficient decoding.
+ */
+function chooseDegree(rng: Xoshiro256, seqLen: number): number {
+  // Use a simplified distribution that tends toward lower degrees
+  // but can occasionally include more fragments
+  const r = rng.nextDouble();
+
+  // Probability distribution favoring lower degrees
+  // Based on robust soliton distribution
+  if (r < 0.5) {
+    return 1;
+  } else if (r < 0.75) {
+    return 2;
+  } else if (r < 0.9) {
+    return Math.min(3, seqLen);
+  } else {
+    // Higher degrees are less common but help with convergence
+    return Math.min(rng.nextInt(4, seqLen + 1), seqLen);
+  }
+}
+
+/**
+ * Mixes the selected fragments using XOR.
+ */
+export function mixFragments(fragments: Uint8Array[], indices: number[]): Uint8Array {
+  if (indices.length === 0) {
+    throw new Error("No fragments to mix");
+  }
+
+  let result: Uint8Array = new Uint8Array(fragments[0].length);
+
+  for (const index of indices) {
+    const fragment = fragments[index];
+    if (fragment === undefined) {
+      throw new Error(`Fragment at index ${index} not found`);
+    }
+    result = xorBytes(result, fragment);
+  }
+
+  return result;
+}
+
+/**
+ * Fountain encoder for creating multipart URs.
+ */
+export class FountainEncoder {
+  private readonly fragments: Uint8Array[];
+  private readonly messageLen: number;
+  private readonly checksum: number;
+  private seqNum = 0;
+
+  /**
+   * Creates a fountain encoder for the given message.
+   *
+   * @param message - The message to encode
+   * @param maxFragmentLen - Maximum length of each fragment
+   */
+  constructor(message: Uint8Array, maxFragmentLen: number) {
+    if (maxFragmentLen < 1) {
+      throw new Error("Fragment length must be at least 1");
+    }
+
+    this.messageLen = message.length;
+    this.checksum = crc32(message);
+    this.fragments = splitMessage(message, maxFragmentLen);
+  }
+
+  /**
+   * Returns the number of pure fragments.
+   */
+  get seqLen(): number {
+    return this.fragments.length;
+  }
+
+  /**
+   * Returns whether the message fits in a single part.
+   */
+  isSinglePart(): boolean {
+    return this.fragments.length === 1;
+  }
+
+  /**
+   * Returns whether all pure parts have been emitted.
+   */
+  isComplete(): boolean {
+    return this.seqNum >= this.seqLen;
+  }
+
+  /**
+   * Generates the next fountain part.
+   */
+  nextPart(): FountainPart {
+    this.seqNum++;
+
+    const indices = chooseFragments(this.seqNum, this.seqLen, this.checksum);
+    const data = mixFragments(this.fragments, indices);
+
+    return {
+      seqNum: this.seqNum,
+      seqLen: this.seqLen,
+      messageLen: this.messageLen,
+      checksum: this.checksum,
+      data,
+    };
+  }
+
+  /**
+   * Returns the current sequence number.
+   */
+  currentSeqNum(): number {
+    return this.seqNum;
+  }
+
+  /**
+   * Resets the encoder to start from the beginning.
+   */
+  reset(): void {
+    this.seqNum = 0;
+  }
+}
+
+/**
+ * Fountain decoder for reassembling multipart URs.
+ */
+export class FountainDecoder {
+  private seqLen: number | null = null;
+  private messageLen: number | null = null;
+  private checksum: number | null = null;
+
+  // Storage for received data
+  private readonly pureFragments = new Map<number, Uint8Array>();
+  private readonly mixedParts = new Map<number, { indices: number[]; data: Uint8Array }>();
+
+  /**
+   * Receives a fountain part and attempts to decode.
+   *
+   * @param part - The fountain part to receive
+   * @returns true if the message is now complete
+   */
+  receive(part: FountainPart): boolean {
+    // Initialize on first part
+    if (this.seqLen === null) {
+      this.seqLen = part.seqLen;
+      this.messageLen = part.messageLen;
+      this.checksum = part.checksum;
+    }
+
+    // Validate consistency
+    if (
+      part.seqLen !== this.seqLen ||
+      part.messageLen !== this.messageLen ||
+      part.checksum !== this.checksum
+    ) {
+      throw new Error("Inconsistent part metadata");
+    }
+
+    // Determine which fragments this part contains
+    const indices = chooseFragments(part.seqNum, this.seqLen, this.checksum);
+
+    if (indices.length === 1) {
+      // Pure fragment
+      const index = indices[0];
+      if (!this.pureFragments.has(index)) {
+        this.pureFragments.set(index, part.data);
+      }
+    } else {
+      // Mixed fragment - store for later reduction
+      if (!this.mixedParts.has(part.seqNum)) {
+        this.mixedParts.set(part.seqNum, { indices, data: part.data });
+      }
+    }
+
+    // Try to reduce mixed parts
+    this.reduceMixedParts();
+
+    return this.isComplete();
+  }
+
+  /**
+   * Attempts to extract pure fragments from mixed parts.
+   */
+  private reduceMixedParts(): void {
+    let progress = true;
+
+    while (progress) {
+      progress = false;
+
+      for (const [seqNum, mixed] of this.mixedParts) {
+        // Find which indices we're missing
+        const missing: number[] = [];
+        let reduced = mixed.data;
+
+        for (const index of mixed.indices) {
+          const pure = this.pureFragments.get(index);
+          if (pure !== undefined) {
+            // XOR out the known fragment
+            reduced = xorBytes(reduced, pure);
+          } else {
+            missing.push(index);
+          }
+        }
+
+        if (missing.length === 0) {
+          // All fragments known, remove this mixed part
+          this.mixedParts.delete(seqNum);
+          progress = true;
+        } else if (missing.length === 1) {
+          // Can extract the missing fragment
+          const missingIndex = missing[0];
+          this.pureFragments.set(missingIndex, reduced);
+          this.mixedParts.delete(seqNum);
+          progress = true;
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns whether all fragments have been received.
+   */
+  isComplete(): boolean {
+    if (this.seqLen === null) {
+      return false;
+    }
+
+    return this.pureFragments.size === this.seqLen;
+  }
+
+  /**
+   * Reconstructs the original message.
+   *
+   * @returns The original message, or null if not yet complete
+   */
+  message(): Uint8Array | null {
+    if (!this.isComplete() || this.seqLen === null || this.messageLen === null) {
+      return null;
+    }
+
+    // Calculate fragment size from first fragment
+    const firstFragment = this.pureFragments.get(0);
+    if (firstFragment === undefined) {
+      return null;
+    }
+
+    const fragmentLen = firstFragment.length;
+    const result = new Uint8Array(this.messageLen);
+
+    // Assemble fragments
+    for (let i = 0; i < this.seqLen; i++) {
+      const fragment = this.pureFragments.get(i);
+      if (fragment === undefined) {
+        return null;
+      }
+
+      const start = i * fragmentLen;
+      const end = Math.min(start + fragmentLen, this.messageLen);
+      const len = end - start;
+
+      result.set(fragment.slice(0, len), start);
+    }
+
+    // Verify checksum
+    const actualChecksum = crc32(result);
+    if (actualChecksum !== this.checksum) {
+      throw new Error(`Checksum mismatch: expected ${this.checksum}, got ${actualChecksum}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Returns the progress as a fraction (0 to 1).
+   */
+  progress(): number {
+    if (this.seqLen === null) {
+      return 0;
+    }
+    return this.pureFragments.size / this.seqLen;
+  }
+
+  /**
+   * Resets the decoder.
+   */
+  reset(): void {
+    this.seqLen = null;
+    this.messageLen = null;
+    this.checksum = null;
+    this.pureFragments.clear();
+    this.mixedParts.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// Core types
+export { UR } from "./ur";
+export { URType } from "./ur-type";
+
+// Error types
+export {
+  URError,
+  InvalidSchemeError,
+  TypeUnspecifiedError,
+  InvalidTypeError,
+  NotSinglePartError,
+  UnexpectedTypeError,
+  BytewordsError,
+  CBORError,
+  isError,
+} from "./error";
+
+export type { Result } from "./error";
+
+// Traits/Interfaces
+export { isUREncodable } from "./ur-encodable";
+export type { UREncodable } from "./ur-encodable";
+export { isURDecodable } from "./ur-decodable";
+export type { URDecodable } from "./ur-decodable";
+export { isURCodable } from "./ur-codable";
+export type { URCodable } from "./ur-codable";
+
+// Multipart encoding/decoding
+export { MultipartEncoder } from "./multipart-encoder";
+export { MultipartDecoder } from "./multipart-decoder";
+
+// Fountain codes (for advanced multipart handling)
+export {
+  FountainEncoder,
+  FountainDecoder,
+  splitMessage,
+  xorBytes,
+  chooseFragments,
+  mixFragments,
+} from "./fountain";
+export type { FountainPart } from "./fountain";
+
+// PRNG for deterministic fountain code mixing
+export { Xoshiro256, createSeed } from "./xoshiro";
+
+// Utilities
+export {
+  isURTypeChar,
+  isValidURType,
+  validateURType,
+  BYTEWORDS,
+  BYTEWORDS_MAP,
+  BYTEMOJIS,
+  encodeBytewordsIdentifier,
+  encodeBytemojisIdentifier,
+  BytewordsStyle,
+  encodeBytewords,
+  decodeBytewords,
+  crc32,
+  MINIMAL_BYTEWORDS_MAP,
+} from "./utils";