ox 0.13.2 → 0.14.0

package/core/Bech32m.ts

@@ -0,0 +1,263 @@
+import type * as Errors from './Errors.js'
+import { BaseError } from './Errors.js'
+
+/**
+ * Encodes data bytes with a human-readable part (HRP) into a bech32m string (BIP-350).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const encoded = Bech32m.encode('tempo', new Uint8Array(20))
+ * // @log: 'tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwa7xtm'
+ * ```
+ *
+ * @param hrp - The human-readable part (e.g. `"tempo"`, `"tempoz"`).
+ * @param data - The data bytes to encode.
+ * @returns The bech32m-encoded string.
+ */
+export function encode(
+  hrp: string,
+  data: Uint8Array,
+  options: encode.Options = {},
+): string {
+  const { limit = 90 } = options
+
+  hrp = hrp.toLowerCase()
+
+  if (hrp.length === 0) throw new InvalidHrpError()
+  for (let i = 0; i < hrp.length; i++) {
+    const c = hrp.charCodeAt(i)
+    if (c < 33 || c > 126) throw new InvalidHrpError()
+  }
+
+  const data5 = convertBits(data, 8, 5, true)
+
+  if (hrp.length + 1 + data5.length + 6 > limit)
+    throw new ExceedsLengthError({ limit })
+
+  const checksum = createChecksum(hrp, data5)
+  let result = hrp + '1'
+  for (const d of data5.concat(checksum)) result += alphabet[d]
+  return result
+}
+
+export declare namespace encode {
+  type Options = {
+    /** Maximum length of the encoded string. @default 90 */
+    limit?: number | undefined
+  }
+
+  type ErrorType = InvalidHrpError | ExceedsLengthError | Errors.GlobalErrorType
+}
+
+/**
+ * Decodes a bech32m string (BIP-350) into a human-readable part and data bytes.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const { hrp, data } = Bech32m.decode('tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwa7xtm')
+ * // @log: { hrp: 'tempo', data: Uint8Array(20) }
+ * ```
+ *
+ * @param str - The bech32m-encoded string to decode.
+ * @returns The decoded HRP and data bytes.
+ */
+export function decode(
+  str: string,
+  options: decode.Options = {},
+): decode.ReturnType {
+  const { limit = 90 } = options
+
+  if (str.length > limit) throw new ExceedsLengthError({ limit })
+
+  if (str !== str.toLowerCase() && str !== str.toUpperCase())
+    throw new MixedCaseError()
+
+  const lower = str.toLowerCase()
+  const pos = lower.lastIndexOf('1')
+  if (pos === -1) throw new NoSeparatorError()
+  if (pos === 0) throw new InvalidHrpError()
+  if (pos + 7 > lower.length) throw new InvalidChecksumError()
+
+  const hrp = lower.slice(0, pos)
+  for (let i = 0; i < hrp.length; i++) {
+    const c = hrp.charCodeAt(i)
+    if (c < 33 || c > 126) throw new InvalidHrpError()
+  }
+
+  const dataChars = lower.slice(pos + 1)
+
+  const data5: number[] = []
+  for (const c of dataChars) {
+    const v = alphabetMap[c]
+    if (v === undefined) throw new InvalidCharacterError({ character: c })
+    data5.push(v)
+  }
+
+  if (!verifyChecksum(hrp, data5)) throw new InvalidChecksumError()
+
+  const data8 = convertBits(data5.slice(0, -6), 5, 8, false)
+  return { hrp, data: new Uint8Array(data8) }
+}
+
+export declare namespace decode {
+  type Options = {
+    /** Maximum length of the encoded string. @default 90 */
+    limit?: number | undefined
+  }
+
+  type ReturnType = {
+    /** The human-readable part. */
+    hrp: string
+    /** The decoded data bytes. */
+    data: Uint8Array
+  }
+
+  type ErrorType =
+    | NoSeparatorError
+    | InvalidChecksumError
+    | InvalidCharacterError
+    | InvalidPaddingError
+    | MixedCaseError
+    | InvalidHrpError
+    | ExceedsLengthError
+    | Errors.GlobalErrorType
+}
+
+/** Thrown when a bech32m string has no separator. */
+export class NoSeparatorError extends BaseError {
+  override readonly name = 'Bech32m.NoSeparatorError'
+  constructor() {
+    super('Bech32m string has no separator.')
+  }
+}
+
+/** Thrown when a bech32m string has an invalid checksum. */
+export class InvalidChecksumError extends BaseError {
+  override readonly name = 'Bech32m.InvalidChecksumError'
+  constructor() {
+    super('Invalid bech32m checksum.')
+  }
+}
+
+/** Thrown when a bech32m string contains an invalid character. */
+export class InvalidCharacterError extends BaseError {
+  override readonly name = 'Bech32m.InvalidCharacterError'
+  constructor({ character }: { character: string }) {
+    super(`Invalid bech32m character: "${character}".`)
+  }
+}
+
+/** Thrown when the padding bits are invalid during base32 conversion. */
+export class InvalidPaddingError extends BaseError {
+  override readonly name = 'Bech32m.InvalidPaddingError'
+  constructor() {
+    super('Invalid padding in bech32m data.')
+  }
+}
+
+/** Thrown when a bech32m string contains mixed case. */
+export class MixedCaseError extends BaseError {
+  override readonly name = 'Bech32m.MixedCaseError'
+  constructor() {
+    super('Bech32m string must not contain mixed case.')
+  }
+}
+
+/** Thrown when the HRP is invalid (empty or contains non-ASCII characters). */
+export class InvalidHrpError extends BaseError {
+  override readonly name = 'Bech32m.InvalidHrpError'
+  constructor() {
+    super(
+      'Invalid bech32m human-readable part (HRP). Must be 1+ characters in ASCII range 33-126.',
+    )
+  }
+}
+
+/** Thrown when the encoded string exceeds the length limit. */
+export class ExceedsLengthError extends BaseError {
+  override readonly name = 'Bech32m.ExceedsLengthError'
+  constructor({ limit }: { limit: number }) {
+    super(`Bech32m string exceeds length limit of ${limit}.`)
+  }
+}
+
+/** @internal */
+const alphabet = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
+
+/** @internal */
+const alphabetMap = /*#__PURE__*/ (() => {
+  const map: Record<string, number> = {}
+  for (let i = 0; i < alphabet.length; i++) map[alphabet[i]!] = i
+  return map
+})()
+
+/** @internal */
+const BECH32M_CONST = 0x2bc830a3
+
+/** @internal */
+const GEN = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3]
+
+/** @internal */
+function polymod(values: number[]): number {
+  let chk = 1
+  for (const v of values) {
+    const b = chk >> 25
+    chk = ((chk & 0x1ffffff) << 5) ^ v
+    for (let i = 0; i < 5; i++) if ((b >> i) & 1) chk ^= GEN[i]!
+  }
+  return chk
+}
+
+/** @internal */
+function hrpExpand(hrp: string): number[] {
+  const ret: number[] = []
+  for (let i = 0; i < hrp.length; i++) ret.push(hrp.charCodeAt(i) >> 5)
+  ret.push(0)
+  for (let i = 0; i < hrp.length; i++) ret.push(hrp.charCodeAt(i) & 31)
+  return ret
+}
+
+/** @internal */
+function createChecksum(hrp: string, data: number[]): number[] {
+  const values = hrpExpand(hrp).concat(data).concat([0, 0, 0, 0, 0, 0])
+  const mod = polymod(values) ^ BECH32M_CONST
+  const ret: number[] = []
+  for (let i = 0; i < 6; i++) ret.push((mod >> (5 * (5 - i))) & 31)
+  return ret
+}
+
+/** @internal */
+function verifyChecksum(hrp: string, data: number[]): boolean {
+  return polymod(hrpExpand(hrp).concat(data)) === BECH32M_CONST
+}
+
+/** @internal */
+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
+}

