@opendatalabs/vana-sdk 0.1.0-alpha.fd33fc9 → 2.0.0

package/dist/core/pollingManager.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Internal polling manager for asynchronous relayer operations.
+ *
+ * @internal
+ * @remarks
+ * This module handles client-side polling for long-running relayer operations
+ * with exponential backoff, jitter, and cancellation support.
+ */
+import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "../types/relayer";
+import type { OperationStatus } from "../types/options";
+import type { Hash, TransactionReceipt } from "viem";
+/**
+ * Configuration options for polling behavior.
+ *
+ * @internal
+ */
+export interface PollingOptions {
+    /** Total timeout in milliseconds before giving up (default: 300000ms = 5 min) */
+    timeout?: number;
+    /** Initial polling interval in milliseconds (default: 1000ms) */
+    initialInterval?: number;
+    /** Maximum polling interval in milliseconds (default: 10000ms) */
+    maxInterval?: number;
+    /** Backoff multiplier for each retry (default: 1.5) */
+    backoffMultiplier?: number;
+    /** Jitter factor to prevent thundering herd (default: 0.2 = 20%) */
+    jitter?: number;
+}
+/**
+ * Internal polling manager that handles asynchronous relayer operations.
+ *
+ * @internal
+ * @remarks
+ * This class implements exponential backoff with jitter to prevent server
+ * overload while maintaining responsive status updates. It's designed to
+ * be resilient to network failures and browser tab closures.
+ */
+export declare class PollingManager {
+    private readonly relayerCallback;
+    private abortController?;
+    private timeoutId?;
+    private pollIntervalId?;
+    constructor(relayerCallback: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);
+    /**
+     * Starts polling for an operation's status.
+     *
+     * @param operationId - The operation ID to poll for
+     * @param options - Polling configuration and callbacks
+     * @returns Promise that resolves when operation completes or fails
+     * @throws TransactionPendingError if polling times out
+     * @throws Error if operation fails or is cancelled
+     */
+    startPolling(operationId: string, options?: {
+        signal?: AbortSignal;
+        onStatusUpdate?: (status: OperationStatus) => void;
+    } & Partial<PollingOptions>): Promise<{
+        hash: Hash;
+        receipt?: TransactionReceipt;
+    }>;
+    /**
+     * Main polling loop with exponential backoff.
+     *
+     * @internal
+     */
+    private poll;
+    /**
+     * Checks the current status of an operation.
+     *
+     * @internal
+     */
+    private checkStatus;
+    /**
+     * Maps relayer response to operation status.
+     *
+     * @internal
+     */
+    private mapResponseToStatus;
+    /**
+     * Determines if status has changed meaningfully.
+     *
+     * @internal
+     */
+    private hasStatusChanged;
+    /**
+     * Calculates next polling interval with jitter.
+     *
+     * @internal
+     */
+    private calculateNextInterval;
+    /**
+     * Waits for specified duration or until aborted.
+     *
+     * @internal
+     */
+    private wait;
+    /**
+     * Creates a timeout promise that rejects after configured duration.
+     *
+     * @internal
+     */
+    private createTimeoutPromise;
+    /**
+     * Determines if an error is retryable.
+     *
+     * @internal
+     */
+    private isRetryableError;
+    /**
+     * Gets last known status for error reporting.
+     *
+     * @internal
+     */
+    private getLastKnownStatus;
+    /**
+     * Cleans up resources.
+     *
+     * @internal
+     */
+    private cleanup;
+}

package/dist/core/pollingManager.js

