ox 1.0.4 → 1.1.0

package/src/wasm/Engine.ts

@@ -0,0 +1,76 @@
+import * as CoreEngine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as Hash from './Hash.js'
+import type * as internal from './internal/instantiate.js'
+
+/**
+ * Compiles every implementation this entrypoint provides and installs it.
+ *
+ * WASM must be compiled asynchronously, so this is where the `await` lives.
+ * Everything afterwards, including the hashing itself, is synchronous.
+ *
+ * Call it once, during startup, before any crypto call. ox resolves the engine
+ * at call time, so values computed beforehand used whatever was installed then.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Hash } from 'ox'
+ * import { Engine } from 'ox/wasm'
+ *
+ * await Engine.load()
+ *
+ * Hash.keccak256('0xdeadbeef')
+ * ```
+ *
+ * @returns The engine that was installed.
+ */
+export async function load(): Promise<load.ReturnType> {
+  const engine = await create()
+  CoreEngine.set(engine)
+  return engine
+}
+
+export declare namespace load {
+  type ReturnType = create.ReturnType
+
+  type ErrorType =
+    | create.ErrorType
+    | CoreEngine.set.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Compiles every implementation this entrypoint provides, without installing
+ * it.
+ *
+ * Reach for this where an engine has to exist as a value: measuring one
+ * implementation against another, or installing through
+ * [`Engine.with`](/api/Engine/with) for the duration of a call. Combining
+ * engines does not need it, because
+ * [`Engine.set`](/api/Engine/set) merges -- `await load()` followed by
+ * `Engine.set({ Secp256k1 })` leaves both in place.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine, Hash } from 'ox'
+ * import { Engine as Wasm } from 'ox/wasm'
+ *
+ * const wasm = await Wasm.create()
+ *
+ * Engine.with(wasm, () => Hash.keccak256('0xdeadbeef'))
+ * ```
+ *
+ * @returns An engine, ready to install.
+ */
+export async function create(): Promise<create.ReturnType> {
+  return { ...(await Hash.create()) }
+}
+
+export declare namespace create {
+  /** Every slot this entrypoint supplies, each with its primitives present. */
+  type ReturnType = Hash.create.ReturnType
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}

package/src/wasm/Hash.bench.ts

@@ -0,0 +1,60 @@
+import { hmac } from '@noble/hashes/hmac.js'
+import { ripemd160 as noble_ripemd160 } from '@noble/hashes/legacy.js'
+import { sha256 as noble_sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 as noble_keccak256 } from '@noble/hashes/sha3.js'
+import { bench, describe } from 'vp/test'
+import { create as createWasm } from './Hash.js'
+
+// Sizes expose fixed boundary overhead and sustained throughput. Crossovers
+// vary by primitive, runtime, and processor.
+//
+// Run `pnpm bench:engines` for the full engine comparison. Vitest cannot
+// run Rust, and this portable benchmark must remain browser-compatible.
+const sizes = [32, 64, 256, 1024, 4096, 65_536, 1_048_576] as const
+
+const wasm = (await createWasm()).Hash
+const key = Uint8Array.from({ length: 32 }, (_, index) => index % 97)
+
+for (const size of sizes) {
+  const bytes = Uint8Array.from({ length: size }, (_, index) => index % 251)
+
+  describe(`keccak256 (${size} bytes input)`, () => {
+    bench('ox', () => {
+      noble_keccak256(bytes)
+    })
+
+    bench('ox/wasm', () => {
+      wasm.keccak256(bytes)
+    })
+  })
+
+  describe(`sha256 (${size} bytes input)`, () => {
+    bench('ox', () => {
+      noble_sha256(bytes)
+    })
+
+    bench('ox/wasm', () => {
+      wasm.sha256(bytes)
+    })
+  })
+
+  describe(`ripemd160 (${size} bytes input)`, () => {
+    bench('ox', () => {
+      noble_ripemd160(bytes)
+    })
+
+    bench('ox/wasm', () => {
+      wasm.ripemd160(bytes)
+    })
+  })
+
+  describe(`hmacSha256 (${size} bytes input)`, () => {
+    bench('ox', () => {
+      hmac(noble_sha256, key, bytes)
+    })
+
+    bench('ox/wasm', () => {
+      wasm.hmacSha256(key, bytes)
+    })
+  })
+}

package/src/wasm/Hash.ts

@@ -0,0 +1,109 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as hash from './internal/hash.js'
+import { wasmBase64 } from './internal/hashes.wasm.js'
+import * as internal from './internal/instantiate.js'
+
+export { MemoryError } from './internal/instantiate.js'
+
+type Exports = hash.Exports & {
+  keccak256(input: number, length: number, out: number): void
+  ripemd160(input: number, length: number, out: number): void
+  sha256(input: number, length: number, out: number): void
+}
+
+/** Digest sizes, in bytes. */
+const digestSize = { keccak256: 32, ripemd160: 20, sha256: 32 }
+
+/**
+ * Compilation is memoized; the engine object deliberately is not.
+ *
+ * Handing every caller the same object means one of them customising a slot
+ * for composition silently changes what a later `create` -- or `Engine.load`
+ * -- installs.
+ *
+ * @internal
+ */
+const instantiate = /*#__PURE__*/ internal.memoize(() =>
+  internal.instantiate<Exports>(wasmBase64),
+)
+
+/**
+ * Compiles the WASM implementation of the [`Hash`](/api/Hash) primitives, without
+ * installing it.
+ *
+ * Most callers want {@link ox#Engine.load} instead, which compiles every
+ * implementation this entrypoint provides and installs them in one call. Reach
+ * for this to take the `Hash` slot on its own, or to hold the implementation
+ * without touching the installed engine.
+ *
+ * :::note
+ * Performance varies by primitive, input size, runtime, and processor. Run
+ * `pnpm bench:engines` to compare Ox's default, Node, WASM, and Alloy
+ * implementations on your target machine.
+ * :::
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine, Hash } from 'ox'
+ * import * as WasmHash from 'ox/wasm/Hash'
+ *
+ * Engine.set(await WasmHash.create())
+ *
+ * Hash.keccak256('0xdeadbeef')
+ * ```
+ *
+ * @returns An engine supplying the `Hash` slot.
+ */
+export async function create(): Promise<create.ReturnType> {
+  {
+    const module = await instantiate()
+
+    // Copies `input` in, runs `hash`, and copies the digest back out.
+    function call(
+      hash: 'keccak256' | 'ripemd160' | 'sha256',
+      input: Uint8Array,
+    ): Uint8Array {
+      const out = digestSize[hash]
+      module.reserve(input.length + out)
+      const inputPtr = module.heapBase
+      const outPtr = inputPtr + input.length
+      module.view().set(input, inputPtr)
+      module.exports[hash](inputPtr, input.length, outPtr)
+      // `slice`, not `subarray`: the result must not alias WASM memory, which the
+      // next call overwrites and a `grow` detaches entirely.
+      return module.view().slice(outPtr, outPtr + out)
+    }
+
+    return {
+      Hash: {
+        hmacSha256: (key, message) => hash.hmacSha256(module, key, message),
+        keccak256: (input) => call('keccak256', input),
+        ripemd160: (input) => call('ripemd160', input),
+        sha256: (input) => call('sha256', input),
+      },
+    }
+  }
+}
+
+export declare namespace create {
+  /**
+   * The `Hash` slot, carrying every primitive this module implements.
+   *
+   * {@link ox#Engine.Engine} is optional all the way down so that an engine can
+   * fill in as little as it likes. This one always fills the same four, and
+   * saying so is what spares callers a non-null assertion per primitive.
+   */
+  type ReturnType = {
+    Hash: {
+      [key in
+        | 'hmacSha256'
+        | 'keccak256'
+        | 'ripemd160'
+        | 'sha256']-?: NonNullable<Engine.Hash[key]>
+    }
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}

package/src/wasm/_test/Engine.test.ts

@@ -0,0 +1,62 @@
+import { Engine as CoreEngine, Hash } from 'ox'
+import { Engine } from 'ox/wasm'
+import { describe, expect, test } from 'vp/test'
+
+describe('create', () => {
+  test('behavior: does not install', async () => {
+    const engine = await Engine.create()
+    expect(Object.keys(engine)).toMatchInlineSnapshot(`
+      [
+        "Hash",
+      ]
+    `)
+    // The whole point of `create` over `load`: benches, differential tests and
+    // composition all need the implementation without touching global state.
+    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+  })
+
+  test('behavior: installs for the duration of a call', async () => {
+    // `with` is the case that genuinely needs a value: there is nothing
+    // installed for `set` to merge into.
+    const wasm = await Engine.create()
+    const inside = CoreEngine.with(wasm, () => Hash.keccak256('0xdeadbeef'))
+    expect(inside).toEqual(Hash.keccak256('0xdeadbeef'))
+    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+  })
+})
+
+describe('load', () => {
+  test('behavior: merges with a later set, rather than being replaced', async () => {
+    await Engine.load()
+    CoreEngine.set({ Mnemonic: { toSeed: () => new Uint8Array(64) } })
+    expect(Object.keys(CoreEngine.get()).sort()).toMatchInlineSnapshot(`
+      [
+        "Hash",
+        "Mnemonic",
+      ]
+    `)
+  })
+
+  test('behavior: installs, and returns what it installed', async () => {
+    const before = Hash.keccak256('0xdeadbeef')
+
+    const engine = await Engine.load()
+
+    expect(Object.keys(CoreEngine.get())).toEqual(Object.keys(engine))
+    // Installing changes which implementation runs, never the answer.
+    expect(Hash.keccak256('0xdeadbeef')).toEqual(before)
+  })
+
+  test('behavior: routes every slot it reports', async () => {
+    await Engine.load()
+    expect(Object.keys(CoreEngine.get().Hash ?? {}).sort())
+      .toMatchInlineSnapshot(`
+      [
+        "hmacSha256",
+        "keccak256",
+        "ripemd160",
+        "sha256",
+      ]
+    `)
+  })
+})

package/src/wasm/_test/Hash.browser.test.ts

@@ -0,0 +1,50 @@
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { describe, expect, test, vi } from 'vp/test'
+import * as Engine from '../../core/Engine.js'
+import * as Hash from '../../core/Hash.js'
+import * as WasmHash from '../Hash.js'
+
+describe('create', () => {
+  test('behavior: instantiates asynchronously', async () => {
+    // Chrome refuses to compile modules above a few kilobytes synchronously on
+    // the main thread, so `new WebAssembly.Module` must never be reached. A spy
+    // is the only way to assert that, since the artifact happens to be small
+    // enough today that a synchronous compile would succeed.
+    const Module = vi.spyOn(globalThis.WebAssembly, 'Module')
+    const Instance = vi.spyOn(globalThis.WebAssembly, 'Instance')
+    try {
+      const engine = await WasmHash.create()
+      expect(Module).not.toHaveBeenCalled()
+      expect(Instance).not.toHaveBeenCalled()
+
+      const input = new Uint8Array(32).fill(1)
+      expect(engine.Hash.keccak256(input)).toEqual(keccak_256(input))
+    } finally {
+      Module.mockRestore()
+      Instance.mockRestore()
+    }
+  })
+
+  test('behavior: grows memory in a real browser, then hashes a small input', async () => {
+    const engine = await WasmHash.create()
+
+    const large = new Uint8Array(3 * 1024 * 1024).fill(7)
+    expect(engine.Hash.keccak256(large)).toEqual(keccak_256(large))
+
+    // `memory.grow` detached the previous `ArrayBuffer`; a retained view would
+    // now read zero bytes.
+    const small = new Uint8Array(32).fill(1)
+    expect(engine.Hash.keccak256(small)).toEqual(keccak_256(small))
+  })
+
+  test('behavior: ox uses the WASM implementation once installed', async () => {
+    Engine.set(await WasmHash.create())
+    try {
+      expect(Hash.keccak256('0xdeadbeef')).toBe(
+        '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',
+      )
+    } finally {
+      Engine.reset()
+    }
+  })
+})

package/src/wasm/_test/Hash.fuzz.ts

@@ -0,0 +1,188 @@
+import { fc, test } from '@fast-check/vitest'
+import { hmac } from '@noble/hashes/hmac.js'
+import { ripemd160 } from '@noble/hashes/legacy.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { Hash as WasmHash } from 'ox/wasm'
+import { beforeAll, describe, expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+
+let engine: WasmHash.create.ReturnType
+
+beforeAll(async () => {
+  engine = await WasmHash.create()
+})
+
+/**
+ * `@noble/hashes` is the oracle: it is audited and it is what ox ships by
+ * default, so any divergence here is a bug in the WASM implementation. Published
+ * vectors live in `Hash.vectors.test.ts` and cover the case where both
+ * implementations could be wrong together.
+ *
+ * The distribution is weighted toward the sizes where padding and block-boundary
+ * bugs hide -- empty input, exact multiples of the keccak256 rate (136) and the
+ * SHA-2 block (64), and the 56-byte threshold at which the length counter no
+ * longer fits in the final block.
+ */
+const arbitraryInput = fc.oneof(
+  { arbitrary: fc.uint8Array({ maxLength: 300, minLength: 0 }), weight: 6 },
+  {
+    arbitrary: fc
+      .constantFrom(0, 1, 55, 56, 63, 64, 65, 111, 112, 135, 136, 137, 272)
+      .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+    weight: 3,
+  },
+  {
+    arbitrary: fc.uint8Array({ maxLength: 4096, minLength: 1024 }),
+    weight: 1,
+  },
+)
+
+/**
+ * HMAC key lengths straddling the 64-byte block. At or under it the key is
+ * zero-padded; over it, it is hashed first -- a different code path that the
+ * message-shaped arbitrary above would only reach by chance.
+ */
+const arbitraryKey = fc.oneof(
+  {
+    arbitrary: fc
+      .constantFrom(0, 1, 32, 63, 64, 65, 96, 128, 129)
+      .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+    weight: 3,
+  },
+  { arbitrary: fc.uint8Array({ maxLength: 200, minLength: 0 }), weight: 1 },
+)
+
+const primitives = {
+  hmacSha256: {
+    reference: (input: Uint8Array, key: Uint8Array) => hmac(sha256, key, input),
+    wasm: (input: Uint8Array, key: Uint8Array) =>
+      engine.Hash.hmacSha256(key, input),
+  },
+  keccak256: {
+    reference: (input: Uint8Array) => keccak_256(input),
+    wasm: (input: Uint8Array) => engine.Hash.keccak256(input),
+  },
+  ripemd160: {
+    reference: (input: Uint8Array) => ripemd160(input),
+    wasm: (input: Uint8Array) => engine.Hash.ripemd160(input),
+  },
+  sha256: {
+    reference: (input: Uint8Array) => sha256(input),
+    wasm: (input: Uint8Array) => engine.Hash.sha256(input),
+  },
+} as const
+
+type Name = keyof typeof primitives
+
+describe('Hash', () => {
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'keccak256 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.Hash.keccak256(input)).toEqual(keccak_256(input))
+    },
+  )
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'sha256 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.Hash.sha256(input)).toEqual(sha256(input))
+    },
+  )
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'ripemd160 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.Hash.ripemd160(input)).toEqual(ripemd160(input))
+    },
+  )
+
+  test.prop({ input: arbitraryInput, key: arbitraryKey }, { numRuns })(
+    'hmacSha256 ≡ @noble/hashes',
+    ({ input, key }) => {
+      expect(engine.Hash.hmacSha256(key, input)).toEqual(
+        hmac(sha256, key, input),
+      )
+    },
+  )
+})
+
+describe('memory', () => {
+  test.prop(
+    {
+      operations: fc.array(
+        fc.record({
+          input: arbitraryInput,
+          key: arbitraryKey,
+          name: fc.constantFrom<Name>(
+            'hmacSha256',
+            'keccak256',
+            'ripemd160',
+            'sha256',
+          ),
+        }),
+        { maxLength: 24, minLength: 2 },
+      ),
+    },
+    { numRuns },
+  )('an arbitrary sequence of calls agrees at every step', ({ operations }) => {
+    // Every primitive shares one region of WASM linear memory, reusing it call
+    // after call. A mis-sized reservation, an off-by-one write, or a digest read
+    // from the wrong offset can leave earlier bytes behind and still produce a
+    // correct answer in isolation -- it only shows up when calls of differing
+    // sizes and kinds are interleaved. Comparing every step of a random sequence
+    // is what catches that; a fixed a/b/a pattern does not.
+    for (const { input, key, name } of operations) {
+      const primitive = primitives[name]
+      expect(
+        primitive.wasm(input, key),
+        `${name} with a ${input.length} byte input`,
+      ).toEqual(primitive.reference(input, key))
+    }
+  })
+
+  test.prop(
+    {
+      sizes: fc.array(fc.integer({ max: 20, min: 0 }), {
+        maxLength: 6,
+        minLength: 2,
+      }),
+    },
+    { numRuns: Math.min(numRuns, 20) },
+  )('repeated growth keeps results correct', ({ sizes }) => {
+    // Each size is a page count. Going up grows linear memory and detaches the
+    // previous `ArrayBuffer`; coming back down must not, since WASM memory never
+    // shrinks. Either way the view has to be re-derived, and a stale one reads
+    // as zeroes rather than throwing.
+    for (const pages of sizes) {
+      const input = new Uint8Array(pages * 65_536).fill(pages & 0xff)
+      expect(engine.Hash.keccak256(input), `${pages} pages`).toEqual(
+        keccak_256(input),
+      )
+    }
+  })
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'digests never alias WASM memory',
+    ({ input }) => {
+      // A digest returned as a view over linear memory would be silently
+      // rewritten by the next call. Hold one across a larger call and check it.
+      const digest = engine.Hash.keccak256(input)
+      const snapshot = digest.slice()
+      engine.Hash.keccak256(new Uint8Array(input.length + 1024).fill(0xaa))
+      expect(digest).toEqual(snapshot)
+    },
+  )
+
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'inputs are not mutated',
+    ({ input }) => {
+      const snapshot = input.slice()
+      engine.Hash.keccak256(input)
+      engine.Hash.sha256(input)
+      engine.Hash.ripemd160(input)
+      engine.Hash.hmacSha256(input, input)
+      expect(input).toEqual(snapshot)
+    },
+  )
+})

package/src/wasm/_test/Hash.test-d.ts

@@ -0,0 +1,28 @@
+import type { Engine } from 'ox'
+import { Hash as WasmHash } from 'ox/wasm'
+import { expectTypeOf, test } from 'vp/test'
+
+type Created = Awaited<ReturnType<typeof WasmHash.create>>
+
+test('every primitive is present, so callers need no assertion', () => {
+  expectTypeOf<Created['Hash']['keccak256']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['sha256']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['ripemd160']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['hmacSha256']>().toEqualTypeOf<
+    (key: Uint8Array, message: Uint8Array) => Uint8Array
+  >()
+})
+
+test('blake3 is absent, because the WASM module does not implement it', () => {
+  expectTypeOf<Created['Hash']>().not.toHaveProperty('blake3')
+})
+
+test('the result is still an engine, so `Engine.set` accepts it', () => {
+  expectTypeOf<Created>().toExtend<Engine.Engine>()
+})