ox 0.14.17 → 0.14.19

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,204 @@
+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()
+  })
+})
+
+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(`
+    [
+      "getRegistrationHash",
+      "getMasterId",
+      "validateSalt",
+      "mineSalt",
+      "mineSaltAsync",
+    ]
+  `)
+})