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

package/core/modules/encrypt/module/init-p.ts

@@ -1,12 +1,16 @@
 import type { FhevmRuntime, FhevmRuntimeConfig } from '../../../types/coreFhevmRuntime.js';
-import type { GetTfheModuleInfoReturnType, TfheModuleInfo } from '../types.js';
+import type {
+  GetTfheModuleInfoParameters,
+  GetTfheModuleInfoReturnType,
+  InitTfheModuleParameters,
+  TfheModuleInfo,
+} from '../types.js';
 import type { TfheLibApi } from '../../../../wasm/tfhe/TfheApi.js';
 import type { TfheAssetMetadata, TfheVersion } from '../../../../wasm/tfhe/loadTfheLib.js';
 import { isomorphicCompileVerifiedWasm, isomorphicCompileWasmFromBase64 } from '../../../base/wasm.js';
 import { isBlobWorkerSupported, isBrowserLike } from '../../../base/isomorphicWorker.js';
 import { threads } from 'wasm-feature-detect';
 import { assertIsFhevmRuntime } from '../../../runtime/CoreFhevmRuntime-p.js';
-import { resolveTfheModuleVersion } from '../../../../wasm/tfheModuleVersion-p.js';
 // Pure JS file (not compiled by tsc) — provides cross-platform base URL
 // for resolving WASM paths. Uses import.meta.url in ESM, __filename in CJS.
 import { wasmBaseUrl } from '../../../../wasm/wasmBaseUrl.js';
