ox 1.2.0 → 1.3.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "ox",
   "description": "Ethereum Standard Library",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "main": "./dist/index.js",
   "sideEffects": false,
   "license": "MIT",
@@ -417,6 +417,11 @@
       "types": "./dist/core/Value.d.ts",
       "default": "./dist/core/Value.js"
     },
+    "./WebAuthn": {
+      "src": "./src/core/WebAuthn.ts",
+      "types": "./dist/core/WebAuthn.d.ts",
+      "default": "./dist/core/WebAuthn.js"
+    },
     "./WebAuthnP256": {
       "src": "./src/core/WebAuthnP256.ts",
       "types": "./dist/core/WebAuthnP256.d.ts",
@@ -1057,6 +1062,9 @@
   "types": "./dist/index.d.ts",
   "typesVersions": {
     "*": {
+      "_types/*": [
+        "./dist/*.d.ts"
+      ],
       "*": [
         "./dist/*",
         "./dist/*/index.d.ts",

package/src/benchmarks/Ox.bench.ts

@@ -0,0 +1,6 @@
+import { Engine } from 'ox'
+import { register } from '../../test/benchmarks/comparison.js'
+import { createOperations } from '../../test/benchmarks/comparison.current.js'
+
+Engine.reset()
+register('ox', createOperations())

package/src/benchmarks/OxNode.bench.ts

@@ -0,0 +1,8 @@
+import { Engine } from 'ox'
+import { Engine as NodeEngine } from 'ox/node'
+import { register } from '../../test/benchmarks/comparison.js'
+import { createOperations } from '../../test/benchmarks/comparison.current.js'
+
+Engine.reset()
+Engine.set(await NodeEngine.engine())
+register('ox/node', createOperations())

package/src/benchmarks/OxV0.bench.ts

@@ -0,0 +1,4 @@
+import { register } from '../../test/benchmarks/comparison.js'
+import { createOperations } from '../../test/benchmarks/comparison.v0.js'
+
+register('ox v0', createOperations())

package/src/benchmarks/OxWasm.bench.ts

@@ -0,0 +1,22 @@
+import { Engine } from 'ox'
+import {
+  Engine as WasmEngine,
+  Keystore as WasmKeystore,
+  Secp256k1 as WasmSecp256k1,
+} from 'ox/wasm'
+import { register } from '../../test/benchmarks/comparison.js'
+import { createOperations } from '../../test/benchmarks/comparison.current.js'
+
+const [wasm, keystore, secp256k1] = await Promise.all([
+  WasmEngine.engine(),
+  WasmKeystore.engine(),
+  WasmSecp256k1.engine(),
+])
+
+Engine.reset()
+Engine.set({
+  ...wasm,
+  Keystore: keystore,
+  Secp256k1: secp256k1,
+})
+register('ox/wasm', createOperations())

package/src/core/AbiFunction.ts

@@ -6,7 +6,7 @@ import type * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
 import type * as internal from './internal/abiFunction.js'
 import type * as AbiItem_internal from './internal/abiItem.js'
-import type * as AbiParameters_internal from './internal/abiParameters.js'
+import * as AbiParameters_internal from './internal/abiParameters.js'
 import * as formatAbiItem from './internal/human-readable/formatAbiItem.js'
 import type { IsNarrowable } from './internal/types.js'
 
@@ -670,10 +670,10 @@ export function encodeData(
 
   const selector = getSelector(item)
 
-  const data =
-    args.length > 0 ? AbiParameters.encode(item.inputs, args) : undefined
-
-  return data ? Hex.concat(selector, data) : selector
+  if (args.length === 0) return selector
+  return AbiParameters_internal.encodeParameters(item.inputs, args, {
+    prefix: selector,
+  })
 }
 
 export declare namespace encodeData {

package/src/core/AbiParameters.ts

@@ -212,29 +212,17 @@ export function encode<
   options?: encode.Options,
 ): Hex.Hex {
   const { checksumAddress = false } = options ?? {}
-
-  if (parameters.length !== values.length)
-    throw new LengthMismatchError({
-      expectedLength: parameters.length as number,
-      givenLength: values.length as any,
-    })
-  // Prepare the parameters to determine dynamic types to encode.
-  const preparedParameters = internal.prepareParameters({
-    checksumAddress,
-    parameters: parameters as readonly Parameter[],
-    values: values as any,
-  })
-  const data = internal.encode(preparedParameters)
-  if (data.length === 0) return '0x'
-  return data
+  return internal.encodeParameters(
+    parameters as readonly Parameter[],
+    values as readonly unknown[],
+    {
+      checksumAddress,
+    },
+  )
 }
 
 export declare namespace encode {
-  type ErrorType =
-    | LengthMismatchError
-    | internal.encode.ErrorType
-    | internal.prepareParameters.ErrorType
-    | Errors.GlobalErrorType
+  type ErrorType = internal.encodeParameters.ErrorType | Errors.GlobalErrorType
 
   type Options = {
     /**

package/src/core/AesGcm.ts

@@ -1,5 +1,5 @@
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
 
 export const ivLength = 16
@@ -134,6 +134,70 @@ export declare namespace encrypt {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives an AES-256-GCM key from a 32-byte WebAuthn PRF output.
+ *
+ * The permanent derivation contract uses the PRF output as the HMAC-SHA256
+ * key. Its message is the UTF-8 bytes of `ox.aesGcm.fromPrf.v1` followed by
+ * a 32-bit big-endian counter set to zero.
+ *
+ * @example
+ * ```ts twoslash
+ * import { AesGcm } from 'ox'
+ *
+ * const key = await AesGcm.fromPrf(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param value - A 32-byte WebAuthn PRF output.
+ * @returns A nonextractable AES-256-GCM key for encryption and decryption.
+ */
+export async function fromPrf(
+  value: Hex.Hex | Bytes.Bytes,
+): Promise<CryptoKey> {
+  const bytes = Bytes.from(value)
+  if (bytes.length !== 32) throw new InvalidPrfSizeError({ size: bytes.length })
+
+  const prfKey = await globalThis.crypto.subtle.importKey(
+    'raw',
+    bytes,
+    {
+      name: 'HMAC',
+      hash: 'SHA-256',
+    },
+    false,
+    ['sign'],
+  )
+  const key = new Uint8Array(
+    await globalThis.crypto.subtle.sign(
+      'HMAC',
+      prfKey,
+      Bytes.concat(fromPrfLabel, Bytes.fromNumber(0, { size: 4 })),
+    ),
+  )
+  try {
+    return await globalThis.crypto.subtle.importKey(
+      'raw',
+      key,
+      { name: 'AES-GCM' },
+      false,
+      ['encrypt', 'decrypt'],
+    )
+  } finally {
+    key.fill(0)
+  }
+}
+
+export declare namespace fromPrf {
+  type ErrorType =
+    | Bytes.concat.ErrorType
+    | Bytes.from.ErrorType
+    | Bytes.fromNumber.ErrorType
+    | InvalidPrfSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Derives an AES-GCM key from a password using PBKDF2.
  *
@@ -206,3 +270,24 @@ export function randomSalt(size = 32): Bytes.Bytes {
 export declare namespace randomSalt {
   type ErrorType = Bytes.random.ErrorType | Errors.GlobalErrorType
 }
+
+/** Thrown when a WebAuthn PRF output is not 32 bytes. */
+export class InvalidPrfSizeError extends Errors.BaseError {
+  override readonly name = 'AesGcm.InvalidPrfSizeError'
+
+  constructor(options: InvalidPrfSizeError.Options) {
+    super(
+      `PRF output must be exactly 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidPrfSizeError {
+  /** Options for {@link ox#AesGcm.InvalidPrfSizeError}. */
+  type Options = {
+    /** Received PRF output size. */
+    size: number
+  }
+}
+
+const fromPrfLabel = Bytes.fromString('ox.aesGcm.fromPrf.v1')

package/src/core/Ed25519.ts

@@ -1,6 +1,7 @@
 import { ed25519 } from '@noble/curves/ed25519.js'
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
+import * as Hash from './Hash.js'
 import * as Hex from './Hex.js'
 import * as engine from './internal/ed25519.js'
 
@@ -58,6 +59,70 @@ export declare namespace createKeyPair {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives an Ed25519 private key from a 32-byte WebAuthn PRF output.
+ *
+ * The permanent derivation contract uses the PRF output as the HMAC-SHA256
+ * key. Its message is the UTF-8 bytes of `ox.ed25519.fromPrf.v1` followed by
+ * a 32-bit big-endian counter set to zero.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Ed25519 } from 'ox'
+ *
+ * const privateKey = Ed25519.fromPrf(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param value - A 32-byte WebAuthn PRF output.
+ * @param options - Options.
+ * @returns An Ed25519 private key.
+ */
+export function fromPrf<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  value: Hex.Hex | Bytes.Bytes,
+  options: fromPrf.Options<as> = {},
+): fromPrf.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = Bytes.from(value)
+  if (bytes.length !== 32) throw new InvalidPrfSizeError({ size: bytes.length })
+
+  const privateKey = Hash.hmac256(
+    bytes,
+    Bytes.concat(fromPrfLabel, Bytes.fromNumber(0, { size: 4 })),
+    { as: 'Bytes' },
+  )
+  if (as === 'Hex') {
+    const value = Hex.fromBytes(privateKey)
+    privateKey.fill(0)
+    return value as never
+  }
+  return privateKey as never
+}
+
+export declare namespace fromPrf {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.concat.ErrorType
+    | Bytes.from.ErrorType
+    | Bytes.fromNumber.ErrorType
+    | Hash.hmac256.ErrorType
+    | Hex.fromBytes.ErrorType
+    | InvalidPrfSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the Ed25519 public key from a provided private key.
  *
@@ -345,3 +410,24 @@ export declare namespace toX25519PrivateKey {
     | Hex.fromBytes.ErrorType
     | Errors.GlobalErrorType
 }
+
+/** Thrown when a WebAuthn PRF output is not 32 bytes. */
+export class InvalidPrfSizeError extends Errors.BaseError {
+  override readonly name = 'Ed25519.InvalidPrfSizeError'
+
+  constructor(options: InvalidPrfSizeError.Options) {
+    super(
+      `PRF output must be exactly 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidPrfSizeError {
+  /** Options for {@link ox#Ed25519.InvalidPrfSizeError}. */
+  type Options = {
+    /** Received PRF output size. */
+    size: number
+  }
+}
+
+const fromPrfLabel = Bytes.fromString('ox.ed25519.fromPrf.v1')

package/src/core/Engine.ts

@@ -9,6 +9,7 @@ export type {
   Eddsa,
   Engine,
   Hash,
+  HashState,
   Keystore,
   Mnemonic,
 } from './internal/engine.js'

package/src/core/Hash.ts

@@ -1,8 +1,187 @@
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
+import type { HashState } from './internal/engine.js'
 import * as engine from './internal/hash.js'
 
+/**
+ * Incremental hash state.
+ *
+ * A hasher accepts any number of chunks. Calling `digest` or `digestInto`
+ * consumes the state. Call `clone` before finalizing to branch from the same
+ * prefix.
+ */
+export type Hasher = {
+  /** Creates an independent copy of the current state. */
+  clone(): Hasher
+  /** Destroys the state. Calling `destroy` more than once has no effect. */
+  destroy(): void
+  /** Finalizes the digest and consumes the state. */
+  digest<as extends 'Hex' | 'Bytes' = 'Hex'>(
+    options?: Hasher.DigestOptions<as>,
+  ): Hasher.DigestReturnType<as>
+  /**
+   * Finalizes into the start of `output` and consumes the state.
+   *
+   * `output` may be larger than the digest. Bytes after the digest are left
+   * unchanged.
+   */
+  digestInto(output: Bytes.Bytes): void
+  /** Absorbs a message chunk. */
+  update(value: Hex.Hex | Bytes.Bytes): Hasher
+}
+
+export declare namespace Hasher {
+  /** Options for `Hasher.digest`. */
+  type DigestOptions<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /** The return type. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  /** Return type for `Hasher.digest`. */
+  type DigestReturnType<as extends 'Hex' | 'Bytes' = 'Hex'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  /** Errors thrown by an incremental hash state. */
+  type ErrorType =
+    | HasherDestroyedError
+    | InvalidDigestSizeError
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Creates an incremental BLAKE3 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createBlake3()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0x53147f3ce49ed4f60dfa5b9654c36ba6103c11f5737df3dabd4cbd296c4161bd'
+ * ```
+ *
+ * @returns An incremental BLAKE3 hasher.
+ */
+export function createBlake3(): Hasher {
+  return fromState(engine.createBlake3(), 32)
+}
+
+export declare namespace createBlake3 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental HMAC-SHA256 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash, Hex } from 'ox'
+ *
+ * const hash = Hash.createHmac256(Hex.fromString('key'))
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * ```
+ *
+ * @param key - HMAC key.
+ * @returns An incremental HMAC-SHA256 hasher.
+ */
+export function createHmac256(key: Hex.Hex | Bytes.Bytes): Hasher {
+  return fromState(engine.createHmacSha256(Bytes.from(key)), 32)
+}
+
+export declare namespace createHmac256 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental Keccak256 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createKeccak256()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1'
+ * ```
+ *
+ * @returns An incremental Keccak256 hasher.
+ */
+export function createKeccak256(): Hasher {
+  return fromState(engine.createKeccak256(), 32)
+}
+
+export declare namespace createKeccak256 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental RIPEMD-160 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createRipemd160()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0x226821c2f5423e11fe9af68bd285c249db2e4b5a'
+ * ```
+ *
+ * @returns An incremental RIPEMD-160 hasher.
+ */
+export function createRipemd160(): Hasher {
+  return fromState(engine.createRipemd160(), 20)
+}
+
+export declare namespace createRipemd160 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental SHA-256 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createSha256()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953'
+ * ```
+ *
+ * @returns An incremental SHA-256 hasher.
+ */
+export function createSha256(): Hasher {
+  return fromState(engine.createSha256(), 32)
+}
+
+export declare namespace createSha256 {
+  type ErrorType = Hasher.ErrorType
+}
+
 /**
  * Calculates the [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
  *
@@ -323,3 +502,85 @@ export declare namespace validate {
     | Hex.size.ErrorType
     | Errors.GlobalErrorType
 }
+
+/** Thrown when an incremental hash state has been consumed or destroyed. */
+export class HasherDestroyedError extends Errors.BaseError {
+  override readonly name = 'Hash.HasherDestroyedError'
+
+  constructor() {
+    super('Hasher has been destroyed.')
+  }
+}
+
+/** Thrown when a digest output buffer is too small. */
+export class InvalidDigestSizeError extends Errors.BaseError {
+  override readonly name = 'Hash.InvalidDigestSizeError'
+
+  constructor(options: InvalidDigestSizeError.Options) {
+    const { minimum, size } = options
+    super(
+      `Digest output is too small. Expected at least ${minimum} bytes. Received ${size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidDigestSizeError {
+  type Options = {
+    /** Minimum output size. */
+    minimum: number
+    /** Received output size. */
+    size: number
+  }
+}
+
+function fromState(state: HashState, digestSize: number): Hasher {
+  let active = true
+
+  const assertActive = () => {
+    if (!active) throw new HasherDestroyedError()
+  }
+
+  const consume = <returnType>(fn: () => returnType): returnType => {
+    assertActive()
+    active = false
+    try {
+      return fn()
+    } finally {
+      state.destroy()
+    }
+  }
+
+  const hasher: Hasher = {
+    clone() {
+      assertActive()
+      return fromState(state.clone(), digestSize)
+    },
+    destroy() {
+      if (!active) return
+      active = false
+      state.destroy()
+    },
+    digest(options = {}) {
+      const value = new Uint8Array(digestSize)
+      consume(() => state.digestInto(value))
+      if (options.as === 'Bytes') return value as never
+      return Hex.fromBytes(value) as never
+    },
+    digestInto(output) {
+      assertActive()
+      if (output.length < digestSize)
+        throw new InvalidDigestSizeError({
+          minimum: digestSize,
+          size: output.length,
+        })
+      consume(() => state.digestInto(output))
+    },
+    update(value) {
+      assertActive()
+      state.update(Bytes.from(value))
+      return hasher
+    },
+  }
+
+  return hasher
+}

package/src/core/Hex.ts

@@ -74,10 +74,7 @@ export function concat(...values: readonly Hex[]): Hex {
   if (values.length === 1) return values[0]!
   if (values.length === 2)
     return `0x${(values[0] as string).slice(2)}${(values[1] as string).slice(2)}` as Hex
-  const parts = Array.from<string>({ length: values.length })
-  for (let i = 0; i < values.length; i++)
-    parts[i] = (values[i] as string).slice(2)
-  return `0x${parts.join('')}` as Hex
+  return `0x${values.reduce((hex, value) => hex + value.replace('0x', ''), '')}`
 }
 
 export declare namespace concat {