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

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

@@ -7,9 +7,12 @@ import type { FetchKeyUrlResult } from '../../../types/relayer-p.js';
 import { setAuth } from '../../../base/auth.js';
 import { RelayerFetchError } from '../../../errors/RelayerFetchError.js';
 import { assertRecordArrayProperty, assertRecordNonNullableProperty } from '../../../base/record.js';
-import { fetchWithRetry } from '../../../base/fetch.js';
+import { fetchWithRetry, normalizeHeaders } from '../../../base/fetch.js';
 import { sdkName, version } from '../../../_version.js';
-import { assertRecordStringArrayProperty, assertRecordStringProperty, removeSuffix } from '../../../base/string.js';
+import { assertRecordStringArrayProperty, assertRecordStringProperty } from '../../../base/string.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
+import { readErrorMessage } from './readErrorMessage.js';
+import { assert } from '../../../base/errors/InternalError.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 // fetchFheEncryptionKeySource
@@ -20,19 +23,22 @@ export async function fetchFheEncryptionKeySource(
   parameters: FetchFheEncryptionKeySourceParameters,
 ): Promise<FetchFheEncryptionKeySourceReturnType> {
   const { options } = parameters;
-  const relayerUrl = relayerClient.relayerUrl;
+  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.relayerUrl, options?.auth !== undefined);
+  const customHeaders = normalizeHeaders(options?.headers);
   const init = setAuth(
     {
       method: 'GET',
       headers: {
-        'ZAMA-SDK-VERSION': version,
-        'ZAMA-SDK-NAME': sdkName,
+        ...customHeaders,
+        'zama-sdk-version': version,
+        'zama-sdk-name': sdkName,
       },
     } satisfies RequestInit,
     options?.auth,
   );
 
-  const url = `${removeSuffix(relayerUrl, '/')}/v2/keyurl`;
+  assert(relayerBaseUrl.pathname.endsWith('/'));
+  const url = buildRelayerUrlString(relayerBaseUrl, 'v2/keyurl');
 
   let response;
   try {
@@ -54,9 +60,16 @@ export async function fetchFheEncryptionKeySource(
   }
 
   if (!response.ok) {
+    // Surface the message the relayer/edge (Cloudflare/Kong) actually sent for
+    // a 401/403 — e.g. a missing/invalid `x-api-key` — instead of discarding
+    // the body behind a generic "HTTP error! status: X".
+    const { message } = await readErrorMessage(response);
     _throwFetchError({
       url,
-      message: `HTTP error! status: ${response.status} on ${response.url}`,
+      message:
+        message !== undefined
+          ? `HTTP error! status: ${response.status} on ${response.url}: ${message}`
+          : `HTTP error! status: ${response.status} on ${response.url}`,
     });
   }
 
@@ -87,7 +100,7 @@ export async function fetchFheEncryptionKeySource(
       capacity: 2048,
     },
     metadata: {
-      relayerUrl,
+      relayerUrl: relayerClient.relayerUrl,
       chainId: relayerClient.chainId,
     },
   };

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

@@ -2,8 +2,9 @@ import type { Bytes65Hex } from '../../../types/primitives.js';
 import type { RelayerFetchPublicDecryptPayload } from '../../../types/relayer-p.js';
 import type { FetchPublicDecryptResult } from '../../../types/relayer.js';
 import type { FetchPublicDecryptParameters, FetchPublicDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
-import { ensure0x, removeSuffix } from '../../../base/string.js';
+import { ensure0x } from '../../../base/string.js';
 import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
 
 //////////////////////////////////////////////////////////////////////////////
 // fetchPublicDecrypt
@@ -23,9 +24,13 @@ export async function fetchPublicDecrypt(
     extraData: payload.extraData,
   };
 
+  const hasAuth: boolean = options?.auth !== undefined;
+  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.chain.fhevm.relayerUrl, hasAuth);
+  const url = buildRelayerUrlString(relayerBaseUrl, 'v2/public-decrypt');
+
   const request = new RelayerAsyncRequest({
     relayerOperation: 'PUBLIC_DECRYPT',
-    url: `${removeSuffix(relayerClient.chain.fhevm.relayerUrl, '/')}/v2/public-decrypt`,
+    url,
     payload: p,
     options,
   });

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

