@stll/stdnum 2.0.0 → 2.1.0

package/src/_checksums/keccak.ts

@@ -0,0 +1,145 @@
+const MASK_64 = (1n << 64n) - 1n;
+
+const ROUND_CONSTANTS = [
+  0x0000000000000001n,
+  0x0000000000008082n,
+  0x800000000000808an,
+  0x8000000080008000n,
+  0x000000000000808bn,
+  0x0000000080000001n,
+  0x8000000080008081n,
+  0x8000000000008009n,
+  0x000000000000008an,
+  0x0000000000000088n,
+  0x0000000080008009n,
+  0x000000008000000an,
+  0x000000008000808bn,
+  0x800000000000008bn,
+  0x8000000000008089n,
+  0x8000000000008003n,
+  0x8000000000008002n,
+  0x8000000000000080n,
+  0x000000000000800an,
+  0x800000008000000an,
+  0x8000000080008081n,
+  0x8000000000008080n,
+  0x0000000080000001n,
+  0x8000000080008008n,
+] as const;
+
+const ROTATION_OFFSETS = [
+  0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39,
+  41, 45, 15, 21, 8, 18, 2, 61, 56, 14,
+] as const;
+
+const RATE_BYTES = 136;
+
+const rotl64 = (value: bigint, shift: number): bigint => {
+  if (shift === 0) return value & MASK_64;
+  const bigShift = BigInt(shift);
+  return (
+    ((value << bigShift) | (value >> (64n - bigShift))) &
+    MASK_64
+  );
+};
+
+const keccakF1600 = (state: bigint[]): void => {
+  const c = Array.from({ length: 5 }, () => 0n);
+  const d = Array.from({ length: 5 }, () => 0n);
+  const b = Array.from({ length: 25 }, () => 0n);
+
+  for (const roundConstant of ROUND_CONSTANTS) {
+    for (let x = 0; x < 5; x += 1) {
+      c[x] =
+        (state[x] ?? 0n) ^
+        (state[x + 5] ?? 0n) ^
+        (state[x + 10] ?? 0n) ^
+        (state[x + 15] ?? 0n) ^
+        (state[x + 20] ?? 0n);
+    }
+
+    for (let x = 0; x < 5; x += 1) {
+      d[x] =
+        (c[(x + 4) % 5] ?? 0n) ^
+        rotl64(c[(x + 1) % 5] ?? 0n, 1);
+    }
+
+    for (let y = 0; y < 5; y += 1) {
+      for (let x = 0; x < 5; x += 1) {
+        const index = x + 5 * y;
+        state[index] =
+          ((state[index] ?? 0n) ^ (d[x] ?? 0n)) & MASK_64;
+      }
+    }
+
+    for (let y = 0; y < 5; y += 1) {
+      for (let x = 0; x < 5; x += 1) {
+        const sourceIndex = x + 5 * y;
+        const targetIndex = y + 5 * ((2 * x + 3 * y) % 5);
+        b[targetIndex] = rotl64(
+          state[sourceIndex] ?? 0n,
+          ROTATION_OFFSETS[sourceIndex] ?? 0,
+        );
+      }
+    }
+
+    for (let y = 0; y < 5; y += 1) {
+      for (let x = 0; x < 5; x += 1) {
+        const index = x + 5 * y;
+        state[index] =
+          ((b[index] ?? 0n) ^
+            (~(b[((x + 1) % 5) + 5 * y] ?? 0n) &
+              (b[((x + 2) % 5) + 5 * y] ?? 0n))) &
+          MASK_64;
+      }
+    }
+
+    state[0] = ((state[0] ?? 0n) ^ roundConstant) & MASK_64;
+  }
+};
+
+export const keccak256 = (
+  bytes: Uint8Array,
+): Uint8Array => {
+  const state = Array.from({ length: 25 }, () => 0n);
+  let offset = 0;
+
+  while (offset + RATE_BYTES <= bytes.length) {
+    for (let i = 0; i < RATE_BYTES; i += 1) {
+      const lane = Math.floor(i / 8);
+      const shift = BigInt((i % 8) * 8);
+      state[lane] =
+        ((state[lane] ?? 0n) ^
+          (BigInt(bytes[offset + i] ?? 0) << shift)) &
+        MASK_64;
+    }
+    keccakF1600(state);
+    offset += RATE_BYTES;
+  }
+
+  const block = new Uint8Array(RATE_BYTES);
+  block.set(bytes.slice(offset));
+  block[bytes.length - offset] = 0x01;
+  block[RATE_BYTES - 1] =
+    (block[RATE_BYTES - 1] ?? 0) ^ 0x80;
+
+  for (let i = 0; i < RATE_BYTES; i += 1) {
+    const lane = Math.floor(i / 8);
+    const shift = BigInt((i % 8) * 8);
+    state[lane] =
+      ((state[lane] ?? 0n) ^
+        (BigInt(block[i] ?? 0) << shift)) &
+      MASK_64;
+  }
+  keccakF1600(state);
+
+  const digest = new Uint8Array(32);
+  for (let i = 0; i < digest.length; i += 1) {
+    const lane = Math.floor(i / 8);
+    const shift = BigInt((i % 8) * 8);
+    digest[i] = Number(
+      ((state[lane] ?? 0n) >> shift) & 0xffn,
+    );
+  }
+  return digest;
+};

