@bcts/uniform-resources 1.0.0-alpha.9 → 1.0.0-beta.1

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@bcts/uniform-resources",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-beta.1",
   "type": "module",
   "description": "Blockchain Commons Uniform Resources (UR) for TypeScript",
   "license": "BSD-2-Clause-Patent",
-  "author": "Leonardo Custodio <leonardo@custodio.me>",
-  "homepage": "https://github.com/leonardocustodio/bcts",
+  "author": "Parity Technologies <admin@parity.io> (https://parity.io)",
+  "homepage": "https://bcts.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/leonardocustodio/bcts",
+    "url": "https://github.com/paritytech/bcts",
     "directory": "packages/uniform-resources"
   },
   "bugs": {
-    "url": "https://github.com/leonardocustodio/bcts/issues"
+    "url": "https://github.com/paritytech/bcts/issues"
   },
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -33,14 +33,14 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "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",
@@ -55,20 +55,21 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@bcts/dcbor": "^1.0.0-alpha.9"
+    "@bcts/crypto": "^1.0.0-beta.1",
+    "@bcts/dcbor": "^1.0.0-beta.1"
   },
   "devDependencies": {
     "@bcts/eslint": "^0.1.0",
     "@bcts/tsconfig": "^0.1.0",
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.2",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.1",
     "@types/pako": "^2.0.4",
-    "eslint": "^9.39.1",
-    "prettier": "^3.7.4",
+    "eslint": "^10.4.0",
+    "prettier": "^3.8.3",
     "ts-node": "^10.9.2",
-    "tsdown": "^0.17.2",
-    "typedoc": "^0.28.15",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "tsdown": "^0.22.0",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   }
 }

package/src/bytewords-namespace.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
+ * Namespace-style re-export of the bytewords helpers in `./utils`.
+ *
+ * Mirrors Rust's `bc_ur::bytewords` module (`bc-ur-rust/src/bytewords.rs`)
+ * so that callers can write
+ *
+ * ```ts
+ * import { bytewords } from "@bcts/uniform-resources";
+ * bytewords.encode(data, bytewords.Style.Minimal);
+ * bytewords.identifier(fourByteSlice);
+ * ```
+ *
+ * matching the ergonomics of
+ *
+ * ```rust
+ * use bc_ur::bytewords;
+ * bytewords::encode(data, bytewords::Style::Minimal);
+ * bytewords::identifier(four_byte_slice);
+ * ```
+ *
+ * This is purely an alias module — every symbol below is the same
+ * function/value already exported individually from the package root.
+ */
+
+export {
+  BYTEWORDS,
+  BYTEMOJIS,
+  BytewordsStyle as Style,
+  encodeBytewords as encode,
+  decodeBytewords as decode,
+  encodeBytewordsIdentifier as identifier,
+  encodeBytemojisIdentifier as bytemojiIdentifier,
+  encodeToWords,
+  encodeToBytemojis,
+  encodeToMinimalBytewords,
+  isValidBytemoji,
+  canonicalizeByteword,
+} from "./utils";

