ox 1.0.4 → 1.1.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "ox",
   "description": "Ethereum Standard Library",
   "type": "module",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "main": "./dist/index.js",
   "sideEffects": false,
   "license": "MIT",
@@ -220,6 +220,11 @@
       "types": "./dist/core/Ed25519.d.ts",
       "default": "./dist/core/Ed25519.js"
     },
+    "./Engine": {
+      "src": "./src/core/Engine.ts",
+      "types": "./dist/core/Engine.d.ts",
+      "default": "./dist/core/Engine.js"
+    },
     "./Ens": {
       "src": "./src/core/Ens.ts",
       "types": "./dist/core/Ens.d.ts",
@@ -505,6 +510,21 @@
       "types": "./dist/erc8021/Attribution.d.ts",
       "default": "./dist/erc8021/Attribution.js"
     },
+    "./node": {
+      "src": "./src/node/index.ts",
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./node/Engine": {
+      "src": "./src/node/Engine.ts",
+      "types": "./dist/node/Engine.d.ts",
+      "default": "./dist/node/Engine.js"
+    },
+    "./node/Hash": {
+      "src": "./src/node/Hash.ts",
+      "types": "./dist/node/Hash.d.ts",
+      "default": "./dist/node/Hash.js"
+    },
     "./tempo": {
       "src": "./src/tempo/index.ts",
       "types": "./dist/tempo/index.d.ts",
@@ -620,6 +640,21 @@
       "types": "./dist/trusted-setups/Paths.d.ts",
       "default": "./dist/trusted-setups/Paths.js"
     },