package/src/_checksums/sha256.ts

@@ -0,0 +1,125 @@
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+  0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+  0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+  0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (value: number, bits: number): number =>
+  (value >>> bits) | (value << (32 - bits));
+
+export const sha256 = (bytes: Uint8Array): Uint8Array => {
+  const bitLength = bytes.length * 8;
+  const messageLength = bytes.length + 1;
+  const paddingLength =
+    (64 - ((messageLength + 8) % 64)) % 64;
+  const totalLength = messageLength + paddingLength + 8;
+  const message = new Uint8Array(totalLength);
+  message.set(bytes);
+  message[bytes.length] = 0x80;
+
+  const high = Math.floor(bitLength / 0x1_0000_0000);
+  const low = bitLength >>> 0;
+  message[totalLength - 8] = high >>> 24;
+  message[totalLength - 7] = high >>> 16;
+  message[totalLength - 6] = high >>> 8;
+  message[totalLength - 5] = high;
+  message[totalLength - 4] = low >>> 24;
+  message[totalLength - 3] = low >>> 16;
+  message[totalLength - 2] = low >>> 8;
+  message[totalLength - 1] = low;
+
+  let h0 = 0x6a09e667;
+  let h1 = 0xbb67ae85;
+  let h2 = 0x3c6ef372;
+  let h3 = 0xa54ff53a;
+  let h4 = 0x510e527f;
+  let h5 = 0x9b05688c;
+  let h6 = 0x1f83d9ab;
+  let h7 = 0x5be0cd19;
+
+  const words = new Uint32Array(64);
+
+  for (let offset = 0; offset < totalLength; offset += 64) {
+    for (let i = 0; i < 16; i += 1) {
+      const j = offset + i * 4;
+      words[i] =
+        ((message[j] ?? 0) << 24) |
+        ((message[j + 1] ?? 0) << 16) |
+        ((message[j + 2] ?? 0) << 8) |
+        (message[j + 3] ?? 0);
+    }
+
+    for (let i = 16; i < 64; i += 1) {
+      const w2 = words[i - 2] ?? 0;
+      const w7 = words[i - 7] ?? 0;
+      const w15 = words[i - 15] ?? 0;
+      const w16 = words[i - 16] ?? 0;
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+      words[i] = (w16 + s0 + w7 + s1) >>> 0;
+    }
+
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 =
+        (h + s1 + ch + (K[i] ?? 0) + (words[i] ?? 0)) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + maj) >>> 0;
+
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+
+    h0 = (h0 + a) >>> 0;
+    h1 = (h1 + b) >>> 0;
+    h2 = (h2 + c) >>> 0;
+    h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0;
+    h5 = (h5 + f) >>> 0;
+    h6 = (h6 + g) >>> 0;
+    h7 = (h7 + h) >>> 0;
+  }
+
+  const digest = new Uint8Array(32);
+  const hash = [h0, h1, h2, h3, h4, h5, h6, h7];
+  for (let i = 0; i < hash.length; i += 1) {
+    const value = hash[i] ?? 0;
+    const j = i * 4;
+    digest[j] = value >>> 24;
+    digest[j + 1] = value >>> 16;
+    digest[j + 2] = value >>> 8;
+    digest[j + 3] = value;
+  }
+
+  return digest;
+};

package/src/crypto/btcbase58.ts

