ox 0.13.1 → 0.14.0

package/tempo/KeyAuthorization.ts

@@ -34,8 +34,8 @@ export type KeyAuthorization<
 > = {
   /** Address derived from the public key of the key type. */
   address: Address.Address
-  /** Chain ID for replay protection (0 = valid on any chain). */
-  chainId?: bigintType | undefined
+  /** Chain ID for replay protection. */
+  chainId: bigintType
   /** Unix timestamp when key expires (0 = never expires). */
   expiry?: numberType | null | undefined
   /** TIP20 spending limits for this key. */
@@ -136,6 +136,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
@@ -157,6 +158,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'p256',
  *   limits: [{
@@ -181,6 +183,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
@@ -214,6 +217,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'p256',
  *   limits: [{
@@ -313,7 +317,7 @@ export declare namespace from {
  * @returns A signed {@link ox#AuthorizationTempo.AuthorizationTempo}.
  */
 export function fromRpc(authorization: Rpc): Signed {
-  const { chainId = '0x0', keyId, expiry = 0, limits, keyType } = authorization
+  const { chainId, keyId, expiry = 0, limits, keyType } = authorization
   const signature = SignatureEnvelope.fromRpc(authorization.signature)
   return {
     address: keyId,
@@ -393,7 +397,7 @@ export function fromTuple<const tuple extends Tuple>(
     address: keyId,
     expiry: typeof expiry !== 'undefined' ? hexToNumber(expiry) : undefined,
     type: keyType,
-    ...(chainId !== '0x' ? { chainId: Hex.toBigInt(chainId) } : {}),
+    chainId: chainId === '0x' ? 0n : Hex.toBigInt(chainId),
     ...(typeof expiry !== 'undefined' ? { expiry: hexToNumber(expiry) } : {}),
     ...(typeof limits !== 'undefined'
       ? {
@@ -436,6 +440,7 @@ export declare namespace fromTuple {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
@@ -467,8 +472,9 @@ export declare namespace getSignPayload {
  * import { Value } from 'ox'
  *
  * const authorization = KeyAuthorization.from({
- *   expiry: 1234567890,
  *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   chainId: 4217n,
+ *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
  *     token: '0x20c0000000000000000000000000000000000001',
@@ -504,8 +510,9 @@ export declare namespace deserialize {
  * import { Value } from 'ox'
  *
  * const authorization = KeyAuthorization.from({
- *   expiry: 1234567890,
  *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   chainId: 4217n,
+ *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
  *     token: '0x20c0000000000000000000000000000000000001',
@@ -543,8 +550,9 @@ export declare namespace hash {
  * import { Value } from 'ox'
  *
  * const authorization = KeyAuthorization.from({
- *   expiry: 1234567890,
  *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   chainId: 4217n,
+ *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
  *     token: '0x20c0000000000000000000000000000000000001',
@@ -579,8 +587,9 @@ export declare namespace serialize {
  * import { Value } from 'ox'
  *
  * const authorization = KeyAuthorization.toRpc({
- *   expiry: 1234567890,
  *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   chainId: 4217n,
+ *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
  *     token: '0x20c0000000000000000000000000000000000001',
@@ -601,14 +610,7 @@ export declare namespace serialize {
  * @returns An RPC-formatted Key Authorization.
  */
 export function toRpc(authorization: Signed): Rpc {
-  const {
-    address,
-    chainId = 0n,
-    expiry,
-    limits,
-    type,
-    signature,
-  } = authorization
+  const { address, chainId, expiry, limits, type, signature } = authorization
 
   return {
     chainId: chainId === 0n ? '0x' : Hex.fromNumber(chainId),
@@ -636,8 +638,9 @@ export declare namespace toRpc {
  * import { Value } from 'ox'
  *
  * const authorization = KeyAuthorization.from({
- *   expiry: 1234567890,
  *   address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+ *   chainId: 4217n,
+ *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
  *     token: '0x20c0000000000000000000000000000000000001',
@@ -660,7 +663,7 @@ export declare namespace toRpc {
 export function toTuple<const authorization extends KeyAuthorization>(
   authorization: authorization,
 ): toTuple.ReturnType<authorization> {
-  const { address, chainId = 0n, expiry, limits } = authorization
+  const { address, chainId, expiry, limits } = authorization
   const signature = authorization.signature
     ? SignatureEnvelope.serialize(authorization.signature)
     : undefined

package/tempo/SignatureEnvelope.test.ts

@@ -50,16 +50,19 @@ const signature_webauthn = SignatureEnvelope.from({
 const signature_keychain_secp256k1 = SignatureEnvelope.from({
   userAddress: '0x1234567890123456789012345678901234567890',
   inner: SignatureEnvelope.from(signature_secp256k1),
+  version: 'v2',
 })
 
 const signature_keychain_p256 = SignatureEnvelope.from({
   userAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
   inner: signature_p256,
+  version: 'v2',
 })
 
 const signature_keychain_webauthn = SignatureEnvelope.from({
   userAddress: '0xfedcbafedcbafedcbafedcbafedcbafedcbafedc',
   inner: signature_webauthn,
+  version: 'v2',
 })
 
 describe('assert', () => {
@@ -509,7 +512,7 @@ describe('deserialize', () => {
         SignatureEnvelope.deserialize('0xdeadbeef'),
       ).toThrowErrorMatchingInlineSnapshot(
         `
-        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xde. Expected 0x01 (P256) or 0x02 (WebAuthn)
+        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xde. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), or 0x04 (Keychain V2)
 
         Serialized: 0xdeadbeef]
       `,
@@ -669,7 +672,7 @@ describe('deserialize', () => {
         SignatureEnvelope.deserialize(unknownType),
       ).toThrowErrorMatchingInlineSnapshot(
         `
-        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xff. Expected 0x01 (P256) or 0x02 (WebAuthn)
+        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xff. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), or 0x04 (Keychain V2)
 
         Serialized: 0xff000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000]
       `,
@@ -712,6 +715,7 @@ describe('deserialize', () => {
           },
           "type": "keychain",
           "userAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+          "version": "v2",
         }
       `)
     })
@@ -742,6 +746,7 @@ describe('deserialize', () => {
           },
           "type": "keychain",
           "userAddress": "0xfedcbafedcbafedcbafedcbafedcbafedcbafedc",
+          "version": "v2",
         }
       `)
     })
@@ -1250,8 +1255,8 @@ describe('serialize', () => {
       // Should be: 1 (type) + 20 (address) + 65 (secp256k1 signature)
       expect(Hex.size(serialized)).toBe(1 + 20 + 65)
 
-      // First byte should be Keychain type identifier (0x03)
-      expect(Hex.slice(serialized, 0, 1)).toBe('0x03')
+      // First byte should be Keychain V2 type identifier (0x04)
+      expect(Hex.slice(serialized, 0, 1)).toBe('0x04')
 
       // Next 20 bytes should be the user address (without '0x')
       expect(Hex.slice(serialized, 1, 21)).toBe(
@@ -1265,8 +1270,8 @@ describe('serialize', () => {
       // Should be: 1 (type) + 20 (address) + 130 (p256 signature with type)
       expect(Hex.size(serialized)).toBe(1 + 20 + 130)
 
-      // First byte should be Keychain type identifier (0x03)
-      expect(Hex.slice(serialized, 0, 1)).toBe('0x03')
+      // First byte should be Keychain V2 type identifier (0x04)
+      expect(Hex.slice(serialized, 0, 1)).toBe('0x04')
 
       // Next 20 bytes should be the user address (without '0x')
       expect(Hex.slice(serialized, 1, 21)).toBe(
@@ -1284,8 +1289,8 @@ describe('serialize', () => {
         signature_keychain_webauthn,
       )
 
-      // First byte should be Keychain type identifier (0x03)
-      expect(Hex.slice(serialized, 0, 1)).toBe('0x03')
+      // First byte should be Keychain V2 type identifier (0x04)
+      expect(Hex.slice(serialized, 0, 1)).toBe('0x04')
 
       // Should contain the user address
       expect(Hex.slice(serialized, 1, 21)).toBe(
@@ -1519,6 +1524,7 @@ describe('serialize', () => {
             },
             "type": "keychain",
             "userAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+            "version": "v2",
           }
         `)
       })
@@ -1549,6 +1555,7 @@ describe('serialize', () => {
             },
             "type": "keychain",
             "userAddress": "0xfedcbafedcbafedcbafedcbafedcbafedcbafedc",
+            "version": "v2",
           }
         `)
       })

package/tempo/SignatureEnvelope.ts

@@ -22,6 +22,7 @@ import * as ox_WebAuthnP256 from '../core/WebAuthnP256.js'
 const serializedP256Type = '0x01'
 const serializedWebAuthnType = '0x02'
 const serializedKeychainType = '0x03'
+const serializedKeychainV2Type = '0x04'
 
 /** Serialized magic identifier for Tempo signature envelopes. */
 export const magicBytes =
@@ -86,9 +87,10 @@ export type GetType<
  *   and clientDataJSON. Enables browser passkey authentication. The signature is also
  *   charged as calldata (16 gas/non-zero byte, 4 gas/zero byte).
  *
- * - **keychain** (type `0x03`): Access key signature that wraps an inner signature (secp256k1,
- *   p256, or webAuthn). Format: `0x03` + user_address (20 bytes) + inner signature. The
- *   protocol validates the access key authorization via the AccountKeychain precompile.
+ * - **keychain** (type `0x03` V1, `0x04` V2): Access key signature that wraps an inner signature
+ *   (secp256k1, p256, or webAuthn). Format: type byte + user_address (20 bytes) + inner signature.
+ *   V2 binds the signature to the user account via `keccak256(sigHash || userAddress)`.
+ *   The protocol validates the access key authorization via the AccountKeychain precompile.
  *
  * [Signature Types Specification](https://docs.tempo.xyz/protocol/transactions/spec-tempo-transaction#signature-types)
  */
@@ -106,18 +108,30 @@ export type SignatureEnvelopeRpc = OneOf<
   Secp256k1Rpc | P256Rpc | WebAuthnRpc | KeychainRpc
 >
 
+/**
+ * Keychain signature version.
+ *
+ * - `'v1'`: Legacy format. Inner signature signs the raw `sig_hash` directly. Deprecated at T1C.
+ * - `'v2'`: Inner signature signs `keccak256(sig_hash || user_address)`, binding the signature
+ *   to the specific user account.
+ */
+export type KeychainVersion = 'v1' | 'v2'
+
 export type Keychain<bigintType = bigint, numberType = number> = {
   /** Root account address that this transaction is being executed for */
   userAddress: Address.Address
   /** The actual signature from the access key (can be Secp256k1, P256, or WebAuthn) */
   inner: SignatureEnvelope<bigintType, numberType>
   type: 'keychain'
+  /** Keychain signature version. @default 'v1' */
+  version?: KeychainVersion | undefined
 }
 
 export type KeychainRpc = {
   type: 'keychain'
   userAddress: Address.Address
   signature: SignatureEnvelopeRpc
+  version?: KeychainVersion | undefined
 }
 
 export type P256<bigintType = bigint, numberType = number> = {
@@ -389,7 +403,8 @@ export declare namespace extractPublicKey {
  * - 65 bytes (no prefix): secp256k1 signature
  * - Type `0x01` + 129 bytes: P256 signature (r, s, pubKeyX, pubKeyY, prehash)
  * - Type `0x02` + variable: WebAuthn signature (webauthnData, r, s, pubKeyX, pubKeyY)
- * - Type `0x03` + 20 bytes + inner: Keychain signature (userAddress + inner signature)
+ * - Type `0x03` + 20 bytes + inner: Keychain V1 signature (userAddress + inner signature)
+ * - Type `0x04` + 20 bytes + inner: Keychain V2 signature (userAddress + inner signature)
  *
  * [Signature Types](https://docs.tempo.xyz/protocol/transactions/spec-tempo-transaction#signature-types)
  *
@@ -510,7 +525,10 @@ export function deserialize(value: Serialized): SignatureEnvelope {
     } satisfies WebAuthn
   }
 
-  if (typeId === serializedKeychainType) {
+  if (
+    typeId === serializedKeychainType ||
+    typeId === serializedKeychainV2Type
+  ) {
     const userAddress = Hex.slice(data, 0, 20)
     const inner = deserialize(Hex.slice(data, 20))
 
@@ -518,11 +536,12 @@ export function deserialize(value: Serialized): SignatureEnvelope {
       userAddress,
       inner,
       type: 'keychain',
+      version: typeId === serializedKeychainV2Type ? 'v2' : 'v1',
     } satisfies Keychain
   }
 
   throw new InvalidSerializedError({
-    reason: `Unknown signature type identifier: ${typeId}. Expected ${serializedP256Type} (P256) or ${serializedWebAuthnType} (WebAuthn)`,
+    reason: `Unknown signature type identifier: ${typeId}. Expected ${serializedP256Type} (P256), ${serializedWebAuthnType} (WebAuthn), ${serializedKeychainType} (Keychain V1), or ${serializedKeychainV2Type} (Keychain V2)`,
     serialized,
   })
 }
@@ -660,6 +679,15 @@ export function from<const value extends from.Value>(
   return {
     ...value,
     ...(type === 'p256' ? { prehash: value.prehash } : {}),
+    ...(type === 'keychain' &&
+    !(
+      typeof value === 'object' &&
+      value !== null &&
+      'version' in value &&
+      value.version
+    )
+      ? { version: 'v1' }
+      : {}),
     type,
   } as never
 }
@@ -778,6 +806,7 @@ export function fromRpc(envelope: SignatureEnvelopeRpc): SignatureEnvelope {
       type: 'keychain',
       userAddress: envelope.userAddress,
       inner: fromRpc(envelope.signature),
+      ...(envelope.version ? { version: envelope.version } : {}),
     }
 
   throw new CoercionError({ envelope })
@@ -868,7 +897,8 @@ export function getType<
  * - secp256k1: 65 bytes (no type prefix, for backward compatibility)
  * - P256: `0x01` + r (32) + s (32) + pubKeyX (32) + pubKeyY (32) + prehash (1) = 130 bytes
  * - WebAuthn: `0x02` + webauthnData (variable) + r (32) + s (32) + pubKeyX (32) + pubKeyY (32)
- * - Keychain: `0x03` + userAddress (20) + inner signature (recursive)
+ * - Keychain V1: `0x03` + userAddress (20) + inner signature (recursive)
+ * - Keychain V2: `0x04` + userAddress (20) + inner signature (recursive)
  *
  * [Signature Types](https://docs.tempo.xyz/protocol/transactions/spec-tempo-transaction#signature-types)
  *
@@ -936,8 +966,12 @@ export function serialize(
 
   if (type === 'keychain') {
     const keychain = envelope as Keychain
+    const keychainTypeId =
+      keychain.version === 'v1'
+        ? serializedKeychainType
+        : serializedKeychainV2Type
     return Hex.concat(
-      serializedKeychainType,
+      keychainTypeId,
       keychain.userAddress,
       serialize(keychain.inner),
       options.magic ? magicBytes : '0x',
@@ -1019,6 +1053,7 @@ export function toRpc(envelope: SignatureEnvelope): SignatureEnvelopeRpc {
       type: 'keychain',
       userAddress: keychain.userAddress,
       signature: toRpc(keychain.inner),
+      ...(keychain.version ? { version: keychain.version } : {}),
     }
   }
 

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,237 @@
+import { Address, Bech32m } 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(
+      `"tempo1qp6z6dwvvc6vq5efyk3ms39une6etu4a9qtj2kk0"`,
+    )
+  })
+
+  test('zone address (zone ID = 1)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 1 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qqqhgtf4e3nrfszn9yj68wzyhj08t90jh55q74d9uj"`,
+    )
+  })
+
+  test('zone address (zone ID = 252)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 252 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qr78gtf4e3nrfszn9yj68wzyhj08t90jh55q9k62jd"`,
+    )
+  })
+
+  test('zone address (zone ID = 253)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 253 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qr7l6qr5956uce35cpfjjfdrhpzte8n4jhet62q0j8hus"`,
+    )
+  })
+
+  test('zone address (zone ID = 65535)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 65535 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qr7lllm5956uce35cpfjjfdrhpzte8n4jhet62q8pdj6j"`,
+    )
+  })
+
+  test('zone address (zone ID = 65536)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 65536 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qrlqqqqpqp6z6dwvvc6vq5efyk3ms39une6etu4a9qdupk5c"`,
+    )
+  })
+
+  test('zone address (zone ID = 4294967295)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: 4294967295 }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qrl0llllla6z6dwvvc6vq5efyk3ms39une6etu4a9qnk36qy"`,
+    )
+  })
+
+  test('zone address (zone ID > 4294967295)', () => {
+    expect(
+      TempoAddress.format(rawAddress, { zoneId: BigInt('4294967296') }),
+    ).toMatchInlineSnapshot(
+      `"tempoz1qrlsqqqqqqqsqqqqwskntnrxxnq9x2f95wuyf0y7wk2l90fg4306kk"`,
+    )
+  })
+
+  test('lowercase output', () => {
+    const result = TempoAddress.format(rawAddress)
+    expect(result).toBe(result.toLowerCase())
+  })
+
+  test('spec test vectors', () => {
+    expect(TempoAddress.format(rawAddress)).toBe(
+      'tempo1qp6z6dwvvc6vq5efyk3ms39une6etu4a9qtj2kk0',
+    )
+    expect(TempoAddress.format(rawAddress, { zoneId: 1 })).toBe(
+      'tempoz1qqqhgtf4e3nrfszn9yj68wzyhj08t90jh55q74d9uj',
+    )
+    expect(TempoAddress.format(rawAddress, { zoneId: 1000 })).toBe(
+      'tempoz1qr77sqm5956uce35cpfjjfdrhpzte8n4jhet62qxx4zvx',
+    )
+    expect(TempoAddress.format(rawAddress, { zoneId: 100000 })).toBe(
+      'tempoz1qrl2ppspqp6z6dwvvc6vq5efyk3ms39une6etu4a9qg5477g',
+    )
+  })
+
+  test('address lengths match spec', () => {
+    expect(TempoAddress.format(rawAddress).length).toBe(46)
+    expect(TempoAddress.format(rawAddress, { zoneId: 1 }).length).toBe(49)
+    expect(TempoAddress.format(rawAddress, { zoneId: 1000 }).length).toBe(52)
+    expect(TempoAddress.format(rawAddress, { zoneId: 100000 }).length).toBe(55)
+  })
+})
+
+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('all uppercase', () => {
+    const encoded = TempoAddress.format(rawAddress)
+    const upper = encoded.toUpperCase()
+    expect(TempoAddress.parse(upper).address).toBe(rawAddress)
+  })
+
+  test('error: invalid prefix', () => {
+    const encoded = Bech32m.encode('bitcoin', new Uint8Array(20))
+    expect(() =>
+      TempoAddress.parse(encoded),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[TempoAddress.InvalidPrefixError: Tempo address "${encoded}" has an invalid prefix. Expected "tempo1" or "tempoz1".]`,
+    )
+  })
+
+  test('error: unsupported version', () => {
+    const data = new Uint8Array([0x01, ...new Uint8Array(20)])
+    const encoded = Bech32m.encode('tempo', data)
+    expect(() => TempoAddress.parse(encoded)).toThrow(
+      TempoAddress.InvalidVersionError,
+    )
+  })
+
+  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.InvalidChecksumError: Tempo address "tempoz1qp6z6dwvvc6vq5efyk3ms39une6etu4a9qtj2kk0" has an invalid checksum.]`,
+    )
+  })
+})
+
+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`)
+  })
+})