@bcts/rand 1.0.0-alpha.10

package/src/magnitude.ts

@@ -0,0 +1,75 @@
+// Ported from bc-rand-rust/src/magnitude.rs
+
+/**
+ * Converts a signed integer to its unsigned magnitude.
+ * For positive numbers, returns the number unchanged.
+ * For negative numbers, returns the absolute value (wrapping for MIN values).
+ *
+ * This matches Rust's wrapping_abs() behavior.
+ */
+export function toMagnitude(value: number, bits: 8 | 16 | 32): number {
+  switch (bits) {
+    case 8: {
+      // i8 to u8: wrapping_abs
+      const i8Value = (value << 24) >> 24; // Sign extend to i8
+      return Math.abs(i8Value) & 0xff;
+    }
+    case 16: {
+      // i16 to u16: wrapping_abs
+      const i16Value = (value << 16) >> 16; // Sign extend to i16
+      return Math.abs(i16Value) & 0xffff;
+    }
+    case 32: {
+      // i32 to u32: wrapping_abs
+      const i32Value = value | 0; // Force to i32
+      // Handle MIN_VALUE specially (wrapping behavior)
+      if (i32Value === -2147483648) {
+        return 2147483648; // Returns as positive
+      }
+      return Math.abs(i32Value) >>> 0; // Convert to unsigned
+    }
+  }
+}
+
+/**
+ * Converts a signed bigint to its unsigned magnitude for 64-bit values.
+ */
+export function toMagnitude64(value: bigint): bigint {
+  const mask = 0xffffffffffffffffn;
+  // Handle negative values
+  if (value < 0n) {
+    // Wrapping absolute value
+    const absValue = -value;
+    return absValue & mask;
+  }
+  return value & mask;
+}
+
+/**
+ * Converts an unsigned magnitude back to a signed value.
+ * Simply reinterprets the bits.
+ */
+export function fromMagnitude(magnitude: number, bits: 8 | 16 | 32): number {
+  switch (bits) {
+    case 8:
+      return (magnitude << 24) >> 24; // Sign extend from u8 to i8
+    case 16:
+      return (magnitude << 16) >> 16; // Sign extend from u16 to i16
+    case 32:
+      return magnitude | 0; // Reinterpret as i32
+  }
+}
+
+/**
+ * Converts an unsigned 64-bit magnitude back to a signed bigint.
+ */
+export function fromMagnitude64(magnitude: bigint): bigint {
+  const mask = 0xffffffffffffffffn;
+  const signBit = 1n << 63n;
+  const maskedMag = magnitude & mask;
+  if ((maskedMag & signBit) !== 0n) {
+    // Negative value - convert from two's complement
+    return maskedMag - (1n << 64n);
+  }
+  return maskedMag;
+}

package/src/random-number-generator.ts

