@bcts/uniform-resources 1.0.0-alpha.13 → 1.0.0-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcts/uniform-resources",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "type": "module",
   "description": "Blockchain Commons Uniform Resources (UR) for TypeScript",
   "license": "BSD-2-Clause-Patent",
@@ -44,7 +44,6 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
@@ -67,18 +66,19 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@bcts/dcbor": "^1.0.0-alpha.13"
+    "@bcts/crypto": "^1.0.0-alpha.15",
+    "@bcts/dcbor": "^1.0.0-alpha.15"
   },
   "devDependencies": {
     "@bcts/eslint": "^0.1.0",
     "@bcts/tsconfig": "^0.1.0",
     "@eslint/js": "^9.39.2",
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.0.6",
     "@types/pako": "^2.0.4",
     "eslint": "^9.39.2",
     "prettier": "^3.7.4",
     "ts-node": "^10.9.2",
-    "tsdown": "^0.18.3",
+    "tsdown": "^0.18.4",
     "typedoc": "^0.28.15",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"

package/src/fountain.ts

@@ -71,6 +71,11 @@ export function xorBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
  * This uses a seeded Xoshiro256** PRNG to deterministically select fragments,
  * ensuring encoder and decoder agree without explicit coordination.
  *
+ * The algorithm matches the BC-UR reference implementation:
+ * 1. For pure parts (seqNum <= seqLen), return single fragment index
+ * 2. For mixed parts, use weighted sampling to choose degree
+ * 3. Shuffle all indices and take the first 'degree' indices
+ *
  * @param seqNum - The sequence number (1-based)
  * @param seqLen - Total number of pure fragments
  * @param checksum - CRC32 checksum of the message
@@ -86,43 +91,18 @@ export function chooseFragments(seqNum: number, seqLen: number, checksum: number
   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 degree using weighted sampler (1/k distribution)
+  const degree = rng.chooseDegree(seqLen);
 
-  // Choose which fragments to include
-  const indices = new Set<number>();
-  while (indices.size < degree) {
-    const index = rng.nextInt(0, seqLen);
-    indices.add(index);
+  // Create array of all indices [0, 1, 2, ..., seqLen-1]
+  const allIndices: number[] = [];
+  for (let i = 0; i < seqLen; i++) {
+    allIndices.push(i);
   }
 
-  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);
-  }
+  // Shuffle all indices and take the first 'degree' indices
+  const shuffled = rng.shuffled(allIndices);
+  return shuffled.slice(0, degree);
 }
 
 /**
@@ -264,7 +244,7 @@ export class FountainDecoder {
     const indices = chooseFragments(part.seqNum, this.seqLen, this.checksum);
 
     if (indices.length === 1) {
-      // Pure fragment
+      // Pure fragment (or degree-1 mixed that acts like pure)
       const index = indices[0];
       if (!this.pureFragments.has(index)) {
         this.pureFragments.set(index, part.data);

package/src/multipart-decoder.ts

@@ -1,4 +1,4 @@
-import { decodeCbor } from "@bcts/dcbor";
+import { decodeCbor, MajorType, type Cbor } from "@bcts/dcbor";
 import { InvalidSchemeError, InvalidTypeError, UnexpectedTypeError, URError } from "./error.js";
 import { UR } from "./ur.js";
 import { URType } from "./ur-type.js";
@@ -118,27 +118,43 @@ export class MultipartDecoder {
 
   /**
    * Decodes a multipart UR's fountain part data.
+   *
+   * The multipart body is a CBOR array: [seqNum, seqLen, messageLen, checksum, data]
    */
   private _decodeFountainPart(partInfo: MultipartInfo): FountainPart {
-    // Decode bytewords
-    const rawData = decodeBytewords(partInfo.encodedData, BytewordsStyle.Minimal);
+    // Decode bytewords to get CBOR data
+    const cborData = decodeBytewords(partInfo.encodedData, BytewordsStyle.Minimal);
 
-    if (rawData.length < 8) {
-      throw new URError("Invalid multipart data: too short");
-    }
+    // Decode the CBOR array
+    const decoded = decodeCbor(cborData);
 
-    // Extract metadata
-    const messageLen =
-      ((rawData[0] << 24) | (rawData[1] << 16) | (rawData[2] << 8) | rawData[3]) >>> 0;
+    // The decoded value should be an array with 5 elements
+    if (decoded.type !== MajorType.Array) {
+      throw new URError("Invalid multipart data: expected CBOR array");
+    }
 
-    const checksum =
-      ((rawData[4] << 24) | (rawData[5] << 16) | (rawData[6] << 8) | rawData[7]) >>> 0;
+    const items = decoded.value as Cbor[];
+    if (items.length !== 5) {
+      throw new URError(`Invalid multipart data: expected 5 elements, got ${items.length}`);
+    }
 
-    const data = rawData.slice(8);
+    // Extract the fields: [seqNum, seqLen, messageLen, checksum, data]
+    const seqNum = Number(items[0].value);
+    const seqLen = Number(items[1].value);
+    const messageLen = Number(items[2].value);
+    const checksum = Number(items[3].value);
+    const data = items[4].value as Uint8Array;
+
+    // Verify seqNum and seqLen match the URL path values
+    if (seqNum !== partInfo.seqNum || seqLen !== partInfo.seqLen) {
+      throw new URError(
+        `Multipart metadata mismatch: URL says ${partInfo.seqNum}-${partInfo.seqLen}, CBOR says ${seqNum}-${seqLen}`,
+      );
+    }
 
     return {
-      seqNum: partInfo.seqNum,
-      seqLen: partInfo.seqLen,
+      seqNum,
+      seqLen,
       messageLen,
       checksum,
       data,

package/src/multipart-encoder.ts

@@ -2,6 +2,7 @@ import type { UR } from "./ur.js";
 import { URError } from "./error.js";
 import { FountainEncoder, type FountainPart } from "./fountain.js";
 import { encodeBytewords, BytewordsStyle } from "./utils.js";
+import { cbor } from "@bcts/dcbor";
 
 /**
  * Encodes a UR as multiple parts using fountain codes.
@@ -96,28 +97,14 @@ export class MultipartEncoder {
   }
 
   /**
-   * Encodes part metadata and data into bytes for bytewords encoding.
+   * Encodes part metadata and data as CBOR for bytewords encoding.
+   * Format: CBOR array [seqNum, seqLen, messageLen, checksum, data]
    */
   private _encodePartData(part: FountainPart): Uint8Array {
-    // Simple encoding: messageLen (4 bytes) + checksum (4 bytes) + data
-    const result = new Uint8Array(8 + part.data.length);
+    // Create CBOR array with 5 elements: [seqNum, seqLen, messageLen, checksum, data]
+    const cborArray = cbor([part.seqNum, part.seqLen, part.messageLen, part.checksum, part.data]);
 
-    // Message length (big-endian)
-    result[0] = (part.messageLen >>> 24) & 0xff;
-    result[1] = (part.messageLen >>> 16) & 0xff;
-    result[2] = (part.messageLen >>> 8) & 0xff;
-    result[3] = part.messageLen & 0xff;
-
-    // Checksum (big-endian)
-    result[4] = (part.checksum >>> 24) & 0xff;
-    result[5] = (part.checksum >>> 16) & 0xff;
-    result[6] = (part.checksum >>> 8) & 0xff;
-    result[7] = part.checksum & 0xff;
-
-    // Fragment data
-    result.set(part.data, 8);
-
-    return result;
+    return cborArray.toData();
   }
 
   /**

package/src/utils.ts

@@ -615,7 +615,7 @@ export function encodeBytemojisIdentifier(data: Uint8Array): string {
 export enum BytewordsStyle {
   /** Full 4-letter words separated by spaces */
   Standard = "standard",
-  /** Full 4-letter words without separators */
+  /** Full 4-letter words separated by hyphens (URI-safe) */
   Uri = "uri",
   /** First and last character only (minimal) - used by UR encoding */
   Minimal = "minimal",
@@ -712,6 +712,7 @@ export function encodeBytewords(
     case BytewordsStyle.Standard:
       return words.join(" ");
     case BytewordsStyle.Uri:
+      return words.join("-");
     case BytewordsStyle.Minimal:
       return words.join("");
   }
@@ -741,19 +742,15 @@ export function decodeBytewords(
       break;
     }
     case BytewordsStyle.Uri: {
-      // 4-character words with no separator
-      if (lowercased.length % 4 !== 0) {
-        throw new Error("Invalid URI bytewords length");
-      }
-      bytes = [];
-      for (let i = 0; i < lowercased.length; i += 4) {
-        const word = lowercased.slice(i, i + 4);
+      // 4-character words separated by hyphens
+      const words = lowercased.split("-");
+      bytes = words.map((word) => {
         const index = BYTEWORDS_MAP.get(word);
         if (index === undefined) {
           throw new Error(`Invalid byteword: ${word}`);
         }
-        bytes.push(index);
-      }
+        return index;
+      });
       break;
     }
     case BytewordsStyle.Minimal: {

package/src/xoshiro.ts

@@ -5,8 +5,11 @@
  * for deterministic fragment selection in fountain codes.
  *
  * Reference: https://prng.di.unimi.it/
+ * BC-UR Reference: https://github.com/nicklockwood/fountain-codes
  */
 
+import { sha256 } from "@bcts/crypto";
+
 const MAX_UINT64 = BigInt("0xffffffffffffffff");
 
 /**
@@ -28,25 +31,33 @@ export class Xoshiro256 {
   private s: [bigint, bigint, bigint, bigint];
 
   /**
-   * Creates a new Xoshiro256** instance from a seed.
+   * Creates a new Xoshiro256** instance from a 32-byte seed.
    *
-   * The seed is hashed using SHA-256 to initialize the state.
-   * For consistent results across encoder/decoder, use the same seed.
+   * The seed must be exactly 32 bytes (256 bits). The bytes are interpreted
+   * using the BC-UR reference algorithm: each 8-byte chunk is read as
+   * big-endian then stored as little-endian for the state.
    *
-   * @param seed - The seed bytes (any length)
+   * @param seed - The seed bytes (must be exactly 32 bytes)
    */
   constructor(seed: Uint8Array) {
-    // Hash the seed using a simple hash function
-    // In production, you'd use SHA-256 here
-    const hash = this.hashSeed(seed);
-
-    // Initialize the 4x64-bit state from the hash
-    this.s = [
-      this.bytesToBigInt(hash.slice(0, 8)),
-      this.bytesToBigInt(hash.slice(8, 16)),
-      this.bytesToBigInt(hash.slice(16, 24)),
-      this.bytesToBigInt(hash.slice(24, 32)),
-    ];
+    if (seed.length !== 32) {
+      throw new Error(`Seed must be 32 bytes, got ${seed.length}`);
+    }
+
+    // BC-UR reference implementation:
+    // For each 8-byte chunk, read as big-endian u64, then convert to little-endian bytes
+    // This effectively swaps the byte order within each 8-byte segment
+    const s: [bigint, bigint, bigint, bigint] = [0n, 0n, 0n, 0n];
+    for (let i = 0; i < 4; i++) {
+      // Read 8 bytes as big-endian u64
+      let v = 0n;
+      for (let n = 0; n < 8; n++) {
+        v = (v << 8n) | BigInt(seed[8 * i + n] ?? 0);
+      }
+      s[i] = v;
+    }
+
+    this.s = s;
   }
 
   /**
@@ -59,47 +70,6 @@ export class Xoshiro256 {
     return instance;
   }
 
-  /**
-   * Simple hash function for seeding.
-   * This is a basic implementation - in production use SHA-256.
-   */
-  private hashSeed(seed: Uint8Array): Uint8Array {
-    // Simple hash expansion using CRC32-like operations
-    const result = new Uint8Array(32);
-
-    if (seed.length === 0) {
-      return result;
-    }
-
-    // Expand seed to 32 bytes using a simple mixing function
-    for (let i = 0; i < 32; i++) {
-      let hash = 0;
-      for (const byte of seed) {
-        hash = (hash * 31 + byte + i) >>> 0;
-      }
-      // Mix the hash further
-      hash ^= hash >>> 16;
-      hash = (hash * 0x85ebca6b) >>> 0;
-      hash ^= hash >>> 13;
-      hash = (hash * 0xc2b2ae35) >>> 0;
-      hash ^= hash >>> 16;
-      result[i] = hash & 0xff;
-    }
-
-    return result;
-  }
-
-  /**
-   * Converts 8 bytes to a 64-bit BigInt (little-endian).
-   */
-  private bytesToBigInt(bytes: Uint8Array): bigint {
-    let result = 0n;
-    for (let i = 7; i >= 0; i--) {
-      result = (result << 8n) | BigInt(bytes[i] ?? 0);
-    }
-    return result;
-  }
-
   /**
    * Generates the next 64-bit random value.
    */
@@ -121,19 +91,21 @@ export class Xoshiro256 {
 
   /**
    * Generates a random double in [0, 1).
+   * Matches BC-UR reference: self.next() as f64 / (u64::MAX as f64 + 1.0)
    */
   nextDouble(): number {
-    // Use the upper 53 bits for double precision
     const value = this.next();
-    return Number(value >> 11n) / Number(1n << 53n);
+    // u64::MAX as f64 + 1.0 = 18446744073709551616.0
+    return Number(value) / 18446744073709551616.0;
   }
 
   /**
-   * Generates a random integer in [low, high).
+   * Generates a random integer in [low, high] (inclusive).
+   * Matches BC-UR reference: (self.next_double() * ((high - low + 1) as f64)) as u64 + low
    */
   nextInt(low: number, high: number): number {
-    const range = high - low;
-    return low + Math.floor(this.nextDouble() * range);
+    const range = high - low + 1;
+    return Math.floor(this.nextDouble() * range) + low;
   }
 
   /**
@@ -153,28 +125,150 @@ export class Xoshiro256 {
     }
     return result;
   }
+
+  /**
+   * Shuffles items by repeatedly picking random indices.
+   * Matches BC-UR reference implementation.
+   */
+  shuffled<T>(items: T[]): T[] {
+    const source = [...items];
+    const shuffled: T[] = [];
+    while (source.length > 0) {
+      const index = this.nextInt(0, source.length - 1);
+      const item = source.splice(index, 1)[0];
+      if (item !== undefined) {
+        shuffled.push(item);
+      }
+    }
+    return shuffled;
+  }
+
+  /**
+   * Chooses the degree (number of fragments to mix) using a weighted sampler.
+   * Uses the robust soliton distribution with weights [1/1, 1/2, 1/3, ..., 1/n].
+   * Matches BC-UR reference implementation.
+   */
+  chooseDegree(seqLen: number): number {
+    // Create weights: [1/1, 1/2, 1/3, ..., 1/seqLen]
+    const weights: number[] = [];
+    for (let i = 1; i <= seqLen; i++) {
+      weights.push(1.0 / i);
+    }
+
+    // Use Vose's alias method for weighted sampling
+    const sampler = new WeightedSampler(weights);
+    return sampler.next(this) + 1; // 1-indexed degree
+  }
 }
 
 /**
- * Creates a seed for the Xoshiro PRNG from message checksum and sequence number.
+ * Weighted sampler using Vose's alias method.
+ * Allows O(1) sampling from a discrete probability distribution.
+ */
+class WeightedSampler {
+  private readonly aliases: number[];
+  private readonly probs: number[];
+
+  constructor(weights: number[]) {
+    const n = weights.length;
+    if (n === 0) {
+      throw new Error("Weights array cannot be empty");
+    }
+
+    // Normalize weights
+    const sum = weights.reduce((a, b) => a + b, 0);
+    if (sum <= 0) {
+      throw new Error("Weights must sum to a positive value");
+    }
+
+    const normalized = weights.map((w) => (w * n) / sum);
+
+    // Initialize alias table
+    this.aliases = Array.from<number>({ length: n }).fill(0);
+    this.probs = Array.from<number>({ length: n }).fill(0);
+
+    // Partition into small and large
+    const small: number[] = [];
+    const large: number[] = [];
+
+    for (let i = n - 1; i >= 0; i--) {
+      if (normalized[i] < 1.0) {
+        small.push(i);
+      } else {
+        large.push(i);
+      }
+    }
+
+    // Build the alias table
+    while (small.length > 0 && large.length > 0) {
+      const a = small.pop();
+      const g = large.pop();
+      if (a === undefined || g === undefined) break;
+      this.probs[a] = normalized[a] ?? 0;
+      this.aliases[a] = g;
+      const normalizedG = normalized[g] ?? 0;
+      const normalizedA = normalized[a] ?? 0;
+      normalized[g] = normalizedG + normalizedA - 1.0;
+      if (normalized[g] !== undefined && normalized[g] < 1.0) {
+        small.push(g);
+      } else {
+        large.push(g);
+      }
+    }
+
+    while (large.length > 0) {
+      const g = large.pop();
+      if (g === undefined) break;
+      this.probs[g] = 1.0;
+    }
+
+    while (small.length > 0) {
+      const a = small.pop();
+      if (a === undefined) break;
+      this.probs[a] = 1.0;
+    }
+  }
+
+  /**
+   * Sample from the distribution.
+   */
+  next(rng: Xoshiro256): number {
+    const r1 = rng.nextDouble();
+    const r2 = rng.nextDouble();
+    const n = this.probs.length;
+    const i = Math.floor(n * r1);
+    if (r2 < this.probs[i]) {
+      return i;
+    } else {
+      return this.aliases[i];
+    }
+  }
+}
+
+/**
+ * Creates a Xoshiro256 PRNG instance from message checksum and sequence number.
+ *
+ * This creates an 8-byte seed by concatenating seqNum and checksum (both in
+ * big-endian), then hashes it with SHA-256 to get the 32-byte seed for Xoshiro.
  *
- * This ensures that both encoder and decoder produce the same random sequence
- * for a given message and part number.
+ * This matches the BC-UR reference implementation.
  */
 export function createSeed(checksum: number, seqNum: number): Uint8Array {
-  const seed = new Uint8Array(8);
+  // Create 8-byte seed: seqNum (big-endian) || checksum (big-endian)
+  const seed8 = new Uint8Array(8);
 
-  // Pack checksum (4 bytes, big-endian)
-  seed[0] = (checksum >>> 24) & 0xff;
-  seed[1] = (checksum >>> 16) & 0xff;
-  seed[2] = (checksum >>> 8) & 0xff;
-  seed[3] = checksum & 0xff;
+  // seqNum in big-endian (bytes 0-3)
+  seed8[0] = (seqNum >>> 24) & 0xff;
+  seed8[1] = (seqNum >>> 16) & 0xff;
+  seed8[2] = (seqNum >>> 8) & 0xff;
+  seed8[3] = seqNum & 0xff;
 
-  // Pack seqNum (4 bytes, big-endian)
-  seed[4] = (seqNum >>> 24) & 0xff;
-  seed[5] = (seqNum >>> 16) & 0xff;
-  seed[6] = (seqNum >>> 8) & 0xff;
-  seed[7] = seqNum & 0xff;
+  // checksum in big-endian (bytes 4-7)
+  seed8[4] = (checksum >>> 24) & 0xff;
+  seed8[5] = (checksum >>> 16) & 0xff;
+  seed8[6] = (checksum >>> 8) & 0xff;
+  seed8[7] = checksum & 0xff;
 
-  return seed;
+  // Hash with SHA-256 to get 32 bytes
+  return sha256(seed8);
 }