ox 0.14.17 → 0.14.18

package/tempo/VirtualAddress.ts

@@ -0,0 +1,201 @@
+import * as Address from '../core/Address.js'
+import * as Bytes from '../core/Bytes.js'
+import * as Errors from '../core/Errors.js'
+import * as Hex from '../core/Hex.js'
+import * as TempoAddress from './TempoAddress.js'
+
+/** Fixed 10-byte marker used by TIP-1022 virtual addresses. */
+export const magic = '0xfdfdfdfdfdfdfdfdfdfd' as const
+
+/** A fixed-width virtual address component. */
+export type Part = Hex.Hex | Bytes.Bytes | number | bigint
+
+/**
+ * Builds a TIP-1022 virtual address from a `masterId` and `userTag`.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * TIP-1022 encodes virtual addresses as:
+ * `[4-byte masterId][10-byte VIRTUAL_MAGIC][6-byte userTag]`
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualAddress } from 'ox/tempo'
+ *
+ * const address = VirtualAddress.from({
+ *   masterId: '0x58e21090',
+ *   userTag: '0x010203040506',
+ * })
+ *
+ * address
+ * // @log: '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506'
+ * ```
+ *
+ * @param value - The virtual address parts.
+ * @returns The virtual address.
+ */
+export function from(value: from.Value): Address.Address {
+  return Address.from(
+    Hex.concat(
+      toFixedHex(value.masterId, 4),
+      magic,
+      toFixedHex(value.userTag, 6),
+    ),
+  )
+}
+
+export declare namespace from {
+  type Value = {
+    /** 4-byte master identifier. */
+    masterId: Part
+    /** 6-byte opaque user tag. */
+    userTag: Part
+  }
+
+  type ErrorType =
+    | Address.from.ErrorType
+    | Bytes.padLeft.ErrorType
+    | Hex.assert.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Hex.fromNumber.ErrorType
+    | Hex.padLeft.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Checks whether an address matches the TIP-1022 virtual address format.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * This only checks the reserved byte layout, not whether the `masterId`
+ * is registered onchain.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualAddress } from 'ox/tempo'
+ *
+ * const isVirtual = VirtualAddress.isVirtual(
+ *   '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506',
+ * )
+ *
+ * isVirtual
+ * // @log: true
+ * ```
+ *
+ * @param address - Address to check.
+ * @returns `true` if the address matches the virtual-address layout.
+ */
+export function isVirtual(address: string): boolean {
+  try {
+    const resolved = resolveAddress(address)
+    return Hex.slice(resolved, 4, 14).toLowerCase() === magic
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Parses a TIP-1022 virtual address into its `masterId` and `userTag` parts.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualAddress } from 'ox/tempo'
+ *
+ * const parsed = VirtualAddress.parse(
+ *   '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506',
+ * )
+ *
+ * parsed
+ * // @log: { masterId: '0x58e21090', userTag: '0x010203040506' }
+ * ```
+ *
+ * @param address - The virtual address to parse.
+ * @returns The decoded virtual address components.
+ */
+export function parse(address: string): parse.ReturnType {
+  const resolved = resolveAddress(address)
+
+  if (Hex.slice(resolved, 4, 14).toLowerCase() !== magic)
+    throw new InvalidMagicError({ address: resolved })
+
+  return {
+    masterId: Hex.slice(resolved, 0, 4),
+    userTag: Hex.slice(resolved, 14, 20),
+  }
+}
+
+export declare namespace parse {
+  type ReturnType = {
+    /** 4-byte master identifier. */
+    masterId: Hex.Hex
+    /** 6-byte opaque user tag. */
+    userTag: Hex.Hex
+  }
+
+  type ErrorType =
+    | Address.assert.ErrorType
+    | InvalidMagicError
+    | TempoAddress.parse.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Validates that an address matches the TIP-1022 virtual address format.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * This only validates the reserved byte layout, not whether the `masterId`
+ * resolves to a registered master onchain.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualAddress } from 'ox/tempo'
+ *
+ * const valid = VirtualAddress.validate(
+ *   '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506',
+ * )
+ *
+ * valid
+ * // @log: true
+ * ```
+ *
+ * @param address - Address to validate.
+ * @returns `true` if the address has a valid virtual-address layout.
+ */
+export function validate(address: string): boolean {
+  try {
+    parse(address)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Thrown when an address does not contain the TIP-1022 virtual marker. */
+export class InvalidMagicError extends Errors.BaseError {
+  override readonly name = 'VirtualAddress.InvalidMagicError'
+
+  constructor({ address }: { address: string }) {
+    super(
+      `Address "${address}" does not contain the TIP-1022 virtual address marker.`,
+    )
+  }
+}
+
+function resolveAddress(address: string): Address.Address {
+  const resolved = TempoAddress.resolve(address as TempoAddress.Address)
+  Address.assert(resolved, { strict: false })
+  return resolved
+}
+
+function toFixedHex(value: Part, size: number): Hex.Hex {
+  if (typeof value === 'number' || typeof value === 'bigint')
+    return Hex.fromNumber(value, { size })
+  if (typeof value === 'string') {
+    Hex.assert(value, { strict: true })
+    return Hex.padLeft(value, size)
+  }
+  return Hex.fromBytes(Bytes.padLeft(value, size))
+}

package/tempo/VirtualMaster/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../../_types/tempo/VirtualMaster.d.ts",
+  "main": "../../_cjs/tempo/VirtualMaster.js",
+  "module": "../../_esm/tempo/VirtualMaster.js"
+}

package/tempo/VirtualMaster.test.ts

@@ -0,0 +1,127 @@
+import { TempoAddress, VirtualMaster } from 'ox/tempo'
+import { describe, expect, test } from 'vitest'
+
+const address = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+const tempoAddress = TempoAddress.format(address)
+const salt =
+  '0x00000000000000000000000000000000000000000000000000000000abf52baf'
+const masterId = '0x58e21090'
+const registrationHash =
+  '0x0000000058e21090d8f4bee424b90cddc2378aefa1bbbfa1443631a929ae966d'
+const virtualAddress = '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506'
+const tip20Address = '0x20c0000000000000000000000000000000000001'
+
+describe('getRegistrationHash', () => {
+  test('raw address', () => {
+    expect(
+      VirtualMaster.getRegistrationHash({
+        address,
+        salt,
+      }),
+    ).toBe(registrationHash)
+  })
+
+  test('tempo address', () => {
+    expect(
+      VirtualMaster.getRegistrationHash({
+        address: tempoAddress,
+        salt,
+      }),
+    ).toBe(registrationHash)
+  })
+})
+
+describe('getMasterId', () => {
+  test('default', () => {
+    expect(
+      VirtualMaster.getMasterId({
+        address,
+        salt,
+      }),
+    ).toBe(masterId)
+  })
+})
+
+describe('validateSalt', () => {
+  test('returns true for valid salt', () => {
+    expect(VirtualMaster.validateSalt({ address, salt })).toBe(true)
+  })
+
+  test('returns false for invalid salt', () => {
+    expect(VirtualMaster.validateSalt({ address, salt: 0n })).toBe(false)
+  })
+})
+
+describe('mineSalt', () => {
+  test('finds the first salt in range with the default keccak path', () => {
+    expect(
+      VirtualMaster.mineSalt({
+        address,
+        count: 16,
+        start: 0xabf52ba0n,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "masterId": "0x58e21090",
+        "registrationHash": "0x0000000058e21090d8f4bee424b90cddc2378aefa1bbbfa1443631a929ae966d",
+        "salt": "0x00000000000000000000000000000000000000000000000000000000abf52baf",
+      }
+    `)
+  })
+
+  test('returns undefined when no salt is found in range', () => {
+    expect(
+      VirtualMaster.mineSalt({
+        address,
+        count: 1,
+        start: 0n,
+      }),
+    ).toBeUndefined()
+  })
+
+  test('throws for a non-integer count', () => {
+    expect(() =>
+      VirtualMaster.mineSalt({
+        address,
+        count: 1.5,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[BaseError: Count "1.5" is invalid. Expected a positive safe integer.]`,
+    )
+  })
+
+  test('throws for a non-finite count', () => {
+    expect(() =>
+      VirtualMaster.mineSalt({
+        address,
+        count: Number.POSITIVE_INFINITY,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[BaseError: Count "Infinity" is invalid. Expected a positive safe integer.]`,
+    )
+  })
+
+  test.each([
+    ['zero address', '0x0000000000000000000000000000000000000000'],
+    ['virtual address', virtualAddress],
+    ['TIP-20 token address', tip20Address],
+  ])('rejects %s as a virtual master', (_label, invalidAddress) => {
+    expect(() =>
+      VirtualMaster.mineSalt({
+        address: invalidAddress as VirtualMaster.mineSalt.Value['address'],
+        count: 1,
+      }),
+    ).toThrowError()
+  })
+})
+
+test('exports', () => {
+  expect(Object.keys(VirtualMaster)).toMatchInlineSnapshot(`
+    [
+      "getRegistrationHash",
+      "getMasterId",
+      "validateSalt",
+      "mineSalt",
+    ]
+  `)
+})

