@0xmonaco/core 0.7.7 → 0.7.9

package/dist/errors/errors.js

@@ -0,0 +1,815 @@
+/**
+ * Monaco SDK Error Types
+ *
+ * Standardized error classes for SDK operations with built-in sensitive data sanitization.
+ * All error classes inherit from MonacoCoreError and provide structured error information
+ * with automatic suggestions for common failure scenarios.
+ *
+ * @module errors
+ */
+import { StatusCodes } from "http-status-codes";
+/**
+ * Sensitive field names that should be redacted in error logs.
+ *
+ * When errors are serialized (via toJSON()) and sent to external monitoring services
+ * like Sentry, Datadog, or CloudWatch, these fields will be replaced with "[REDACTED]"
+ * to prevent exposure of sensitive information.
+ *
+ * Categories:
+ * - Authentication & Authorization: tokens, API keys, secrets
+ * - User PII: emails, phone numbers, addresses
+ * - Security credentials: private keys, mnemonics, signatures
+ * - Session data: cookies, session IDs
+ *
+ * @constant
+ */
+const SENSITIVE_FIELDS = [
+    // Authentication & Authorization
+    "token",
+    "accessToken",
+    "access_token",
+    "refreshToken",
+    "refresh_token",
+    "authToken",
+    "auth_token",
+    "bearerToken",
+    "bearer_token",
+    "jwtToken",
+    "jwt_token",
+    "apiKey",
+    "api_key",
+    "apikey",
+    "clientSecret",
+    "client_secret",
+    "clientId",
+    "client_id",
+    "secret",
+    "password",
+    "authorization",
+    "bearer",
+    "auth",
+    "credentials",
+    "credential",
+    // User PII
+    "email",
+    "phone",
+    "phoneNumber",
+    "phone_number",
+    "ssn",
+    "socialSecurity",
+    "social_security",
+    "address",
+    "passport",
+    "passportNumber",
+    "passport_number",
+    "driversLicense",
+    "drivers_license",
+    // Financial
+    "cardNumber",
+    "card_number",
+    "creditCard",
+    "credit_card",
+    "cvv",
+    "pin",
+    // Security & Crypto
+    "signature",
+    "privateKey",
+    "private_key",
+    "publicKey",
+    "public_key",
+    "mnemonic",
+    "seed",
+    "salt",
+    "hash",
+    "certificate",
+    "cert",
+    "fingerprint",
+    // Session & Cookies
+    "cookie",
+    "session",
+    "sessionId",
+    "session_id",
+    "sessionToken",
+    "session_token",
+    // Network & Device
+    "ipAddress",
+    "ip_address",
+    "deviceId",
+    "device_id",
+    "userId",
+    "user_id",
+    "accountId",
+    "account_id",
+];
+/**
+ * Sanitize data by redacting sensitive fields and limiting size.
+ *
+ * Recursively processes data structures to protect sensitive information while
+ * preserving debugging utility. Used by error classes when serializing to JSON.
+ *
+ * **Protections applied:**
+ * - Redacts sensitive fields (tokens, passwords, PII, etc.)
+ * - Truncates long strings (500 chars for object values, 1000 for standalone)
+ * - Limits array size (10 items max, then "... N more items")
+ * - Prevents infinite recursion (max depth: 5)
+ *
+ * **Examples:**
+ * ```typescript
+ * sanitizeData({ token: "secret", name: "John" })
+ * // → { token: "[REDACTED]", name: "John" }
+ *
+ * sanitizeData(["a".repeat(1000)])
+ * // → ["aaa... [truncated]"]
+ *
+ * sanitizeData({ nested: { deep: { ... } } }, 2)
+ * // → { nested: { deep: "[Max depth reached]" } }
+ * ```
+ *
+ * @param data - Data to sanitize (any type)
+ * @param maxDepth - Maximum recursion depth to prevent infinite loops (default: 5)
+ * @param currentDepth - Internal parameter tracking current recursion level
+ * @returns Sanitized data safe for logging to external services
+ */
+function sanitizeData(data, maxDepth = 5, currentDepth = 0) {
+    // Prevent infinite recursion
+    if (currentDepth >= maxDepth) {
+        return "[Max depth reached]";
+    }
+    // Handle null/undefined
+    if (data === null || data === undefined) {
+        return data;
+    }
+    // Handle arrays
+    if (Array.isArray(data)) {
+        // Limit array size to prevent huge logs
+        const limit = 10;
+        const sanitized = data.slice(0, limit).map((item) => sanitizeData(item, maxDepth, currentDepth + 1));
+        if (data.length > limit) {
+            sanitized.push(`[... ${data.length - limit} more items]`);
+        }
+        return sanitized;
+    }
+    // Handle objects
+    if (typeof data === "object") {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(data)) {
+            const lowerKey = key.toLowerCase();
+            // Check if field is sensitive
+            const isSensitive = SENSITIVE_FIELDS.some((field) => lowerKey.includes(field.toLowerCase()));
+            if (isSensitive) {
+                sanitized[key] = "[REDACTED]";
+            }
+            else if (typeof value === "string" && value.length > 500) {
+                // Truncate long strings to prevent huge logs
+                sanitized[key] = `${value.substring(0, 500)}... [truncated]`;
+            }
+            else {
+                sanitized[key] = sanitizeData(value, maxDepth, currentDepth + 1);
+            }
+        }
+        return sanitized;
+    }
+    // Handle strings
+    if (typeof data === "string") {
+        // Truncate long strings
+        if (data.length > 1000) {
+            return `${data.substring(0, 1000)}... [truncated]`;
+        }
+        return data;
+    }
+    // Primitives (numbers, booleans) pass through
+    return data;
+}
+/**
+ * Monaco Core SDK error codes.
+ *
+ * Categorized error codes for better error handling and debugging.
+ * Each error class uses one of these codes to identify the error type.
+ *
+ * **Categories:**
+ *
+ * **Initialization Errors** (Configuration and setup):
+ * - `INITIALIZATION_ERROR`: General initialization failure
+ * - `INVALID_CONFIG`: Invalid SDK configuration (missing/wrong parameters)
+ * - `INVALID_STATE`: Invalid SDK state (operation called at wrong time)
+ * - `UNSUPPORTED_NETWORK`: Network not supported by SDK
+ *
+ * **API Errors** (External communication):
+ * - `API_ERROR`: API request failed (HTTP errors, network issues)
+ * - `CONTRACT_ERROR`: Smart contract interaction failure
+ * - `TRANSACTION_ERROR`: Blockchain transaction failure
+ *
+ * **Order Errors** (Trading operations):
+ * - `ORDER_ERROR`: General order operation failure
+ * - `INVALID_ORDER`: Order validation failure (invalid parameters)
+ * - `ORDER_NOT_FOUND`: Order does not exist
+ * - `INSUFFICIENT_BALANCE`: Insufficient token balance for operation
+ *
+ * **Event Errors** (WebSocket and subscriptions):
+ * - `EVENT_ERROR`: General event handling failure
+ * - `SUBSCRIPTION_ERROR`: Event subscription failure
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.someOperation();
+ * } catch (error) {
+ *   if (error.code === ERROR_CODES.INVALID_CONFIG) {
+ *     // Handle configuration error
+ *   } else if (error.code === ERROR_CODES.API_ERROR) {
+ *     // Handle API error
+ *   }
+ * }
+ * ```
+ *
+ * @constant
+ */
+export const ERROR_CODES = {
+    /** Initialization errors */
+    INITIALIZATION_ERROR: "INITIALIZATION_ERROR",
+    INVALID_CONFIG: "INVALID_CONFIG",
+    INVALID_STATE: "INVALID_STATE",
+    UNSUPPORTED_NETWORK: "UNSUPPORTED_NETWORK",
+    /** API errors */
+    API_ERROR: "API_ERROR",
+    CONTRACT_ERROR: "CONTRACT_ERROR",
+    TRANSACTION_ERROR: "TRANSACTION_ERROR",
+    /** Order errors */
+    ORDER_ERROR: "ORDER_ERROR",
+    INVALID_ORDER: "INVALID_ORDER",
+    ORDER_NOT_FOUND: "ORDER_NOT_FOUND",
+    INSUFFICIENT_BALANCE: "INSUFFICIENT_BALANCE",
+    /** Event errors */
+    EVENT_ERROR: "EVENT_ERROR",
+    SUBSCRIPTION_ERROR: "SUBSCRIPTION_ERROR",
+};
+/**
+ * Base class for all Monaco SDK errors.
+ *
+ * Provides common error functionality including:
+ * - Structured error codes for programmatic handling
+ * - Automatic recovery suggestions based on error context
+ * - Retry-ability indication for automatic retry logic
+ * - Timestamps for error tracking
+ * - JSON serialization for logging to external services
+ * - Cause chain support for error wrapping
+ *
+ * All SDK errors inherit from this class and provide specific error details.
+ *
+ * **Common Properties:**
+ * - `code`: MonacoErrorCode - Categorized error identifier
+ * - `message`: string - Human-readable error description
+ * - `suggestion`: string | undefined - Actionable recovery steps
+ * - `retryable`: boolean - Whether the operation can be retried
+ * - `timestamp`: number - Unix timestamp when error occurred
+ * - `cause`: unknown - Original error that caused this error (if wrapped)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.someOperation();
+ * } catch (error) {
+ *   if (error instanceof MonacoCoreError) {
+ *     console.log(`Error: ${error.message}`);
+ *     console.log(`Code: ${error.code}`);
+ *     console.log(`Suggestion: ${error.suggestion}`);
+ *     console.log(`Can retry: ${error.retryable}`);
+ *
+ *     // Send to monitoring service
+ *     logger.error(error.toJSON());
+ *   }
+ * }
+ * ```
+ *
+ * @abstract
+ */
+export class MonacoCoreError extends Error {
+    cause;
+    suggestion;
+    retryable = false;
+    timestamp;
+    constructor(message, options) {
+        super(message);
+        this.name = this.constructor.name;
+        this.timestamp = Date.now();
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+        if (options?.suggestion) {
+            this.suggestion = options.suggestion;
+        }
+        if (options?.retryable !== undefined) {
+            this.retryable = options.retryable;
+        }
+    }
+    /**
+     * Serialize error to JSON for logging/reporting
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            suggestion: this.suggestion,
+            retryable: this.retryable,
+            timestamp: this.timestamp,
+            cause: this.cause instanceof Error ? this.cause.message : this.cause,
+        };
+    }
+}
+/**
+ * Error thrown when SDK is initialized or configured incorrectly.
+ *
+ * Indicates invalid or missing configuration parameters that prevent
+ * the SDK from initializing or operating correctly. Includes automatic
+ * suggestions for common configuration fields.
+ *
+ * **Additional Properties:**
+ * - `field`: string | undefined - The configuration field that's invalid
+ * - `value`: unknown - The invalid value provided (sanitized in toJSON)
+ *
+ * **Common Causes:**
+ * - Missing required parameters (walletClient, seiRpcUrl)
+ * - Invalid URL formats
+ * - Unsupported network values
+ * - Wallet client chain mismatch
+ *
+ * @example
+ * ```typescript
+ * // Missing required field
+ * throw new InvalidConfigError(
+ *   "Wallet client is required",
+ *   "walletClient"
+ * );
+ *
+ * // Invalid value
+ * throw new InvalidConfigError(
+ *   "Invalid URL format",
+ *   "seiRpcUrl",
+ *   "not-a-url"
+ * );
+ *
+ * // With cause
+ * try {
+ *   new URL(config.wsUrl);
+ * } catch (error) {
+ *   throw new InvalidConfigError(
+ *     "wsUrl must be a valid URL",
+ *     "wsUrl",
+ *     config.wsUrl,
+ *     error
+ *   );
+ * }
+ * ```
+ */
+export class InvalidConfigError extends MonacoCoreError {
+    code = "INVALID_CONFIG";
+    field;
+    value;
+    constructor(message, field, value, cause) {
+        const suggestion = field
+            ? `Check the '${field}' configuration parameter. ${getSuggestionForConfigField(field)}`
+            : "Review your SDK configuration and ensure all required fields are provided correctly.";
+        super(message, { cause, suggestion, retryable: false });
+        this.field = field;
+        this.value = value;
+    }
+    toJSON() {
+        // Sanitize value based on field name - if the field is sensitive, redact the value
+        let sanitizedValue;
+        if (this.field) {
+            const lowerField = this.field.toLowerCase();
+            const isSensitive = SENSITIVE_FIELDS.some((sensitive) => lowerField.includes(sensitive.toLowerCase()));
+            if (isSensitive) {
+                sanitizedValue = "[REDACTED]";
+            }
+            else {
+                // Still sanitize the value in case it's an object with sensitive fields
+                sanitizedValue = sanitizeData(this.value);
+            }
+        }
+        else {
+            sanitizedValue = sanitizeData(this.value);
+        }
+        return {
+            ...super.toJSON(),
+            field: this.field,
+            value: sanitizedValue,
+        };
+    }
+}
+/**
+ * Get field-specific suggestions for common configuration parameters.
+ *
+ * Provides actionable guidance for fixing invalid configuration values.
+ * Used by InvalidConfigError to generate context-aware suggestions.
+ *
+ * **Supported Fields:**
+ * - `walletClient`: Wallet creation and account configuration
+ * - `seiRpcUrl`: RPC endpoint URLs for testnet/mainnet
+ * - `network`: Valid network presets
+ * - `*` (default): Generic configuration documentation link
+ *
+ * @param field - Configuration field name (case-insensitive)
+ * @returns Specific suggestion string for the field
+ * @internal
+ */
+function getSuggestionForConfigField(field) {
+    switch (field.toLowerCase()) {
+        case "walletclient":
+            return "Ensure you're creating the wallet client with a valid account and chain configuration.";
+        case "seirpcurl":
+            return "Use 'https://evm-rpc-testnet.sei-apis.com' for testnet or 'https://evm-rpc.sei-apis.com' for mainnet.";
+        case "wsurl":
+            return "Use 'wss://development.apimonaco.xyz/ws' for testnet or 'wss://api.monaco.xyz/ws' for mainnet.";
+        case "network":
+            return "Valid networks are: 'mainnet', 'development', 'staging', 'local'.";
+        default:
+            return "Refer to the SDK documentation for correct configuration format.";
+    }
+}
+/**
+ * Error thrown when an operation is called in an invalid SDK state.
+ *
+ * Indicates that a method was called at the wrong time or when prerequisites
+ * weren't met. Includes state transition information when available.
+ *
+ * **Additional Properties:**
+ * - `currentState`: string | undefined - The current state of the SDK
+ * - `expectedState`: string | undefined - The state required for this operation
+ *
+ * **Common Causes:**
+ * - Calling authenticated methods before login
+ * - Calling methods after logout/disconnect
+ * - Operation sequence violations
+ *
+ * @example
+ * ```typescript
+ * // With state information
+ * throw new InvalidStateError(
+ *   "Cannot place orders while disconnected",
+ *   "disconnected",
+ *   "connected"
+ * );
+ * // Suggestion: "Current state is 'disconnected', Expected state is 'connected'. Ensure operations are performed in the correct order."
+ *
+ * // Without state information
+ * throw new InvalidStateError(
+ *   "Prerequisites not met"
+ * );
+ * // Suggestion: "Check that prerequisites are met before calling this method."
+ * ```
+ */
+export class InvalidStateError extends MonacoCoreError {
+    code = "INVALID_STATE";
+    currentState;
+    expectedState;
+    constructor(message, currentState, expectedState, cause) {
+        const suggestion = expectedState
+            ? `${currentState ? `Current state is '${currentState}', ` : ""}Expected state is '${expectedState}'. Ensure operations are performed in the correct order.`
+            : "Check that prerequisites are met before calling this method.";
+        super(message, { cause, suggestion, retryable: false });
+        this.currentState = currentState;
+        this.expectedState = expectedState;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            currentState: this.currentState,
+            expectedState: this.expectedState,
+        };
+    }
+}
+/**
+ * Error thrown when an API request fails.
+ *
+ * Represents failures in HTTP/API communication including network errors,
+ * server errors, validation failures, and rate limiting. Automatically
+ * determines retry-ability and provides context-aware recovery suggestions.
+ *
+ * **Additional Properties:**
+ * - `endpoint`: string | undefined - The API endpoint that failed
+ * - `statusCode`: number | undefined - HTTP status code (undefined for network errors)
+ * - `responseBody`: unknown - Response body from the API (sanitized in toJSON)
+ * - `requestBody`: unknown - Request body sent to the API (sanitized in toJSON)
+ * - `requestId`: string | undefined - Request ID from X-Request-ID header
+ * - `retryAfter`: number | undefined - Retry-After header value in seconds
+ *
+ * **Common Status Codes:**
+ * - `undefined`: Network error (connection failed, timeout, DNS error)
+ * - `400`: Bad request (validation failed, invalid parameters)
+ * - `401`: Unauthorized (missing or expired token)
+ * - `403`: Forbidden (insufficient permissions)
+ * - `404`: Not found (resource doesn't exist)
+ * - `429`: Rate limit exceeded
+ * - `500+`: Server error
+ *
+ * **Retry-ability:**
+ * - ✅ Retryable: Network errors, 429, 500+, 409
+ * - ❌ Not retryable: 400, 401, 403, 404, and most client errors
+ *
+ * @example
+ * ```typescript
+ * // Network error (no response)
+ * throw new APIError("Network request failed", {
+ *   endpoint: "/api/orders",
+ *   cause: new Error("ECONNREFUSED")
+ * });
+ *
+ * // API validation error
+ * throw new APIError("Invalid order parameters", {
+ *   endpoint: "/api/orders",
+ *   statusCode: 400,
+ *   responseBody: { error: "Price must be positive" },
+ *   requestBody: { price: -10 }
+ * });
+ *
+ * // Rate limit with retry-after
+ * throw new APIError("Rate limit exceeded", {
+ *   endpoint: "/api/orders",
+ *   statusCode: 429,
+ *   requestId: "req_abc123",
+ *   retryAfter: 60
+ * });
+ *
+ * // Check if retryable
+ * try {
+ *   await sdk.someOperation();
+ * } catch (error) {
+ *   if (error instanceof APIError && error.retryable) {
+ *     // Implement retry logic
+ *     await delay(error.retryAfter || 5);
+ *     await sdk.someOperation();
+ *   }
+ * }
+ * ```
+ */
+export class APIError extends MonacoCoreError {
+    code = "API_ERROR";
+    endpoint;
+    statusCode;
+    responseBody;
+    requestBody;
+    requestId;
+    retryAfter;
+    constructor(message, options) {
+        // Determine suggestion and retry-ability based on status code
+        const { suggestion, retryable } = getErrorSuggestion(options?.statusCode, message, options?.responseBody);
+        super(message, { cause: options?.cause, suggestion, retryable });
+        this.endpoint = options?.endpoint;
+        this.statusCode = options?.statusCode;
+        this.responseBody = options?.responseBody;
+        this.requestBody = options?.requestBody;
+        this.requestId = options?.requestId;
+        this.retryAfter = options?.retryAfter;
+    }
+    /**
+     * Override toJSON to include API-specific fields with sanitization
+     *
+     * Sanitizes requestBody and responseBody to prevent sensitive data exposure
+     * when errors are logged to external monitoring services.
+     */
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            endpoint: this.endpoint,
+            statusCode: this.statusCode,
+            responseBody: sanitizeData(this.responseBody),
+            requestBody: sanitizeData(this.requestBody),
+            requestId: this.requestId,
+            retryAfter: this.retryAfter,
+        };
+    }
+}
+/**
+ * Generate helpful error suggestions and determine retry-ability based on HTTP status codes.
+ *
+ * Analyzes API errors to provide actionable recovery suggestions and indicate whether
+ * the operation can be safely retried. Used automatically by APIError constructor.
+ *
+ * **Status Code Precedence** (checked in this order):
+ * 1. No status code (network errors) → retryable
+ * 2. 401 Unauthorized → check for token expiration, not retryable
+ * 3. 403 Forbidden → permission issue, not retryable
+ * 4. 404 Not Found → resource missing, not retryable
+ * 5. 409 Conflict → resource conflict, retryable
+ * 6. 400 Bad Request → check for specific issues (balance, validation), not retryable
+ * 7. 429 Too Many Requests → rate limit, retryable with backoff
+ * 8. 500-599 Server Errors → retryable (explicit range check)
+ * 9. Default → not retryable
+ *
+ * **Examples:**
+ * ```typescript
+ * getErrorSuggestion(401, "Token expired")
+ * // → {
+ * //     suggestion: "Access token has expired. Call sdk.refreshAuth()...",
+ * //     retryable: false
+ * //   }
+ *
+ * getErrorSuggestion(429, "Rate limit", { retry_after: 60 })
+ * // → {
+ * //     suggestion: "Rate limit exceeded. Wait 60 seconds before retrying...",
+ * //     retryable: true
+ * //   }
+ *
+ * getErrorSuggestion(undefined, "Network failed")
+ * // → {
+ * //     suggestion: "Network request failed. Check your internet connection...",
+ * //     retryable: true
+ * //   }
+ * ```
+ *
+ * @param statusCode - HTTP status code from the failed request (undefined for network errors)
+ * @param message - Error message from the API or network layer
+ * @param responseBody - Response body from the API (may contain retry_after, etc.)
+ * @returns Object with suggestion string and retryable boolean
+ * @internal
+ */
+function getErrorSuggestion(statusCode, message, responseBody) {
+    // Network/timeout errors - always retryable
+    if (!statusCode) {
+        return {
+            suggestion: "Network request failed. Check your internet connection and try again.",
+            retryable: true,
+        };
+    }
+    // Authentication errors (401 Unauthorized)
+    if (statusCode === StatusCodes.UNAUTHORIZED) {
+        if (message?.toLowerCase().includes("expired")) {
+            return {
+                suggestion: "Access token has expired. Call sdk.refreshAuth() to get a new token, or call sdk.login() to re-authenticate.",
+                retryable: false,
+            };
+        }
+        return {
+            suggestion: "Authentication required. Call sdk.login(clientId) to authenticate before making this request.",
+            retryable: false,
+        };
+    }
+    // Forbidden (403)
+    if (statusCode === StatusCodes.FORBIDDEN) {
+        return {
+            suggestion: "Access denied. Ensure your application has the required permissions and your client ID is valid.",
+            retryable: false,
+        };
+    }
+    // Not found (404)
+    if (statusCode === StatusCodes.NOT_FOUND) {
+        return {
+            suggestion: "Resource not found. Check that the ID or identifier is correct and the resource exists.",
+            retryable: false,
+        };
+    }
+    // Conflict (409) - check BEFORE 500+ to avoid being shadowed
+    if (statusCode === StatusCodes.CONFLICT) {
+        return {
+            suggestion: "Resource conflict. The resource may have been modified. Refresh and try again.",
+            retryable: true,
+        };
+    }
+    // Validation errors (400 Bad Request)
+    if (statusCode === StatusCodes.BAD_REQUEST) {
+        if (message?.toLowerCase().includes("insufficient balance")) {
+            return {
+                suggestion: "Insufficient balance. Deposit more funds using sdk.vault.deposit() or reduce the order size.",
+                retryable: false,
+            };
+        }
+        if (message?.toLowerCase().includes("invalid")) {
+            return {
+                suggestion: "Invalid request parameters. Check the API documentation for correct parameter format and values.",
+                retryable: false,
+            };
+        }
+        return {
+            suggestion: "Bad request. Verify that all required parameters are provided and correctly formatted.",
+            retryable: false,
+        };
+    }
+    // Rate limiting (429 Too Many Requests)
+    if (statusCode === StatusCodes.TOO_MANY_REQUESTS) {
+        let retryText;
+        if (typeof responseBody === "object" && responseBody !== null && "retry_after" in responseBody && responseBody.retry_after) {
+            const retryAfterValue = responseBody.retry_after;
+            retryText = ` Wait ${String(retryAfterValue)} seconds before retrying.`;
+        }
+        else {
+            retryText = " Wait a moment before retrying.";
+        }
+        return {
+            suggestion: `Rate limit exceeded.${retryText} Consider implementing exponential backoff for retries.`,
+            retryable: true,
+        };
+    }
+    // Server errors (500-599) - retryable
+    // Use explicit range check to avoid shadowing other status codes
+    if (statusCode >= StatusCodes.INTERNAL_SERVER_ERROR && statusCode < 600) {
+        return {
+            suggestion: "Server error occurred. This is likely a temporary issue. Try again in a few moments.",
+            retryable: true,
+        };
+    }
+    // Default - not retryable
+    return {
+        suggestion: undefined,
+        retryable: false,
+    };
+}
+/**
+ * Error thrown when a smart contract interaction fails.
+ *
+ * Represents failures in blockchain contract interactions including transaction
+ * reverts, gas estimation failures, and contract execution errors. Includes
+ * revert reasons and transaction hashes when available for debugging.
+ *
+ * **Additional Properties:**
+ * - `revertReason`: string | undefined - The reason the contract reverted
+ * - `transactionHash`: string | undefined - Transaction hash (if transaction was submitted)
+ * - `contractAddress`: string | undefined - Address of the contract that failed
+ *
+ * **Common Causes:**
+ * - Contract revert (require/assert failed)
+ * - Gas estimation failure (transaction would fail)
+ * - Insufficient gas provided
+ * - Contract state restrictions (e.g., paused, unauthorized)
+ * - Transaction reverted after submission
+ *
+ * @example
+ * ```typescript
+ * // Contract revert during simulation
+ * throw new ContractError(
+ *   "Insufficient balance for withdrawal",
+ *   {
+ *     revertReason: "Insufficient balance",
+ *     contractAddress: "0x123...",
+ *   }
+ * );
+ *
+ * // Transaction reverted on-chain
+ * throw new ContractError(
+ *   "Transaction reverted",
+ *   {
+ *     transactionHash: "0xabc...",
+ *     revertReason: "Slippage tolerance exceeded",
+ *     contractAddress: "0x456...",
+ *   }
+ * );
+ *
+ * // Gas estimation failure
+ * try {
+ *   await contract.estimateGas.someMethod(...args);
+ * } catch (error) {
+ *   throw new ContractError(
+ *     "Gas estimation failed",
+ *     {
+ *       revertReason: error.reason,
+ *       contractAddress: contract.address,
+ *       cause: error,
+ *     }
+ *   );
+ * }
+ * ```
+ */
+export class ContractError extends MonacoCoreError {
+    code = "CONTRACT_ERROR";
+    revertReason;
+    transactionHash;
+    contractAddress;
+    constructor(message, options) {
+        const suggestion = getContractErrorSuggestion(options?.revertReason);
+        super(message, { cause: options?.cause, suggestion, retryable: false });
+        this.revertReason = options?.revertReason;
+        this.transactionHash = options?.transactionHash;
+        this.contractAddress = options?.contractAddress;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            revertReason: this.revertReason,
+            transactionHash: this.transactionHash,
+            contractAddress: this.contractAddress,
+        };
+    }
+}
+/**
+ * Get suggestions for common contract errors
+ */
+function getContractErrorSuggestion(revertReason) {
+    if (!revertReason) {
+        return "Smart contract execution failed. Check transaction parameters and try again.";
+    }
+    const reason = revertReason.toLowerCase();
+    if (reason.includes("insufficient allowance")) {
+        return "Token allowance is insufficient. Call sdk.vault.approve() to increase the token allowance for the vault contract.";
+    }
+    if (reason.includes("insufficient balance")) {
+        return "Wallet balance is insufficient for this transaction. Ensure you have enough tokens and native currency for gas fees.";
+    }
+    if (reason.includes("nonce")) {
+        return "Transaction nonce error. This may be due to a pending transaction. Wait for pending transactions to complete or reset your account nonce.";
+    }
+    if (reason.includes("gas")) {
+        return "Transaction ran out of gas. Try increasing the gas limit for this transaction.";
+    }
+    return undefined;
+}