@fhevm/sdk 0.13.2 → 0.14.0-12

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

@@ -0,0 +1,75 @@
+import type { FetchFeaturesParameters, FetchFeaturesReturnType, RelayerClientWithRuntime } from '../types.js';
+import { RelayerResponseErrorBase } from '../../../errors/RelayerResponseErrorBase.js';
+import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
+
+//////////////////////////////////////////////////////////////////////////////
+// fetchFeatures
+//////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Probes whether the relayer exposes the unified user-decrypt route, and reports it as
+ * `relayerSupportsV3UserDecryptRoute`.
+ *
+ * There is no dedicated feature endpoint, so we detect the route by POSTing an **empty probe
+ * payload** to `v3/user-decrypt` and reading the outcome. Routing is path-based, so the body never
+ * decides existence:
+ *
+ * - **Route absent** → a user-decrypt POST does not expect a 404, so the request layer surfaces it
+ *   as `status: 404` → `relayerSupportsV3UserDecryptRoute: false`.
+ * - **Route present** → the relayer answers the (invalid) probe with a 400 (or 429 / 5xx). Any such
+ *   response proves the endpoint exists → `relayerSupportsV3UserDecryptRoute: true`.
+ * - **Auth rejected (401 / 403)** → the key is missing, bad, or expired (or an edge proxy blocked
+ *   the request). That is not a capability answer, so we **fail loudly** (rethrow) rather than guess.
+ *   `ensureRelayerFeatures` clears its in-flight promise on this rejection, so a retry with a valid
+ *   key resolves cleanly.
+ *
+ * `options.auth` is forwarded so the probe can authenticate against relayers that require a key
+ * (e.g. mainnet); the resulting capability is itself auth-independent.
+ *
+ * Any non-response failure (network, DNS, timeout) is likewise rethrown so the caller fails loudly
+ * and retries instead of caching a wrong answer.
+ */
+export async function fetchFeatures(
+  relayerClient: RelayerClientWithRuntime,
+  parameters: FetchFeaturesParameters,
+): Promise<FetchFeaturesReturnType> {
+  const { options } = parameters;
+
+  const hasAuth: boolean = options?.auth !== undefined;
+  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.chain.fhevm.relayerUrl, hasAuth);
+  const url = buildRelayerUrlString(relayerBaseUrl, 'v3/user-decrypt');
+
+  const request = new RelayerAsyncRequest({
+    relayerOperation: 'USER_DECRYPT',
+    url,
+    // Deliberately-empty probe: a present route rejects it with a 400 (proving it exists); an absent
+    // route 404s. We never expect this request to succeed.
+    payload: {},
+    options,
+    // Do not use a logger here: this is a low-level probe.
+    // logger: relayerClient.runtime.config.logger,
+  });
+
+  try {
+    await request.run();
+    // Not expected from an empty payload — but if the route accepts it, it certainly exists.
+    return { relayerSupportsV3UserDecryptRoute: true };
+  } catch (error) {
+    if (error instanceof RelayerResponseErrorBase) {
+      if (error.status === 404) {
+        // RelayerResponseStatusError(404)
+        return { relayerSupportsV3UserDecryptRoute: false };
+      }
+      // Auth rejected (missing / bad / expired key) or edge-blocked → fail loudly instead of
+      // reporting a capability: the caller supplied a key we could not authenticate with.
+      if (error.status === 401 || error.status === 403) {
+        throw error;
+      }
+      // Any other relayer response (400 rejects the empty probe, 429, 5xx) proves the route exists.
+      return { relayerSupportsV3UserDecryptRoute: true };
+    }
+    // Non-response failure (network / timeout): can't determine support — fail loudly.
+    throw error;
+  }
+}

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

@@ -33,6 +33,7 @@ export async function fetchPublicDecrypt(
     url,
     payload: p,
     options,
+    logger: relayerClient.runtime.config.logger,
   });
 
   const result = (await request.run()) as FetchPublicDecryptResult;

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

@@ -76,6 +76,7 @@ export async function fetchUserDecryptV1(
     url,
     payload: relayerPayload,
     options,
+    logger: relayerClient.runtime.config.logger,
   });
 
   const result = (await request.run()) as FetchUserDecryptResult;

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