package/tempo/VirtualMaster.ts

@@ -0,0 +1,303 @@
+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 TempoAddress from './TempoAddress.js'
+import * as VirtualAddress from './VirtualAddress.js'
+
+const tip20Prefix = '0x20c000000000000000000000'
+const zeroAddress = '0x0000000000000000000000000000000000000000'
+
+/** A valid salt input for TIP-1022 master registration. */
+export type Salt = Hex.Hex | Bytes.Bytes | number | bigint
+
+/**
+ * Computes the TIP-1022 registration hash for a master address and salt.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * The registration hash is `keccak256(masterAddress || salt)` where `salt`
+ * is encoded as a 32-byte value.
+ *
+ * Master addresses must satisfy TIP-1022 registration constraints: they cannot
+ * be the zero address, another virtual address, or a TIP-20 token address.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualMaster } from 'ox/tempo'
+ *
+ * const hash = VirtualMaster.getRegistrationHash({
+ *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ * })
+ *
+ * hash
+ * // @log: '0x0000000058e21090d8f4bee424b90cddc2378aefa1bbbfa1443631a929ae966d'
+ * ```
+ *
+ * @param value - Master address and salt.
+ * @returns The registration hash.
+ */
+export function getRegistrationHash(value: getRegistrationHash.Value): Hex.Hex {
+  return Hash.keccak256(
+    Hex.concat(resolveAddress(value.address), toFixedHex(value.salt, 32)),
+  )
+}
+
+export declare namespace getRegistrationHash {
+  type Value = {
+    /** Master address. Accepts both hex and Tempo addresses. */
+    address: TempoAddress.Address
+    /** 32-byte salt used for registration. */
+    salt: Salt
+  }
+
+  type ErrorType =
+    | Address.assert.ErrorType
+    | Bytes.padLeft.ErrorType
+    | Errors.BaseError
+    | Hash.keccak256.ErrorType
+    | Hex.assert.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Hex.fromNumber.ErrorType
+    | Hex.padLeft.ErrorType
+    | TempoAddress.parse.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Derives the 4-byte TIP-1022 `masterId` from a master address and salt.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * This returns bytes `[4:8]` of the registration hash, regardless of whether the
+ * salt satisfies the proof-of-work requirement.
+ *
+ * Master addresses must satisfy TIP-1022 registration constraints: they cannot
+ * be the zero address, another virtual address, or a TIP-20 token address.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualMaster } from 'ox/tempo'
+ *
+ * const masterId = VirtualMaster.getMasterId({
+ *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ * })
+ *
+ * masterId
+ * // @log: '0x58e21090'
+ * ```
+ *
+ * @param value - Master address and salt.
+ * @returns The derived master identifier.
+ */
+export function getMasterId(value: getMasterId.Value): Hex.Hex {
+  return Hex.slice(getRegistrationHash(value), 4, 8)
+}
+
+export declare namespace getMasterId {
+  type Value = getRegistrationHash.Value
+  type ErrorType = getRegistrationHash.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Validates that a salt satisfies the TIP-1022 32-bit proof-of-work requirement.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * Returns `false` for invalid master addresses, including the zero address,
+ * virtual addresses, and TIP-20 token addresses.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualMaster } from 'ox/tempo'
+ *
+ * const valid = VirtualMaster.validateSalt({
+ *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ * })
+ *
+ * valid
+ * // @log: true
+ * ```
+ *
+ * @param value - Master address and salt.
+ * @returns `true` if the first 4 bytes of the registration hash are zero.
+ */
+export function validateSalt(value: validateSalt.Value): boolean {
+  try {
+    return hasProofOfWork(
+      Hash.keccak256(
+        Hex.concat(resolveAddress(value.address), toFixedHex(value.salt, 32)),
+        { as: 'Bytes' },
+      ),
+    )
+  } catch {
+    return false
+  }
+}
+
+export declare namespace validateSalt {
+  type Value = getRegistrationHash.Value
+}
+
+/**
+ * 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)
+ *
+ * This is intentionally a small, deterministic primitive. It does not coordinate
+ * workers or async execution. Callers that need large searches can shard ranges
+ * externally.
+ *
+ * Master addresses must satisfy TIP-1022 registration constraints: they cannot
+ * be the zero address, another virtual address, or a TIP-20 token address.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualMaster } from 'ox/tempo'
+ *
+ * const result = VirtualMaster.mineSalt({
+ *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   start: 0xabf52ba0n,
+ *   count: 16,
+ * })
+ *
+ * result?.salt
+ * // @log: '0x00000000000000000000000000000000000000000000000000000000abf52baf'
+ * ```
+ *
+ * @param value - Search range parameters.
+ * @returns The first matching salt in the range, if any.
+ */
+export function mineSalt(
+  value: mineSalt.Value,
+): mineSalt.ReturnType | undefined {
+  assertCount(value.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)
+  input.set(addressBytes)
+
+  for (let i = 0; i < value.count; i++) {
+    input.set(saltBytes, addressBytes.length)
+
+    const registrationHash = Hash.keccak256(input, { as: 'Bytes' })
+
+    if (hasProofOfWork(registrationHash)) {
+      return {
+        masterId: Hex.fromBytes(registrationHash.subarray(4, 8)),
+        registrationHash: Hex.fromBytes(registrationHash),
+        salt: Hex.fromBytes(saltBytes),
+      }
+    }
+
+    if (i < value.count - 1 && !increment(saltBytes)) break
+  }
+
+  return undefined
+}
+
+export declare namespace mineSalt {
+  type Value = {
+    /** Master address. Accepts both hex and Tempo addresses. */
+    address: TempoAddress.Address
+    /** Number of consecutive salts to try. */
+    count: number
+    /** Starting salt value. @default 0n */
+    start?: Salt | undefined
+  }
+
+  type ReturnType = {
+    /** The 4-byte master identifier derived from the matching salt. */
+    masterId: Hex.Hex
+    /** The matching registration hash. */
+    registrationHash: Hex.Hex
+    /** The discovered 32-byte salt. */
+    salt: Hex.Hex
+  }
+
+  type ErrorType =
+    | Address.assert.ErrorType
+    | Bytes.fromHex.ErrorType
+    | Bytes.padLeft.ErrorType
+    | Errors.BaseError
+    | Hash.keccak256.ErrorType
+    | Hex.assert.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Hex.fromNumber.ErrorType
+    | Hex.padLeft.ErrorType
+    | TempoAddress.parse.ErrorType
+    | Errors.GlobalErrorType
+}
+
+function hasProofOfWork(hash: Bytes.Bytes): boolean {
+  return hash[0] === 0 && hash[1] === 0 && hash[2] === 0 && hash[3] === 0
+}
+
+function assertCount(count: number) {
+  if (Number.isSafeInteger(count) && count > 0) return
+
+  throw new Errors.BaseError(
+    `Count "${count}" is invalid. Expected a positive safe integer.`,
+  )
+}
+
+function increment(bytes: Bytes.Bytes): boolean {
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    const value = bytes[i]!
+    if (value === 0xff) {
+      bytes[i] = 0
+      continue
+    }
+
+    bytes[i] = value + 1
+    return true
+  }
+
+  return false
+}
+
+function resolveAddress(address: string): Address.Address {
+  const resolved = TempoAddress.resolve(address as TempoAddress.Address)
+  Address.assert(resolved, { strict: false })
+  assertValidMasterAddress(resolved)
+  return resolved
+}
+
+function assertValidMasterAddress(address: Address.Address) {
+  const normalized = address.toLowerCase()
+
+  if (normalized === zeroAddress)
+    throw new Errors.BaseError(
+      'Virtual master address cannot be the zero address.',
+    )
+
+  if (VirtualAddress.isVirtual(address))
+    throw new Errors.BaseError(
+      'Virtual master address cannot itself be a virtual address.',
+    )
+
+  if (normalized.startsWith(tip20Prefix))
+    throw new Errors.BaseError(
+      'Virtual master address cannot be a TIP-20 token address.',
+    )
+}
+
+function toFixedBytes(value: Salt, size: number): Bytes.Bytes {
+  return Bytes.fromHex(toFixedHex(value, size))
+}
+
+function toFixedHex(value: Salt, size: number): Hex.Hex {
+  if (typeof value === 'number' || typeof value === 'bigint')
+    return Hex.fromNumber(value, { size })
+  if (typeof value === 'string') {
+    Hex.assert(value, { strict: true })
+    return Hex.padLeft(value, size)
+  }
+  return Hex.fromBytes(Bytes.padLeft(value, size))
+}

