@bcts/uniform-resources 1.0.0-alpha.12 → 1.0.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcts/uniform-resources",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "type": "module",
   "description": "Blockchain Commons Uniform Resources (UR) for TypeScript",
   "license": "BSD-2-Clause-Patent",
@@ -47,11 +47,12 @@
     "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "eslint 'src/**/*.ts'",
-    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "docs": "typedoc"
+    "docs": "typedoc",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "keywords": [
     "uniform-resources",
@@ -66,7 +67,8 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@bcts/dcbor": "^1.0.0-alpha.12"
+    "@bcts/crypto": "^1.0.0-alpha.14",
+    "@bcts/dcbor": "^1.0.0-alpha.14"
   },
   "devDependencies": {
     "@bcts/eslint": "^0.1.0",

package/src/error.ts

@@ -78,6 +78,17 @@ export class CBORError extends URError {
   }
 }
 
+/**
+ * Error type for UR decoder errors.
+ * Matches Rust's Error::UR(String) variant.
+ */
+export class URDecodeError extends URError {
+  constructor(message: string) {
+    super(`UR decoder error (${message})`);
+    this.name = "URDecodeError";
+  }
+}
+
 export type Result<T> = T | Error;
 
 /**

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/index.ts

@@ -2,9 +2,10 @@
 export { UR } from "./ur";
 export { URType } from "./ur-type";
 
-// Error types
+// Error types (matching Rust's Error enum variants)
 export {
   URError,
+  URDecodeError,
   InvalidSchemeError,
   TypeUnspecifiedError,
   InvalidTypeError,
@@ -29,33 +30,13 @@ export type { URCodable } from "./ur-codable";
 export { MultipartEncoder } from "./multipart-encoder";
 export { MultipartDecoder } from "./multipart-decoder";
 
-// Fountain codes (for advanced multipart handling)
+// Bytewords module (matching Rust's pub mod bytewords)
 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,
+  encodeBytewordsIdentifier,
+  encodeBytemojisIdentifier,
 } from "./utils";

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,
@@ -160,28 +176,6 @@ export class MultipartDecoder {
   message(): UR | null {
     return this._decodedMessage;
   }
-
-  /**
-   * Returns the decoding progress as a fraction (0 to 1).
-   */
-  progress(): number {
-    if (this._decodedMessage !== null) {
-      return 1;
-    }
-    if (this._fountainDecoder === null) {
-      return 0;
-    }
-    return this._fountainDecoder.progress();
-  }
-
-  /**
-   * Resets the decoder to receive a new message.
-   */
-  reset(): void {
-    this._urType = null;
-    this._fountainDecoder = null;
-    this._decodedMessage = null;
-  }
 }
 
 /**

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.
@@ -58,15 +59,6 @@ export class MultipartEncoder {
     this._fountainEncoder = new FountainEncoder(cborData, maxFragmentLen);
   }
 
-  /**
-   * Returns whether the message fits in a single part.
-   *
-   * For single-part messages, consider using UR.string() directly.
-   */
-  isSinglePart(): boolean {
-    return this._fountainEncoder.isSinglePart();
-  }
-
   /**
    * Gets the next part of the encoding.
    *
@@ -105,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();
   }
 
   /**
@@ -145,22 +123,4 @@ export class MultipartEncoder {
   partsCount(): number {
     return this._fountainEncoder.seqLen;
   }
-
-  /**
-   * Checks if all pure parts have been emitted.
-   *
-   * Even after this returns true, you can continue calling nextPart()
-   * to generate additional rateless parts for redundancy.
-   */
-  isComplete(): boolean {
-    return this._fountainEncoder.isComplete();
-  }
-
-  /**
-   * Resets the encoder to start from the beginning.
-   */
-  reset(): void {
-    this._currentIndex = 0;
-    this._fountainEncoder.reset();
-  }
 }

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: {