@@ -0,0 +1,279 @@
+// Ported from bc-rand-rust/src/random_number_generator.rs
+
+import { wideMulU32, wideMulU64 } from "./widening.js";
+import {
+  toMagnitude,
+  toMagnitude64 as _toMagnitude64,
+  fromMagnitude as _fromMagnitude,
+  fromMagnitude64 as _fromMagnitude64,
+} from "./magnitude.js";
+
+/**
+ * Interface for random number generators.
+ * This is the TypeScript equivalent of Rust's RandomNumberGenerator trait
+ * which extends RngCore + CryptoRng.
+ *
+ * This is compatible with the RandomNumberGenerator Swift protocol used
+ * in MacOS and iOS, which is important for cross-platform testing.
+ */
+export interface RandomNumberGenerator {
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number;
+
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint;
+
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void;
+
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   */
+  randomData(size: number): Uint8Array;
+
+  /**
+   * Fills the given Uint8Array with random bytes.
+   * Alias for fillBytes for compatibility.
+   */
+  fillRandomData(data: Uint8Array): void;
+}
+
+/**
+ * Returns a Uint8Array of random bytes of the given size.
+ */
+export function rngRandomData(rng: RandomNumberGenerator, size: number): Uint8Array {
+  const data = new Uint8Array(size);
+  rng.fillRandomData(data);
+  return data;
+}
+
+/**
+ * Fills the given Uint8Array with random bytes.
+ */
+export function rngFillRandomData(rng: RandomNumberGenerator, data: Uint8Array): void {
+  rng.fillRandomData(data);
+}
+
+/**
+ * Returns a random value that is less than the given upper bound.
+ *
+ * Uses Lemire's "nearly divisionless" method for generating random
+ * integers in an interval. For a detailed explanation, see:
+ * https://arxiv.org/abs/1805.10941
+ *
+ * @param rng - The random number generator to use
+ * @param upperBound - The upper bound for the randomly generated value. Must be non-zero.
+ * @returns A random value in the range [0, upperBound). Every value in the range is equally likely.
+ */
+export function rngNextWithUpperBound(rng: RandomNumberGenerator, upperBound: bigint): bigint {
+  if (upperBound === 0n) {
+    throw new Error("upperBound must be non-zero");
+  }
+
+  // We use Lemire's "nearly divisionless" method for generating random
+  // integers in an interval. For a detailed explanation, see:
+  // https://arxiv.org/abs/1805.10941
+
+  const bitmask = 0xffffffffffffffffn; // u64 max
+  let random = rng.nextU64() & bitmask;
+  let m = wideMulU64(random, upperBound);
+
+  if (m[0] < upperBound) {
+    // t = (0 - upperBound) % upperBound
+    const negUpperBound = (bitmask + 1n - upperBound) & bitmask;
+    const t = negUpperBound % upperBound;
+    while (m[0] < t) {
+      random = rng.nextU64() & bitmask;
+      m = wideMulU64(random, upperBound);
+    }
+  }
+
+  return m[1];
+}
+
+/**
+ * Returns a random 32-bit value that is less than the given upper bound.
+ * This matches Rust's behavior when called with u32 type.
+ *
+ * Uses Lemire's "nearly divisionless" method with 32-bit arithmetic.
+ *
+ * @param rng - The random number generator to use
+ * @param upperBound - The upper bound for the randomly generated value. Must be non-zero and fit in u32.
+ * @returns A random u32 value in the range [0, upperBound).
+ */
+export function rngNextWithUpperBoundU32(rng: RandomNumberGenerator, upperBound: number): number {
+  if (upperBound === 0) {
+    throw new Error("upperBound must be non-zero");
+  }
+
+  const upperBoundU32 = upperBound >>> 0;
+  const bitmask = 0xffffffff;
+
+  // Get random and mask to 32 bits (matches Rust behavior)
+  let random = Number(rng.nextU64() & BigInt(bitmask));
+  let m = wideMulU32(random, upperBoundU32);
+
+  if (Number(m[0]) < upperBoundU32) {
+    // t = (0 - upperBound) % upperBound (wrapping subtraction)
+    const t = ((bitmask + 1 - upperBoundU32) >>> 0) % upperBoundU32;
+    while (Number(m[0]) < t) {
+      random = Number(rng.nextU64() & BigInt(bitmask));
+      m = wideMulU32(random, upperBoundU32);
+    }
+  }
+
+  return Number(m[1]);
+}
+
+/**
+ * Returns a random value within the specified range [start, end) using 32-bit arithmetic.
+ * This matches Rust's behavior when called with i32 types.
+ *
+ * @param rng - The random number generator to use
+ * @param start - The lower bound (inclusive) as i32
+ * @param end - The upper bound (exclusive) as i32
+ * @returns A random i32 value within the bounds
+ */
+export function rngNextInRangeI32(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) {
+    throw new Error("start must be less than end");
+  }
+
+  const startI32 = start | 0;
+  const endI32 = end | 0;
+  const delta = toMagnitude(endI32 - startI32, 32);
+
+  if (delta === 0xffffffff) {
+    return rng.nextU32() | 0;
+  }
+
+  const random = rngNextWithUpperBoundU32(rng, delta);
+  return (startI32 + random) | 0;
+}
+
+/**
+ * Returns a random value within the specified range [start, end).
+ *
+ * @param rng - The random number generator to use
+ * @param start - The lower bound (inclusive)
+ * @param end - The upper bound (exclusive)
+ * @returns A random value within the bounds of the range
+ */
+export function rngNextInRange(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint {
+  if (start >= end) {
+    throw new Error("start must be less than end");
+  }
+
+  const delta = end - start;
+
+  // If delta covers the entire range, just return a random value
+  const maxU64 = 0xffffffffffffffffn;
+  if (delta === maxU64) {
+    return rng.nextU64();
+  }
+
+  const random = rngNextWithUpperBound(rng, delta);
+  return start + random;
+}
+
+/**
+ * Returns a random value within the specified closed range [start, end].
+ *
+ * @param rng - The random number generator to use
+ * @param start - The lower bound (inclusive)
+ * @param end - The upper bound (inclusive)
+ * @returns A random value within the bounds of the range
+ */
+export function rngNextInClosedRange(
+  rng: RandomNumberGenerator,
+  start: bigint,
+  end: bigint,
+): bigint {
+  if (start > end) {
+    throw new Error("start must be less than or equal to end");
+  }
+
+  const delta = end - start;
+
+  // If delta covers the entire range, just return a random value
+  const maxU64 = 0xffffffffffffffffn;
+  if (delta === maxU64) {
+    return rng.nextU64();
+  }
+
+  const random = rngNextWithUpperBound(rng, delta + 1n);
+  return start + random;
+}
+
+/**
+ * Returns a random value within the specified closed range [start, end] for i32 values.
+ * Convenience function that handles signed 32-bit integers.
+ *
+ * @param rng - The random number generator to use
+ * @param start - The lower bound (inclusive) as i32
+ * @param end - The upper bound (inclusive) as i32
+ * @returns A random i32 value within the bounds of the range
+ */
+export function rngNextInClosedRangeI32(
+  rng: RandomNumberGenerator,
+  start: number,
+  end: number,
+): number {
+  if (start > end) {
+    throw new Error("start must be less than or equal to end");
+  }
+
+  // Convert to i32
+  const startI32 = start | 0;
+  const endI32 = end | 0;
+
+  // Calculate delta as u32 magnitude
+  const delta = toMagnitude(endI32 - startI32, 32);
+
+  // If delta covers the entire u32 range, just return a random value
+  if (delta === 0xffffffff) {
+    return rng.nextU32() | 0;
+  }
+
+  const random = rngNextWithUpperBoundU32(rng, delta + 1);
+  return (startI32 + random) | 0;
+}
+
+/**
+ * Returns a fixed-size array of random bytes.
+ *
+ * @param rng - The random number generator to use
+ * @param size - The size of the array to return
+ * @returns A Uint8Array of the specified size filled with random bytes
+ */
+export function rngRandomArray(rng: RandomNumberGenerator, size: number): Uint8Array {
+  const data = new Uint8Array(size);
+  rng.fillRandomData(data);
+  return data;
+}
+
+/**
+ * Returns a random boolean value.
+ *
+ * @param rng - The random number generator to use
+ * @returns A random boolean
+ */
+export function rngRandomBool(rng: RandomNumberGenerator): boolean {
+  return (rng.nextU32() & 1) === 0;
+}
+
+/**
+ * Returns a random 32-bit unsigned integer.
+ *
+ * @param rng - The random number generator to use
+ * @returns A random u32 value
+ */
+export function rngRandomU32(rng: RandomNumberGenerator): number {
+  return rng.nextU32();
+}

package/src/secure-random.ts

@@ -0,0 +1,97 @@
+// Ported from bc-rand-rust/src/secure_random.rs
+
+import type { RandomNumberGenerator } from "./random-number-generator.js";
+
+/**
+ * Detects the crypto API available in the current environment.
+ * Works in both Node.js and browser environments.
+ */
+function getCrypto(): Crypto {
+  // Browser environment
+  if (
+    typeof globalThis !== "undefined" &&
+    globalThis.crypto !== null &&
+    globalThis.crypto !== undefined
+  ) {
+    return globalThis.crypto;
+  }
+  // Node.js environment - globalThis.crypto is also available in Node.js >= 15
+  if (typeof globalThis.crypto !== "undefined") {
+    return globalThis.crypto;
+  }
+  throw new Error("No crypto API available in this environment");
+}
+
+/**
+ * Generate a Uint8Array of cryptographically strong random bytes of the given size.
+ */
+export function randomData(size: number): Uint8Array {
+  const data = new Uint8Array(size);
+  fillRandomData(data);
+  return data;
+}
+
+/**
+ * Fill the given Uint8Array with cryptographically strong random bytes.
+ */
+export function fillRandomData(data: Uint8Array): void {
+  const crypto = getCrypto();
+  crypto.getRandomValues(data);
+}
+
+/**
+ * Returns the next cryptographically strong random 64-bit unsigned integer.
+ */
+export function nextU64(): bigint {
+  const data = new Uint8Array(8);
+  fillRandomData(data);
+  const view = new DataView(data.buffer);
+  return view.getBigUint64(0, true); // little-endian
+}
+
+/**
+ * A random number generator that can be used as a source of
+ * cryptographically-strong randomness.
+ *
+ * Uses the Web Crypto API (crypto.getRandomValues) which is available
+ * in both browsers and Node.js >= 15.
+ */
+export class SecureRandomNumberGenerator implements RandomNumberGenerator {
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number {
+    const data = new Uint8Array(4);
+    fillRandomData(data);
+    const view = new DataView(data.buffer);
+    return view.getUint32(0, true) >>> 0; // little-endian, unsigned
+  }
+
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint {
+    return nextU64();
+  }
+
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void {
+    fillRandomData(dest);
+  }
+
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   */
+  randomData(size: number): Uint8Array {
+    return randomData(size);
+  }
+
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillRandomData(data: Uint8Array): void {
+    fillRandomData(data);
+  }
+}

package/src/seeded-random.ts

@@ -0,0 +1,171 @@
+// Ported from bc-rand-rust/src/seeded_random.rs
+
+import type { RandomNumberGenerator } from "./random-number-generator.js";
+
+/**
+ * Xoshiro256** state
+ * Based on xoshiro256** 1.0 by David Blackman and Sebastiano Vigna
+ * https://prng.di.unimi.it/
+ */
+interface Xoshiro256State {
+  s0: bigint;
+  s1: bigint;
+  s2: bigint;
+  s3: bigint;
+}
+
+/**
+ * Rotate left for 64-bit bigint
+ */
+function rotl(x: bigint, k: number): bigint {
+  const mask = 0xffffffffffffffffn;
+  return ((x << BigInt(k)) | (x >> BigInt(64 - k))) & mask;
+}
+
+/**
+ * Xoshiro256** PRNG implementation
+ * This is the same algorithm used by rand_xoshiro in Rust
+ */
+function xoshiro256StarStar(state: Xoshiro256State): bigint {
+  const mask = 0xffffffffffffffffn;
+
+  // result = rotl(s1 * 5, 7) * 9
+  const result = (rotl((state.s1 * 5n) & mask, 7) * 9n) & mask;
+
+  // t = s1 << 17
+  const t = (state.s1 << 17n) & mask;
+
+  // Update state
+  state.s2 ^= state.s0;
+  state.s3 ^= state.s1;
+  state.s1 ^= state.s2;
+  state.s0 ^= state.s3;
+
+  state.s2 ^= t;
+  state.s3 = rotl(state.s3, 45);
+
+  return result;
+}
+
+/**
+ * A random number generator that can be used as a source of deterministic
+ * pseudo-randomness for testing purposes.
+ *
+ * Uses the Xoshiro256** algorithm, which is the same algorithm used by
+ * rand_xoshiro in Rust. This ensures cross-platform compatibility with
+ * the Rust implementation.
+ *
+ * WARNING: This is NOT cryptographically secure and should only be used
+ * for testing purposes.
+ */
+export class SeededRandomNumberGenerator implements RandomNumberGenerator {
+  private readonly state: Xoshiro256State;
+
+  /**
+   * Creates a new seeded random number generator.
+   *
+   * The seed should be a 256-bit value, represented as an array of 4 64-bit
+   * integers (as bigints). For the output distribution to look random, the seed
+   * should not have any obvious patterns, like all zeroes or all ones.
+   *
+   * This is not cryptographically secure, and should only be used for
+   * testing purposes.
+   *
+   * @param seed - Array of 4 64-bit unsigned integers as bigints
+   */
+  constructor(seed: [bigint, bigint, bigint, bigint]) {
+    this.state = {
+      s0: seed[0] & 0xffffffffffffffffn,
+      s1: seed[1] & 0xffffffffffffffffn,
+      s2: seed[2] & 0xffffffffffffffffn,
+      s3: seed[3] & 0xffffffffffffffffn,
+    };
+  }
+
+  /**
+   * Creates a new seeded random number generator from a seed array.
+   * Convenience method that accepts numbers and converts to bigints.
+   *
+   * @param seed - Array of 4 64-bit unsigned integers
+   */
+  static fromSeed(seed: [bigint, bigint, bigint, bigint]): SeededRandomNumberGenerator {
+    return new SeededRandomNumberGenerator(seed);
+  }
+
+  /**
+   * Returns the next random 64-bit unsigned integer as a bigint.
+   */
+  nextU64(): bigint {
+    return xoshiro256StarStar(this.state);
+  }
+
+  /**
+   * Returns the next random 32-bit unsigned integer.
+   */
+  nextU32(): number {
+    return Number(this.nextU64() & 0xffffffffn) >>> 0;
+  }
+
+  /**
+   * Fills the given Uint8Array with random bytes.
+   *
+   * Note: This implementation matches the Rust behavior exactly -
+   * it uses one nextU64() call per byte (taking only the low byte),
+   * which matches the Swift version's behavior.
+   */
+  fillBytes(dest: Uint8Array): void {
+    for (let i = 0; i < dest.length; i++) {
+      dest[i] = Number(this.nextU64() & 0xffn);
+    }
+  }
+
+  /**
+   * Returns a Uint8Array of random bytes of the given size.
+   *
+   * This might not be the most efficient implementation,
+   * but it works the same as the Swift version.
+   */
+  randomData(size: number): Uint8Array {
+    const data = new Uint8Array(size);
+    for (let i = 0; i < size; i++) {
+      data[i] = Number(this.nextU64() & 0xffn);
+    }
+    return data;
+  }
+
+  /**
+   * Fills the given Uint8Array with random bytes.
+   */
+  fillRandomData(data: Uint8Array): void {
+    this.fillBytes(data);
+  }
+}
+
+/**
+ * The standard test seed used across all Blockchain Commons implementations.
+ */
+export const TEST_SEED: [bigint, bigint, bigint, bigint] = [
+  17295166580085024720n,
+  422929670265678780n,
+  5577237070365765850n,
+  7953171132032326923n,
+];
+
+/**
+ * Creates a seeded random number generator with a fixed seed.
+ * This is useful for reproducible testing across different platforms.
+ */
+export function makeFakeRandomNumberGenerator(): SeededRandomNumberGenerator {
+  return new SeededRandomNumberGenerator(TEST_SEED);
+}
+
+/**
+ * Creates a Uint8Array of random data with a fixed seed.
+ * This is useful for reproducible testing.
+ *
+ * @param size - The number of bytes to generate
+ * @returns A Uint8Array of pseudo-random bytes
+ */
+export function fakeRandomData(size: number): Uint8Array {
+  return makeFakeRandomNumberGenerator().randomData(size);
+}

package/src/widening.ts

@@ -0,0 +1,70 @@
+// The below is so we don't have to use #![feature(bigint_helper_methods)]
+// Ported from bc-rand-rust/src/widening.rs
+
+/**
+ * Wide multiplication result type - returns (low, high) parts.
+ * For a multiplication of two N-bit values, the result is 2N bits
+ * split into two N-bit parts.
+ */
+export type WideMulResult = [bigint, bigint];
+
+/**
+ * Performs wide multiplication for unsigned integers.
+ * Returns (low, high) parts of the full-width result.
+ *
+ * This is equivalent to Rust's widening_mul for unsigned types.
+ */
+export function wideMul(a: bigint, b: bigint, bits: number): WideMulResult {
+  const mask = (1n << BigInt(bits)) - 1n;
+  const wide = (a & mask) * (b & mask);
+  const low = wide & mask;
+  const high = wide >> BigInt(bits);
+  return [low, high];
+}
+
+/**
+ * Wide multiplication for 8-bit unsigned integers.
+ * @param a - First 8-bit value
+ * @param b - Second 8-bit value
+ * @returns Tuple of (low 8 bits, high 8 bits)
+ */
+export function wideMulU8(a: number, b: number): [number, number] {
+  const wide = (a & 0xff) * (b & 0xff);
+  return [wide & 0xff, (wide >> 8) & 0xff];
+}
+
+/**
+ * Wide multiplication for 16-bit unsigned integers.
+ * @param a - First 16-bit value
+ * @param b - Second 16-bit value
+ * @returns Tuple of (low 16 bits, high 16 bits)
+ */
+export function wideMulU16(a: number, b: number): [number, number] {
+  const wide = (a & 0xffff) * (b & 0xffff);
+  return [wide & 0xffff, (wide >>> 16) & 0xffff];
+}
+
+/**
+ * Wide multiplication for 32-bit unsigned integers.
+ * @param a - First 32-bit value
+ * @param b - Second 32-bit value
+ * @returns Tuple of (low 32 bits, high 32 bits) as bigints
+ */
+export function wideMulU32(a: number, b: number): [bigint, bigint] {
+  const aBig = BigInt(a >>> 0);
+  const bBig = BigInt(b >>> 0);
+  const wide = aBig * bBig;
+  return [wide & 0xffffffffn, wide >> 32n];
+}
+
+/**
+ * Wide multiplication for 64-bit unsigned integers.
+ * @param a - First 64-bit value as bigint
+ * @param b - Second 64-bit value as bigint
+ * @returns Tuple of (low 64 bits, high 64 bits) as bigints
+ */
+export function wideMulU64(a: bigint, b: bigint): [bigint, bigint] {
+  const mask64 = 0xffffffffffffffffn;
+  const wide = (a & mask64) * (b & mask64);
+  return [wide & mask64, wide >> 64n];
+}