@@ -2,8 +2,9 @@ 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, removeSuffix } from '../../../base/string.js';
+import { remove0x } from '../../../base/string.js';
 import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
 
 //////////////////////////////////////////////////////////////////////////////
 // fetchUserDecrypt
@@ -42,9 +43,13 @@ export async function fetchUserDecrypt(
     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: `${removeSuffix(relayerClient.chain.fhevm.relayerUrl, '/')}/v2/user-decrypt`,
+    url,
     payload: relayerPayload,
     options,
   });

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

@@ -0,0 +1,56 @@
+import { isNonEmptyString, isRecordStringProperty } from '../../../base/string.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// readErrorMessage
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Best-effort reader that surfaces the message a relayer or an intermediary
+ * edge proxy (Cloudflare/Kong) actually sent in a non-2xx JSON error body.
+ *
+ * Two body shapes are recognized:
+ * - relayer:           `{ "error": { "message": "...", "label": "..." } }`
+ * - Cloudflare / Kong: `{ "message": "...", "label": "..." }` (flat)
+ *
+ * The body is read at most once and only surfaced when it parses as JSON. A
+ * non-JSON body (a bare `"Forbidden"`/`"Rate Limit"` string, an HTML error
+ * page, ...) intentionally surfaces nothing, so the previous behavior for those
+ * responses is preserved and no noise leaks into error messages.
+ *
+ * This function never throws.
+ *
+ * Empty-string `message`/`label` values are treated as absent.
+ *
+ * @param response - The non-2xx fetch {@link Response} to inspect.
+ * @returns The surfaced non-empty `message` and/or `label`, or an empty object
+ *          when the body is missing, unreadable, not JSON, or carries neither.
+ */
+export async function readErrorMessage(
+  response: Response,
+): Promise<{ message?: string | undefined; label?: string | undefined }> {
+  let text: string;
+  try {
+    text = await response.text();
+  } catch {
+    return {};
+  }
+
+  if (text.length === 0) {
+    return {};
+  }
+
+  try {
+    const json: unknown = JSON.parse(text);
+    const err: unknown = typeof json === 'object' && json !== null && 'error' in json ? json.error : json;
+    // Treat empty strings as absent so callers can use `?? <fallback>` safely.
+    const message = isRecordStringProperty(err, 'message') && isNonEmptyString(err.message) ? err.message : undefined;
+    const label = isRecordStringProperty(err, 'label') && isNonEmptyString(err.label) ? err.label : undefined;
+    if (message !== undefined || label !== undefined) {
+      return { message, label };
+    }
+  } catch {
+    // Body wasn't JSON — surface nothing and leave the non-JSON behavior unchanged.
+  }
+
+  return {};
+}

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

@@ -1,38 +1,77 @@
-import { removeSuffix } from '../../../base/string.js';
+import { assert } from '../../../base/errors/InternalError.js';
+import { InvalidUrlError } from '../../../base/errors/InvalidUrlError.js';
+import { removePrefix, removeSuffix } from '../../../base/string.js';
 
