@fhevm/sdk 1.1.0-alpha.6 → 1.1.0-alpha.8

package/core/modules/relayer/module/fetchUserDecryptV2.ts

@@ -0,0 +1,71 @@
+import type { KmsSigncryptedShare } from '../../../types/kms-p.js';
+import type { FetchUserDecryptPayloadV2 } from '../../../types/relayer-p.js';
+import type { FetchUserDecryptResult } from '../../../types/relayer.js';
+import type { FetchUserDecryptParametersV2, FetchUserDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
+import { remove0x } from '../../../base/string.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
+
+//////////////////////////////////////////////////////////////////////////////
+// fetchUserDecryptV2 (protocol version >= 0.14.0)
+//////////////////////////////////////////////////////////////////////////////
+
+export async function fetchUserDecryptV2(
+  relayerClient: RelayerClientWithRuntime,
+  parameters: FetchUserDecryptParametersV2,
+): Promise<FetchUserDecryptReturnType> {
+  const { options, payload } = parameters;
+
+  const firstHandleContractPair = payload.handleContractPairs[0];
+  if (firstHandleContractPair === undefined) {
+    throw new Error('Empty handle contract pairs');
+  }
+
+  // V3 envelope: AttestedUserDecryptRequestJson
+  // publicKey and signature keep their 0x prefix (unlike the V1/V2 flat payload)
+  const relayerPayload: FetchUserDecryptPayloadV2 = {
+    attestationType: 'eip712-unified-user-decrypt-v1',
+    attestedPayload: {
+      version: '2.0',
+      type: 'user_decryption',
+      handles: payload.handleContractPairs.map((pair) => ({
+        ctHandle: pair.handle.bytes32Hex,
+        contractAddress: pair.contractAddress,
+        ownerAddress: pair.ownerAddress,
+      })),
+      userAddress: payload.kmsDecryptEip712Message.userAddress,
+      allowedContracts: payload.kmsDecryptEip712Message.allowedContracts,
+      requestValidity: {
+        startTimestamp: payload.kmsDecryptEip712Message.startTimestamp,
+        durationSeconds: payload.kmsDecryptEip712Message.durationSeconds,
+      },
+      publicKey: payload.kmsDecryptEip712Message.publicKey,
+      extraData: payload.kmsDecryptEip712Message.extraData,
+    },
+    signature: payload.kmsDecryptEip712Signature,
+  };
+
+  const hasAuth: boolean = options?.auth !== undefined;
+  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.chain.fhevm.relayerUrl, hasAuth);
+  const url = buildRelayerUrlString(relayerBaseUrl, 'v3/user-decrypt');
+
+  const request = new RelayerAsyncRequest({
+    relayerOperation: 'USER_DECRYPT',
+    url,
+    payload: relayerPayload,
+    options,
+  });
+
+  const result = (await request.run()) as FetchUserDecryptResult;
+
+  const shares: KmsSigncryptedShare[] = result.map((r) => {
+    const share: KmsSigncryptedShare = {
+      signature: r.signature,
+      payload: r.payload,
+      extraData: remove0x(r.extraData),
+    };
+    return share;
+  });
+
+  return shares;
+}

package/core/modules/relayer/module/guards/RelayerResponseFailed.ts