@@ -0,0 +1,268 @@
+import { TransactionPendingError } from "../errors";
+const DEFAULT_POLLING_OPTIONS = {
+  timeout: 3e5,
+  // 5 minutes
+  initialInterval: 1e3,
+  // 1 second
+  maxInterval: 1e4,
+  // 10 seconds
+  backoffMultiplier: 1.5,
+  // 1s -> 1.5s -> 2.25s -> 3.375s -> 5s -> 7.5s -> 10s
+  jitter: 0.2
+  // 20% randomization
+};
+class PollingManager {
+  constructor(relayerCallback) {
+    this.relayerCallback = relayerCallback;
+  }
+  abortController;
+  timeoutId;
+  pollIntervalId;
+  /**
+   * Starts polling for an operation's status.
+   *
+   * @param operationId - The operation ID to poll for
+   * @param options - Polling configuration and callbacks
+   * @returns Promise that resolves when operation completes or fails
+   * @throws TransactionPendingError if polling times out
+   * @throws Error if operation fails or is cancelled
+   */
+  async startPolling(operationId, options = {}) {
+    const context = {
+      operationId,
+      signal: options.signal,
+      onStatusUpdate: options.onStatusUpdate,
+      relayerCallback: this.relayerCallback,
+      options: {
+        ...DEFAULT_POLLING_OPTIONS,
+        ...options
+      }
+    };
+    this.abortController = new AbortController();
+    if (context.signal) {
+      context.signal.addEventListener("abort", () => {
+        this.abortController?.abort();
+      });
+    }
+    const timeoutPromise = this.createTimeoutPromise(context);
+    const pollingPromise = this.poll(context);
+    try {
+      const result = await Promise.race([pollingPromise, timeoutPromise]);
+      this.cleanup();
+      return result;
+    } catch (error) {
+      this.cleanup();
+      if (error instanceof Error && !error.message.includes("operationId")) {
+        throw new TransactionPendingError(
+          operationId,
+          error.message,
+          this.getLastKnownStatus(context)
+        );
+      }
+      throw error;
+    }
+  }
+  /**
+   * Main polling loop with exponential backoff.
+   *
+   * @internal
+   */
+  async poll(context) {
+    let currentInterval = context.options.initialInterval;
+    let lastStatus = null;
+    let retryCount = 0;
+    while (!this.abortController?.signal.aborted) {
+      try {
+        const response = await this.checkStatus(context);
+        const status = this.mapResponseToStatus(response, context.operationId);
+        if (this.hasStatusChanged(lastStatus, status)) {
+          context.onStatusUpdate?.(status);
+          lastStatus = status;
+        }
+        if (status.type === "confirmed") {
+          return {
+            hash: status.hash,
+            receipt: status.receipt
+          };
+        }
+        if (status.type === "failed") {
+          throw new Error(status.error);
+        }
+        retryCount = 0;
+      } catch (error) {
+        if (this.isRetryableError(error)) {
+          retryCount++;
+          if (retryCount > 5) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(
+              `Failed to poll after ${retryCount} attempts: ${errorMessage}`
+            );
+          }
+        } else {
+          throw error;
+        }
+      }
+      await this.wait(this.calculateNextInterval(currentInterval, context));
+      currentInterval = Math.min(
+        currentInterval * context.options.backoffMultiplier,
+        context.options.maxInterval
+      );
+    }
+    throw new Error("Polling cancelled");
+  }
+  /**
+   * Checks the current status of an operation.
+   *
+   * @internal
+   */
+  async checkStatus(context) {
+    const request = {
+      type: "status_check",
+      operationId: context.operationId
+    };
+    return await context.relayerCallback(request);
+  }
+  /**
+   * Maps relayer response to operation status.
+   *
+   * @internal
+   */
+  mapResponseToStatus(response, operationId) {
+    switch (response.type) {
+      case "pending":
+        return { type: "pending", operationId };
+      case "submitted":
+        return { type: "submitted", hash: response.hash };
+      case "confirmed":
+        return {
+          type: "confirmed",
+          hash: response.hash,
+          receipt: response.receipt
+        };
+      case "error":
+        return {
+          type: "failed",
+          error: response.error,
+          operationId
+        };
+      case "direct":
+        const result = response.result;
+        if (result?.status === "queued") {
+          return {
+            type: "queued",
+            position: result.position,
+            estimatedWait: result.estimatedWait
+          };
+        }
+        if (result?.status === "processing") {
+          return { type: "processing" };
+        }
+        return { type: "pending", operationId };
+      default:
+        return { type: "pending", operationId };
+    }
+  }
+  /**
+   * Determines if status has changed meaningfully.
+   *
+   * @internal
+   */
+  hasStatusChanged(oldStatus, newStatus) {
+    if (!oldStatus) return true;
+    if (oldStatus.type !== newStatus.type) return true;
+    if (oldStatus.type === "queued" && newStatus.type === "queued" && oldStatus.position !== newStatus.position) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Calculates next polling interval with jitter.
+   *
+   * @internal
+   */
+  calculateNextInterval(baseInterval, context) {
+    const jitterRange = baseInterval * context.options.jitter;
+    const jitter = (Math.random() - 0.5) * 2 * jitterRange;
+    return Math.max(0, baseInterval + jitter);
+  }
+  /**
+   * Waits for specified duration or until aborted.
+   *
+   * @internal
+   */
+  async wait(ms) {
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(resolve, ms);
+      this.abortController?.signal.addEventListener("abort", () => {
+        clearTimeout(timeoutId);
+        reject(new Error("Polling cancelled"));
+      });
+      this.pollIntervalId = timeoutId;
+    });
+  }
+  /**
+   * Creates a timeout promise that rejects after configured duration.
+   *
+   * @internal
+   */
+  createTimeoutPromise(context) {
+    return new Promise((_, reject) => {
+      this.timeoutId = setTimeout(() => {
+        reject(
+          new TransactionPendingError(
+            context.operationId,
+            `Polling timeout after ${context.options.timeout}ms`,
+            this.getLastKnownStatus(context)
+          )
+        );
+      }, context.options.timeout);
+    });
+  }
+  /**
+   * Determines if an error is retryable.
+   *
+   * @internal
+   */
+  isRetryableError(error) {
+    if (!(error instanceof Error)) return false;
+    const message = error.message.toLowerCase();
+    if (message.includes("network") || message.includes("fetch") || message.includes("timeout") || message.includes("econnrefused") || message.includes("enotfound")) {
+      return true;
+    }
+    if (message.includes("500") || message.includes("502") || message.includes("503") || message.includes("504")) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Gets last known status for error reporting.
+   *
+   * @internal
+   */
+  getLastKnownStatus(context) {
+    return { type: "pending", operationId: context.operationId };
+  }
+  /**
+   * Cleans up resources.
+   *
+   * @internal
+   */
+  cleanup() {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = void 0;
+    }
+    if (this.pollIntervalId) {
+      clearTimeout(this.pollIntervalId);
+      this.pollIntervalId = void 0;
+    }
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = void 0;
+    }
+  }
+}
+export {
+  PollingManager
+};
+//# sourceMappingURL=pollingManager.js.map

