@fhevm/sdk 1.1.0-alpha.3 → 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

@@ -37,7 +37,7 @@ import { sdkName, version } from '../../../_version.js';
 import { setAuth } from '../../../base/auth.js';
 import { InvalidPropertyError } from '../../../base/errors/InvalidPropertyError.js';
 import { assertNever } from '../../../base/errors/utils.js';
-import { formatFetchErrorMetaMessages } from '../../../base/fetch.js';
+import { formatFetchErrorMetaMessages, normalizeHeaders } from '../../../base/fetch.js';
 import { isNonEmptyString, safeJSONstringify } from '../../../base/string.js';
 import { isUint } from '../../../base/uint.js';
 import { RelayerAbortError } from '../../../errors/RelayerAbortError.js';
@@ -65,6 +65,7 @@ import {
   assertIsRelayerPostResponse202Queued,
 } from './guards/RelayerResponseQueued.js';
 import { assertIsRelayerUserDecryptSucceeded } from './guards/RelayerUserDecryptSucceeded.js';
+import { readErrorMessage } from './readErrorMessage.js';
 
 /*
     Actions:
@@ -139,6 +140,7 @@ export class RelayerAsyncRequest {
   private readonly _url: string;
   private readonly _payload: Record<string, unknown>;
   private readonly _fhevmAuth: Auth | undefined;
+  private readonly _customHeaders: Record<string, string> | undefined;
   private _retryAfterTimeoutPromiseFuncReject?: ((reason?: unknown) => void) | undefined;
   private readonly _onProgress?:
     | ((
@@ -206,6 +208,7 @@ export class RelayerAsyncRequest {
     this._payload = params.payload;
     this._debug = params.options?.debug === true;
     this._fhevmAuth = params.options?.auth;
+    this._customHeaders = normalizeHeaders(params.options?.headers);
     this._onProgress = params.options?.onProgress as typeof this._onProgress;
     this._state = {
       aborted: false,
@@ -488,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) {
@@ -562,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
@@ -722,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) {
@@ -959,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: {
@@ -1197,9 +1224,10 @@ export class RelayerAsyncRequest {
       {
         method: 'POST',
         headers: {
-          'Content-Type': 'application/json',
-          'ZAMA-SDK-VERSION': version,
-          'ZAMA-SDK-NAME': sdkName,
+          ...this._customHeaders,
+          'content-type': 'application/json',
+          'zama-sdk-version': version,
+          'zama-sdk-name': sdkName,
         },
         body: JSON.stringify(this._payload),
         ...(this._internalAbortSignal ? { signal: this._internalAbortSignal } : {}),
@@ -1265,19 +1293,18 @@ export class RelayerAsyncRequest {
 
     this._trace('_fetchGet', `jobId=${this.jobId}`);
 
-    // Do not include API key here!
-    // API key is only required on POST (by design).
-    // This is necessary for future caching on gateway.
-    // It will be implemented in future releases on (relayer).
-    // See relayer team.
-    const init: RequestInit = {
-      method: 'GET',
-      headers: {
-        'ZAMA-SDK-VERSION': version,
-        'ZAMA-SDK-NAME': sdkName,
-      },
-      ...(this._internalAbortSignal ? { signal: this._internalAbortSignal } : {}),
-    };
+    const init = setAuth(
+      {
+        method: 'GET',
+        headers: {
+          ...this._customHeaders,
+          'zama-sdk-version': version,
+          'zama-sdk-name': sdkName,
+        },
+        ...(this._internalAbortSignal ? { signal: this._internalAbortSignal } : {}),
+      } satisfies RequestInit,
+      this._fhevmAuth,
+    );
 
     this._state.fetching = true;
 
@@ -1599,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/fetchCoprocessorSignatures.ts

@@ -6,9 +6,9 @@ import type {
   RelayerClientWithRuntime,
 } from '../types.js';
 import { bytesToHexNo0x } from '../../../base/bytes.js';
-import { removeSuffix } from '../../../base/string.js';
 import { uintToHex0x } from '../../../base/uint.js';
 import { RelayerAsyncRequest } from './RelayerAsyncRequest.js';
+import { buildRelayerUrlString, validateRelayerBaseUrl } from './relayerUrl.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 // fetchCoprocessorSignatures
@@ -28,9 +28,13 @@ export async function fetchCoprocessorSignatures(
     userAddress: payload.zkProof.userAddress,
   };
 
+  const hasAuth: boolean = options?.auth !== undefined;
+  const relayerBaseUrl: URL = validateRelayerBaseUrl(relayerClient.chain.fhevm.relayerUrl, hasAuth);
+  const url = buildRelayerUrlString(relayerBaseUrl, 'v2/input-proof');
+
   const request = new RelayerAsyncRequest({
     relayerOperation: 'INPUT_PROOF',
-    url: `${removeSuffix(relayerClient.chain.fhevm.relayerUrl, '/')}/v2/input-proof`,
+    url,
     payload: inputProofPayload,
     options,
   });

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

@@ -6,8 +6,9 @@ import type {
   RelayerClientWithRuntime,
 } from '../types.js';
 import type { KmsSigncryptedShare } from '../../../types/kms-p.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';
 
 //////////////////////////////////////////////////////////////////////////////
 // fetchDelegatedUserDecrypt
@@ -45,9 +46,13 @@ export async function fetchDelegatedUserDecrypt(
     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/delegated-user-decrypt');
+
   const request = new RelayerAsyncRequest({
     relayerOperation: 'DELEGATED_USER_DECRYPT',
-    url: `${removeSuffix(relayerClient.chain.fhevm.relayerUrl, '/')}/v2/delegated-user-decrypt`,
+    url,
     payload: relayerPayload,
     options,
   });