package/src/error.ts

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Error type for UR encoding/decoding operations.
  */
 export class URError extends Error {
@@ -10,30 +14,36 @@ export class URError extends Error {
 
 /**
  * Error type for invalid UR schemes.
+ *
+ * Message matches Rust bc-ur-rust/src/error.rs: `invalid UR scheme`.
  */
 export class InvalidSchemeError extends URError {
   constructor() {
-    super("Invalid UR scheme");
+    super("invalid UR scheme");
     this.name = "InvalidSchemeError";
   }
 }
 
 /**
  * Error type for unspecified UR types.
+ *
+ * Message matches Rust bc-ur-rust/src/error.rs: `no UR type specified`.
  */
 export class TypeUnspecifiedError extends URError {
   constructor() {
-    super("No UR type specified");
+    super("no UR type specified");
     this.name = "TypeUnspecifiedError";
   }
 }
 
 /**
  * Error type for invalid UR types.
+ *
+ * Message matches Rust bc-ur-rust/src/error.rs: `invalid UR type`.
  */
 export class InvalidTypeError extends URError {
   constructor() {
-    super("Invalid UR type");
+    super("invalid UR type");
     this.name = "InvalidTypeError";
   }
 }
@@ -50,34 +60,52 @@ export class NotSinglePartError extends URError {
 
 /**
  * Error type for unexpected UR types.
+ *
+ * Message matches Rust bc-ur-rust/src/error.rs:
+ * `expected UR type {expected}, but found {found}`.
  */
 export class UnexpectedTypeError extends URError {
   constructor(expected: string, found: string) {
-    super(`Expected UR type ${expected}, but found ${found}`);
+    super(`expected UR type ${expected}, but found ${found}`);
     this.name = "UnexpectedTypeError";
   }
 }
 
 /**
  * Error type for Bytewords encoding/decoding errors.
+ *
+ * Message matches Rust bc-ur-rust/src/error.rs: `Bytewords error ({0})`.
  */
 export class BytewordsError extends URError {
   constructor(message: string) {
-    super(`Bytewords error: ${message}`);
+    super(`Bytewords error (${message})`);
     this.name = "BytewordsError";
   }
 }
 
 /**
  * Error type for CBOR encoding/decoding errors.
+ *
+ * Message matches Rust bc-ur-rust/src/error.rs: `CBOR error ({0})`.
  */
 export class CBORError extends URError {
   constructor(message: string) {
-    super(`CBOR error: ${message}`);
+    super(`CBOR error (${message})`);
     this.name = "CBORError";
   }
 }
 
+/**
+ * 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

@@ -1,4 +1,8 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Fountain code implementation for multipart URs.
  *
  * This implements a hybrid fixed-rate and rateless fountain code system
@@ -30,27 +34,86 @@ export interface FountainPart {
 }
 
 /**
- * Splits data into fragments of the specified size.
+ * Calculates the quotient of `a` and `b`, rounded toward positive infinity.
+ *
+ * Mirrors Rust `ur-0.4.1/src/fountain.rs::div_ceil`.
  */
-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);
+function divCeil(a: number, b: number): number {
+  const d = Math.floor(a / b);
+  const r = a % b;
+  return r > 0 ? d + 1 : d;
+}
 
-    // Copy data and pad with zeros if needed
-    const sourceSlice = message.slice(start, end);
-    fragment.set(sourceSlice);
+/**
+ * Computes the optimal fragment length for a given message length and
+ * maximum fragment length.
+ *
+ * The algorithm:
+ *   fragment_count  = ceil(data_length / max_fragment_length)
+ *   fragment_length = ceil(data_length / fragment_count)
+ *
+ * This produces fragments that are as balanced as possible while still
+ * respecting `maxFragmentLen` as an upper bound on each fragment. For
+ * example, a 10-byte message with `maxFragmentLen = 6` yields a fragment
+ * length of 5 (so two even 5-byte fragments) rather than 6 (one full
+ * fragment plus a 4-byte tail).
+ *
+ * Mirrors Rust `ur-0.4.1/src/fountain.rs::fragment_length` byte-for-byte.
+ */
+export function fragmentLength(dataLength: number, maxFragmentLength: number): number {
+  const fragmentCount = divCeil(dataLength, maxFragmentLength);
+  return divCeil(dataLength, fragmentCount);
+}
 
-    fragments.push(fragment);
+/**
+ * Splits `data` into a list of `fragmentLen`-sized chunks, zero-padding
+ * the last chunk if necessary so that every chunk is exactly
+ * `fragmentLen` bytes long.
+ *
+ * Note: `fragmentLen` is the **already-computed** fragment length (see
+ * {@link fragmentLength}), not the user-facing maximum fragment length.
+ *
+ * Mirrors Rust `ur-0.4.1/src/fountain.rs::partition` byte-for-byte.
+ */
+export function partition(data: Uint8Array, fragmentLen: number): Uint8Array[] {
+  if (fragmentLen < 1) {
+    throw new Error("fragment length must be at least 1");
   }
+  const remainder = data.length % fragmentLen;
+  const padding = remainder === 0 ? 0 : fragmentLen - remainder;
+  const padded = new Uint8Array(data.length + padding);
+  padded.set(data);
+  // Trailing bytes are already zero by Uint8Array's default initialization.
 
+  const fragments: Uint8Array[] = [];
+  for (let start = 0; start < padded.length; start += fragmentLen) {
+    fragments.push(padded.slice(start, start + fragmentLen));
+  }
   return fragments;
 }
 
+/**
+ * Convenience: compute the optimal fragment length for `message` given
+ * `maxFragmentLen` and partition the message into that many fragments.
+ *
+ * Equivalent to:
+ * ```ts
+ * partition(message, fragmentLength(message.length, maxFragmentLen))
+ * ```
+ *
+ * This is what {@link FountainEncoder} does internally when constructing
+ * its fragment table.
+ */
+export function splitMessage(message: Uint8Array, maxFragmentLen: number): Uint8Array[] {
+  if (maxFragmentLen < 1) {
+    throw new Error("max fragment length must be at least 1");
+  }
+  if (message.length === 0) {
+    return [];
+  }
+  return partition(message, fragmentLength(message.length, maxFragmentLen));
+}
+
 /**
  * XOR two Uint8Arrays together.
  */
@@ -71,6 +134,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 +154,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);
 }
 
 /**
@@ -160,15 +203,25 @@ export class FountainEncoder {
    *
    * @param message - The message to encode
    * @param maxFragmentLen - Maximum length of each fragment
+   *
+   * @throws if `message` is empty (mirrors Rust `Error::EmptyMessage`).
+   * @throws if `maxFragmentLen < 1` (mirrors Rust `Error::InvalidFragmentLen`).
    */
   constructor(message: Uint8Array, maxFragmentLen: number) {
+    if (message.length === 0) {
+      throw new Error("expected non-empty message");
+    }
     if (maxFragmentLen < 1) {
-      throw new Error("Fragment length must be at least 1");
+      throw new Error("expected positive maximum fragment length");
     }
 
     this.messageLen = message.length;
     this.checksum = crc32(message);
-    this.fragments = splitMessage(message, maxFragmentLen);
+    // Mirrors Rust `Encoder::new`:
+    //   let fragment_length = fragment_length(message.len(), max_fragment_length);
+    //   let fragments = partition(message.to_vec(), fragment_length);
+    const optimalLen = fragmentLength(message.length, maxFragmentLen);
+    this.fragments = partition(message, optimalLen);
   }
 
   /**
@@ -232,54 +285,86 @@ export class FountainDecoder {
   private seqLen: number | null = null;
   private messageLen: number | null = null;
   private checksum: number | null = null;
+  private fragmentLen: number | null = null;
 
   // Storage for received data
   private readonly pureFragments = new Map<number, Uint8Array>();
   private readonly mixedParts = new Map<number, { indices: number[]; data: Uint8Array }>();
+  // Set of already-received `indices` keys (joined by `,`) — Rust uses
+  // `BTreeSet<Vec<usize>>` so two parts producing the same index set are
+  // deduped even when they have different sequence numbers. Mirrors
+  // `ur-0.4.1/src/fountain.rs::Decoder.received`.
+  private readonly receivedIndexSets = new Set<string>();
 
   /**
    * Receives a fountain part and attempts to decode.
    *
    * @param part - The fountain part to receive
-   * @returns true if the message is now complete
+   * @returns `true` if this part contributed new information,
+   *          `false` if it was an exact duplicate of a part already seen
+   *          (or if the decoder was already complete).
+   *
+   * @throws if the part is empty or inconsistent with previously received
+   *   parts. Mirrors Rust `Error::EmptyPart` and `Error::InconsistentPart`.
    */
   receive(part: FountainPart): boolean {
+    // Mirrors Rust `Decoder::receive`:
+    //   if self.complete() { return Ok(false); }
+    if (this.isComplete()) {
+      return false;
+    }
+
+    // Mirrors Rust's eager EmptyPart check.
+    if (part.seqLen === 0 || part.data.length === 0 || part.messageLen === 0) {
+      throw new Error("expected non-empty part");
+    }
+
     // Initialize on first part
     if (this.seqLen === null) {
       this.seqLen = part.seqLen;
       this.messageLen = part.messageLen;
       this.checksum = part.checksum;
-    }
-
-    // Validate consistency
-    if (
+      this.fragmentLen = part.data.length;
+    } else if (
+      // Mirrors Rust `Decoder::validate` exactly: every metadata field
+      // (sequence_count, message_length, checksum, fragment_length) must
+      // match across all received parts.
       part.seqLen !== this.seqLen ||
       part.messageLen !== this.messageLen ||
-      part.checksum !== this.checksum
+      part.checksum !== this.checksum ||
+      part.data.length !== this.fragmentLen
     ) {
-      throw new Error("Inconsistent part metadata");
+      throw new Error("part is inconsistent with previous ones");
     }
 
-    // Determine which fragments this part contains
-    const indices = chooseFragments(part.seqNum, this.seqLen, this.checksum);
+    // Determine which fragments this part contains.
+    const indices = chooseFragments(part.seqNum, this.seqLen, this.checksum ?? 0);
+    // Rust sorts the indices implicitly via `BTreeSet` membership; we
+    // explicitly sort the key so that two parts whose `chooseFragments`
+    // output is the same multiset (regardless of order) collapse to the
+    // same dedup key. In practice `chooseFragments` already produces a
+    // deterministic shuffle, so this is just defensive.
+    const indexSetKey = [...indices].sort((a, b) => a - b).join(",");
+    if (this.receivedIndexSets.has(indexSetKey)) {
+      return false;
+    }
+    this.receivedIndexSets.add(indexSetKey);
 
     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);
       }
     } else {
-      // Mixed fragment - store for later reduction
-      if (!this.mixedParts.has(part.seqNum)) {
-        this.mixedParts.set(part.seqNum, { indices, data: part.data });
-      }
+      // Mixed fragment - store for later reduction.
+      this.mixedParts.set(part.seqNum, { indices, data: part.data });
     }
 