+    "./wasm": {
+      "src": "./src/wasm/index.ts",
+      "types": "./dist/wasm/index.d.ts",
+      "default": "./dist/wasm/index.js"
+    },
+    "./wasm/Engine": {
+      "src": "./src/wasm/Engine.ts",
+      "types": "./dist/wasm/Engine.d.ts",
+      "default": "./dist/wasm/Engine.js"
+    },
+    "./wasm/Hash": {
+      "src": "./src/wasm/Hash.ts",
+      "types": "./dist/wasm/Hash.d.ts",
+      "default": "./dist/wasm/Hash.js"
+    },
     "./webauthn": {
       "src": "./src/webauthn/index.ts",
       "types": "./dist/webauthn/index.d.ts",

package/src/core/Base64.ts

@@ -1,66 +1,7 @@
 import * as Bytes from './Bytes.js'
-import * as Errors from './Errors.js'
+import type * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
-import { decoder } from './internal/codec/utf8.js'
-
-// Standard Base64 alphabet (RFC 4648 section 4) and URL-safe alphabet (section 5).
-const stdAlphabet =
-  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
-
-// Char-code -> 6-bit integer lookup. Sentinel `0xff` = invalid character.
-// Standard alphabet plus URL-safe `-`/`_` (decoders are alphabet-agnostic).
-const characterToInteger = /*#__PURE__*/ (() => {
-  const table = new Uint8Array(256).fill(0xff)
-  for (let i = 0; i < stdAlphabet.length; i++)
-    table[stdAlphabet.charCodeAt(i)] = i
-  // URL-safe alternates: `-` for `+` (62), `_` for `/` (63).
-  table[45 /* '-' */] = 62
-  table[95 /* '_' */] = 63
-  return table
-})()
-
-// Integer -> char-code table for the standard alphabet, indexed by 6-bit value.
-const integerToCharacter = /*#__PURE__*/ (() => {
-  const table = new Uint8Array(64)
-  for (let i = 0; i < stdAlphabet.length; i++)
-    table[i] = stdAlphabet.charCodeAt(i)
-  return table
-})()
-
-// Phase 2 native fast-path detection: `Uint8Array.prototype.toBase64` /
-// `Uint8Array.fromBase64` ship in Node 22+, Safari 18+, Firefox 133+.
-const nativeToBase64:
-  | ((
-      this: Uint8Array,
-      options?: { alphabet?: 'base64' | 'base64url'; omitPadding?: boolean },
-    ) => string)
-  | undefined = (
-  Uint8Array.prototype as Uint8Array & {
-    toBase64?: (options?: {
-      alphabet?: 'base64' | 'base64url'
-      omitPadding?: boolean
-    }) => string
-  }
-).toBase64
-const nativeFromBase64:
-  | ((
-      value: string,
-      options?: {
-        alphabet?: 'base64' | 'base64url-or-base64'
-        lastChunkHandling?: 'loose' | 'strict' | 'stop-before-partial'
-      },
-    ) => Uint8Array)
-  | undefined = (
-  Uint8Array as typeof Uint8Array & {
-    fromBase64?: (
-      value: string,
-      options?: {
-        alphabet?: 'base64' | 'base64url-or-base64'
-        lastChunkHandling?: 'loose' | 'strict' | 'stop-before-partial'
-      },
-    ) => Uint8Array
-  }
-).fromBase64
+import * as internal from './internal/codec/base64.js'
 
 /**
  * Encodes a {@link ox#Bytes.Bytes} to a Base64-encoded string (with optional padding and/or URL-safe characters).
@@ -109,39 +50,7 @@ const nativeFromBase64:
  * @returns The Base64 encoded string.
  */
 export function fromBytes(value: Bytes.Bytes, options: fromBytes.Options = {}) {
-  const { pad = true, url = false } = options
-
-  if (nativeToBase64) {
-    const out = nativeToBase64.call(value, {
-      alphabet: url ? 'base64url' : 'base64',
-      omitPadding: !pad,
-    })
-    // Native `base64url` already omits padding; if pad was requested, restore it.
-    if (url && pad) {
-      const k = value.length % 3
-      if (k === 1) return `${out}==`
-      if (k === 2) return `${out}=`
-    }
-    return out
-  }
-
-  const encoded = new Uint8Array(Math.ceil(value.length / 3) * 4)
-
-  for (let i = 0, j = 0; j < value.length; i += 4, j += 3) {
-    const y = (value[j]! << 16) + (value[j + 1]! << 8) + (value[j + 2]! | 0)
-    encoded[i] = integerToCharacter[y >> 18]!
-    encoded[i + 1] = integerToCharacter[(y >> 12) & 0x3f]!
-    encoded[i + 2] = integerToCharacter[(y >> 6) & 0x3f]!
-    encoded[i + 3] = integerToCharacter[y & 0x3f]!
-  }
-
-  const k = value.length % 3
-  const end = Math.floor(value.length / 3) * 4 + (k && k + 1)
-  let base64 = decoder.decode(new Uint8Array(encoded.buffer, 0, end))
-  if (pad && k === 1) base64 += '=='
-  if (pad && k === 2) base64 += '='
-  if (url) base64 = base64.replaceAll('+', '-').replaceAll('/', '_')
-  return base64
+  return internal.fromBytes(value, options)
 }
 
 export declare namespace fromBytes {
@@ -307,54 +216,7 @@ export declare namespace fromString {
  * @returns The Base64 decoded {@link ox#Bytes.Bytes}.
  */
 export function toBytes(value: string): Bytes.Bytes {
-  // Strip trailing '=' padding (only at the very end).
-  let bodyEnd = value.length
-  let pad = 0
-  while (bodyEnd > 0 && value.charCodeAt(bodyEnd - 1) === 61 /* '=' */) {
-    bodyEnd--
-    pad++
-  }
-
-  const size = bodyEnd
-  // Reject impossible lengths and excessive padding.
-  if (size % 4 === 1) throw new InvalidLengthError({ length: value.length })
-  if (pad > 2) throw new InvalidPaddingError({ padding: pad })
-
-  if (nativeFromBase64) {
-    try {
-      // `base64url-or-base64` accepts both alphabets transparently.
-      return nativeFromBase64(value.slice(0, bodyEnd), {
-        alphabet: 'base64url-or-base64',
-        lastChunkHandling: 'loose',
-      })
-    } catch {
-      // Fall through to the JS path so we throw the typed error class.
-    }
-  }
-
-  // Validate characters: every char must be in the standard or URL-safe
-  // alphabet, and '=' may not appear in the body (only stripped trailing
-  // padding).
-  const decoded = new Uint8Array(
-    (size >> 2) * 3 + (size % 4 ? (size % 4) - 1 : 0),
-  )
-  let acc = 0
-  let bits = 0
-  let n = 0
-  for (let i = 0; i < size; i++) {
-    const code = value.charCodeAt(i)
-    if (code === 61 /* '=' */)
-      throw new InvalidCharacterError({ character: '=' })
-    const v = characterToInteger[code]!
-    if (v === 0xff) throw new InvalidCharacterError({ character: value[i]! })
-    acc = (acc << 6) | v
-    bits += 6
-    if (bits >= 8) {
-      bits -= 8
-      decoded[n++] = (acc >>> bits) & 0xff
-    }
-  }
-  return decoded
+  return internal.toBytes(value)
 }
 
 export declare namespace toBytes {
@@ -409,29 +271,20 @@ export declare namespace toString {
   type ErrorType = toBytes.ErrorType | Errors.GlobalErrorType
 }
 
-/** Thrown when a Base64 string contains an invalid character. */
-export class InvalidCharacterError extends Errors.BaseError {
-  override readonly name = 'Base64.InvalidCharacterError'
-
-  constructor({ character }: { character: string }) {
-    super(`Invalid Base64 character: "${character}".`)
-  }
-}
+/** Thrown when a Base64 string contains a character outside its alphabet. */
+export const InvalidCharacterError = internal.InvalidCharacterError
+export type InvalidCharacterError = InstanceType<
+  typeof internal.InvalidCharacterError
+>
 
 /** Thrown when a Base64 string has an impossible length. */
-export class InvalidLengthError extends Errors.BaseError {
-  override readonly name = 'Base64.InvalidLengthError'
-
-  constructor({ length }: { length: number }) {
-    super(`Invalid Base64 input length \`${length}\`.`)
-  }
-}
-
-/** Thrown when a Base64 string contains too many trailing `=` padding characters. */
-export class InvalidPaddingError extends Errors.BaseError {
-  override readonly name = 'Base64.InvalidPaddingError'
-
-  constructor({ padding }: { padding: number }) {
-    super(`Invalid Base64 padding length \`${padding}\` (must be 0, 1, or 2).`)
-  }
-}
+export const InvalidLengthError = internal.InvalidLengthError
+export type InvalidLengthError = InstanceType<
+  typeof internal.InvalidLengthError
+>
+
+/** Thrown when a Base64 string carries more than two padding characters. */
+export const InvalidPaddingError = internal.InvalidPaddingError
+export type InvalidPaddingError = InstanceType<
+  typeof internal.InvalidPaddingError
+>

package/src/core/BinaryStateTree.ts

@@ -1,6 +1,5 @@
-import { blake3 } from '@noble/hashes/blake3.js'
-
 import * as Bytes from './Bytes.js'
+import * as engine from './internal/hash.js'
 import type { OneOf } from './internal/types.js'
 
 /** Type that defines a Binary State Tree instance. */
@@ -276,5 +275,5 @@ function bitsToBytes(bits: number[]): Bytes.Bytes {
 function hash(bytes: Bytes.Bytes | undefined): Bytes.Bytes {
   if (!bytes) return new Uint8Array(32).fill(0)
   if (!bytes.some((byte) => byte !== 0)) return new Uint8Array(32).fill(0)
-  return blake3(bytes)
+  return engine.blake3(bytes)
 }

package/src/core/Bls.ts

@@ -4,6 +4,7 @@ import * as BlsPoint from './BlsPoint.js'
 import * as Bytes from './Bytes.js'
 import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
+import * as engine from './internal/bls.js'
 import type { OneOf } from './internal/types.js'
 
 /**
@@ -116,12 +117,11 @@ export function aggregate(
     return point
   })
 
-  const first = normalized[0]!
+  // A single point aggregates to itself. The engine is not consulted because
+  // there is no addition to perform, only the identity.
+  if (normalized.length === 1) return normalized[0]!
 
-  // Fast path: a single point aggregates to itself.
-  if (normalized.length === 1) return first
-
-  const isG1 = typeof first.x === 'string'
+  const isG1 = typeof normalized[0]!.x === 'string'
   for (let i = 1; i < normalized.length; i++) {
     if ((typeof normalized[i]!.x === 'string') !== isG1)
       throw new Errors.BaseError(
@@ -130,13 +130,13 @@ export function aggregate(
   }
 
   const groupName = isG1 ? 'G1' : 'G2'
-  const group = isG1 ? bls.G1 : bls.G2
-  let acc = group.Point.ZERO
-  for (let i = 0; i < normalized.length; i++) {
-    const p = normalized[i]!
-    acc = acc.add(BlsPoint.toNoblePoint(p as any, groupName) as any)
-  }
-  return BlsPoint.fromNoblePoint(acc, groupName) as BlsPoint.BlsPoint
+  const point = engine.aggregate(
+    normalized.map((point) =>
+      BlsPoint.toBytes(point as BlsPoint.G1 | BlsPoint.G2),
+    ),
+    groupName,
+  )
+  return BlsPoint.fromBytes(point, groupName) as BlsPoint.BlsPoint
 }
 
 export declare namespace aggregate {
@@ -349,14 +349,8 @@ export function getPublicKey<
 export function getPublicKey(options: getPublicKey.Options): unknown {
   const { as = 'Object', privateKey, size = 'short-key:long-sig' } = options
   const groupName = size === 'short-key:long-sig' ? 'G1' : 'G2'
-  const group = groupName === 'G1' ? bls.G1 : bls.G2
-  const point = group.Point.BASE.multiply(
-    group.Point.Fn.fromBytes(Bytes.from(privateKey)),
-  )
-  const publicKey = BlsPoint.fromNoblePoint(
-    point,
-    groupName,
-  ) as BlsPoint.BlsPoint
+  const point = engine.getPublicKey(Bytes.from(privateKey), groupName)
+  const publicKey = BlsPoint.fromBytes(point, groupName) as BlsPoint.BlsPoint
   return formatBlsPoint(publicKey, as)
 }
 
@@ -422,7 +416,7 @@ export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: randomPrivateKey.Options<as> = {},
 ): randomPrivateKey.ReturnType<as> {
   const { as = 'Hex' } = options
-  const bytes = bls.utils.randomSecretKey()
+  const bytes = engine.randomSecretKey()
   if (as === 'Hex') return Hex.fromBytes(bytes) as never
   return bytes as never
 }
@@ -507,18 +501,11 @@ export function sign(options: sign.Options): unknown {
 
   const signatureGroupName: 'G1' | 'G2' =
     size === 'short-key:long-sig' ? 'G2' : 'G1'
-  const payloadGroup = signatureGroupName === 'G2' ? bls.G2 : bls.G1
-  const payloadPoint = payloadGroup.hashToCurve(
-    Bytes.from(payload),
-    suite ? { DST: Bytes.fromString(suite) } : undefined,
-  )
-
-  const privateKeyGroup = size === 'short-key:long-sig' ? bls.G1 : bls.G2
-  const signature = payloadPoint.multiply(
-    privateKeyGroup.Point.Fn.fromBytes(Bytes.from(privateKey)),
-  )
-
-  const result = BlsPoint.fromNoblePoint(
+  const signature = engine.sign(Bytes.from(payload), Bytes.from(privateKey), {
+    dst: suite ? Bytes.fromString(suite) : undefined,
+    group: signatureGroupName,
+  })
+  const result = BlsPoint.fromBytes(
     signature,
     signatureGroupName,
   ) as BlsPoint.BlsPoint
@@ -674,51 +661,14 @@ export function verify(options: verify.Options): boolean {
       : normalizeBlsPoint(publicKeyRaw as Hex.Hex | Bytes.Bytes, publicKeyGroup)
   ) as BlsPoint.BlsPoint<any>
 
-  const isShortSig = signatureGroup === 'G1'
-
-  const group = isShortSig ? bls.G1 : bls.G2
-  const payloadPoint = group.hashToCurve(
+  return engine.verify(
+    BlsPoint.toBytes(signature as BlsPoint.G1 | BlsPoint.G2),
     Bytes.from(payload),
-    suite ? { DST: Bytes.fromString(suite) } : undefined,
-  )
-
-  const shortSigPairing = () =>
-    bls.pairingBatch([
-      {
-        g1: payloadPoint as InstanceType<typeof bls.G1.Point>,
-        g2: BlsPoint.toNoblePoint(publicKey as any, 'G2') as InstanceType<
-          typeof bls.G2.Point
-        >,
-      },
-      {
-        g1: BlsPoint.toNoblePoint(signature as any, 'G1') as InstanceType<
-          typeof bls.G1.Point
-        >,
-        g2: bls.G2.Point.BASE.negate(),
-      },
-    ])
-
-  const longSigPairing = () =>
-    bls.pairingBatch([
-      {
-        g1: (
-          BlsPoint.toNoblePoint(publicKey as any, 'G1') as InstanceType<
-            typeof bls.G1.Point
-          >
-        ).negate(),
-        g2: payloadPoint as InstanceType<typeof bls.G2.Point>,
-      },
-      {
-        g1: bls.G1.Point.BASE,
-        g2: BlsPoint.toNoblePoint(signature as any, 'G2') as InstanceType<
-          typeof bls.G2.Point
-        >,
-      },
-    ])
-
-  return bls.fields.Fp12.eql(
-    isShortSig ? shortSigPairing() : longSigPairing(),
-    bls.fields.Fp12.ONE,
+    BlsPoint.toBytes(publicKey as BlsPoint.G1 | BlsPoint.G2),
+    {
+      dst: suite ? Bytes.fromString(suite) : undefined,
+      signatureGroup,
+    },
   )
 }
 

package/src/core/Ed25519.ts

@@ -2,6 +2,7 @@ import { ed25519 } from '@noble/curves/ed25519.js'
 import * as Bytes from './Bytes.js'
 import type * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
+import * as engine from './internal/ed25519.js'
 
 /** Re-export of noble/curves Ed25519 utilities. */
 export const noble = ed25519
@@ -77,7 +78,7 @@ export function getPublicKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
 ): getPublicKey.ReturnType<as> {
   const { as = 'Hex', privateKey } = options
   const privateKeyBytes = Bytes.from(privateKey)
-  const publicKeyBytes = ed25519.getPublicKey(privateKeyBytes)
+  const publicKeyBytes = engine.getPublicKey(privateKeyBytes)
   if (as === 'Hex') return Hex.fromBytes(publicKeyBytes) as never
   return publicKeyBytes as never
 }
@@ -122,7 +123,7 @@ export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: randomPrivateKey.Options<as> = {},
 ): randomPrivateKey.ReturnType<as> {
   const { as = 'Hex' } = options
-  const bytes = ed25519.utils.randomSecretKey()
+  const bytes = engine.randomSecretKey()
   if (as === 'Hex') return Hex.fromBytes(bytes) as never
   return bytes as never
 }
@@ -166,7 +167,7 @@ export function sign<as extends 'Hex' | 'Bytes' = 'Hex'>(
   const { as = 'Hex', payload, privateKey } = options
   const payloadBytes = Bytes.from(payload)
   const privateKeyBytes = Bytes.from(privateKey)
-  const signatureBytes = ed25519.sign(payloadBytes, privateKeyBytes)
+  const signatureBytes = engine.sign(payloadBytes, privateKeyBytes)
   if (as === 'Hex') return Hex.fromBytes(signatureBytes) as never
   return signatureBytes as never
 }
@@ -227,7 +228,7 @@ export function verify(options: verify.Options): boolean {
   const payloadBytes = Bytes.from(payload)
   const publicKeyBytes = Bytes.from(publicKey)
   const signatureBytes = Bytes.from(signature)
-  return ed25519.verify(signatureBytes, payloadBytes, publicKeyBytes)
+  return engine.verify(signatureBytes, payloadBytes, publicKeyBytes)
 }
 
 export declare namespace verify {
@@ -268,7 +269,7 @@ export function toX25519PublicKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
 ): toX25519PublicKey.ReturnType<as> {
   const { as = 'Hex', publicKey } = options
   const publicKeyBytes = Bytes.from(publicKey)
-  const x25519PublicKeyBytes = ed25519.utils.toMontgomery(publicKeyBytes)
+  const x25519PublicKeyBytes = engine.toMontgomery(publicKeyBytes)
   if (as === 'Hex') return Hex.fromBytes(x25519PublicKeyBytes) as never
   return x25519PublicKeyBytes as never
 }
@@ -319,8 +320,7 @@ export function toX25519PrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
 ): toX25519PrivateKey.ReturnType<as> {
   const { as = 'Hex', privateKey } = options
   const privateKeyBytes = Bytes.from(privateKey)
-  const x25519PrivateKeyBytes =
-    ed25519.utils.toMontgomerySecret(privateKeyBytes)
+  const x25519PrivateKeyBytes = engine.toMontgomerySecret(privateKeyBytes)
   if (as === 'Hex') return Hex.fromBytes(x25519PrivateKeyBytes) as never
   return x25519PrivateKeyBytes as never
 }