ox 1.0.5 → 1.1.0

package/src/core/P256.ts

@@ -8,6 +8,7 @@ import {
   normalizePublicKey,
   normalizeSignature,
 } from './internal/cryptoIo.js'
+import * as engine from './internal/p256.js'
 import * as Entropy from './internal/entropy.js'
 import {
   fromRecoveredBytes,
@@ -85,7 +86,7 @@ export function getPublicKey<as extends 'Hex' | 'Bytes' | 'Object' = 'Object'>(
   options: getPublicKey.Options<as>,
 ): getPublicKey.ReturnType<as> {
   const { as = 'Object', privateKey } = options
-  const bytes = noble_p256.getPublicKey(Bytes.from(privateKey), false)
+  const bytes = engine.getPublicKey(Bytes.from(privateKey))
   const publicKey = PublicKey.fromBytes(bytes)
   return formatPublicKey(publicKey, as) as never
 }
@@ -134,10 +135,9 @@ export function getSharedSecret<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: getSharedSecret.Options<as>,
 ): getSharedSecret.ReturnType<as> {
   const { as = 'Hex', privateKey, publicKey } = options
-  const sharedSecret = noble_p256.getSharedSecret(
+  const sharedSecret = engine.getSharedSecret(
     Bytes.from(privateKey),
     PublicKey.toBytes(normalizePublicKey(publicKey)),
-    true, // compressed
   )
   if (as === 'Hex') return Hex.fromBytes(sharedSecret) as never
   return sharedSecret as never
@@ -190,7 +190,7 @@ export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: randomPrivateKey.Options<as> = {},
 ): randomPrivateKey.ReturnType<as> {
   const { as = 'Hex' } = options
-  const bytes = noble_p256.utils.randomSecretKey()
+  const bytes = engine.randomSecretKey()
   if (as === 'Hex') return Hex.fromBytes(bytes) as never
   return bytes as never
 }
@@ -238,11 +238,8 @@ export function recoverPublicKey<
 >(options: recoverPublicKey.Options<as>): recoverPublicKey.ReturnType<as> {
   const { as = 'Object', payload, signature } = options
   const sigBytes = toRecoveredBytes(normalizeSignature<true>(signature))
-  const point = noble_p256.Signature.fromBytes(
-    sigBytes,
-    'recovered',
-  ).recoverPublicKey(Bytes.from(payload))
-  const publicKey = PublicKey.fromBytes(point.toBytes(false))
+  const bytes = engine.recoverPublicKey(sigBytes, Bytes.from(payload))
+  const publicKey = PublicKey.fromBytes(bytes)
   return formatPublicKey(publicKey, as) as never
 }
 
@@ -302,19 +299,13 @@ export function sign<as extends 'Hex' | 'Bytes' | 'Object' = 'Object'>(
     payload,
     privateKey,
   } = options
-  const sigBytes = noble_p256.sign(
-    Bytes.from(payload),
-    Bytes.from(privateKey),
-    {
-      extraEntropy:
-        typeof extraEntropy === 'boolean'
-          ? extraEntropy
-          : Bytes.from(extraEntropy),
-      lowS: true,
-      prehash: hash === true,
-      format: 'recovered',
-    },
-  )
+  const sigBytes = engine.sign(Bytes.from(payload), Bytes.from(privateKey), {
+    extraEntropy:
+      typeof extraEntropy === 'boolean'
+        ? extraEntropy
+        : Bytes.from(extraEntropy),
+    prehash: hash === true,
+  })
   const signature = fromRecoveredBytes(sigBytes)
   return formatSignature(signature, as) as never
 }
