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

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