ox 0.14.28 → 1.0.0-beta.0

package/src/core/internal/address.ts

@@ -0,0 +1,79 @@
+/** @internal */
+export const length = 42
+
+const ZERO = 48 // '0'
+const NINE = 57 // '9'
+const A_UPPER = 65 // 'A'
+const F_UPPER = 70 // 'F'
+const A_LOWER = 97 // 'a'
+const F_LOWER = 102 // 'f'
+const X_LOWER = 120 // 'x'
+
+/**
+ * Combined shape + lowercase classification for an Ethereum address string.
+ * Avoids the regex / try-catch / error-allocation overhead in the hot path
+ * and avoids a second pass for callers that need both pieces of metadata
+ * (e.g. strict validation).
+ *
+ * - `0` = invalid shape (not `0x[0-9a-fA-F]{40}`)
+ * - `1` = valid shape, all-lowercase hex body (no checksum to verify)
+ * - `2` = valid shape, contains at least one `A-F` upper char
+ *
+ * @internal
+ */
+export function classify(value: string): 0 | 1 | 2 {
+  if (typeof value !== 'string' || value.length !== length) return 0
+  if (value.charCodeAt(0) !== ZERO || value.charCodeAt(1) !== X_LOWER) return 0
+  let hasUpper = false
+  for (let i = 2; i < length; i++) {
+    const code = value.charCodeAt(i)
+    if (code >= ZERO && code <= NINE) continue
+    if (code >= A_LOWER && code <= F_LOWER) continue
+    if (code >= A_UPPER && code <= F_UPPER) {
+      hasUpper = true
+      continue
+    }
+    return 0
+  }
+  return hasUpper ? 2 : 1
+}
+
+/**
+ * Manual ASCII shape check for an Ethereum address string. Returns `true`
+ * when `value` has the shape `0x[0-9a-fA-F]{40}`. Does not verify checksum
+ * casing.
+ *
+ * @internal
+ */
+export function hasShape(value: string): boolean {
+  return classify(value) !== 0
+}
+
+/**
+ * Returns the canonical lowercase form of a shape-validated address, or the
+ * input unchanged when it is already all-lowercase. Pre-condition: caller has
+ * already verified the string is shape-valid via {@link hasShape} or
+ * {@link classify}.
+ *
+ * @internal
+ */
+export function lowercase(value: string): string {
+  let hasUpper = false
+  for (let i = 2; i < length; i++) {
+    const code = value.charCodeAt(i)
+    if (code >= A_UPPER && code <= F_UPPER) {
+      hasUpper = true
+      break
+    }
+  }
+  if (!hasUpper) return value
+
+  const out = new Uint16Array(length)
+  out[0] = ZERO
+  out[1] = X_LOWER
+  for (let i = 2; i < length; i++) {
+    const code = value.charCodeAt(i)
+    out[i] = code >= A_UPPER && code <= F_UPPER ? code + 32 : code
+  }
+  return String.fromCharCode.apply(null, out as unknown as number[])
+}

package/src/core/internal/base58.ts

