ox 1.1.0 → 1.2.0

package/src/core/Hash.ts

@@ -3,6 +3,65 @@ import type * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
 import * as engine from './internal/hash.js'
 
+/**
+ * Calculates the [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ *
+ * Backed by `blake3` from [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), an audited & minimal JS hashing library, unless another implementation is installed with {@link ox#Engine.set}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.blake3('0xdeadbeef')
+ * // @log: '0x53147f3ce49ed4f60dfa5b9654c36ba6103c11f5737df3dabd4cbd296c4161bd'
+ * ```
+ *
+ * @example
+ * ### Configure Return Type
+ *
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.blake3('0xdeadbeef', { as: 'Bytes' })
+ * // @log: Uint8Array [...]
+ * ```
+ *
+ * @param value - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ * @param options - Options.
+ * @returns BLAKE3 hash.
+ */
+export function blake3<
+  value extends Hex.Hex | Bytes.Bytes,
+  as extends 'Hex' | 'Bytes' =
+    | (value extends Hex.Hex ? 'Hex' : never)
+    | (value extends Bytes.Bytes ? 'Bytes' : never),
+>(
+  value: value | Hex.Hex | Bytes.Bytes,
+  options: blake3.Options<as> = {},
+): blake3.ReturnType<as> {
+  const isBytes = value instanceof Uint8Array
+  const { as = isBytes ? 'Bytes' : 'Hex' } = options
+  const bytes = engine.blake3(isBytes ? value : Bytes.from(value))
+  if (as === 'Bytes') return bytes as never
+  return Hex.fromBytes(bytes) as never
+}
+
+export declare namespace blake3 {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** The return type. Defaults to the input format. */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Calculates the [Keccak256](https://en.wikipedia.org/wiki/SHA-3) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
  *

package/src/core/_test/Block.test.ts

@@ -400,9 +400,16 @@ describe('fromRpc', () => {
         method: 'eth_getBlockByNumber',
         params: ['latest', true],
       })
-      .then(Block.fromRpc)
+      .then((block) => Block.fromRpc(block, { includeTransactions: true }))
 
-    expect(block).toMatchSnapshot()
+    const transactions = block?.transactions.map((transaction) => {
+      const { blockTimestamp: _, ...transaction_ } = {
+        blockTimestamp: undefined,
+        ...transaction,
+      }
+      return transaction_
+    })
+    expect({ ...block, transactions }).toMatchSnapshot()
   })
 })
 

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

@@ -17,6 +17,62 @@ type Unlisted = {
   >
 }[keyof Engine.Engine]
 