@@ -23,7 +27,7 @@ const nodeDefaultLocateFile = (file: string): URL => {
 
 type TfheInitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
-type InitTfheModuleParameters = {
+type TfheLibInitAsyncParameters = {
   readonly module_or_path: TfheInitInput | Promise<TfheInitInput>;
   readonly memory?: WebAssembly.Memory;
   readonly thread_stack_size?: number;
@@ -62,29 +66,37 @@ type ResolvedTfheModuleConfig = {
   readonly supportsThreads: boolean | undefined;
 };
 
-let resolvedTfheModuleConfig: ResolvedTfheModuleConfig | undefined = undefined;
-let resolvingTfheModuleConfigPromise: Promise<ResolvedTfheModuleConfig> | undefined;
+const resolvedTfheModuleConfigByVersion = new Map<TfheVersion, ResolvedTfheModuleConfig>();
+const resolvingTfheModuleConfigPromiseByVersion = new Map<TfheVersion, Promise<ResolvedTfheModuleConfig>>();
 
 /**
  * @internal
- * Returns the existing resolved config, or resolves it from the runtime config.
+ * Returns the existing resolved config for a TFHE version, or resolves it from
+ * the runtime config.
  */
-async function _getOrResolveTfheModuleConfig(runtime: FhevmRuntime): Promise<ResolvedTfheModuleConfig> {
+async function _getOrResolveTfheModuleConfig(
+  runtime: FhevmRuntime,
+  tfheVersion: TfheVersion,
+): Promise<ResolvedTfheModuleConfig> {
+  const resolvedTfheModuleConfig = resolvedTfheModuleConfigByVersion.get(tfheVersion);
   if (resolvedTfheModuleConfig !== undefined) {
     return resolvedTfheModuleConfig;
   }
 
-  const version = resolveTfheModuleVersion(runtime.config);
-
-  resolvingTfheModuleConfigPromise ??= _resolveTfheModuleConfig(runtime.config, version)
-    .then((cfg) => {
-      resolvedTfheModuleConfig = cfg;
-      return cfg;
-    })
-    .catch((error: unknown) => {
-      resolvingTfheModuleConfigPromise = undefined;
-      throw error;
-    });
+  let resolvingTfheModuleConfigPromise = resolvingTfheModuleConfigPromiseByVersion.get(tfheVersion);
+  if (resolvingTfheModuleConfigPromise === undefined) {
+    resolvingTfheModuleConfigPromise = _resolveTfheModuleConfig(runtime.config, tfheVersion)
+      .then((cfg) => {
+        resolvedTfheModuleConfigByVersion.set(tfheVersion, cfg);
+        return cfg;
+      })
+      .catch((error: unknown) => {
+        resolvingTfheModuleConfigPromiseByVersion.delete(tfheVersion);
+        throw error;
+      });
+
+    resolvingTfheModuleConfigPromiseByVersion.set(tfheVersion, resolvingTfheModuleConfigPromise);
+  }
 
   return resolvingTfheModuleConfigPromise;
 }
@@ -187,30 +199,54 @@ async function _resolveTfheModuleConfig(
 // initTfheModule
 ////////////////////////////////////////////////////////////////////////////////
 
-let cachedTfheModulePromise: Promise<TfheLibApi> | undefined;
-let ownerUid: string | undefined = undefined;
+const ownerUidByVersion = new Map<TfheVersion, string>();
+const cachedTfheModulePromiseByVersion = new Map<TfheVersion, Promise<TfheLibApi>>();
+const moduleInfoByVersion = new Map<TfheVersion, TfheModuleInfo>();
+
+////////////////////////////////////////////////////////////////////////////////
+// Version-tagged native wrappers
+////////////////////////////////////////////////////////////////////////////////
+
+export const TFHE_VERSION_TAG: unique symbol = Symbol('TFHE.version');
+
+export type VersionTaggedTfheNative = {
+  readonly [TFHE_VERSION_TAG]: TfheVersion;
+};
+
+export function getTaggedTfheVersion(value: VersionTaggedTfheNative): TfheVersion {
+  return value[TFHE_VERSION_TAG];
+}
+
+export function assertTaggedTfheVersion(value: VersionTaggedTfheNative, expectedVersion: TfheVersion): void {
+  const actualVersion = getTaggedTfheVersion(value);
+  if (actualVersion !== expectedVersion) {
+    throw new Error(`Unexpected TFHE native wrapper version '${actualVersion}', expected '${expectedVersion}'.`);
+  }
+}
 
 /**
  * Initializes the TFHE module and returns the loaded lib bindings.
- * Idempotent: subsequent calls return the same cached lib instance.
+ * Idempotent per TFHE version: subsequent calls return the same cached lib instance.
  */
-export async function initTfheModule(runtime: FhevmRuntime): Promise<TfheLibApi> {
+export async function initTfheModule(runtime: FhevmRuntime, parameters: InitTfheModuleParameters): Promise<TfheLibApi> {
   assertIsFhevmRuntime(runtime, {});
 
+  const ownerUid = ownerUidByVersion.get(parameters.tfheVersion);
   if (ownerUid !== undefined && runtime.uid !== ownerUid) {
     throw new Error(
       `Encrypt WASM module is already owned by runtime '${ownerUid}' and cannot be shared with runtime '${runtime.uid}'`,
     );
   }
 
-  ownerUid = runtime.uid;
+  ownerUidByVersion.set(parameters.tfheVersion, runtime.uid);
 
   // Cache the whole initialization promise before the first await. Several
   // clients may call initTfheModule concurrently during startup; if the promise
   // were assigned after resolving the config, each caller could enter
   // _initTfheModule and try to start the global TFHE worker pool independently.
-  // The worker pool is process-wide and startWorkers() is intentionally
-  // one-shot, so every concurrent caller must await this same promise.
+  // Each TFHE version has its own JS glue module and worker pool, and each
+  // version's startWorkers() is intentionally one-shot, so concurrent callers
+  // for the same version must await the same promise.
   //
   // Retry is not supported:
   // -----------------------
@@ -220,20 +256,20 @@ export async function initTfheModule(runtime: FhevmRuntime): Promise<TfheLibApi>
   // original initialization error instead of retrying against half-initialized
   // state and producing secondary errors such as "Already started".
 
-  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+  let cachedTfheModulePromise = cachedTfheModulePromiseByVersion.get(parameters.tfheVersion);
   if (cachedTfheModulePromise === undefined) {
     cachedTfheModulePromise = (async () => {
       // resolve is async
-      const cfg = await _getOrResolveTfheModuleConfig(runtime);
+      const cfg = await _getOrResolveTfheModuleConfig(runtime, parameters.tfheVersion);
       return await _initTfheModule(cfg);
     })();
+
+    cachedTfheModulePromiseByVersion.set(parameters.tfheVersion, cachedTfheModulePromise);
   }
 
   return cachedTfheModulePromise;
 }
 
-let moduleInfo: TfheModuleInfo | undefined = undefined;
-
 async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibApi> {
   const tfheLib = await loadTfheLib(cfg.version);
 
@@ -248,7 +284,7 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
     wasmModule = await isomorphicCompileWasmFromBase64(tfheWasmBase64, tfheWasmBase64CompressionFormat);
   }
 
-  const input: InitTfheModuleParameters = { module_or_path: wasmModule };
+  const input: TfheLibInitAsyncParameters = { module_or_path: wasmModule };
 
   // 2. Load and instantiate the TFHE WASM binary
   await tfheLib.initAsync(input);
@@ -263,15 +299,24 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
   }
 
   const wasmInfo = tfheLib.getWasmInfo();
+  const memory = { byteLength: 0, pages: 0 };
+  if (wasmInfo.memory !== undefined) {
+    memory.byteLength = wasmInfo.memory.byteLength;
+    memory.pages = wasmInfo.memory.pages;
+  }
 
-  moduleInfo = Object.freeze({
-    wasmUrl: cfg.wasm.url ? new URL(cfg.wasm.url) : undefined,
-    version: wasmInfo.version,
-    name: wasmInfo.name,
-    workerUrl: cfg.worker.url ? new URL(cfg.worker.url) : undefined,
-    numberOfThreads: cfg.singleThread ? 0 : cfg.numberOfThreads,
-    threadsAvailable: cfg.supportsThreads,
-  });
+  moduleInfoByVersion.set(
+    cfg.version,
+    Object.freeze({
+      wasmUrl: cfg.wasm.url ? new URL(cfg.wasm.url) : undefined,
+      version: wasmInfo.version,
+      name: wasmInfo.name,
+      workerUrl: cfg.worker.url ? new URL(cfg.worker.url) : undefined,
+      numberOfThreads: cfg.singleThread ? 0 : cfg.numberOfThreads,
+      threadsAvailable: cfg.supportsThreads,
+      memory,
+    }),
+  );
 
   return tfheLib;
 }
@@ -280,6 +325,20 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
 // getTfheModuleInfo
 ////////////////////////////////////////////////////////////////////////////////
 
-export function getTfheModuleInfo(): GetTfheModuleInfoReturnType {
-  return moduleInfo;
+export async function getTfheModuleInfo(parameters: GetTfheModuleInfoParameters): Promise<GetTfheModuleInfoReturnType> {
+  const tfheLib = await loadTfheLib(parameters.tfheVersion);
+  const stored = moduleInfoByVersion.get(parameters.tfheVersion);
+  if (stored === undefined) {
+    throw new Error(`getTfheModuleInfo: no module info recorded for version "${parameters.tfheVersion}"`);
+  }
+  const memory: { byteLength: number; pages: number } = {
+    byteLength: stored.memory.byteLength,
+    pages: stored.memory.pages,
+  };
+  const wasmInfo = tfheLib.getWasmInfo();
+  if (wasmInfo.memory !== undefined) {
+    memory.byteLength = wasmInfo.memory.byteLength;
+    memory.pages = wasmInfo.memory.pages;
+  }
+  return { ...stored, memory };
 }

package/core/modules/encrypt/types.ts

@@ -10,6 +10,7 @@ import type {
 } from '../../types/fheEncryptionKey.js';
 import type { Prettify } from '../../types/utils.js';
 import type { FhevmRuntime } from '../../types/coreFhevmRuntime.js';
+import type { TfheVersion } from '../../../wasm/tfhe/TfheApi.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 //
@@ -39,8 +40,12 @@ Worker creation (how to spawn thread pool workers):
 // initTfheModuleFunction
 ////////////////////////////////////////////////////////////////////////////////
 
+export type InitTfheModuleParameters = {
+  readonly tfheVersion: TfheVersion;
+};
+
 export type InitTfheModuleFunction = {
-  initTfheModule(): Promise<void>;
+  initTfheModule(parameters: InitTfheModuleParameters): Promise<void>;
 };
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -73,6 +78,25 @@ export type TfheModuleInfo = {
    * - `false` — multi-threading was requested but unavailable; fell back to single-threaded.
    */
   readonly threadsAvailable: boolean | undefined;
+
+  /**
+   * Current size of the TFHE WASM linear memory.
+   * This is the size of the underlying `WebAssembly.Memory` buffer, not live heap usage.
+   */
+  readonly memory: {
+    /**
+     * Current memory buffer size in bytes.
+     */
+    readonly byteLength: number;
+    /**
+     * Current memory buffer size in 64 KiB WASM pages.
+     */
+    readonly pages: number;
+  };
+};
+
+export type GetTfheModuleInfoParameters = {
+  readonly tfheVersion: TfheVersion;
 };
 
 export type GetTfheModuleInfoReturnType = TfheModuleInfo | undefined;
@@ -82,7 +106,7 @@ export type GetTfheModuleInfoFunction = {
    * Returns {@link TfheModuleInfo} when the module is initialized,
    * or `undefined` if the module has not completed initialization.
    */
-  getTfheModuleInfo(): GetTfheModuleInfoReturnType;
+  getTfheModuleInfo(parameters: GetTfheModuleInfoParameters): Promise<GetTfheModuleInfoReturnType>;
 };
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -91,6 +115,7 @@ export type GetTfheModuleInfoFunction = {
 
 export type ParseTFHEProvenCompactCiphertextListParameters = {
   readonly ciphertextWithZkProof: Uint8Array | string;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type ParseTFHEProvenCompactCiphertextListReturnType = {
@@ -113,11 +138,13 @@ export type BuildWithProofPackedParameters = {
   readonly typedValues: TypedValue[];
   readonly metaData: Uint8Array;
   readonly extraData: BytesHex;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type BuildWithProofPackedReturnType = {
   readonly ciphertextWithZKProofBytes: Uint8Array;
   readonly extraData: BytesHex;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type BuildWithProofPackedModuleFunction = {
@@ -130,6 +157,7 @@ export type BuildWithProofPackedModuleFunction = {
 
 export type SerializeFheEncryptionKeyParameters = {
   readonly fheEncryptionKey: FheEncryptionKeyWasm;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type SerializeFheEncryptionKeyReturnType = FheEncryptionKeyBytes;
@@ -146,6 +174,7 @@ export type SerializeFheEncryptionKeyModuleFunction = {
 
 export type SerializeFheEncryptionPublicKeyParameters = {
   readonly publicKey: FheEncryptionPublicKey;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type SerializeFheEncryptionPublicKeyReturnType = FheEncryptionPublicKeyBytes;
@@ -162,6 +191,7 @@ export type SerializeFheEncryptionPublicKeyModuleFunction = {
 
 export type SerializeFheEncryptionCrsParameters = {
   readonly crs: FheEncryptionCrs;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type SerializeFheEncryptionCrsReturnType = FheEncryptionCrsBytes;
@@ -178,6 +208,7 @@ export type SerializeFheEncryptionCrsModuleFunction = {
 
 export type DeserializeFheEncryptionPublicKeyParameters = {
   readonly publicKeyBytes: FheEncryptionPublicKeyBytes;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type DeserializeFheEncryptionPublicKeyReturnType = FheEncryptionPublicKey;
@@ -194,6 +225,7 @@ export type DeserializeFheEncryptionPublicKeyModuleFunction = {
 
 export type DeserializeFheEncryptionCrsParameters = {
   readonly crsBytes: FheEncryptionCrsBytes;
+  readonly tfheVersion: TfheVersion;
 };
 
 export type DeserializeFheEncryptionCrsReturnType = FheEncryptionCrs;

package/core/modules/relayer/cleartext/fetchDelegatedUserDecrypt.ts

@@ -7,7 +7,7 @@ import type {
   RelayerClientWithRuntime,
 } from '../types.js';
 import { remove0x } from '../../../base/string.js';
-import { asUint32BigInt, parseUintBigIntString, randomUniqueUints } from '../../../base/uint.js';
+import { asUint32BigInt, tryParseUintBigIntString, randomUniqueUints } from '../../../base/uint.js';
 import { getTrustedClient } from '../../../runtime/CoreFhevm-p.js';
 import { userDecryptResultToKmsSigncryptedShares } from '../utils.js';
 import { getKmsSignersPrivateKeyMap } from './signers.js';
@@ -139,7 +139,7 @@ export async function fetchDelegatedUserDecrypt(
 ////////////////////////////////////////////////////////////////////////////////
 
 function _parseUintBigIntString(label: string, value: string): bigint {
-  const bn = parseUintBigIntString(value);
+  const bn = tryParseUintBigIntString(value);
   if (bn === undefined) {
     throw new Error(`${label} is not a valid uint string, got ${JSON.stringify(value)}`);
   }

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

@@ -3,7 +3,7 @@ import type { FetchUserDecryptResultItem } from '../../../types/relayer.js';
 import type { CleartextEthereumModule } from '../../ethereum/types-ct.js';
 import type { FetchUserDecryptParameters, FetchUserDecryptReturnType, RelayerClientWithRuntime } from '../types.js';
 import { remove0x } from '../../../base/string.js';
-import { asUint32BigInt, parseUintBigIntString, randomUniqueUints } from '../../../base/uint.js';
+import { asUint32BigInt, tryParseUintBigIntString, randomUniqueUints } from '../../../base/uint.js';
 import { getTrustedClient } from '../../../runtime/CoreFhevm-p.js';
 import { userDecryptResultToKmsSigncryptedShares } from '../utils.js';
 import { getKmsSignersPrivateKeyMap } from './signers.js';
@@ -133,7 +133,7 @@ export async function fetchUserDecrypt(
 ////////////////////////////////////////////////////////////////////////////////
 
 function _parseUintBigIntString(label: string, value: string): bigint {
-  const bn = parseUintBigIntString(value);
+  const bn = tryParseUintBigIntString(value);
   if (bn === undefined) {
     throw new Error(`${label} is not a valid uint string, got ${JSON.stringify(value)}`);
   }

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

@@ -65,6 +65,7 @@ import {
   assertIsRelayerPostResponse202Queued,
 } from './guards/RelayerResponseQueued.js';
 import { assertIsRelayerUserDecryptSucceeded } from './guards/RelayerUserDecryptSucceeded.js';
+import { readErrorMessage } from './readErrorMessage.js';
 
 /*
     Actions:
@@ -490,6 +491,15 @@ export class RelayerAsyncRequest {
 
       // At this stage: `terminated` is guaranteed to be `false`.
 
+      // 403 is not part of the typed relayer contract: it is emitted by an
+      // edge proxy (Cloudflare/Kong), typically on a missing/invalid
+      // `x-api-key`. Intercept it before the typed switch, read the JSON body,
+      // and surface the edge message instead of discarding it.
+      if (response.status === 403) {
+        const { message } = await readErrorMessage(response);
+        this._throwUnexpectedStatusError(403, message);
+      }
+
       const responseStatus: RelayerPostResponseStatus = response.status as RelayerPostResponseStatus;
 
       switch (responseStatus) {
@@ -564,7 +574,10 @@ export class RelayerAsyncRequest {
         // RelayerApiError401
         // falls through
         case 401: {
-          this._throwUnauthorizedError(responseStatus);
+          // Surface the message the origin (Kong/relayer) actually sent for a
+          // missing/invalid `x-api-key`, falling back to the canned string.
+          const { message } = await readErrorMessage(response);
+          this._throwUnauthorizedError(responseStatus, message);
         }
         // RelayerResponseFailed
         // RelayerApiError429
@@ -724,6 +737,15 @@ export class RelayerAsyncRequest {
 
       // At this stage: `terminated` is guaranteed to be `false`.
 
+      // 403 is not part of the typed relayer contract: it is emitted by an
+      // edge proxy (Cloudflare/Kong), typically on a missing/invalid
+      // `x-api-key`. Intercept it before the typed switch, read the JSON body,
+      // and surface the edge message instead of discarding it.
+      if (response.status === 403) {
+        const { message } = await readErrorMessage(response);
+        this._throwUnexpectedStatusError(403, message);
+      }
+
       const responseStatus: RelayerGetResponseStatus = response.status as RelayerGetResponseStatus;
 
       switch (responseStatus) {
@@ -961,7 +983,10 @@ export class RelayerAsyncRequest {
         }
         // falls through
         case 401: {
-          this._throwUnauthorizedError(responseStatus);
+          // Surface the message the origin (Kong/relayer) actually sent for a
+          // missing/invalid `x-api-key`, falling back to the canned string.
+          const { message } = await readErrorMessage(response);
+          this._throwUnauthorizedError(responseStatus, message);
         }
         // falls through
         case 404: {
@@ -1601,18 +1626,49 @@ export class RelayerAsyncRequest {
 
   /**
    * Throws an unauthorized error for 401 responses.
+   *
+   * The `message` surfaced from the response body (the relayer/edge JSON error)
+   * is used when present; otherwise the canned string is kept. The
+   * `'unauthorized'` label and error shape are preserved so downstream
+   * consumers reading `relayerApiError.message`/`.label` keep working.
+   *
+   * @param status - The 401 status.
+   * @param surfacedMessage - The message read from the response body, if any.
    * @throws {RelayerResponseApiError} Always throws with 'unauthorized' label.
    */
-  private _throwUnauthorizedError(status: Extract<RelayerFailureStatus, 401>): never {
+  private _throwUnauthorizedError(status: Extract<RelayerFailureStatus, 401>, surfacedMessage?: string): never {
     this._throwRelayerResponseApiError({
       status,
       relayerApiError: {
         label: 'unauthorized',
-        message: 'Unauthorized, missing or invalid Zama Fhevm API Key.',
+        message: surfacedMessage ?? 'Unauthorized, missing or invalid Zama Fhevm API Key.',
       },
     });
   }
 
+  /**
+   * Throws for an HTTP status that is not part of the typed relayer contract —
+   * e.g. a 403 emitted by an edge proxy (Cloudflare/Kong). The `message`
+   * surfaced from the JSON body is appended to the error when present.
+   *
+   * @param status - The unexpected HTTP status.
+   * @param surfacedMessage - The message read from the response body, if any.
+   * @throws {RelayerResponseStatusError} Always throws.
+   */
+  private _throwUnexpectedStatusError(status: number, surfacedMessage?: string): never {
+    throw new RelayerResponseStatusError({
+      fetchMethod: this._fetchMethod as unknown as RelayerFetchMethod,
+      status,
+      url: this._url,
+      ...(this._jobId !== undefined ? { jobId: this._jobId } : {}),
+      operation: this._relayerOperation,
+      elapsed: this._elapsed,
+      retryCount: this._retryCount,
+      state: { ...this._state },
+      ...(surfacedMessage !== undefined ? { responseMessage: surfacedMessage } : {}),
+    });
+  }
+
   // private _throwRelayerResponseApiErrorLoose(params: { status: number; bodyJson: Record<string, unknown> }): never {
   //   // body is considered ok if:
   //   // body.error exists

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

@@ -11,6 +11,7 @@ import { fetchWithRetry, normalizeHeaders } from '../../../base/fetch.js';
 import { sdkName, version } from '../../../_version.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';
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -59,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}`,
     });
   }
 

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 {};
+}