ox 1.1.0 → 1.2.0

package/src/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '1.1.0'
+export const version = '1.2.0'

package/src/wasm/Ed25519.ts

@@ -0,0 +1,114 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as crypto25519 from './internal/crypto25519.js'
+import * as ed25519 from './internal/ed25519.js'
+import * as internal from './internal/instantiate.js'
+
+export * from '../core/Ed25519.js'
+export { MemoryError } from './internal/instantiate.js'
+
+const keySize = 32
+const signatureSize = 64
+
+/**
+ * Compiles WASM implementations of selected [`Ed25519`](/api/Ed25519)
+ * primitives, without installing them.
+ *
+ * Public-key conversion and random key generation remain on Ox's default
+ * implementation. The public conversion is omitted because Monocypher does not
+ * reproduce Ox's invalid-point validation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/wasm'
+ *
+ * await Engine.install({ Ed25519: Ed25519.engine() })
+ *
+ * Ed25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The WASM implementation of part of the `Ed25519` slot.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await crypto25519.load()
+
+  return {
+    getPublicKey(privateKey) {
+      assertLength(privateKey, keySize, 'private key')
+      module.reserve(keySize * 2)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + keySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        module.exports.ed25519_get_public_key(privateKeyPtr, publicKeyPtr)
+        return module.view().slice(publicKeyPtr, publicKeyPtr + keySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, keySize * 2)
+      }
+    },
+    sign(payload, privateKey) {
+      assertLength(privateKey, keySize, 'private key')
+      return ed25519.sign(module, payload, privateKey)
+    },
+    toMontgomerySecret(privateKey) {
+      assertLength(privateKey, keySize, 'private key')
+      module.reserve(keySize * 2)
+      const privateKeyPtr = module.heapBase
+      const secretKeyPtr = privateKeyPtr + keySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        module.exports.ed25519_to_montgomery_secret(privateKeyPtr, secretKeyPtr)
+        return module.view().slice(secretKeyPtr, secretKeyPtr + keySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, keySize * 2)
+      }
+    },
+    verify(signature, payload, publicKey) {
+      assertLength(signature, signatureSize, 'signature')
+      assertLength(publicKey, keySize, 'public key')
+      const size = signatureSize + payload.length + keySize
+      module.reserve(size)
+      const signaturePtr = module.heapBase
+      const payloadPtr = signaturePtr + signatureSize
+      const publicKeyPtr = payloadPtr + payload.length
+      try {
+        const memory = module.view()
+        memory.set(signature, signaturePtr)
+        memory.set(payload, payloadPtr)
+        memory.set(publicKey, publicKeyPtr)
+        return (
+          module.exports.ed25519_verify(
+            signaturePtr,
+            payloadPtr,
+            payload.length,
+            publicKeyPtr,
+          ) === 1
+        )
+      } finally {
+        module.exports.zero(signaturePtr, size)
+      }
+    },
+  }
+}
+
+export declare namespace engine {
+  /** Every `Ed25519` primitive this module implements. */
+  type ReturnType = {
+    [key in
+      | 'getPublicKey'
+      | 'sign'
+      | 'toMontgomerySecret'
+      | 'verify']-?: NonNullable<Engine.Eddsa[key]>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}
+
+function assertLength(value: Uint8Array, length: number, name: string): void {
+  if (value.length !== length)
+    throw new RangeError(
+      `Ed25519 ${name} must be ${length} bytes, got ${value.length}`,
+    )
+}

package/src/wasm/Engine.ts

@@ -1,55 +1,81 @@
 import * as CoreEngine from '../core/Engine.js'
 import type * as Errors from '../core/Errors.js'
+import * as Ed25519 from './Ed25519.js'
 import * as Hash from './Hash.js'
+import * as keystore from './internal/keystore.js'
+import * as Mnemonic from './Mnemonic.js'
+import * as X25519 from './X25519.js'
 import type * as internal from './internal/instantiate.js'
 