package/tempo/e2e.test.ts

@@ -3,7 +3,6 @@ import {
   Address,
   Hex,
   P256,
-  RpcTransport,
   Secp256k1,
   Value,
   WebAuthnP256,
@@ -17,7 +16,6 @@ import {
   KeyAuthorization,
   Period,
   SignatureEnvelope,
-  ZoneRpcAuthentication,
 } from './index.js'
 import * as Transaction from './Transaction.js'
 import * as TransactionReceipt from './TransactionReceipt.js'

package/tempo/index.ts

@@ -369,6 +369,58 @@ export * as TransactionRequest from './TransactionRequest.js'
  * @category Reference
  */
 export * as TxEnvelopeTempo from './TxEnvelopeTempo.js'
+/**
+ * TIP-1022 virtual address encoding and parsing utilities.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * Virtual addresses reserve the following 20-byte layout:
+ * `[4-byte masterId][10-byte VIRTUAL_MAGIC][6-byte userTag]`.
+ * These helpers only operate on the reserved byte layout and do not query
+ * onchain registration state.
+ *
+ * @example
+ * ```ts twoslash
+ * import { TempoAddress, VirtualAddress } from 'ox/tempo'
+ *
+ * const masterId = '0x58e21090' // derived when the master registers
+ * const userTag = '0x010203040506' // operator-defined deposit identifier
+ *
+ * const address = VirtualAddress.from({
+ *   masterId,
+ *   userTag,
+ * })
+ *
+ * const tempoAddress = TempoAddress.format(address) // optional display format
+ * ```
+ *
+ * @category Reference
+ */
+export * as VirtualAddress from './VirtualAddress.js'
+/**
+ * TIP-1022 master registration utilities.
+ *
+ * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
+ *
+ * These utilities expose deterministic hashing and bounded salt mining helpers for
+ * `registerVirtualMaster(bytes32 salt)` without introducing any extra hashing dependency.
+ *
+ * @example
+ * ```ts twoslash
+ * import { VirtualMaster } from 'ox/tempo'
+ *
+ * const registration = {
+ *   address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+ *   salt: '0x00000000000000000000000000000000000000000000000000000000abf52baf',
+ * }
+ *
+ * const registrationHash = VirtualMaster.getRegistrationHash(registration) // keccak256(address || salt)
+ * const masterId = VirtualMaster.getMasterId(registration) // bytes [4:8] of the hash
+ * ```
+ *
+ * @category Reference
+ */
+export * as VirtualMaster from './VirtualMaster.js'
 /**
  * Zone ID utilities for converting between zone IDs and zone chain IDs.
  *