@@ -0,0 +1,102 @@
+import * as Bytes from '../Bytes.js'
+import type * as Errors from '../Errors.js'
+import * as Hex from '../Hex.js'
+
+/** @internal */
+export const integerToAlphabet =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+/** @internal */
+export const alphabetToInteger = /* __PURE__ */ Object.freeze<
+  Record<string, bigint>
+>({
+  1: 0n,
+  2: 1n,
+  3: 2n,
+  4: 3n,
+  5: 4n,
+  6: 5n,
+  7: 6n,
+  8: 7n,
+  9: 8n,
+  A: 9n,
+  B: 10n,
+  C: 11n,
+  D: 12n,
+  E: 13n,
+  F: 14n,
+  G: 15n,
+  H: 16n,
+  J: 17n,
+  K: 18n,
+  L: 19n,
+  M: 20n,
+  N: 21n,
+  P: 22n,
+  Q: 23n,
+  R: 24n,
+  S: 25n,
+  T: 26n,
+  U: 27n,
+  V: 28n,
+  W: 29n,
+  X: 30n,
+  Y: 31n,
+  Z: 32n,
+  a: 33n,
+  b: 34n,
+  c: 35n,
+  d: 36n,
+  e: 37n,
+  f: 38n,
+  g: 39n,
+  h: 40n,
+  i: 41n,
+  j: 42n,
+  k: 43n,
+  m: 44n,
+  n: 45n,
+  o: 46n,
+  p: 47n,
+  q: 48n,
+  r: 49n,
+  s: 50n,
+  t: 51n,
+  u: 52n,
+  v: 53n,
+  w: 54n,
+  x: 55n,
+  y: 56n,
+  z: 57n,
+})
+
+/** @internal */
+export function from(value: Hex.Hex | Bytes.Bytes) {
+  const bytes = Bytes.from(value)
+
+  if (bytes.length === 0) return ''
+
+  let pad = 0
+  while (pad < bytes.length && bytes[pad] === 0) pad++
+
+  let integer =
+    value instanceof Uint8Array
+      ? BigInt(Hex.fromBytes(bytes))
+      : BigInt(value as string)
+
+  let result = ''
+  while (integer > 0n) {
+    const remainder = Number(integer % 58n)
+    integer = integer / 58n
+    result = integerToAlphabet[remainder] + result
+  }
+
+  return '1'.repeat(pad) + result
+}
+
+/** @internal */
+export declare namespace from {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/** @internal */

package/src/core/internal/bytes.ts

@@ -0,0 +1,139 @@
+import * as Bytes from '../Bytes.js'
+import type * as Errors from '../Errors.js'
+
+/** @internal */
+export function assertSize(bytes: Bytes.Bytes, size_: number): void {
+  if (Bytes.size(bytes) > size_)
+    throw new Bytes.SizeOverflowError({
+      givenSize: Bytes.size(bytes),
+      maxSize: size_,
+    })
+}
+
+/** @internal */
+export declare namespace assertSize {
+  type ErrorType =
+    | Bytes.size.ErrorType
+    | Bytes.SizeOverflowError
+    | Errors.GlobalErrorType
+}
+
+/** @internal */
+export function assertStartOffset(value: Bytes.Bytes, start?: number) {
+  if (typeof start === 'number' && start > 0 && start > Bytes.size(value) - 1)
+    throw new Bytes.SliceOffsetOutOfBoundsError({
+      offset: start,
+      position: 'start',
+      size: Bytes.size(value),
+    })
+}
+
+export declare namespace assertStartOffset {
+  export type ErrorType =
+    | Bytes.SliceOffsetOutOfBoundsError
+    | Bytes.size.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/** @internal */
+export function assertEndOffset(
+  value: Bytes.Bytes,
+  start?: number,
+  end?: number,
+) {
+  if (
+    typeof start === 'number' &&
+    typeof end === 'number' &&
+    Bytes.size(value) !== end - start
+  ) {
+    throw new Bytes.SliceOffsetOutOfBoundsError({
+      offset: end,
+      position: 'end',
+      size: Bytes.size(value),
+    })
+  }
+}
+
+/** @internal */
+export declare namespace assertEndOffset {
+  type ErrorType =
+    | Bytes.SliceOffsetOutOfBoundsError
+    | Bytes.size.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/** @internal */
+export const charCodeMap = {
+  zero: 48,
+  nine: 57,
+  A: 65,
+  F: 70,
+  a: 97,
+  f: 102,
+} as const
+
+/** @internal */
+export function charCodeToBase16(char: number) {
+  if (char >= charCodeMap.zero && char <= charCodeMap.nine)
+    return char - charCodeMap.zero
+  if (char >= charCodeMap.A && char <= charCodeMap.F)
+    return char - (charCodeMap.A - 10)
+  if (char >= charCodeMap.a && char <= charCodeMap.f)
+    return char - (charCodeMap.a - 10)
+  return undefined
+}
+
+/** @internal */
+export function pad(bytes: Bytes.Bytes, options: pad.Options = {}) {
+  const { dir, size = 32 } = options
+  if (size === 0) return bytes
+  if (bytes.length > size)
+    throw new Bytes.SizeExceedsPaddingSizeError({
+      size: bytes.length,
+      targetSize: size,
+      type: 'Bytes',
+    })
+  const paddedBytes = new Uint8Array(size)
+  paddedBytes.set(bytes, dir === 'right' ? 0 : size - bytes.length)
+  return paddedBytes
+}
+
+/** @internal */
+export declare namespace pad {
+  type Options = {
+    dir?: 'left' | 'right' | undefined
+    size?: number | undefined
+  }
+
+  type ReturnType = Bytes.Bytes
+
+  type ErrorType = Bytes.SizeExceedsPaddingSizeError | Errors.GlobalErrorType
+}
+
+/** @internal */
+export function trim(
+  value: Bytes.Bytes,
+  options: trim.Options = {},
+): trim.ReturnType {
+  const { dir = 'left' } = options
+
+  let start = 0
+  let end = value.length
+  if (dir === 'left') while (start < end && value[start] === 0) start++
+  else while (end > start && value[end - 1] === 0) end--
+
+  return (
+    start === 0 && end === value.length ? value : value.slice(start, end)
+  ) as trim.ReturnType
+}
+
+/** @internal */
+export declare namespace trim {
+  type Options = {
+    dir?: 'left' | 'right' | undefined
+  }
+
+  type ReturnType = Bytes.Bytes
+
+  type ErrorType = Errors.GlobalErrorType
+}

package/src/core/internal/codec/bech32-base32.ts

@@ -0,0 +1,64 @@
+import * as Errors from '../../Errors.js'
+
+/**
+ * Bech32/BIP-173 base32 alphabet. Shared between `Base32` and `Bech32m`.
+ *
+ * @internal
+ */
+export const alphabet = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
+
+/** @internal */
+export const alphabetMap = /*#__PURE__*/ (() => {
+  const map: Record<string, number> = {}
+  for (let i = 0; i < alphabet.length; i++) map[alphabet[i]!] = i
+  return map
+})()
+
+/**
+ * Repacks bits between two power-of-two bases (`fromBits` -> `toBits`).
+ *
+ * When `pad` is `true`, leftover bits are zero-padded to a final symbol. When
+ * `pad` is `false`, leftover bits must be zero (canonical form per BIP-173)
+ * and a non-zero remainder throws `InvalidPaddingError`.
+ *
+ * @internal
+ */
+export function convertBits(
+  data: Iterable<number>,
+  fromBits: number,
+  toBits: number,
+  pad: boolean,
+): number[] {
+  let acc = 0
+  let bits = 0
+  const maxv = (1 << toBits) - 1
+  const ret: number[] = []
+  for (const value of data) {
+    acc = (acc << fromBits) | value
+    bits += fromBits
+    while (bits >= toBits) {
+      bits -= toBits
+      ret.push((acc >> bits) & maxv)
+    }
+  }
+  if (pad) {
+    if (bits > 0) ret.push((acc << (toBits - bits)) & maxv)
+  } else if (bits >= fromBits || (acc << (toBits - bits)) & maxv) {
+    throw new InvalidPaddingError()
+  }
+  return ret
+}
+
+/** Thrown when leftover bits during base32 conversion are non-zero. */
+export class InvalidPaddingError extends Errors.BaseError {
+  override readonly name = 'Bech32m.InvalidPaddingError'
+
+  constructor() {
+    super('Invalid padding in base32 data.')
+  }
+}
+
+/** @internal */
+export declare namespace convertBits {
+  type ErrorType = InvalidPaddingError | Errors.GlobalErrorType
+}

package/src/core/internal/codec/errors.ts

@@ -0,0 +1,30 @@
+import * as Errors from '../../Errors.js'
+
+/**
+ * Shared `SizeOverflowError` class for `Bytes` and `Hex`. The `name` is
+ * passed at construction time so a single class identity backs both
+ * `Bytes.SizeOverflowError` and `Hex.SizeOverflowError` re-exports without
+ * forcing `Bytes` and `Hex` to import each other at runtime.
+ *
+ * @internal
+ */
+export class BytesSizeOverflowError extends Errors.BaseError {
+  override readonly name = 'Bytes.SizeOverflowError'
+
+  constructor({ givenSize, maxSize }: { givenSize: number; maxSize: number }) {
+    super(
+      `Size cannot exceed \`${maxSize}\` bytes. Given size: \`${givenSize}\` bytes.`,
+    )
+  }
+}
+
+/** @internal */
+export class HexSizeOverflowError extends Errors.BaseError {
+  override readonly name = 'Hex.SizeOverflowError'
+
+  constructor({ givenSize, maxSize }: { givenSize: number; maxSize: number }) {
+    super(
+      `Size cannot exceed \`${maxSize}\` bytes. Given size: \`${givenSize}\` bytes.`,
+    )
+  }
+}

package/src/core/internal/codec/hex.ts

@@ -0,0 +1,145 @@
+import * as Errors from '../../Errors.js'
+
+/** @internal */
+export type Hex = `0x${string}`
+
+/** @internal */
+const hexes = /*#__PURE__*/ Array.from({ length: 256 }, (_v, i) =>
+  i.toString(16).padStart(2, '0'),
+)
+
+// Char-code → 4-bit nibble lookup table. Sentinel `0xff` = invalid.
+const nibbleTable = /*#__PURE__*/ (() => {
+  const table = new Uint8Array(256).fill(0xff)
+  for (let i = 0; i < 10; i++) table[48 + i] = i // '0'-'9'
+  for (let i = 0; i < 6; i++) {
+    table[65 + i] = 10 + i // 'A'-'F'
+    table[97 + i] = 10 + i // 'a'-'f'
+  }
+  return table
+})()
+
+// Phase 2 native fast-path detection: `Uint8Array.prototype.toHex` lands in
+// Node 22+, Safari 18+, Firefox 133+. Falls back to `Buffer` on Node, then to
+// the JS loop.
+const _Buffer: typeof globalThis.Buffer | undefined = (
+  globalThis as typeof globalThis & { Buffer?: typeof globalThis.Buffer }
+).Buffer
+const nativeToHex: ((this: Uint8Array) => string) | undefined = (
+  Uint8Array.prototype as Uint8Array & { toHex?: () => string }
+).toHex
+const nativeFromHex: ((value: string) => Uint8Array) | undefined = (
+  Uint8Array as typeof Uint8Array & { fromHex?: (value: string) => Uint8Array }
+).fromHex
+
+/**
+ * Encodes a `Uint8Array` into a `0x`-prefixed lowercase hex string. Uses the
+ * native `Uint8Array.prototype.toHex` (Node 22+, Safari 18+, Firefox 133+) or
+ * Node's `Buffer` when available; otherwise a tight JS loop.
+ *
+ * @internal
+ */
+export function bytesToHex(value: Uint8Array): Hex {
+  if (nativeToHex) return `0x${nativeToHex.call(value)}` as Hex
+  if (_Buffer)
+    return `0x${_Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('hex')}` as Hex
+  const length = value.length
+  const parts = Array.from<string>({ length })
+  for (let i = 0; i < length; i++) parts[i] = hexes[value[i]!]!
+  return `0x${parts.join('')}` as Hex
+}
+
+/**
+ * Strictly decodes a `0x`-prefixed even-length hex string into a `Uint8Array`.
+ * Uses the native `Uint8Array.fromHex` (Node 22+, Safari 18+, Firefox 133+) or
+ * Node's `Buffer` when available; otherwise a tight JS loop.
+ *
+ * @internal
+ */
+export function hexToBytes(value: string): Uint8Array {
+  if (
+    typeof value !== 'string' ||
+    value.length < 2 ||
+    value.charCodeAt(0) !== 48 /* '0' */ ||
+    value.charCodeAt(1) !== 120 /* 'x' */
+  )
+    throw new InvalidHexValueError(value)
+  const body = value.length === 2 ? '' : (value as string).slice(2)
+  if ((body.length & 1) !== 0) throw new InvalidLengthError(value as Hex)
+
+  if (nativeFromHex) {
+    try {
+      return nativeFromHex(body)
+    } catch {
+      throw new InvalidHexValueError(value)
+    }
+  }
+  if (_Buffer && body.length > 0) {
+    // Buffer.from with 'hex' silently truncates on invalid chars; verify
+    // byteLength matches expectations to detect malformed input.
+    const expected = body.length >> 1
+    const buf = _Buffer.from(body, 'hex')
+    if (buf.length !== expected) throw new InvalidHexValueError(value)
+    // Copy out of Buffer pool: callers may rely on `.buffer` being a
+    // standalone ArrayBuffer (e.g. WebAuthn attestationObject round-trips).
+    const out = new Uint8Array(buf.byteLength)
+    out.set(buf)
+    return out
+  }
+
+  const length = body.length >> 1
+  const out = new Uint8Array(length)
+  for (let i = 0, j = 0; i < length; i++) {
+    const hi = nibbleTable[body.charCodeAt(j++)]!
+    const lo = nibbleTable[body.charCodeAt(j++)]!
+    if (hi === 0xff || lo === 0xff) throw new InvalidHexValueError(value)
+    out[i] = (hi << 4) | lo
+  }
+  return out
+}
+
+/** @internal */
+export function charCodeToBase16(char: number): number | undefined {
+  const v = nibbleTable[char]!
+  return v === 0xff ? undefined : v
+}
+
+/** Thrown when a value is not a valid `0x`-prefixed hex string. */
+export class InvalidHexValueError extends Errors.BaseError {
+  override readonly name = 'Hex.InvalidHexValueError'
+
+  constructor(value: unknown) {
+    super(`Value \`${value}\` is an invalid hex value.`, {
+      metaMessages: [
+        'Hex values must start with `"0x"` and contain only hexadecimal characters (0-9, a-f, A-F).',
+      ],
+    })
+  }
+}
+
+/** Thrown when a hex string has an odd nibble count. */
+export class InvalidLengthError extends Errors.BaseError {
+  override readonly name = 'Hex.InvalidLengthError'
+
+  constructor(value: Hex) {
+    super(
+      `Hex value \`"${value}"\` is an odd length (${value.length - 2} nibbles).`,
+      {
+        metaMessages: ['It must be an even length.'],
+      },
+    )
+  }
+}
+
+/** @internal */
+export declare namespace bytesToHex {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/** @internal */
+export declare namespace hexToBytes {
+  type ErrorType =
+    | InvalidHexValueError
+    | InvalidLengthError
+    | Errors.GlobalErrorType
+}