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

package/core/base/object.ts

@@ -16,6 +16,44 @@ export function simpleDeepFreeze<T extends object>(obj: T): Readonly<T> {
   return obj;
 }
 
+/**
+ * Recursively compares two JSON-like values.
+ *
+ * Arrays are order-sensitive. Objects must have the same own enumerable string keys, but key
+ * insertion order does not matter.
+ */
+export function isDeepEqual(value: unknown, expected: unknown): boolean {
+  if (value === expected) {
+    return true;
+  }
+
+  if (Array.isArray(expected)) {
+    return (
+      Array.isArray(value) &&
+      value.length === expected.length &&
+      expected.every((expectedItem, index) => isDeepEqual(value[index], expectedItem))
+    );
+  }
+
+  if (expected === null || typeof expected !== 'object') {
+    return value === expected;
+  }
+
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const record = value as Record<string, unknown>;
+  const expectedRecord = expected as Record<string, unknown>;
+  const keys = Object.keys(record);
+  const expectedKeys = Object.keys(expectedRecord);
+
+  return (
+    keys.length === expectedKeys.length &&
+    expectedKeys.every((key) => Object.hasOwn(record, key) && isDeepEqual(record[key], expectedRecord[key]))
+  );
+}
+
 /**
  * Defines a non-enumerable, non-writable, non-configurable property on the target object.
  * The property is hidden from `Object.keys()` / `Object.entries()` and cannot be

package/core/base/semver.ts

@@ -0,0 +1,231 @@
+import type { UintNumber } from '../types/primitives.js';
+import { assertIsUintNumber } from './uint.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type Semver = {
+  readonly version: string;
+  readonly major: UintNumber;
+  readonly minor: UintNumber;
+  readonly patch: UintNumber;
+  readonly prerelease?: readonly string[] | undefined;
+  readonly build?: readonly string[] | undefined;
+};
+
+export type SemverComparator = 'lt' | 'le' | 'gt' | 'ge' | 'eq';
+
+export type SemverRange = {
+  readonly version: string;
+  readonly comparator: SemverComparator;
+};
+
+export type SemverIntervalLowerBound = {
+  readonly version: string;
+  readonly comparator: 'gt' | 'ge';
+};
+
+export type SemverIntervalUpperBound = {
+  readonly version: string;
+  readonly comparator: 'lt' | 'le';
+};
+
+export type SemverInterval = {
+  readonly lowerBound?: SemverIntervalLowerBound | undefined;
+  readonly upperBound?: SemverIntervalUpperBound | undefined;
+};
+
+const SEMVER_REGEX =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+export function parseSemver(version: string): Semver {
+  const match = SEMVER_REGEX.exec(version);
+  if (match === null) {
+    throw new Error(`Invalid SemVer version: "${version}".`);
+  }
+
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+
+  assertIsUintNumber(major, {});
+  assertIsUintNumber(minor, {});
+  assertIsUintNumber(patch, {});
+
+  return Object.freeze({
+    version,
+    major,
+    minor,
+    patch,
+    prerelease: match[4]?.split('.'),
+    build: match[5]?.split('.'),
+  });
+}
+
+export function isSemverStrictlyBefore(version: string, before: string): boolean {
+  return compareSemver(version, before) < 0;
+}
+
+export function isSemverInRange(version: string, range: SemverRange): boolean {
+  const comparison = compareSemver(version, range.version);
+
+  switch (range.comparator) {
+    case 'lt':
+      return comparison < 0;
+    case 'le':
+      return comparison <= 0;
+    case 'gt':
+      return comparison > 0;
+    case 'ge':
+      return comparison >= 0;
+    case 'eq':
+      return comparison === 0;
+    default: {
+      const exhaustiveCheck: never = range.comparator;
+      throw new Error(`Unsupported SemVer comparator "${exhaustiveCheck}".`);
+    }
+  }
+}
+
+export function isSemverInInterval(version: string, interval: SemverInterval): boolean {
+  if (interval.lowerBound !== undefined && !isSemverInRange(version, interval.lowerBound)) {
+    return false;
+  }
+  if (interval.upperBound !== undefined && !isSemverInRange(version, interval.upperBound)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Returns whether a SemVer comparator constraint implies a SemVer range.
+ *
+ * Mathematically: for every SemVer `x`, if `x comparator version` is true,
+ * then `x range.comparator range.version` is also true.
+ */
+export function semverComparatorImpliesRange(
+  version: string,
+  comparator: SemverComparator,
+  range: SemverRange,
+): boolean {
+  if (comparator === 'eq') {
+    return isSemverInRange(version, range);
+  }
+
+  const comparison = compareSemver(version, range.version);
+
+  switch (comparator) {
+    case 'lt':
+      return range.comparator === 'lt' || range.comparator === 'le' ? comparison <= 0 : false;
+    case 'le':
+      if (range.comparator === 'lt') {
+        return comparison < 0;
+      }
+      return range.comparator === 'le' ? comparison <= 0 : false;
+    case 'gt':
+      return range.comparator === 'gt' || range.comparator === 'ge' ? comparison >= 0 : false;
+    case 'ge':
+      if (range.comparator === 'gt') {
+        return comparison > 0;
+      }
+      return range.comparator === 'ge' ? comparison >= 0 : false;
+    default: {
+      const exhaustiveCheck: never = comparator;
+      throw new Error(`Unsupported SemVer comparator "${exhaustiveCheck}".`);
+    }
+  }
+}
+
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+
+  const releaseComparison = _compareNumbers(
+    [left.major, left.minor, left.patch],
+    [right.major, right.minor, right.patch],
+  );
+  if (releaseComparison !== 0) {
+    return releaseComparison;
+  }
+
+  return _comparePrerelease(left.prerelease, right.prerelease);
+}
+
+function _compareNumbers(a: readonly number[], b: readonly number[]): -1 | 0 | 1 {
+  for (let i = 0; i < a.length; ++i) {
+    const left = a[i];
+    const right = b[i];
+    if (left === undefined) {
+      return right === undefined ? 0 : -1;
+    }
+    if (right === undefined) {
+      return 1;
+    }
+    if (left < right) {
+      return -1;
+    }
+    if (left > right) {
+      return 1;
+    }
+  }
+  return a.length === b.length ? 0 : -1;
+}
+
+function _comparePrerelease(a: readonly string[] | undefined, b: readonly string[] | undefined): -1 | 0 | 1 {
+  if (a === undefined && b === undefined) {
+    return 0;
+  }
+  if (a === undefined) {
+    return 1;
+  }
+  if (b === undefined) {
+    return -1;
+  }
+
+  const length = Math.max(a.length, b.length);
+  for (let i = 0; i < length; ++i) {
+    const left = a[i];
+    const right = b[i];
+
+    if (left === undefined) {
+      return -1;
+    }
+    if (right === undefined) {
+      return 1;
+    }
+
+    const comparison = _comparePrereleaseIdentifier(left, right);
+    if (comparison !== 0) {
+      return comparison;
+    }
+  }
+
+  return 0;
+}
+
+function _comparePrereleaseIdentifier(a: string, b: string): -1 | 0 | 1 {
+  const aIsNumeric = _isNumericIdentifier(a);
+  const bIsNumeric = _isNumericIdentifier(b);
+
+  if (aIsNumeric && bIsNumeric) {
+    return _compareNumbers([Number(a)], [Number(b)]);
+  }
+
+  if (aIsNumeric) {
+    return -1;
+  }
+  if (bIsNumeric) {
+    return 1;
+  }
+
+  if (a < b) {
+    return -1;
+  }
+  if (a > b) {
+    return 1;
+  }
+  return 0;
+}
+
+function _isNumericIdentifier(value: string): boolean {
+  return /^(0|[1-9]\d*)$/.test(value);
+}

