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

package/core/kms/{kmsDelegatedUserDecryptEip712Types.ts → kmsDelegatedUserDecryptEip712V1Types.ts}

@@ -1,10 +1,11 @@
-import type { KmsDelegateUserDecryptEip712Types } from '../types/kms.js';
+import type { KmsDelegatedUserDecryptEip712V1Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsDelegateUserDecryptEIP712Types
+// KmsDelegatedUserDecryptEip712V1Types
 ////////////////////////////////////////////////////////////////////////////////
 
-export const kmsDelegatedUserDecryptEip712Types: KmsDelegateUserDecryptEip712Types = {
+// Careful: do not change any fields in this structure
+export const kmsDelegatedUserDecryptEip712V1Types: KmsDelegatedUserDecryptEip712V1Types = {
   EIP712Domain: [
     { name: 'name', type: 'string' },
     { name: 'version', type: 'string' },
@@ -24,8 +25,8 @@ export const kmsDelegatedUserDecryptEip712Types: KmsDelegateUserDecryptEip712Typ
   ] as const,
 } as const;
 
-Object.freeze(kmsDelegatedUserDecryptEip712Types);
-Object.freeze(kmsDelegatedUserDecryptEip712Types.EIP712Domain);
-Object.freeze(kmsDelegatedUserDecryptEip712Types.DelegatedUserDecryptRequestVerification);
-kmsDelegatedUserDecryptEip712Types.EIP712Domain.forEach(Object.freeze);
-kmsDelegatedUserDecryptEip712Types.DelegatedUserDecryptRequestVerification.forEach(Object.freeze);
+Object.freeze(kmsDelegatedUserDecryptEip712V1Types);
+Object.freeze(kmsDelegatedUserDecryptEip712V1Types.EIP712Domain);
+Object.freeze(kmsDelegatedUserDecryptEip712V1Types.DelegatedUserDecryptRequestVerification);
+kmsDelegatedUserDecryptEip712V1Types.EIP712Domain.forEach(Object.freeze);
+kmsDelegatedUserDecryptEip712V1Types.DelegatedUserDecryptRequestVerification.forEach(Object.freeze);

package/core/kms/kmsPublicDecryptEip712Types.ts

@@ -1,7 +1,7 @@
 import type { KmsPublicDecryptEip712Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsPublicDecryptEIP712Types
+// KmsPublicDecryptEip712Types
 ////////////////////////////////////////////////////////////////////////////////
 
 export const kmsPublicDecryptEip712Types: KmsPublicDecryptEip712Types = {

package/core/kms/{kmsUserDecryptEip712Types.ts → kmsUserDecryptEip712V1Types.ts}

@@ -1,10 +1,11 @@
-import type { KmsUserDecryptEip712Types } from '../types/kms.js';
+import type { KmsUserDecryptEip712V1Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsUserDecryptEIP712Types
+// KmsUserDecryptEip712V1Types
 ////////////////////////////////////////////////////////////////////////////////
 
-export const kmsUserDecryptEip712Types: KmsUserDecryptEip712Types = {
+// Careful: do not change any fields in this structure
+export const kmsUserDecryptEip712V1Types: KmsUserDecryptEip712V1Types = {
   EIP712Domain: [
     { name: 'name', type: 'string' },
     { name: 'version', type: 'string' },
@@ -23,8 +24,8 @@ export const kmsUserDecryptEip712Types: KmsUserDecryptEip712Types = {
   ] as const,
 } as const;
 
-Object.freeze(kmsUserDecryptEip712Types);
-Object.freeze(kmsUserDecryptEip712Types.EIP712Domain);
-Object.freeze(kmsUserDecryptEip712Types.UserDecryptRequestVerification);
-kmsUserDecryptEip712Types.EIP712Domain.forEach(Object.freeze);
-kmsUserDecryptEip712Types.UserDecryptRequestVerification.forEach(Object.freeze);
+Object.freeze(kmsUserDecryptEip712V1Types);
+Object.freeze(kmsUserDecryptEip712V1Types.EIP712Domain);
+Object.freeze(kmsUserDecryptEip712V1Types.UserDecryptRequestVerification);
+kmsUserDecryptEip712V1Types.EIP712Domain.forEach(Object.freeze);
+kmsUserDecryptEip712V1Types.UserDecryptRequestVerification.forEach(Object.freeze);

package/core/kms/kmsUserDecryptEip712V2Types.ts

@@ -1,9 +1,10 @@
 import type { KmsUserDecryptEip712V2Types } from '../types/kms.js';
 
 ////////////////////////////////////////////////////////////////////////////////
-// KmsUserDecryptEIP712V2Types (RFC-016)
+// KmsUserDecryptEip712V2Types (RFC-016)
 ////////////////////////////////////////////////////////////////////////////////
 
+// Careful: do not change any fields in this structure
 export const kmsUserDecryptEip712V2Types: KmsUserDecryptEip712V2Types = {
   EIP712Domain: [
     { name: 'name', type: 'string' },

package/core/kms/publicDecrypt.ts

@@ -73,7 +73,7 @@ export async function publicDecrypt(context: Context, parameters: Parameters): P
   // 5. Call relayer
   const {
     orderedAbiEncodedClearValues,
-    kmsPublicDecryptEIP712Signatures,
+    kmsPublicDecryptEip712Signatures,
     extraData: relayerExtraData,
   } = await context.runtime.relayer.fetchPublicDecrypt(context, {
     payload: {
@@ -97,7 +97,7 @@ export async function publicDecrypt(context: Context, parameters: Parameters): P
     originToken,
     orderedHandles: orderedHandles,
     orderedAbiEncodedClearValues,
-    kmsPublicDecryptEIP712Signatures,
+    kmsPublicDecryptEip712Signatures,
     kmsSignersContext: reconciledKmsSignersContext,
   });
 

package/core/kms/utils.ts

@@ -26,35 +26,3 @@ export function assertKmsDecryptionBitLimit(handles: readonly Handle[]): UintNum
 
   return total as UintNumber;
 }
-
-export function assertKmsEIP712DeadlineValidity(
-  {
-    startTimestamp,
-    durationDays,
-  }: {
-    startTimestamp: bigint | number | string;
-    durationDays: bigint | number | string;
-  },
-  maxDurationDays: UintNumber,
-): void {
-  if (durationDays === 0) {
-    throw Error('durationDays is zero');
-  }
-
-  const durationDaysBigInt = BigInt(durationDays);
-  if (durationDaysBigInt > BigInt(maxDurationDays)) {
-    throw Error(`durationDays is above max duration of ${maxDurationDays}`);
-  }
-
-  const startTimestampBigInt = BigInt(startTimestamp);
-
-  const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
-  if (startTimestampBigInt > currentTimestamp) {
-    throw Error('startTimestamp is set in the future');
-  }
-
-  const durationInSeconds = durationDaysBigInt * BigInt(24 * 60 * 60);
-  if (startTimestampBigInt + durationInSeconds < currentTimestamp) {
-    throw Error('request has expired');
-  }
-}

package/core/kms/verifyKmsPublicDecryptEip712-p.ts

@@ -19,7 +19,7 @@ type Context = {
 type Parameters = {
   readonly orderedHandles: readonly Handle[];
   readonly orderedAbiEncodedClearValues: BytesHex;
-  readonly kmsPublicDecryptEIP712Signatures: readonly Bytes65Hex[];
+  readonly kmsPublicDecryptEip712Signatures: readonly Bytes65Hex[];
   readonly kmsSignersContext: KmsSignersContext;
 };
 
@@ -28,7 +28,7 @@ type Parameters = {
 export async function verifyKmsPublicDecryptEip712(context: Context, parameters: Parameters): Promise<void> {
   const { kmsSignersContext, orderedHandles: orderedEncryptedValues, orderedAbiEncodedClearValues } = parameters;
 
-  // TODO:  use createKmsPublicDecryptEIP712 instead!
+  // TODO:  use createKmsPublicDecryptEip712 instead!
 
   const extraData: BytesHex = kmsSignersContextToExtraData(kmsSignersContext);
 
@@ -66,7 +66,7 @@ export async function verifyKmsPublicDecryptEip712(context: Context, parameters:
     domain,
     types: kmsPublicDecryptEip712Types,
     primaryType: 'PublicDecryptVerification',
-    signatures: parameters.kmsPublicDecryptEIP712Signatures,
+    signatures: parameters.kmsPublicDecryptEip712Signatures,
     message,
   });
 

package/core/modules/decrypt/module/api-p.ts

@@ -76,7 +76,7 @@ type TypedPlaintextWasmType = TypedPlaintext & {
   readonly [__TypedPlaintextWasm]: never;
 };
 
-type KmsEIP712DomainWasmType = Readonly<
+type KmsEip712DomainWasmType = Readonly<
   Omit<KmsEip712Domain, 'chainId' | 'verifyingContract'> & {
     readonly chain_id: Uint8Array;
     readonly verifying_contract: ChecksummedAddress;
@@ -297,16 +297,16 @@ export async function decryptAndReconstruct(
     kmsLib,
   );
 
-  // KmsEIP712Domain
-  const kmsEIP712Domain: KmsEip712Domain = metadata.eip712Domain;
+  // KmsEip712Domain
+  const kmsEip712Domain: KmsEip712Domain = metadata.eip712Domain;
   const clientAddress: ChecksummedAddress = metadata.eip712SignerAddress;
 
   // To be modified! use uint64ToBytes32 instead
-  const eip712DomainWasmArg: KmsEIP712DomainWasmType = {
-    name: kmsEIP712Domain.name,
-    version: kmsEIP712Domain.version,
-    chain_id: uint32ToBytes32(kmsEIP712Domain.chainId), // gateway chainId
-    verifying_contract: kmsEIP712Domain.verifyingContract,
+  const eip712DomainWasmArg: KmsEip712DomainWasmType = {
+    name: kmsEip712Domain.name,
+    version: kmsEip712Domain.version,
+    chain_id: uint32ToBytes32(kmsEip712Domain.chainId), // gateway chainId
+    verifying_contract: kmsEip712Domain.verifyingContract,
     salt: null,
   };
 

package/core/modules/decrypt/module/init-p.ts

@@ -90,21 +90,21 @@ async function _resolveKmsAssets(
 function _logResolvedKmsAssets(resolvedAssets: ResolvedKmsAssets, logger: FhevmRuntimeConfig['logger']): void {
   const { wasm } = resolvedAssets;
   if (wasm.resolution === 'user') {
-    logger?.debug(`resolve tkms wasm filename using 'locateFile' function: ${wasm.filename} -> url: ${wasm.url}`);
+    logger?.debug?.(`resolve tkms wasm filename using 'locateFile' function: ${wasm.filename} -> url: ${wasm.url}`);
   } else if (wasm.resolution === 'node') {
     if (wasm.url === undefined) {
       // Auto-derived assets were missing on disk (e.g. a bundler such as Turbopack
       // relocated the package) and were cleared by _resolveTkmsAssets -> base64.
-      logger?.debug(
+      logger?.debug?.(
         `tkms auto-derived assets not found on disk (bundler relocation?); using embedded base64 ` +
           `(wasm: ${wasm.localRelativePath})`,
       );
     } else {
-      logger?.debug(`resolve tkms wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
+      logger?.debug?.(`resolve tkms wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
     }
   } else {
     // 'none': browser zero-config (no 'locateFile', not Node) -> embedded base64.
-    logger?.debug(`resolve tkms assets using embedded base64 (browser, no 'locateFile')`);
+    logger?.debug?.(`resolve tkms assets using embedded base64 (browser, no 'locateFile')`);
   }
 }
 
@@ -170,7 +170,7 @@ async function _resolveTkmsModuleConfig(
     logger: parameters.logger,
   };
 
-  parameters.logger?.debug(JSON.stringify(cfg, null, 2));
+  //parameters.logger?.debug?.(JSON.stringify(cfg, null, 2));
 
   return cfg;
 }
@@ -226,11 +226,11 @@ async function _compileWasmModule(cfg: ResolvedTkmsModuleConfig): Promise<WebAss
   let wasmModule;
 
   if (cfg.assets.wasm.url !== undefined) {
-    cfg.logger?.debug(`compile tkms verified wasm at: ${cfg.assets.wasm.url}`);
+    cfg.logger?.debug?.(`compile tkms verified wasm at: ${cfg.assets.wasm.url}`);
     wasmModule = await isomorphicCompileVerifiedWasm(cfg.assets.wasm.url, cfg.assets.wasm.sha256);
   } else {
     const { tkmsWasmBase64, tkmsWasmBase64CompressionFormat } = await loadKmsWasmBase64(cfg.version);
-    cfg.logger?.debug(
+    cfg.logger?.debug?.(
       `compile tkms wasm from embedded base64 (compression:${tkmsWasmBase64CompressionFormat ?? 'none'})`,
     );
     wasmModule = await isomorphicCompileWasmFromBase64(tkmsWasmBase64, tkmsWasmBase64CompressionFormat);

package/core/modules/encrypt/module/init-p.ts

@@ -208,23 +208,25 @@ async function _resolveTfheAssets(
 function _logResolvedTfheAssets(resolvedAssets: ResolvedTfheAssets, logger: FhevmRuntimeConfig['logger']): void {
   const { wasm, worker } = resolvedAssets;
   if (wasm.resolution === 'user') {
-    logger?.debug(`resolve tfhe wasm filename using 'locateFile' function: ${wasm.filename} -> url: ${wasm.url}`);
-    logger?.debug(`resolve tfhe worker filename using 'locateFile' function: ${worker.filename} -> url: ${worker.url}`);
+    logger?.debug?.(`resolve tfhe wasm filename using 'locateFile' function: ${wasm.filename} -> url: ${wasm.url}`);
+    logger?.debug?.(
+      `resolve tfhe worker filename using 'locateFile' function: ${worker.filename} -> url: ${worker.url}`,
+    );
   } else if (wasm.resolution === 'node') {
     if (wasm.url === undefined) {
       // Auto-derived assets were missing on disk (e.g. a bundler such as Turbopack
       // relocated the package) and were cleared by _resolveTfheAssets -> base64.
-      logger?.debug(
+      logger?.debug?.(
         `tfhe auto-derived assets not found on disk (bundler relocation?); using embedded base64 ` +
           `(wasm: ${wasm.localRelativePath}, worker: ${worker.localRelativePath})`,
       );
     } else {
-      logger?.debug(`resolve tfhe wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
-      logger?.debug(`resolve tfhe worker local path: ${worker.localRelativePath} -> url: ${worker.url}`);
+      logger?.debug?.(`resolve tfhe wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
+      logger?.debug?.(`resolve tfhe worker local path: ${worker.localRelativePath} -> url: ${worker.url}`);
     }
   } else {
     // 'none': browser zero-config (no 'locateFile', not Node) -> embedded base64.
-    logger?.debug(`resolve tfhe assets using embedded base64 (browser, no 'locateFile')`);
+    logger?.debug?.(`resolve tfhe assets using embedded base64 (browser, no 'locateFile')`);
   }
 }
 
@@ -475,7 +477,10 @@ async function _resolveTfheModuleConfig(
     // Single source of truth for browser-vs-Node, resolved on the main thread
     // (robust to bundler `process` shims) — the worker bootstrap no longer detects it.
     isBrowserLike: isBrowserLike(),
-    logger: parameters.logger,
+    logger:
+      parameters.logger?.debug !== undefined && parameters.logger.error !== undefined
+        ? { debug: parameters.logger.debug, error: parameters.logger.error }
+        : undefined,
   });
 
   const cfg = {
@@ -488,7 +493,7 @@ async function _resolveTfheModuleConfig(
     supportsThreads,
   };
 
-  parameters.logger?.debug(JSON.stringify(cfg, null, 2));
+  //parameters.logger?.debug?.(JSON.stringify(cfg, null, 2));
 
   return cfg;
 }
@@ -572,11 +577,11 @@ async function _compileWasmModule(cfg: ResolvedTfheModuleConfig): Promise<WebAss
   let wasmModule;
 
   if (cfg.assets.wasm.url !== undefined) {
-    cfg.logger?.debug(`compile verified wasm at: ${cfg.assets.wasm.url}`);
+    cfg.logger?.debug?.(`compile verified wasm at: ${cfg.assets.wasm.url}`);
     wasmModule = await isomorphicCompileVerifiedWasm(cfg.assets.wasm.url, cfg.assets.wasm.sha256);
   } else {
     const { tfheWasmBase64, tfheWasmBase64CompressionFormat } = await loadTfheWasmBase64(cfg.version);
-    cfg.logger?.debug(`compile wasm from embedded base64 (compression:${tfheWasmBase64CompressionFormat ?? 'none'})`);
+    cfg.logger?.debug?.(`compile wasm from embedded base64 (compression:${tfheWasmBase64CompressionFormat ?? 'none'})`);
     wasmModule = await isomorphicCompileWasmFromBase64(tfheWasmBase64, tfheWasmBase64CompressionFormat);
   }
 
@@ -599,7 +604,7 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
 
   // 4. Spawn Web Workers for parallel FHE operations (skipped when single-threaded)
   if (!cfg.singleThread) {
-    cfg.logger?.debug(`initThreadPool(${cfg.numberOfThreads})`);
+    cfg.logger?.debug?.(`initThreadPool(${cfg.numberOfThreads})`);
     await tfheLib.initThreadPool(cfg.numberOfThreads);
   }
 

package/core/modules/relayer/cleartext/fetchPublicDecrypt.ts

@@ -46,7 +46,7 @@ export async function fetchPublicDecrypt(
   const signersAddress = res[2] as readonly ChecksummedAddress[];
   const signers = getKmsSignersPrivateKeyMap(relayerClient);
 
-  const kmsPublicDecryptEIP712Signatures: Bytes65Hex[] = [];
+  const kmsPublicDecryptEip712Signatures: Bytes65Hex[] = [];
 
   for (let i = 0; i < signersAddress.length; ++i) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -56,12 +56,12 @@ export async function fetchPublicDecrypt(
     }
 
     const signature = await cleartextEthereumModule.sign({ hash: digest, privateKey });
-    kmsPublicDecryptEIP712Signatures.push(signature);
+    kmsPublicDecryptEip712Signatures.push(signature);
   }
 
   return {
     orderedAbiEncodedClearValues: res[0] as BytesHex,
-    kmsPublicDecryptEIP712Signatures,
+    kmsPublicDecryptEip712Signatures,
     extraData: res[4] as BytesHex,
   };
 }

package/core/modules/relayer/cleartext/fetchUserDecrypt.ts

@@ -1,7 +1,7 @@
 import type { BytesHex, ChecksummedAddress } from '../../../types/primitives.js';
 import type { FetchUserDecryptResultItem } from '../../../types/relayer.js';
 import type { CleartextEthereumModule } from '../../ethereum/types-ct.js';
-import type { FetchUserDecryptParameters, FetchUserDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
+import type { FetchUserDecryptParametersV1, FetchUserDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
 import { remove0x } from '../../../base/string.js';
 import { asUint32BigInt, tryParseUintBigIntString, randomUniqueUints } from '../../../base/uint.js';
 import { getTrustedClient } from '../../../runtime/CoreFhevm-p.js';
@@ -61,7 +61,7 @@ const userDecryptAbi = [
 
 export async function fetchUserDecrypt(
   relayerClient: RelayerClientWithRuntime,
-  parameters: FetchUserDecryptParameters,
+  parameters: FetchUserDecryptParametersV1,
 ): Promise<FetchUserDecryptReturnType> {
   const cleartextEthereumModule = relayerClient.runtime.ethereum as CleartextEthereumModule;
   const { payload } = parameters;

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

@@ -39,7 +39,7 @@ export async function fetchPublicDecrypt(
 
   return {
     orderedAbiEncodedClearValues: ensure0x(result.decryptedValue),
-    kmsPublicDecryptEIP712Signatures: result.signatures.map(ensure0x) as Bytes65Hex[],
+    kmsPublicDecryptEip712Signatures: result.signatures.map(ensure0x) as Bytes65Hex[],
     extraData: result.extraData,
   };
 }

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

@@ -1,10 +1,14 @@
-import type { KmsSigncryptedShare } from '../../../types/kms-p.js';
-import type { FetchUserDecryptPayload } from '../../../types/relayer-p.js';
-import type { FetchUserDecryptResult } from '../../../types/relayer.js';
-import type { FetchUserDecryptParameters, FetchUserDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
-import { remove0x } from '../../../base/string.js';
-import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
-import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
+import type {
+  FetchUserDecryptParameters,
+  FetchUserDecryptParametersV1,
+  FetchUserDecryptParametersV2,
+  FetchUserDecryptReturnType,
+  RelayerClientWithRuntime,
+} from '../types.js';
+import { getResolvedProtocolVersion } from '../../../runtime/CoreFhevm-p.js';
+import { isSemverStrictlyBefore } from '../../../base/semver.js';
+import { fetchUserDecryptV1 } from './fetchUserDecryptV1.js';
+import { fetchUserDecryptV2 } from './fetchUserDecryptV2.js';
 
 //////////////////////////////////////////////////////////////////////////////
 // fetchUserDecrypt
@@ -14,56 +18,16 @@ export async function fetchUserDecrypt(
   relayerClient: RelayerClientWithRuntime,
   parameters: FetchUserDecryptParameters,
 ): Promise<FetchUserDecryptReturnType> {
-  const { options, payload } = parameters;
-
-  const firstHandleContractPair = payload.handleContractPairs[0];
-  if (firstHandleContractPair === undefined) {
-    throw new Error('Empty handle contract pairs');
+  const protocolVersion = getResolvedProtocolVersion(relayerClient);
+  if (protocolVersion === undefined) {
+    throw new Error(
+      'Unable to resolve protocol version from context, ensure proper initialization of the FhevmRuntime and FhevmChain.',
+    );
   }
 
-  // retrieve chainId using handles
-  const contractsChainId = firstHandleContractPair.handle.chainId.toString();
-
-  const relayerPayload: FetchUserDecryptPayload = {
-    handleContractPairs: payload.handleContractPairs.map((pair) => {
-      return {
-        handle: pair.handle.bytes32Hex,
-        contractAddress: pair.contractAddress,
-      };
-    }),
-    requestValidity: {
-      startTimestamp: payload.kmsDecryptEip712Message.startTimestamp,
-      durationDays: payload.kmsDecryptEip712Message.durationDays,
-    },
-    contractsChainId,
-    contractAddresses: payload.kmsDecryptEip712Message.contractAddresses,
-    userAddress: payload.kmsDecryptEip712Signer,
-    signature: remove0x(payload.kmsDecryptEip712Signature),
-    extraData: payload.kmsDecryptEip712Message.extraData,
-    publicKey: remove0x(payload.kmsDecryptEip712Message.publicKey),
-  };
-
-  const hasAuth: boolean = options?.auth !== undefined;
-  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.chain.fhevm.relayerUrl, hasAuth);
-  const url = buildRelayerUrlString(relayerBaseUrl, 'v2/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;
-  });
+  if (isSemverStrictlyBefore(protocolVersion.version, '0.14.0')) {
+    return await fetchUserDecryptV1(relayerClient, parameters as FetchUserDecryptParametersV1);
+  }
 
-  return shares;
+  return await fetchUserDecryptV2(relayerClient, parameters as FetchUserDecryptParametersV2);
 }

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

@@ -0,0 +1,69 @@
+import type { KmsSigncryptedShare } from '../../../types/kms-p.js';
+import type { FetchUserDecryptPayload as FetchUserDecryptPayloadV1 } from '../../../types/relayer-p.js';
+import type { FetchUserDecryptResult } from '../../../types/relayer.js';
+import type { FetchUserDecryptParametersV1, FetchUserDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
+import { remove0x } from '../../../base/string.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
+
+//////////////////////////////////////////////////////////////////////////////
+// fetchUserDecryptV1 (protocol version < 0.14.0)
+//////////////////////////////////////////////////////////////////////////////
+
+export async function fetchUserDecryptV1(
+  relayerClient: RelayerClientWithRuntime,
+  parameters: FetchUserDecryptParametersV1,
+): Promise<FetchUserDecryptReturnType> {
+  const { options, payload } = parameters;
+
+  const firstHandleContractPair = payload.handleContractPairs[0];
+  if (firstHandleContractPair === undefined) {
+    throw new Error('Empty handle contract pairs');
+  }
+
+  // retrieve chainId using handles
+  const contractsChainId = firstHandleContractPair.handle.chainId.toString();
+
+  const relayerPayload: FetchUserDecryptPayloadV1 = {
+    handleContractPairs: payload.handleContractPairs.map((pair) => {
+      return {
+        handle: pair.handle.bytes32Hex,
+        contractAddress: pair.contractAddress,
+      };
+    }),
+    requestValidity: {
+      startTimestamp: payload.kmsDecryptEip712Message.startTimestamp,
+      durationDays: payload.kmsDecryptEip712Message.durationDays,
+    },
+    contractsChainId,
+    contractAddresses: payload.kmsDecryptEip712Message.contractAddresses,
+    userAddress: payload.kmsDecryptEip712Signer,
+    signature: remove0x(payload.kmsDecryptEip712Signature),
+    extraData: payload.kmsDecryptEip712Message.extraData,
+    publicKey: remove0x(payload.kmsDecryptEip712Message.publicKey),
+  };
+
+  const hasAuth: boolean = options?.auth !== undefined;
+  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.chain.fhevm.relayerUrl, hasAuth);
+  const url = buildRelayerUrlString(relayerBaseUrl, 'v2/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/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;
+}