@@ -54,6 +54,7 @@ export async function fetchUserDecryptV2(
     url,
     payload: relayerPayload,
     options,
+    logger: relayerClient.runtime.config.logger,
   });
 
   const result = (await request.run()) as FetchUserDecryptResult;

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

@@ -5,6 +5,7 @@ import { fetchPublicDecrypt } from './fetchPublicDecrypt.js';
 import { fetchFheEncryptionKeyBytes } from './fetchFheEncryptionKeyBytes.js';
 import { fetchFheEncryptionKeySource } from './fetchFheEncryptionKeySource.js';
 import { fetchUserDecrypt } from './fetchUserDecrypt.js';
+import { fetchFeatures } from './fetchFeatures.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 // relayerModule
@@ -19,6 +20,7 @@ export const relayerModule: RelayerModuleFactory = () => {
       fetchPublicDecrypt,
       fetchUserDecrypt,
       fetchDelegatedUserDecrypt,
+      fetchFeatures,
     }),
   });
 };

package/core/modules/relayer/types.ts

@@ -19,6 +19,7 @@ import type { Handle, InputHandle } from '../../types/encryptedTypes-p.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
 import type { FhevmRuntime } from '../../types/coreFhevmRuntime.js';
 import type { FhevmClientFrozenContext } from '../../types/fhevmClientFrozenContext-p.js';
+import type { Auth } from '../../types/auth.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 //
@@ -152,7 +153,8 @@ export type FetchUserDecryptParametersV2 = {
     }>;
     readonly kmsDecryptEip712Signer: ChecksummedAddress;
     readonly kmsDecryptEip712Message: KmsUserDecryptEip712V2Message;
-    readonly kmsDecryptEip712Signature: Bytes65Hex;
+    // Variable length: 65-byte EOA, ERC-1271 blob, or empty `0x`.
+    readonly kmsDecryptEip712Signature: BytesHex;
   };
   readonly fhevmContext: FhevmClientFrozenContext;
   readonly options?: RelayerUserDecryptOptions | undefined;
@@ -197,6 +199,27 @@ export type FetchDelegatedUserDecryptModuleFunction = {
   ): Promise<FetchDelegatedUserDecryptReturnType>;
 };
 
+////////////////////////////////////////////////////////////////////////////////
+// 6. fetchFeatures
+////////////////////////////////////////////////////////////////////////////////
+
+export type FetchFeaturesParameters = {
+  readonly options?:
+    | {
+        readonly auth?: Auth | undefined;
+      }
+    | undefined;
+};
+
+export type FetchFeaturesReturnType = { readonly relayerSupportsV3UserDecryptRoute: boolean };
+
+export type FetchFeaturesModuleFunction = {
+  fetchFeatures(
+    relayerClient: RelayerClientWithRuntime,
+    parameters: FetchFeaturesParameters,
+  ): Promise<FetchFeaturesReturnType>;
+};
+
 ////////////////////////////////////////////////////////////////////////////////
 // RelayerModule
 ////////////////////////////////////////////////////////////////////////////////
@@ -207,7 +230,8 @@ export type RelayerModule = Prettify<
     FetchCoprocessorSignaturesModuleFunction &
     FetchUserDecryptModuleFunction &
     FetchPublicDecryptModuleFunction &
-    FetchDelegatedUserDecryptModuleFunction
+    FetchDelegatedUserDecryptModuleFunction &
+    FetchFeaturesModuleFunction
 >;
 
 // Relayer is a base module. It does not take any runtime argument

package/core/relayerFeatures/ensureRelayerFeatures-p.ts