@@ -0,0 +1,144 @@
+/**
+ * Bitcoin Base58Check address.
+ *
+ * Validates legacy mainnet P2PKH and P2SH Bitcoin
+ * addresses, including the double-SHA-256 checksum.
+ */
+
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+
+import { sha256 } from "#checksums/sha256";
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+const BASE58_ALPHABET =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+const MIN_LENGTH = 26;
+const MAX_LENGTH = 35;
+const DECODED_ADDRESS_LENGTH = 25;
+const CHECKSUM_LENGTH = 4;
+const MAINNET_P2PKH_VERSION = 0x00;
+const MAINNET_P2SH_VERSION = 0x05;
+
+const compact = (value: string): string =>
+  clean(value, " ");
+
+const decodeBase58 = (value: string): Uint8Array | null => {
+  let decoded = 0n;
+  for (const ch of value) {
+    const digit = BASE58_ALPHABET.indexOf(ch);
+    if (digit === -1) return null;
+    decoded = decoded * 58n + BigInt(digit);
+  }
+
+  const bytes: number[] = [];
+  while (decoded > 0n) {
+    bytes.push(Number(decoded & 0xffn));
+    decoded >>= 8n;
+  }
+  bytes.reverse();
+
+  let leadingZeros = 0;
+  while (value.charAt(leadingZeros) === "1") {
+    leadingZeros += 1;
+  }
+
+  const result = new Uint8Array(
+    leadingZeros + bytes.length,
+  );
+  result.set(bytes, leadingZeros);
+  return result;
+};
+
+const hasValidChecksum = (decoded: Uint8Array): boolean => {
+  if (decoded.length <= CHECKSUM_LENGTH) return false;
+
+  const payload = decoded.slice(0, -CHECKSUM_LENGTH);
+  const checksum = decoded.slice(-CHECKSUM_LENGTH);
+  const digest = sha256(sha256(payload));
+
+  for (let i = 0; i < CHECKSUM_LENGTH; i += 1) {
+    if (checksum[i] !== digest[i]) return false;
+  }
+  return true;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < MIN_LENGTH || v.length > MAX_LENGTH) {
+    return err(
+      "INVALID_LENGTH",
+      "Bitcoin Base58Check address must be 26-35 characters",
+    );
+  }
+  if (!/^[13]/.test(v)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Bitcoin Base58Check address must start with 1 or 3",
+    );
+  }
+
+  const decoded = decodeBase58(v);
+  if (decoded === null) {
+    return err(
+      "INVALID_FORMAT",
+      "Bitcoin Base58Check address contains invalid characters",
+    );
+  }
+  if (decoded.length !== DECODED_ADDRESS_LENGTH) {
+    return err(
+      "INVALID_LENGTH",
+      "Bitcoin Base58Check address decoded payload must be 25 bytes",
+    );
+  }
+
+  const version = decoded[0];
+  if (
+    version !== MAINNET_P2PKH_VERSION &&
+    version !== MAINNET_P2SH_VERSION
+  ) {
+    return err(
+      "INVALID_COMPONENT",
+      "Bitcoin Base58Check address has an unsupported version",
+    );
+  }
+
+  if (!hasValidChecksum(decoded)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Bitcoin Base58Check address fails checksum validation",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+const btcBase58: GlobalValidator = {
+  scope: "global",
+  name: "Bitcoin Base58Check Address",
+  localName: "Bitcoin Base58Check Address",
+  abbreviation: "BTC",
+  aliases: [
+    "Bitcoin address",
+    "Bitcoin legacy address",
+    "Base58Check address",
+  ] as const,
+  candidatePattern: "[13][1-9A-HJ-NP-Za-km-z]{25,34}",
+  entityType: "any",
+  examples: [
+    "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
+    "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
+  ] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default btcBase58;
+export { compact, decodeBase58, format, validate };

package/src/crypto/btcbech32.ts

@@ -0,0 +1,210 @@
+/**
+ * Bitcoin Bech32/Bech32m address.
+ *
+ * Validates mainnet SegWit addresses with the
+ * Bech32 checksum for v0 and Bech32m for v1+.
+ */
+
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const GENERATORS = [
+  0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd,
+  0x2a1462b3,
+] as const;
+const BECH32_CONST = 1;
+const BECH32M_CONST = 0x2bc830a3;
+const CHECKSUM_LENGTH = 6;
+const MIN_DATA_LENGTH = 11;
+const MAX_DATA_LENGTH = 71;
+const BC_HRP_EXPANSION = [3, 3, 0, 2, 3] as const;
+
+const compact = (value: string): string =>
+  clean(value, " ").toLowerCase();
+
+const polymod = (values: readonly number[]): number => {
+  let chk = 1;
+  for (const value of values) {
+    const top = chk >>> 25;
+    chk = (((chk & 0x1ffffff) << 5) ^ value) >>> 0;
+    for (let i = 0; i < GENERATORS.length; i += 1) {
+      const generator = GENERATORS[i] ?? 0;
+      if (((top >>> i) & 1) === 1) {
+        chk = (chk ^ generator) >>> 0;
+      }
+    }
+  }
+  return chk >>> 0;
+};
+
+const dataValues = (data: string): number[] | null => {
+  const values: number[] = [];
+  for (const ch of data) {
+    const value = CHARSET.indexOf(ch);
+    if (value === -1) return null;
+    values.push(value);
+  }
+  return values;
+};
+
+const convertBits = (
+  values: readonly number[],
+  fromBits: number,
+  toBits: number,
+): number[] | null => {
+  let accumulator = 0;
+  let bits = 0;
+  const maxValue = (1 << toBits) - 1;
+  const result: number[] = [];
+
+  for (const value of values) {
+    if (value < 0 || value >>> fromBits !== 0) return null;
+    accumulator = (accumulator << fromBits) | value;
+    bits += fromBits;
+    while (bits >= toBits) {
+      bits -= toBits;
+      result.push((accumulator >>> bits) & maxValue);
+    }
+  }
+
+  if (bits >= fromBits) return null;
+  if (((accumulator << (toBits - bits)) & maxValue) !== 0) {
+    return null;
+  }
+
+  return result;
+};
+
+type Bech32Validation =
+  | { valid: true }
+  | {
+      valid: false;
+      code: "format" | "checksum" | "component";
+    };
+
+const validateBech32 = (
+  rawValue: string,
+): Bech32Validation => {
+  const hasLower = /[a-z]/.test(rawValue);
+  const hasUpper = /[A-Z]/.test(rawValue);
+  if (hasLower && hasUpper)
+    return { valid: false, code: "format" };
+
+  const v = rawValue.toLowerCase();
+  if (!v.startsWith("bc1"))
+    return { valid: false, code: "component" };
+
+  const data = v.slice(3);
+  if (
+    data.length < MIN_DATA_LENGTH ||
+    data.length > MAX_DATA_LENGTH
+  ) {
+    return { valid: false, code: "format" };
+  }
+
+  const values = dataValues(data);
+  if (values === null)
+    return { valid: false, code: "format" };
+
+  const expanded: number[] = Array.from(BC_HRP_EXPANSION);
+  for (const value of values) {
+    expanded.push(value);
+  }
+  const check = polymod(expanded);
+
+  const version = values[0];
+  if (version === undefined || version > 16) {
+    return { valid: false, code: "component" };
+  }
+
+  if (version === 0 && check !== BECH32_CONST) {
+    return { valid: false, code: "checksum" };
+  }
+  if (version > 0 && check !== BECH32M_CONST) {
+    return { valid: false, code: "checksum" };
+  }
+
+  const programValues = values.slice(1, -CHECKSUM_LENGTH);
+  const program = convertBits(programValues, 5, 8);
+  if (
+    program === null ||
+    program.length < 2 ||
+    program.length > 40
+  ) {
+    return { valid: false, code: "component" };
+  }
+
+  if (
+    version === 0 &&
+    program.length !== 20 &&
+    program.length !== 32
+  ) {
+    return { valid: false, code: "component" };
+  }
+
+  return { valid: true };
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  const result = validateBech32(clean(value, " "));
+  if (result.valid) return { valid: true, compact: v };
+
+  if (result.code === "component") {
+    return err(
+      "INVALID_COMPONENT",
+      "Bitcoin Bech32 address has an unsupported component",
+    );
+  }
+  if (result.code === "checksum") {
+    return err(
+      "INVALID_CHECKSUM",
+      "Bitcoin Bech32 address fails checksum validation",
+    );
+  }
+  return err(
+    "INVALID_FORMAT",
+    "Bitcoin Bech32 address has an invalid format",
+  );
+};
+
+const format = (value: string): string => compact(value);
+
+const btcBech32: GlobalValidator = {
+  scope: "global",
+  name: "Bitcoin Bech32 Address",
+  localName: "Bitcoin Bech32 Address",
+  abbreviation: "BTC",
+  aliases: [
+    "Bitcoin address",
+    "Bitcoin SegWit address",
+    "Bech32 address",
+    "Bech32m address",
+  ] as const,
+  candidatePattern:
+    "(?:bc1[ac-hj-np-z02-9]{11,71}|BC1[AC-HJ-NP-Z02-9]{11,71})",
+  entityType: "any",
+  examples: [
+    "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
+    "bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3",
+  ] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default btcBech32;
+export {
+  compact,
+  convertBits,
+  format,
+  polymod,
+  validate,
+  validateBech32,
+};