ox 0.13.1 → 0.13.2

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/index.ts

@@ -120,7 +120,27 @@ export * as PoolId from './PoolId.js'
  * @category Reference
  */
 export * as SignatureEnvelope from './SignatureEnvelope.js'
-
+/**
+ * Tempo address encoding/decoding utilities for human-readable addresses.
+ *
+ * Tempo addresses use a bech32 base32-encoded format with `tempo1` prefix for mainnet
+ * and `tempoz1` prefix for zone addresses. Includes CompactSize zone ID encoding
+ * and double-SHA256 checksumming.
+ *
+ * @example
+ * ```ts twoslash
+ * import { TempoAddress } from 'ox/tempo'
+ *
+ * const encoded = TempoAddress.format('0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28')
+ * // @log: 'tempo1wskntnrxxnq9x2f95wuyf0y7wk2l90fg8zd8djs'
+ *
+ * const { address, zoneId } = TempoAddress.parse(encoded)
+ * // @log: { address: '0x742d35CC6634c0532925a3B844bc9e7595F2Bd28' }
+ * ```
+ *
+ * @category Reference
+ */
+export * as TempoAddress from './TempoAddress.js'
 /**
  * Tick-based pricing utilities for DEX price conversions.
  *
@@ -141,7 +161,6 @@ export * as SignatureEnvelope from './SignatureEnvelope.js'
  * @category Reference
  */
 export * as Tick from './Tick.js'
-
 /**
  * TIP-20 token ID utilities for converting between token IDs and addresses.
  *
@@ -163,7 +182,6 @@ export * as Tick from './Tick.js'
  * @category Reference
  */
 export * as TokenId from './TokenId.js'
-
 /**
  * Token role utilities for serializing role identifiers to keccak256 hashes.
  *

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.13.1'
+export const version = '0.13.2'