ox 0.13.0 → 0.13.2

package/tempo/SignatureEnvelope.ts

@@ -269,6 +269,119 @@ export declare namespace assert {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Extracts the address of the signer from a {@link ox#SignatureEnvelope.SignatureEnvelope}.
+ *
+ * - **secp256k1**: Recovers the address from the payload via `ecrecover`.
+ * - **p256** / **webAuthn**: Derives the address from the embedded public key.
+ * - **keychain**: Extracts from the inner signature (or returns `userAddress` if `user` is `true`).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ * import { SignatureEnvelope } from 'ox/tempo'
+ *
+ * const payload = '0xdeadbeef'
+ * const signature = Secp256k1.sign({ payload, privateKey: '0x...' })
+ * const envelope = SignatureEnvelope.from(signature)
+ *
+ * const address = SignatureEnvelope.extractAddress({ // [!code focus]
+ *   payload, // [!code focus]
+ *   signature: envelope, // [!code focus]
+ * }) // [!code focus]
+ * ```
+ *
+ * @param options - The extraction options.
+ * @returns The signer address.
+ */
+export function extractAddress(
+  options: extractAddress.Options,
+): extractAddress.ReturnType {
+  const { signature, root } = options
+  if (signature.type === 'keychain') {
+    if (root) return signature.userAddress
+    return extractAddress({ ...options, signature: signature.inner })
+  }
+  return Address.fromPublicKey(extractPublicKey(options))
+}
+
+export declare namespace extractAddress {
+  type Options = {
+    /** The sign payload that was signed (only required for secp256k1 signatures). */
+    payload: Hex.Hex | Bytes.Bytes
+    /** The signature envelope. */
+    signature: SignatureEnvelope
+    /** Whether to return the root `userAddress` for keychain signatures instead of extracting from the inner signature. */
+    root?: boolean | undefined
+  }
+
+  type ReturnType = Address.Address
+
+  type ErrorType =
+    | Address.fromPublicKey.ErrorType
+    | extractPublicKey.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Extracts the public key of the signer from a {@link ox#SignatureEnvelope.SignatureEnvelope}.
+ *
+ * - **secp256k1**: Recovers the public key from the payload via `ecrecover`.
+ * - **p256** / **webAuthn**: Returns the embedded public key.
+ * - **keychain**: Extracts from the inner signature.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ * import { SignatureEnvelope } from 'ox/tempo'
+ *
+ * const payload = '0xdeadbeef'
+ * const signature = Secp256k1.sign({ payload, privateKey: '0x...' })
+ * const envelope = SignatureEnvelope.from(signature)
+ *
+ * const publicKey = SignatureEnvelope.extractPublicKey({ // [!code focus]
+ *   payload, // [!code focus]
+ *   signature: envelope, // [!code focus]
+ * }) // [!code focus]
+ * ```
+ *
+ * @param options - The extraction options.
+ * @returns The signer's public key.
+ */
+export function extractPublicKey(
+  options: extractPublicKey.Options,
+): extractPublicKey.ReturnType {
+  const { payload, signature } = options
+
+  switch (signature.type) {
+    case 'secp256k1':
+      return ox_Secp256k1.recoverPublicKey({
+        payload,
+        signature: signature.signature,
+      })
+    case 'p256':
+    case 'webAuthn':
+      return signature.publicKey
+    case 'keychain':
+      return extractPublicKey({ payload, signature: signature.inner })
+  }
+}
+
+export declare namespace extractPublicKey {
+  type Options = {
+    /** The sign payload that was signed (only required for secp256k1 signatures). */
+    payload: Hex.Hex | Bytes.Bytes
+    /** The signature envelope. */
+    signature: SignatureEnvelope
+  }
+
+  type ReturnType = PublicKey.PublicKey
+
+  type ErrorType =
+    | ox_Secp256k1.recoverPublicKey.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Deserializes a hex-encoded signature envelope into a typed signature object.
  *

package/tempo/TempoAddress/package.json

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

package/tempo/TempoAddress.test.ts

@@ -0,0 +1,202 @@
+import { Address } from 'ox'
+import { TempoAddress } from 'ox/tempo'
+import { describe, expect, test } from 'vitest'
+
+const rawAddress = Address.checksum(
+  '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28',
+)
+
+describe('format', () => {
+  test('mainnet address', () => {
+    expect(TempoAddress.format(rawAddress)).toMatchInlineSnapshot(
+      `"tempo1wskntnrxxnq9x2f95wuyf0y7wk2l90fg8zd8djs"`,
+    )
+  })
+
+  test('zone address (zone ID = 1)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 1 }),
+    ).toMatchInlineSnapshot(`"tempoz1q96z6dwvvc6vq5efyk3ms39une6etu4a9zeqtx3q"`)
+  })
+
+  test('zone address (zone ID = 252)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 252 }),
+    ).toMatchInlineSnapshot(`"tempoz1l36z6dwvvc6vq5efyk3ms39une6etu4a9z8vgw44"`)
+  })
+
+  test('zone address (zone ID = 253)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 253 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1lh7sqapdxhxxvdxq2v5jtgacgj7fuav4727jsx0032us"`,
+    )
+  })
+
+  test('zone address (zone ID = 65535)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 65535 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1lhll7apdxhxxvdxq2v5jtgacgj7fuav4727j37cldu7q"`,
+    )
+  })
+
+  test('zone address (zone ID = 65536)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 65536 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1lcqqqqgqwskntnrxxnq9x2f95wuyf0y7wk2l90fga965qjc"`,
+    )
+  })
+
+  test('zone address (zone ID = 4294967295)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 4294967295 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1lmllllllwskntnrxxnq9x2f95wuyf0y7wk2l90fgxg58ulq"`,
+    )
+  })
+
+  test('zone address (zone ID > 4294967295)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: BigInt('4294967296') }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1luqqqqqqqyqqqqr5956uce35cpfjjfdrhpzte8n4jhet62pnyj7cc"`,
+    )
+  })
+
+  test('lowercase output', () => {
+    const result = TempoAddress.format(rawAddress)
+    expect(result).toBe(result.toLowerCase())
+  })
+})
+
+describe('parse', () => {
+  test('mainnet', () => {
+    const encoded = TempoAddress.format(rawAddress)
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": undefined,
+      }
+    `)
+  })
+
+  test('zone (zone ID = 1)', () => {
+    const encoded = TempoAddress.format(rawAddress, { zoneId: 1 })
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": 1n,
+      }
+    `)
+  })
+
+  test('zone (zone ID = 252)', () => {
+    const encoded = TempoAddress.format(rawAddress, { zoneId: 252 })
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": 252n,
+      }
+    `)
+  })
+
+  test('zone (zone ID = 253)', () => {
+    const encoded = TempoAddress.format(rawAddress, { zoneId: 253 })
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": 253n,
+      }
+    `)
+  })
+
+  test('zone (zone ID = 65535)', () => {
+    const encoded = TempoAddress.format(rawAddress, { zoneId: 65535 })
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": 65535n,
+      }
+    `)
+  })
+
+  test('zone (zone ID = 65536)', () => {
+    const encoded = TempoAddress.format(rawAddress, { zoneId: 65536 })
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": 65536n,
+      }
+    `)
+  })
+
+  test('zone (large zone ID)', () => {
+    const encoded = TempoAddress.format(rawAddress, {
+      zoneId: BigInt('18446744073709551615'),
+    })
+    expect(TempoAddress.parse(encoded)).toMatchInlineSnapshot(`
+      {
+        "address": "0x742d35CC6634c0532925a3B844bc9e7595F2Bd28",
+        "zoneId": 18446744073709551615n,
+      }
+    `)
+  })
+
+  test('case insensitive', () => {
+    const encoded = TempoAddress.format(rawAddress)
+    const upper = encoded.slice(0, 6) + encoded.slice(6).toUpperCase()
+    expect(TempoAddress.parse(upper).address).toBe(rawAddress)
+  })
+
+  test('error: invalid prefix', () => {
+    expect(() =>
+      TempoAddress.parse('bitcoin1abc'),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[TempoAddress.InvalidPrefixError: Tempo address "bitcoin1abc" has an invalid prefix. Expected "tempo1" or "tempoz1".]`,
+    )
+  })
+
+  test('error: invalid checksum', () => {
+    const encoded = TempoAddress.format(rawAddress)
+    const tampered = encoded.slice(0, -1) + (encoded.endsWith('q') ? 'p' : 'q')
+    expect(() =>
+      TempoAddress.parse(tampered),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[TempoAddress.InvalidChecksumError: Tempo address "${tampered}" has an invalid checksum.]`,
+    )
+  })
+
+  test('error: prefix swap detected', () => {
+    const mainnet = TempoAddress.format(rawAddress)
+    const swapped = 'tempoz1' + mainnet.slice(6)
+    expect(() =>
+      TempoAddress.parse(swapped),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[TempoAddress.InvalidLengthError: Tempo address "${swapped}" has an invalid payload length. Expected 24 bytes, got 23.]`,
+    )
+  })
+})
+
+describe('validate', () => {
+  test('valid mainnet address', () => {
+    const encoded = TempoAddress.format(rawAddress)
+    expect(TempoAddress.validate(encoded)).toMatchInlineSnapshot(`true`)
+  })
+
+  test('valid zone address', () => {
+    const encoded = TempoAddress.format(rawAddress, { zoneId: 1 })
+    expect(TempoAddress.validate(encoded)).toMatchInlineSnapshot(`true`)
+  })
+
+  test('invalid address', () => {
+    expect(TempoAddress.validate('invalid')).toMatchInlineSnapshot(`false`)
+  })
+
+  test('tampered address', () => {
+    const encoded = TempoAddress.format(rawAddress)
+    const tampered = encoded.slice(0, -1) + (encoded.endsWith('q') ? 'p' : 'q')
+    expect(TempoAddress.validate(tampered)).toMatchInlineSnapshot(`false`)
+  })
+})

package/tempo/TempoAddress.ts

@@ -0,0 +1,225 @@
+import * as Address from '../core/Address.js'
+import * as Base32 from '../core/Base32.js'
+import * as Bytes from '../core/Bytes.js'
+import * as CompactSize from '../core/CompactSize.js'
+import * as Errors from '../core/Errors.js'
+import * as Hash from '../core/Hash.js'
+import * as Hex from '../core/Hex.js'
+
+/** Root type for a Tempo Address. */
+export type TempoAddress = `tempo1${string}` | `tempoz1${string}`
+
+/**
+ * Formats a raw Ethereum address (and optional zone ID) into a Tempo address string.
+ *
+ * @example
+ * ```ts twoslash
+ * import { TempoAddress } from 'ox/tempo'
+ *
+ * const address = TempoAddress.format('0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28')
+ * // @log: 'tempo1wskntnrxxnq9x2f95wuyf0y7wk2l90fg8zd8djs'
+ * ```
+ *
+ * @example
+ * ### Zone Address
+ * ```ts twoslash
+ * import { TempoAddress } from 'ox/tempo'
+ *
+ * const address = TempoAddress.format(
+ *   '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28',
+ *   { zoneId: 1 },
+ * )
+ * // @log: 'tempoz1q96z6dwvvc6vq5efyk3ms39une6etu4a9zeqtx3q'
+ * ```
+ *
+ * @param address - The raw 20-byte Ethereum address.
+ * @param options - Options.
+ * @returns The encoded Tempo address string.
+ */
+export function format(
+  address: Address.Address,
+  options: format.Options = {},
+): TempoAddress {
+  const { zoneId } = options
+
+  const prefix = zoneId != null ? 'tempoz1' : 'tempo1'
+  const zone = zoneId != null ? CompactSize.toBytes(zoneId) : new Uint8Array()
+  const address_bytes = Bytes.fromHex(address)
+
+  const input = Bytes.concat(Bytes.fromString(prefix), zone, address_bytes)
+  const checksum = Hash.sha256(Hash.sha256(input, { as: 'Bytes' }), {
+    as: 'Bytes',
+  }).slice(0, 4)
+
+  const payload = Bytes.concat(zone, address_bytes, checksum)
+  return `${prefix}${Base32.fromBytes(payload)}` as TempoAddress
+}
+
+export declare namespace format {
+  type Options = {
+    /** Zone ID for zone addresses. */
+    zoneId?: bigint | number | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Parses a Tempo address string into a raw Ethereum address and optional zone ID.
+ *
+ * @example
+ * ### Mainnet Address
+ * ```ts twoslash
+ * import { TempoAddress } from 'ox/tempo'
+ *
+ * const result = TempoAddress.parse(
+ *   'tempo1wst8d6qejxtdg4y5r3zarvary0c5xw7kvmgh8pm',
+ * )
+ * // { address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28' }
+ * ```
+ *
+ * @example
+ * ### Zone Address
+ * ```ts twoslash
+ * import { TempoAddress } from 'ox/tempo'
+ *
+ * const result = TempoAddress.parse(
+ *   'tempoz1qwst8d6qejxtdg4y5r3zarvary0c5xw7kvmgh8pm',
+ * )
+ * // { address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28', zoneId: 1 }
+ * ```
+ *
+ * @param tempoAddress - The Tempo address string to parse.
+ * @returns The parsed raw address and optional zone ID.
+ */
+export function parse(tempoAddress: string): parse.ReturnType {
+  const lower = tempoAddress.toLowerCase()
+
+  let prefix: string
+  let hasZone: boolean
+  if (lower.startsWith('tempoz1')) {
+    prefix = 'tempoz1'
+    hasZone = true
+  } else if (lower.startsWith('tempo1')) {
+    prefix = 'tempo1'
+    hasZone = false
+  } else {
+    throw new InvalidPrefixError({ address: tempoAddress })
+  }
+
+  const payload = Base32.toBytes(lower.slice(prefix.length))
+
+  let zoneId: bigint | undefined
+  let remaining: Uint8Array
+  if (hasZone) {
+    const { value, size } = CompactSize.fromBytes(payload)
+    zoneId = value
+    remaining = payload.slice(size)
+  } else {
+    zoneId = undefined
+    remaining = payload
+  }
+
+  if (remaining.length !== 24)
+    throw new InvalidLengthError({
+      address: tempoAddress,
+      expected: 24,
+      actual: remaining.length,
+    })
+
+  const rawAddress = remaining.slice(0, 20)
+  const checksum = remaining.slice(20, 24)
+
+  const zoneBytes =
+    zoneId != null ? CompactSize.toBytes(zoneId) : new Uint8Array()
+  const checksumInput = Bytes.concat(
+    Bytes.fromString(prefix),
+    zoneBytes,
+    rawAddress,
+  )
+  const expected = Hash.sha256(Hash.sha256(checksumInput, { as: 'Bytes' }), {
+    as: 'Bytes',
+  }).slice(0, 4)
+
+  if (!Bytes.isEqual(checksum, expected))
+    throw new InvalidChecksumError({ address: tempoAddress })
+
+  const address = Address.checksum(Hex.fromBytes(rawAddress) as Address.Address)
+
+  return { address, zoneId }
+}
+
+export declare namespace parse {
+  type ReturnType = {
+    /** The raw 20-byte Ethereum address. */
+    address: Address.Address
+    /** The zone ID, or `undefined` for mainnet addresses. */
+    zoneId: bigint | undefined
+  }
+
+  type ErrorType =
+    | InvalidPrefixError
+    | InvalidLengthError
+    | InvalidChecksumError
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Validates a Tempo address string.
+ *
+ * @example
+ * ```ts twoslash
+ * import { TempoAddress } from 'ox/tempo'
+ *
+ * const valid = TempoAddress.validate(
+ *   'tempo1wst8d6qejxtdg4y5r3zarvary0c5xw7kvmgh8pm',
+ * )
+ * // true
+ * ```
+ *
+ * @param tempoAddress - The Tempo address string to validate.
+ * @returns Whether the address is valid.
+ */
+export function validate(tempoAddress: string): boolean {
+  try {
+    parse(tempoAddress)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Thrown when a Tempo address has an invalid prefix. */
+export class InvalidPrefixError extends Errors.BaseError {
+  override readonly name = 'TempoAddress.InvalidPrefixError'
+
+  constructor({ address }: { address: string }) {
+    super(
+      `Tempo address "${address}" has an invalid prefix. Expected "tempo1" or "tempoz1".`,
+    )
+  }
+}
+
+/** Thrown when a Tempo address has an invalid payload length. */
+export class InvalidLengthError extends Errors.BaseError {
+  override readonly name = 'TempoAddress.InvalidLengthError'
+
+  constructor({
+    address,
+    expected,
+    actual,
+  }: { address: string; expected: number; actual: number }) {
+    super(
+      `Tempo address "${address}" has an invalid payload length. Expected ${expected} bytes, got ${actual}.`,
+    )
+  }
+}
+
+/** Thrown when a Tempo address has an invalid checksum. */
+export class InvalidChecksumError extends Errors.BaseError {
+  override readonly name = 'TempoAddress.InvalidChecksumError'
+
+  constructor({ address }: { address: string }) {
+    super(`Tempo address "${address}" has an invalid checksum.`)
+  }
+}

package/tempo/TxEnvelopeTempo.ts

@@ -378,18 +378,11 @@ export function deserialize(serialized: Serialized): Compute<TxEnvelopeTempo> {
   // Recover sender address from the signature if not already set.
   if (!transaction.from && signatureEnvelope) {
     try {
-      if (signatureEnvelope.type === 'keychain')
-        transaction.from = signatureEnvelope.userAddress
-      else if (
-        signatureEnvelope.type === 'p256' ||
-        signatureEnvelope.type === 'webAuthn'
-      )
-        transaction.from = Address.fromPublicKey(signatureEnvelope.publicKey)
-      else if (signatureEnvelope.type === 'secp256k1')
-        transaction.from = Secp256k1.recoverAddress({
-          payload: getSignPayload(from(transaction)),
-          signature: signatureEnvelope.signature,
-        })
+      transaction.from = SignatureEnvelope.extractAddress({
+        payload: getSignPayload(from(transaction)),
+        signature: signatureEnvelope,
+        root: true,
+      })
     } catch {}
   }