-    // Try to reduce mixed parts
+    // Try to reduce mixed parts.
     this.reduceMixedParts();
 
-    return this.isComplete();
+    return true;
   }
 
   /**
@@ -391,7 +476,9 @@ export class FountainDecoder {
     this.seqLen = null;
     this.messageLen = null;
     this.checksum = null;
+    this.fragmentLen = null;
     this.pureFragments.clear();
     this.mixedParts.clear();
+    this.receivedIndexSets.clear();
   }
 }

package/src/index.ts

@@ -1,10 +1,17 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Core types
 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,
@@ -18,9 +25,9 @@ export {
 export type { Result } from "./error";
 
 // Traits/Interfaces
-export { isUREncodable } from "./ur-encodable";
+export { isUREncodable, urFromEncodable, urStringFromEncodable } from "./ur-encodable";
 export type { UREncodable } from "./ur-encodable";
-export { isURDecodable } from "./ur-decodable";
+export { isURDecodable, decodableFromUR, decodableFromURString } from "./ur-decodable";
 export type { URDecodable } from "./ur-decodable";
 export { isURCodable } from "./ur-codable";
 export type { URCodable } from "./ur-codable";
@@ -29,33 +36,27 @@ export type { URCodable } from "./ur-codable";
 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
+// URType validation helpers (mirroring Rust's `URTypeChar` / `URTypeString`
+// trait sugar in `bc-ur-rust/src/utils.rs`).
+export { isURTypeChar, isValidURType, validateURType } from "./utils";
+
+// Bytewords module (matching Rust's pub mod bytewords)
 export {
-  isURTypeChar,
-  isValidURType,
-  validateURType,
   BYTEWORDS,
-  BYTEWORDS_MAP,
   BYTEMOJIS,
-  encodeBytewordsIdentifier,
-  encodeBytemojisIdentifier,
   BytewordsStyle,
   encodeBytewords,
   decodeBytewords,
-  crc32,
-  MINIMAL_BYTEWORDS_MAP,
+  encodeBytewordsIdentifier,
+  encodeBytemojisIdentifier,
+  encodeToWords,
+  encodeToBytemojis,
+  encodeToMinimalBytewords,
+  isValidBytemoji,
+  canonicalizeByteword,
 } from "./utils";
+
+// Namespace-style re-export so callers can write `bytewords.encode(...)` /
+// `bytewords.decode(...)` to mirror Rust's `bc_ur::bytewords::encode(...)` etc.
+// Tracked in PARITY_AUDIT.md §3.1 / §4.5.
+export * as bytewords from "./bytewords-namespace";