@fhevm/sdk 0.13.2-1 → 0.14.0-12

package/core/kms/SignedDecryptionPermitV2-p.ts

@@ -1,20 +1,18 @@
 import type { SignedDecryptionPermit, SignedDecryptionPermitV2 } from '../types/signedDecryptionPermit.js';
 import type { KmsUserDecryptEip712V2 } from '../types/kms.js';
-import type { Bytes65Hex, BytesHex, ChecksummedAddress, Uint8Number } from '../types/primitives.js';
-import type { FhevmChain } from '../types/fhevmChain.js';
-import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { BytesHex, ChecksummedAddress, Uint8Number } from '../types/primitives.js';
 import type { KmsSignDecryptionPermitContext, KmsSignDecryptionPermitParameters } from './SignedDecryptionPermit-p.js';
 import type { KmsExtraData } from '../types/kms-p.js';
 import type { FhevmClientFrozenContext } from '../types/fhevmClientFrozenContext-p.js';
 import { assertRecordNonNullableProperty } from '../base/record.js';
-import { assertRecordBytes65HexProperty } from '../base/bytes.js';
+import { assertRecordBytesHexProperty } from '../base/bytes.js';
 import { addressToChecksummedAddress, assertIsAddress, assertRecordAddressProperty } from '../base/address.js';
 import { assertRecordStringProperty } from '../base/string.js';
 import { assertIsTransportKeyPair, type TransportKeyPair } from './TransportKeyPair-p.js';
 import { readCurrentKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
 import { kmsSignersContextToExtraData } from '../host-contracts/KmsSignersContext-p.js';
 import { assertIsKmsUserDecryptEip712V2, createKmsUserDecryptEip712V2 } from './createKmsUserDecryptEip712V2.js';
-import { verifyKmsUserDecryptEip712V2 } from '../utils-p/decrypt/verifyKmsUserDecryptEip712V2.js';
+import { verifyErc1271UserDecrypt } from '../utils-p/decrypt/verifyErc1271UserDecrypt-p.js';
 import { assert } from '../base/errors/InternalError.js';
 import { EXTRA_DATA_V2 } from './kmsExtraData-p.js';
 import { assertIsUintNumber } from '../base/uint.js';
@@ -30,7 +28,7 @@ const MAX_USER_DECRYPT_CONTRACT_ADDRESSES = 10 as Uint8Number;
 
 class SignedDecryptionPermitV2Impl implements SignedDecryptionPermitV2 {
   readonly #eip712: KmsUserDecryptEip712V2;
-  readonly #signature: Bytes65Hex;
+  readonly #signature: BytesHex;
   readonly #signerAddress: ChecksummedAddress;
   readonly #delegatorAddress: ChecksummedAddress | undefined;
 
@@ -38,7 +36,7 @@ class SignedDecryptionPermitV2Impl implements SignedDecryptionPermitV2 {
     privateToken: symbol,
     parameters: {
       readonly eip712: KmsUserDecryptEip712V2;
-      readonly signature: Bytes65Hex;
+      readonly signature: BytesHex;
       readonly signerAddress: ChecksummedAddress;
       readonly delegatorAddress?: ChecksummedAddress | undefined;
     },
@@ -56,7 +54,7 @@ class SignedDecryptionPermitV2Impl implements SignedDecryptionPermitV2 {
     return this.#eip712;
   }
 
-  public get signature(): Bytes65Hex {
+  public get signature(): BytesHex {
     return this.#signature;
   }
 
@@ -95,6 +93,44 @@ export function isSignedDecryptionPermitV2(value: unknown): value is SignedDecry
   return value instanceof SignedDecryptionPermitV2Impl;
 }
 
+////////////////////////////////////////////////////////////////////////////////
+// _createSignedDecryptionPermitV2
+////////////////////////////////////////////////////////////////////////////////
+
+async function _createSignedDecryptionPermitV2(
+  context: KmsSignDecryptionPermitContext,
+  parameters: {
+    readonly signerAddress: ChecksummedAddress;
+    readonly eip712: KmsUserDecryptEip712V2;
+    readonly signature: BytesHex;
+    readonly delegatorAddress?: ChecksummedAddress | undefined;
+  },
+): Promise<SignedDecryptionPermitV2> {
+  const { eip712, signature } = parameters;
+
+  // Enforced here (the choke point shared by signDecryptionPermitV2 and
+  // parseSignedDecryptionPermitV2). The message field is a validated uint256
+  // string, so `BigInt` is safe; a uint can only be non-positive when it is 0.
+  if (BigInt(eip712.message.durationSeconds) <= 0n) {
+    throw new RangeError(`durationSeconds must be positive, got ${eip712.message.durationSeconds}`);
+  }
+
+  if (eip712.message.allowedContracts.length > MAX_USER_DECRYPT_CONTRACT_ADDRESSES) {
+    throw Error(`allowedContracts max length of ${MAX_USER_DECRYPT_CONTRACT_ADDRESSES} exceeded`);
+  }
+
+  // Precautionary local check against `eip712.message.userAddress`; auto-detects
+  // EOA vs ERC-1271 (a normal EOA permit stays on the no-RPC fast path). The KMS
+  // remains authoritative — see `verifyErc1271UserDecrypt` for the full contract.
+  await verifyErc1271UserDecrypt(context, {
+    userAddress: eip712.message.userAddress,
+    eip712,
+    signature,
+  });
+
+  return new SignedDecryptionPermitV2Impl(PRIVATE_TOKEN, parameters);
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 // signDecryptionPermitV2
 ////////////////////////////////////////////////////////////////////////////////
@@ -153,7 +189,11 @@ export async function parseSignedDecryptionPermitV2(
   const options = {};
 
   assertRecordNonNullableProperty(permit, 'eip712', permitName, options);
-  assertRecordBytes65HexProperty(permit, 'signature', permitName, options);
+
+  // Accept a variable-length signature: a 65-byte EOA signature, a concatenated
+  // multisig ERC-1271 blob, or the empty `0x` pre-approved-hash flow. The verify
+  // step below auto-detects EOA vs ERC-1271 against `eip712.message.userAddress`.
+  assertRecordBytesHexProperty(permit, 'signature', permitName, options);
   assertRecordAddressProperty(permit, 'signerAddress', permitName, options);
 
   const eip712 = permit.eip712;
@@ -175,7 +215,11 @@ export async function parseSignedDecryptionPermitV2(
     );
   }
 
-  return await _createSignedDecryptionPermitV2(context, { signature: permit.signature, eip712, signerAddress });
+  return await _createSignedDecryptionPermitV2(context, {
+    signature: permit.signature,
+    eip712,
+    signerAddress,
+  });
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -269,37 +313,6 @@ export async function createUnsignedDecryptionPermitEip712V2(
   return eip712;
 }
 
-////////////////////////////////////////////////////////////////////////////////
-// _createSignedDecryptionPermitV2
-////////////////////////////////////////////////////////////////////////////////
-
-async function _createSignedDecryptionPermitV2(
-  context: { readonly chain: FhevmChain; readonly runtime: FhevmRuntime },
-  parameters: {
-    readonly signerAddress: ChecksummedAddress;
-    readonly eip712: KmsUserDecryptEip712V2;
-    readonly signature: Bytes65Hex;
-    readonly delegatorAddress?: ChecksummedAddress | undefined;
-  },
-): Promise<SignedDecryptionPermitV2> {
-  const { signerAddress, eip712, signature } = parameters;
-
-  // Enforced here (the choke point shared by signDecryptionPermitV2 and
-  // parseSignedDecryptionPermitV2). The message field is a validated uint256
-  // string, so `BigInt` is safe; a uint can only be non-positive when it is 0.
-  if (BigInt(eip712.message.durationSeconds) <= 0n) {
-    throw new RangeError(`durationSeconds must be positive, got ${eip712.message.durationSeconds}`);
-  }
-
-  if (eip712.message.allowedContracts.length > MAX_USER_DECRYPT_CONTRACT_ADDRESSES) {
-    throw Error(`allowedContracts max length of ${MAX_USER_DECRYPT_CONTRACT_ADDRESSES} exceeded`);
-  }
-
-  await verifyKmsUserDecryptEip712V2(context, { signer: signerAddress, message: eip712.message, signature });
-
-  return new SignedDecryptionPermitV2Impl(PRIVATE_TOKEN, parameters);
-}
-
 ////////////////////////////////////////////////////////////////////////////////
 // _assertKmsEip712V2DeadlineValidity
 ////////////////////////////////////////////////////////////////////////////////

package/core/kms/decryptValuesFromPairs.ts

@@ -9,7 +9,6 @@ import type { RelayerDelegatedUserDecryptOptions, RelayerUserDecryptOptions } fr
 import type { SignedDecryptionPermit } from '../types/signedDecryptionPermit.js';
 import type { TransportKeyPair } from './TransportKeyPair-p.js';
 import type { FhevmClientFrozenContext } from '../types/fhevmClientFrozenContext-p.js';
-import { SDK_PROTOCOL_API_MAJOR_VERSION, SDK_PROTOCOL_API_MINOR_VERSION } from '../runtime/sdkProtocolApiVersion.js';
 import { decryptKmsSigncryptedShares } from './decryptKmsSigncryptedShares-p.js';
 import { fetchKmsSigncryptedSharesV1 } from './fetchKmsSigncryptedSharesV1-p.js';
 import { fetchKmsSigncryptedSharesV2 } from './fetchKmsSigncryptedSharesV2-p.js';
@@ -47,40 +46,22 @@ export async function decryptValuesFromPairs(fhevm: Context, parameters: Paramet
 
   let kmsSigncryptedShares: KmsSigncryptedShares;
 
-  // Compile-time fast path for the protocol API version this SDK is using.
-  // At v0.13.x the SDK only ever produces/handles V1 permits, so the V2 fetch
-  // path is statically unreachable here. This guard is a foldable literal
-  // comparison, so bundlers evaluate it at build time and tree-shake
-  // fetchKmsSigncryptedSharesV2 (and its V2-only deps) out of the bundle.
-  // When the SDK adopts protocol API v0.14+, this branch stops folding to true
-  // and the permit-version routing below takes over.
-  if (SDK_PROTOCOL_API_MAJOR_VERSION === 0 && SDK_PROTOCOL_API_MINOR_VERSION <= 13) {
-    // A V2 permit cannot be served by this build: routing it through the V1
-    // path would silently reach the wrong relayer endpoint, so fail loudly.
-    if (parameters.signedPermit.version > 1) {
-      throw new Error(
-        `Unsupported permit version ${parameters.signedPermit.version}: this SDK uses protocol API v0.13.x, which only supports V1 decryption permits. V2 permits require an SDK using protocol API v0.14.0 or later.`,
-      );
-    }
+  // Route on the permit's OWN version, never the resolved protocol version. A signed
+  // permit is a self-describing artifact: its version fixes the EIP-712 message shape,
+  // so only the matching route can read it and reach the matching relayer endpoint.
+  // Keying off protocol version instead is indirect and breaks the moment the two
+  // diverge (e.g. a v1 permit used against a chain that now resolves to a newer
+  // protocol) — the artifact you are consuming is the source of truth, not the context.
+  //
+  //   v1: message.contractAddresses              -> fetchKmsSigncryptedSharesV1 -> POST v2/user-decrypt
+  //   v2: message.userAddress + allowedContracts -> fetchKmsSigncryptedSharesV2 -> POST v3/user-decrypt
+  if (parameters.signedPermit.version === 1) {
     kmsSigncryptedShares = await fetchKmsSigncryptedSharesV1(fhevm, parameters);
   } else {
-    // Route on the permit's OWN version, never the resolved protocol version. A signed
-    // permit is a self-describing artifact: its version fixes the EIP-712 message shape,
-    // so only the matching route can read it and reach the matching relayer endpoint.
-    // Keying off protocol version instead is indirect and breaks the moment the two
-    // diverge (e.g. a v1 permit used against a chain that now resolves to a newer
-    // protocol) — the artifact you are consuming is the source of truth, not the context.
-    //
-    //   v1: message.contractAddresses              -> fetchKmsSigncryptedSharesV1 -> POST v2/user-decrypt
-    //   v2: message.userAddress + allowedContracts -> fetchKmsSigncryptedSharesV2 -> POST v3/user-decrypt
-    if (parameters.signedPermit.version === 1) {
-      kmsSigncryptedShares = await fetchKmsSigncryptedSharesV1(fhevm, parameters);
-    } else {
-      kmsSigncryptedShares = await fetchKmsSigncryptedSharesV2(fhevm, {
-        ...parameters,
-        options: parameters.options as RelayerUserDecryptOptions | undefined,
-      });
-    }
+    kmsSigncryptedShares = await fetchKmsSigncryptedSharesV2(fhevm, {
+      ...parameters,
+      options: parameters.options as RelayerUserDecryptOptions | undefined,
+    });
   }
 
   // Using the `KmsSigncryptedShares` decrypt and reconstruct clear values

package/core/kms/fetchKmsSigncryptedSharesV2-p.ts

@@ -17,6 +17,7 @@ import { checkPersistAllowed } from '../host-contracts/checkPersistAllowed.js';
 import { checkDelegation } from '../host-contracts/checkDelegation.js';
 import { createKmsEip712Domain } from './createKmsEip712Domain.js';
 import { EXTRA_DATA_V2, createKmsExtraDataFromBytesHex } from './kmsExtraData-p.js';
+import { ensureRelayerFeatures } from '../relayerFeatures/ensureRelayerFeatures-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -48,6 +49,20 @@ type ReturnType = KmsSigncryptedShares;
 
 export async function fetchKmsSigncryptedSharesV2(context: Context, parameters: Parameters): Promise<ReturnType> {
   const { options, pairs, fhevmContext } = parameters;
+
+  // The v3 / unified user-decrypt route only exists on relayers that advertise it. Guard here — not
+  // only at callers — so any direct caller of this V2 path is protected too. Resolved once per client
+  // (cached), using the same effective auth this function uses for the actual relayer request.
+  const features = await ensureRelayerFeatures(context, {
+    auth: options?.auth ?? context.runtime.config.auth,
+  });
+  if (!features.relayerSupportsV3UserDecryptRoute) {
+    throw new Error(
+      'The relayer does not support unified (V2) decryption permits. Call `canUseUnifiedDecryptionPermit` up ' +
+        'front to check support, and use a legacy (V1) decryption permit against this relayer instead.',
+    );
+  }
+
   const signedPermit = parameters.signedPermit as SignedDecryptionPermitV2;
 
   const tkmsVersion = fhevmContext.tkmsVersion;

package/core/modules/decrypt/module/api-p.ts

@@ -31,7 +31,7 @@ import { uint32ToBytes32 } from '../../../base/uint.js';
 import { createClearValue } from '../../../handle/ClearValue.js';
 import { bytesToClearValueType } from '../../../handle/FheType.js';
 import { remove0x } from '../../../base/string.js';
-import { bytesToHexLarge } from '../../../base/bytes.js';
+import { bytesToHexLarge, isBytes65Hex } from '../../../base/bytes.js';
 import { WasmScope } from '../../../base/wasmScope.js';
 import { initTkmsModule } from './init-p.js';
 import { getMetadata, getShares } from '../../../kms/KmsSigncryptedShares-p.js';
@@ -379,8 +379,10 @@ export async function decryptAndReconstruct(
     );
 
     const requestWasmArg = {
-      // unused according to KMS documentation
-      signature: remove0x(metadata.eip712Signature),
+      // The tkms request parser accepts only a strict 65-byte ECDSA signature
+      // here and documents the field as optional — ERC-1271 permits (multisig
+      // blobs, empty approved-hash signatures) must omit it.
+      signature: isBytes65Hex(metadata.eip712Signature) ? remove0x(metadata.eip712Signature) : undefined,
       client_address: clientAddress,
       enc_key: remove0x(publicEncKeyMlKem512WasmBytesHex),
       ciphertext_handles: metadata.handles.map((h) => h.bytes32HexNo0x),

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

@@ -247,7 +247,12 @@ async function _initTkmsModule(cfg: ResolvedTkmsModuleConfig): Promise<KmsLibApi
 
   const input: TkmsLibInitAsyncParameters = { module_or_path: wasmModule };
 
-  await kmsLib.initAsync(input);
+  try {
+    await kmsLib.initAsync(input);
+  } catch (e) {
+    cfg.logger?.error?.(`Failed to instantiate tkms WASM module (version=${cfg.version}).`, e);
+    throw e;
+  }
 
   // Note: init_panic_hook is not exposed by kms_lib
   const wasmInfo = kmsLib.getWasmInfo();

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

@@ -597,7 +597,12 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
   const input: TfheLibInitAsyncParameters = { module_or_path: wasmModule };
 
   // 2. Load and instantiate the TFHE WASM binary
-  await tfheLib.initAsync(input);
+  try {
+    await tfheLib.initAsync(input);
+  } catch (e) {
+    cfg.logger?.error?.(`Failed to instantiate tfhe WASM module (version=${cfg.version}).`, e);
+    throw e;
+  }
 
   // 3. Route WASM panics to console.error instead of silently aborting
   tfheLib.init_panic_hook();
@@ -605,7 +610,15 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
   // 4. Spawn Web Workers for parallel FHE operations (skipped when single-threaded)
   if (!cfg.singleThread) {
     cfg.logger?.debug?.(`initThreadPool(${cfg.numberOfThreads})`);
-    await tfheLib.initThreadPool(cfg.numberOfThreads);
+    try {
+      await tfheLib.initThreadPool(cfg.numberOfThreads);
+    } catch (e) {
+      cfg.logger?.error?.(
+        `Failed to initialize tfhe WASM thread pool (numberOfThreads=${cfg.numberOfThreads}, version=${cfg.version}).`,
+        e,
+      );
+      throw e;
+    }
   }
 
   const wasmInfo = tfheLib.getWasmInfo();

package/core/modules/ethereum/types.ts

@@ -1,5 +1,5 @@
 import type { TrustedValue } from '../../base/trustedValue.js';
-import type { Bytes65Hex, BytesHex, ChecksummedAddress, Uint256 } from '../../types/primitives.js';
+import type { Bytes32Hex, Bytes65Hex, BytesHex, ChecksummedAddress, Uint256 } from '../../types/primitives.js';
 import type { Prettify } from '../../types/utils.js';
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -37,6 +37,58 @@ export type RecoverTypedDataAddressModuleFunction = {
   recoverTypedDataAddress(parameters: RecoverTypedDataAddressParameters): Promise<RecoverTypedDataAddressReturnType>;
 };
 
+////////////////////////////////////////////////////////////////////////////////
+// hashTypedData
+////////////////////////////////////////////////////////////////////////////////
+
+export type HashTypedDataParameters = Readonly<{
+  domain: RecoverTypedDataAddressParameters['domain'];
+  types: Record<string, Array<{ name: string; type: string }>>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}>;
+
+/** The EIP-712 digest (`bytes32`) that a signer signs. */
+export type HashTypedDataReturnType = Bytes32Hex;
+
+export type HashTypedDataModuleFunction = {
+  hashTypedData(parameters: HashTypedDataParameters): HashTypedDataReturnType;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// call (raw eth_call / STATICCALL)
+////////////////////////////////////////////////////////////////////////////////
+
+export type EthCallParameters = Readonly<{
+  readonly to: ChecksummedAddress;
+  readonly data: BytesHex;
+  /** Optional gas cap for the call. */
+  readonly gas?: bigint | undefined;
+}>;
+
+/**
+ * Outcome of a raw `eth_call`.
+ *
+ * - `{ success: true }` — the node returned (possibly empty) returndata. A no-code
+ *   address yields empty `0x` data, mirroring EVM `STATICCALL` semantics.
+ * - `{ success: false }` — the call reverted cleanly at the EVM level. This is a
+ *   *definitive* on-chain rejection (distinct from a transport-level failure,
+ *   which the adapter rethrows so the caller can degrade gracefully).
+ */
+export type EthCallResult =
+  | { readonly success: true; readonly data: BytesHex }
+  | { readonly success: false; readonly reason: string };
+
+export type CallModuleFunction = {
+  /**
+   * Performs a raw `eth_call` (STATICCALL semantics) and returns the raw
+   * returndata. Reverts are surfaced as `{ success: false }`; transport-level
+   * errors (network, timeout, rate limit, …) are thrown so callers can decide
+   * whether to fail or degrade.
+   */
+  call(hostPublicClient: TrustedClient, parameters: EthCallParameters): Promise<EthCallResult>;
+};
+
 ////////////////////////////////////////////////////////////////////////////////
 // signTypedData
 ////////////////////////////////////////////////////////////////////////////////
@@ -139,8 +191,10 @@ export type ReadContractModuleFunction = {
 
 export type EthereumModule = Prettify<
   RecoverTypedDataAddressModuleFunction &
+    HashTypedDataModuleFunction &
     SignTypedDataModuleFunction &
     ReadContractModuleFunction &
+    CallModuleFunction &
     EncodeModuleFunction &
     EncodePackedModuleFunction &
     DecodeModuleFunction &

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

@@ -1,9 +1,12 @@
 import type { UintNumber } from '../../../types/primitives.js';
 import type {
+  FetchFeaturesParameters,
+  FetchFeaturesReturnType,
   FetchFheEncryptionKeyBytesParameters,
   FetchFheEncryptionKeyBytesReturnType,
   FetchFheEncryptionKeySourceParameters,
   RelayerClient,
+  RelayerClientWithRuntime,
   RelayerModuleFactory,
 } from '../types.js';
 import { createDeadbeefBytes } from '../../../base/bytes.js';
@@ -49,6 +52,14 @@ export const relayerModule: RelayerModuleFactory = () => {
       fetchPublicDecrypt,
       fetchUserDecrypt,
       fetchDelegatedUserDecrypt,
+      fetchFeatures: (
+        _relayerClient: RelayerClientWithRuntime,
+        _parameters: FetchFeaturesParameters,
+      ): Promise<FetchFeaturesReturnType> => {
+        return Promise.resolve({
+          relayerSupportsV3UserDecryptRoute: true,
+        });
+      },
     }),
   });
 };

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

@@ -1,4 +1,5 @@
 import type { Auth } from '../../../types/auth.js';
+import type { Logger } from '../../../types/logger.js';
 import type {
   RelayerApiError,
   RelayerAsyncRequestState,
@@ -110,6 +111,7 @@ type RelayerAsyncRequestParams = {
   payload: Record<string, unknown>;
   timeoutInSeconds?: number | undefined;
   throwErrorIfNoRetryAfter?: boolean | undefined;
+  logger?: Logger | undefined;
   options?:
     | RelayerInputProofOptions
     | RelayerUserDecryptOptions
@@ -120,6 +122,7 @@ type RelayerAsyncRequestParams = {
 
 export class RelayerAsyncRequest {
   private readonly _debug: boolean;
+  private readonly _logger: Logger | undefined;
   private _fetchMethod: 'GET' | 'POST' | undefined;
   private _elapsed: number;
   private _jobId: string | undefined;
@@ -207,6 +210,7 @@ export class RelayerAsyncRequest {
     this._url = params.url;
     this._payload = params.payload;
     this._debug = params.options?.debug === true;
+    this._logger = params.logger;
     this._fhevmAuth = params.options?.auth;
     this._customHeaders = normalizeHeaders(params.options?.headers);
     this._onProgress = params.options?.onProgress as typeof this._onProgress;
@@ -600,6 +604,10 @@ export class RelayerAsyncRequest {
 
           const retryAfterMs = this._getRetryAfterHeaderValueInMs(response);
 
+          this._logger?.warn?.(
+            `[RelayerAsyncRequest] Throttled (429) on ${this._url} (operation=${this._relayerOperation}, retryCount=${this._retryCount}). Retrying in ${retryAfterMs}ms.`,
+          );
+
           // Async onProgress callback
           this._postAsyncOnProgressCallback({
             type: 'throttled',
@@ -678,6 +686,10 @@ export class RelayerAsyncRequest {
         default: {
           // Use TS compiler + `never` to guarantee the switch integrity
           const throwUnsupportedStatus = (unsupportedStatus: never): never => {
+            this._logger?.error?.(
+              `[RelayerAsyncRequest] Unsupported POST response status ${String(unsupportedStatus)} on ${this._url} (operation=${this._relayerOperation})`,
+              undefined,
+            );
             throw new RelayerResponseStatusError({
               fetchMethod: 'POST',
               status: unsupportedStatus,
@@ -1059,6 +1071,10 @@ export class RelayerAsyncRequest {
         default: {
           // Use TS compiler + `never` to guarantee the switch integrity
           const throwUnsupportedStatus = (unsupportedStatus: never): never => {
+            this._logger?.error?.(
+              `[RelayerAsyncRequest] Unsupported GET response status ${String(unsupportedStatus)} on ${this._url} (operation=${this._relayerOperation}, jobId=${this.jobId})`,
+              undefined,
+            );
             throw new RelayerResponseStatusError({
               fetchMethod: 'GET',
               status: unsupportedStatus,
@@ -1191,6 +1207,10 @@ export class RelayerAsyncRequest {
         throw fetchError;
       }
 
+      this._logger?.warn?.(
+        `[RelayerAsyncRequest] Fetch to ${this._url} failed (attempt ${attempts}/${this._fetchRetries}, operation=${this._relayerOperation}): ${formatFetchErrorMetaMessages(fetchError).join('. ')}. Retrying.`,
+      );
+
       // Wait before retry using state-machine-aware timeout
       // This allows cancellation to interrupt the delay
       // Skip incrementing _retryCount since fetch retries are separate from polling retries
@@ -1391,6 +1411,10 @@ export class RelayerAsyncRequest {
       this._assert(!this._state.canceled, '!this._state.canceled');
     }
 
+    this._logger?.warn?.(
+      `[RelayerAsyncRequest] Request aborted on ${this._url} (reason=${String(signal.reason)}, operation=${this._relayerOperation}, jobId=${this._jobId})`,
+    );
+
     this._postAsyncOnProgressCallback({
       type: 'abort',
       url: this._url,
@@ -1558,6 +1582,11 @@ export class RelayerAsyncRequest {
 
     this._state.timeout = true;
 
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] Request timed out on ${this._url} (operation=${this._relayerOperation}, jobId=${this._jobId}, retryCount=${this._retryCount}, timeoutMs=${this._requestMaxDurationInMs})`,
+      undefined,
+    );
+
     this._postAsyncOnProgressCallback({
       type: 'timeout',
       url: this._url,
@@ -1656,6 +1685,10 @@ export class RelayerAsyncRequest {
    * @throws {RelayerResponseStatusError} Always throws.
    */
   private _throwUnexpectedStatusError(status: number, surfacedMessage?: string): never {
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] Unexpected HTTP status ${status} on ${this._url} (operation=${this._relayerOperation}, jobId=${this._jobId})${surfacedMessage !== undefined ? `: ${surfacedMessage}` : ''}`,
+      undefined,
+    );
     throw new RelayerResponseStatusError({
       fetchMethod: this._fetchMethod as unknown as RelayerFetchMethod,
       status,
@@ -1694,6 +1727,11 @@ export class RelayerAsyncRequest {
     // Clone
     const clonedRelayerApiError = JSON.parse(JSON.stringify(params.relayerApiError)) as RelayerApiError;
 
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] Relayer API error on ${this._url} (status=${params.status}, operation=${this._relayerOperation}, jobId=${this._jobId}, retryCount=${this._retryCount}): label=${params.relayerApiError.label}, message=${params.relayerApiError.message}`,
+      undefined,
+    );
+
     const args: RelayerProgressFailed<RelayerPostOperation> = {
       type: 'failed',
       url: this._url,
@@ -1743,6 +1781,10 @@ export class RelayerAsyncRequest {
    * @throws {RelayerRequestInternalError}
    */
   private _throwInternalError(message: string): never {
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] Internal error on ${this._url} (operation=${this._relayerOperation}): ${message}`,
+      undefined,
+    );
     throw new RelayerRequestInternalError({
       operation: this._relayerOperation,
       url: this._url,
@@ -1758,6 +1800,10 @@ export class RelayerAsyncRequest {
    */
   private _throwMaxRetryError(params: { fetchMethod: 'GET' | 'POST' }): never {
     const elapsed = this._jobIdTimestamp !== undefined ? Date.now() - this._jobIdTimestamp : 0;
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] Max retry count exceeded on ${this._url} (${params.fetchMethod}, operation=${this._relayerOperation}, jobId=${this._jobId}, retryCount=${this._retryCount}, elapsed=${elapsed}ms).`,
+      undefined,
+    );
     throw new RelayerMaxRetryError({
       operation: this._relayerOperation,
       url: this._url,
@@ -1778,6 +1824,10 @@ export class RelayerAsyncRequest {
     cause: InvalidPropertyError;
     bodyJson: string;
   }): never {
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] Unexpected response body on ${this._url} (status=${params.status}, operation=${this._relayerOperation}, jobId=${this._jobId}): ${params.bodyJson}`,
+      params.cause,
+    );
     throw new RelayerResponseInvalidBodyError({
       ...params,
       fetchMethod: this._fetchMethod as unknown as RelayerFetchMethod,
@@ -1795,6 +1845,10 @@ export class RelayerAsyncRequest {
    * @throws {RelayerFetchError} Always throws.
    */
   private _throwFetchError(params: { message: string; cause: unknown }): never {
+    this._logger?.error?.(
+      `[RelayerAsyncRequest] ${params.message} (url=${this._url}, operation=${this._relayerOperation}, jobId=${this._jobId}, retryCount=${this._retryCount})`,
+      params.cause,
+    );
     throw new RelayerFetchError({
       ...params,
       elapsed: this._elapsed,
@@ -1839,5 +1893,6 @@ export class RelayerAsyncRequest {
     if (this._debug) {
       console.log(`[RelayerAsyncRequest]:${functionName}: ${message}`);
     }
+    this._logger?.debug?.(`[RelayerAsyncRequest]:${functionName}: ${message}`);
   }
 }

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

@@ -37,6 +37,7 @@ export async function fetchCoprocessorSignatures(
     url,
     payload: inputProofPayload,
     options,
+    logger: relayerClient.runtime.config.logger,
   });
 
   const result = (await request.run()) as FetchInputProofResult;

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

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