+export {
+  AsyncScopeError,
+  get,
+  InvalidSlotValueError,
+  reset,
+  set,
+  UnknownPrimitiveError,
+  UnknownSlotError,
+  with,
+} from '../core/Engine.js'
+export type {
+  Bls,
+  Ecdh,
+  Ecdsa,
+  Eddsa,
+  Engine,
+  Hash,
+  Keystore,
+  Mnemonic,
+} from '../core/Engine.js'
+
 /**
- * Compiles every implementation this entrypoint provides and installs it.
+ * Compiles and installs every WASM implementation this entrypoint provides.
  *
- * WASM must be compiled asynchronously, so this is where the `await` lives.
- * Everything afterwards, including the hashing itself, is synchronous.
+ * Slot compilation starts concurrently. Nothing is installed until every slot
+ * resolves successfully.
  *
- * 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.
+ * Call this 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'
+ * import { Engine, Hash } from 'ox/wasm'
  *
- * await Engine.load()
+ * await Engine.install()
  *
- * Hash.keccak256('0xdeadbeef')
+ * Hash.sha256('0xdeadbeef')
  * ```
  *
  * @returns The engine that was installed.
  */
-export async function load(): Promise<load.ReturnType> {
-  const engine = await create()
-  CoreEngine.set(engine)
-  return engine
+export async function install(): Promise<install.ReturnType> {
+  return CoreEngine.install({
+    Ed25519: Ed25519.engine(),
+    Hash: Hash.engine(),
+    Keystore: keystore.engine(),
+    Mnemonic: Mnemonic.engine(),
+    X25519: X25519.engine(),
+  })
 }
 
-export declare namespace load {
-  type ReturnType = create.ReturnType
+export declare namespace install {
+  type ReturnType = engine.ReturnType
 
   type ErrorType =
-    | create.ErrorType
-    | CoreEngine.set.ErrorType
+    | engine.ErrorType
+    | CoreEngine.install.ErrorType
     | Errors.GlobalErrorType
 }
 
 /**
- * Compiles every implementation this entrypoint provides, without installing
- * it.
+ * Compiles every WASM 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.
+ * Reach for this where an engine has to exist as a value, such as a benchmark
+ * or an [`Engine.with`](/api/Engine/with) scope. Use the individual module's
+ * `engine` function to select only some slots.
  *
  * @example
  * ```ts twoslash
@@ -57,20 +83,41 @@ export declare namespace load {
  * import { Engine, Hash } from 'ox'
  * import { Engine as Wasm } from 'ox/wasm'
  *
- * const wasm = await Wasm.create()
+ * const wasm = await Wasm.engine()
  *
- * Engine.with(wasm, () => Hash.keccak256('0xdeadbeef'))
+ * Engine.with(wasm, () => Hash.sha256('0xdeadbeef'))
  * ```
  *
  * @returns An engine, ready to install.
  */
-export async function create(): Promise<create.ReturnType> {
-  return { ...(await Hash.create()) }
+export async function engine(): Promise<engine.ReturnType> {
+  const [ed25519, hash, keystoreEngine, mnemonic, x25519] = await Promise.all([
+    Ed25519.engine(),
+    Hash.engine(),
+    keystore.engine(),
+    Mnemonic.engine(),
+    X25519.engine(),
+  ])
+  return {
+    Ed25519: ed25519,
+    Hash: hash,
+    Keystore: keystoreEngine,
+    Mnemonic: mnemonic,
+    X25519: x25519,
+  }
 }
 
-export declare namespace create {
+export declare namespace engine {
   /** Every slot this entrypoint supplies, each with its primitives present. */
-  type ReturnType = Hash.create.ReturnType
+  type ReturnType = {
+    Ed25519: Ed25519.engine.ReturnType
+    Hash: Hash.engine.ReturnType
+    Keystore: {
+      pbkdf2Sha256: NonNullable<CoreEngine.Keystore['pbkdf2Sha256']>
+    }
+    Mnemonic: Mnemonic.engine.ReturnType
+    X25519: X25519.engine.ReturnType
+  }
 
   type ErrorType = internal.MemoryError | Errors.GlobalErrorType
 }

package/src/wasm/Hash.bench.ts

@@ -3,7 +3,7 @@ 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'
+import { engine as wasmEngine } from './Hash.js'
 
 // Sizes expose fixed boundary overhead and sustained throughput. Crossovers
 // vary by primitive, runtime, and processor.
@@ -12,7 +12,7 @@ import { create as createWasm } from './Hash.js'
 // 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 wasm = await wasmEngine()
 const key = Uint8Array.from({ length: 32 }, (_, index) => index % 97)
 
 for (const size of sizes) {

package/src/wasm/Hash.ts

@@ -1,38 +1,22 @@
 import type * as Engine from '../core/Engine.js'
 import type * as Errors from '../core/Errors.js'
+import * as blake3 from './internal/blake3.js'
 import * as hash from './internal/hash.js'
-import { wasmBase64 } from './internal/hashes.wasm.js'
+import * as hashes from './internal/hashes.js'
 import * as internal from './internal/instantiate.js'
 
+export * from '../core/Hash.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.
+ * Compiles the WASM implementation of the [`Hash`](/api/Hash) primitives,
+ * without installing it.
  *
- * Most callers want {@link ox#Engine.load} instead, which compiles every
+ * Most callers want
+ * [`Engine.install`](/wasm/crypto/Engine/install) 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.
@@ -46,19 +30,22 @@ const instantiate = /*#__PURE__*/ internal.memoize(() =>
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Engine, Hash } from 'ox'
- * import * as WasmHash from 'ox/wasm/Hash'
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/wasm'
  *
- * Engine.set(await WasmHash.create())
+ * await Engine.install({ Hash: Hash.engine() })
  *
  * Hash.keccak256('0xdeadbeef')
  * ```
  *
- * @returns An engine supplying the `Hash` slot.
+ * @returns The WASM implementation of the `Hash` slot.
  */
-export async function create(): Promise<create.ReturnType> {
+export async function engine(): Promise<engine.ReturnType> {
   {
-    const module = await instantiate()
+    const [blake3Module, module] = await Promise.all([
+      blake3.load(),
+      hashes.load(),
+    ])
 
     // Copies `input` in, runs `hash`, and copies the digest back out.
     function call(
@@ -77,32 +64,24 @@ export async function create(): Promise<create.ReturnType> {
     }
 
     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),
-      },
+      blake3: (input) => blake3.hash(blake3Module, input),
+      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.
-   */
+export declare namespace engine {
+  /** Every `Hash` primitive this module implements. */
   type ReturnType = {
-    Hash: {
-      [key in
-        | 'hmacSha256'
-        | 'keccak256'
-        | 'ripemd160'
-        | 'sha256']-?: NonNullable<Engine.Hash[key]>
-    }
+    [key in
+      | 'blake3'
+      | 'hmacSha256'
+      | 'keccak256'
+      | 'ripemd160'
+      | 'sha256']-?: NonNullable<Engine.Hash[key]>
   }
 
   type ErrorType = internal.MemoryError | Errors.GlobalErrorType

package/src/wasm/Keystore.bench.ts

@@ -0,0 +1,26 @@
+import { scrypt as scrypt_noble } from '@noble/hashes/scrypt.js'
+import { bench, describe } from 'vp/test'
+import { engine as wasmEngine } from './Keystore.js'
+
+// Run `pnpm bench --project core src/wasm/Keystore.bench.ts`. These cases expose
+// the effect of block size, parallelization, and the public defaults.
+const cases = [
+  { N: 1024, dkLen: 32, p: 1, r: 1 },
+  { N: 16_384, dkLen: 32, p: 1, r: 8 },
+  { N: 262_144, dkLen: 32, p: 8, r: 1 },
+] as const
+
+const wasm = await wasmEngine()
+const password = new Uint8Array(16).fill(0x5a)
+const salt = new Uint8Array(32).fill(0xa5)
+
+for (const options of cases)
+  describe(`scrypt (N=${options.N}, r=${options.r}, p=${options.p})`, () => {
+    bench('ox', () => {
+      scrypt_noble(password, salt, options)
+    })
+
+    bench('ox/wasm', () => {
+      wasm.scrypt(password, salt, options)
+    })
+  })

package/src/wasm/Keystore.ts

@@ -0,0 +1,66 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as internal from './internal/instantiate.js'
+import * as keystore from './internal/keystore.js'
+import * as scrypt from './internal/scrypt.js'
+
+export * from '../core/Keystore.js'
+export { MemoryError } from './internal/instantiate.js'
+
+/**
+ * Compiles the WASM implementations of the [`Keystore`](/api/Keystore)
+ * synchronous key-derivation primitives, without installing them.
+ *
+ * Most callers can use [`Engine.install`](/wasm/crypto/Engine/install).
+ * Install this factory explicitly when an application has benchmarked and
+ * selected WASM scrypt.
+ *
+ * This provider stays synchronous and leaves AES and asynchronous key
+ * derivation on Ox's default implementation.
+ *
+ * Scrypt uses a standalone artifact and grows memory only when called.
+ * WebAssembly cannot shrink that capacity. The provider clears its contents
+ * and enforces Noble's 1 GiB temporary-workspace limit.
+ *
+ * The aggregate [`Engine.install`](/wasm/crypto/Engine/install) installs only
+ * PBKDF2 from this provider. Install this factory explicitly to opt into
+ * scrypt, whose relative performance depends on its parameters and runtime.
+ *
+ * Copied inputs, derived output, and the complete workspace are cleared after
+ * every return or trap.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Keystore } from 'ox/wasm'
+ *
+ * await Engine.install({ Keystore: Keystore.engine() })
+ *
+ * Keystore.scrypt({ password: 'testpassword' })
+ * ```
+ *
+ * @returns The WASM implementations of synchronous PBKDF2-HMAC-SHA256 and
+ * scrypt.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const [keystoreEngine, scryptModule] = await Promise.all([
+    keystore.engine(),
+    scrypt.load(),
+  ])
+  return {
+    ...keystoreEngine,
+    scrypt: (password, salt, options) =>
+      scrypt.derive(scryptModule, password, salt, options),
+  }
+}
+
+export declare namespace engine {
+  /** The WASM `Keystore` primitives this module implements. */
+  type ReturnType = {
+    pbkdf2Sha256: NonNullable<Engine.Keystore['pbkdf2Sha256']>
+    scrypt: NonNullable<Engine.Keystore['scrypt']>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}

package/src/wasm/Kzg.bench.ts

@@ -0,0 +1,63 @@
+import { afterAll, bench, describe } from 'vp/test'
+import { mainnet as trustedSetup } from '../trusted-setups/Setups.js'
+import { create } from './Kzg.js'
+
+const once = {
+  iterations: 1,
+  time: 0,
+  warmupIterations: 0,
+  warmupTime: 0,
+} as const
+
+describe('create', () => {
+  bench(
+    'precompute 0',
+    async () => {
+      const kzg = await create({ trustedSetup })
+      kzg.dispose()
+    },
+    once,
+  )
+
+  bench(
+    'precompute 8',
+    async () => {
+      const kzg = await create({ precompute: 8, trustedSetup })
+      kzg.dispose()
+    },
+    once,
+  )
+})
+
+const kzg = await create({ trustedSetup })
+const blob = new Uint8Array(131_072)
+const commitment = kzg.blobToKzgCommitment(blob)
+const { cells, proofs } = kzg.computeCellsAndKzgProofs(blob)
+const indices = cells.map((_, index) => index)
+const commitments = cells.map(() => commitment)
+const partialIndices = indices.filter((index) => index % 2 === 0)
+const partialCells = cells.filter((_, index) => index % 2 === 0)
+
+afterAll(() => kzg.dispose())
+
+describe('operations', () => {
+  bench('blobToKzgCommitment', () => {
+    kzg.blobToKzgCommitment(blob)
+  })
+
+  bench('computeCells', () => {
+    kzg.computeCells(blob)
+  })
+
+  bench('computeCellsAndKzgProofs', () => {
+    kzg.computeCellsAndKzgProofs(blob)
+  })
+
+  bench('recoverCellsAndKzgProofs', () => {
+    kzg.recoverCellsAndKzgProofs(partialIndices, partialCells)
+  })
+
+  bench('verifyCellKzgProofBatch', () => {
+    kzg.verifyCellKzgProofBatch(commitments, indices, cells, proofs)
+  })
+})