@@ -0,0 +1,84 @@
+import type { Auth } from '../types/auth.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import {
+  getRelayerFeatures,
+  getRelayerFeaturesPromise,
+  setRelayerFeatures,
+  setRelayerFeaturesPromise,
+} from '../runtime/CoreFhevm-p.js';
+import { resolveRelayerFeatures, type RelayerFeatures } from './resolveRelayerFeatures-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly chain: FhevmChain;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Resolves the client's relayer feature list **exactly once** and returns it, deduping concurrent
+ * callers onto a single in-flight fetch. The relayer-service sibling of `ensureFrozenContext`.
+ *
+ * ### Why this lives beside the frozen context, not inside it
+ *
+ * The frozen context is the *version basis*, resolved at `init()` from pure chain reads with **no
+ * inputs**. Relayer features are a *service capability*, fetched over HTTP and — critically —
+ * requiring an `Auth` that only arrives with a public action call, never at `init()`. So they
+ * cannot share the frozen context's resolution point, and they are resolved **lazily** here: at the
+ * first relayer action that carries an `Auth`.
+ *
+ * ### Auth is used only on the first resolution
+ *
+ * The result is Auth-independent (a deployment capability — see {@link RelayerFeatures}). The first
+ * caller's `auth` authorizes the one discovery request; the result is then pinned on the client and
+ * every later caller — regardless of its own `auth` — reads the same snapshot. This is what keeps a
+ * single per-client cache correct while avoiding dynamic drift.
+ *
+ * ### Lifecycle — promise while resolving, data afterwards (mirrors `ensureFrozenContext`)
+ *
+ * - Already stored on the client → return it immediately (no re-fetch).
+ * - Otherwise resolve once; on success store it (`setRelayerFeatures`) so later reads are
+ *   synchronous, and drop the transient promise.
+ * - The transient promise is cleared once resolution settles either way (`.finally`), so a first
+ *   attempt that fails — e.g. an auth-less call to an auth-required endpoint — does not poison later
+ *   auth'd calls: the next caller retries, and the first success wins.
+ *
+ * All state lives on the client instance (`getRelayerFeatures` / `getRelayerFeaturesPromise`), so it
+ * is scoped to the client's lifecycle and safe to use per-request in a server component.
+ *
+ * NOTE: this depends on the client-instance accessors `getRelayerFeatures` / `setRelayerFeatures` /
+ * `getRelayerFeaturesPromise` / `setRelayerFeaturesPromise` being added to `CoreFhevm-p.ts`, exactly
+ * parallel to the frozen-context slot (`#frozenContext` / `#frozenContextPromise` + their symbols).
+ * Wiring those into `CoreFhevm-p.ts` is intentionally out of scope of this folder.
+ *
+ * @internal
+ */
+export async function ensureRelayerFeatures(
+  fhevm: Context,
+  parameters: { readonly auth?: Auth | undefined },
+): Promise<RelayerFeatures> {
+  const existing = getRelayerFeatures(fhevm);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  let pending = getRelayerFeaturesPromise(fhevm);
+  if (pending === undefined) {
+    pending = resolveRelayerFeatures(fhevm, parameters)
+      .then((relayerFeatures) => {
+        setRelayerFeatures(fhevm, relayerFeatures);
+        return relayerFeatures;
+      })
+      .finally(() => {
+        setRelayerFeaturesPromise(fhevm, undefined);
+      });
+    setRelayerFeaturesPromise(fhevm, pending);
+  }
+
+  return pending;
+}

package/core/relayerFeatures/resolveRelayerFeatures-p.ts

@@ -0,0 +1,47 @@
+import type { Auth } from '../types/auth.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import type { FetchFeaturesReturnType } from '../modules/relayer/types.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly chain: FhevmChain;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * The relayer capability snapshot a client resolves **once** and then pins for its lifetime
+ * (currently just `relayerSupportsV3UserDecryptRoute`). It is the relayer-service analogue of the
+ * frozen context's version basis — but a *different category*: fetched over HTTP from the relayer,
+ * not derived from chain reads, so it lives beside {@link FhevmClientFrozenContext}, never inside it.
+ *
+ * **Auth-independent.** The feature list is a property of the relayer *deployment*, identical for
+ * every caller; an `Auth` (optional API key) is only needed to *reach* the discovery endpoint, and
+ * never changes the result. This is precisely what makes a single per-client resolution correct —
+ * were features per-caller, a per-client cache would be a correctness bug.
+ */
+export type RelayerFeatures = FetchFeaturesReturnType;
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Resolves the relayer feature list via the relayer module's `fetchFeatures`.
+ *
+ * Unlike `resolveFhevmClientFrozenContext` (pure chain reads, no inputs), this is a network call to
+ * the relayer whose discovery endpoint requires an `Auth`. The `auth` is threaded through purely to
+ * authorize the request; the returned {@link RelayerFeatures} does not depend on it (see the type
+ * doc above), so the caller is free to resolve once and reuse across callers with different auths.
+ *
+ * @internal
+ */
+export async function resolveRelayerFeatures(
+  fhevm: Context,
+  parameters: { readonly auth?: Auth | undefined },
+): Promise<RelayerFeatures> {
+  return await fhevm.runtime.relayer.fetchFeatures(fhevm, { options: { auth: parameters.auth } });
+}