package/dist/core/pollingManager.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/pollingManager.ts"],"sourcesContent":["/**\n * Internal polling manager for asynchronous relayer operations.\n *\n * @internal\n * @remarks\n * This module handles client-side polling for long-running relayer operations\n * with exponential backoff, jitter, and cancellation support.\n */\n\nimport type {\n  UnifiedRelayerRequest,\n  UnifiedRelayerResponse,\n} from \"../types/relayer\";\nimport type { OperationStatus } from \"../types/options\";\nimport type { Hash, TransactionReceipt } from \"viem\";\nimport { TransactionPendingError } from \"../errors\";\n\n/**\n * Configuration options for polling behavior.\n *\n * @internal\n */\nexport interface PollingOptions {\n  /** Total timeout in milliseconds before giving up (default: 300000ms = 5 min) */\n  timeout?: number;\n  /** Initial polling interval in milliseconds (default: 1000ms) */\n  initialInterval?: number;\n  /** Maximum polling interval in milliseconds (default: 10000ms) */\n  maxInterval?: number;\n  /** Backoff multiplier for each retry (default: 1.5) */\n  backoffMultiplier?: number;\n  /** Jitter factor to prevent thundering herd (default: 0.2 = 20%) */\n  jitter?: number;\n}\n\n/**\n * Context for a polling operation.\n *\n * @internal\n */\ninterface PollingContext {\n  operationId: string;\n  signal?: AbortSignal;\n  onStatusUpdate?: (status: OperationStatus) => void;\n  relayerCallback: (\n    request: UnifiedRelayerRequest,\n  ) => Promise<UnifiedRelayerResponse>;\n  options: Required<PollingOptions>;\n}\n\n/**\n * Default polling configuration based on production load testing.\n *\n * @internal\n */\nconst DEFAULT_POLLING_OPTIONS: Required<PollingOptions> = {\n  timeout: 300000, // 5 minutes\n  initialInterval: 1000, // 1 second\n  maxInterval: 10000, // 10 seconds\n  backoffMultiplier: 1.5, // 1s -> 1.5s -> 2.25s -> 3.375s -> 5s -> 7.5s -> 10s\n  jitter: 0.2, // 20% randomization\n};\n\n/**\n * Internal polling manager that handles asynchronous relayer operations.\n *\n * @internal\n * @remarks\n * This class implements exponential backoff with jitter to prevent server\n * overload while maintaining responsive status updates. It's designed to\n * be resilient to network failures and browser tab closures.\n */\nexport class PollingManager {\n  private abortController?: AbortController;\n  private timeoutId?: NodeJS.Timeout | number;\n  private pollIntervalId?: NodeJS.Timeout | number;\n\n  constructor(\n    private readonly relayerCallback: (\n      request: UnifiedRelayerRequest,\n    ) => Promise<UnifiedRelayerResponse>,\n  ) {}\n\n  /**\n   * Starts polling for an operation's status.\n   *\n   * @param operationId - The operation ID to poll for\n   * @param options - Polling configuration and callbacks\n   * @returns Promise that resolves when operation completes or fails\n   * @throws TransactionPendingError if polling times out\n   * @throws Error if operation fails or is cancelled\n   */\n  async startPolling(\n    operationId: string,\n    options: {\n      signal?: AbortSignal;\n      onStatusUpdate?: (status: OperationStatus) => void;\n    } & Partial<PollingOptions> = {},\n  ): Promise<{ hash: Hash; receipt?: TransactionReceipt }> {\n    const context: PollingContext = {\n      operationId,\n      signal: options.signal,\n      onStatusUpdate: options.onStatusUpdate,\n      relayerCallback: this.relayerCallback,\n      options: {\n        ...DEFAULT_POLLING_OPTIONS,\n        ...options,\n      },\n    };\n\n    // Set up abort handling\n    this.abortController = new AbortController();\n    if (context.signal) {\n      context.signal.addEventListener(\"abort\", () => {\n        this.abortController?.abort();\n      });\n    }\n\n    // Set up timeout\n    const timeoutPromise = this.createTimeoutPromise(context);\n\n    // Start polling\n    const pollingPromise = this.poll(context);\n\n    try {\n      // Race between polling completion and timeout\n      const result = await Promise.race([pollingPromise, timeoutPromise]);\n\n      // Clean up\n      this.cleanup();\n\n      return result;\n    } catch (error) {\n      // Clean up on error\n      this.cleanup();\n\n      // Preserve operationId in error for recovery\n      if (error instanceof Error && !error.message.includes(\"operationId\")) {\n        throw new TransactionPendingError(\n          operationId,\n          error.message,\n          this.getLastKnownStatus(context),\n        );\n      }\n\n      throw error;\n    }\n  }\n\n  /**\n   * Main polling loop with exponential backoff.\n   *\n   * @internal\n   */\n  private async poll(\n    context: PollingContext,\n  ): Promise<{ hash: Hash; receipt?: TransactionReceipt }> {\n    let currentInterval = context.options.initialInterval;\n    let lastStatus: OperationStatus | null = null;\n    let retryCount = 0;\n\n    while (!this.abortController?.signal.aborted) {\n      try {\n        // Check operation status\n        const response = await this.checkStatus(context);\n\n        // Process response\n        const status = this.mapResponseToStatus(response, context.operationId);\n\n        // Notify if status changed\n        if (this.hasStatusChanged(lastStatus, status)) {\n          context.onStatusUpdate?.(status);\n          lastStatus = status;\n        }\n\n        // Check for terminal states\n        if (status.type === \"confirmed\") {\n          return {\n            hash: status.hash,\n            receipt: status.receipt as TransactionReceipt | undefined,\n          };\n        }\n\n        if (status.type === \"failed\") {\n          throw new Error(status.error);\n        }\n\n        // Reset retry count on successful poll\n        retryCount = 0;\n      } catch (error) {\n        // Network errors are retryable\n        if (this.isRetryableError(error)) {\n          retryCount++;\n          if (retryCount > 5) {\n            const errorMessage =\n              error instanceof Error ? error.message : String(error);\n            throw new Error(\n              `Failed to poll after ${retryCount} attempts: ${errorMessage}`,\n            );\n          }\n        } else {\n          // Non-retryable errors should bubble up\n          throw error;\n        }\n      }\n\n      // Wait before next poll with exponential backoff\n      await this.wait(this.calculateNextInterval(currentInterval, context));\n\n      // Increase interval for next iteration\n      currentInterval = Math.min(\n        currentInterval * context.options.backoffMultiplier,\n        context.options.maxInterval,\n      );\n    }\n\n    // Aborted\n    throw new Error(\"Polling cancelled\");\n  }\n\n  /**\n   * Checks the current status of an operation.\n   *\n   * @internal\n   */\n  private async checkStatus(\n    context: PollingContext,\n  ): Promise<UnifiedRelayerResponse> {\n    const request: UnifiedRelayerRequest = {\n      type: \"status_check\",\n      operationId: context.operationId,\n    };\n\n    return await context.relayerCallback(request);\n  }\n\n  /**\n   * Maps relayer response to operation status.\n   *\n   * @internal\n   */\n  private mapResponseToStatus(\n    response: UnifiedRelayerResponse,\n    operationId: string,\n  ): OperationStatus {\n    switch (response.type) {\n      case \"pending\":\n        return { type: \"pending\", operationId };\n\n      case \"submitted\":\n        return { type: \"submitted\", hash: response.hash };\n\n      case \"confirmed\":\n        return {\n          type: \"confirmed\",\n          hash: response.hash,\n          receipt: response.receipt,\n        };\n\n      case \"error\":\n        return {\n          type: \"failed\",\n          error: response.error,\n          operationId,\n        };\n\n      case \"direct\":\n        // Direct responses during polling might include queue info\n        const result = response.result as any;\n        if (result?.status === \"queued\") {\n          return {\n            type: \"queued\",\n            position: result.position,\n            estimatedWait: result.estimatedWait,\n          };\n        }\n        if (result?.status === \"processing\") {\n          return { type: \"processing\" };\n        }\n        // Fallback\n        return { type: \"pending\", operationId };\n\n      default:\n        return { type: \"pending\", operationId };\n    }\n  }\n\n  /**\n   * Determines if status has changed meaningfully.\n   *\n   * @internal\n   */\n  private hasStatusChanged(\n    oldStatus: OperationStatus | null,\n    newStatus: OperationStatus,\n  ): boolean {\n    if (!oldStatus) return true;\n\n    // Check type change\n    if (oldStatus.type !== newStatus.type) return true;\n\n    // Check queue position change\n    if (\n      oldStatus.type === \"queued\" &&\n      newStatus.type === \"queued\" &&\n      oldStatus.position !== newStatus.position\n    ) {\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Calculates next polling interval with jitter.\n   *\n   * @internal\n   */\n  private calculateNextInterval(\n    baseInterval: number,\n    context: PollingContext,\n  ): number {\n    const jitterRange = baseInterval * context.options.jitter;\n    const jitter = (Math.random() - 0.5) * 2 * jitterRange;\n    return Math.max(0, baseInterval + jitter);\n  }\n\n  /**\n   * Waits for specified duration or until aborted.\n   *\n   * @internal\n   */\n  private async wait(ms: number): Promise<void> {\n    return new Promise((resolve, reject) => {\n      const timeoutId = setTimeout(resolve, ms);\n\n      // Handle abort\n      this.abortController?.signal.addEventListener(\"abort\", () => {\n        clearTimeout(timeoutId);\n        reject(new Error(\"Polling cancelled\"));\n      });\n\n      this.pollIntervalId = timeoutId as any;\n    });\n  }\n\n  /**\n   * Creates a timeout promise that rejects after configured duration.\n   *\n   * @internal\n   */\n  private createTimeoutPromise(context: PollingContext): Promise<never> {\n    return new Promise((_, reject) => {\n      this.timeoutId = setTimeout(() => {\n        reject(\n          new TransactionPendingError(\n            context.operationId,\n            `Polling timeout after ${context.options.timeout}ms`,\n            this.getLastKnownStatus(context),\n          ),\n        );\n      }, context.options.timeout) as any;\n    });\n  }\n\n  /**\n   * Determines if an error is retryable.\n   *\n   * @internal\n   */\n  private isRetryableError(error: unknown): boolean {\n    if (!(error instanceof Error)) return false;\n\n    const message = error.message.toLowerCase();\n\n    // Network errors\n    if (\n      message.includes(\"network\") ||\n      message.includes(\"fetch\") ||\n      message.includes(\"timeout\") ||\n      message.includes(\"econnrefused\") ||\n      message.includes(\"enotfound\")\n    ) {\n      return true;\n    }\n\n    // Server errors (5xx)\n    if (\n      message.includes(\"500\") ||\n      message.includes(\"502\") ||\n      message.includes(\"503\") ||\n      message.includes(\"504\")\n    ) {\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Gets last known status for error reporting.\n   *\n   * @internal\n   */\n  private getLastKnownStatus(\n    context: PollingContext,\n  ): OperationStatus | undefined {\n    // In a real implementation, we'd track this\n    return { type: \"pending\", operationId: context.operationId };\n  }\n\n  /**\n   * Cleans up resources.\n   *\n   * @internal\n   */\n  private cleanup(): void {\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId as any);\n      this.timeoutId = undefined;\n    }\n\n    if (this.pollIntervalId) {\n      clearTimeout(this.pollIntervalId as any);\n      this.pollIntervalId = undefined;\n    }\n\n    if (this.abortController) {\n      this.abortController.abort();\n      this.abortController = undefined;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core.cjs