@@ -63,7 +63,8 @@ export function assertIsRelayerApiError(
   if (
     value.label === ('malformed_json' satisfies RelayerApiError400NoDetails['label']) ||
     value.label === ('request_error' satisfies RelayerApiError400NoDetails['label']) ||
-    value.label === ('not_ready_for_decryption' satisfies RelayerApiError400NoDetails['label'])
+    value.label === ('not_ready_for_decryption' satisfies RelayerApiError400NoDetails['label']) ||
+    value.label === ('not_allowed_on_host_acl' satisfies RelayerApiError400NoDetails['label'])
   ) {
     assertIsRelayerApiError400NoDetails(value, name, options);
   }
@@ -94,6 +95,8 @@ export function assertIsRelayerApiError(
     value.label === ('readiness_check_timed_out' satisfies RelayerApiError503['label']) ||
     value.label === ('response_timed_out' satisfies RelayerApiError503['label']) ||
     value.label === ('protocol_paused' satisfies RelayerApiError503['label']) ||
+    value.label === ('insufficient_balance' satisfies RelayerApiError503['label']) ||
+    value.label === ('insufficient_allowance' satisfies RelayerApiError503['label']) ||
     value.label === ('gateway_not_reachable' satisfies RelayerApiError503['label'])
   ) {
     assertIsRelayerApiError503(value, name, options);
@@ -109,11 +112,14 @@ export function assertIsRelayerApiError(
           'malformed_json',
           'request_error',
           'not_ready_for_decryption',
+          'not_allowed_on_host_acl',
           'missing_fields',
           'validation_failed',
           'rate_limited',
           'internal_server_error',
           'protocol_paused',
+          'insufficient_balance',
+          'insufficient_allowance',
           'protocol_overload',
           'gateway_not_reachable',
           'readiness_check_timed_out',
@@ -150,7 +156,8 @@ export function assertIsRelayerResponseFailedWithError400(
   if (
     value.error.label === ('malformed_json' satisfies RelayerApiError400NoDetails['label']) ||
     value.error.label === ('request_error' satisfies RelayerApiError400NoDetails['label']) ||
-    value.error.label === ('not_ready_for_decryption' satisfies RelayerApiError400NoDetails['label'])
+    value.error.label === ('not_ready_for_decryption' satisfies RelayerApiError400NoDetails['label']) ||
+    value.error.label === ('not_allowed_on_host_acl' satisfies RelayerApiError400NoDetails['label'])
   ) {
     assertIsRelayerApiError400NoDetails(value.error, `${name}.error`, options);
   } else if (
@@ -168,6 +175,7 @@ export function assertIsRelayerResponseFailedWithError400(
           'malformed_json',
           'request_error',
           'not_ready_for_decryption',
+          'not_allowed_on_host_acl',
           'missing_fields',
           'validation_failed',
         ],

package/core/modules/relayer/module/guards/api-errors/RelayerApiError400NoDetails.ts

@@ -14,7 +14,8 @@ export function isRelayerApiError400NoDetails(error: unknown): error is RelayerA
     !(
       error.label === ('malformed_json' satisfies T['label']) ||
       error.label === ('request_error' satisfies T['label']) ||
-      error.label === ('not_ready_for_decryption' satisfies T['label'])
+      error.label === ('not_ready_for_decryption' satisfies T['label']) ||
+      error.label === ('not_allowed_on_host_acl' satisfies T['label'])
     )
   ) {
     return false;
@@ -26,7 +27,7 @@ export function isRelayerApiError400NoDetails(error: unknown): error is RelayerA
  * Asserts that a value matches the {@link RelayerApiError400NoDetails} schema:
  * ```json
  * {
- *   "label": "malformed_json" | "request_error" | "not_ready_for_decryption",
+ *   "label": "malformed_json" | "request_error" | "not_ready_for_decryption" | "not_allowed_on_host_acl",
  *   "message": "string"
  * }
  * ```
@@ -42,7 +43,8 @@ export function assertIsRelayerApiError400NoDetails(
     !(
       value.label === ('malformed_json' satisfies T['label']) ||
       value.label === ('request_error' satisfies T['label']) ||
-      value.label === ('not_ready_for_decryption' satisfies T['label'])
+      value.label === ('not_ready_for_decryption' satisfies T['label']) ||
+      value.label === ('not_allowed_on_host_acl' satisfies T['label'])
     )
   ) {
     throw new InvalidPropertyError(
@@ -54,6 +56,7 @@ export function assertIsRelayerApiError400NoDetails(
           'malformed_json' satisfies T['label'],
           'request_error' satisfies T['label'],
           'not_ready_for_decryption' satisfies T['label'],
+          'not_allowed_on_host_acl' satisfies T['label'],
         ],
         type: typeof value.label, // === "string"
         value: value.label,

package/core/modules/relayer/module/guards/api-errors/RelayerApiError503.ts

@@ -20,6 +20,8 @@ export function assertIsRelayerApiError503(
   assertRecordStringProperty(value, 'label' satisfies keyof T, name, {
     expectedValue: [
       'protocol_paused' satisfies T['label'],
+      'insufficient_balance' satisfies T['label'],
+      'insufficient_allowance' satisfies T['label'],
       'gateway_not_reachable' satisfies T['label'],
       'readiness_check_timed_out' satisfies T['label'],
       'response_timed_out' satisfies T['label'],

package/core/modules/relayer/module/index.ts

@@ -1,6 +1,6 @@
 import type { RelayerModuleFactory } from '../types.js';
 import { fetchCoprocessorSignatures } from './fetchCoprocessorSignatures.js';
-import { fetchDelegatedUserDecrypt } from './fetchDelegatedUserDecrypt.js';
+import { fetchDelegatedUserDecrypt } from './fetchDelegatedUserDecryptV1.js';
 import { fetchPublicDecrypt } from './fetchPublicDecrypt.js';
 import { fetchFheEncryptionKeyBytes } from './fetchFheEncryptionKeyBytes.js';
 import { fetchFheEncryptionKeySource } from './fetchFheEncryptionKeySource.js';

package/core/modules/relayer/types.ts

@@ -7,7 +7,11 @@ import type {
 } from '../../types/relayer.js';
 import type { FheEncryptionKeyBytes, FheEncryptionKeySource } from '../../types/fheEncryptionKey.js';
 import type { KmsSigncryptedShare } from '../../types/kms-p.js';
-import type { KmsDelegatedUserDecryptEip712Message, KmsUserDecryptEip712Message } from '../../types/kms.js';
+import type {
+  KmsDelegatedUserDecryptEip712V1Message,
+  KmsUserDecryptEip712V1Message,
+  KmsUserDecryptEip712V2Message,
+} from '../../types/kms.js';
 import type { Bytes65Hex, BytesHex, ChecksummedAddress } from '../../types/primitives.js';
 import type { Prettify } from '../../types/utils.js';
 import type { ZkProof } from '../../types/zkProof-p.js';
@@ -105,7 +109,7 @@ export type FetchPublicDecryptParameters = {
 
 export type FetchPublicDecryptReturnType = {
   readonly orderedAbiEncodedClearValues: BytesHex;
-  readonly kmsPublicDecryptEIP712Signatures: Bytes65Hex[];
+  readonly kmsPublicDecryptEip712Signatures: Bytes65Hex[];
   readonly extraData: BytesHex;
 };
 
@@ -120,19 +124,34 @@ export type FetchPublicDecryptModuleFunction = {
 // 4. fetchUserDecrypt
 ////////////////////////////////////////////////////////////////////////////////
 
-export type FetchUserDecryptParameters = {
+export type FetchUserDecryptParametersV1 = {
   readonly payload: {
     readonly handleContractPairs: ReadonlyArray<{
       readonly handle: Handle;
       readonly contractAddress: ChecksummedAddress;
     }>;
     readonly kmsDecryptEip712Signer: ChecksummedAddress;
-    readonly kmsDecryptEip712Message: KmsUserDecryptEip712Message;
+    readonly kmsDecryptEip712Message: KmsUserDecryptEip712V1Message;
+    readonly kmsDecryptEip712Signature: Bytes65Hex;
+  };
+  readonly options?: RelayerUserDecryptOptions | undefined;
+};
+
+export type FetchUserDecryptParametersV2 = {
+  readonly payload: {
+    readonly handleContractPairs: ReadonlyArray<{
+      readonly handle: Handle;
+      readonly contractAddress: ChecksummedAddress;
+      readonly ownerAddress: ChecksummedAddress;
+    }>;
+    readonly kmsDecryptEip712Message: KmsUserDecryptEip712V2Message;
     readonly kmsDecryptEip712Signature: Bytes65Hex;
   };
   readonly options?: RelayerUserDecryptOptions | undefined;
 };
 
+export type FetchUserDecryptParameters = FetchUserDecryptParametersV1 | FetchUserDecryptParametersV2;
+
 export type FetchUserDecryptReturnType = readonly KmsSigncryptedShare[];
 
 export type FetchUserDecryptModuleFunction = {
@@ -153,7 +172,7 @@ export type FetchDelegatedUserDecryptParameters = {
       readonly contractAddress: ChecksummedAddress;
     }>;
     readonly kmsDecryptEip712Signer: ChecksummedAddress;
-    readonly kmsDecryptEip712Message: KmsDelegatedUserDecryptEip712Message;
+    readonly kmsDecryptEip712Message: KmsDelegatedUserDecryptEip712V1Message;
     readonly kmsDecryptEip712Signature: Bytes65Hex;
   };
   readonly options?: RelayerDelegatedUserDecryptOptions | undefined;

package/core/runtime/HyperWasmSolver-p.ts

@@ -350,11 +350,7 @@ function _handleModuleVersionCompatibilityPolicy(
     case 'throw':
       throw new Error(message);
     case 'warn':
-      if (logger?.warn !== undefined) {
-        logger.warn(message);
-      } else {
-        console.warn(message);
-      }
+      logger?.warn?.(message);
       return;
     case 'off':
       return;

package/core/types/kms-p.ts

@@ -2,7 +2,15 @@ import type { TkmsVersion } from '../../wasm/tkms/KmsLibApi.js';
 import type { Handle } from './encryptedTypes-p.js';
 import type { KmsEip712Domain } from './kms.js';
 import type { KmsSignersContext } from './kmsSignersContext.js';
-import type { Bytes65Hex, Bytes65HexNo0x, BytesHexNo0x, ChecksummedAddress } from './primitives.js';
+import type {
+  Bytes65Hex,
+  Bytes65HexNo0x,
+  BytesHex,
+  BytesHexNo0x,
+  ChecksummedAddress,
+  Uint256BigInt,
+  Uint8Number,
+} from './primitives.js';
 
 export interface KmsSigncryptedSharesMetadata {
   readonly kmsSignersContext: KmsSignersContext;
@@ -18,3 +26,10 @@ export interface KmsSigncryptedShare {
   readonly signature: Bytes65HexNo0x;
   readonly extraData: BytesHexNo0x;
 }
+
+export interface KmsExtraData {
+  readonly version: Uint8Number;
+  readonly kmsContextId: Uint256BigInt;
+  readonly kmsEpochId: Uint256BigInt;
+  toBytesHex(): BytesHex;
+}

package/core/types/kms.ts

@@ -31,7 +31,7 @@ export type KmsEip712Domain = Readonly<{
   verifyingContract: ChecksummedAddress;
 }>;
 
-export type KmsUserDecryptEip712Types = {
+export type KmsUserDecryptEip712V1Types = {
   readonly EIP712Domain: readonly [
     { readonly name: 'name'; readonly type: 'string' },
     { readonly name: 'version'; readonly type: 'string' },
@@ -48,7 +48,7 @@ export type KmsUserDecryptEip712Types = {
   ];
 };
 
-export type KmsDelegateUserDecryptEip712Types = {
+export type KmsDelegatedUserDecryptEip712V1Types = {
   readonly EIP712Domain: readonly [
     { readonly name: 'name'; readonly type: 'string' },
     { readonly name: 'version'; readonly type: 'string' },
@@ -98,7 +98,7 @@ export type KmsPublicDecryptEip712Types = {
   ];
 };
 
-export type KmsUserDecryptEip712Message = Readonly<{
+export type KmsUserDecryptEip712V1Message = Readonly<{
   publicKey: BytesHex;
   contractAddresses: readonly ChecksummedAddress[];
   startTimestamp: string;
@@ -106,8 +106,9 @@ export type KmsUserDecryptEip712Message = Readonly<{
   extraData: BytesHex;
 }>;
 
-export type KmsDelegatedUserDecryptEip712Message = Prettify<
-  KmsUserDecryptEip712Message & {
+// Protocol <= v0.13
+export type KmsDelegatedUserDecryptEip712V1Message = Prettify<
+  KmsUserDecryptEip712V1Message & {
     readonly delegatorAddress: ChecksummedAddress;
   }
 >;
@@ -127,33 +128,44 @@ export type KmsUserDecryptEip712V2Message = Readonly<{
   extraData: BytesHex;
 }>;
 
-export type KmsUserDecryptEip712 = Prettify<{
+export type KmsUserDecryptEip712Base = {
   readonly domain: KmsEip712Domain;
-  readonly types: KmsUserDecryptEip712Types;
-  readonly primaryType: 'UserDecryptRequestVerification';
-  readonly message: KmsUserDecryptEip712Message;
-}>;
+};
 
-export type KmsDelegatedUserDecryptEip712 = Prettify<{
-  readonly domain: KmsEip712Domain;
-  readonly types: KmsDelegateUserDecryptEip712Types;
-  readonly primaryType: 'DelegatedUserDecryptRequestVerification';
-  readonly message: KmsDelegatedUserDecryptEip712Message;
-}>;
+// Protocol <= v0.13
+export type KmsUserDecryptEip712V1 = Prettify<
+  KmsUserDecryptEip712Base & {
+    readonly types: KmsUserDecryptEip712V1Types;
+    readonly primaryType: 'UserDecryptRequestVerification';
+    readonly message: KmsUserDecryptEip712V1Message;
+  }
+>;
 
-export type KmsPublicDecryptEip712 = Prettify<{
-  readonly domain: KmsEip712Domain;
-  readonly types: KmsPublicDecryptEip712Types;
-  readonly primaryType: 'PublicDecryptVerification';
-  readonly message: KmsPublicDecryptEip712Message;
-}>;
+// Protocol <= v0.13
+export type KmsDelegatedUserDecryptEip712V1 = Prettify<
+  KmsUserDecryptEip712Base & {
+    readonly types: KmsDelegatedUserDecryptEip712V1Types;
+    readonly primaryType: 'DelegatedUserDecryptRequestVerification';
+    readonly message: KmsDelegatedUserDecryptEip712V1Message;
+  }
+>;
 
-export type KmsUserDecryptEip712V2 = Prettify<{
-  readonly domain: KmsEip712Domain;
-  readonly types: KmsUserDecryptEip712V2Types;
-  readonly primaryType: 'UserDecryptRequestVerification';
-  readonly message: KmsUserDecryptEip712V2Message;
-}>;
+// Protocol >= v0.14
+export type KmsUserDecryptEip712V2 = Prettify<
+  KmsUserDecryptEip712Base & {
+    readonly types: KmsUserDecryptEip712V2Types;
+    readonly primaryType: 'UserDecryptRequestVerification';
+    readonly message: KmsUserDecryptEip712V2Message;
+  }
+>;
+
+export type KmsPublicDecryptEip712 = Prettify<
+  KmsUserDecryptEip712Base & {
+    readonly types: KmsPublicDecryptEip712Types;
+    readonly primaryType: 'PublicDecryptVerification';
+    readonly message: KmsPublicDecryptEip712Message;
+  }
+>;
 
 ////////////////////////////////////////////////////////////////////////////////
 //

package/core/types/logger.ts

@@ -1,5 +1,5 @@
 export type Logger = {
-  readonly debug: (message: string) => void;
-  readonly warn?: ((message: string) => void) | undefined;
-  readonly error: (message: string, cause: unknown) => void;
+  readonly debug: ((message: string) => void) | undefined;
+  readonly warn: ((message: string) => void) | undefined;
+  readonly error: ((message: string, cause: unknown) => void) | undefined;
 };

package/core/types/record-p.ts

@@ -1,4 +1,4 @@
-import type { Uint, ChecksummedAddress, Uint256, Address } from './primitives.js';
+import type { Uint, ChecksummedAddress, Uint256, Address, UintNumber } from './primitives.js';
 
 /**
  * Generic helper type that creates a record with a specific property of type T.
@@ -17,6 +17,7 @@ export type RecordBooleanPropertyType<K extends string> = RecordWithPropertyType
 
 export type RecordUintPropertyType<K extends string> = RecordWithPropertyType<K, Uint>;
 export type RecordUint256PropertyType<K extends string> = RecordWithPropertyType<K, Uint256>;
+export type RecordUintNumberPropertyType<K extends string> = RecordWithPropertyType<K, UintNumber>;
 
 export type RecordUint8ArrayPropertyType<K extends string> = RecordWithPropertyType<K, Uint8Array>;
 

package/core/types/relayer-p.ts

@@ -51,7 +51,7 @@ export type RelayerFetchPublicDecryptPayload = {
 };
 
 // https://github.com/zama-ai/fhevm-relayer/blob/96151ef300f787658c5fbaf1b4471263160032d5/src/http/userdecrypt_http_listener.rs#L33
-export type HandleContractPair = {
+export type HandleContractPairV1 = {
   // Hex encoded bytes32 with 0x prefix.
   readonly handle: HandleBytes32Hex;
   // Hex encoded address with 0x prefix.
@@ -60,7 +60,7 @@ export type HandleContractPair = {
 
 // https://github.com/zama-ai/fhevm-relayer/blob/96151ef300f787658c5fbaf1b4471263160032d5/src/http/userdecrypt_http_listener.rs#L20
 export type FetchUserDecryptPayload = {
-  readonly handleContractPairs: readonly HandleContractPair[];
+  readonly handleContractPairs: readonly HandleContractPairV1[];
   readonly requestValidity: {
     // Number as a string
     readonly startTimestamp: string;
@@ -81,8 +81,45 @@ export type FetchUserDecryptPayload = {
   readonly extraData: BytesHex;
 };
 
+// https://github.com/zama-ai/fhevm-relayer v3 HandleEntryJson (camelCase)
+export type HandleContractPairV2 = {
+  // Hex encoded bytes32 with 0x prefix.
+  readonly ctHandle: HandleBytes32Hex;
+  // Hex encoded address with 0x prefix.
+  readonly contractAddress: ChecksummedAddress;
+  // Hex encoded address with 0x prefix.
+  readonly ownerAddress: ChecksummedAddress;
+};
+
+// https://github.com/zama-ai/fhevm-relayer — v3/user-decrypt (RFC-016 unified struct)
+// POST body: AttestedUserDecryptRequestJson envelope
+export type FetchUserDecryptPayloadV2 = {
+  readonly attestationType: 'eip712-unified-user-decrypt-v1';
+  readonly attestedPayload: {
+    readonly version: '2.0';
+    readonly type: 'user_decryption';
+    readonly handles: readonly HandleContractPairV2[];
+    // Hex encoded address with 0x prefix.
+    readonly userAddress: ChecksummedAddress;
+    // List of hex encoded addresses with 0x prefix (empty = permissive mode)
+    readonly allowedContracts: readonly ChecksummedAddress[];
+    readonly requestValidity: {
+      // Number as a string
+      readonly startTimestamp: string;
+      // Number as a string
+      readonly durationSeconds: string;
+    };
+    // Hex encoded key with 0x prefix.
+    readonly publicKey: BytesHex;
+    // Hex encoded bytes with 0x prefix. Default: 0x00
+    readonly extraData: BytesHex;
+  };
+  // Hex encoded signature with 0x prefix.
+  readonly signature: Bytes65Hex;
+};
+
 export type FetchDelegatedUserDecryptPayload = {
-  readonly handleContractPairs: readonly HandleContractPair[];
+  readonly handleContractPairs: readonly HandleContractPairV1[];
   // Hex encoded uint256 string without prefix
   readonly contractsChainId: string;
   // List of hex encoded addresses with 0x prefix
@@ -318,7 +355,7 @@ export type RelayerApiError400 = RelayerApiError400NoDetails | RelayerApiError40
  * Status: 400 (no details)
  */
 export type RelayerApiError400NoDetails = {
-  label: 'malformed_json' | 'request_error' | 'not_ready_for_decryption';
+  label: 'malformed_json' | 'request_error' | 'not_ready_for_decryption' | 'not_allowed_on_host_acl';
   message: string;
 };
 
@@ -372,7 +409,13 @@ export type RelayerApiError500 = {
  * Status: 503
  */
 export type RelayerApiError503 = {
-  label: 'protocol_paused' | 'gateway_not_reachable' | 'readiness_check_timed_out' | 'response_timed_out';
+  label:
+    | 'protocol_paused'
+    | 'insufficient_balance'
+    | 'insufficient_allowance'
+    | 'gateway_not_reachable'
+    | 'readiness_check_timed_out'
+    | 'response_timed_out';
   message: string;
 };
 

package/core/types/signedDecryptionPermit.ts

@@ -1,11 +1,8 @@
-import type { KmsDelegatedUserDecryptEip712, KmsUserDecryptEip712 } from './kms.js';
+import type { KmsDelegatedUserDecryptEip712V1, KmsUserDecryptEip712V1, KmsUserDecryptEip712V2 } from './kms.js';
 import type { Bytes65Hex, BytesHex, ChecksummedAddress } from './primitives.js';
 
 /**
- * A signed EIP-712 authorization that allows the signer's ephemeral key
- * to request decryption of the signer's own FHE handles from the KMS.
- *
- * Created once, serializable, and reusable across multiple decrypt calls.
+ * Common fields shared by all signed decryption permit versions.
  */
 export type SignedDecryptionPermitBase = {
   /** The EIP-712 signature. */
@@ -15,36 +12,60 @@ export type SignedDecryptionPermitBase = {
   /**
    * The account that owns the encrypted data this permit covers.
    *
-   * - **Self permit:** equals `signerAddress` — the signer authorizes decryption
-   *   of their own data.
-   *
-   * - **Delegated permit:** differs from `signerAddress`. Step by step:
-   *   1. Alice owns encrypted values on-chain (ebool, euint8, etc.).
-   *   2. Alice calls the ACL contract to grant Bob permission to decrypt her data.
-   *   3. Bob signs an EIP-712 delegated decryption permit referencing Alice as the
-   *      `encryptedDataOwnerAddress` (= `delegatorAddress` in the EIP-712 message).
-   *   4. The KMS verifies Bob's signature (`signerAddress`) and that Alice
-   *      (`encryptedDataOwnerAddress`) has granted him on-chain permission.
-   *   5. Bob can now decrypt Alice's encrypted values using this permit.
+   * - **Self permit:** equals `signerAddress`.
+   * - **Delegated permit:** differs from `signerAddress`. The owner has granted
+   *   the signer permission via `FHE.delegateUserDecryption()` on-chain.
    */
   readonly encryptedDataOwnerAddress: ChecksummedAddress;
   /** The E2E transport public key embedded in the EIP-712 message. */
   readonly transportPublicKey: BytesHex;
+  /** `true` when the signer is decrypting on behalf of another account (delegated permit). */
+  readonly isDelegated: boolean;
 
-  /** @throws If the permit has expired based on `startTimestamp` + `durationDays`. */
+  /** @throws If the permit has expired. */
   assertNotExpired(): void;
 };
 
-export type SignedSelfDecryptionPermit = SignedDecryptionPermitBase & {
-  readonly eip712: KmsUserDecryptEip712;
-  /** Always `false` for non-delegated permits. `encryptedDataOwnerAddress === signerAddress`. */
-  readonly isDelegated: false;
+////////////////////////////////////////////////////////////////////////////////
+// V1 — protocol v13 and below (two separate EIP-712 shapes)
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Signed decryption permit produced by protocol v13 and below.
+ *
+ * Narrow to self vs delegated via `eip712.primaryType`:
+ * - `'UserDecryptRequestVerification'` → self permit (`encryptedDataOwnerAddress === signerAddress`)
+ * - `'DelegatedUserDecryptRequestVerification'` → delegated permit
+ */
+export type SignedDecryptionPermitV1 = SignedDecryptionPermitBase & {
+  readonly version: 1;
+  readonly eip712: KmsUserDecryptEip712V1 | KmsDelegatedUserDecryptEip712V1;
 };
 
-export type SignedDelegatedDecryptionPermit = SignedDecryptionPermitBase & {
-  readonly eip712: KmsDelegatedUserDecryptEip712;
-  /** Always `true` for delegated permits. `v` is the delegated account. (see `SenderCannotBeDelegate` is ACL.sol) */
-  readonly isDelegated: true;
+////////////////////////////////////////////////////////////////////////////////
+// V2 — protocol v14 and above (unified EIP-712 shape)
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Signed decryption permit produced by protocol v14 and above.
+ *
+ * Uses the unified `KmsUserDecryptEip712V2` EIP-712 shape — there is no longer
+ * a separate delegated variant. The `encryptedDataOwnerAddress` is read from
+ * `eip712.message.userAddress` and may differ from `signerAddress`.
+ *
+ * Discriminate from {@link SignedDecryptionPermitV1} with `permit.version === 2`.
+ */
+export type SignedDecryptionPermitV2 = SignedDecryptionPermitBase & {
+  readonly version: 2;
+  readonly eip712: KmsUserDecryptEip712V2;
 };
 
-export type SignedDecryptionPermit = SignedSelfDecryptionPermit | SignedDelegatedDecryptionPermit;
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A signed decryption permit, covering all protocol versions.
+ *
+ * Narrow by version: `permit.version === 1` → {@link SignedDecryptionPermitV1},
+ * `permit.version === 2` → {@link SignedDecryptionPermitV2}.
+ */
+export type SignedDecryptionPermit = SignedDecryptionPermitV1 | SignedDecryptionPermitV2;

package/core/utils-p/decrypt/{verifyKmsDelegatedUserDecryptEip712.ts → verifyKmsDelegatedUserDecryptEip712V1.ts}

@@ -1,23 +1,23 @@
 import type { FhevmRuntime } from '../../types/coreFhevmRuntime.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
-import type { KmsDelegatedUserDecryptEip712, KmsDelegatedUserDecryptEip712Message } from '../../types/kms.js';
+import type { KmsDelegatedUserDecryptEip712V1, KmsDelegatedUserDecryptEip712V1Message } from '../../types/kms.js';
 import type { Bytes65Hex, ChecksummedAddress } from '../../types/primitives.js';
-import { kmsDelegatedUserDecryptEip712Types } from '../../kms/kmsDelegatedUserDecryptEip712Types.js';
+import { kmsDelegatedUserDecryptEip712V1Types } from '../../kms/kmsDelegatedUserDecryptEip712V1Types.js';
 import { ThresholdSignerError, UnknownSignerError } from '../../errors/SignersError.js';
 import { createKmsEip712Domain } from '../../kms/createKmsEip712Domain.js';
 import { recoverSigners } from '../runtime/recoverSigners.js';
 
-export type VerifyKmsDelegatedUserDecryptEip712Parameters = {
+export type VerifyKmsDelegatedUserDecryptEip712V1Parameters = {
   readonly signer: ChecksummedAddress;
-  readonly message: KmsDelegatedUserDecryptEip712Message;
+  readonly message: KmsDelegatedUserDecryptEip712V1Message;
   readonly signature: Bytes65Hex;
 };
 
-export async function verifyKmsDelegatedUserDecryptEip712(
+export async function verifyKmsDelegatedUserDecryptEip712V1(
   context: { readonly chain: FhevmChain; readonly runtime: FhevmRuntime },
-  parameters: VerifyKmsDelegatedUserDecryptEip712Parameters,
+  parameters: VerifyKmsDelegatedUserDecryptEip712V1Parameters,
 ): Promise<void> {
-  // A 'DelegatedUserDecryptRequestVerification' KmsEIP712Domain (for signed permit)
+  // A 'DelegatedUserDecryptRequestVerification' KmsEip712Domain (for signed permit)
   // uses `chain.id` (NOT fhevm.gateway.id!!)
   const domain = createKmsEip712Domain({
     chainId: context.chain.id,
@@ -26,8 +26,8 @@ export async function verifyKmsDelegatedUserDecryptEip712(
 
   const recoveredAddresses = await recoverSigners(context, {
     domain,
-    types: kmsDelegatedUserDecryptEip712Types,
-    primaryType: 'DelegatedUserDecryptRequestVerification' satisfies KmsDelegatedUserDecryptEip712['primaryType'],
+    types: kmsDelegatedUserDecryptEip712V1Types,
+    primaryType: 'DelegatedUserDecryptRequestVerification' satisfies KmsDelegatedUserDecryptEip712V1['primaryType'],
     signatures: [parameters.signature],
     message: parameters.message,
   });