+describe('install', () => {
+  test('accepts raw and promised slots and preserves their resolved shape', () => {
+    const keccak256 = (input: Uint8Array) => input
+    const toSeed = (_mnemonic: string) => new Uint8Array(64)
+
+    expectTypeOf(
+      Engine.install({
+        Hash: Promise.resolve({ keccak256 }),
+        Mnemonic: { toSeed },
+      }),
+    ).toEqualTypeOf<
+      Promise<{
+        Hash: { keccak256: typeof keccak256 }
+        Mnemonic: { toSeed: typeof toSeed }
+      }>
+    >()
+  })
+
+  test('rejects an unknown slot', () => {
+    // @ts-expect-error
+    void Engine.install({ Keccak: Promise.resolve({}) })
+  })
+
+  test('rejects an unknown slot alongside a valid slot', () => {
+    void Engine.install({
+      Hash: { keccak256: (input) => input },
+      // @ts-expect-error
+      Keccak: {},
+    })
+  })
+
+  test('rejects a misspelled function', () => {
+    void Engine.install({
+      // @ts-expect-error
+      Hash: Promise.resolve({ keccak_256: (input: Uint8Array) => input }),
+    })
+  })
+
+  test('rejects a misspelled function alongside a valid function', () => {
+    void Engine.install({
+      // @ts-expect-error
+      Hash: {
+        keccak256: (input: Uint8Array) => input,
+        keccak_256: (input: Uint8Array) => input,
+      },
+    })
+  })
+
+  test('rejects a mistyped promised function', () => {
+    void Engine.install({
+      // @ts-expect-error
+      Hash: Promise.resolve({ keccak256: (input: string) => input }),
+    })
+  })
+})
+
 describe('set', () => {
   test('accepts a partial engine', () => {
     expectTypeOf(Engine.set).parameter(0).toEqualTypeOf<Engine.Engine>()

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

@@ -38,6 +38,101 @@ function merkelize() {
   return BinaryStateTree.merkelize(tree)
 }
 
+describe('install', () => {
+  test('behavior: resolves slots in parallel and installs them atomically', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    const sign = () => new Uint8Array(65).fill(3)
+    const toSeed = () => new Uint8Array(64).fill(2)
+    let releaseHash: (() => void) | undefined
+
+    Engine.set({ Secp256k1: { sign } })
+
+    const hash = {
+      // oxlint-disable-next-line unicorn/no-thenable -- Distinguishes parallel resolution from sequential awaits.
+      then(
+        resolve: (value: Engine.Hash) => void,
+        reject: (reason: unknown) => void,
+      ) {
+        const timeout = setTimeout(
+          () => reject(new Error('slots resolved serially')),
+          0,
+        )
+        releaseHash = () => {
+          clearTimeout(timeout)
+          resolve({ keccak256 })
+        }
+      },
+    } as unknown as PromiseLike<Engine.Hash>
+    const mnemonic = {
+      // oxlint-disable-next-line unicorn/no-thenable -- Distinguishes parallel resolution from sequential awaits.
+      then(resolve: (value: Engine.Mnemonic) => void) {
+        resolve({ toSeed })
+        releaseHash?.()
+      },
+    } as unknown as PromiseLike<Engine.Mnemonic>
+
+    const installed = await Engine.install({ Hash: hash, Mnemonic: mnemonic })
+
+    expect(installed).toEqual({
+      Hash: { keccak256 },
+      Mnemonic: { toSeed },
+    })
+    expect(Engine.get()).toEqual({
+      ...installed,
+      Secp256k1: { sign },
+    })
+  })
+
+  test('behavior: a rejected slot leaves the previous engine installed', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    Engine.set({ Hash: { keccak256 } })
+
+    await expect(
+      Engine.install({
+        Hash: Promise.resolve({
+          sha256: () => new Uint8Array(32).fill(2),
+        }),
+        Mnemonic: Promise.reject(new Error('could not load engine')),
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: could not load engine]`,
+    )
+    expect(Engine.get()).toEqual({ Hash: { keccak256 } })
+  })
+
+  test('behavior: an invalid resolved engine leaves the previous engine installed', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    Engine.set({ Hash: { keccak256 } })
+
+    await expect(
+      Engine.install({
+        Hash: Promise.resolve({
+          sha256: () => new Uint8Array(32).fill(2),
+        }),
+        Mnemonic: Promise.resolve({
+          to_seed: () => new Uint8Array(64),
+        }),
+      } as never),
+    ).rejects.toThrowError(Engine.UnknownPrimitiveError)
+    expect(Engine.get()).toEqual({ Hash: { keccak256 } })
+  })
+
+  test('behavior: a null resolved slot leaves the previous engine installed', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    Engine.set({ Hash: { keccak256 } })
+
+    await expect(
+      Engine.install({
+        Hash: Promise.resolve({
+          sha256: () => new Uint8Array(32).fill(2),
+        }),
+        Mnemonic: Promise.resolve(null),
+      } as never),
+    ).rejects.toThrowError(Engine.InvalidSlotValueError)
+    expect(Engine.get()).toEqual({ Hash: { keccak256 } })
+  })
+})
+
 describe('set', () => {
   test('behavior: empty engine is a no-op', () => {
     const before = Hash.keccak256(payload)

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

@@ -0,0 +1,18 @@
+import { type Bytes, Hash, type Hex } from 'ox'
+import { describe, expectTypeOf, test } from 'vp/test'
+
+describe('blake3', () => {
+  test('default', () => {
+    expectTypeOf(Hash.blake3('0x')).toEqualTypeOf<Hex.Hex>()
+    expectTypeOf(Hash.blake3(new Uint8Array())).toEqualTypeOf<Bytes.Bytes>()
+  })
+
+  test('as', () => {
+    expectTypeOf(
+      Hash.blake3('0x', { as: 'Bytes' }),
+    ).toEqualTypeOf<Bytes.Bytes>()
+    expectTypeOf(
+      Hash.blake3(new Uint8Array(), { as: 'Hex' }),
+    ).toEqualTypeOf<Hex.Hex>()
+  })
+})

package/src/core/_test/Hash.test.ts

@@ -1,6 +1,104 @@
-import { Hash } from 'ox'
+import { Engine, Hash } from 'ox'
 import { describe, expect, test } from 'vp/test'
 
+describe('blake3', () => {
+  test('default', () => {
+    expect(Hash.blake3('0x')).toMatchInlineSnapshot(
+      `"0xaf1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262"`,
+    )
+
+    expect(Hash.blake3(new Uint8Array())).toMatchInlineSnapshot(`
+      Uint8Array [
+        175,
+        19,
+        73,
+        185,
+        245,
+        249,
+        161,
+        166,
+        160,
+        64,
+        77,
+        234,
+        54,
+        220,
+        201,
+        73,
+        155,
+        203,
+        37,
+        201,
+        173,
+        193,
+        18,
+        183,
+        204,
+        154,
+        147,
+        202,
+        228,
+        31,
+        50,
+        98,
+      ]
+    `)
+  })
+
+  test('as: Hex', () => {
+    expect(Hash.blake3(new Uint8Array(), { as: 'Hex' })).toMatchInlineSnapshot(
+      `"0xaf1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262"`,
+    )
+  })
+
+  test('as: Bytes', () => {
+    expect(Hash.blake3('0x', { as: 'Bytes' })).toMatchInlineSnapshot(`
+      Uint8Array [
+        175,
+        19,
+        73,
+        185,
+        245,
+        249,
+        161,
+        166,
+        160,
+        64,
+        77,
+        234,
+        54,
+        220,
+        201,
+        73,
+        155,
+        203,
+        37,
+        201,
+        173,
+        193,
+        18,
+        183,
+        204,
+        154,
+        147,
+        202,
+        228,
+        31,
+        50,
+        98,
+      ]
+    `)
+  })
+
+  test('behavior: routes through the installed engine', () => {
+    Engine.set({ Hash: { blake3: () => new Uint8Array(32).fill(1) } })
+
+    expect(Hash.blake3('0x')).toMatchInlineSnapshot(
+      `"0x0101010101010101010101010101010101010101010101010101010101010101"`,
+    )
+  })
+})
+
 describe('hmac256', () => {
   test('default', () => {
     expect(
@@ -530,6 +628,7 @@ describe('validate', () => {
 test('exports', () => {
   expect(Object.keys(Hash)).toMatchInlineSnapshot(`
     [
+      "blake3",
       "keccak256",
       "hmac256",
       "ripemd160",

package/src/core/_test/Hash.vectors.test.ts

@@ -11,6 +11,13 @@ import * as vectors from '../../../test/vectors/hashes/index.js'
  * See `test/vectors/hashes/README.md`.
  */
 
+describe('blake3', () => {
+  test(`matches ${vectors.blake3.length} official BLAKE3 vectors`, () => {
+    for (const { digest, message } of vectors.blake3)
+      expect(Hash.blake3(message, { as: 'Bytes' })).toEqual(digest)
+  })
+})
+
 describe('sha256', () => {
   test(`matches ${vectors.sha256.length} NIST CAVP vectors`, () => {
     for (const { digest, message } of vectors.sha256)

package/src/core/_test/Transaction.test.ts

@@ -158,7 +158,11 @@ describe('fromRpc', () => {
         })
         .then(Transaction.fromRpc)
 
-      expect(transaction).toMatchInlineSnapshot(`
+      const { blockTimestamp: _, ...transaction_ } = {
+        blockTimestamp: undefined,
+        ...transaction,
+      }
+      expect(transaction_).toMatchInlineSnapshot(`
         {
           "blockHash": "0x8299a290ae51a8958965987e2caf178a09b8ecde01b737b5f9a8badbacb407cb",
           "blockNumber": 1110749n,
@@ -411,7 +415,12 @@ describe('fromRpc', () => {
           ],
         })
         .then(Transaction.fromRpc)
-      expect(transaction).toMatchInlineSnapshot(`
+
+      const { blockTimestamp: _, ...transaction_ } = {
+        blockTimestamp: undefined,
+        ...transaction,
+      }
+      expect(transaction_).toMatchInlineSnapshot(`
         {
           "accessList": [],
           "blockHash": "0xc350d807505fb835650f0013632c5515592987ba169bbc6626d9fc54d91f0f0b",

package/src/core/internal/engine.ts

@@ -263,21 +263,21 @@ export type Bls = {
  * @internal
  */
 export type Engine = {
-  /** Implementation for {@link ox#Bls}. */
+  /** Implementation for [`Bls`](/api/Bls). */
   Bls?: Bls | undefined
-  /** Implementation for {@link ox#Ed25519}. */
+  /** Implementation for [`Ed25519`](/api/Ed25519). */
   Ed25519?: Eddsa | undefined
-  /** Implementation for {@link ox#Hash}. */
+  /** Implementation for [`Hash`](/api/Hash). */
   Hash?: Hash | undefined
-  /** Implementation for {@link ox#Keystore}. */
+  /** Implementation for [`Keystore`](/api/Keystore). */
   Keystore?: Keystore | undefined
-  /** Implementation for {@link ox#Mnemonic}. */
+  /** Implementation for [`Mnemonic`](/api/Mnemonic). */
   Mnemonic?: Mnemonic | undefined
-  /** Implementation for {@link ox#P256}. */
+  /** Implementation for [`P256`](/api/P256). */
   P256?: Ecdsa | undefined
-  /** Implementation for {@link ox#Secp256k1}. */
+  /** Implementation for [`Secp256k1`](/api/Secp256k1). */
   Secp256k1?: Ecdsa | undefined
-  /** Implementation for {@link ox#X25519}. */
+  /** Implementation for [`X25519`](/api/X25519). */
   X25519?: Ecdh | undefined
 }
 

package/src/index.ts

@@ -1536,9 +1536,12 @@ export * as Ed25519 from './core/Ed25519.js'
  *
  * ```ts twoslash
  * // @noErrors
- * import { Engine } from 'ox/wasm'
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/wasm'
  *
- * await Engine.load()
+ * await Engine.install({
+ *   Hash: Hash.engine()
+ * })
  * ```
  *
  * @example

package/src/node/Ed25519.ts

@@ -0,0 +1,87 @@
+import * as crypto from 'node:crypto'
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+
+export * from '../core/Ed25519.js'
+
+const privateKeyPrefix = Buffer.from('302e020100300506032b657004220420', 'hex')
+
+/**
+ * Creates a Node.js implementation of the [`Ed25519`](/api/Ed25519) engine
+ * slot, without installing it.
+ *
+ * Node's verifier does not implement Ox's ZIP-215 verification semantics, so
+ * this engine deliberately omits `verify`. Public-key conversion and random
+ * key generation also remain on Ox's default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/node'
+ *
+ * await Engine.install({ Ed25519: Ed25519.engine() })
+ *
+ * Ed25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The raw `Ed25519` engine slot.
+ */
+export function engine(): Promise<engine.ReturnType> {
+  return Promise.resolve({
+    getPublicKey: (privateKey) =>
+      rawPublicKey(crypto.createPublicKey(toPrivateKey(privateKey))),
+    sign: (payload, privateKey) =>
+      new Uint8Array(crypto.sign(null, payload, toPrivateKey(privateKey))),
+    toMontgomerySecret: (privateKey) => {
+      assertLength(privateKey)
+      const digest = crypto.hash('sha512', privateKey, 'buffer')
+      try {
+        const secretKey = Uint8Array.from(digest.subarray(0, 32))
+        secretKey[0]! &= 248
+        secretKey[31]! &= 127
+        secretKey[31]! |= 64
+        return secretKey
+      } finally {
+        digest.fill(0)
+      }
+    },
+  })
+}
+
+export declare namespace engine {
+  /** Every `Ed25519` primitive this module implements. */
+  type ReturnType = {
+    [key in 'getPublicKey' | 'sign' | 'toMontgomerySecret']-?: NonNullable<
+      Engine.Eddsa[key]
+    >
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+function assertLength(key: Uint8Array): void {
+  if (key.length !== 32)
+    throw new RangeError(
+      `Ed25519 private key must be 32 bytes, got ${key.length}`,
+    )
+}
+
+function rawPublicKey(publicKey: crypto.KeyObject): Uint8Array {
+  const der = publicKey.export({ format: 'der', type: 'spki' })
+  return Uint8Array.from(der.subarray(-32))
+}
+
+function toPrivateKey(privateKey: Uint8Array): crypto.KeyObject {
+  assertLength(privateKey)
+  const der = Buffer.concat([privateKeyPrefix, privateKey])
+  try {
+    return crypto.createPrivateKey({
+      format: 'der',
+      key: der,
+      type: 'pkcs8',
+    })
+  } finally {
+    der.fill(0)
+  }
+}