ox 0.13.2 → 0.14.1

package/tempo/KeyAuthorization.ts

@@ -5,6 +5,7 @@ import * as Hex from '../core/Hex.js'
 import type { Compute } from '../core/internal/types.js'
 import * as Rlp from '../core/Rlp.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
+import * as TempoAddress from './TempoAddress.js'
 
 /**
  * Key authorization for provisioning access keys.
@@ -33,9 +34,9 @@ export type KeyAuthorization<
   numberType = number,
 > = {
   /** 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
+  address: TempoAddress.Address
+  /** 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. */
@@ -107,7 +108,7 @@ export type Tuple<signed extends boolean = boolean> = signed extends true
  */
 export type TokenLimit<bigintType = bigint> = {
   /** Address of the TIP-20 token. */
-  token: Address.Address
+  token: TempoAddress.Address
   /** Maximum spending amount for this token (enforced over the key's lifetime). */
   limit: bigintType
 }
@@ -136,6 +137,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
@@ -157,6 +159,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'p256',
  *   limits: [{
@@ -181,6 +184,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
@@ -214,6 +218,7 @@ export type TokenLimit<bigintType = bigint> = {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'p256',
  *   limits: [{
@@ -251,14 +256,28 @@ export function from<
   authorization: authorization | KeyAuthorization,
   options: from.Options<signature> = {},
 ): from.ReturnType<authorization, signature> {
-  if (typeof authorization.expiry === 'string')
-    return fromRpc(authorization as Rpc) as never
+  if ('keyId' in authorization) return fromRpc(authorization as Rpc) as never
+  const auth = authorization as KeyAuthorization & {
+    limits?: readonly { token: TempoAddress.Address; limit: bigint }[]
+  }
+  const resolved = {
+    ...auth,
+    address: TempoAddress.resolve(auth.address as TempoAddress.Address),
+    ...(auth.limits
+      ? {
+          limits: auth.limits.map((l) => ({
+            ...l,
+            token: TempoAddress.resolve(l.token as TempoAddress.Address),
+          })),
+        }
+      : {}),
+  }
   if (options.signature)
     return {
-      ...authorization,
+      ...resolved,
       signature: SignatureEnvelope.from(options.signature),
     } as never
-  return authorization as never
+  return resolved as never
 }
 
 export declare namespace from {
@@ -296,6 +315,7 @@ export declare namespace from {
  * import { KeyAuthorization } from 'ox/tempo'
  *
  * const keyAuthorization = KeyAuthorization.fromRpc({
+ *   chainId: '0x1079',
  *   expiry: '0x174876e800',
  *   keyId: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
  *   keyType: 'secp256k1',
@@ -313,7 +333,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 +413,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 +456,7 @@ export declare namespace fromTuple {
  *
  * const authorization = KeyAuthorization.from({
  *   address,
+ *   chainId: 4217n,
  *   expiry: 1234567890,
  *   type: 'secp256k1',
  *   limits: [{
@@ -467,8 +488,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 +526,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 +566,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 +603,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 +626,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),
@@ -617,7 +635,7 @@ export function toRpc(authorization: Signed): Rpc {
       token,
       limit: Hex.fromNumber(limit),
     })),
-    keyId: address,
+    keyId: TempoAddress.resolve(address),
     signature: SignatureEnvelope.toRpc(signature),
     keyType: type,
   }
@@ -636,8 +654,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 +679,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/PoolId.test.ts

@@ -30,4 +30,13 @@ test('from', () => {
     validatorToken: 1n,
   })
   expect(poolId4).toBe(poolId1)
+
+  // Test with tempo address inputs
+  const tempoAddr0 = 'tempo1qqsvqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqv0ywuh'
+  const tempoAddr1 = 'tempo1qqsvqqqqqqqqqqqqqqqqqqqqqqqqqqqqqyr9xgnd'
+  const poolId5 = PoolId.from({
+    userToken: tempoAddr0,
+    validatorToken: tempoAddr1,
+  })
+  expect(poolId5).toBe(poolId1)
 })

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",
         }
       `)
     })
@@ -1035,6 +1040,61 @@ describe('from', () => {
 
       expect(envelope.type).toBe('keychain')
     })
+
+    test('behavior: computes keyId from p256 inner publicKey', () => {
+      const envelope = SignatureEnvelope.from({
+        userAddress: '0x1234567890123456789012345678901234567890',
+        inner: signature_p256,
+      })
+
+      expect(envelope.keyId).toBe(Address.fromPublicKey(publicKey))
+    })
+
+    test('behavior: computes keyId from webAuthn inner publicKey', () => {
+      const envelope = SignatureEnvelope.from({
+        userAddress: '0x1234567890123456789012345678901234567890',
+        inner: signature_webauthn,
+      })
+
+      expect(envelope.keyId).toBe(Address.fromPublicKey(publicKey))
+    })
+
+    test('behavior: computes keyId from secp256k1 inner with payload', () => {
+      const privateKey = Secp256k1.randomPrivateKey()
+      const accessKeyPublicKey = Secp256k1.getPublicKey({ privateKey })
+      const payload = '0xdeadbeef'
+      const sig = Secp256k1.sign({ payload, privateKey })
+
+      const envelope = SignatureEnvelope.from(
+        {
+          userAddress: '0x1234567890123456789012345678901234567890',
+          inner: SignatureEnvelope.from(sig),
+        },
+        { payload },
+      )
+
+      expect(envelope.keyId).toBe(Address.fromPublicKey(accessKeyPublicKey))
+    })
+
+    test('behavior: does not compute keyId for secp256k1 without payload', () => {
+      const envelope = SignatureEnvelope.from({
+        userAddress: '0x1234567890123456789012345678901234567890',
+        inner: SignatureEnvelope.from(signature_secp256k1),
+      })
+
+      expect(envelope.keyId).toBeUndefined()
+    })
+
+    test('behavior: preserves explicit keyId', () => {
+      const explicitKeyId = '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
+      const envelope = SignatureEnvelope.from({
+        userAddress: '0x1234567890123456789012345678901234567890',
+        inner: signature_p256,
+        keyId: explicitKeyId,
+      })
+
+      expect(envelope.keyId).toBe(explicitKeyId)
+    })
   })
 })
 
@@ -1250,8 +1310,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 +1325,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 +1344,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 +1579,7 @@ describe('serialize', () => {
             },
             "type": "keychain",
             "userAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+            "version": "v2",
           }
         `)
       })
@@ -1549,6 +1610,7 @@ describe('serialize', () => {
             },
             "type": "keychain",
             "userAddress": "0xfedcbafedcbafedcbafedcbafedcbafedcbafedc",
+            "version": "v2",
           }
         `)
       })
@@ -2228,6 +2290,24 @@ describe('fromRpc', () => {
         },
       })
     })
+
+    test('behavior: preserves keyId from RPC', () => {
+      const rpc: SignatureEnvelope.KeychainRpc = {
+        type: 'keychain',
+        userAddress: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+        keyId: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+        signature: {
+          type: 'secp256k1',
+          r: '0xa2bb71146c20ce932456c043ebb2973ed205e07cd32c35a60bdefca1285fd132',
+          s: '0x7cba10692bccdbfba9a215418443c2903dbee6fe5cb55c91172e47efc607840e',
+          yParity: '0x1',
+        },
+      }
+
+      const envelope = SignatureEnvelope.fromRpc(rpc)
+
+      expect(envelope.keyId).toBe('0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c')
+    })
   })
 })
 
@@ -2345,6 +2425,41 @@ describe('toRpc', () => {
       expect(typeof rpc.signature.pubKeyX).toBe('string')
       expect(typeof rpc.signature.webauthnData).toBe('string')
     })
+
+    test('behavior: preserves keyId in toRpc', () => {
+      const envelope: SignatureEnvelope.Keychain = {
+        type: 'keychain',
+        userAddress: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+        keyId: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+        inner: {
+          signature: signature_secp256k1,
+          type: 'secp256k1',
+        },
+      }
+
+      const rpc = SignatureEnvelope.toRpc(
+        envelope,
+      ) as SignatureEnvelope.KeychainRpc
+
+      expect(rpc.keyId).toBe('0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c')
+    })
+
+    test('behavior: omits keyId in toRpc when not set', () => {
+      const envelope: SignatureEnvelope.Keychain = {
+        type: 'keychain',
+        userAddress: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
+        inner: {
+          signature: signature_secp256k1,
+          type: 'secp256k1',
+        },
+      }
+
+      const rpc = SignatureEnvelope.toRpc(
+        envelope,
+      ) as SignatureEnvelope.KeychainRpc
+
+      expect(rpc.keyId).toBeUndefined()
+    })
   })
 })
 

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,33 @@ 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>
+  /** The access key address (recovered address of the access key signer). */
+  keyId?: Address.Address | undefined
   type: 'keychain'
+  /** Keychain signature version. @default 'v1' */
+  version?: KeychainVersion | undefined
 }
 
 export type KeychainRpc = {
   type: 'keychain'
   userAddress: Address.Address
+  keyId?: Address.Address | undefined
   signature: SignatureEnvelopeRpc
+  version?: KeychainVersion | undefined
 }
 
 export type P256<bigintType = bigint, numberType = number> = {
@@ -389,7 +406,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 +528,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 +539,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,
   })
 }
@@ -644,6 +666,7 @@ export function deserialize(value: Serialized): SignatureEnvelope {
  */
 export function from<const value extends from.Value>(
   value: value | from.Value,
+  options?: from.Options | undefined,
 ): from.ReturnValue<value> {
   if (typeof value === 'string') return deserialize(value) as never
 
@@ -660,11 +683,45 @@ 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: 'v2' }
+            : {}),
+          ...(!(typeof value === 'object' && 'keyId' in value && value.keyId)
+            ? (() => {
+                const inner = (value as Keychain).inner
+                if (inner.type === 'p256' || inner.type === 'webAuthn')
+                  return { keyId: Address.fromPublicKey(inner.publicKey) }
+                if (inner.type === 'secp256k1' && options?.payload)
+                  return {
+                    keyId: Address.fromPublicKey(
+                      ox_Secp256k1.recoverPublicKey({
+                        payload: options.payload,
+                        signature: inner.signature,
+                      }),
+                    ),
+                  }
+                return {}
+              })()
+            : {}),
+        }
+      : {}),
     type,
   } as never
 }
 
 export declare namespace from {
+  type Options = {
+    /** Payload that was signed. Used to recover `keyId` for keychain envelopes with secp256k1 inner signatures. */
+    payload?: Hex.Hex | Bytes.Bytes | undefined
+  }
+
   type Value =
     | UnionPartialBy<SignatureEnvelope, 'prehash' | 'type'>
     | Secp256k1Flat
@@ -678,7 +735,14 @@ export declare namespace from {
           ? Secp256k1
           : IsNarrowable<value, SignatureEnvelope> extends true
             ? SignatureEnvelope
-            : Assign<value, { readonly type: GetType<value> }>
+            : Assign<
+                value,
+                {
+                  readonly type: GetType<value>
+                } & (GetType<value> extends 'keychain'
+                  ? { keyId?: Address.Address | undefined }
+                  : {})
+              >
     >
   >
 }
@@ -778,6 +842,8 @@ export function fromRpc(envelope: SignatureEnvelopeRpc): SignatureEnvelope {
       type: 'keychain',
       userAddress: envelope.userAddress,
       inner: fromRpc(envelope.signature),
+      ...(envelope.keyId ? { keyId: envelope.keyId } : {}),
+      ...(envelope.version ? { version: envelope.version } : {}),
     }
 
   throw new CoercionError({ envelope })
@@ -868,7 +934,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 +1003,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 +1090,8 @@ export function toRpc(envelope: SignatureEnvelope): SignatureEnvelopeRpc {
       type: 'keychain',
       userAddress: keychain.userAddress,
       signature: toRpc(keychain.inner),
+      ...(keychain.keyId ? { keyId: keychain.keyId } : {}),
+      ...(keychain.version ? { version: keychain.version } : {}),
     }
   }