package/core/base/string.ts

@@ -15,6 +15,16 @@ export function removeSuffix(s: string | undefined, suffix: string): string {
   return s.endsWith(suffix) ? s.slice(0, -suffix.length) : s;
 }
 
+export function removePrefix(s: string | undefined, prefix: string): string {
+  if (s === undefined) {
+    return '';
+  }
+  if (prefix.length === 0) {
+    return s;
+  }
+  return s.startsWith(prefix) ? s.substring(prefix.length) : s;
+}
+
 export function is0x(s: unknown): s is `0x${string}` {
   return typeof s === 'string' && s.startsWith('0x');
 }

package/core/base/uint.ts

@@ -116,6 +116,13 @@ export function isUintBigInt(value: unknown, max?: bigint | number): value is Ui
   return typeof value === 'bigint' && value >= 0 && (max === undefined || value <= max);
 }
 
+export function isUintString(value: unknown, max?: number | bigint): value is string {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  return tryParseUintBigIntString(value, max) !== undefined;
+}
+
 export function isUintForType(value: unknown, typeName?: UintTypeName): value is Uint {
   return isUint(value, typeName !== undefined ? MAX_UINT_FOR_TYPE[typeName] : undefined);
 }
@@ -330,6 +337,22 @@ export function assertIsUintBigInt(
   }
 }
 