@@ -381,11 +372,11 @@ export declare namespace sign {
  */
 export function verify(options: verify.Options): boolean {
   const { hash, payload, publicKey, signature } = options
-  return noble_p256.verify(
+  return engine.verify(
     toCompactBytes(normalizeSignature(signature)),
     Bytes.from(payload),
     PublicKey.toBytes(normalizePublicKey(publicKey)),
-    { lowS: true, prehash: hash === true },
+    { prehash: hash === true },
   )
 }
 

package/src/core/Rlp_tx.bench.ts

@@ -1,7 +1,5 @@
-// Track B / transactions: bench coverage for the RLP encode/decode hot
-// paths exercised by every TxEnvelope codec. The encoding thread owns
-// codec-only bench naming under `src/core/Rlp.bench.ts`; this file scopes
-// to transaction-shaped inputs to avoid collision.
+// Scoped to transaction-shaped inputs, the RLP paths every TxEnvelope codec
+// exercises. `src/core/Rlp.bench.ts` covers RLP on its own terms.
 
 import { bench, describe } from 'vp/test'
 import * as Hex from './Hex.js'

package/src/core/Secp256k1.ts

@@ -9,6 +9,7 @@ import {
   normalizePublicKey,
   normalizeSignature,
 } from './internal/cryptoIo.js'
+import * as engine from './internal/secp256k1.js'
 import * as Entropy from './internal/entropy.js'
 import {
   fromRecoveredBytes,
@@ -89,7 +90,7 @@ export function getPublicKey<as extends 'Hex' | 'Bytes' | 'Object' = 'Object'>(
   options: getPublicKey.Options<as>,
 ): getPublicKey.ReturnType<as> {
   const { as = 'Object', privateKey } = options
-  const bytes = secp256k1.getPublicKey(Bytes.from(privateKey), false)
+  const bytes = engine.getPublicKey(Bytes.from(privateKey))
   const publicKey = PublicKey.fromBytes(bytes)
   return formatPublicKey(publicKey, as) as never
 }
@@ -142,10 +143,9 @@ export function getSharedSecret<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: getSharedSecret.Options<as>,
 ): getSharedSecret.ReturnType<as> {
   const { as = 'Hex', privateKey, publicKey } = options
-  const sharedSecret = secp256k1.getSharedSecret(
+  const sharedSecret = engine.getSharedSecret(
     Bytes.from(privateKey),
     PublicKey.toBytes(normalizePublicKey(publicKey)),
-    true, // compressed
   )
   if (as === 'Hex') return Hex.fromBytes(sharedSecret) as never
   return sharedSecret as never
@@ -199,7 +199,7 @@ export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: randomPrivateKey.Options<as> = {},
 ): randomPrivateKey.ReturnType<as> {
   const { as = 'Hex' } = options
-  const bytes = secp256k1.utils.randomSecretKey()
+  const bytes = engine.randomSecretKey()
   if (as === 'Hex') return Hex.fromBytes(bytes) as never
   return bytes as never
 }
@@ -296,11 +296,8 @@ export function recoverPublicKey<
 >(options: recoverPublicKey.Options<as>): recoverPublicKey.ReturnType<as> {
   const { as = 'Object', payload, signature } = options
   const sigBytes = toRecoveredBytes(normalizeSignature<true>(signature))
-  const point = secp256k1.Signature.fromBytes(
-    sigBytes,
-    'recovered',
-  ).recoverPublicKey(Bytes.from(payload))
-  const publicKey = PublicKey.fromBytes(point.toBytes(false))
+  const bytes = engine.recoverPublicKey(sigBytes, Bytes.from(payload))
+  const publicKey = PublicKey.fromBytes(bytes)
   return formatPublicKey(publicKey, as) as never
 }
 
@@ -360,14 +357,12 @@ export function sign<as extends 'Hex' | 'Bytes' | 'Object' = 'Object'>(
     payload,
     privateKey,
   } = options
-  const sigBytes = secp256k1.sign(Bytes.from(payload), Bytes.from(privateKey), {
+  const sigBytes = engine.sign(Bytes.from(payload), Bytes.from(privateKey), {
     extraEntropy:
       typeof extraEntropy === 'boolean'
         ? extraEntropy
         : Bytes.from(extraEntropy),
-    lowS: true,
     prehash: hash === true,
-    format: 'recovered',
   })
   const signature = fromRecoveredBytes(sigBytes)
   return formatSignature(signature, as) as never
@@ -462,11 +457,11 @@ export function verify(options: verify.Options): boolean {
       recoverAddress({ payload, signature: options.signature }),
     )
   const sig = normalizeSignature(options.signature)
-  return secp256k1.verify(
+  return engine.verify(
     toCompactBytes(sig),
     Bytes.from(payload),
     PublicKey.toBytes(normalizePublicKey(options.publicKey)),
-    { lowS: true, prehash: hash === true },
+    { prehash: hash === true },
   )
 }
 

package/src/core/TxEnvelopeEip1559.bench.ts

@@ -1,8 +1,3 @@
-// Track B / transactions: bench coverage for the EIP-1559 envelope
-// serialize / deserialize / hash hot paths. Targets per
-// `tasks/perf-api-audit-transactions.md` Phase 1: ≥ 2× faster envelope
-// serialize and deserialize at the same input.
-
 import { bench, describe } from 'vp/test'
 import * as TxEnvelopeEip1559 from './TxEnvelopeEip1559.js'
 

package/src/core/WebCryptoP256.ts

@@ -1,4 +1,3 @@
-import { p256 } from '@noble/curves/nist.js'
 import * as Bytes from './Bytes.js'
 import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
@@ -7,12 +6,13 @@ import {
   normalizePublicKey,
   normalizeSignature,
 } from './internal/cryptoIo.js'
+import { p256N } from './internal/curves.js'
 import type { Compute } from './internal/types.js'
 import * as PublicKey from './PublicKey.js'
 import type * as Signature from './Signature.js'
 
 /** secp256r1 / P-256 curve order. */
-const N = p256.Point.CURVE().n
+const N = p256N
 
 /**
  * Generates an ECDSA P256 key pair that includes:

package/src/core/X25519.ts

@@ -2,6 +2,7 @@ import { x25519 } 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/x25519.js'
 
 /** Re-export of noble/curves X25519 utilities. */
 export const noble = x25519
@@ -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 = x25519.getPublicKey(privateKeyBytes)
+  const publicKeyBytes = engine.getPublicKey(privateKeyBytes)
   if (as === 'Hex') return Hex.fromBytes(publicKeyBytes) as never
   return publicKeyBytes as never
 }
@@ -130,7 +131,7 @@ export function getSharedSecret<as extends 'Hex' | 'Bytes' = 'Hex'>(
   const { as = 'Hex', privateKey, publicKey } = options
   const privateKeyBytes = Bytes.from(privateKey)
   const publicKeyBytes = Bytes.from(publicKey)
-  const sharedSecretBytes = x25519.getSharedSecret(
+  const sharedSecretBytes = engine.getSharedSecret(
     privateKeyBytes,
     publicKeyBytes,
   )
@@ -182,7 +183,7 @@ export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
   options: randomPrivateKey.Options<as> = {},
 ): randomPrivateKey.ReturnType<as> {
   const { as = 'Hex' } = options
-  const bytes = x25519.utils.randomSecretKey()
+  const bytes = engine.randomSecretKey()
   if (as === 'Hex') return Hex.fromBytes(bytes) as never
   return bytes as never
 }

package/src/core/_test/AbiParameters.adversarial.fuzz.ts

@@ -3,8 +3,7 @@ import { AbiParameters, Bytes, Hex } from 'ox'
 import { describe, expect } from 'vp/test'
 
 import { arbitraryAbiCase } from '../../../test/fuzz/arbitraries/abi.js'
-
-const numRuns = Number(process.env.FC_NUM_RUNS) || 100
+import { numRuns } from '../../../test/fuzz/numRuns.js'
 
 /**
  * Whitelist of error names ox is allowed to throw on adversarial-but-

package/src/core/_test/AbiParameters.fuzz.ts

@@ -3,8 +3,7 @@ import { AbiParameters } from 'ox'
 import { describe, expect } from 'vp/test'
 
 import { arbitraryAbiCase } from '../../../test/fuzz/arbitraries/abi.js'
-
-const numRuns = Number(process.env.FC_NUM_RUNS) || 100
+import { numRuns } from '../../../test/fuzz/numRuns.js'
 
 describe('AbiParameters round-trip', () => {
   test.prop(

package/src/core/_test/Base.fuzz.ts

@@ -3,8 +3,7 @@ import { Base32, Base58, Base64 } from 'ox'
 import { describe, expect } from 'vp/test'
 
 import { arbitraryBytes } from '../../../test/fuzz/arbitraries/bytes.js'
-
-const numRuns = Number(process.env.FC_NUM_RUNS) || 100
+import { numRuns } from '../../../test/fuzz/numRuns.js'
 
 describe('Base32 round-trip', () => {
   test.prop({ bytes: arbitraryBytes() }, { numRuns })(

package/src/core/_test/Cbor.fuzz.ts

@@ -1,8 +1,7 @@
 import { fc, test } from '@fast-check/vitest'
 import { Cbor } from 'ox'
 import { describe, expect } from 'vp/test'
-
-const numRuns = Number(process.env.FC_NUM_RUNS) || 100
+import { numRuns } from '../../../test/fuzz/numRuns.js'
 
 /**
  * Recursive CBOR-encodable value. ox's Cbor module supports:

package/src/core/_test/Engine.fuzz.ts

@@ -0,0 +1,293 @@
+import { fc, test } from '@fast-check/vitest'
+import {
+  Bls,
+  Ed25519,
+  Engine,
+  Hash,
+  Keystore,
+  Mnemonic,
+  P256,
+  Secp256k1,
+  X25519,
+} from 'ox'
+import { afterEach, describe, expect } from 'vp/test'
+import { identity, sentinel } from '../../../test/engines.js'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+
+const arbitraryBytes = fc.uint8Array({ maxLength: 256, minLength: 0 })
+/**
+ * A 32-byte scalar that is a valid private key on every curve ox uses.
+ *
+ * Built compositionally rather than by filtering, so no candidate is ever
+ * rejected: a leading byte in `[0x01, 0x72]` is clear of zero and below every
+ * order in play. BLS12-381 sets the ceiling, not the 256-bit curves -- its
+ * scalar field is `0x73eda753…`, so anything above `0x72` reduces rather than
+ * being used as given, which would quietly narrow what the fuzz explores.
+ */
+const arbitraryPrivateKey = fc
+  .tuple(
+    fc.integer({ max: 0x72, min: 0x01 }),
+    fc.uint8Array({ maxLength: 31, minLength: 31 }),
+  )
+  .map(([first, rest]) => Uint8Array.of(first, ...rest))
+
+afterEach(() => {
+  Engine.reset()
+})
+
+/**
+ * Each entry runs one routed call site. `run` must be deterministic given its
+ * inputs, so that the same call before and after installing an engine can be
+ * compared directly.
+ */
+const callSites = [
+  {
+    name: 'Hash.keccak256',
+    run: (bytes: Uint8Array) => Hash.keccak256(bytes),
+  },
+  {
+    name: 'Hash.sha256',
+    run: (bytes: Uint8Array) => Hash.sha256(bytes),
+  },
+  {
+    name: 'Hash.ripemd160',
+    run: (bytes: Uint8Array) => Hash.ripemd160(bytes),
+  },
+  {
+    name: 'Hash.hmac256',
+    run: (bytes: Uint8Array) => Hash.hmac256(new Uint8Array(32).fill(7), bytes),
+  },
+] as const
+
+describe('identity engine', () => {
+  test.prop({ bytes: arbitraryBytes }, { numRuns })(
+    'leaves every hash call site unchanged',
+    ({ bytes }) => {
+      const before = callSites.map((site) => site.run(bytes))
+      Engine.set(identity)
+      expect(callSites.map((site) => site.run(bytes))).toEqual(before)
+    },
+  )
+
+  test.prop(
+    { payload: arbitraryBytes, privateKey: arbitraryPrivateKey },
+    {
+      numRuns,
+    },
+  )('leaves secp256k1 unchanged', ({ payload, privateKey }) => {
+    const before = {
+      publicKey: Secp256k1.getPublicKey({ privateKey }),
+      signature: Secp256k1.sign({ payload, privateKey }),
+    }
+    const recovered = Secp256k1.recoverPublicKey({
+      payload,
+      signature: before.signature,
+    })
+
+    Engine.set(identity)
+
+    expect(Secp256k1.getPublicKey({ privateKey })).toEqual(before.publicKey)
+    expect(Secp256k1.sign({ payload, privateKey })).toEqual(before.signature)
+    expect(
+      Secp256k1.recoverPublicKey({ payload, signature: before.signature }),
+    ).toEqual(recovered)
+    expect(
+      Secp256k1.verify({
+        payload,
+        publicKey: before.publicKey,
+        signature: before.signature,
+      }),
+    ).toBe(true)
+  })
+
+  test.prop(
+    { payload: arbitraryBytes, privateKey: arbitraryPrivateKey },
+    {
+      numRuns,
+    },
+  )('leaves P256 unchanged', ({ payload, privateKey }) => {
+    const publicKey = P256.getPublicKey({ privateKey })
+    const signature = P256.sign({ payload, privateKey })
+
+    Engine.set(identity)
+
+    expect(P256.getPublicKey({ privateKey })).toEqual(publicKey)
+    expect(P256.sign({ payload, privateKey })).toEqual(signature)
+    expect(P256.verify({ payload, publicKey, signature })).toBe(true)
+  })
+
+  test.prop(
+    { payload: arbitraryBytes, privateKey: arbitraryPrivateKey },
+    { numRuns },
+  )('leaves Ed25519 and X25519 unchanged', ({ payload, privateKey }) => {
+    const before = {
+      ed25519PublicKey: Ed25519.getPublicKey({ privateKey }),
+      signature: Ed25519.sign({ payload, privateKey }),
+      x25519PublicKey: X25519.getPublicKey({ privateKey }),
+    }
+    const sharedSecret = X25519.getSharedSecret({
+      privateKey,
+      publicKey: before.x25519PublicKey,
+    })
+
+    Engine.set(identity)
+
+    expect(Ed25519.getPublicKey({ privateKey })).toEqual(
+      before.ed25519PublicKey,
+    )
+    expect(Ed25519.sign({ payload, privateKey })).toEqual(before.signature)
+    expect(X25519.getPublicKey({ privateKey })).toEqual(before.x25519PublicKey)
+    expect(
+      X25519.getSharedSecret({
+        privateKey,
+        publicKey: before.x25519PublicKey,
+      }),
+    ).toEqual(sharedSecret)
+  })
+
+  test.prop({ password: fc.string({ maxLength: 64 }) }, { numRuns: 10 })(
+    'leaves Keystore key derivation unchanged',
+    ({ password }) => {
+      // The smallest parameters ox accepts -- these run per { numRuns } case, and
+      // scrypt's real defaults take seconds. `iv` is pinned because it defaults
+      // to random, and the returned key is a thunk, so compare derived material
+      // rather than the returned tuple.
+      const options = {
+        iv: '0x6087dab2f9fdbbfaddc31a909735c1e6',
+        password,
+        salt: '0xae3cd4e7013836a3df6bd7241b12db061dbe2c6785853cce422d148a624ce0bd',
+      } as const
+      const before = {
+        pbkdf2: Keystore.pbkdf2({ ...options, iterations: 1000 })[0](),
+        scrypt: Keystore.scrypt({ ...options, n: 1024, p: 1, r: 1 })[0](),
+      }
+
+      Engine.set(identity)
+
+      expect(Keystore.pbkdf2({ ...options, iterations: 1000 })[0]()).toEqual(
+        before.pbkdf2,
+      )
+      expect(Keystore.scrypt({ ...options, n: 1024, p: 1, r: 1 })[0]()).toEqual(
+        before.scrypt,
+      )
+    },
+  )
+
+  test.prop(
+    { payload: arbitraryBytes, privateKey: arbitraryPrivateKey },
+    { numRuns: Math.min(numRuns, 10) },
+  )('leaves Bls unchanged', ({ payload, privateKey }) => {
+    const before = {
+      publicKey: Bls.getPublicKey({ privateKey }),
+      signature: Bls.sign({ payload, privateKey }),
+    }
+
+    Engine.set(identity)
+
+    expect(Bls.getPublicKey({ privateKey })).toEqual(before.publicKey)
+    expect(Bls.sign({ payload, privateKey })).toEqual(before.signature)
+    expect(
+      Bls.verify({
+        payload,
+        publicKey: before.publicKey,
+        signature: before.signature,
+      }),
+    ).toBe(true)
+  })
+
+  test.prop({ passphrase: fc.string({ maxLength: 32 }) }, { numRuns })(
+    'leaves Mnemonic.toSeed unchanged',
+    ({ passphrase }) => {
+      const mnemonic =
+        'test test test test test test test test test test test junk'
+      const before = Mnemonic.toSeed(mnemonic, { passphrase })
+      Engine.set(identity)
+      expect(Mnemonic.toSeed(mnemonic, { passphrase })).toEqual(before)
+    },
+  )
+})
+
+describe('sentinel engine', () => {
+  test.prop({ bytes: arbitraryBytes }, { numRuns })(
+    'is consulted by every hash call site',
+    ({ bytes }) => {
+      // The inverse of the identity property: if a result survives a wrong
+      // implementation, the call site never reached the engine at all.
+      const before = callSites.map((site) => site.run(bytes))
+      Engine.set(sentinel)
+      const after = callSites.map((site) => site.run(bytes))
+      for (const [index, site] of callSites.entries())
+        expect(after[index], site.name).not.toEqual(before[index])
+    },
+  )
+})
+
+describe('with', () => {
+  test.prop(
+    { bytes: arbitraryBytes, depth: fc.integer({ max: 6, min: 1 }) },
+    { numRuns },
+  )('restores the engine at every nesting depth', ({ bytes, depth }) => {
+    const expected = Hash.keccak256(bytes)
+
+    function nest(level: number): void {
+      if (level === 0) return
+      Engine.with(
+        { Hash: { keccak256: () => new Uint8Array(32).fill(level) } },
+        () => {
+          expect(Hash.keccak256(bytes, { as: 'Bytes' })[0]).toBe(level)
+          nest(level - 1)
+          // Unwinding must restore *this* level, not the default.
+          expect(Hash.keccak256(bytes, { as: 'Bytes' })[0]).toBe(level)
+        },
+      )
+    }
+
+    nest(depth)
+    expect(Engine.get()).toEqual({})
+    expect(Hash.keccak256(bytes)).toEqual(expected)
+  })
+
+  test.prop({ bytes: arbitraryBytes }, { numRuns })(
+    'restores the engine when the callback throws',
+    ({ bytes }) => {
+      const expected = Hash.keccak256(bytes)
+      expect(() =>
+        Engine.with({ Hash: { keccak256: () => new Uint8Array(32) } }, () => {
+          throw new Error('boom')
+        }),
+      ).toThrow('boom')
+      expect(Hash.keccak256(bytes)).toEqual(expected)
+    },
+  )
+})
+
+describe('merge', () => {
+  const slotNames = ['Hash', 'Secp256k1', 'P256', 'Ed25519', 'X25519'] as const
+
+  test.prop(
+    {
+      slots: fc.array(fc.constantFrom(...slotNames), {
+        maxLength: 8,
+        minLength: 1,
+      }),
+    },
+    { numRuns },
+  )('accumulates slots across calls in any order', ({ slots }) => {
+    for (const slot of slots) Engine.set({ [slot]: {} })
+    expect(Object.keys(Engine.get()).sort()).toEqual([...new Set(slots)].sort())
+  })
+
+  test.prop(
+    {
+      slots: fc.array(fc.constantFrom(...slotNames), {
+        maxLength: 8,
+        minLength: 1,
+      }),
+    },
+    { numRuns },
+  )('reset clears whatever was accumulated', ({ slots }) => {
+    for (const slot of slots) Engine.set({ [slot]: {} })
+    Engine.reset()
+    expect(Engine.get()).toEqual({})
+  })
+})

package/src/core/_test/Engine.test-d.ts

@@ -0,0 +1,84 @@
+import { Engine } from 'ox'
+import { describe, expectTypeOf, test } from 'vp/test'
+import type { primitives } from '../internal/engine.js'
+
+/**
+ * Primitives on a slot contract that the runtime name table omits.
+ *
+ * `set` rejects any name absent from that table, so anything showing up here
+ * would be a valid override refused at runtime.
+ */
+type Unlisted = {
+  // `-?` because the slots are optional, which would otherwise leave
+  // `undefined` in the union and mask a genuinely missing name.
+  [key in keyof Engine.Engine]-?: Exclude<
+    keyof NonNullable<Engine.Engine[key]>,
+    (typeof primitives)[key][number]
+  >
+}[keyof Engine.Engine]
+
+describe('set', () => {
+  test('accepts a partial engine', () => {
+    expectTypeOf(Engine.set).parameter(0).toEqualTypeOf<Engine.Engine>()
+  })
+
+  test('rejects an unknown slot', () => {
+    // @ts-expect-error
+    Engine.set({ Keccak: {} })
+  })
+
+  test('rejects a misspelled function', () => {
+    // @ts-expect-error
+    Engine.set({ Hash: { keccak_256: (input: Uint8Array) => input } })
+  })
+
+  test('rejects a mistyped function', () => {
+    // @ts-expect-error
+    Engine.set({ Hash: { keccak256: (input: string) => input } })
+  })
+
+  test('the runtime name table lists every primitive it must accept', () => {
+    expectTypeOf<Unlisted>().toEqualTypeOf<never>()
+  })
+})
+
+describe('get', () => {
+  test('default', () => {
+    expectTypeOf(Engine.get()).toEqualTypeOf<Engine.Engine>()
+  })
+})
+
+describe('reset', () => {
+  test('accepts a slot name', () => {
+    expectTypeOf(Engine.reset)
+      .parameter(0)
+      .toEqualTypeOf<keyof Engine.Engine | undefined>()
+  })
+})
+
+describe('with', () => {
+  test('preserves the return type', () => {
+    expectTypeOf(Engine.with({}, () => 1 as const)).toEqualTypeOf<1>()
+  })
+})
+
+describe('Engine', () => {
+  test('the Secp256k1 and P256 slots share the Ecdsa contract', () => {
+    expectTypeOf<Engine.Engine['Secp256k1']>().toEqualTypeOf<
+      Engine.Ecdsa | undefined
+    >()
+    expectTypeOf<Engine.Engine['P256']>().toEqualTypeOf<
+      Engine.Ecdsa | undefined
+    >()
+  })
+
+  test('every slot is optional', () => {
+    expectTypeOf<Engine.Engine>().toEqualTypeOf<Partial<Engine.Engine>>()
+  })
+
+  test('contracts speak raw bytes, not branded ox types', () => {
+    expectTypeOf<NonNullable<Engine.Hash['keccak256']>>().toEqualTypeOf<
+      (input: Uint8Array) => Uint8Array
+    >()
+  })
+})