ox 0.14.18 → 0.14.19

package/tempo/VirtualMaster.test.ts

@@ -115,6 +115,82 @@ describe('mineSalt', () => {
   })
 })
 
+describe('mineSaltAsync', () => {
+  test('finds the same salt as the sync version', async () => {
+    const result = await VirtualMaster.mineSaltAsync({
+      address,
+      count: 16,
+      start: 0xabf52ba0n,
+      workers: 1,
+    })
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "masterId": "0x58e21090",
+        "registrationHash": "0x0000000058e21090d8f4bee424b90cddc2378aefa1bbbfa1443631a929ae966d",
+        "salt": "0x00000000000000000000000000000000000000000000000000000000abf52baf",
+      }
+    `)
+  })
+
+  test('finds the same salt with workers', async () => {
+    const result = await VirtualMaster.mineSaltAsync({
+      address,
+      count: 16,
+      start: 0xabf52ba0n,
+      workers: 2,
+    })
+
+    expect(result).toEqual({
+      masterId: '0x58e21090',
+      registrationHash:
+        '0x0000000058e21090d8f4bee424b90cddc2378aefa1bbbfa1443631a929ae966d',
+      salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+    })
+  })
+
+  test('returns undefined when no salt is found', async () => {
+    const result = await VirtualMaster.mineSaltAsync({
+      address,
+      count: 1,
+      start: 0n,
+      workers: 1,
+    })
+
+    expect(result).toBeUndefined()
+  })
+
+  test('reports progress', async () => {
+    const progressCalls: VirtualMaster.mineSaltAsync.Progress[] = []
+
+    await VirtualMaster.mineSaltAsync({
+      address,
+      count: 16,
+      start: 0xabf52ba0n,
+      workers: 1,
+      chunkSize: 8,
+      onProgress: (p) => progressCalls.push({ ...p }),
+    })
+
+    expect(progressCalls.length).toBeGreaterThanOrEqual(1)
+    expect(progressCalls[0]!.workers).toBe(1)
+    expect(progressCalls[0]!.attempts).toBeGreaterThan(0)
+  })
+
+  test('supports AbortSignal cancellation', async () => {
+    const controller = new AbortController()
+    controller.abort()
+
+    await expect(
+      VirtualMaster.mineSaltAsync({
+        address,
+        count: 1_000_000,
+        signal: controller.signal,
+      }),
+    ).rejects.toThrow()
+  })
+})
+
 test('exports', () => {
   expect(Object.keys(VirtualMaster)).toMatchInlineSnapshot(`
     [
@@ -122,6 +198,7 @@ test('exports', () => {
       "getMasterId",
       "validateSalt",
       "mineSalt",
+      "mineSaltAsync",
     ]
   `)
 })

package/tempo/VirtualMaster.ts

@@ -1,8 +1,10 @@
+import { keccak_256 } from '@noble/hashes/sha3'
 import * as Address from '../core/Address.js'
 import * as Bytes from '../core/Bytes.js'
 import * as Errors from '../core/Errors.js'
 import * as Hash from '../core/Hash.js'
 import * as Hex from '../core/Hex.js'
+import * as VirtualMasterPool from './internal/virtualMasterPool.js'
 import * as TempoAddress from './TempoAddress.js'
 import * as VirtualAddress from './VirtualAddress.js'
 
@@ -25,11 +27,12 @@ export type Salt = Hex.Hex | Bytes.Bytes | number | bigint
  *
  * @example
  * ```ts twoslash
+ * import { Address, Hex } from 'ox'
  * import { VirtualMaster } from 'ox/tempo'
  *
  * const hash = VirtualMaster.getRegistrationHash({
- *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
- *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ *   address: Address.from('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'),
+ *   salt: Hex.from('0x00000000000000000000000000000000000000000000000000000000abf52baf'),
  * })
  *
  * hash
@@ -79,11 +82,12 @@ export declare namespace getRegistrationHash {
  *
  * @example
  * ```ts twoslash
+ * import { Address, Hex } from 'ox'
  * import { VirtualMaster } from 'ox/tempo'
  *
  * const masterId = VirtualMaster.getMasterId({
- *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
- *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ *   address: Address.from('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'),
+ *   salt: Hex.from('0x00000000000000000000000000000000000000000000000000000000abf52baf'),
  * })
  *
  * masterId
@@ -112,11 +116,12 @@ export declare namespace getMasterId {
  *
  * @example
  * ```ts twoslash
+ * import { Address, Hex } from 'ox'
  * import { VirtualMaster } from 'ox/tempo'
  *
  * const valid = VirtualMaster.validateSalt({
- *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
- *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ *   address: Address.from('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'),
+ *   salt: Hex.from('0x00000000000000000000000000000000000000000000000000000000abf52baf'),
  * })
  *
  * valid
@@ -146,7 +151,7 @@ export declare namespace validateSalt {
 /**
  * Searches a bounded range of salts for the first value that satisfies TIP-1022 PoW.
  *
- * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ * [TIP-1022](https://tips.sh/1022)
  *
  * This is intentionally a small, deterministic primitive. It does not coordinate
  * workers or async execution. Callers that need large searches can shard ranges
@@ -155,14 +160,21 @@ export declare namespace validateSalt {
  * Master addresses must satisfy TIP-1022 registration constraints: they cannot
  * be the zero address, another virtual address, or a TIP-20 token address.
  *
+ * :::warning
+ *
+ * It is strongly recommended to use {@link ox#VirtualMaster.(mineSaltAsync:function)} instead of this
+ * function. `mineSaltAsync` uses WASM-accelerated keccak256 with parallel
+ * workers and is a lot faster than the pure JS implementation used here.
+ *
+ * :::
+ *
  * @example
  * ```ts twoslash
+ * import { Address } from 'ox'
  * import { VirtualMaster } from 'ox/tempo'
  *
  * const result = VirtualMaster.mineSalt({
  *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
- *   start: 0xabf52ba0n,
- *   count: 16,
  * })
  *
  * result?.salt
@@ -175,28 +187,30 @@ export declare namespace validateSalt {
 export function mineSalt(
   value: mineSalt.Value,
 ): mineSalt.ReturnType | undefined {
-  assertCount(value.count)
+  const count = value.count ?? 2 ** 32
+
+  assertCount(count)
 
-  const address = resolveAddress(value.address)
-  const addressBytes = Bytes.fromHex(address)
-  const saltBytes = toFixedBytes(value.start ?? 0n, 32)
-  const input = new Uint8Array(addressBytes.length + saltBytes.length)
+  const addressBytes = Bytes.fromHex(resolveAddress(value.address))
+  const input = new Uint8Array(addressBytes.length + 32)
   input.set(addressBytes)
 
-  for (let i = 0; i < value.count; i++) {
-    input.set(saltBytes, addressBytes.length)
+  // Salt is a view into input — increment mutates input directly, no copy.
+  const saltView = input.subarray(addressBytes.length)
+  saltView.set(toFixedBytes(value.start ?? 0n, 32))
 
-    const registrationHash = Hash.keccak256(input, { as: 'Bytes' })
+  for (let i = 0; i < count; i++) {
+    const hash = keccak_256(input)
 
-    if (hasProofOfWork(registrationHash)) {
+    if (hash[0] === 0 && hash[1] === 0 && hash[2] === 0 && hash[3] === 0) {
       return {
-        masterId: Hex.fromBytes(registrationHash.subarray(4, 8)),
-        registrationHash: Hex.fromBytes(registrationHash),
-        salt: Hex.fromBytes(saltBytes),
+        masterId: Hex.fromBytes(hash.subarray(4, 8)),
+        registrationHash: Hex.fromBytes(hash),
+        salt: Hex.fromBytes(saltView),
       }
     }
 
-    if (i < value.count - 1 && !increment(saltBytes)) break
+    if (i < count - 1 && !increment(saltView)) break
   }
 
   return undefined
@@ -207,7 +221,7 @@ export declare namespace mineSalt {
     /** Master address. Accepts both hex and Tempo addresses. */
     address: TempoAddress.Address
     /** Number of consecutive salts to try. */
-    count: number
+    count?: number | undefined
     /** Starting salt value. @default 0n */
     start?: Salt | undefined
   }
@@ -235,10 +249,379 @@ export declare namespace mineSalt {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Searches for a salt that satisfies TIP-1022 PoW using parallel workers and
+ * WASM-accelerated keccak256.
+ *
+ * [TIP-1022](https://tips.sh/1022)
+ *
+ * Uses WASM-accelerated keccak256 with parallel
+ * workers when available. Falls back to chunked single-threaded mining in
+ * environments without worker support.
+ *
+ * - **Node.js / Bun / Deno**: Spawns `worker_threads` with inline WASM keccak256.
+ * - **Browsers**: Spawns Web Workers via Blob URLs with inline WASM keccak256.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Address } from 'ox'
+ * import { VirtualMaster } from 'ox/tempo'
+ *
+ * const result = await VirtualMaster.mineSaltAsync({
+ *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ * })
+ * ```
+ *
+ * @param parameters - Search parameters.
+ * @returns The first matching salt, if any.
+ */
+export async function mineSaltAsync(
+  parameters: mineSaltAsync.Parameters,
+): Promise<mineSalt.ReturnType | undefined> {
+  const {
+    chunkSize = 100_000,
+    count = 2 ** 32,
+    onProgress,
+    signal,
+    start: start_ = 0n,
+    workers = getDefaultWorkerCount(),
+  } = parameters
+
+  const address = resolveAddress(parameters.address)
+  const start = toFixedHex(start_, 32)
+
+  assertCount(count)
+  if (workers !== undefined) assertWorkers(workers)
+  throwIfAborted(signal)
+
+  const workerCount = Math.max(
+    1,
+    Math.min(workers, Math.ceil(count / chunkSize)),
+  )
+
+  if (workerCount <= 1)
+    return mineSaltAsyncFallback({
+      address,
+      chunkSize,
+      count,
+      onProgress,
+      signal,
+      start,
+    })
+
+  const pool = await VirtualMasterPool.resolve()
+  if (!pool)
+    return mineSaltAsyncFallback({
+      address,
+      chunkSize,
+      count,
+      onProgress,
+      signal,
+      start,
+    })
+
+  return mineSaltWithWorkerPool({
+    address,
+    chunkSize,
+    count,
+    onProgress,
+    pool,
+    signal,
+    start,
+    workerCount,
+  })
+}
+
+export declare namespace mineSaltAsync {
+  type Parameters = {
+    /** Master address. Accepts both hex and Tempo addresses. */
+    address: TempoAddress.Address
+    /**
+     * Number of salts each worker processes before sending a progress update.
+     *
+     * @default 100_000
+     */
+    chunkSize?: number | undefined
+    /** Number of consecutive salts to try. @default 2 ** 32 */
+    count?: number | undefined
+    /** Progress callback invoked after each completed chunk. */
+    onProgress?: ((progress: Progress) => void) | undefined
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal | undefined
+    /** Starting salt value. @default 0n */
+    start?: Salt | undefined
+    /**
+     * Number of workers to use.
+     *
+     * Set to `0` or `1` to disable worker parallelism.
+     *
+     * @default os.availableParallelism() - 1
+     */
+    workers?: number | undefined
+  }
+
+  type Progress = {
+    /** Total attempts so far. */
+    attempts: number
+    /** Configured chunk size. */
+    chunkSize: number
+    /** Total count requested. */
+    count: number
+    /** Elapsed time in milliseconds. */
+    elapsed: number
+    /** Fraction complete (0–1). */
+    progress: number
+    /** Hashes per second. */
+    rate: number
+    /** Number of workers in use. */
+    workers: number
+  }
+
+  type ErrorType =
+    | mineSalt.ErrorType
+    | Errors.BaseError
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Runs parallel salt mining across a worker pool.
+ *
+ * @internal
+ */
+// biome-ignore lint/correctness/noUnusedVariables: _
+function mineSaltWithWorkerPool(
+  value: mineSaltWithWorkerPool.Options,
+): Promise<mineSalt.ReturnType | undefined> {
+  const startedAt = Date.now()
+
+  return new Promise<mineSalt.ReturnType | undefined>((resolve, reject) => {
+    let settled = false
+    let attempts = 0
+    let completedWorkers = 0
+    const handles: { terminate(): void }[] = []
+
+    const emitProgress = () => {
+      if (!value.onProgress) return
+      const elapsed = Date.now() - startedAt
+      const seconds = elapsed / 1000
+      value.onProgress({
+        attempts,
+        chunkSize: value.chunkSize,
+        count: value.count,
+        elapsed,
+        progress: Math.min(1, attempts / value.count),
+        rate: seconds === 0 ? 0 : attempts / seconds,
+        workers: value.workerCount,
+      })
+    }
+
+    const terminateAll = () => {
+      for (const h of handles) h.terminate()
+    }
+
+    const succeed = (result: mineSalt.ReturnType | undefined) => {
+      if (settled) return
+      settled = true
+      value.signal?.removeEventListener('abort', onAbort)
+      terminateAll()
+      resolve(result)
+    }
+
+    const fail = (error: unknown) => {
+      if (settled) return
+      settled = true
+      value.signal?.removeEventListener('abort', onAbort)
+      terminateAll()
+      reject(
+        error instanceof Error
+          ? error
+          : new Errors.BaseError('Failed to mine virtual master salt.'),
+      )
+    }
+
+    const onMessage = (msg: VirtualMasterPool.Message) => {
+      if (settled) return
+      switch (msg.type) {
+        case 'found':
+          succeed(msg.result as mineSalt.ReturnType)
+          return
+        case 'progress':
+          attempts += msg.attempts
+          emitProgress()
+          return
+        case 'done':
+          completedWorkers++
+          if (completedWorkers === value.workerCount) succeed(undefined)
+          return
+        case 'error':
+          fail(new Errors.BaseError(msg.message))
+          return
+      }
+    }
+
+    const onAbort = () => fail(getAbortError(value.signal))
+    value.signal?.addEventListener('abort', onAbort, { once: true })
+
+    for (let i = 0; i < value.workerCount; i++) {
+      const handle = value.pool.spawn(i, onMessage, fail)
+      handles.push(handle)
+      handle.postMessage({
+        type: 'start',
+        address: value.address,
+        chunkSize: value.chunkSize,
+        count: value.count,
+        start: value.start,
+        workerCount: value.workerCount,
+        workerIndex: i,
+      })
+    }
+  })
+}
+
+declare namespace mineSaltWithWorkerPool {
+  type Options = {
+    /** Resolved master address. */
+    address: Address.Address
+    /** Salts per chunk before a progress update. */
+    chunkSize: number
+    /** Total number of salts to try. */
+    count: number
+    /** Progress callback. */
+    onProgress: mineSaltAsync.Parameters['onProgress']
+    /** Worker pool to distribute work across. */
+    pool: VirtualMasterPool.Pool
+    /** AbortSignal for cancellation. */
+    signal: AbortSignal | undefined
+    /** Starting salt as a hex string. */
+    start: Hex.Hex
+    /** Number of workers to use. */
+    workerCount: number
+  }
+}
+
+/**
+ * Single-threaded chunked fallback when no worker pool is available.
+ *
+ * @internal
+ */
+// biome-ignore lint/correctness/noUnusedVariables: _
+async function mineSaltAsyncFallback(
+  value: mineSaltAsyncFallback.Options,
+): Promise<mineSalt.ReturnType | undefined> {
+  const startedAt = Date.now()
+  const startBigInt = BigInt(value.start)
+
+  for (let offset = 0; offset < value.count; offset += value.chunkSize) {
+    throwIfAborted(value.signal)
+
+    const count = Math.min(value.chunkSize, value.count - offset)
+    const result = mineSalt({
+      address: value.address,
+      count,
+      start: startBigInt + BigInt(offset),
+    })
+
+    if (value.onProgress) {
+      const attempts = Math.min(value.count, offset + count)
+      const elapsed = Date.now() - startedAt
+      const seconds = elapsed / 1000
+      value.onProgress({
+        attempts,
+        chunkSize: value.chunkSize,
+        count: value.count,
+        elapsed,
+        progress: Math.min(1, attempts / value.count),
+        rate: seconds === 0 ? 0 : attempts / seconds,
+        workers: 1,
+      })
+    }
+
+    if (result) return result
+
+    // Yield to the event loop between chunks.
+    await new Promise<void>((r) => setTimeout(r, 0))
+  }
+
+  return undefined
+}
+
+declare namespace mineSaltAsyncFallback {
+  type Options = {
+    /** Resolved master address. */
+    address: Address.Address
+    /** Salts per chunk before yielding to the event loop. */
+    chunkSize: number
+    /** Total number of salts to try. */
+    count: number
+    /** Progress callback. */
+    onProgress: mineSaltAsync.Parameters['onProgress']
+    /** AbortSignal for cancellation. */
+    signal: AbortSignal | undefined
+    /** Starting salt as a hex string. */
+    start: Hex.Hex
+  }
+}
+
+/**
+ * Asserts that `workers` is a non-negative safe integer.
+ *
+ * @internal
+ */
+function assertWorkers(workers: number) {
+  if (Number.isSafeInteger(workers) && workers >= 0) return
+  throw new Errors.BaseError(
+    `Workers "${workers}" is invalid. Expected a non-negative safe integer.`,
+  )
+}
+
+/**
+ * Extracts or creates an error from an `AbortSignal`.
+ *
+ * @internal
+ */
+function getAbortError(signal?: AbortSignal): Error {
+  const reason = signal?.reason
+  if (reason instanceof Error) return reason
+  return new Errors.BaseError('The operation was aborted.')
+}
+
+/**
+ * Returns the default number of workers for the current platform.
+ *
+ * @internal
+ */
+function getDefaultWorkerCount(): number {
+  if (typeof navigator !== 'undefined') {
+    const c = navigator.hardwareConcurrency
+    if (c && c > 1) return c - 1
+  }
+  return 1
+}
+
+/**
+ * Throws the signal's abort reason if the signal is aborted.
+ *
+ * @internal
+ */
+function throwIfAborted(signal?: AbortSignal) {
+  if (!signal?.aborted) return
+  throw getAbortError(signal)
+}
+
+/**
+ * Returns `true` if the first 4 bytes of a hash are zero.
+ *
+ * @internal
+ */
 function hasProofOfWork(hash: Bytes.Bytes): boolean {
   return hash[0] === 0 && hash[1] === 0 && hash[2] === 0 && hash[3] === 0
 }
 
+/**
+ * Asserts that `count` is a positive safe integer.
+ *
+ * @internal
+ */
 function assertCount(count: number) {
   if (Number.isSafeInteger(count) && count > 0) return
 
@@ -247,6 +630,11 @@ function assertCount(count: number) {
   )
 }
 
+/**
+ * Increments a big-endian byte array by one. Returns `false` on overflow.
+ *
+ * @internal
+ */
 function increment(bytes: Bytes.Bytes): boolean {
   for (let i = bytes.length - 1; i >= 0; i--) {
     const value = bytes[i]!
@@ -262,6 +650,11 @@ function increment(bytes: Bytes.Bytes): boolean {
   return false
 }
 
+/**
+ * Resolves a Tempo or hex address, validates it as a valid master.
+ *
+ * @internal
+ */
 function resolveAddress(address: string): Address.Address {
   const resolved = TempoAddress.resolve(address as TempoAddress.Address)
   Address.assert(resolved, { strict: false })
@@ -269,6 +662,11 @@ function resolveAddress(address: string): Address.Address {
   return resolved
 }
 
+/**
+ * Throws if the address is zero, virtual, or a TIP-20 token.
+ *
+ * @internal
+ */
 function assertValidMasterAddress(address: Address.Address) {
   const normalized = address.toLowerCase()
 
@@ -288,10 +686,20 @@ function assertValidMasterAddress(address: Address.Address) {
     )
 }
 
+/**
+ * Converts a salt to a fixed-size byte array.
+ *
+ * @internal
+ */
 function toFixedBytes(value: Salt, size: number): Bytes.Bytes {
   return Bytes.fromHex(toFixedHex(value, size))
 }
 
+/**
+ * Converts a salt to a zero-padded hex string of the given size.
+ *
+ * @internal
+ */
 function toFixedHex(value: Salt, size: number): Hex.Hex {
   if (typeof value === 'number' || typeof value === 'bigint')
     return Hex.fromNumber(value, { size })

package/tempo/index.ts

@@ -131,6 +131,7 @@ export * as PoolId from './PoolId.js'
  *
  * @example
  * ```ts twoslash
+ * import 'ox/window'
  * import { Provider, RpcSchema } from 'ox'
  * import { RpcSchemaTempo } from 'ox/tempo'
  *
@@ -407,11 +408,12 @@ export * as VirtualAddress from './VirtualAddress.js'
  *
  * @example
  * ```ts twoslash
+ * import { Address, Hex } from 'ox'
  * import { VirtualMaster } from 'ox/tempo'
  *
  * const registration = {
- *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
- *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ *   address: Address.from('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'),
+ *   salt: Hex.from('0x00000000000000000000000000000000000000000000000000000000abf52baf'),
  * }
  *
  * const registrationHash = VirtualMaster.getRegistrationHash(registration) // keccak256(address || salt)
@@ -421,6 +423,7 @@ export * as VirtualAddress from './VirtualAddress.js'
  * @category Reference
  */
 export * as VirtualMaster from './VirtualMaster.js'
+
 /**
  * Zone ID utilities for converting between zone IDs and zone chain IDs.
  *