@dynamic-labs-wallet/forward-mpc-client 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -398,6 +398,63 @@ declare class ClientSessionEstablishFailedError extends ClientError {
     constructor(context?: Record<string, unknown>);
 }
 
+/**
+ * Error classification result from Forward MPC operations.
+ */
+type ForwardMpcErrorType = 'ATTESTATION_FAILURE' | 'FORWARD_MPC_TIMEOUT' | 'FORWARD_MPC_ERROR';
+/**
+ * Result of classifying a Forward MPC error.
+ */
+interface ForwardMpcErrorClassification {
+    /** The type of error encountered */
+    errorType: ForwardMpcErrorType;
+    /** Error code from ForwardMPCError, if available */
+    errorCode: string | undefined;
+    /** Error message */
+    errorMessage: string;
+    /** Attestation verification errors, if this is an attestation failure */
+    attestationErrors?: unknown[];
+    /** Whether the session was established before the error occurred */
+    sessionEstablished: boolean;
+    /** Whether this error should trigger a fallback to relay-based MPC */
+    shouldFallback: boolean;
+}
+/**
+ * Classifies a Forward MPC error and returns structured data for logging.
+ * Use this to standardize error handling across keygen, signing, and connect operations.
+ *
+ * @param error - The error to classify
+ * @returns Classification result with error details and recommended action
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await forwardMpcClient.sign(...);
+ * } catch (error) {
+ *   const classification = classifyForwardMpcError(error);
+ *   logger.warn(`Forward MPC ${operation} failed`, {
+ *     ...classification,
+ *     chainName,
+ *     environmentId,
+ *   });
+ *   if (classification.shouldFallback) {
+ *     // Fall through to relay-based MPC
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+declare function classifyForwardMpcError(error: unknown): ForwardMpcErrorClassification;
+/**
+ * Type guard to check if an error is a Forward MPC error that should be handled.
+ */
+declare function isForwardMpcError(error: unknown): error is ForwardMPCError;
+/**
+ * Type guard to check if an error is an attestation failure.
+ */
+declare function isAttestationError(error: unknown): error is SessionAttestationError;
+
 /**
  * Nitro Enclave Attestation Document Verifier
  * Uses Evervault's official WASM attestation bindings
@@ -430,4 +487,4 @@ declare class NitroAttestationVerifier implements AttestationVerifier {
     verify(attestationDocBase64: string, expectedChallenge: string, nonce: Uint8Array): Promise<AttestationVerificationResult>;
 }
 
-export { AttestationErrorCode, type AttestationVerificationConfig, type AttestationVerificationResult, type AttestationVerifier, ClientError, type ClientEvents, ClientSessionEstablishFailedError, ClientUnsupportedAlgorithmError, type ClientV2Events, ErrorCode, type ExternalLogger, ForwardMPCClient, type ForwardMPCClientOptions, ForwardMPCClientSingleton, ForwardMPCClientV2, type ForwardMPCClientV2Options, ForwardMPCError, ForwardMPCErrorType, type KeygenParams, type KeygenResult, NitroAttestationVerifier, type ReceiveKeyParams, type ReceiveKeyResult, SessionAttestationError, SessionDisposedError, SessionError, SessionHandshakeError, SessionHandshakeInvalidResponseError, SessionMessageParseError, SessionRemoteError, SessionRequestTimeoutError, SessionServerError, type SignMessageParams, type SignMessageResult, TransportConnectionError, TransportConnectionTimeoutError, TransportError, TransportNotConnectedError };
+export { AttestationErrorCode, type AttestationVerificationConfig, type AttestationVerificationResult, type AttestationVerifier, ClientError, type ClientEvents, ClientSessionEstablishFailedError, ClientUnsupportedAlgorithmError, type ClientV2Events, ErrorCode, type ExternalLogger, ForwardMPCClient, type ForwardMPCClientOptions, ForwardMPCClientSingleton, ForwardMPCClientV2, type ForwardMPCClientV2Options, ForwardMPCError, ForwardMPCErrorType, type ForwardMpcErrorClassification, type ForwardMpcErrorType, type KeygenParams, type KeygenResult, NitroAttestationVerifier, type ReceiveKeyParams, type ReceiveKeyResult, SessionAttestationError, SessionDisposedError, SessionError, SessionHandshakeError, SessionHandshakeInvalidResponseError, SessionMessageParseError, SessionRemoteError, SessionRequestTimeoutError, SessionServerError, type SignMessageParams, type SignMessageResult, TransportConnectionError, TransportConnectionTimeoutError, TransportError, TransportNotConnectedError, classifyForwardMpcError, isAttestationError, isForwardMpcError };

package/dist/index.d.ts

@@ -398,6 +398,63 @@ declare class ClientSessionEstablishFailedError extends ClientError {
     constructor(context?: Record<string, unknown>);
 }
 
+/**
+ * Error classification result from Forward MPC operations.
+ */
+type ForwardMpcErrorType = 'ATTESTATION_FAILURE' | 'FORWARD_MPC_TIMEOUT' | 'FORWARD_MPC_ERROR';
+/**
+ * Result of classifying a Forward MPC error.
+ */
+interface ForwardMpcErrorClassification {
+    /** The type of error encountered */
+    errorType: ForwardMpcErrorType;
+    /** Error code from ForwardMPCError, if available */
+    errorCode: string | undefined;
+    /** Error message */
+    errorMessage: string;
+    /** Attestation verification errors, if this is an attestation failure */
+    attestationErrors?: unknown[];
+    /** Whether the session was established before the error occurred */
+    sessionEstablished: boolean;
+    /** Whether this error should trigger a fallback to relay-based MPC */
+    shouldFallback: boolean;
+}
+/**
+ * Classifies a Forward MPC error and returns structured data for logging.
+ * Use this to standardize error handling across keygen, signing, and connect operations.
+ *
+ * @param error - The error to classify
+ * @returns Classification result with error details and recommended action
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await forwardMpcClient.sign(...);
+ * } catch (error) {
+ *   const classification = classifyForwardMpcError(error);
+ *   logger.warn(`Forward MPC ${operation} failed`, {
+ *     ...classification,
+ *     chainName,
+ *     environmentId,
+ *   });
+ *   if (classification.shouldFallback) {
+ *     // Fall through to relay-based MPC
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+declare function classifyForwardMpcError(error: unknown): ForwardMpcErrorClassification;
+/**
+ * Type guard to check if an error is a Forward MPC error that should be handled.
+ */
+declare function isForwardMpcError(error: unknown): error is ForwardMPCError;
+/**
+ * Type guard to check if an error is an attestation failure.
+ */
+declare function isAttestationError(error: unknown): error is SessionAttestationError;
+
 /**
  * Nitro Enclave Attestation Document Verifier
  * Uses Evervault's official WASM attestation bindings
@@ -430,4 +487,4 @@ declare class NitroAttestationVerifier implements AttestationVerifier {
     verify(attestationDocBase64: string, expectedChallenge: string, nonce: Uint8Array): Promise<AttestationVerificationResult>;
 }
 
-export { AttestationErrorCode, type AttestationVerificationConfig, type AttestationVerificationResult, type AttestationVerifier, ClientError, type ClientEvents, ClientSessionEstablishFailedError, ClientUnsupportedAlgorithmError, type ClientV2Events, ErrorCode, type ExternalLogger, ForwardMPCClient, type ForwardMPCClientOptions, ForwardMPCClientSingleton, ForwardMPCClientV2, type ForwardMPCClientV2Options, ForwardMPCError, ForwardMPCErrorType, type KeygenParams, type KeygenResult, NitroAttestationVerifier, type ReceiveKeyParams, type ReceiveKeyResult, SessionAttestationError, SessionDisposedError, SessionError, SessionHandshakeError, SessionHandshakeInvalidResponseError, SessionMessageParseError, SessionRemoteError, SessionRequestTimeoutError, SessionServerError, type SignMessageParams, type SignMessageResult, TransportConnectionError, TransportConnectionTimeoutError, TransportError, TransportNotConnectedError };
+export { AttestationErrorCode, type AttestationVerificationConfig, type AttestationVerificationResult, type AttestationVerifier, ClientError, type ClientEvents, ClientSessionEstablishFailedError, ClientUnsupportedAlgorithmError, type ClientV2Events, ErrorCode, type ExternalLogger, ForwardMPCClient, type ForwardMPCClientOptions, ForwardMPCClientSingleton, ForwardMPCClientV2, type ForwardMPCClientV2Options, ForwardMPCError, ForwardMPCErrorType, type ForwardMpcErrorClassification, type ForwardMpcErrorType, type KeygenParams, type KeygenResult, NitroAttestationVerifier, type ReceiveKeyParams, type ReceiveKeyResult, SessionAttestationError, SessionDisposedError, SessionError, SessionHandshakeError, SessionHandshakeInvalidResponseError, SessionMessageParseError, SessionRemoteError, SessionRequestTimeoutError, SessionServerError, type SignMessageParams, type SignMessageResult, TransportConnectionError, TransportConnectionTimeoutError, TransportError, TransportNotConnectedError, classifyForwardMpcError, isAttestationError, isForwardMpcError };

package/dist/index.js

@@ -1415,6 +1415,54 @@ var ForwardMPCClientSingleton = class extends ForwardMPCClientV2 {
   }
 };
 
-export { AttestationErrorCode, ClientError, ClientSessionEstablishFailedError, ClientUnsupportedAlgorithmError, ErrorCode, ForwardMPCClient, ForwardMPCClientSingleton, ForwardMPCClientV2, ForwardMPCError, ForwardMPCErrorType, NitroAttestationVerifier, SessionAttestationError, SessionDisposedError, SessionError, SessionHandshakeError, SessionHandshakeInvalidResponseError, SessionMessageParseError, SessionRemoteError, SessionRequestTimeoutError, SessionServerError, TransportConnectionError, TransportConnectionTimeoutError, TransportError, TransportNotConnectedError };
+// src/client-v2/error-classification.ts
+function classifyForwardMpcError(error) {
+  if (error instanceof SessionAttestationError) {
+    return {
+      errorType: "ATTESTATION_FAILURE",
+      errorCode: error.code,
+      errorMessage: error.message,
+      attestationErrors: error.context?.["errors"],
+      sessionEstablished: false,
+      shouldFallback: true
+    };
+  }
+  if (error instanceof SessionRequestTimeoutError) {
+    return {
+      errorType: "FORWARD_MPC_TIMEOUT",
+      errorCode: error.code,
+      errorMessage: error.message,
+      sessionEstablished: true,
+      shouldFallback: false
+    };
+  }
+  if (error instanceof ForwardMPCError) {
+    return {
+      errorType: "FORWARD_MPC_ERROR",
+      errorCode: error.code,
+      errorMessage: error.message,
+      sessionEstablished: true,
+      shouldFallback: false
+    };
+  }
+  return {
+    errorType: "FORWARD_MPC_ERROR",
+    errorCode: void 0,
+    errorMessage: error instanceof Error ? error.message : String(error),
+    sessionEstablished: false,
+    shouldFallback: false
+  };
+}
+__name(classifyForwardMpcError, "classifyForwardMpcError");
+function isForwardMpcError(error) {
+  return error instanceof ForwardMPCError;
+}
+__name(isForwardMpcError, "isForwardMpcError");
+function isAttestationError(error) {
+  return error instanceof SessionAttestationError;
+}
+__name(isAttestationError, "isAttestationError");
+
+export { AttestationErrorCode, ClientError, ClientSessionEstablishFailedError, ClientUnsupportedAlgorithmError, ErrorCode, ForwardMPCClient, ForwardMPCClientSingleton, ForwardMPCClientV2, ForwardMPCError, ForwardMPCErrorType, NitroAttestationVerifier, SessionAttestationError, SessionDisposedError, SessionError, SessionHandshakeError, SessionHandshakeInvalidResponseError, SessionMessageParseError, SessionRemoteError, SessionRequestTimeoutError, SessionServerError, TransportConnectionError, TransportConnectionTimeoutError, TransportError, TransportNotConnectedError, classifyForwardMpcError, isAttestationError, isForwardMpcError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map