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

package/core/kms/{createKmsDelegatedUserDecryptEip712.ts → createKmsDelegatedUserDecryptEip712V1.ts}

@@ -1,4 +1,4 @@
-import type { KmsDelegatedUserDecryptEip712 } from '../types/kms.js';
+import type { KmsDelegatedUserDecryptEip712V1 } from '../types/kms.js';
 import type { BytesHex } from '../types/primitives.js';
 import type { ErrorMetadataParams } from '../base/errors/ErrorBase.js';
 import {
@@ -11,13 +11,13 @@ import { asBytesHex, assertIsBytesHex, bytesToHexLarge } from '../base/bytes.js'
 import { ensure0x } from '../base/string.js';
 import { assertIsUintNumber } from '../base/uint.js';
 import { createKmsEip712Domain } from './createKmsEip712Domain.js';
-import { _assertIsKmsUserDecryptEip712Base } from './createKmsUserDecryptEip712.js';
-import { kmsDelegatedUserDecryptEip712Types } from './kmsDelegatedUserDecryptEip712Types.js';
+import { _assertIsKmsUserDecryptEip712V1Base } from './createKmsUserDecryptEip712V1.js';
+import { kmsDelegatedUserDecryptEip712V1Types } from './kmsDelegatedUserDecryptEip712V1Types.js';
 import { assertIsKmsExtraData } from './kmsExtraData.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export type CreateKmsDelegatedUserDecryptEip712Parameters = {
+export type CreateKmsDelegatedUserDecryptEip712V1Parameters = {
   readonly verifyingContractAddressDecryption: string;
   readonly chainId: number | bigint;
   readonly publicKey: string | Uint8Array;
@@ -29,12 +29,12 @@ export type CreateKmsDelegatedUserDecryptEip712Parameters = {
 };
 
 ////////////////////////////////////////////////////////////////////////////////
-// createKmsDelegatedUserDecryptEip712
+// createKmsDelegatedUserDecryptEip712V1
 ////////////////////////////////////////////////////////////////////////////////
 
-export function createKmsDelegatedUserDecryptEip712(
-  parameters: CreateKmsDelegatedUserDecryptEip712Parameters,
-): KmsDelegatedUserDecryptEip712 {
+export function createKmsDelegatedUserDecryptEip712V1(
+  parameters: CreateKmsDelegatedUserDecryptEip712V1Parameters,
+): KmsDelegatedUserDecryptEip712V1 {
   const {
     verifyingContractAddressDecryption,
     chainId,
@@ -58,15 +58,15 @@ export function createKmsDelegatedUserDecryptEip712(
 
   const checksummedDelegatorAddress = addressToChecksummedAddress(delegatorAddress);
 
-  const primaryType: KmsDelegatedUserDecryptEip712['primaryType'] = 'DelegatedUserDecryptRequestVerification';
+  const primaryType: KmsDelegatedUserDecryptEip712V1['primaryType'] = 'DelegatedUserDecryptRequestVerification';
 
   const domain = createKmsEip712Domain({
     chainId,
     verifyingContractAddressDecryption,
   });
 
-  const eip712: KmsDelegatedUserDecryptEip712 = {
-    types: kmsDelegatedUserDecryptEip712Types,
+  const eip712: KmsDelegatedUserDecryptEip712V1 = {
+    types: kmsDelegatedUserDecryptEip712V1Types,
     primaryType,
     domain,
     message: {
@@ -92,21 +92,21 @@ export function createKmsDelegatedUserDecryptEip712(
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export function assertIsKmsDelegatedUserDecryptEip712(
+export function assertIsKmsDelegatedUserDecryptEip712V1(
   value: unknown,
   name: string,
   options: ErrorMetadataParams,
-): asserts value is KmsDelegatedUserDecryptEip712 {
-  _assertIsKmsUserDecryptEip712Base(
+): asserts value is KmsDelegatedUserDecryptEip712V1 {
+  _assertIsKmsUserDecryptEip712V1Base(
     value,
     name,
-    'DelegatedUserDecryptRequestVerification' satisfies KmsDelegatedUserDecryptEip712['primaryType'],
+    'DelegatedUserDecryptRequestVerification' satisfies KmsDelegatedUserDecryptEip712V1['primaryType'],
     options,
   );
 
   assertRecordChecksummedAddressProperty(
     value.message,
-    'delegatorAddress' satisfies keyof KmsDelegatedUserDecryptEip712['message'],
+    'delegatorAddress' satisfies keyof KmsDelegatedUserDecryptEip712V1['message'],
     `${name}.message`,
     options,
   );

package/core/kms/createKmsPublicDecryptEip712.ts

@@ -16,7 +16,7 @@ export type CreateKmsPublicDecryptEip712Parameters = {
 };
 
 ////////////////////////////////////////////////////////////////////////////////
-// createKmsPublicDecryptEIP712
+// createKmsPublicDecryptEip712
 ////////////////////////////////////////////////////////////////////////////////
 
 export function createKmsPublicDecryptEip712(

package/core/kms/{createKmsUserDecryptEip712.ts → createKmsUserDecryptEip712V1.ts}

@@ -1,7 +1,7 @@
 import type { ErrorMetadataParams } from '../base/errors/ErrorBase.js';
-import type { KmsEip712Domain, KmsUserDecryptEip712 } from '../types/kms.js';
+import type { KmsEip712Domain, KmsUserDecryptEip712V1 } from '../types/kms.js';
 import type { BytesHex } from '../types/primitives.js';
-import type { KmsUserDecryptEip712Message } from '../types/kms.js';
+import type { KmsUserDecryptEip712V1Message } from '../types/kms.js';
 import {
   addressToChecksummedAddress,
   assertIsAddress,
@@ -14,12 +14,13 @@ import { assertRecordNonNullableProperty } from '../base/record.js';
 import { assertRecordStringProperty, ensure0x } from '../base/string.js';
 import { assertIsUint64, assertIsUintNumber } from '../base/uint.js';
 import { assertIsKmsExtraData } from './kmsExtraData.js';
-import { kmsUserDecryptEip712Types } from './kmsUserDecryptEip712Types.js';
+import { kmsUserDecryptEip712V1Types } from './kmsUserDecryptEip712V1Types.js';
+import { kmsDelegatedUserDecryptEip712V1Types } from './kmsDelegatedUserDecryptEip712V1Types.js';
 import { isDeepEqual } from '../base/object.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export type CreateKmsUserDecryptEip712Parameters = {
+export type CreateKmsUserDecryptEip712V1Parameters = {
   readonly verifyingContractAddressDecryption: string;
   readonly chainId: number | bigint;
   readonly publicKey: string | Uint8Array;
@@ -30,10 +31,12 @@ export type CreateKmsUserDecryptEip712Parameters = {
 };
 
 ////////////////////////////////////////////////////////////////////////////////
-// createKmsUserDecryptEip712
+// createKmsUserDecryptEip712V1
 ////////////////////////////////////////////////////////////////////////////////
 
-export function createKmsUserDecryptEip712(parameters: CreateKmsUserDecryptEip712Parameters): KmsUserDecryptEip712 {
+export function createKmsUserDecryptEip712V1(
+  parameters: CreateKmsUserDecryptEip712V1Parameters,
+): KmsUserDecryptEip712V1 {
   const {
     verifyingContractAddressDecryption,
     chainId,
@@ -55,7 +58,7 @@ export function createKmsUserDecryptEip712(parameters: CreateKmsUserDecryptEip71
 
   const checksummedContractAddresses = contractAddresses.map(addressToChecksummedAddress);
 
-  const primaryType: KmsUserDecryptEip712['primaryType'] = 'UserDecryptRequestVerification';
+  const primaryType: KmsUserDecryptEip712V1['primaryType'] = 'UserDecryptRequestVerification';
 
   const domain = createKmsEip712Domain({
     chainId,
@@ -64,7 +67,7 @@ export function createKmsUserDecryptEip712(parameters: CreateKmsUserDecryptEip71
 
   const eip712 = {
     domain,
-    types: kmsUserDecryptEip712Types,
+    types: kmsUserDecryptEip712V1Types,
     primaryType,
     message: {
       publicKey: publicKeyBytesHex,
@@ -88,25 +91,25 @@ export function createKmsUserDecryptEip712(parameters: CreateKmsUserDecryptEip71
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export function assertIsKmsUserDecryptEip712(
+export function assertIsKmsUserDecryptEip712V1(
   value: unknown,
   name: string,
   options: ErrorMetadataParams,
-): asserts value is KmsUserDecryptEip712 {
-  _assertIsKmsUserDecryptEip712Base(
+): asserts value is KmsUserDecryptEip712V1 {
+  _assertIsKmsUserDecryptEip712V1Base(
     value,
     name,
-    'UserDecryptRequestVerification' satisfies KmsUserDecryptEip712['primaryType'],
+    'UserDecryptRequestVerification' satisfies KmsUserDecryptEip712V1['primaryType'],
     options,
   );
 }
 
 /**
  * Validates the common structure shared by both
- * {@link KmsUserDecryptEip712} and {@link KmsDelegatedUserDecryptEIP712}:
+ * {@link KmsUserDecryptEip712V1} and {@link KmsDelegatedUserDecryptEip712V1}:
  * domain, types, primaryType, and base message fields.
  */
-export function _assertIsKmsUserDecryptEip712Base(
+export function _assertIsKmsUserDecryptEip712V1Base(
   value: unknown,
   name: string,
   primaryType: string,
@@ -115,14 +118,20 @@ export function _assertIsKmsUserDecryptEip712Base(
   readonly domain: KmsEip712Domain;
   readonly types: object;
   readonly primaryType: string;
-  readonly message: KmsUserDecryptEip712Message;
+  readonly message: KmsUserDecryptEip712V1Message;
 } {
   assertRecordNonNullableProperty(value, 'domain', name, options);
   assertIsKmsEip712Domain((value as Record<string, unknown>).domain, `${name}.domain`, options);
 
   assertRecordNonNullableProperty(value, 'types', name, options);
-  if (!isDeepEqual(value.types, kmsUserDecryptEip712Types)) {
-    throw new Error('Unexpected KmsUserDecryptEip712Types');
+
+  const expectedTypes =
+    primaryType === 'DelegatedUserDecryptRequestVerification'
+      ? kmsDelegatedUserDecryptEip712V1Types
+      : kmsUserDecryptEip712V1Types;
+
+  if (!isDeepEqual(value.types, expectedTypes)) {
+    throw new Error('Unexpected KmsUserDecryptEip712V1Types');
   }
 
   assertRecordStringProperty(value, 'primaryType', name, {
@@ -132,19 +141,19 @@ export function _assertIsKmsUserDecryptEip712Base(
 
   assertRecordNonNullableProperty(value, 'message', name, options);
   const msg = (value as Record<string, unknown>).message as Record<string, unknown>;
-  _assertIsKmsUserDecryptEip712Message(msg, `${name}.message`, options);
+  _assertIsKmsUserDecryptEip712V1Message(msg, `${name}.message`, options);
 }
 
 /**
  * Validates the common message fields shared by both
- * {@link KmsUserDecryptEip712} and {@link KmsDelegatedUserDecryptEIP712}.
+ * {@link KmsUserDecryptEip712V1} and {@link KmsDelegatedUserDecryptEip712V1}.
  */
-function _assertIsKmsUserDecryptEip712Message(
+function _assertIsKmsUserDecryptEip712V1Message(
   msg: unknown,
   msgName: string,
   options: ErrorMetadataParams,
-): asserts msg is KmsUserDecryptEip712Message {
-  type MessageType = KmsUserDecryptEip712['message'];
+): asserts msg is KmsUserDecryptEip712V1Message {
+  type MessageType = KmsUserDecryptEip712V1['message'];
   assertRecordBytesHexProperty(msg, 'publicKey' satisfies keyof MessageType, msgName, options);
   assertRecordChecksummedAddressArrayProperty(msg, 'contractAddresses' satisfies keyof MessageType, msgName, options);
   assertRecordStringProperty(msg, 'startTimestamp' satisfies keyof MessageType, msgName, options);

package/core/kms/createKmsUserDecryptEip712V2.ts

@@ -27,7 +27,7 @@ export type CreateKmsUserDecryptEip712V2Parameters = {
   readonly publicKey: string | Uint8Array;
   readonly allowedContracts: readonly string[];
   readonly startTimestamp: number | bigint;
-  readonly durationSeconds: number | bigint;
+  readonly durationSeconds: bigint;
   readonly extraData: string;
 };
 

package/core/kms/decryptValuesFromPairs.ts

@@ -7,10 +7,13 @@ import type { FhevmChain } from '../types/fhevmChain.js';
 import type { KmsSigncryptedShares } from '../types/kms.js';
 import type { ChecksummedAddress, TypedValue } from '../types/primitives.js';
 import type { RelayerDelegatedUserDecryptOptions, RelayerUserDecryptOptions } from '../types/relayer.js';
-import type { SignedDelegatedDecryptionPermit, SignedSelfDecryptionPermit } from '../types/signedDecryptionPermit.js';
+import type { SignedDecryptionPermit } from '../types/signedDecryptionPermit.js';
 import type { TransportKeyPair } from './TransportKeyPair-p.js';
+import { isSemverStrictlyBefore } from '../base/semver.js';
+import { getResolvedProtocolVersion } from '../runtime/CoreFhevm-p.js';
 import { decryptKmsSigncryptedShares } from './decryptKmsSigncryptedShares-p.js';
-import { fetchKmsSigncryptedShares } from './fetchKmsSigncryptedShares-p.js';
+import { fetchKmsSigncryptedSharesV1 } from './fetchKmsSigncryptedSharesV1-p.js';
+import { fetchKmsSigncryptedSharesV2 } from './fetchKmsSigncryptedSharesV2-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -22,25 +25,19 @@ type Context = {
   readonly options: { readonly batchRpcCalls: boolean };
 };
 
-type Parameters =
-  | {
-      readonly pairs: ReadonlyArray<{
-        readonly handle: Handle;
-        readonly contractAddress: ChecksummedAddress;
-      }>;
-      readonly signedPermit: SignedSelfDecryptionPermit;
-      readonly transportKeyPair: TransportKeyPair;
-      readonly options?: RelayerUserDecryptOptions | undefined;
-    }
-  | {
-      readonly pairs: ReadonlyArray<{
-        readonly handle: Handle;
-        readonly contractAddress: ChecksummedAddress;
-      }>;
-      readonly signedPermit: SignedDelegatedDecryptionPermit;
-      readonly transportKeyPair: TransportKeyPair;
-      readonly options?: RelayerDelegatedUserDecryptOptions | undefined;
-    };
+type Parameters = {
+  readonly pairs: ReadonlyArray<{
+    readonly handle: Handle;
+    readonly contractAddress: ChecksummedAddress;
+    // ownerAddress is only relevant for V2 (protocol >= 0.14.0). When omitted,
+    // fetchKmsSigncryptedSharesV2 defaults to userAddress (direct-access path).
+    // Provide it explicitly only for delegated handles where ownerAddress !== userAddress.
+    readonly ownerAddress?: ChecksummedAddress | undefined;
+  }>;
+  readonly signedPermit: SignedDecryptionPermit;
+  readonly transportKeyPair: TransportKeyPair;
+  readonly options?: RelayerUserDecryptOptions | RelayerDelegatedUserDecryptOptions | undefined;
+};
 
 export type ReturnType = readonly TypedValue[];
 
@@ -49,7 +46,22 @@ export type ReturnType = readonly TypedValue[];
 export async function decryptValuesFromPairs(fhevm: Context, parameters: Parameters): Promise<ReturnType> {
   const { transportKeyPair: transportKeyPair } = parameters;
 
-  const kmsSigncryptedShares: KmsSigncryptedShares = await fetchKmsSigncryptedShares(fhevm, parameters);
+  const protocolVersion = getResolvedProtocolVersion(fhevm);
+  if (protocolVersion === undefined) {
+    throw new Error(
+      'Unable to resolve protocol version from context, ensure proper initialization of the FhevmRuntime and FhevmChain.',
+    );
+  }
+
+  let kmsSigncryptedShares: KmsSigncryptedShares;
+  if (isSemverStrictlyBefore(protocolVersion.version, '0.14.0')) {
+    kmsSigncryptedShares = await fetchKmsSigncryptedSharesV1(fhevm, parameters);
+  } else {
+    kmsSigncryptedShares = await fetchKmsSigncryptedSharesV2(fhevm, {
+      ...parameters,
+      options: parameters.options as RelayerUserDecryptOptions | undefined,
+    });
+  }
 
   // Using the `KmsSigncryptedShares` decrypt and reconstruct clear values
   return decryptKmsSigncryptedShares(fhevm, {

package/core/kms/{fetchKmsSigncryptedShares-p.ts → fetchKmsSigncryptedSharesV1-p.ts}

@@ -5,12 +5,12 @@ import type { KmsSignersContext } from '../types/kmsSignersContext.js';
 import type { ChecksummedAddress, Uint64BigInt } from '../types/primitives.js';
 import type { FhevmChain } from '../types/fhevmChain.js';
 import type { RelayerDelegatedUserDecryptOptions, RelayerUserDecryptOptions } from '../types/relayer.js';
-import type { SignedDelegatedDecryptionPermit, SignedSelfDecryptionPermit } from '../types/signedDecryptionPermit.js';
+import type { SignedDecryptionPermit, SignedDecryptionPermitV1 } from '../types/signedDecryptionPermit.js';
 import type { Handle } from '../types/encryptedTypes-p.js';
 import { assertHandlesBelongToSameChainId } from '../handle/FhevmHandle.js';
-import { createKmsSigncryptedShares } from '../kms/KmsSigncryptedShares-p.js';
+import { createKmsSigncryptedShares } from './KmsSigncryptedShares-p.js';
 import { readKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
-import { assertIsSignedDecryptionPermit, assertPermitIncludesContractAddresses } from './SignedDecryptionPermit-p.js';
+import { assertIsSignedDecryptionPermit } from './SignedDecryptionPermit-p.js';
 import { assertKmsDecryptionBitLimit } from './utils.js';
 import { checkPersistAllowed } from '../host-contracts/checkPersistAllowed.js';
 import { assertExtraDataMatchesKmsSingersContext } from '../host-contracts/KmsSignersContext-p.js';
@@ -40,23 +40,14 @@ type Context = {
   readonly options: { readonly batchRpcCalls: boolean };
 };
 
-type Parameters =
-  | {
-      readonly pairs: ReadonlyArray<{
-        readonly handle: Handle;
-        readonly contractAddress: ChecksummedAddress;
-      }>;
-      readonly signedPermit: SignedSelfDecryptionPermit;
-      readonly options?: RelayerUserDecryptOptions | undefined;
-    }
-  | {
-      readonly pairs: ReadonlyArray<{
-        readonly handle: Handle;
-        readonly contractAddress: ChecksummedAddress;
-      }>;
-      readonly signedPermit: SignedDelegatedDecryptionPermit;
-      readonly options?: RelayerDelegatedUserDecryptOptions | undefined;
-    };
+type Parameters = {
+  readonly pairs: ReadonlyArray<{
+    readonly handle: Handle;
+    readonly contractAddress: ChecksummedAddress;
+  }>;
+  readonly signedPermit: SignedDecryptionPermit;
+  readonly options?: RelayerUserDecryptOptions | RelayerDelegatedUserDecryptOptions | undefined;
+};
 
 type ReturnType = KmsSigncryptedShares;
 
@@ -64,19 +55,36 @@ type ReturnType = KmsSigncryptedShares;
 
 const MAX_USER_DECRYPT_CONTRACT_ADDRESSES = 10;
 
+/**
+ * Asserts that every address in {@link contractAddresses} is listed in the
+ * permit's `contractAddresses` (case-insensitive comparison).
+ */
+export function assertPermitV1IncludesContractAddresses(
+  permit: SignedDecryptionPermitV1,
+  contractAddresses: readonly string[],
+): void {
+  const permitAddresses = permit.eip712.message.contractAddresses;
+  for (const address of contractAddresses) {
+    if (!permitAddresses.some((a) => a.toLowerCase() === address.toLowerCase())) {
+      throw Error(`contract address ${address} is not listed in the permit's contractAddresses`);
+    }
+  }
+}
+
 ////////////////////////////////////////////////////////////////////////////////
-// fetchKmsSigncryptedShares
+// fetchKmsSigncryptedSharesV1
 ////////////////////////////////////////////////////////////////////////////////
 
-export async function fetchKmsSigncryptedShares(context: Context, parameters: Parameters): Promise<ReturnType> {
-  const { signedPermit, options, pairs } = parameters;
+export async function fetchKmsSigncryptedSharesV1(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const { options, pairs } = parameters;
+  const signedPermit = parameters.signedPermit as SignedDecryptionPermitV1;
 
   // This helper must support base clients, where TKMS is not mandatory
   // and tkmsVersion may not be initialized in the CoreFhevm instance yet.
   const tkmsVersion = await resolveFhevmTkmsVersion(context);
 
   // Check: every requested contractAddress is listed in the permit
-  assertPermitIncludesContractAddresses(
+  assertPermitV1IncludesContractAddresses(
     signedPermit,
     pairs.map((p) => p.contractAddress),
   );
@@ -124,7 +132,7 @@ export async function fetchKmsSigncryptedShares(context: Context, parameters: Pa
   signedPermit.assertNotExpired();
 
   // 7. Check: ACL permissions (user is signer or delegatorAddress)
-  if (signedPermit.isDelegated) {
+  if (signedPermit.eip712.primaryType === 'DelegatedUserDecryptRequestVerification') {
     await checkDelegation(context, {
       aclAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
       delegate: signerAddress,
@@ -139,7 +147,7 @@ export async function fetchKmsSigncryptedShares(context: Context, parameters: Pa
     });
   }
 
-  // 8. Verify the EIP712 signature
+  // 8. Verify the Eip712 signature
   // Not required because a signedPermit is guaranteed to be verified.
 
   // 9. Fetch `KmsSignersContext` on-chain (cached)
@@ -170,12 +178,9 @@ export async function fetchKmsSigncryptedShares(context: Context, parameters: Pa
   );
 
   // 10. Fetch `KmsSigncryptedShares` from the relayer
-  // Safe casts: the discriminated union on parameters guarantees
-  // that options type matches signedPermit type, but TS can't prove
-  // it after destructuring (nested discriminant limitation).
   let shares: readonly KmsSigncryptedShare[];
 
-  if (signedPermit.isDelegated) {
+  if (signedPermit.eip712.primaryType === 'DelegatedUserDecryptRequestVerification') {
     shares = await context.runtime.relayer.fetchDelegatedUserDecrypt(context, {
       payload: {
         handleContractPairs,

package/core/kms/fetchKmsSigncryptedSharesV2-p.ts

@@ -0,0 +1,176 @@
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { KmsSigncryptedShare, KmsSigncryptedSharesMetadata } from '../types/kms-p.js';
+import type { KmsSigncryptedShares } from '../types/kms.js';
+import type { KmsSignersContext } from '../types/kmsSignersContext.js';
+import type { ChecksummedAddress, Uint64BigInt } from '../types/primitives.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import type { RelayerUserDecryptOptions } from '../types/relayer.js';
+import type { SignedDecryptionPermit, SignedDecryptionPermitV2 } from '../types/signedDecryptionPermit.js';
+import type { Handle } from '../types/encryptedTypes-p.js';
+import { assertHandlesBelongToSameChainId } from '../handle/FhevmHandle.js';
+import { createKmsSigncryptedShares } from './KmsSigncryptedShares-p.js';
+import { readKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
+import { assertIsSignedDecryptionPermit } from './SignedDecryptionPermit-p.js';
+import { assertKmsDecryptionBitLimit } from './utils.js';
+import { checkPersistAllowed } from '../host-contracts/checkPersistAllowed.js';
+import { checkDelegation } from '../host-contracts/checkDelegation.js';
+import { assertExtraDataMatchesKmsSingersContext } from '../host-contracts/KmsSignersContext-p.js';
+import { createKmsEip712Domain } from './createKmsEip712Domain.js';
+import { resolveFhevmTkmsVersion } from '../runtime/resolveFhevmVersions-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly chain: FhevmChain;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+type Parameters = {
+  readonly pairs: ReadonlyArray<{
+    readonly handle: Handle;
+    readonly contractAddress: ChecksummedAddress;
+    // When omitted, defaults to userAddress (direct-access path).
+    // Provide explicitly only for delegated handles where ownerAddress !== userAddress.
+    readonly ownerAddress?: ChecksummedAddress | undefined;
+  }>;
+  readonly signedPermit: SignedDecryptionPermit;
+  readonly options?: RelayerUserDecryptOptions | undefined;
+};
+
+type ReturnType = KmsSigncryptedShares;
+
+////////////////////////////////////////////////////////////////////////////////
+// fetchKmsSigncryptedSharesV2
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchKmsSigncryptedSharesV2(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const { options, pairs } = parameters;
+  const signedPermit = parameters.signedPermit as SignedDecryptionPermitV2;
+
+  const tkmsVersion = await resolveFhevmTkmsVersion(context);
+
+  const relayerOptions = {
+    auth: context.runtime.config.auth,
+    ...options,
+  };
+
+  assertIsSignedDecryptionPermit(signedPermit, {});
+
+  const { signerAddress, signature } = signedPermit;
+  const userAddress = signedPermit.eip712.message.userAddress;
+
+  // 1. Check: At least one handle/contract pair is required
+  if (pairs.length === 0) {
+    throw Error(
+      `encrypted value/contract pairs must not be empty, at least one encrypted value/contract pair is required`,
+    );
+  }
+
+  // Resolve ownerAddress for each pair: defaults to userAddress (direct-access path)
+  // when not explicitly provided by the caller.
+  const resolvedPairs = pairs.map((p) => ({
+    handle: p.handle,
+    contractAddress: p.contractAddress,
+    ownerAddress: p.ownerAddress ?? userAddress,
+  }));
+
+  const handles = resolvedPairs.map((p) => p.handle);
+  Object.freeze(handles);
+
+  // 2. Check: All handles belong to the host chainId
+  assertHandlesBelongToSameChainId(handles, BigInt(context.chain.id) as Uint64BigInt);
+
+  // 3. Check: 2048 bits limit
+  assertKmsDecryptionBitLimit(handles);
+
+  // 4. Check: Expiration date
+  signedPermit.assertNotExpired();
+
+  // 5. Check: ACL permissions — split pairs by direct vs delegated access
+  const directPairs = resolvedPairs.filter((p) => p.ownerAddress.toLowerCase() === userAddress.toLowerCase());
+  const delegatedPairs = resolvedPairs.filter((p) => p.ownerAddress.toLowerCase() !== userAddress.toLowerCase());
+
+  if (directPairs.length > 0) {
+    await checkPersistAllowed(context, {
+      aclAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
+      userAddress,
+      handleContractPairs: directPairs,
+    });
+  }
+
+  if (delegatedPairs.length > 0) {
+    // Group delegated pairs by delegator (ownerAddress): a single batch may contain
+    // handles from multiple delegators, each requiring a separate ACL delegation check.
+    const byDelegator = new Map<ChecksummedAddress, Array<(typeof delegatedPairs)[number]>>();
+    for (const pair of delegatedPairs) {
+      const group = byDelegator.get(pair.ownerAddress) ?? [];
+      group.push(pair);
+      byDelegator.set(pair.ownerAddress, group);
+    }
+    for (const [delegator, groupedPairs] of byDelegator) {
+      await checkDelegation(context, {
+        aclAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
+        delegate: userAddress,
+        delegator,
+        handleContractPairs: groupedPairs,
+      });
+    }
+  }
+
+  // 6. Verify the Eip712 signature
+  // Not required because a signedPermit is guaranteed to be verified.
+
+  // 7. Fetch `KmsSignersContext` on-chain (cached)
+  // Reject the permit early if it was signed against a different KMS context.
+  //
+  // TODO: The current check is a strict byte-level comparison. A permit signed
+  // with the correct `kmsContextId` but a different `extraData` encoding format
+  // (e.g. a version change in the serialization scheme) will be rejected even
+  // though the context ID matches. Consider comparing the decoded `kmsContextId`
+  // instead of the raw `extraData` bytes.
+  const requestedKmsSignersContext: KmsSignersContext = await readKmsSignersContext(context, {
+    kmsVerifierAddress: context.chain.fhevm.contracts.kmsVerifier.address as ChecksummedAddress,
+    protocolConfigAddress: context.chain.fhevm.contracts.protocolConfig?.address as ChecksummedAddress | undefined,
+  });
+
+  assertExtraDataMatchesKmsSingersContext(
+    {
+      extraData: signedPermit.eip712.message.extraData,
+      kmsSignersContext: requestedKmsSignersContext,
+    },
+    { subject: 'Invalid permit' },
+  );
+
+  // 8. Fetch `KmsSigncryptedShares` from the relayer (unified V2 route)
+  const shares: readonly KmsSigncryptedShare[] = await context.runtime.relayer.fetchUserDecrypt(context, {
+    payload: {
+      handleContractPairs: resolvedPairs,
+      kmsDecryptEip712Message: signedPermit.eip712.message,
+      kmsDecryptEip712Signature: signature,
+    },
+    options: relayerOptions,
+  });
+
+  // 9. Build and verify the sealed validated `KmsSigncryptedShares` object
+  const sharesMetadata: KmsSigncryptedSharesMetadata = {
+    kmsSignersContext: requestedKmsSignersContext,
+    eip712Domain: createKmsEip712Domain({
+      chainId: context.chain.fhevm.gateway.id,
+      verifyingContractAddressDecryption: context.chain.fhevm.gateway.contracts.decryption.address,
+    }),
+    eip712Signature: signature,
+    eip712SignerAddress: signerAddress,
+    handles,
+    tkmsVersion,
+  };
+
+  // 10. The returned KmsSigncryptedShares is guaranteed to be fully verified:
+  // uniform extraData across shares, valid extraData format, and consistency
+  // with the KmsSignersContext (see KmsSigncryptedSharesImpl invariants).
+  return await createKmsSigncryptedShares(context, {
+    metadata: sharesMetadata,
+    shares,
+  });
+}