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

package/core/coprocessor/ZkProofBuilder-p.ts

@@ -1,7 +1,7 @@
 import type { Bytes20, Bytes32, BytesHex, ChecksummedAddress, UintNumber } from '../types/primitives.js';
 import type { ZkProof } from '../types/zkProof-p.js';
 import type { EncryptionBits, FheType } from '../types/fheType.js';
-import type { ZkProofBuilder } from '../types/zkProofBuilder.js';
+import type { ZkProofBuilder } from '../types/zkProofBuilder-p.js';
 import type { WithEncrypt } from '../types/coreFhevmRuntime.js';
 import type { FhevmChain } from '../types/fhevmChain.js';
 import type {
@@ -15,6 +15,7 @@ import type {
   BoolValueLike,
   AddressValueLike,
 } from '../types/primitives.js';
+import type { TfheVersion } from '../../wasm/tfhe/TfheApi.js';
 import { assert } from '../base/errors/InternalError.js';
 import { isUint64, uint256ToBytes32 } from '../base/uint.js';
 import { isAddress } from '../base/address.js';
@@ -30,6 +31,7 @@ import { fetchFheEncryptionKeyWasm } from '../key/fetchFheEncryptionKey.js';
 type Context = {
   readonly chain: FhevmChain;
   readonly runtime: WithEncrypt;
+  readonly tfheVersion: TfheVersion;
 };
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -150,7 +152,7 @@ class ZkProofBuilderImpl implements ZkProofBuilder {
     },
   ): Promise<ZkProof> {
     // Fetch the FheEncryptionKey (in wasm format) from the global cache.
-    const fheEncryptionKeyWasm = await fetchFheEncryptionKeyWasm(context);
+    const fheEncryptionKeyWasm = await fetchFheEncryptionKeyWasm(context, {});
 
     if (this.#totalBits === 0) {
       throw new ZkProofError({
@@ -219,6 +221,7 @@ class ZkProofBuilderImpl implements ZkProofBuilder {
         fheEncryptionKey: fheEncryptionKeyWasm,
         metaData,
         extraData: asBytesHex(extraData),
+        tfheVersion: context.tfheVersion,
       });
 
     return toZkProof(

package/core/coprocessor/encrypt.ts

@@ -3,6 +3,7 @@ import type { FhevmChain } from '../types/fhevmChain.js';
 import type { BytesHex, ChecksummedAddress, TypedValue } from '../types/primitives.js';
 import type { RelayerInputProofOptions } from '../types/relayer.js';
 import type { InputHandle } from '../types/encryptedTypes-p.js';
+import type { TfheVersion } from '../../wasm/tfhe/TfheApi.js';
 import { fetchVerifiedInputProof } from './fetchVerifiedInputProof.js';
 import { createZkProof } from './ZkProofBuilder-p.js';
 
@@ -12,6 +13,7 @@ type Context = {
   readonly chain: FhevmChain;
   readonly runtime: WithEncrypt;
   readonly client: NonNullable<object>;
+  readonly tfheVersion: TfheVersion;
   readonly options: { readonly batchRpcCalls: boolean };
 };
 
@@ -32,7 +34,10 @@ type ReturnType = {
 export async function encrypt(context: Context, parameters: Parameters): Promise<ReturnType> {
   const hardCodedExtraData = '0x00' as BytesHex;
 
-  const zkProof = await createZkProof(context, { ...parameters, extraData: hardCodedExtraData });
+  const zkProof = await createZkProof(
+    { chain: context.chain, runtime: context.runtime, tfheVersion: context.tfheVersion },
+    { ...parameters, extraData: hardCodedExtraData },
+  );
 
   const inputProof = await fetchVerifiedInputProof(context, {
     zkProof,

package/core/errors/RelayerResponseStatusError.ts

@@ -15,6 +15,12 @@ export type RelayerResponseStatusErrorType = RelayerResponseStatusError & {
 export type RelayerResponseStatusErrorParams = Prettify<
   Omit<RelayerResponseErrorBaseParams, 'message' | 'name' | 'details'> & {
     readonly state: RelayerAsyncRequestState;
+    /**
+     * Optional message surfaced from the response body — e.g. the JSON error a
+     * Cloudflare/Kong edge proxy returns on a 403. Appended to the error
+     * message and details when present.
+     */
+    readonly responseMessage?: string | undefined;
   }
 >;
 
@@ -22,12 +28,18 @@ export type RelayerResponseStatusErrorParams = Prettify<
  * The response status is unexpected.
  */
 export class RelayerResponseStatusError extends RelayerResponseErrorBase {
-  constructor(params: RelayerResponseStatusErrorParams) {
+  constructor({ responseMessage, ...params }: RelayerResponseStatusErrorParams) {
     super({
       ...params,
       name: 'RelayerResponseStatusError',
       message: `${humanReadableOperation(params.operation, true)}: Relayer returned unexpected response status: ${params.status}`,
-      details: `The Relayer server returned an unexpected response status (${params.status}). This status ${params.status} is not part of the expected API contract and may indicate a server configuration issue.`,
+      // Surface the relayer/edge message (e.g. a Cloudflare/Kong 403 block) via
+      // the `Details:` line when present; otherwise keep the generic
+      // explanation. The primary message is unchanged for backward
+      // compatibility.
+      details:
+        responseMessage ??
+        `The Relayer server returned an unexpected response status (${params.status}). This status ${params.status} is not part of the expected API contract and may indicate a server configuration issue.`,
     });
   }
 }

package/core/host-contracts/HostContractVersion-p.ts

@@ -19,16 +19,34 @@ type Parameters = {
 };
 
 type ReturnType = HostContractVersion;
+type InvalidateVersionCacheOptions = {
+  readonly includeInflight?: boolean | undefined;
+};
+type InvalidateVersionCacheParameters = Parameters & InvalidateVersionCacheOptions;
 
 ////////////////////////////////////////////////////////////////////////////////
 
 const cachedGetVersion = createCachedFetch<Context, Parameters, ReturnType>({
   executeFn: _getVersion,
-  cacheKeyFn: (context, params) => `${context.runtime.uid.toLowerCase()}:${params.address.toLowerCase()}`,
+  cacheKeyFn: _getVersionCacheKey,
   // Host contract versions are immutable per deployment, so a long TTL is safe.
   ttlMs: CACHE_TTL_24H,
 });
 
+/**
+ * Builds the cache key for a host contract version lookup.
+ *
+ * The runtime UID scopes the entry to one SDK runtime instance, while the
+ * address scopes it to one deployed host contract within that runtime.
+ *
+ * Host-contract addresses are treated as globally unique deployment
+ * identifiers across supported chains. If that invariant changes, include the
+ * chain id in this key.
+ */
+function _getVersionCacheKey(context: Context, parameters: Parameters): string {
+  return `${context.runtime.uid.toLowerCase()}:${parameters.address.toLowerCase()}`;
+}
+
 /**
  * Reads the version of a host contract at the given address.
  *
@@ -46,13 +64,51 @@ const cachedGetVersion = createCachedFetch<Context, Parameters, ReturnType>({
  *   Use this after a known contract upgrade to ensure all subsequent callers
  *   see the updated version.
  */
-export function getVersion(
+export function getHostContractVersion(
   context: Context,
   parameters: Parameters & { readonly forceRefresh?: boolean },
 ): Promise<ReturnType> {
   return cachedGetVersion.execute(context, parameters);
 }
 
+/**
+ * Invalidates cached host contract versions.
+ *
+ * When called with `context` and `address`, only that runtime/address entry is
+ * invalidated. When called without arguments, all settled host-version cache
+ * entries in the current JS realm are invalidated.
+ *
+ * In-flight entries are kept by default. Pass `includeInflight: true` to also
+ * discard in-flight fetches; existing callers still receive their promises, but
+ * those results will no longer be stored in the cache.
+ */
+export function invalidateVersionCache(options?: InvalidateVersionCacheOptions): void;
+export function invalidateVersionCache(context: Context, parameters: InvalidateVersionCacheParameters): void;
+export function invalidateVersionCache(
+  contextOrOptions?: Context | InvalidateVersionCacheOptions,
+  parameters?: InvalidateVersionCacheParameters,
+): void {
+  if (parameters === undefined) {
+    const options = contextOrOptions as InvalidateVersionCacheOptions | undefined;
+    cachedGetVersion.clear(_makeClearOptions(options));
+    return;
+  }
+
+  cachedGetVersion.clear({
+    key: _getVersionCacheKey(contextOrOptions as Context, parameters),
+    ..._makeClearOptions(parameters),
+  });
+}
+
+function _makeClearOptions(
+  options: InvalidateVersionCacheOptions | undefined,
+): { readonly includeInflight?: boolean } | undefined {
+  if (options?.includeInflight === undefined) {
+    return undefined;
+  }
+  return { includeInflight: options.includeInflight };
+}
+
 async function _getVersion(context: Context, parameters: Parameters): Promise<HostContractVersion> {
   const trustedClient = getTrustedClient(context);
   const address = parameters.address;
@@ -109,7 +165,8 @@ function parseVersion(version: string): HostContractVersion {
     contractName !== 'FHEVMExecutor' &&
     contractName !== 'InputVerifier' &&
     contractName !== 'KMSVerifier' &&
-    contractName !== 'HCULimit'
+    contractName !== 'HCULimit' &&
+    contractName !== 'ProtocolConfig'
   ) {
     throw new Error(err);
   }

package/core/host-contracts/KmsSignersContext-p.ts

@@ -7,7 +7,13 @@ import { InvalidTypeError } from '../base/errors/InvalidTypeError.js';
 import { addressToChecksummedAddress } from '../base/address.js';
 import { DuplicateSignerError, ThresholdSignerError, UnknownSignerError } from '../errors/SignersError.js';
 import { assertOwnedBy } from '../runtime/CoreFhevmRuntime-p.js';
-import { assertIsKmsExtraData, toKmsExtraData } from '../kms/kmsExtraData.js';
+import {
+  assertIsKmsExtraData,
+  EXTRA_DATA_V0,
+  EXTRA_DATA_V1,
+  EXTRA_DATA_V2,
+  toKmsExtraData,
+} from '../kms/kmsExtraData.js';
 import { assertIsNonEmptyString, ensure0x } from '../base/string.js';
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -25,6 +31,7 @@ class KmsSignersContextImpl implements KmsSignersContext {
   readonly #owner: WeakRef<FhevmRuntime>;
   readonly #address: ChecksummedAddress;
   readonly #kmsContextId: Uint256BigInt;
+  readonly #kmsEpochId: Uint256BigInt;
   readonly #kmsSigners: ChecksummedAddress[];
   readonly #kmsSignersSet: Set<string>;
   readonly #kmsSignerThreshold: Uint8Number;
@@ -35,6 +42,7 @@ class KmsSignersContextImpl implements KmsSignersContext {
     parameters: {
       readonly address: ChecksummedAddress;
       readonly kmsContextId: Uint256BigInt;
+      readonly kmsEpochId: Uint256BigInt;
       readonly kmsSigners: ChecksummedAddress[];
       readonly kmsSignerThreshold: Uint8Number;
     },
@@ -45,6 +53,7 @@ class KmsSignersContextImpl implements KmsSignersContext {
     this.#owner = owner;
     this.#address = parameters.address;
     this.#kmsContextId = parameters.kmsContextId;
+    this.#kmsEpochId = parameters.kmsEpochId;
     this.#kmsSigners = [...parameters.kmsSigners];
     this.#kmsSignerThreshold = parameters.kmsSignerThreshold;
     this.#kmsSignersSet = new Set(this.#kmsSigners.map((addr) => addr.toLowerCase()));
@@ -61,6 +70,10 @@ class KmsSignersContextImpl implements KmsSignersContext {
     return this.#kmsContextId;
   }
 
+  public get epochId(): Uint256BigInt {
+    return this.#kmsEpochId;
+  }
+
   public get signers(): ChecksummedAddress[] {
     return this.#kmsSigners;
   }
@@ -102,16 +115,19 @@ Object.freeze(KmsSignersContextImpl);
 export function createKmsSignersContext(
   owner: WeakRef<FhevmRuntime>,
   parameters: {
-    readonly address: ChecksummedAddress;
+    readonly kmsVerifierAddress: ChecksummedAddress;
     readonly kmsContextId: Uint256BigInt;
+    readonly kmsEpochId: Uint256BigInt;
     readonly kmsSigners: readonly ChecksummedAddress[];
     readonly kmsSignerThreshold: Uint8Number;
   },
 ): KmsSignersContext {
-  const { address, kmsContextId, kmsSigners, kmsSignerThreshold } = parameters;
+  const { kmsVerifierAddress: address, kmsContextId, kmsEpochId, kmsSigners, kmsSignerThreshold } = parameters;
+
   return new KmsSignersContextImpl(PRIVATE_TOKEN, owner, {
     address: addressToChecksummedAddress(address),
     kmsContextId,
+    kmsEpochId,
     kmsSignerThreshold: Number(kmsSignerThreshold) as Uint8Number,
     kmsSigners: kmsSigners.map(addressToChecksummedAddress),
   });
@@ -121,12 +137,27 @@ export function createKmsSignersContext(
 
 export function kmsSignersContextToExtraData(kmsSignersContext: KmsSignersContext): BytesHex {
   assertIsKmsSignersContext(kmsSignersContext, {});
+
   if (kmsSignersContext.id === 0n) {
-    return '0x00' as BytesHex;
+    return toKmsExtraData({
+      version: EXTRA_DATA_V0,
+      kmsContextId: 0n as Uint256BigInt,
+      kmsEpochId: 0n as Uint256BigInt,
+    });
   }
+
+  if (kmsSignersContext.epochId === 0n) {
+    return toKmsExtraData({
+      version: EXTRA_DATA_V1,
+      kmsContextId: kmsSignersContext.id,
+      kmsEpochId: 0n as Uint256BigInt,
+    });
+  }
+
   return toKmsExtraData({
-    version: 1 as Uint8Number,
+    version: EXTRA_DATA_V2,
     kmsContextId: kmsSignersContext.id,
+    kmsEpochId: kmsSignersContext.epochId,
   });
 }
 

package/core/host-contracts/abi-fragments/fragments.ts

@@ -309,6 +309,34 @@ export const getSignersForKmsContextAbi: readonly [
   },
 ] as const;
 
+////////////////////////////////////////////////////////////////////////////////
+// ProtocolConfig.getCurrentKmsContextAndEpoch()
+// Protocol version >= 0.14
+////////////////////////////////////////////////////////////////////////////////
+
+export const getCurrentKmsContextAndEpochAbi: readonly [
+  Record<string, unknown> & { readonly name: 'getCurrentKmsContextAndEpoch' },
+] = [
+  {
+    inputs: [],
+    name: 'getCurrentKmsContextAndEpoch',
+    outputs: [
+      {
+        internalType: 'uint256',
+        name: 'contextId',
+        type: 'uint256',
+      },
+      {
+        internalType: 'uint256',
+        name: 'epochId',
+        type: 'uint256',
+      },
+    ],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
 //getSignersForKmsContext
 ////////////////////////////////////////////////////////////////////////////////
 // InputVerifier.getCoprocessorSigners()

package/core/host-contracts/canDecryptValuesFromPairs.ts

@@ -82,7 +82,7 @@ export async function canDecryptValuesFromPairs(context: Context, parameters: Pa
   }
 
   const details = await isUserDecryptable(context, {
-    address: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
+    aclAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
     userAddress,
     handleContractPairs,
   });

package/core/host-contracts/checkAllowedForDecryption.ts

@@ -15,21 +15,21 @@ type Context = {
 };
 
 type Parameters = {
-  readonly address: ChecksummedAddress;
+  readonly aclAddress: ChecksummedAddress;
   readonly handles: readonly Handle[];
 };
 
 ////////////////////////////////////////////////////////////////////////////////
 
 export async function checkAllowedForDecryption(context: Context, parameters: Parameters): Promise<void> {
-  const { handles } = parameters;
+  const { aclAddress, handles } = parameters;
 
   const results = await isAllowedForDecryption(context, parameters);
 
   const failedHandles = handles.filter((_, i) => results[i] !== true).map((h) => h.bytes32Hex);
   if (failedHandles.length > 0) {
     throw new AclPublicDecryptionError({
-      contractAddress: context.chain.fhevm.contracts.acl.address as ChecksummedAddress,
+      contractAddress: aclAddress,
       handles: failedHandles,
     });
   }

package/core/host-contracts/checkDelegation.ts

@@ -15,7 +15,7 @@ type Context = {
 };
 
 type Parameters = {
-  readonly address: ChecksummedAddress;
+  readonly aclAddress: ChecksummedAddress;
   readonly delegator: ChecksummedAddress;
   readonly delegate: ChecksummedAddress;
   readonly handleContractPairs: ReadonlyArray<{
@@ -27,7 +27,7 @@ type Parameters = {
 ////////////////////////////////////////////////////////////////////////////////
 
 export async function checkDelegation(context: Context, parameters: Parameters): Promise<void> {
-  const { address, delegator, delegate, handleContractPairs } = parameters;
+  const { aclAddress, delegator, delegate, handleContractPairs } = parameters;
 
   if (handleContractPairs.length === 0) {
     throw new Error('checkDelegation requires at least one (handle, contractAddress) pair');
@@ -41,7 +41,7 @@ export async function checkDelegation(context: Context, parameters: Parameters):
   // 1. Verify rule: delegator !== delegate
   if (delegator.toLowerCase() === delegate.toLowerCase()) {
     throw new AclUserDecryptionError({
-      contractAddress: address,
+      contractAddress: aclAddress,
       message: `delegator ${delegator} cannot be equal to delegate`,
     });
   }
@@ -49,13 +49,13 @@ export async function checkDelegation(context: Context, parameters: Parameters):
   // 2. Verify rule: delegate !== WILDCARD_CONTRACT
   if (delegate.toLowerCase() === WILDCARD_DELEGATION_ADDRESS.toLowerCase()) {
     throw new AclUserDecryptionError({
-      contractAddress: address,
+      contractAddress: aclAddress,
       message: `delegate cannot be equal to wildcard contract address`,
     });
   }
   if (delegator.toLowerCase() === WILDCARD_DELEGATION_ADDRESS.toLowerCase()) {
     throw new AclUserDecryptionError({
-      contractAddress: address,
+      contractAddress: aclAddress,
       message: `delegator cannot be equal to wildcard contract address`,
     });
   }
@@ -64,13 +64,13 @@ export async function checkDelegation(context: Context, parameters: Parameters):
   for (const pair of handleContractPairs) {
     if (delegator.toLowerCase() === pair.contractAddress.toLowerCase()) {
       throw new AclUserDecryptionError({
-        contractAddress: address,
+        contractAddress: aclAddress,
         message: `delegator ${delegator} cannot be equal to contractAddress`,
       });
     }
     if (delegate.toLowerCase() === pair.contractAddress.toLowerCase()) {
       throw new AclUserDecryptionError({
-        contractAddress: address,
+        contractAddress: aclAddress,
         message: `delegate ${delegate} cannot be equal to contractAddress`,
       });
     }
@@ -98,7 +98,7 @@ export async function checkDelegation(context: Context, parameters: Parameters):
 
   // 5. Single batched RPC call for all unique checks
   const allResults = await isHandleDelegatedForUserDecryption(context, {
-    address,
+    aclAddress,
     delegator,
     delegate,
     pairs: allChecks,
@@ -121,7 +121,7 @@ export async function checkDelegation(context: Context, parameters: Parameters):
     const key = getKey(pair.contractAddress, pair.handle.bytes32Hex);
     if (resultMap.get(key) !== true) {
       throw new AclUserDecryptionError({
-        contractAddress: address,
+        contractAddress: aclAddress,
         message: `Delegate ${delegate} is not delegated by ${delegator} to user decrypt handle ${pair.handle.bytes32Hex} on contract ${pair.contractAddress}!`,
       });
     }

package/core/host-contracts/checkPersistAllowed.ts

@@ -14,7 +14,7 @@ type Context = {
 };
 
 type Parameters = {
-  readonly address: ChecksummedAddress;
+  readonly aclAddress: ChecksummedAddress;
   readonly userAddress: ChecksummedAddress;
   readonly handleContractPairs: ReadonlyArray<{
     readonly handle: Handle;
@@ -25,7 +25,7 @@ type Parameters = {
 ////////////////////////////////////////////////////////////////////////////////
 
 export async function checkPersistAllowed(context: Context, parameters: Parameters): Promise<void> {
-  const { address, userAddress, handleContractPairs } = parameters;
+  const { aclAddress, userAddress, handleContractPairs } = parameters;
 
   if (handleContractPairs.length === 0) {
     throw new Error('checkPersistAllowed requires at least one (handle, contractAddress) pair');
@@ -38,9 +38,9 @@ export async function checkPersistAllowed(context: Context, parameters: Paramete
 
   // 1. Verify rule: userAddress !== contractAddress
   for (const pair of handleContractPairs) {
-    if (parameters.userAddress.toLowerCase() === pair.contractAddress.toLowerCase()) {
+    if (userAddress.toLowerCase() === pair.contractAddress.toLowerCase()) {
       throw new AclUserDecryptionError({
-        contractAddress: address,
+        contractAddress: aclAddress,
         message: `userAddress ${userAddress} should not be equal to contractAddress when requesting user decryption!`,
       });
     }
@@ -52,12 +52,12 @@ export async function checkPersistAllowed(context: Context, parameters: Paramete
 
   for (const pair of handleContractPairs) {
     // User check (runtime defensive check, use lowercase)
-    const userKey = getKey(parameters.userAddress, pair.handle.bytes32Hex);
+    const userKey = getKey(userAddress, pair.handle.bytes32Hex);
     if (!seenKeys.has(userKey)) {
       seenKeys.add(userKey);
       allChecks.push({
         handle: pair.handle,
-        account: parameters.userAddress,
+        account: userAddress,
       });
     }
     // Contract check (runtime defensive check, use lowercase)
@@ -77,7 +77,7 @@ export async function checkPersistAllowed(context: Context, parameters: Paramete
 
   // 3. Single batched RPC call for all unique checks
   const allResults = await persistAllowed(context, {
-    address,
+    aclAddress,
     pairs: allChecks,
   });
 
@@ -98,8 +98,8 @@ export async function checkPersistAllowed(context: Context, parameters: Paramete
     const userKey = getKey(parameters.userAddress, pair.handle.bytes32Hex);
     if (resultMap.get(userKey) !== true) {
       throw new AclUserDecryptionError({
-        contractAddress: address,
-        message: `User ${parameters.userAddress} is not authorized to decrypt handle ${pair.handle.bytes32Hex}!`,
+        contractAddress: aclAddress,
+        message: `User ${userAddress} is not authorized to decrypt handle ${pair.handle.bytes32Hex}!`,
       });
     }
 
@@ -107,7 +107,7 @@ export async function checkPersistAllowed(context: Context, parameters: Paramete
     const contractKey = getKey(pair.contractAddress, pair.handle.bytes32Hex);
     if (resultMap.get(contractKey) !== true) {
       throw new AclUserDecryptionError({
-        contractAddress: address,
+        contractAddress: aclAddress,
         message: `Dapp contract ${pair.contractAddress} is not authorized to user decrypt handle ${pair.handle.bytes32Hex}!`,
       });
     }

package/core/host-contracts/getAclAddress-p.ts

@@ -12,7 +12,7 @@ type Context = {
 };
 
 type Parameters = {
-  readonly address: ChecksummedAddress;
+  readonly fhevmExecutorAddress: ChecksummedAddress;
 };
 
 type ReturnType = ChecksummedAddress;
@@ -26,10 +26,9 @@ type ReturnType = ChecksummedAddress;
  */
 export async function getAclAddress(context: Context, parameters: Parameters): Promise<ReturnType> {
   const trustedClient = getTrustedClient(context);
-  const address = parameters.address;
 
   const res = await context.runtime.ethereum.readContract(trustedClient, {
-    address: address,
+    address: parameters.fhevmExecutorAddress,
     abi: getACLAddressAbi,
     args: [],
     functionName: getACLAddressAbi[0].name,

package/core/host-contracts/getCurrentKmsContextAndEpoch-p.ts

@@ -0,0 +1,92 @@
+import type { ChecksummedAddress, Uint256BigInt } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { getCurrentKmsContextAndEpochAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+import { getHostContractVersion, isVersionStrictlyBefore } from './HostContractVersion-p.js';
+import { assertIsUint256 } from '../base/uint.js';
+import { CACHE_TTL_24H, createCachedFetch } from '../base/cachedFetch.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly protocolConfigAddress: ChecksummedAddress;
+};
+
+type ReturnType = { readonly contextId: Uint256BigInt; readonly epochId: Uint256BigInt };
+
+////////////////////////////////////////////////////////////////////////////////
+
+const cachedGetCurrentKmsContextAndEpoch = createCachedFetch<Context, Parameters, ReturnType>({
+  executeFn: _getCurrentKmsContextAndEpoch,
+  cacheKeyFn: (context, params) => `${context.runtime.uid.toLowerCase()}:${params.protocolConfigAddress.toLowerCase()}`,
+  // Host contract values are immutable per deployment, so a long TTL is safe.
+  ttlMs: CACHE_TTL_24H,
+});
+
+/**
+ * Reads the current KMS context ID and epoch ID from a ProtocolConfig contract.
+ *
+ * Requires ProtocolConfig >= v0.2.0 (protocol v0.14.0).
+ *
+ * Results are cached per (runtime, address) with a 24-hour TTL.
+ * Concurrent callers share a single in-flight RPC request (deduplication).
+ *
+ * @param parameters.address - The checksummed address of the ProtocolConfig contract.
+ * @param parameters.forceRefresh - If `true`, invalidates the cached entry and
+ *   makes a fresh RPC call. The new result is stored back in the cache.
+ */
+export function getCurrentKmsContextAndEpoch(
+  context: Context,
+  parameters: Parameters & { readonly forceRefresh?: boolean | undefined },
+): Promise<ReturnType> {
+  return cachedGetCurrentKmsContextAndEpoch.execute(context, parameters);
+}
+
+async function _getCurrentKmsContextAndEpoch(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const protocolConfigVersion = await getHostContractVersion(context, { address: parameters.protocolConfigAddress });
+
+  // getCurrentKmsContextAndEpoch requires ProtocolConfig >= v0.2.0 (protocol v0.14.0)
+  if (isVersionStrictlyBefore(protocolConfigVersion, { major: 0, minor: 2 })) {
+    throw new Error(
+      'ProtocolConfig.getCurrentKmsContextAndEpoch() requires ProtocolConfig >= v0.2.0 (protocol v0.14.0)',
+    );
+  }
+
+  const trustedClient = getTrustedClient(context);
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: parameters.protocolConfigAddress,
+    abi: getCurrentKmsContextAndEpochAbi,
+    args: [],
+    functionName: getCurrentKmsContextAndEpochAbi[0].name,
+  });
+
+  if (!Array.isArray(res) || res.length < 2) {
+    throw new Error(`Invalid getCurrentKmsContextAndEpoch result.`);
+  }
+
+  const unknownContextId = res[0] as unknown;
+  const unknownEpochId = res[1] as unknown;
+
+  try {
+    assertIsUint256(unknownContextId, {});
+  } catch (e) {
+    throw new Error(`Invalid KMS Context Id.`, { cause: e });
+  }
+
+  try {
+    assertIsUint256(unknownEpochId, {});
+  } catch (e) {
+    throw new Error(`Invalid KMS Epoch Id.`, { cause: e });
+  }
+
+  return Object.freeze({
+    contextId: BigInt(unknownContextId) as Uint256BigInt,
+    epochId: BigInt(unknownEpochId) as Uint256BigInt,
+  });
+}