package/core/runtime/CoreFhevm-p.ts

@@ -15,6 +15,7 @@ import type { FhevmRuntime, WithModule, WithModuleMap } from '../types/coreFhevm
 import type { FhevmClientFrozenContext } from '../types/fhevmClientFrozenContext-p.js';
 import type { TfheVersion } from '../../wasm/tfhe/TfheApi.js';
 import type { TkmsVersion } from '../../wasm/tkms/KmsLibApi.js';
+import type { RelayerFeatures } from '../relayerFeatures/resolveRelayerFeatures-p.js';
 import { InvalidTypeError } from '../base/errors/InvalidTypeError.js';
 import { verifyTrustedValue } from '../base/trustedValue.js';
 import { uid } from '../base/uid.js';
@@ -31,6 +32,10 @@ const GET_FROZEN_CONTEXT = Symbol('CoreFhevmHostClient.getFrozenContext');
 const SET_FROZEN_CONTEXT = Symbol('CoreFhevmHostClient.setFrozenContext');
 const GET_FROZEN_CONTEXT_PROMISE = Symbol('CoreFhevmHostClient.getFrozenContextPromise');
 const SET_FROZEN_CONTEXT_PROMISE = Symbol('CoreFhevmHostClient.setFrozenContextPromise');
+const GET_RELAYER_FEATURES = Symbol('CoreFhevmHostClient.getRelayerFeatures');
+const SET_RELAYER_FEATURES = Symbol('CoreFhevmHostClient.setRelayerFeatures');
+const GET_RELAYER_FEATURES_PROMISE = Symbol('CoreFhevmHostClient.getRelayerFeaturesPromise');
+const SET_RELAYER_FEATURES_PROMISE = Symbol('CoreFhevmHostClient.setRelayerFeaturesPromise');
 
 const UNRESOLVED_FHEVM_CONTEXT_MESSAGE = 'Fhevm context has not been resolved. Await client.ready before.';
 
@@ -38,6 +43,10 @@ type GetFrozenContextFn = () => FhevmClientFrozenContext | undefined;
 type SetFrozenContextFn = (frozenContext: FhevmClientFrozenContext) => void;
 type GetFrozenContextPromiseFn = () => Promise<FhevmClientFrozenContext> | undefined;
 type SetFrozenContextPromiseFn = (frozenContextPromise: Promise<FhevmClientFrozenContext> | undefined) => void;
+type GetRelayerFeaturesFn = () => RelayerFeatures | undefined;
+type SetRelayerFeaturesFn = (relayerFeatures: RelayerFeatures) => void;
+type GetRelayerFeaturesPromiseFn = () => Promise<RelayerFeatures> | undefined;
+type SetRelayerFeaturesPromiseFn = (relayerFeaturesPromise: Promise<RelayerFeatures> | undefined) => void;
 
 ////////////////////////////////////////////////////////////////////////////////
 // CoreFhevmImpl
@@ -52,6 +61,8 @@ class CoreFhevmImpl<
   readonly #uid: string;
   #frozenContext: FhevmClientFrozenContext | undefined;
   #frozenContextPromise: Promise<FhevmClientFrozenContext> | undefined;