+export function assertIsUintString(
+  value: unknown,
+  options: { max?: bigint | number; subject?: string } & ErrorMetadataParams,
+): asserts value is string {
+  if (!isUintString(value, options.max)) {
+    throw new InvalidTypeError(
+      {
+        subject: options.subject,
+        type: typeof value,
+        expectedType: 'uintString',
+      },
+      options,
+    );
+  }
+}
+
 export function assertIsUint8(
   value: unknown,
   options: { subject?: string } & ErrorMetadataParams,
@@ -645,7 +668,7 @@ export function assertRecordUintBigIntProperty<K extends string>(
   property: K,
   recordName: string,
   options: ErrorMetadataParams,
-): asserts record is RecordWithPropertyType<K, number> {
+): asserts record is RecordWithPropertyType<K, bigint> {
   if (typeofProperty(record, property) !== 'bigint' || !isUintBigInt((record as Record<string, unknown>)[property])) {
     throw new InvalidPropertyError(
       {
@@ -659,17 +682,23 @@ export function assertRecordUintBigIntProperty<K extends string>(
   }
 }
 
-export function parseUintBigIntString(value: string): bigint | undefined {
+/**
+ * Tries to parse a canonical unsigned decimal string as a bigint.
+ *
+ * Returns `undefined` instead of throwing when `value` is not parseable, is negative, is not in
+ * canonical decimal form, or exceeds `max`.
+ */
+export function tryParseUintBigIntString(value: string, max?: number | bigint): UintBigInt | undefined {
   let parsed: bigint;
   try {
     parsed = BigInt(value);
   } catch {
     return undefined;
   }
-  if (parsed < 0n || parsed.toString() !== value) {
+  if (parsed < 0n || parsed.toString() !== value || (max !== undefined && parsed > BigInt(max))) {
     return undefined;
   }
-  return parsed;
+  return parsed as UintBigInt;
 }
 
 /** Returns `count` unique integers drawn uniformly from [0, n-1]. Mock/debug only. */

package/core/chains/definitions/localTestnet.ts

@@ -13,6 +13,9 @@ export const localTestnet = /*#__PURE__*/ defineFhevmChain({
       kmsVerifier: {
         address: '0xa1880e99d86F081E8D3868A8C4732C8f65dfdB11',
       },
+      protocolConfig: {
+        address: '0x52054F36036811ca418be59e41Fc6DD1b9e4F4c8',
+      },
     },
     relayerUrl: 'http://localhost:9000',
     gateway: {

package/core/chains/definitions/mainnet.ts

@@ -13,6 +13,7 @@ export const mainnet = /*#__PURE__*/ defineFhevmChain({
       kmsVerifier: {
         address: '0x77627828a55156b04Ac0DC0eb30467f1a552BB03',
       },
+      protocolConfig: undefined, // To be filled
     },
     relayerUrl: 'https://relayer.mainnet.zama.org',
     gateway: {

package/core/chains/definitions/sepolia.ts

@@ -1,5 +1,4 @@
 import type { FhevmChain } from '../../types/fhevmChain.js';
-import type { ChecksummedAddress } from '../../types/primitives.js';
 import { defineFhevmChain } from '../utils.js';
 
 export const sepolia: FhevmChain = /*#__PURE__*/ defineFhevmChain({
@@ -7,24 +6,25 @@ export const sepolia: FhevmChain = /*#__PURE__*/ defineFhevmChain({
   fhevm: {
     contracts: {
       acl: {
-        address: '0xf0Ffdc93b7E186bC2f8CB3dAA75D86d1930A433D' as ChecksummedAddress,
+        address: '0xf0Ffdc93b7E186bC2f8CB3dAA75D86d1930A433D',
       },
       inputVerifier: {
-        address: '0xBBC1fFCdc7C316aAAd72E807D9b0272BE8F84DA0' as ChecksummedAddress,
+        address: '0xBBC1fFCdc7C316aAAd72E807D9b0272BE8F84DA0',
       },
       kmsVerifier: {
-        address: '0xbE0E383937d564D7FF0BC3b46c51f0bF8d5C311A' as ChecksummedAddress,
+        address: '0xbE0E383937d564D7FF0BC3b46c51f0bF8d5C311A',
       },
+      protocolConfig: undefined, // To be filled
     },
     relayerUrl: 'https://relayer.testnet.zama.org',
     gateway: {
       id: 10_901,
       contracts: {
         decryption: {
-          address: '0x5D8BD78e2ea6bbE41f26dFe9fdaEAa349e077478' as ChecksummedAddress,
+          address: '0x5D8BD78e2ea6bbE41f26dFe9fdaEAa349e077478',
         },
         inputVerification: {
-          address: '0x483b9dE06E4E4C7D35CCf5837A1668487406D955' as ChecksummedAddress,
+          address: '0x483b9dE06E4E4C7D35CCf5837A1668487406D955',
         },
       },
     },

package/core/clients/decorators/base.ts

@@ -50,6 +50,7 @@ import {
   type DecryptPublicValuesWithSignaturesParameters,
   type DecryptPublicValuesWithSignaturesReturnType,
 } from '../../actions/base/decryptPublicValuesWithSignatures.js';
+import { ensureResolvedProtocolVersion } from '../../runtime/resolveFhevmVersions-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -193,11 +194,17 @@ function _baseActions(fhevm: Fhevm<FhevmChain>): BaseActions {
 
 ////////////////////////////////////////////////////////////////////////////////
 
+async function _initBase(fhevm: FhevmBase<FhevmChain>): Promise<void> {
+  await ensureResolvedProtocolVersion(fhevm);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
 export function baseActions(fhevm: FhevmBase<FhevmChain>): FhevmExtension<BaseActions> {
   assertIsFhevmBaseClient(fhevm);
   return {
     actions: _baseActions(fhevm),
     runtime: fhevm.runtime,
-    // no init required, no prefetch of the FheEncryptionKey. This is the whole purpose of the fetchFheEncryptionKeyBytes action
+    init: _initBase,
   };
 }

package/core/clients/decorators/decrypt-p.ts

@@ -0,0 +1,18 @@
+import type { FhevmBase } from '../../types/coreFhevmClient.js';
+import type { FhevmChain } from '../../types/fhevmChain.js';
+import { asFhevmClientWith, setResolvedTkmsVersion } from '../../runtime/CoreFhevm-p.js';
+import { ensureResolvedProtocolVersion, resolveFhevmTkmsVersion } from '../../runtime/resolveFhevmVersions-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export async function _initDecrypt(fhevm: FhevmBase<FhevmChain>): Promise<void> {
+  const f = asFhevmClientWith(fhevm, 'decrypt');
+
+  await ensureResolvedProtocolVersion(f);
+
+  const tkmsVersion = await resolveFhevmTkmsVersion(f);
+
+  await f.runtime.decrypt.initTkmsModule({ tkmsVersion });
+
+  setResolvedTkmsVersion(f, tkmsVersion);
+}

package/core/clients/decorators/decrypt.ts

@@ -1,10 +1,10 @@
-import type { Fhevm, FhevmBase, FhevmExtension, OptionalNativeClient } from '../../types/coreFhevmClient.js';
-import type { FhevmRuntime, WithDecrypt } from '../../types/coreFhevmRuntime.js';
+import type { Fhevm, FhevmBase, FhevmExtension, WithTkmsVersion } from '../../types/coreFhevmClient.js';
+import type { WithDecrypt } from '../../types/coreFhevmRuntime.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
 import type { GenerateTransportKeyPairReturnType } from '../../actions/decrypt/generateTransportKeyPair.js';
 import type { DecryptModuleFactory } from '../../modules/decrypt/types.js';
-import { asFhevmClientWith, assertIsFhevmClientWith } from '../../runtime/CoreFhevm-p.js';
-import { generateTransportKeyPair } from '../../kms/TransportKeyPair-p.js';
+import { assertIsFhevmClientWith } from '../../runtime/CoreFhevm-p.js';
+import { generateTransportKeyPair } from '../../actions/decrypt/generateTransportKeyPair.js';
 import {
   decryptValue,
   type DecryptValueParameters,
@@ -20,22 +20,24 @@ import {
   type DecryptValuesFromPairsParameters,
   type DecryptValuesFromPairsReturnType,
 } from '../../actions/decrypt/decryptValuesFromPairs.js';
+import { _initDecrypt } from './decrypt-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export type DecryptActions = {
+type DecryptActionMethods = {
   readonly decryptValue: (parameters: DecryptValueParameters) => Promise<DecryptValueReturnType>;
   readonly decryptValues: (parameters: DecryptValuesParameters) => Promise<DecryptValuesReturnType>;
-
   readonly decryptValuesFromPairs: (
     parameters: DecryptValuesFromPairsParameters,
   ) => Promise<DecryptValuesFromPairsReturnType>;
   readonly generateTransportKeyPair: () => Promise<GenerateTransportKeyPairReturnType>;
 };
 
+export type DecryptActions = DecryptActionMethods & WithTkmsVersion;
+
 ////////////////////////////////////////////////////////////////////////////////
 
-function _decryptActions(fhevm: Fhevm<FhevmChain, WithDecrypt>): DecryptActions {
+function _decryptActions(fhevm: Fhevm<FhevmChain, WithDecrypt>): DecryptActionMethods {
   // Preserve the original action overloads on the decorated client API.
   // Runtime behavior is unchanged: this is a direct pass-through wrapper.
   return {
@@ -48,13 +50,6 @@ function _decryptActions(fhevm: Fhevm<FhevmChain, WithDecrypt>): DecryptActions
 
 ////////////////////////////////////////////////////////////////////////////////
 
-function _initDecrypt(fhevm: FhevmBase<FhevmChain | undefined, FhevmRuntime, OptionalNativeClient>): Promise<void> {
-  const f = asFhevmClientWith(fhevm, 'decrypt');
-  return f.runtime.decrypt.initTkmsModule();
-}
-
-////////////////////////////////////////////////////////////////////////////////
-
 export function decryptActionsWithModule(
   fhevm: FhevmBase<FhevmChain>,
   factory: DecryptModuleFactory,
@@ -62,7 +57,7 @@ export function decryptActionsWithModule(
   const runtime = fhevm.runtime.extend(factory);
   assertIsFhevmClientWith(fhevm, 'decrypt');
   return {
-    actions: _decryptActions(fhevm),
+    actions: _decryptActions(fhevm) as DecryptActions,
     runtime,
     init: _initDecrypt,
   };

package/core/clients/decorators/encrypt-p.ts

@@ -1,18 +1,23 @@
-import type { FhevmBase, OptionalNativeClient } from '../../types/coreFhevmClient.js';
-import type { FhevmRuntime } from '../../types/coreFhevmRuntime.js';
+import type { FhevmBase } from '../../types/coreFhevmClient.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
-import { asFhevmClientWith } from '../../runtime/CoreFhevm-p.js';
+import { asFhevmClientWith, setResolvedTfheVersion } from '../../runtime/CoreFhevm-p.js';
 import { fetchFheEncryptionKeyBytes } from '../../key/fetchFheEncryptionKeyBytes.js';
+import { ensureResolvedProtocolVersion, resolveFhevmTfheVersion } from '../../runtime/resolveFhevmVersions-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export async function _initEncrypt(
-  fhevm: FhevmBase<FhevmChain | undefined, FhevmRuntime, OptionalNativeClient>,
-): Promise<void> {
+export async function _initEncrypt(fhevm: FhevmBase<FhevmChain>): Promise<void> {
   const f = asFhevmClientWith(fhevm, 'encrypt');
+
+  await ensureResolvedProtocolVersion(fhevm);
+
+  const tfheVersion = await resolveFhevmTfheVersion(f);
+
   await Promise.all([
     // Prefetch the global FheEncryptionKey in bytes format
     fetchFheEncryptionKeyBytes(f, {}),
-    f.runtime.encrypt.initTfheModule(),
+    f.runtime.encrypt.initTfheModule({ tfheVersion }),
   ]);
+
+  setResolvedTfheVersion(f, tfheVersion);
 }

package/core/clients/decorators/encrypt.ts

@@ -1,4 +1,4 @@
-import type { Fhevm, FhevmBase, FhevmExtension } from '../../types/coreFhevmClient.js';
+import type { Fhevm, FhevmBase, FhevmExtension, WithTfheVersion } from '../../types/coreFhevmClient.js';
 import type { WithEncrypt } from '../../types/coreFhevmRuntime.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
 import type { EncryptModuleFactory } from '../../modules/encrypt/types.js';
@@ -17,14 +17,16 @@ import { _initEncrypt } from './encrypt-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export type EncryptActions = {
+type EncryptActionMethods = {
   readonly encryptValue: (parameters: EncryptValueParameters) => Promise<EncryptValueReturnType>;
   readonly encryptValues: (parameters: EncryptValuesParameters) => Promise<EncryptValuesReturnType>;
 };
 
+export type EncryptActions = EncryptActionMethods & WithTfheVersion;
+
 ////////////////////////////////////////////////////////////////////////////////
 
-function _encryptActions(fhevm: Fhevm<FhevmChain, WithEncrypt>): EncryptActions {
+function _encryptActions(fhevm: Fhevm<FhevmChain, WithEncrypt>): EncryptActionMethods {
   return {
     encryptValue: (parameters) => encryptValue(fhevm, parameters),
     encryptValues: (parameters) => encryptValues(fhevm, parameters),
@@ -40,7 +42,7 @@ export function encryptActionsWithModule(
   const runtime = fhevm.runtime.extend(factory);
   assertIsFhevmClientWith(fhevm, 'encrypt');
   return {
-    actions: _encryptActions(fhevm),
+    actions: _encryptActions(fhevm) as EncryptActions,
     runtime,
     init: _initEncrypt,
   };

package/core/coprocessor/ZkProof-p.ts

@@ -13,6 +13,7 @@ import type { ErrorMetadataParams } from '../base/errors/ErrorBase.js';
 import type { EncryptionBits, FheTypeId } from '../types/fheType.js';
 import type { ParseTFHEProvenCompactCiphertextListModuleFunction } from '../modules/encrypt/types.js';
 import type { InputHandle } from '../types/encryptedTypes-p.js';
+import type { TfheVersion } from '../../wasm/tfhe/TfheApi.js';
 import {
   addressToChecksummedAddress,
   assertIsAddress,
@@ -230,7 +231,10 @@ export async function toZkProof(
   zkProofLike: ZkProofLike,
   extraData: BytesHex,
   options?: {
-    readonly zkProofParser?: ParseTFHEProvenCompactCiphertextListModuleFunction;
+    readonly zkProofParser?: {
+      readonly parserFn: ParseTFHEProvenCompactCiphertextListModuleFunction;
+      readonly tfheVersion: TfheVersion;
+    };
     readonly copy?: boolean;
   },
 ): Promise<ZkProof> {
@@ -290,7 +294,10 @@ export async function zkProofToExternalEncryptedValues(
   zkProofLike: ZkProofLike,
   options?: {
     readonly version?: number;
-    readonly zkProofParser?: ParseTFHEProvenCompactCiphertextListModuleFunction;
+    readonly zkProofParser?: {
+      readonly parserFn: ParseTFHEProvenCompactCiphertextListModuleFunction;
+      readonly tfheVersion: TfheVersion;
+    };
   },
 ): Promise<readonly InputHandle[]> {
   if (zkProofLike instanceof ZkProofImpl) {
@@ -397,7 +404,10 @@ function _zkProofToInputHandles(
 async function _getOrParseEncryptionBits(
   encryptionBits: readonly number[] | undefined,
   ciphertextWithZkProof: Uint8Array | string,
-  zkProofParser?: ParseTFHEProvenCompactCiphertextListModuleFunction,
+  zkProofParser?: {
+    readonly parserFn: ParseTFHEProvenCompactCiphertextListModuleFunction;
+    readonly tfheVersion: TfheVersion;
+  },
 ): Promise<readonly EncryptionBits[]> {
   // Case 1: encryptionBits provided — validate, and verify against parsed if possible
   if (encryptionBits != null) {
@@ -406,8 +416,9 @@ async function _getOrParseEncryptionBits(
     });
 
     if (zkProofParser != null) {
-      const parsed = await zkProofParser.parseTFHEProvenCompactCiphertextList({
+      const parsed = await zkProofParser.parserFn.parseTFHEProvenCompactCiphertextList({
         ciphertextWithZkProof: ciphertextWithZkProof,
+        tfheVersion: zkProofParser.tfheVersion,
       });
       _assertEncryptionBitsMatch(parsed.encryptionBits, encryptionBits);
     }
@@ -417,8 +428,9 @@ async function _getOrParseEncryptionBits(
 
   // Case 2: encryptionBits not provided — extract if parse function available
   if (zkProofParser != null) {
-    const parsed = await zkProofParser.parseTFHEProvenCompactCiphertextList({
+    const parsed = await zkProofParser.parserFn.parseTFHEProvenCompactCiphertextList({
       ciphertextWithZkProof: ciphertextWithZkProof,
+      tfheVersion: zkProofParser.tfheVersion,
     });
     return parsed.encryptionBits;
   }