-export const ZamaMainnetRelayerBaseUrl = 'https://relayer.mainnet.zama.org';
-export const ZamaMainnetRelayerUrlV2 = `${ZamaMainnetRelayerBaseUrl}/v2`;
+/**
+ * Validates and normalizes a relayer URL before it's used to build the request.
+ *
+ * Validation:
+ *   - non-empty string
+ *   - parses as a URL
+ *   - protocol is `http:` or `https:`
+ *   - contains no userinfo (`user:pass@host`)
+ *   - contains no query string or fragment (they would corrupt path concatenation)
+ *   - if `hasAuth` is true, requires `https:` unless the host is localhost
+ *
+ * Normalization (via WHATWG `URL`):
+ *   - scheme and host lower-cased
+ *   - default ports collapsed (`:443` for https, `:80` for http)
+ *   - path percent-encoded canonically
+ *   - bare-origin URLs get a single trailing `/` (`https://x` → `https://x/`)
+ *
+ * Throws {@link InvalidUrlError} on any failure so the caller surfaces a
+ * uniform error type.
+ *
+ * @returns The normalized URL object.
+ */
+export function validateRelayerBaseUrl(relayerUrl: unknown, hasAuth: boolean): URL {
+  if (typeof relayerUrl !== 'string' || relayerUrl.length === 0) {
+    throw new InvalidUrlError({ message: 'Invalid relayerUrl: must be a non-empty string.' }, {});
+  }
 
-export const ZamaSepoliaRelayerBaseUrl = 'https://relayer.testnet.zama.org';
-export const ZamaSepoliaRelayerUrlV2 = `${ZamaSepoliaRelayerBaseUrl}/v2`;
+  let parsed: URL;
+  try {
+    parsed = new URL(relayerUrl);
+  } catch (cause) {
+    throw new InvalidUrlError({ message: `Invalid relayerUrl: cannot parse as URL}.`, cause }, {});
+  }
 
-export function parseZamaRelayerUrl(relayerUrl: unknown): string | null {
-  if (relayerUrl === undefined || relayerUrl === null || typeof relayerUrl !== 'string') {
-    return null;
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new InvalidUrlError(
+      { message: `Invalid relayerUrl protocol: ${parsed.protocol} (expected http: or https:).` },
+      {},
+    );
   }
 
-  const urlNoSlash = removeSuffix(relayerUrl, '/');
-  if (!URL.canParse(urlNoSlash)) {
-    return null;
+  if (parsed.username !== '' || parsed.password !== '') {
+    throw new InvalidUrlError(
+      { message: 'Invalid relayerUrl: URL must not contain credentials (user:pass@host).' },
+      {},
+    );
   }
 
-  if (urlNoSlash.startsWith(ZamaMainnetRelayerBaseUrl) || urlNoSlash.startsWith(ZamaSepoliaRelayerBaseUrl)) {
-    const zamaUrls = [
-      ZamaSepoliaRelayerBaseUrl,
-      ZamaSepoliaRelayerUrlV2,
-      ZamaMainnetRelayerBaseUrl,
-      ZamaMainnetRelayerUrlV2,
-    ];
-    const isZamaUrl = zamaUrls.includes(urlNoSlash);
-    if (isZamaUrl) {
-      if (urlNoSlash.endsWith('/v2')) {
-        return urlNoSlash;
-      }
-      return `${urlNoSlash}/v2`;
+  if (hasAuth && parsed.protocol === 'http:') {
+    const isLocalhost =
+      parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '[::1]';
+    if (!isLocalhost) {
+      throw new InvalidUrlError(
+        { message: 'Invalid relayerUrl: HTTPS is required when auth credentials are provided.' },
+        {},
+      );
     }
-    // malformed Zama url
-    return null;
   }
 
-  return urlNoSlash;
+  // At the end of validateRelayerUrl, just before `return parsed;`
+  if (!parsed.pathname.endsWith('/')) {
+    parsed.pathname += '/';
+  }
+
+  return parsed;
+}
+
+export function buildRelayerUrlString(relayerBaseUrl: URL, path: string): string {
+  assert(relayerBaseUrl.pathname.endsWith('/'));
+  const sanitizedPath = removeSuffix(removePrefix(path, '/'), '/');
+  const url = new URL(sanitizedPath, relayerBaseUrl).toString();
+  return removeSuffix(url, '/');
 }

package/core/runtime/CoreFhevm-p.ts

@@ -8,43 +8,74 @@ import type {
   FhevmOptions,
   NativeClient,
   OptionalNativeClient,
+  ProtocolVersionResolution,
   ResolvedFhevmOptions,
+  WithProtocolVersion,
+  WithTfheVersion,
+  WithTkmsVersion,
 } from '../types/coreFhevmClient.js';
 import type { FhevmRuntime, WithModule, WithModuleMap } from '../types/coreFhevmRuntime.js';
+import type { TfheVersion } from '../../wasm/tfhe/TfheApi.js';
+import type { TkmsVersion } from '../../wasm/tkms/KmsLibApi.js';
 import { InvalidTypeError } from '../base/errors/InvalidTypeError.js';
 import { verifyTrustedValue } from '../base/trustedValue.js';
 import { uid } from '../base/uid.js';
 import { createTrustedClient } from '../modules/ethereum/createTrustedClient.js';
 import { asFhevmRuntimeWith, assertIsFhevmRuntime, assertIsFhevmRuntimeWith } from './CoreFhevmRuntime-p.js';
 import { globalFheEncryptionKeyCache } from '../key/FheEncryptionKeyCache-p.js';
+import { cloneModuleVersions } from '../runtimeConfig-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
 const PRIVATE_TOKEN = Symbol('CoreFhevmHostClient.token');
+const GET_PROTOCOL_VERSION = Symbol('CoreFhevmHostClient.getProtocolVersion');
+const GET_TFHE_VERSION = Symbol('CoreFhevmHostClient.getTfheVersion');
+const GET_TKMS_VERSION = Symbol('CoreFhevmHostClient.getTkmsVersion');
+const SET_PROTOCOL_VERSION = Symbol('CoreFhevmHostClient.setProtocolVersion');
+const SET_TFHE_VERSION = Symbol('CoreFhevmHostClient.setTfheVersion');
+const SET_TKMS_VERSION = Symbol('CoreFhevmHostClient.setTkmsVersion');
+
+const UNRESOLVED_PROTOCOL_VERSION_MESSAGE =
+  'Protocol version has not been resolved. Await client.ready before reading protocolVersion.';
+const UNRESOLVED_TFHE_VERSION_MESSAGE =
+  'TFHE version has not been resolved. Await client.ready before reading tfheVersion.';
+const UNRESOLVED_TKMS_VERSION_MESSAGE =
+  'TKMS version has not been resolved. Await client.ready before reading tkmsVersion.';
+
+type GetProtocolVersionFn = () => ProtocolVersionResolution | undefined;
+type GetTfheVersionFn = () => TfheVersion | undefined;
+type GetTkmsVersionFn = () => TkmsVersion | undefined;
+type SetProtocolVersionFn = (protocolVersion: ProtocolVersionResolution) => void;
+type SetTfheVersionFn = (tfheVersion: TfheVersion) => void;
+type SetTkmsVersionFn = (tkmsVersion: TkmsVersion) => void;
 
 ////////////////////////////////////////////////////////////////////////////////
 // CoreFhevmImpl
 ////////////////////////////////////////////////////////////////////////////////
 
 class CoreFhevmImpl<
-  chain extends FhevmChain | undefined,
+  chain extends FhevmChain,
   runtime extends FhevmRuntime,
-  client extends OptionalNativeClient,
+  client extends NativeClient,
 > implements Fhevm<chain, FhevmRuntime, client> {
   // Private fields (truly inaccessible from outside)
   readonly #uid: string;
+  #protocolVersion: ProtocolVersionResolution | undefined;
+  #tfheVersion: TfheVersion | undefined;
+  #tkmsVersion: TkmsVersion | undefined;
   readonly #runtime: runtime;
   readonly #trustedClient: TrustedClient<client> | undefined;
   readonly #chain: chain | undefined;
   readonly #options: ResolvedFhevmOptions;
-  readonly #initFns: Set<
-    (client: FhevmBase<FhevmChain | undefined, FhevmRuntime, OptionalNativeClient>) => Promise<void>
-  >;
+  readonly #initFns: Set<(client: FhevmBase<FhevmChain>) => Promise<void>>;
   #readyPromise: Promise<void> | undefined;
 
   // Declared for TypeScript — defined at runtime via Object.defineProperties
   declare readonly uid: string;
   declare readonly chain: chain;
+  declare readonly protocolVersion: ProtocolVersionResolution;
+  declare readonly tfheVersion: TfheVersion;
+  declare readonly tkmsVersion: TkmsVersion;
   declare readonly options: ResolvedFhevmOptions;
   declare readonly trustedClient: client extends NativeClient ? TrustedClient<client> : undefined;
   declare readonly client: client;
@@ -73,10 +104,13 @@ class CoreFhevmImpl<
 
     this.#runtime = parameters.runtime;
     this.#uid = uid();
+    this.#protocolVersion = undefined;
+    this.#tfheVersion = undefined;
+    this.#tkmsVersion = undefined;
     this.#trustedClient =
       parameters.client !== undefined ? createTrustedClient(parameters.client, ownerToken) : undefined;
     this.#chain = parameters.chain;
-    this.#options = Object.freeze(resolveOptions(parameters.options));
+    this.#options = resolveOptions(parameters.options);
     this.#initFns = new Set();
     this.#readyPromise = undefined;
 
@@ -90,6 +124,36 @@ class CoreFhevmImpl<
         configurable: false,
         enumerable: true,
       },
+      protocolVersion: {
+        get: () => {
+          if (this.#protocolVersion === undefined) {
+            throw new Error(UNRESOLVED_PROTOCOL_VERSION_MESSAGE);
+          }
+          return this.#protocolVersion;
+        },
+        configurable: false,
+        enumerable: true,
+      },
+      tfheVersion: {
+        get: () => {
+          if (this.#tfheVersion === undefined) {
+            throw new Error(UNRESOLVED_TFHE_VERSION_MESSAGE);
+          }
+          return this.#tfheVersion;
+        },
+        configurable: false,
+        enumerable: true,
+      },
+      tkmsVersion: {
+        get: () => {
+          if (this.#tkmsVersion === undefined) {
+            throw new Error(UNRESOLVED_TKMS_VERSION_MESSAGE);
+          }
+          return this.#tkmsVersion;
+        },
+        configurable: false,
+        enumerable: true,
+      },
       chain: {
         get: () => this.#chain,
         configurable: false,
@@ -131,6 +195,64 @@ class CoreFhevmImpl<
         enumerable: false,
         writable: false,
       },
+      [GET_PROTOCOL_VERSION]: {
+        value: (): ProtocolVersionResolution | undefined => this.#protocolVersion,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [GET_TFHE_VERSION]: {
+        value: (): TfheVersion | undefined => this.#tfheVersion,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [GET_TKMS_VERSION]: {
+        value: (): TkmsVersion | undefined => this.#tkmsVersion,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [SET_PROTOCOL_VERSION]: {
+        value: (protocolVersion: ProtocolVersionResolution): void => {
+          if (
+            this.#protocolVersion !== undefined &&
+            !_sameProtocolVersionResolution(this.#protocolVersion, protocolVersion)
+          ) {
+            throw new Error(
+              `Protocol version already resolved as ${_formatProtocolVersionResolution(
+                this.#protocolVersion,
+              )}; cannot set ${_formatProtocolVersionResolution(protocolVersion)}.`,
+            );
+          }
+          this.#protocolVersion = protocolVersion;
+        },
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [SET_TFHE_VERSION]: {
+        value: (tfheVersion: TfheVersion): void => {
+          if (this.#tfheVersion !== undefined && this.#tfheVersion !== tfheVersion) {
+            throw new Error(`TFHE version already resolved as ${this.#tfheVersion}; cannot set ${tfheVersion}.`);
+          }
+          this.#tfheVersion = tfheVersion;
+        },
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [SET_TKMS_VERSION]: {
+        value: (tkmsVersion: TkmsVersion): void => {
+          if (this.#tkmsVersion !== undefined && this.#tkmsVersion !== tkmsVersion) {
+            throw new Error(`TKMS version already resolved as ${this.#tkmsVersion}; cannot set ${tkmsVersion}.`);
+          }
+          this.#tkmsVersion = tkmsVersion;
+        },
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
       extend: {
         value: (actionsFactory: (client: typeof this) => FhevmExtension) =>
           extendCoreFhevm(this, actionsFactory, (fn) => {
@@ -255,6 +377,67 @@ export function asFhevmClientWith<
 
 ////////////////////////////////////////////////////////////////////////////////
 
+export function asFhevmWithProtocolVersion<
+  chain extends FhevmChain | undefined = FhevmChain | undefined,
+  runtime extends FhevmRuntime = FhevmRuntime,
+  client extends OptionalNativeClient = NativeClient,
+>(
+  fhevm: FhevmBase<chain, runtime, client>,
+): Fhevm<chain & FhevmChain, runtime, client & NativeClient> & WithProtocolVersion {
+  assertIsFhevmBaseClient(fhevm);
+  const f = fhevm as Fhevm<chain & FhevmChain, runtime, client & NativeClient> & WithProtocolVersion;
+  if (getResolvedProtocolVersion(f) === undefined) {
+    throw new Error(UNRESOLVED_PROTOCOL_VERSION_MESSAGE);
+  }
+  return f;
+}
+
+export function asFhevmWithTfheVersion<
+  chain extends FhevmChain | undefined = FhevmChain | undefined,
+  runtime extends FhevmRuntime = FhevmRuntime,
+  client extends OptionalNativeClient = NativeClient,
+>(
+  fhevm: FhevmBase<chain, runtime, client>,
+): Fhevm<chain & FhevmChain, runtime & WithModule<'encrypt'>, client & NativeClient> & WithTfheVersion {
+  const f = asFhevmClientWith(fhevm, 'encrypt') as Fhevm<
+    chain & FhevmChain,
+    runtime & WithModule<'encrypt'>,
+    client & NativeClient
+  > &
+    WithTfheVersion;
+  if (getResolvedProtocolVersion(f) === undefined) {
+    throw new Error(UNRESOLVED_PROTOCOL_VERSION_MESSAGE);
+  }
+  if (getResolvedTfheVersion(f) === undefined) {
+    throw new Error(UNRESOLVED_TFHE_VERSION_MESSAGE);
+  }
+  return f;
+}
+
+export function asFhevmWithTkmsVersion<
+  chain extends FhevmChain | undefined = FhevmChain | undefined,
+  runtime extends FhevmRuntime = FhevmRuntime,
+  client extends OptionalNativeClient = NativeClient,
+>(
+  fhevm: FhevmBase<chain, runtime, client>,
+): Fhevm<chain & FhevmChain, runtime & WithModule<'decrypt'>, client & NativeClient> & WithTkmsVersion {
+  const f = asFhevmClientWith(fhevm, 'decrypt') as Fhevm<
+    chain & FhevmChain,
+    runtime & WithModule<'decrypt'>,
+    client & NativeClient
+  > &
+    WithTkmsVersion;
+  if (getResolvedProtocolVersion(f) === undefined) {
+    throw new Error(UNRESOLVED_PROTOCOL_VERSION_MESSAGE);
+  }
+  if (getResolvedTkmsVersion(f) === undefined) {
+    throw new Error(UNRESOLVED_TKMS_VERSION_MESSAGE);
+  }
+  return f;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
 export function assertIsFhevmClientWith<
   module extends keyof WithModuleMap,
   chain extends FhevmChain | undefined = FhevmChain | undefined,
@@ -277,9 +460,7 @@ export function assertIsFhevmBaseClient<
   chain extends FhevmChain | undefined = FhevmChain | undefined,
   runtime extends FhevmRuntime = FhevmRuntime,
   client extends OptionalNativeClient = NativeClient,
->(
-  fhevm: FhevmBase<chain, runtime, client>,
-): asserts fhevm is Fhevm<chain & FhevmChain, runtime, client & NativeClient> {
+>(fhevm: unknown): asserts fhevm is Fhevm<chain & FhevmChain, runtime, client & NativeClient> {
   const f = asCoreClientFhevm(fhevm);
   if (f.chain === undefined) {
     throw new Error('Fhevm client chain is undefined');
@@ -335,9 +516,9 @@ export function getTrustedClient<client extends NonNullable<object>>(value: {
 ////////////////////////////////////////////////////////////////////////////////
 
 export type CreateCoreFhevmParameters<
-  chain extends FhevmChain | undefined = FhevmChain | undefined,
-  runtime extends FhevmRuntime = FhevmRuntime,
-  client extends OptionalNativeClient = OptionalNativeClient,
+  chain extends FhevmChain,
+  runtime extends FhevmRuntime,
+  client extends NativeClient,
 > = {
   readonly chain?: chain | undefined;
   readonly client?: client | undefined;
@@ -345,11 +526,10 @@ export type CreateCoreFhevmParameters<
   readonly options?: FhevmOptions | undefined;
 };
 
-export function createCoreFhevm<
-  chain extends FhevmChain | undefined = FhevmChain | undefined,
-  runtime extends FhevmRuntime = FhevmRuntime,
-  client extends OptionalNativeClient = OptionalNativeClient,
->(ownerToken: symbol, parameters: CreateCoreFhevmParameters<chain, runtime, client>): Fhevm<chain, runtime, client> {
+export function createCoreFhevm<chain extends FhevmChain, runtime extends FhevmRuntime, client extends NativeClient>(
+  ownerToken: symbol,
+  parameters: CreateCoreFhevmParameters<chain, runtime, client>,
+): Fhevm<chain, runtime, client> {
   // Pre-populate the global FheEncryptionKey cache if the caller provided one.
   // Avoids a 50MB fetch later when encrypt is first called.
   // No-op if an entry already exists for this relayerUrl (first write wins).
@@ -371,9 +551,7 @@ export function createCoreFhevm<
 function extendCoreFhevm<T extends Fhevm<FhevmChain | undefined, FhevmRuntime, OptionalNativeClient>>(
   client: T,
   actionsFactory: (client: T) => FhevmExtension,
-  pushInitFn: (
-    fn: (client: FhevmBase<FhevmChain | undefined, FhevmRuntime, OptionalNativeClient>) => Promise<void>,
-  ) => void,
+  pushInitFn: (fn: (client: FhevmBase<FhevmChain>) => Promise<void>) => void,
 ): T {
   const { actions, runtime, init } = actionsFactory(client);
 
@@ -403,7 +581,54 @@ function extendCoreFhevm<T extends Fhevm<FhevmChain | undefined, FhevmRuntime, O
 ////////////////////////////////////////////////////////////////////////////////
 
 function resolveOptions(options: FhevmOptions | undefined): ResolvedFhevmOptions {
-  return {
+  return Object.freeze<ResolvedFhevmOptions>({
     batchRpcCalls: options?.batchRpcCalls ?? false,
-  };
+    moduleVersions: cloneModuleVersions(options?.moduleVersions),
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+function _sameProtocolVersionResolution(a: ProtocolVersionResolution, b: ProtocolVersionResolution): boolean {
+  return a.version === b.version && a.comparator === b.comparator;
+}
+
+function _formatProtocolVersionResolution(protocolVersion: ProtocolVersionResolution): string {
+  return `${protocolVersion.comparator}:${protocolVersion.version}`;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function setResolvedProtocolVersion(fhevm: FhevmBase, protocolVersion: ProtocolVersionResolution): void {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [SET_PROTOCOL_VERSION]: SetProtocolVersionFn };
+  f[SET_PROTOCOL_VERSION](protocolVersion);
+}
+
+export function setResolvedTfheVersion(fhevm: FhevmBase, tfheVersion: TfheVersion): void {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [SET_TFHE_VERSION]: SetTfheVersionFn };
+  f[SET_TFHE_VERSION](tfheVersion);
+}
+
+export function setResolvedTkmsVersion(fhevm: FhevmBase, tkmsVersion: TkmsVersion): void {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [SET_TKMS_VERSION]: SetTkmsVersionFn };
+  f[SET_TKMS_VERSION](tkmsVersion);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function getResolvedProtocolVersion(fhevm: unknown): ProtocolVersionResolution | undefined {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [GET_PROTOCOL_VERSION]: GetProtocolVersionFn };
+  return f[GET_PROTOCOL_VERSION]();
 }
+
+export function getResolvedTfheVersion(fhevm: unknown): TfheVersion | undefined {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [GET_TFHE_VERSION]: GetTfheVersionFn };
+  return f[GET_TFHE_VERSION]();
+}
+
+export function getResolvedTkmsVersion(fhevm: unknown): TkmsVersion | undefined {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [GET_TKMS_VERSION]: GetTkmsVersionFn };
+  return f[GET_TKMS_VERSION]();
+}
+
+////////////////////////////////////////////////////////////////////////////////