+  #relayerFeatures: RelayerFeatures | undefined;
+  #relayerFeaturesPromise: Promise<RelayerFeatures> | undefined;
   readonly #runtime: runtime;
   readonly #trustedClient: TrustedClient<client> | undefined;
   readonly #chain: chain | undefined;
@@ -95,6 +106,8 @@ class CoreFhevmImpl<
     this.#uid = uid();
     this.#frozenContext = undefined;
     this.#frozenContextPromise = undefined;
+    this.#relayerFeatures = undefined;
+    this.#relayerFeaturesPromise = undefined;
     this.#trustedClient =
       parameters.client !== undefined ? createTrustedClient(parameters.client, ownerToken) : undefined;
     this.#chain = parameters.chain;
@@ -274,6 +287,38 @@ class CoreFhevmImpl<
         enumerable: false,
         writable: false,
       },
+      [GET_RELAYER_FEATURES]: {
+        value: (): RelayerFeatures | undefined => this.#relayerFeatures,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [SET_RELAYER_FEATURES]: {
+        // Plain overwrite: relayer features are resolved once (Auth-independent) and pinned.
+        value: (relayerFeatures: RelayerFeatures): void => {
+          this.#relayerFeatures = relayerFeatures;
+        },
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [GET_RELAYER_FEATURES_PROMISE]: {
+        value: (): Promise<RelayerFeatures> | undefined => this.#relayerFeaturesPromise,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
+      [SET_RELAYER_FEATURES_PROMISE]: {
+        // Transient: holds the single in-flight fetch so concurrent callers dedupe
+        // onto one promise; cleared once it settles (the resolved features are kept
+        // as data in #relayerFeatures).
+        value: (relayerFeaturesPromise: Promise<RelayerFeatures> | undefined): void => {
+          this.#relayerFeaturesPromise = relayerFeaturesPromise;
+        },
+        configurable: false,
+        enumerable: false,
+        writable: false,
+      },
       extend: {
         value: (actionsFactory: (client: typeof this) => FhevmExtension) =>
           extendCoreFhevm(this, actionsFactory, (fn) => {
@@ -676,4 +721,30 @@ export function getFrozenContextPromise(fhevm: unknown): Promise<FhevmClientFroz
   return f[GET_FROZEN_CONTEXT_PROMISE]();
 }
 
+// `fhevm` is typed `unknown` (like the getters): relayer features are resolved lazily from within
+// internal `context`-typed decrypt helpers that carry a minimal client shape, not a full `FhevmBase`.
+// `asCoreFhevm` validates at runtime that it is a genuine SDK client.
+export function setRelayerFeatures(fhevm: unknown, relayerFeatures: RelayerFeatures): void {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [SET_RELAYER_FEATURES]: SetRelayerFeaturesFn };
+  f[SET_RELAYER_FEATURES](relayerFeatures);
+}
+
+export function getRelayerFeatures(fhevm: unknown): RelayerFeatures | undefined {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [GET_RELAYER_FEATURES]: GetRelayerFeaturesFn };
+  return f[GET_RELAYER_FEATURES]();
+}
+
+export function setRelayerFeaturesPromise(
+  fhevm: unknown,
+  relayerFeaturesPromise: Promise<RelayerFeatures> | undefined,
+): void {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [SET_RELAYER_FEATURES_PROMISE]: SetRelayerFeaturesPromiseFn };
+  f[SET_RELAYER_FEATURES_PROMISE](relayerFeaturesPromise);
+}
+
+export function getRelayerFeaturesPromise(fhevm: unknown): Promise<RelayerFeatures> | undefined {
+  const f = asCoreFhevm(fhevm) as CoreFhevm & { readonly [GET_RELAYER_FEATURES_PROMISE]: GetRelayerFeaturesPromiseFn };
+  return f[GET_RELAYER_FEATURES_PROMISE]();
+}
+
 ////////////////////////////////////////////////////////////////////////////////

package/core/runtime/HyperWasmSolver-p.ts

@@ -1,7 +1,7 @@
 import type { ModuleVersionCompatibilityCheck, TfheVersion, TkmsVersion } from '../types/moduleVersions.js';
 import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
 import type { FhevmProtocolContext, ResolvedFhevmOptions, VersionResolution } from '../types/coreFhevmClient.js';
-import type { SemverRange } from '../base/semver.js';
+import type { SemverInterval, SemverRange } from '../base/semver.js';
 import type { Logger } from '../types/logger.js';
 import { semverComparatorImpliesRange } from '../base/semver.js';
 
@@ -22,7 +22,7 @@ type WasmModuleKey = keyof WasmModuleVersionByKey;
 type WasmModuleVersion<K extends WasmModuleKey> = WasmModuleVersionByKey[K];
 
 type WasmCompatibilityRule = {
-  readonly protocol: SemverRange;
+  readonly protocol: SemverInterval;
   readonly pubKeyCrs: SemverRange;
   readonly tfhe: {
     readonly canonical: TfheVersion;
@@ -69,7 +69,7 @@ const HYPER_WASM_SOLVER_CONFIG = {
   compatibilityRules: [
     {
       // protocol.version <= 0.12.x
-      protocol: { version: '0.13.0', comparator: 'lt' },
+      protocol: { upperBound: { version: '0.13.0', comparator: 'lt' } },
       // pubKeyCrs.version <= 1.5.x (ex: mainnet 1.4.0-alpha.3)
       pubKeyCrs: { version: '1.6.0', comparator: 'lt' },
       tfhe: {
@@ -82,8 +82,11 @@ const HYPER_WASM_SOLVER_CONFIG = {
       },
     },
     {
-      // protocol.version >= 0.13.0
-      protocol: { version: '0.13.0', comparator: 'ge' },
+      // 0.13.0 <= protocol.version < 0.14.0
+      protocol: {
+        lowerBound: { version: '0.13.0', comparator: 'ge' },
+        upperBound: { version: '0.14.0', comparator: 'lt' },
+      },
       // pubKeyCrs.version <= 1.5.x (ex: mainnet 1.4.0-alpha.3)
       pubKeyCrs: { version: '1.6.0', comparator: 'lt' },
       tfhe: {
@@ -96,8 +99,11 @@ const HYPER_WASM_SOLVER_CONFIG = {
       },
     },
     {
-      // protocol.version >= 0.13.0
-      protocol: { version: '0.13.0', comparator: 'ge' },
+      // 0.13.0 <= protocol.version < 0.14.0
+      protocol: {
+        lowerBound: { version: '0.13.0', comparator: 'ge' },
+        upperBound: { version: '0.14.0', comparator: 'lt' },
+      },
       // pubKeyCrs.version >= 1.6.0 (ex: localstack_v13)
       pubKeyCrs: { version: '1.6.0', comparator: 'ge' },
       tfhe: {
@@ -109,6 +115,34 @@ const HYPER_WASM_SOLVER_CONFIG = {
         compatible: ['0.13.10', '0.13.20-0'],
       },
     },
+    {
+      // protocol.version >= 0.14.0
+      protocol: { lowerBound: { version: '0.14.0', comparator: 'ge' } },
+      // pubKeyCrs.version <= 1.5.x (ex: mainnet 1.4.0-alpha.3)
+      pubKeyCrs: { version: '1.6.0', comparator: 'lt' },
+      tfhe: {
+        canonical: '1.6.2',
+        compatible: ['1.5.3', '1.6.2'],
+      },
+      kms: {
+        canonical: '0.14.0-1',
+        compatible: ['0.13.10', '0.13.20-0', '0.14.0-1'],
+      },
+    },
+    {
+      // protocol.version >= 0.14.0
+      protocol: { lowerBound: { version: '0.14.0', comparator: 'ge' } },
+      // pubKeyCrs.version >= 1.6.0 (ex: localstack_v13)
+      pubKeyCrs: { version: '1.6.0', comparator: 'ge' },
+      tfhe: {
+        canonical: '1.6.2',
+        compatible: ['1.6.2'],
+      },
+      kms: {
+        canonical: '0.14.0-1',
+        compatible: ['0.13.10', '0.13.20-0', '0.14.0-1'],
+      },
+    },
   ],
 } as const satisfies HyperWasmSolverConfig;
 
@@ -203,6 +237,7 @@ export function hyperWasmResolveTfheModuleVersion(
  *   `protocolVersion = eq:0.12.0, pubKeyCrsVersion = eq:1.5.4` -> `'0.13.10'`.
  *   `protocolVersion = eq:0.13.0, pubKeyCrsVersion = eq:1.4.0-alpha.3` -> `'0.13.20-0'`.
  *   `protocolVersion = eq:0.13.0, pubKeyCrsVersion = eq:1.6.1` -> `'0.13.20-0'`.
+ *   `protocolVersion = eq:0.14.0, pubKeyCrsVersion = eq:1.6.1` -> `'0.14.0-1'`.
  */
 export function hyperWasmResolveTkmsModuleVersion(
   parameters: ResolveParameters,
@@ -295,7 +330,7 @@ function _resolveWasmCompatibilityRule(
 function _findWasmCompatibilityRules(protocolContext: FhevmProtocolContext): WasmCompatibilityRule[] {
   return WASM_COMPATIBILITY_RULES.filter(
     (entry) =>
-      _versionResolutionImpliesRange(protocolContext.protocolVersion, entry.protocol) &&
+      _versionResolutionImpliesInterval(protocolContext.protocolVersion, entry.protocol) &&
       _versionResolutionImpliesRange(protocolContext.pubKeyCrsVersion, entry.pubKeyCrs),
   );
 }
@@ -304,6 +339,19 @@ function _versionResolutionImpliesRange(versionResolution: VersionResolution<str
   return semverComparatorImpliesRange(versionResolution.version, versionResolution.comparator, range);
 }
 
+function _versionResolutionImpliesInterval(
+  versionResolution: VersionResolution<string>,
+  interval: SemverInterval,
+): boolean {
+  if (interval.lowerBound !== undefined && !_versionResolutionImpliesRange(versionResolution, interval.lowerBound)) {
+    return false;
+  }
+  if (interval.upperBound !== undefined && !_versionResolutionImpliesRange(versionResolution, interval.upperBound)) {
+    return false;
+  }
+  return true;
+}
+
 function _resolveModuleVersionCompatibilityCheck(
   checkCompatibility: ModuleVersionCompatibilityCheck | undefined,
 ): ModuleVersionCompatibilityCheck {
@@ -348,6 +396,7 @@ function _handleModuleVersionCompatibilityPolicy(
   const resolvedCheckCompatibility = _resolveModuleVersionCompatibilityCheck(checkCompatibility);
   switch (resolvedCheckCompatibility) {
     case 'throw':
+      logger?.error?.(message, undefined);
       throw new Error(message);
     case 'warn':
       logger?.warn?.(message);

package/core/runtime/ProtocolVersionResolver-p.ts

@@ -23,12 +23,20 @@ export type ResolveProtocolContextParameters = ResolveProtocolVersionParameters;
 export async function resolveProtocolContext(
   parameters: ResolveProtocolContextParameters,
 ): Promise<FhevmProtocolContext> {
-  const aclAddress = addressToChecksummedAddress(asAddress(parameters.chain.fhevm.contracts.acl.address));
-  const aclVersion = await getHostContractVersion(parameters, { address: aclAddress });
+  try {
+    const aclAddress = addressToChecksummedAddress(asAddress(parameters.chain.fhevm.contracts.acl.address));
+    const aclVersion = await getHostContractVersion(parameters, { address: aclAddress });
 
-  assertIsHostContractVersionOf(aclVersion, 'ACL');
+    assertIsHostContractVersionOf(aclVersion, 'ACL');
 
-  return protocolContextFromAclVersion(parameters.chain, aclVersion);
+    return protocolContextFromAclVersion(parameters.chain, aclVersion);
+  } catch (e) {
+    parameters.runtime.config.logger?.error?.(
+      `Failed to resolve protocol context for chain ${parameters.chain.id} (ACL address=${parameters.chain.fhevm.contracts.acl.address}).`,
+      e,
+    );
+    throw e;
+  }
 }
 
 export async function resolveProtocolVersion(

package/core/runtime/initFhevmDecryptRuntime-p.ts

@@ -5,5 +5,5 @@ import { decryptModule } from '../modules/decrypt/module/index.js';
 export async function initFhevmDecryptRuntime(runtime: FhevmRuntime, ownerToken: symbol): Promise<void> {
   verifyFhevmRuntime(runtime, ownerToken);
   const decryptRuntime = runtime.extend(decryptModule);
-  await decryptRuntime.decrypt.initTkmsModule({ tkmsVersion: '0.13.20-0' });
+  await decryptRuntime.decrypt.initTkmsModule({ tkmsVersion: '0.14.0-1' });
 }

package/core/runtime/initFhevmRuntime-p.ts

@@ -7,7 +7,7 @@ export async function initFhevmRuntime(runtime: FhevmRuntime, ownerToken: symbol
   verifyFhevmRuntime(runtime, ownerToken);
   const fullRuntime = runtime.extend(decryptModule).extend(encryptModule);
   await Promise.all([
-    fullRuntime.decrypt.initTkmsModule({ tkmsVersion: '0.13.20-0' }),
+    fullRuntime.decrypt.initTkmsModule({ tkmsVersion: '0.14.0-1' }),
     fullRuntime.encrypt.initTfheModule({ tfheVersion: '1.6.2' }),
   ]);
 }

package/core/runtime/sdkProtocolApiVersion.ts

@@ -1,5 +1,5 @@
 /**
- * The FHEVM protocol API version this SDK is using (currently `0.13.0`).
+ * The FHEVM protocol API version this SDK is using (currently `0.14.0`).
  *
  * This is a static compile-time constant, distinct from the *dynamic*
  * on-chain protocol version reported by `resolveProtocolVersion()` /
@@ -7,16 +7,15 @@
  *
  * ## Supported protocol versions
  *
- * This SDK natively supports FHEVM protocol **v11, v12, and v13** — it knows
- * each of their on-chain APIs and encodes requests accordingly.
+ * This SDK natively supports FHEVM protocol **v11, v12, v13, and v14** — it
+ * knows each of their on-chain APIs and encodes requests accordingly.
  *
- * It is also **guaranteed to work on v14 and later**: the FHEVM protocol
+ * It is also **guaranteed to work on v15 and later**: the FHEVM protocol
  * guarantees backward compatibility, so a chain running a newer protocol
- * version still accepts the v13 API this SDK speaks. Against such a chain the
- * SDK keeps using its v13 API — it does not opt into any v14+ feature it does
- * not yet know about (for example, the v14 API introduces V2 decryption
- * permits, which this SDK does not emit).
+ * version still accepts the v14 API this SDK speaks. Against such a chain the
+ * SDK keeps using its v14 API — it does not opt into any v15+ feature it does
+ * not yet know about.
  */
 export const SDK_PROTOCOL_API_MAJOR_VERSION: number = 0;
-export const SDK_PROTOCOL_API_MINOR_VERSION: number = 13;
+export const SDK_PROTOCOL_API_MINOR_VERSION: number = 14;
 export const SDK_PROTOCOL_API_PATCH_VERSION: number = 0;

package/core/types/kms-p.ts

@@ -3,7 +3,6 @@ import type { Handle } from './encryptedTypes-p.js';
 import type { KmsEip712Domain } from './kms.js';
 import type { KmsSignersContext } from './kmsSignersContext.js';
 import type {
-  Bytes65Hex,
   Bytes65HexNo0x,
   BytesHex,
   BytesHexNo0x,
@@ -16,7 +15,8 @@ export interface KmsSigncryptedSharesMetadata {
   readonly kmsSignersContext: KmsSignersContext;
   readonly eip712ExtraData: BytesHex;
   readonly eip712Domain: KmsEip712Domain;
-  readonly eip712Signature: Bytes65Hex;
+  // Variable length: 65-byte EOA, ERC-1271 blob, or empty `0x`.
+  readonly eip712Signature: BytesHex;
   readonly eip712SignerAddress: ChecksummedAddress;
   readonly handles: readonly Handle[];
   readonly tkmsVersion: TkmsVersion;