ox 0.13.2 → 0.14.1

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.1",
   "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",

package/tempo/AuthorizationTempo.test.ts

@@ -84,6 +84,19 @@ describe('from', () => {
     }
   })
 
+  test('tempo address input', () => {
+    const tempoAddr = 'tempo1qzlftsl42n5lep0v2xlxng7cq7sd2k709sxlwnsu'
+
+    const authorization = AuthorizationTempo.from({
+      address: tempoAddr,
+      chainId: 1,
+      nonce: 40n,
+    })
+    expect(authorization.address).toBe(
+      '0xBE95c3f554e9Fc85ec51bE69a3D807A0D55BCF2C',
+    )
+  })
+
   test('options: signature (secp256k1)', () => {
     const authorization = AuthorizationTempo.from({
       address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',

package/tempo/AuthorizationTempo.ts

@@ -1,10 +1,10 @@
-import type * as Address from '../core/Address.js'
 import type * as Errors from '../core/Errors.js'
 import * as Hash from '../core/Hash.js'
 import * as Hex from '../core/Hex.js'
 import type { Compute, Mutable } from '../core/internal/types.js'
 import * as Rlp from '../core/Rlp.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
+import * as TempoAddress from './TempoAddress.js'
 
 /**
  * Root type for a Tempo Authorization.
@@ -21,7 +21,7 @@ export type AuthorizationTempo<
 > = Compute<
   {
     /** Address of the contract to set as code for the Authority. */
-    address: Address.Address
+    address: TempoAddress.Address
     /** Chain ID to authorize. */
     chainId: numberType
     /** Nonce of the Authority to authorize. */
@@ -100,7 +100,7 @@ export type TupleListSigned = TupleList<true>
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -118,7 +118,7 @@ export type TupleListSigned = TupleList<true>
  * const privateKey = Secp256k1.randomPrivateKey()
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   address: 'tempo1qzlftsl42n5lep0v2xlxng7cq7sd2k709sxlwnsu',
  *   chainId: 1,
  *   nonce: 40n,
  * })
@@ -148,7 +148,7 @@ export type TupleListSigned = TupleList<true>
  * const { privateKey, publicKey } = P256.createKeyPair()
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   address: 'tempo1qzlftsl42n5lep0v2xlxng7cq7sd2k709sxlwnsu',
  *   chainId: 1,
  *   nonce: 40n,
  * })
@@ -183,7 +183,7 @@ export type TupleListSigned = TupleList<true>
  * const { privateKey, publicKey } = await WebCryptoP256.createKeyPair()
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   address: 'tempo1qzlftsl42n5lep0v2xlxng7cq7sd2k709sxlwnsu',
  *   chainId: 1,
  *   nonce: 40n,
  * })
@@ -219,7 +219,7 @@ export type TupleListSigned = TupleList<true>
  * const credential = await WebAuthnP256.createCredential({ name: 'Example' })
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   address: 'tempo1qzlftsl42n5lep0v2xlxng7cq7sd2k709sxlwnsu',
  *   chainId: 1,
  *   nonce: 40n,
  * })
@@ -253,10 +253,16 @@ export function from<
 ): from.ReturnType<authorization, signature> {
   if (typeof authorization.chainId === 'string')
     return fromRpc(authorization as Rpc) as never
+  const resolved = {
+    ...authorization,
+    address: TempoAddress.resolve(
+      authorization.address as TempoAddress.Address,
+    ),
+  }
   if (options.signature) {
-    return { ...authorization, signature: options.signature } as never
+    return { ...resolved, signature: options.signature } as never
   }
-  return authorization as never
+  return resolved as never
 }
 
 export declare namespace from {
@@ -294,7 +300,7 @@ export declare namespace from {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization = AuthorizationTempo.fromRpc({
- *   address: '0x0000000000000000000000000000000000000000',
+ *   address: 'tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj97hme',
  *   chainId: '0x1',
  *   nonce: '0x1',
  *   signature: {
@@ -332,7 +338,7 @@ export declare namespace fromRpc {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorizationList = AuthorizationTempo.fromRpcList([{
- *   address: '0x0000000000000000000000000000000000000000',
+ *   address: 'tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj97hme',
  *   chainId: '0x1',
  *   nonce: '0x1',
  *   signature: {
@@ -516,7 +522,7 @@ export declare namespace fromTupleList {
  * const privateKey = Secp256k1.randomPrivateKey()
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -544,7 +550,7 @@ export declare namespace fromTupleList {
  * const { privateKey, publicKey } = P256.createKeyPair()
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -577,7 +583,7 @@ export declare namespace fromTupleList {
  * const { privateKey, publicKey } = await WebCryptoP256.createKeyPair()
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -611,7 +617,7 @@ export declare namespace fromTupleList {
  * const credential = await WebAuthnP256.createCredential({ name: 'Example' })
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -652,7 +658,7 @@ export declare namespace getSignPayload {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -708,7 +714,7 @@ export declare namespace hash {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization = AuthorizationTempo.toRpc({
- *   address: '0x0000000000000000000000000000000000000000',
+ *   address: 'tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj97hme',
  *   chainId: 1,
  *   nonce: 1n,
  *   signature: {
@@ -748,7 +754,7 @@ export declare namespace toRpc {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization = AuthorizationTempo.toRpcList([{
- *   address: '0x0000000000000000000000000000000000000000',
+ *   address: 'tempo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj97hme',
  *   chainId: 1,
  *   nonce: 1n,
  *   signature: {
@@ -781,7 +787,7 @@ export declare namespace toRpcList {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
@@ -830,12 +836,12 @@ export declare namespace toTuple {
  * import { AuthorizationTempo } from 'ox/tempo'
  *
  * const authorization_1 = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 1,
  *   nonce: 69n,
  * })
  * const authorization_2 = AuthorizationTempo.from({
- *   address: '0x1234567890abcdef1234567890abcdef12345678',
+ *   address: 'tempo1qqfrg4ncjz4ummcjx3t83y9tehh3ydzk0qhcg00y',
  *   chainId: 3,
  *   nonce: 20n,
  * })