package/index.ts

@@ -862,7 +862,6 @@ export * as Authorization from './core/Authorization.js'
  * @category Data
  */
 export * as Base32 from './core/Base32.js'
-
 /**
  * Utility functions for working with [Base58](https://digitalbazaar.github.io/base58-spec/) values.
  *
@@ -917,7 +916,6 @@ export * as Base32 from './core/Base32.js'
  * @category Data
  */
 export * as Base58 from './core/Base58.js'
-
 /**
  * Utility functions for working with [RFC-4648](https://datatracker.ietf.org/doc/html/rfc4648) Base64.
  *
@@ -971,6 +969,30 @@ export * as Base58 from './core/Base58.js'
  * @category Data
  */
 export * as Base64 from './core/Base64.js'
+/**
+ * Utility functions for [BIP-350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) bech32m encoding and decoding.
+ *
+ * @example
+ * ### Encoding
+ *
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const encoded = Bech32m.encode('tempo', new Uint8Array(20))
+ * ```
+ *
+ * @example
+ * ### Decoding
+ *
+ * ```ts twoslash
+ * import { Bech32m } from 'ox'
+ *
+ * const { hrp, data } = Bech32m.decode('tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq7w9gdx')
+ * ```
+ *
+ * @category Data
+ */
+export * as Bech32m from './core/Bech32m.js'
 
 /**
  * Utility functions for working with [EIP-7864](https://eips.ethereum.org/EIPS/eip-7864) Binary State Trees.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ox",
   "description": "Ethereum Standard Library",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",
@@ -128,6 +128,11 @@
       "import": "./_esm/core/Base64.js",
       "default": "./_cjs/core/Base64.js"
     },
+    "./Bech32m": {
+      "types": "./_types/core/Bech32m.d.ts",
+      "import": "./_esm/core/Bech32m.js",
+      "default": "./_cjs/core/Bech32m.js"
+    },
     "./BinaryStateTree": {
       "types": "./_types/core/BinaryStateTree.d.ts",
       "import": "./_esm/core/BinaryStateTree.js",