@opendatalabs/vana-sdk 0.1.0-alpha.2b6935d → 0.1.0-alpha.2e569eb

package/dist/server/relayerHandler.cjs

@@ -18,54 +18,254 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var relayerHandler_exports = {};
 __export(relayerHandler_exports, {
-  handleRelayerOperation: () => handleRelayerOperation,
-  handleRelayerRequest: () => import_handler.handleRelayerRequest
+  handleRelayerOperation: () => handleRelayerOperation
 });
 module.exports = __toCommonJS(relayerHandler_exports);
+var import_uuid = require("uuid");
 var import_errors = require("../errors");
 var import_viem = require("viem");
-var import_handler = require("./handler");
-async function handleRelayerOperation(sdk, request) {
-  if (request.type === "signed") {
-    return handleSignedOperation(sdk, request);
+async function handleRelayerOperation(sdk, request, options = {}) {
+  const sdkWithStores = sdk;
+  const storeUntyped = sdkWithStores.operationStore;
+  const isRelayerStore = storeUntyped && "get" in storeUntyped && "set" in storeUntyped;
+  const store = isRelayerStore ? storeUntyped : void 0;
+  const executionMode = options.execution ?? "sync";
+  const syncTimeout = options.syncTimeout ?? 3e4;
+  const transactionOptions = options.gas || options.gasPrice || options.maxFeePerGas || options.maxPriorityFeePerGas || options.nonce !== void 0 || options.value || options.signal || options.onStatusUpdate ? {
+    ...options.gas && { gas: options.gas },
+    ...options.gasPrice && { gasPrice: options.gasPrice },
+    ...options.maxFeePerGas && { maxFeePerGas: options.maxFeePerGas },
+    ...options.maxPriorityFeePerGas && {
+      maxPriorityFeePerGas: options.maxPriorityFeePerGas
+    },
+    ...options.nonce !== void 0 && { nonce: options.nonce },
+    ...options.value && { value: options.value },
+    ...options.signal && { signal: options.signal },
+    ...options.onStatusUpdate && {
+      onStatusUpdate: options.onStatusUpdate
+    }
+  } : void 0;
+  if (store) {
+    if (request.type === "status_check") {
+      const state = await store.get(request.operationId);
+      if (!state) return { type: "error", error: "Operation not found" };
+      if (state.status === "confirmed")
+        return {
+          type: "confirmed",
+          hash: state.transactionHash,
+          receipt: state.finalReceipt
+        };
+      if (state.status === "failed")
+        return { type: "error", error: state.error ?? "Operation failed" };
+      if (state.status === "pending") {
+        try {
+          const publicClient = sdkWithStores.publicClient;
+          if (publicClient) {
+            let receipt;
+            try {
+              receipt = await publicClient.getTransactionReceipt({
+                hash: state.transactionHash
+              });
+            } catch (receiptError) {
+              if (receiptError?.name !== "TransactionReceiptNotFoundError") {
+                console.warn(
+                  `\u26A0\uFE0F [Relayer] Unexpected error checking receipt:`,
+                  receiptError?.message ?? receiptError
+                );
+              }
+              receipt = null;
+            }
+            if (receipt) {
+              const updatedState = {
+                ...state,
+                status: receipt.status === "success" ? "confirmed" : "failed",
+                finalReceipt: receipt,
+                ...receipt.status !== "success" && {
+                  error: "Transaction reverted on chain"
+                }
+              };
+              await store.set(request.operationId, updatedState);
+              if (receipt.status === "success") {
+                return {
+                  type: "confirmed",
+                  hash: state.transactionHash,
+                  receipt
+                };
+              } else {
+                return {
+                  type: "error",
+                  error: "Transaction reverted on chain"
+                };
+              }
+            }
+          } else {
+            console.warn(
+              "\u26A0\uFE0F [Relayer] No public client available for status checking"
+            );
+          }
+        } catch (error) {
+          console.error(
+            `\u274C [Relayer] Unexpected error in status check:`,
+            error
+          );
+        }
+      }
+      return { type: "pending", operationId: request.operationId };
+    }
+    const operationId = (0, import_uuid.v4)();
+    if (executionMode === "async") {
+      await store.set(operationId, {
+        status: "pending",
+        transactionHash: "",
+        // Will be filled when processed
+        originalRequest: request,
+        nonce: options?.nonce,
+        retryCount: 0,
+        lastAttemptedGas: {
+          maxFeePerGas: transactionOptions?.maxFeePerGas?.toString(),
+          maxPriorityFeePerGas: transactionOptions?.maxPriorityFeePerGas?.toString()
+        },
+        submittedAt: Date.now()
+      });
+      console.log(
+        `[Relayer] Operation ${operationId} queued for async processing`
+      );
+      return { type: "pending", operationId };
+    }
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Sync execution timeout after ${syncTimeout}ms`));
+        }, syncTimeout);
+      });
+      const response = await Promise.race([
+        routeAndExecuteRequest(sdk, request, transactionOptions),
+        timeoutPromise
+      ]);
+      if (response.type === "signed") {
+        await store.set(operationId, {
+          status: "confirmed",
+          transactionHash: response.hash,
+          originalRequest: request,
+          nonce: transactionOptions?.nonce,
+          retryCount: 0,
+          lastAttemptedGas: {
+            maxFeePerGas: transactionOptions?.maxFeePerGas?.toString(),
+            maxPriorityFeePerGas: transactionOptions?.maxPriorityFeePerGas?.toString()
+          },
+          submittedAt: Date.now()
+        });
+        return response;
+      } else if (response.type === "direct") {
+        return response;
+      } else {
+        return response;
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error("Unknown error during operation submission");
+      await store.set(operationId, {
+        status: "pending",
+        transactionHash: "",
+        // Will be filled when retried
+        originalRequest: request,
+        nonce: options?.nonce,
+        retryCount: 0,
+        lastAttemptedGas: {
+          maxFeePerGas: transactionOptions?.maxFeePerGas?.toString(),
+          maxPriorityFeePerGas: transactionOptions?.maxPriorityFeePerGas?.toString()
+        },
+        submittedAt: Date.now(),
+        error: error.message
+      });
+      console.warn(
+        `[Relayer] Sync execution failed/timed out, returning pending operationId: ${operationId}`
+      );
+      return { type: "pending", operationId };
+    }
+  } else {
+    if (request.type === "status_check") {
+      return {
+        type: "error",
+        error: "Stateless relayer does not support operation status checks."
+      };
+    }
+    try {
+      const response = await routeAndExecuteRequest(
+        sdk,
+        request,
+        transactionOptions
+      );
+      if (response.type === "signed") {
+        return { type: "submitted", hash: response.hash };
+      } else if (response.type === "direct" && response.result && typeof response.result === "object" && "hash" in response.result) {
+        return {
+          type: "submitted",
+          hash: response.result.hash
+        };
+      } else {
+        return response;
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error("Unknown error during operation submission");
+      return { type: "error", error: error.message };
+    }
   }
-  return handleDirectOperation(sdk, request);
 }
-async function handleSignedOperation(sdk, request) {
-  const { typedData, signature, expectedUserAddress } = request;
-  let recoveredAddress;
-  try {
-    recoveredAddress = await (0, import_viem.recoverTypedDataAddress)({
-      domain: {
-        ...typedData.domain,
-        chainId: typedData.domain.chainId ? BigInt(typedData.domain.chainId) : void 0
-      },
-      types: typedData.types,
-      primaryType: typedData.primaryType,
-      message: typedData.message,
-      signature
-    });
-  } catch (error) {
-    throw new import_errors.SignatureError(
-      `Signature verification failed: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
-  }
-  if (expectedUserAddress) {
-    const normalizedExpected = (0, import_viem.getAddress)(expectedUserAddress);
-    const normalizedSigner = (0, import_viem.getAddress)(recoveredAddress);
-    if (normalizedSigner !== normalizedExpected) {
+async function routeAndExecuteRequest(sdk, request, options) {
+  if (request.type === "signed") {
+    const { typedData, signature, expectedUserAddress } = request;
+    let recoveredAddress;
+    try {
+      recoveredAddress = await (0, import_viem.recoverTypedDataAddress)({
+        domain: {
+          ...typedData.domain,
+          chainId: typedData.domain.chainId ? BigInt(typedData.domain.chainId) : void 0
+        },
+        types: typedData.types,
+        primaryType: typedData.primaryType,
+        message: typedData.message,
+        signature
+      });
+    } catch (error) {
       throw new import_errors.SignatureError(
-        `Security verification failed: Recovered signer address (${normalizedSigner}) does not match expected user address (${normalizedExpected})`
+        `Signature verification failed: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
+    if (expectedUserAddress) {
+      const normalizedExpected = (0, import_viem.getAddress)(expectedUserAddress);
+      const normalizedSigner = (0, import_viem.getAddress)(recoveredAddress);
+      if (normalizedSigner !== normalizedExpected) {
+        throw new import_errors.SignatureError(
+          `Security verification failed: Recovered signer address (${normalizedSigner}) does not match expected user address (${normalizedExpected})`
+        );
+      }
+    }
+    const result = await routeSignedOperation(
+      sdk,
+      typedData,
+      signature,
+      options
+    );
+    return { type: "signed", hash: result.hash };
+  } else if (request.type === "direct") {
+    return await handleDirectOperation(sdk, request, options);
   }
-  const result = await routeSignedOperation(sdk, typedData, signature);
-  return {
-    type: "signed",
-    hash: result.hash
-  };
+  throw new Error("Invalid request type for execution");
 }
-async function routeSignedOperation(sdk, typedData, signature) {
+async function routeSignedOperation(sdk, typedData, signature, options) {
+  const validPrimaryTypes = [
+    "Permission",
+    "RevokePermission",
+    "TrustServer",
+    "AddServer",
+    "UntrustServer",
+    "ServerFilesAndPermission"
+  ];
+  if (!validPrimaryTypes.includes(typedData.primaryType)) {
+    throw new Error(
+      `Unsupported operation type: ${typedData.primaryType}. Supported types: ${validPrimaryTypes.join(", ")}`
+    );
+  }
   const primaryType = typedData.primaryType;
   switch (primaryType) {
     case "Permission":
@@ -74,7 +274,8 @@ async function routeSignedOperation(sdk, typedData, signature) {
           ...typedData,
           primaryType: "Permission"
         },
-        signature
+        signature,
+        options
       );
     case "RevokePermission":
       return sdk.permissions.submitSignedRevoke(
@@ -82,7 +283,8 @@ async function routeSignedOperation(sdk, typedData, signature) {
           ...typedData,
           primaryType: "RevokePermission"
         },
-        signature
+        signature,
+        options
       );
     case "TrustServer":
       return sdk.permissions.submitSignedTrustServer(
@@ -90,7 +292,8 @@ async function routeSignedOperation(sdk, typedData, signature) {
           ...typedData,
           primaryType: "TrustServer"
         },
-        signature
+        signature,
+        options
       );
     case "AddServer":
       return sdk.permissions.submitSignedAddAndTrustServer(
@@ -98,7 +301,8 @@ async function routeSignedOperation(sdk, typedData, signature) {
           ...typedData,
           primaryType: "AddServer"
         },
-        signature
+        signature,
+        options
       );
     case "UntrustServer":
       return sdk.permissions.submitSignedUntrustServer(
@@ -106,7 +310,8 @@ async function routeSignedOperation(sdk, typedData, signature) {
           ...typedData,
           primaryType: "UntrustServer"
         },
-        signature
+        signature,
+        options
       );
     case "ServerFilesAndPermission":
       return sdk.permissions.submitSignedAddServerFilesAndPermissions(
@@ -114,97 +319,93 @@ async function routeSignedOperation(sdk, typedData, signature) {
           ...typedData,
           primaryType: "ServerFilesAndPermission"
         },
-        signature
+        signature,
+        options
       );
-    // RegisterGrantee is commented out as it's not supported by smart contracts yet
+    // TODO: RegisterGrantee with signature is not supported until
+    // DataPortabilityGrantees contract adds registerGranteeWithSignature function
     // case "RegisterGrantee":
     //   return sdk.permissions.submitSignedRegisterGrantee(...);
     default:
-      throw new Error(`Unsupported operation type: ${typedData.primaryType}`);
+      throw new Error(
+        `Unsupported operation type: ${typedData.primaryType}. Supported types: Permission, RevokePermission, TrustServer, AddServer, UntrustServer, ServerFilesAndPermission`
+      );
   }
 }
-async function handleDirectOperation(sdk, request) {
+async function handleDirectOperation(sdk, request, options) {
   switch (request.operation) {
     case "submitFileAddition": {
       const { url, userAddress } = request.params;
       const result = await sdk.data.addFileWithPermissions(
         url,
         userAddress,
-        []
+        [],
         // No permissions
+        options
       );
-      const eventData = await sdk.waitForTransactionEvents(result);
-      const fileId = eventData.expectedEvents?.FileAdded?.fileId;
-      if (!fileId) {
-        throw new Error("Failed to get fileId from transaction events");
-      }
-      return {
-        type: "direct",
-        result: {
-          fileId: Number(fileId),
-          transactionHash: result.hash
-        }
-      };
+      return { type: "direct", result };
     }
     case "submitFileAdditionWithPermissions": {
       const { url, userAddress, permissions } = request.params;
       const result = await sdk.data.addFileWithPermissions(
         url,
         userAddress,
-        permissions
+        permissions,
+        options
       );
-      const eventData = await sdk.waitForTransactionEvents(result);
-      const fileId = eventData.expectedEvents?.FileAdded?.fileId;
-      if (!fileId) {
-        throw new Error("Failed to get fileId from transaction events");
-      }
-      return {
-        type: "direct",
-        result: {
-          fileId: Number(fileId),
-          transactionHash: result.hash
-        }
-      };
+      return { type: "direct", result };
     }
     case "submitFileAdditionComplete": {
       const { url, userAddress, permissions, schemaId, ownerAddress } = request.params;
-      const sdkPermissions = permissions.map((p) => ({
-        account: p.account,
-        publicKey: p.key
-        // Map 'key' to 'publicKey'
-      }));
-      const result = await sdk.data.addFileWithPermissionsAndSchema(
+      const txResult = await sdk.data.addFileWithEncryptedPermissionsAndSchema(
         url,
         ownerAddress ?? userAddress,
-        sdkPermissions,
-        schemaId
+        permissions,
+        // Already in correct format with encrypted 'key' field
+        schemaId,
+        options
       );
-      const eventData = await sdk.waitForTransactionEvents(result);
-      const fileId = eventData.expectedEvents?.FileAdded?.fileId;
-      if (!fileId) {
-        throw new Error("Failed to get fileId from transaction events");
+      const eventResult = await sdk.waitForTransactionEvents(txResult);
+      const fileAddedEvent = eventResult.expectedEvents?.FileAdded;
+      if (!fileAddedEvent || !fileAddedEvent.fileId) {
+        console.error("Event result:", eventResult);
+        throw new Error("FileAdded event not found in transaction");
       }
+      const fileId = Number(fileAddedEvent.fileId);
       return {
         type: "direct",
         result: {
-          fileId: Number(fileId),
-          transactionHash: result.hash
+          fileId,
+          transactionHash: txResult.hash
         }
       };
     }
     case "storeGrantFile": {
       const grantFile = request.params;
+      const dataController = sdk.data;
+      const context = dataController.context;
+      if (!context?.storageManager) {
+        throw new Error(
+          "Storage configuration is required for storing grant files"
+        );
+      }
       const blob = new Blob([JSON.stringify(grantFile)], {
         type: "application/json"
       });
-      const result = await sdk.data.upload({
-        content: blob,
-        filename: `grant-${Date.now()}.json`
+      const uploadResult = await context.storageManager.upload(
+        blob,
+        `grant-${Date.now()}.json`
+      );
+      return { type: "direct", result: { url: uploadResult.url } };
+    }
+    case "submitRegisterGrantee": {
+      const { owner, granteeAddress, publicKey } = request.params;
+      const result = await sdk.permissions.submitRegisterGrantee({
+        owner,
+        granteeAddress,
+        publicKey
       });
-      return {
-        type: "direct",
-        result: { url: result.url }
-      };
+      return { type: "direct", result };
     }
     default: {
       const exhaustiveCheck = request;
@@ -214,7 +415,6 @@ async function handleDirectOperation(sdk, request) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  handleRelayerOperation,
-  handleRelayerRequest
+  handleRelayerOperation
 });
 //# sourceMappingURL=relayerHandler.cjs.map

package/dist/server/relayerHandler.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/server/relayerHandler.ts"],"sourcesContent":["import type { VanaInstance } from \"../index.node\";\nimport type {\n  UnifiedRelayerRequest,\n  UnifiedRelayerResponse,\n  SignedRelayerRequest,\n  DirectRelayerRequest,\n} from \"../types/relayer\";\nimport type {\n  GenericTypedData,\n  PermissionGrantTypedData,\n  RevokePermissionTypedData,\n  TrustServerTypedData,\n  AddAndTrustServerTypedData,\n  ServerFilesAndPermissionTypedData,\n  TypedDataPrimaryType,\n} from \"../types/permissions\";\nimport { SignatureError } from \"../errors\";\nimport { recoverTypedDataAddress, getAddress, type Hash } from \"viem\";\n\n/**\n * Universal handler for all relayer operations.\n *\n * This function processes both EIP-712 signed operations and direct operations,\n * automatically routing to the appropriate SDK methods.\n *\n * @param sdk - Initialized Vana SDK instance\n * @param request - The unified relayer request\n * @returns Promise resolving to operation-specific response\n *\n * @category Server\n * @example\n * ```typescript\n * // In your server endpoint (Next.js example):\n * import { handleRelayerOperation } from '@opendatalabs/vana-sdk/node';\n *\n * export async function POST(request: NextRequest) {\n *   try {\n *     const body = await request.json();\n *     const vana = getServerVanaInstance(); // Your server SDK instance\n *\n *     const result = await handleRelayerOperation(vana, body);\n *\n *     return NextResponse.json(result);\n *   } catch (error) {\n *     return NextResponse.json(\n *       { error: error.message },\n *       { status: 500 }\n *     );\n *   }\n * }\n * ```\n */\nexport async function handleRelayerOperation(\n  sdk: VanaInstance,\n  request: UnifiedRelayerRequest,\n): Promise<UnifiedRelayerResponse> {\n  // Handle signed operations (EIP-712)\n  if (request.type === \"signed\") {\n    return handleSignedOperation(sdk, request);\n  }\n\n  // Handle direct operations (non-signed)\n  return handleDirectOperation(sdk, request);\n}\n\n/**\n * Handle EIP-712 signed operations with full type safety\n */\nasync function handleSignedOperation(\n  sdk: VanaInstance,\n  request: SignedRelayerRequest,\n): Promise<UnifiedRelayerResponse> {\n  const { typedData, signature, expectedUserAddress } = request;\n\n  // Step 1: Verify the signature (security check)\n  let recoveredAddress: `0x${string}`;\n  try {\n    recoveredAddress = await recoverTypedDataAddress({\n      domain: {\n        ...typedData.domain,\n        chainId: typedData.domain.chainId\n          ? BigInt(typedData.domain.chainId)\n          : undefined,\n      },\n      types: typedData.types,\n      primaryType: typedData.primaryType,\n      message: typedData.message as unknown as Record<string, unknown>,\n      signature,\n    });\n  } catch (error) {\n    // Handle signature verification errors\n    throw new SignatureError(\n      `Signature verification failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    );\n  }\n\n  // Optional security check: Verify the signer matches expected address\n  if (expectedUserAddress) {\n    const normalizedExpected = getAddress(expectedUserAddress);\n    const normalizedSigner = getAddress(recoveredAddress);\n\n    if (normalizedSigner !== normalizedExpected) {\n      throw new SignatureError(\n        `Security verification failed: Recovered signer address (${normalizedSigner}) does not match expected user address (${normalizedExpected})`,\n      );\n    }\n  }\n\n  // Step 2: Route to appropriate SDK method based on primaryType\n  // Using proper type narrowing instead of unsafe casts\n  const result = await routeSignedOperation(sdk, typedData, signature);\n\n  // Return the transaction hash with type\n  return {\n    type: \"signed\",\n    hash: result.hash,\n  };\n}\n\n/**\n * Route signed operations to the appropriate SDK method with type safety\n */\nasync function routeSignedOperation(\n  sdk: VanaInstance,\n  typedData: GenericTypedData,\n  signature: Hash,\n) {\n  const primaryType = typedData.primaryType as TypedDataPrimaryType;\n\n  // Type-safe routing based on primaryType\n  switch (primaryType) {\n    case \"Permission\":\n      // TypeScript knows this is a Permission operation\n      return sdk.permissions.submitSignedGrant(\n        {\n          ...typedData,\n          primaryType: \"Permission\",\n        } as PermissionGrantTypedData,\n        signature,\n      );\n\n    case \"RevokePermission\":\n      return sdk.permissions.submitSignedRevoke(\n        {\n          ...typedData,\n          primaryType: \"RevokePermission\",\n        } as RevokePermissionTypedData,\n        signature,\n      );\n\n    case \"TrustServer\":\n      return sdk.permissions.submitSignedTrustServer(\n        {\n          ...typedData,\n          primaryType: \"TrustServer\",\n        } as TrustServerTypedData,\n        signature,\n      );\n\n    case \"AddServer\":\n      return sdk.permissions.submitSignedAddAndTrustServer(\n        {\n          ...typedData,\n          primaryType: \"AddServer\",\n        } as AddAndTrustServerTypedData,\n        signature,\n      );\n\n    case \"UntrustServer\":\n      return sdk.permissions.submitSignedUntrustServer(\n        {\n          ...typedData,\n          primaryType: \"UntrustServer\",\n        } as GenericTypedData,\n        signature,\n      );\n\n    case \"ServerFilesAndPermission\":\n      return sdk.permissions.submitSignedAddServerFilesAndPermissions(\n        {\n          ...typedData,\n          primaryType: \"ServerFilesAndPermission\",\n        } as ServerFilesAndPermissionTypedData,\n        signature,\n      );\n\n    // RegisterGrantee is commented out as it's not supported by smart contracts yet\n    // case \"RegisterGrantee\":\n    //   return sdk.permissions.submitSignedRegisterGrantee(...);\n\n    default:\n      throw new Error(`Unsupported operation type: ${typedData.primaryType}`);\n  }\n}\n\n/**\n * Handle direct (non-signed) operations\n */\nasync function handleDirectOperation(\n  sdk: VanaInstance,\n  request: DirectRelayerRequest,\n): Promise<UnifiedRelayerResponse> {\n  switch (request.operation) {\n    case \"submitFileAddition\": {\n      const { url, userAddress } = request.params;\n\n      // Use SDK to add file with no permissions\n      const result = await sdk.data.addFileWithPermissions(\n        url,\n        userAddress,\n        [], // No permissions\n      );\n\n      // Wait for transaction events to get fileId\n      const eventData = await sdk.waitForTransactionEvents(result);\n      const fileId = eventData.expectedEvents?.FileAdded?.fileId;\n\n      if (!fileId) {\n        throw new Error(\"Failed to get fileId from transaction events\");\n      }\n\n      return {\n        type: \"direct\",\n        result: {\n          fileId: Number(fileId),\n          transactionHash: result.hash,\n        },\n      };\n    }\n\n    case \"submitFileAdditionWithPermissions\": {\n      const { url, userAddress, permissions } = request.params;\n\n      // Use SDK to add file with permissions\n      const result = await sdk.data.addFileWithPermissions(\n        url,\n        userAddress,\n        permissions,\n      );\n\n      // Wait for transaction events to get fileId\n      const eventData = await sdk.waitForTransactionEvents(result);\n      const fileId = eventData.expectedEvents?.FileAdded?.fileId;\n\n      if (!fileId) {\n        throw new Error(\"Failed to get fileId from transaction events\");\n      }\n\n      return {\n        type: \"direct\",\n        result: {\n          fileId: Number(fileId),\n          transactionHash: result.hash,\n        },\n      };\n    }\n\n    case \"submitFileAdditionComplete\": {\n      const { url, userAddress, permissions, schemaId, ownerAddress } =\n        request.params;\n\n      // Map permissions from relayer format to SDK format\n      const sdkPermissions = permissions.map((p) => ({\n        account: p.account,\n        publicKey: p.key, // Map 'key' to 'publicKey'\n      }));\n\n      // Use SDK to add file with permissions and schema\n      const result = await sdk.data.addFileWithPermissionsAndSchema(\n        url,\n        ownerAddress ?? userAddress,\n        sdkPermissions,\n        schemaId,\n      );\n\n      // Wait for transaction events to get fileId\n      const eventData = await sdk.waitForTransactionEvents(result);\n      const fileId = eventData.expectedEvents?.FileAdded?.fileId;\n\n      if (!fileId) {\n        throw new Error(\"Failed to get fileId from transaction events\");\n      }\n\n      return {\n        type: \"direct\",\n        result: {\n          fileId: Number(fileId),\n          transactionHash: result.hash,\n        },\n      };\n    }\n\n    case \"storeGrantFile\": {\n      const grantFile = request.params;\n\n      // Store grant file using SDK's data controller\n      // Convert grant file to blob for storage\n      const blob = new Blob([JSON.stringify(grantFile)], {\n        type: \"application/json\",\n      });\n\n      // Upload using the data controller\n      const result = await sdk.data.upload({\n        content: blob,\n        filename: `grant-${Date.now()}.json`,\n      });\n\n      return {\n        type: \"direct\",\n        result: { url: result.url },\n      };\n    }\n\n    default: {\n      // TypeScript exhaustiveness check - ensures all cases are handled at compile time\n      const exhaustiveCheck: never = request;\n      // Return exhaustiveCheck to satisfy TypeScript while throwing an error\n      // This should never be reached if all cases are handled\n      return exhaustiveCheck;\n    }\n  }\n}\n\n// Legacy handler export - DEPRECATED\n// TODO: Remove in next major version\n// Migration guide: Use handleRelayerOperation instead\nexport { handleRelayerRequest } from \"./handler\";\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/server/relayerHandler.ts"],"sourcesContent":["import { v4 as uuidv4 } from \"uuid\";\nimport type { VanaInstance, VanaWithStores } from \"../index.node\";\nimport type {\n  UnifiedRelayerRequest,\n  UnifiedRelayerResponse,\n  DirectRelayerRequest,\n} from \"../types/relayer\";\nimport type { TransactionResult } from \"../types\";\nimport type {\n  TransactionOptions,\n  TransactionReceipt,\n} from \"../types/operations\";\nimport type { OperationState } from \"../types/operationStore\";\nimport type { Contract, Fn } from \"../generated/event-types\";\nimport type {\n  GenericTypedData,\n  PermissionGrantTypedData,\n  RevokePermissionTypedData,\n  TrustServerTypedData,\n  AddAndTrustServerTypedData,\n  ServerFilesAndPermissionTypedData,\n  TypedDataPrimaryType,\n} from \"../types/permissions\";\nimport { SignatureError } from \"../errors\";\nimport { recoverTypedDataAddress, getAddress, type Hash } from \"viem\";\n\n/**\n * Options for handleRelayerOperation\n */\nexport interface RelayerOperationOptions extends TransactionOptions {\n  /**\n   * Execution mode for the operation.\n   *\n   * @remarks\n   * - 'sync' (default): Attempts to process the transaction immediately.\n   *   If a timeout occurs, automatically falls back to returning a pending operation ID.\n   *   This is the Vana App's current model.\n   *\n   * - 'async': Immediately queues the operation and returns a pending operation ID.\n   *   The transaction will be processed by a background worker.\n   *   Requires an operationStore to be configured.\n   *\n   * @default 'sync'\n   */\n  execution?: \"sync\" | \"async\";\n\n  /**\n   * Timeout for synchronous execution in milliseconds.\n   * Only applies when execution is 'sync'.\n   *\n   * @default 30000 (30 seconds)\n   */\n  syncTimeout?: number;\n}\n\n/**\n * Universal handler for all relayer operations.\n *\n * This function processes both EIP-712 signed operations and direct operations,\n * automatically routing to the appropriate SDK methods.\n *\n * @param sdk - Initialized Vana SDK instance\n * @param request - The unified relayer request\n * @param options - Transaction and execution options\n * @returns Promise resolving to operation-specific response\n *\n * @category Server\n * @example\n * ```typescript\n * // In your server endpoint (Next.js example):\n * import { handleRelayerOperation } from '@opendatalabs/vana-sdk/node';\n *\n * export async function POST(request: NextRequest) {\n *   try {\n *     const body = await request.json();\n *     const vana = getServerVanaInstance(); // Your server SDK instance\n *\n *     // Explicit synchronous execution (Vana App model)\n *     const result = await handleRelayerOperation(vana, body, {\n *       execution: 'sync', // Explicit mode\n *       syncTimeout: 45000  // 45 second timeout\n *     });\n *\n *     return NextResponse.json(result);\n *   } catch (error) {\n *     return NextResponse.json(\n *       { error: error.message },\n *       { status: 500 }\n *     );\n *   }\n * }\n * ```\n */\nexport async function handleRelayerOperation(\n  sdk: VanaInstance,\n  request: UnifiedRelayerRequest,\n  options: RelayerOperationOptions = {},\n): Promise<UnifiedRelayerResponse> {\n  // Type cast to access internal properties - safe for server-side relayer instances\n  const sdkWithStores = sdk as VanaInstance & Partial<VanaWithStores>;\n  const storeUntyped = sdkWithStores.operationStore;\n\n  // Check if it's a IRelayerStateStore (has get/set methods)\n  const isRelayerStore =\n    storeUntyped && \"get\" in storeUntyped && \"set\" in storeUntyped;\n  const store = isRelayerStore\n    ? (storeUntyped as import(\"../types/operationStore\").IRelayerStateStore)\n    : undefined;\n\n  // Extract execution mode and timeout with defaults\n  const executionMode = options.execution ?? \"sync\";\n  const syncTimeout = options.syncTimeout ?? 30000; // 30 seconds default\n\n  // Extract only TransactionOptions, excluding relayer-specific options\n  // Pass undefined if no transaction options were provided\n  const transactionOptions: TransactionOptions | undefined =\n    options.gas ||\n    options.gasPrice ||\n    options.maxFeePerGas ||\n    options.maxPriorityFeePerGas ||\n    options.nonce !== undefined ||\n    options.value ||\n    options.signal ||\n    options.onStatusUpdate\n      ? {\n          ...(options.gas && { gas: options.gas }),\n          ...(options.gasPrice && { gasPrice: options.gasPrice }),\n          ...(options.maxFeePerGas && { maxFeePerGas: options.maxFeePerGas }),\n          ...(options.maxPriorityFeePerGas && {\n            maxPriorityFeePerGas: options.maxPriorityFeePerGas,\n          }),\n          ...(options.nonce !== undefined && { nonce: options.nonce }),\n          ...(options.value && { value: options.value }),\n          ...(options.signal && { signal: options.signal }),\n          ...(options.onStatusUpdate && {\n            onStatusUpdate: options.onStatusUpdate,\n          }),\n        }\n      : undefined;\n\n  // --- STATEFUL (ROBUST) MODE ---\n  // This block executes ONLY if the developer provided a relayer state store.\n  if (store) {\n    if (request.type === \"status_check\") {\n      const state = await store.get(request.operationId);\n      if (!state) return { type: \"error\", error: \"Operation not found\" };\n\n      // If already confirmed or failed, return immediately\n      if (state.status === \"confirmed\")\n        return {\n          type: \"confirmed\",\n          hash: state.transactionHash,\n          receipt: state.finalReceipt,\n        };\n      if (state.status === \"failed\")\n        return { type: \"error\", error: state.error ?? \"Operation failed\" };\n\n      // For pending operations, check the blockchain for transaction status\n      if (state.status === \"pending\") {\n        try {\n          // Get a public client to check transaction status\n          const publicClient = sdkWithStores.publicClient;\n\n          if (publicClient) {\n            // Check if transaction has been mined\n            let receipt;\n            try {\n              receipt = await publicClient.getTransactionReceipt({\n                hash: state.transactionHash,\n              });\n            } catch (receiptError: any) {\n              // Transaction not found is expected - it may not be mined yet\n              if (receiptError?.name !== \"TransactionReceiptNotFoundError\") {\n                // Unexpected error - log but don't fail\n                console.warn(\n                  `⚠️ [Relayer] Unexpected error checking receipt:`,\n                  receiptError?.message ?? receiptError,\n                );\n              }\n              // Continue returning pending status\n              receipt = null;\n            }\n\n            if (receipt) {\n              // Update the operation state based on transaction status\n              const updatedState: OperationState = {\n                ...state,\n                status: receipt.status === \"success\" ? \"confirmed\" : \"failed\",\n                finalReceipt: receipt as TransactionReceipt,\n                ...(receipt.status !== \"success\" && {\n                  error: \"Transaction reverted on chain\",\n                }),\n              };\n\n              // Persist the updated state\n              await store.set(request.operationId, updatedState);\n\n              // Return the appropriate response\n              if (receipt.status === \"success\") {\n                return {\n                  type: \"confirmed\",\n                  hash: state.transactionHash,\n                  receipt: receipt as TransactionReceipt,\n                };\n              } else {\n                return {\n                  type: \"error\",\n                  error: \"Transaction reverted on chain\",\n                };\n              }\n            }\n          } else {\n            console.warn(\n              \"⚠️ [Relayer] No public client available for status checking\",\n            );\n          }\n        } catch (error) {\n          console.error(\n            `❌ [Relayer] Unexpected error in status check:`,\n            error,\n          );\n          // Don't fail the operation, just continue returning pending\n        }\n      }\n\n      return { type: \"pending\", operationId: request.operationId };\n    }\n\n    const operationId = uuidv4();\n\n    // Handle async execution mode - immediately queue and return\n    if (executionMode === \"async\") {\n      // Store the operation for later processing\n      await store.set(operationId, {\n        status: \"pending\",\n        transactionHash: \"\" as Hash, // Will be filled when processed\n        originalRequest: request,\n        nonce: options?.nonce,\n        retryCount: 0,\n        lastAttemptedGas: {\n          maxFeePerGas: transactionOptions?.maxFeePerGas?.toString(),\n          maxPriorityFeePerGas:\n            transactionOptions?.maxPriorityFeePerGas?.toString(),\n        },\n        submittedAt: Date.now(),\n      });\n\n      console.log(\n        `[Relayer] Operation ${operationId} queued for async processing`,\n      );\n      return { type: \"pending\", operationId };\n    }\n\n    // Handle sync execution mode (default) - try to execute immediately with timeout protection\n    try {\n      // Create a timeout promise\n      const timeoutPromise = new Promise<never>((_, reject) => {\n        setTimeout(() => {\n          reject(new Error(`Sync execution timeout after ${syncTimeout}ms`));\n        }, syncTimeout);\n      });\n\n      // Race between execution and timeout\n      const response = await Promise.race([\n        routeAndExecuteRequest(sdk, request, transactionOptions),\n        timeoutPromise,\n      ]);\n\n      // Handle different response types\n      if (response.type === \"signed\") {\n        // Store signed transaction state\n        await store.set(operationId, {\n          status: \"confirmed\",\n          transactionHash: response.hash,\n          originalRequest: request,\n          nonce: transactionOptions?.nonce,\n          retryCount: 0,\n          lastAttemptedGas: {\n            maxFeePerGas: transactionOptions?.maxFeePerGas?.toString(),\n            maxPriorityFeePerGas:\n              transactionOptions?.maxPriorityFeePerGas?.toString(),\n          },\n          submittedAt: Date.now(),\n        });\n\n        // Return signed response as-is\n        return response;\n      } else if (response.type === \"direct\") {\n        // Non-transactional direct operations - return as-is\n        return response;\n      } else {\n        // Error responses - return as-is\n        return response;\n      }\n    } catch (e) {\n      // On timeout or error in sync mode, fall back to pending\n      const error =\n        e instanceof Error\n          ? e\n          : new Error(\"Unknown error during operation submission\");\n\n      // Store as pending for recovery\n      await store.set(operationId, {\n        status: \"pending\",\n        transactionHash: \"\" as Hash, // Will be filled when retried\n        originalRequest: request,\n        nonce: options?.nonce,\n        retryCount: 0,\n        lastAttemptedGas: {\n          maxFeePerGas: transactionOptions?.maxFeePerGas?.toString(),\n          maxPriorityFeePerGas:\n            transactionOptions?.maxPriorityFeePerGas?.toString(),\n        },\n        submittedAt: Date.now(),\n        error: error.message,\n      });\n\n      console.warn(\n        `[Relayer] Sync execution failed/timed out, returning pending operationId: ${operationId}`,\n      );\n      return { type: \"pending\", operationId };\n    }\n  }\n\n  // --- STATELESS (SIMPLE) MODE ---\n  // This block executes if no IOperationStore was provided. Fire-and-forget.\n  else {\n    if (request.type === \"status_check\") {\n      return {\n        type: \"error\",\n        error: \"Stateless relayer does not support operation status checks.\",\n      };\n    }\n\n    try {\n      const response = await routeAndExecuteRequest(\n        sdk,\n        request,\n        transactionOptions,\n      );\n\n      // For stateless relayers, convert transaction responses to 'submitted' type\n      if (response.type === \"signed\") {\n        return { type: \"submitted\", hash: response.hash };\n      } else if (\n        response.type === \"direct\" &&\n        response.result &&\n        typeof response.result === \"object\" &&\n        \"hash\" in response.result\n      ) {\n        // Direct operations that return TransactionResults\n        return {\n          type: \"submitted\",\n          hash: (response.result as { hash: Hash }).hash,\n        };\n      } else {\n        // Return other response types as-is (direct non-transaction results, error)\n        return response;\n      }\n    } catch (e) {\n      const error =\n        e instanceof Error\n          ? e\n          : new Error(\"Unknown error during operation submission\");\n      return { type: \"error\", error: error.message };\n    }\n  }\n}\n\n/**\n * Helper function to route and execute requests.\n * This simply delegates to the appropriate handler based on request type.\n */\nasync function routeAndExecuteRequest(\n  sdk: VanaInstance,\n  request: UnifiedRelayerRequest,\n  options?: TransactionOptions,\n): Promise<UnifiedRelayerResponse> {\n  if (request.type === \"signed\") {\n    const { typedData, signature, expectedUserAddress } = request;\n\n    // Step 1: Verify the signature (security check)\n    let recoveredAddress: `0x${string}`;\n    try {\n      recoveredAddress = await recoverTypedDataAddress({\n        domain: {\n          ...typedData.domain,\n          chainId: typedData.domain.chainId\n            ? BigInt(typedData.domain.chainId)\n            : undefined,\n        },\n        types: typedData.types,\n        primaryType: typedData.primaryType,\n        message: typedData.message as unknown as Record<string, unknown>,\n        signature,\n      });\n    } catch (error) {\n      // Handle signature verification errors\n      throw new SignatureError(\n        `Signature verification failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      );\n    }\n\n    // Optional security check: Verify the signer matches expected address\n    if (expectedUserAddress) {\n      const normalizedExpected = getAddress(expectedUserAddress);\n      const normalizedSigner = getAddress(recoveredAddress);\n\n      if (normalizedSigner !== normalizedExpected) {\n        throw new SignatureError(\n          `Security verification failed: Recovered signer address (${normalizedSigner}) does not match expected user address (${normalizedExpected})`,\n        );\n      }\n    }\n\n    // Step 2: Route to appropriate SDK method based on primaryType\n    const result = await routeSignedOperation(\n      sdk,\n      typedData,\n      signature,\n      options,\n    );\n    return { type: \"signed\", hash: result.hash };\n  } else if (request.type === \"direct\") {\n    return await handleDirectOperation(sdk, request, options);\n  }\n  throw new Error(\"Invalid request type for execution\");\n}\n\n/**\n * Route signed operations to the appropriate SDK method with type safety.\n *\n * Returns a TransactionResult for one of the valid contracts and their functions.\n * Using Contract and Fn<Contract> ensures we're working with known contract types.\n */\nasync function routeSignedOperation(\n  sdk: VanaInstance,\n  typedData: GenericTypedData,\n  signature: Hash,\n  options?: TransactionOptions,\n): Promise<TransactionResult<Contract, Fn<Contract>>> {\n  // Validate primaryType before casting\n  const validPrimaryTypes: readonly TypedDataPrimaryType[] = [\n    \"Permission\",\n    \"RevokePermission\",\n    \"TrustServer\",\n    \"AddServer\",\n    \"UntrustServer\",\n    \"ServerFilesAndPermission\",\n  ] as const;\n\n  if (\n    !validPrimaryTypes.includes(typedData.primaryType as TypedDataPrimaryType)\n  ) {\n    throw new Error(\n      `Unsupported operation type: ${typedData.primaryType}. ` +\n        `Supported types: ${validPrimaryTypes.join(\", \")}`,\n    );\n  }\n  const primaryType = typedData.primaryType as TypedDataPrimaryType;\n\n  // Type-safe routing based on primaryType\n  switch (primaryType) {\n    case \"Permission\":\n      // TypeScript knows this is a Permission operation\n      return sdk.permissions.submitSignedGrant(\n        {\n          ...typedData,\n          primaryType: \"Permission\",\n        } as PermissionGrantTypedData,\n        signature,\n        options,\n      );\n\n    case \"RevokePermission\":\n      return sdk.permissions.submitSignedRevoke(\n        {\n          ...typedData,\n          primaryType: \"RevokePermission\",\n        } as RevokePermissionTypedData,\n        signature,\n        options,\n      );\n\n    case \"TrustServer\":\n      // Note: TrustServer operation is deprecated but still supported for backwards compatibility\n      // New implementations should use AddServer (AddAndTrustServer) instead\n      return sdk.permissions.submitSignedTrustServer(\n        {\n          ...typedData,\n          primaryType: \"TrustServer\",\n        } as TrustServerTypedData,\n        signature,\n        options,\n      );\n\n    case \"AddServer\":\n      return sdk.permissions.submitSignedAddAndTrustServer(\n        {\n          ...typedData,\n          primaryType: \"AddServer\",\n        } as AddAndTrustServerTypedData,\n        signature,\n        options,\n      );\n\n    case \"UntrustServer\":\n      return sdk.permissions.submitSignedUntrustServer(\n        {\n          ...typedData,\n          primaryType: \"UntrustServer\",\n        } as GenericTypedData,\n        signature,\n        options,\n      );\n\n    case \"ServerFilesAndPermission\":\n      return sdk.permissions.submitSignedAddServerFilesAndPermissions(\n        {\n          ...typedData,\n          primaryType: \"ServerFilesAndPermission\",\n        } as ServerFilesAndPermissionTypedData,\n        signature,\n        options,\n      );\n\n    // TODO: RegisterGrantee with signature is not supported until\n    // DataPortabilityGrantees contract adds registerGranteeWithSignature function\n    // case \"RegisterGrantee\":\n    //   return sdk.permissions.submitSignedRegisterGrantee(...);\n\n    default:\n      // This should never be reached due to validation above, but TypeScript requires it\n      throw new Error(\n        `Unsupported operation type: ${typedData.primaryType}. ` +\n          `Supported types: Permission, RevokePermission, TrustServer, AddServer, UntrustServer, ServerFilesAndPermission`,\n      );\n  }\n}\n\n/**\n * Handle direct (non-signed) operations\n */\nasync function handleDirectOperation(\n  sdk: VanaInstance,\n  request: DirectRelayerRequest,\n  options?: TransactionOptions,\n): Promise<UnifiedRelayerResponse> {\n  switch (request.operation) {\n    case \"submitFileAddition\": {\n      const { url, userAddress } = request.params;\n\n      // Use SDK to add file with no permissions\n      const result = await sdk.data.addFileWithPermissions(\n        url,\n        userAddress,\n        [], // No permissions\n        options,\n      );\n\n      // Return as direct result wrapped in UnifiedRelayerResponse\n      return { type: \"direct\", result };\n    }\n\n    case \"submitFileAdditionWithPermissions\": {\n      const { url, userAddress, permissions } = request.params;\n\n      // Use SDK to add file with permissions\n      const result = await sdk.data.addFileWithPermissions(\n        url,\n        userAddress,\n        permissions,\n        options,\n      );\n\n      // Return as direct result wrapped in UnifiedRelayerResponse\n      return { type: \"direct\", result };\n    }\n\n    case \"submitFileAdditionComplete\": {\n      const { url, userAddress, permissions, schemaId, ownerAddress } =\n        request.params;\n\n      // Permissions are already encrypted, use the appropriate method\n      // No mapping needed - permissions already have { account, key } format\n      const txResult = await sdk.data.addFileWithEncryptedPermissionsAndSchema(\n        url,\n        ownerAddress ?? userAddress,\n        permissions, // Already in correct format with encrypted 'key' field\n        schemaId,\n        options,\n      );\n\n      // File uploads need synchronous response with fileId\n      // Use the SDK's built-in event parsing - it knows how to extract events from TransactionResult\n      const eventResult = await sdk.waitForTransactionEvents(txResult);\n      const fileAddedEvent = eventResult.expectedEvents?.FileAdded;\n\n      if (!fileAddedEvent || !fileAddedEvent.fileId) {\n        console.error(\"Event result:\", eventResult);\n        throw new Error(\"FileAdded event not found in transaction\");\n      }\n\n      const fileId = Number(fileAddedEvent.fileId);\n\n      // Return as a direct result wrapped in UnifiedRelayerResponse\n      return {\n        type: \"direct\",\n        result: {\n          fileId,\n          transactionHash: txResult.hash,\n        },\n      };\n    }\n\n    case \"storeGrantFile\": {\n      const grantFile = request.params;\n\n      // Access the data controller's context which has storage\n      const dataController = sdk.data as any;\n      const context = dataController.context;\n\n      if (!context?.storageManager) {\n        throw new Error(\n          \"Storage configuration is required for storing grant files\",\n        );\n      }\n\n      // Convert grant file to blob for storage\n      const blob = new Blob([JSON.stringify(grantFile)], {\n        type: \"application/json\",\n      });\n\n      // Upload directly to storage (IPFS) without blockchain transaction\n      const uploadResult = await context.storageManager.upload(\n        blob,\n        `grant-${Date.now()}.json`,\n      );\n\n      return { type: \"direct\", result: { url: uploadResult.url } };\n    }\n\n    case \"submitRegisterGrantee\": {\n      const { owner, granteeAddress, publicKey } = request.params;\n\n      // Use SDK to register grantee\n      const result = await sdk.permissions.submitRegisterGrantee({\n        owner,\n        granteeAddress,\n        publicKey,\n      });\n\n      // Return as direct result wrapped in UnifiedRelayerResponse\n      return { type: \"direct\", result };\n    }\n\n    default: {\n      // TypeScript exhaustiveness check - ensures all cases are handled at compile time\n      const exhaustiveCheck: never = request;\n      // Return exhaustiveCheck to satisfy TypeScript while throwing an error\n      // This should never be reached if all cases are handled\n      return exhaustiveCheck;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAA6B;AAuB7B,oBAA+B;AAC/B,kBAA+D;AAqE/D,eAAsB,uBACpB,KACA,SACA,UAAmC,CAAC,GACH;AAEjC,QAAM,gBAAgB;AACtB,QAAM,eAAe,cAAc;AAGnC,QAAM,iBACJ,gBAAgB,SAAS,gBAAgB,SAAS;AACpD,QAAM,QAAQ,iBACT,eACD;AAGJ,QAAM,gBAAgB,QAAQ,aAAa;AAC3C,QAAM,cAAc,QAAQ,eAAe;AAI3C,QAAM,qBACJ,QAAQ,OACR,QAAQ,YACR,QAAQ,gBACR,QAAQ,wBACR,QAAQ,UAAU,UAClB,QAAQ,SACR,QAAQ,UACR,QAAQ,iBACJ;AAAA,IACE,GAAI,QAAQ,OAAO,EAAE,KAAK,QAAQ,IAAI;AAAA,IACtC,GAAI,QAAQ,YAAY,EAAE,UAAU,QAAQ,SAAS;AAAA,IACrD,GAAI,QAAQ,gBAAgB,EAAE,cAAc,QAAQ,aAAa;AAAA,IACjE,GAAI,QAAQ,wBAAwB;AAAA,MAClC,sBAAsB,QAAQ;AAAA,IAChC;AAAA,IACA,GAAI,QAAQ,UAAU,UAAa,EAAE,OAAO,QAAQ,MAAM;AAAA,IAC1D,GAAI,QAAQ,SAAS,EAAE,OAAO,QAAQ,MAAM;AAAA,IAC5C,GAAI,QAAQ,UAAU,EAAE,QAAQ,QAAQ,OAAO;AAAA,IAC/C,GAAI,QAAQ,kBAAkB;AAAA,MAC5B,gBAAgB,QAAQ;AAAA,IAC1B;AAAA,EACF,IACA;AAIN,MAAI,OAAO;AACT,QAAI,QAAQ,SAAS,gBAAgB;AACnC,YAAM,QAAQ,MAAM,MAAM,IAAI,QAAQ,WAAW;AACjD,UAAI,CAAC,MAAO,QAAO,EAAE,MAAM,SAAS,OAAO,sBAAsB;AAGjE,UAAI,MAAM,WAAW;AACnB,eAAO;AAAA,UACL,MAAM;AAAA,UACN,MAAM,MAAM;AAAA,UACZ,SAAS,MAAM;AAAA,QACjB;AACF,UAAI,MAAM,WAAW;AACnB,eAAO,EAAE,MAAM,SAAS,OAAO,MAAM,SAAS,mBAAmB;AAGnE,UAAI,MAAM,WAAW,WAAW;AAC9B,YAAI;AAEF,gBAAM,eAAe,cAAc;AAEnC,cAAI,cAAc;AAEhB,gBAAI;AACJ,gBAAI;AACF,wBAAU,MAAM,aAAa,sBAAsB;AAAA,gBACjD,MAAM,MAAM;AAAA,cACd,CAAC;AAAA,YACH,SAAS,cAAmB;AAE1B,kBAAI,cAAc,SAAS,mCAAmC;AAE5D,wBAAQ;AAAA,kBACN;AAAA,kBACA,cAAc,WAAW;AAAA,gBAC3B;AAAA,cACF;AAEA,wBAAU;AAAA,YACZ;AAEA,gBAAI,SAAS;AAEX,oBAAM,eAA+B;AAAA,gBACnC,GAAG;AAAA,gBACH,QAAQ,QAAQ,WAAW,YAAY,cAAc;AAAA,gBACrD,cAAc;AAAA,gBACd,GAAI,QAAQ,WAAW,aAAa;AAAA,kBAClC,OAAO;AAAA,gBACT;AAAA,cACF;AAGA,oBAAM,MAAM,IAAI,QAAQ,aAAa,YAAY;AAGjD,kBAAI,QAAQ,WAAW,WAAW;AAChC,uBAAO;AAAA,kBACL,MAAM;AAAA,kBACN,MAAM,MAAM;AAAA,kBACZ;AAAA,gBACF;AAAA,cACF,OAAO;AACL,uBAAO;AAAA,kBACL,MAAM;AAAA,kBACN,OAAO;AAAA,gBACT;AAAA,cACF;AAAA,YACF;AAAA,UACF,OAAO;AACL,oBAAQ;AAAA,cACN;AAAA,YACF;AAAA,UACF;AAAA,QACF,SAAS,OAAO;AACd,kBAAQ;AAAA,YACN;AAAA,YACA;AAAA,UACF;AAAA,QAEF;AAAA,MACF;AAEA,aAAO,EAAE,MAAM,WAAW,aAAa,QAAQ,YAAY;AAAA,IAC7D;AAEA,UAAM,kBAAc,YAAAA,IAAO;AAG3B,QAAI,kBAAkB,SAAS;AAE7B,YAAM,MAAM,IAAI,aAAa;AAAA,QAC3B,QAAQ;AAAA,QACR,iBAAiB;AAAA;AAAA,QACjB,iBAAiB;AAAA,QACjB,OAAO,SAAS;AAAA,QAChB,YAAY;AAAA,QACZ,kBAAkB;AAAA,UAChB,cAAc,oBAAoB,cAAc,SAAS;AAAA,UACzD,sBACE,oBAAoB,sBAAsB,SAAS;AAAA,QACvD;AAAA,QACA,aAAa,KAAK,IAAI;AAAA,MACxB,CAAC;AAED,cAAQ;AAAA,QACN,uBAAuB,WAAW;AAAA,MACpC;AACA,aAAO,EAAE,MAAM,WAAW,YAAY;AAAA,IACxC;AAGA,QAAI;AAEF,YAAM,iBAAiB,IAAI,QAAe,CAAC,GAAG,WAAW;AACvD,mBAAW,MAAM;AACf,iBAAO,IAAI,MAAM,gCAAgC,WAAW,IAAI,CAAC;AAAA,QACnE,GAAG,WAAW;AAAA,MAChB,CAAC;AAGD,YAAM,WAAW,MAAM,QAAQ,KAAK;AAAA,QAClC,uBAAuB,KAAK,SAAS,kBAAkB;AAAA,QACvD;AAAA,MACF,CAAC;AAGD,UAAI,SAAS,SAAS,UAAU;AAE9B,cAAM,MAAM,IAAI,aAAa;AAAA,UAC3B,QAAQ;AAAA,UACR,iBAAiB,SAAS;AAAA,UAC1B,iBAAiB;AAAA,UACjB,OAAO,oBAAoB;AAAA,UAC3B,YAAY;AAAA,UACZ,kBAAkB;AAAA,YAChB,cAAc,oBAAoB,cAAc,SAAS;AAAA,YACzD,sBACE,oBAAoB,sBAAsB,SAAS;AAAA,UACvD;AAAA,UACA,aAAa,KAAK,IAAI;AAAA,QACxB,CAAC;AAGD,eAAO;AAAA,MACT,WAAW,SAAS,SAAS,UAAU;AAErC,eAAO;AAAA,MACT,OAAO;AAEL,eAAO;AAAA,MACT;AAAA,IACF,SAAS,GAAG;AAEV,YAAM,QACJ,aAAa,QACT,IACA,IAAI,MAAM,2CAA2C;AAG3D,YAAM,MAAM,IAAI,aAAa;AAAA,QAC3B,QAAQ;AAAA,QACR,iBAAiB;AAAA;AAAA,QACjB,iBAAiB;AAAA,QACjB,OAAO,SAAS;AAAA,QAChB,YAAY;AAAA,QACZ,kBAAkB;AAAA,UAChB,cAAc,oBAAoB,cAAc,SAAS;AAAA,UACzD,sBACE,oBAAoB,sBAAsB,SAAS;AAAA,QACvD;AAAA,QACA,aAAa,KAAK,IAAI;AAAA,QACtB,OAAO,MAAM;AAAA,MACf,CAAC;AAED,cAAQ;AAAA,QACN,6EAA6E,WAAW;AAAA,MAC1F;AACA,aAAO,EAAE,MAAM,WAAW,YAAY;AAAA,IACxC;AAAA,EACF,OAIK;AACH,QAAI,QAAQ,SAAS,gBAAgB;AACnC,aAAO;AAAA,QACL,MAAM;AAAA,QACN,OAAO;AAAA,MACT;AAAA,IACF;AAEA,QAAI;AACF,YAAM,WAAW,MAAM;AAAA,QACrB;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAGA,UAAI,SAAS,SAAS,UAAU;AAC9B,eAAO,EAAE,MAAM,aAAa,MAAM,SAAS,KAAK;AAAA,MAClD,WACE,SAAS,SAAS,YAClB,SAAS,UACT,OAAO,SAAS,WAAW,YAC3B,UAAU,SAAS,QACnB;AAEA,eAAO;AAAA,UACL,MAAM;AAAA,UACN,MAAO,SAAS,OAA0B;AAAA,QAC5C;AAAA,MACF,OAAO;AAEL,eAAO;AAAA,MACT;AAAA,IACF,SAAS,GAAG;AACV,YAAM,QACJ,aAAa,QACT,IACA,IAAI,MAAM,2CAA2C;AAC3D,aAAO,EAAE,MAAM,SAAS,OAAO,MAAM,QAAQ;AAAA,IAC/C;AAAA,EACF;AACF;AAMA,eAAe,uBACb,KACA,SACA,SACiC;AACjC,MAAI,QAAQ,SAAS,UAAU;AAC7B,UAAM,EAAE,WAAW,WAAW,oBAAoB,IAAI;AAGtD,QAAI;AACJ,QAAI;AACF,yBAAmB,UAAM,qCAAwB;AAAA,QAC/C,QAAQ;AAAA,UACN,GAAG,UAAU;AAAA,UACb,SAAS,UAAU,OAAO,UACtB,OAAO,UAAU,OAAO,OAAO,IAC/B;AAAA,QACN;AAAA,QACA,OAAO,UAAU;AAAA,QACjB,aAAa,UAAU;AAAA,QACvB,SAAS,UAAU;AAAA,QACnB;AAAA,MACF,CAAC;AAAA,IACH,SAAS,OAAO;AAEd,YAAM,IAAI;AAAA,QACR,kCAAkC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MAC5F;AAAA,IACF;AAGA,QAAI,qBAAqB;AACvB,YAAM,yBAAqB,wBAAW,mBAAmB;AACzD,YAAM,uBAAmB,wBAAW,gBAAgB;AAEpD,UAAI,qBAAqB,oBAAoB;AAC3C,cAAM,IAAI;AAAA,UACR,2DAA2D,gBAAgB,2CAA2C,kBAAkB;AAAA,QAC1I;AAAA,MACF;AAAA,IACF;AAGA,UAAM,SAAS,MAAM;AAAA,MACnB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AACA,WAAO,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;AAAA,EAC7C,WAAW,QAAQ,SAAS,UAAU;AACpC,WAAO,MAAM,sBAAsB,KAAK,SAAS,OAAO;AAAA,EAC1D;AACA,QAAM,IAAI,MAAM,oCAAoC;AACtD;AAQA,eAAe,qBACb,KACA,WACA,WACA,SACoD;AAEpD,QAAM,oBAAqD;AAAA,IACzD;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,MACE,CAAC,kBAAkB,SAAS,UAAU,WAAmC,GACzE;AACA,UAAM,IAAI;AAAA,MACR,+BAA+B,UAAU,WAAW,sBAC9B,kBAAkB,KAAK,IAAI,CAAC;AAAA,IACpD;AAAA,EACF;AACA,QAAM,cAAc,UAAU;AAG9B,UAAQ,aAAa;AAAA,IACnB,KAAK;AAEH,aAAO,IAAI,YAAY;AAAA,QACrB;AAAA,UACE,GAAG;AAAA,UACH,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IAEF,KAAK;AACH,aAAO,IAAI,YAAY;AAAA,QACrB;AAAA,UACE,GAAG;AAAA,UACH,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IAEF,KAAK;AAGH,aAAO,IAAI,YAAY;AAAA,QACrB;AAAA,UACE,GAAG;AAAA,UACH,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IAEF,KAAK;AACH,aAAO,IAAI,YAAY;AAAA,QACrB;AAAA,UACE,GAAG;AAAA,UACH,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IAEF,KAAK;AACH,aAAO,IAAI,YAAY;AAAA,QACrB;AAAA,UACE,GAAG;AAAA,UACH,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IAEF,KAAK;AACH,aAAO,IAAI,YAAY;AAAA,QACrB;AAAA,UACE,GAAG;AAAA,UACH,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA;AAAA;AAAA;AAAA;AAAA,IAOF;AAEE,YAAM,IAAI;AAAA,QACR,+BAA+B,UAAU,WAAW;AAAA,MAEtD;AAAA,EACJ;AACF;AAKA,eAAe,sBACb,KACA,SACA,SACiC;AACjC,UAAQ,QAAQ,WAAW;AAAA,IACzB,KAAK,sBAAsB;AACzB,YAAM,EAAE,KAAK,YAAY,IAAI,QAAQ;AAGrC,YAAM,SAAS,MAAM,IAAI,KAAK;AAAA,QAC5B;AAAA,QACA;AAAA,QACA,CAAC;AAAA;AAAA,QACD;AAAA,MACF;AAGA,aAAO,EAAE,MAAM,UAAU,OAAO;AAAA,IAClC;AAAA,IAEA,KAAK,qCAAqC;AACxC,YAAM,EAAE,KAAK,aAAa,YAAY,IAAI,QAAQ;AAGlD,YAAM,SAAS,MAAM,IAAI,KAAK;AAAA,QAC5B;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAGA,aAAO,EAAE,MAAM,UAAU,OAAO;AAAA,IAClC;AAAA,IAEA,KAAK,8BAA8B;AACjC,YAAM,EAAE,KAAK,aAAa,aAAa,UAAU,aAAa,IAC5D,QAAQ;AAIV,YAAM,WAAW,MAAM,IAAI,KAAK;AAAA,QAC9B;AAAA,QACA,gBAAgB;AAAA,QAChB;AAAA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAIA,YAAM,cAAc,MAAM,IAAI,yBAAyB,QAAQ;AAC/D,YAAM,iBAAiB,YAAY,gBAAgB;AAEnD,UAAI,CAAC,kBAAkB,CAAC,eAAe,QAAQ;AAC7C,gBAAQ,MAAM,iBAAiB,WAAW;AAC1C,cAAM,IAAI,MAAM,0CAA0C;AAAA,MAC5D;AAEA,YAAM,SAAS,OAAO,eAAe,MAAM;AAG3C,aAAO;AAAA,QACL,MAAM;AAAA,QACN,QAAQ;AAAA,UACN;AAAA,UACA,iBAAiB,SAAS;AAAA,QAC5B;AAAA,MACF;AAAA,IACF;AAAA,IAEA,KAAK,kBAAkB;AACrB,YAAM,YAAY,QAAQ;AAG1B,YAAM,iBAAiB,IAAI;AAC3B,YAAM,UAAU,eAAe;AAE/B,UAAI,CAAC,SAAS,gBAAgB;AAC5B,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AAGA,YAAM,OAAO,IAAI,KAAK,CAAC,KAAK,UAAU,SAAS,CAAC,GAAG;AAAA,QACjD,MAAM;AAAA,MACR,CAAC;AAGD,YAAM,eAAe,MAAM,QAAQ,eAAe;AAAA,QAChD;AAAA,QACA,SAAS,KAAK,IAAI,CAAC;AAAA,MACrB;AAEA,aAAO,EAAE,MAAM,UAAU,QAAQ,EAAE,KAAK,aAAa,IAAI,EAAE;AAAA,IAC7D;AAAA,IAEA,KAAK,yBAAyB;AAC5B,YAAM,EAAE,OAAO,gBAAgB,UAAU,IAAI,QAAQ;AAGrD,YAAM,SAAS,MAAM,IAAI,YAAY,sBAAsB;AAAA,QACzD;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAGD,aAAO,EAAE,MAAM,UAAU,OAAO;AAAA,IAClC;AAAA,IAEA,SAAS;AAEP,YAAM,kBAAyB;AAG/B,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":["uuidv4"]}

package/dist/server/relayerHandler.d.ts

@@ -1,5 +1,33 @@
 import type { VanaInstance } from "../index.node";
 import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "../types/relayer";
+import type { TransactionOptions } from "../types/operations";
+/**
+ * Options for handleRelayerOperation
+ */
+export interface RelayerOperationOptions extends TransactionOptions {
+    /**
+     * Execution mode for the operation.
+     *
+     * @remarks
+     * - 'sync' (default): Attempts to process the transaction immediately.
+     *   If a timeout occurs, automatically falls back to returning a pending operation ID.
+     *   This is the Vana App's current model.
+     *
+     * - 'async': Immediately queues the operation and returns a pending operation ID.
+     *   The transaction will be processed by a background worker.
+     *   Requires an operationStore to be configured.
+     *
+     * @default 'sync'
+     */
+    execution?: "sync" | "async";
+    /**
+     * Timeout for synchronous execution in milliseconds.
+     * Only applies when execution is 'sync'.
+     *
+     * @default 30000 (30 seconds)
+     */
+    syncTimeout?: number;
+}
 /**
  * Universal handler for all relayer operations.
  *
@@ -8,6 +36,7 @@ import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "../types/rel
  *
  * @param sdk - Initialized Vana SDK instance
  * @param request - The unified relayer request
+ * @param options - Transaction and execution options
  * @returns Promise resolving to operation-specific response
  *
  * @category Server
@@ -21,7 +50,11 @@ import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "../types/rel
  *     const body = await request.json();
  *     const vana = getServerVanaInstance(); // Your server SDK instance
  *
- *     const result = await handleRelayerOperation(vana, body);
+ *     // Explicit synchronous execution (Vana App model)
+ *     const result = await handleRelayerOperation(vana, body, {
+ *       execution: 'sync', // Explicit mode
+ *       syncTimeout: 45000  // 45 second timeout
+ *     });
  *
  *     return NextResponse.json(result);
  *   } catch (error) {
@@ -33,5 +66,4 @@ import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "../types/rel
  * }
  * ```
  */
-export declare function handleRelayerOperation(sdk: VanaInstance, request: UnifiedRelayerRequest): Promise<UnifiedRelayerResponse>;
-export { handleRelayerRequest } from "./handler";
+export declare function handleRelayerOperation(sdk: VanaInstance, request: UnifiedRelayerRequest, options?: RelayerOperationOptions): Promise<UnifiedRelayerResponse>;