@@ -39,6 +39,7 @@ var import_data = require("./controllers/data");
 var import_schemas = require("./controllers/schemas");
 var import_server = require("./controllers/server");
 var import_protocol = require("./controllers/protocol");
+var import_operations = require("./controllers/operations");
 var import_storage = require("./storage");
 var import_viem = require("viem");
 var import_wallet = require("./utils/wallet");
@@ -93,6 +94,8 @@ class VanaCore {
   data;
   /** Manages data schemas and refiners. */
   schemas;
+  /** Manages asynchronous operation recovery and status checking. */
+  operations;
   /** Provides personal server setup and trusted server interactions. */
   server;
   /** Offers low-level access to Vana protocol smart contracts. */
@@ -109,6 +112,8 @@ class VanaCore {
   walletClient;
   _staticUserAddress;
   // For read-only mode
+  operationStore;
+  atomicStore;
   /**
    * Initializes a new VanaCore client instance with the provided configuration.
    *
@@ -133,6 +138,7 @@ class VanaCore {
   constructor(platform, config) {
     this.platform = platform;
     this.validateConfig(config);
+    this.operationStore = config?.operationStore;
     this.relayerConfig = config.relayer;
     if (config.relayer) {
       if (typeof config.relayer !== "string" && typeof config.relayer !== "function") {
@@ -254,11 +260,13 @@ class VanaCore {
       ipfsGateways: this.ipfsGateways,
       defaultPersonalServerUrl: personalServerUrl,
       waitForTransactionEvents: this.waitForTransactionEvents.bind(this),
-      waitForOperation: this.waitForOperation.bind(this)
+      waitForOperation: this.waitForOperation.bind(this),
+      operationStore: this.operationStore
     };
     this.permissions = new import_permissions.PermissionsController(sharedContext);
     this.data = new import_data.DataController(sharedContext);
     this.schemas = new import_schemas.SchemaController(sharedContext);
+    this.operations = new import_operations.OperationsController(sharedContext);
     this.server = new import_server.ServerController(sharedContext);
     this.protocol = new import_protocol.ProtocolController(sharedContext);
   }
@@ -714,6 +722,52 @@ class VanaCore {
     const result = parseTransaction(transaction, receipt);
     return result;
   }
+  /**
+   * Enhances a unified relayer response with client-side behavior.
+   *
+   * @remarks
+   * This method wraps a relayer response in an enhanced object that provides
+   * a fluent `.wait()` method for handling asynchronous operations. The enhanced
+   * response intelligently handles both submitted transactions (via hash) and
+   * pending operations (via operationId).
+   *
+   * @param response - The unified relayer response to enhance
+   * @returns EnhancedTransactionResponse if the response can be enhanced, null otherwise
+   *
+   * @example
+   * ```typescript
+   * // Enhance a relayer response for fluent waiting
+   * const response = await handleRelayerOperation(vana, request);
+   * const enhanced = vana.enhanceRelayerResponse(response);
+   * if (enhanced) {
+   *   const result = await enhanced.wait();
+   *   if (result.expectedEvents?.FileAdded) {
+   *     console.log('File ID:', result.expectedEvents.FileAdded.fileId);
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With status updates for pending operations
+   * const enhanced = vana.enhanceRelayerResponse(response);
+   * if (enhanced) {
+   *   const result = await enhanced.wait({
+   *     onStatusUpdate: (status) => {
+   *       console.log('Operation status:', status.type);
+   *     },
+   *     timeout: 60000 // 1 minute timeout
+   *   });
+   * }
+   * ```
+   *
+   * @category Relayer
+   * @since 0.2.0
+   */
+  async enhanceRelayerResponse(response) {
+    const { enhanceResponse } = await import("./client/enhancedResponse");
+    return enhanceResponse(response, this);
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {