@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.8117ac2

package/dist/server/relayerHandler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/relayerHandler.ts"],"sourcesContent":["import { v4 as uuidv4 } from \"uuid\";\nimport type { VanaInstance } from \"../index.node\";\nimport type {\n  UnifiedRelayerRequest,\n  UnifiedRelayerResponse,\n  DirectRelayerRequest,\n} from \"../types/relayer\";\nimport type {\n  TransactionResult,\n  TransactionOptions,\n  IOperationStore,\n  OperationState,\n  TransactionReceipt,\n} from \"../types\";\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 * 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, // The public signature is generic\n  request: UnifiedRelayerRequest,\n  options?: TransactionOptions,\n): Promise<UnifiedRelayerResponse> {\n  // Type assertion required: VanaInstance public interface doesn't expose operationStore\n  // to maintain API simplicity, but server-side handler needs access for stateful mode.\n  // The factory overloads guarantee this is safe for relayer-configured instances.\n  // TODO(TYPES): Consider exposing operationStore through a server-specific interface\n\n  const store = (sdk as any).operationStore as IOperationStore | undefined;\n\n  // --- STATEFUL (ROBUST) MODE ---\n  // This block executes ONLY if the developer provided an IOperationStore.\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          // The SDK stores it as a direct property\n          const publicClient = (sdk as any).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    try {\n      const txResult = await routeAndExecuteRequest(sdk, request, options);\n      // We only store state for operations that result in a transaction.\n      if (\"hash\" in txResult) {\n        await store.set(operationId, {\n          status: \"pending\",\n          transactionHash: txResult.hash,\n          originalRequest: request,\n          nonce: options?.nonce,\n          retryCount: 0,\n          lastAttemptedGas: {\n            maxFeePerGas: options?.maxFeePerGas?.toString(),\n            maxPriorityFeePerGas: options?.maxPriorityFeePerGas?.toString(),\n          },\n          submittedAt: Date.now(),\n        });\n        return { type: \"pending\", operationId };\n      } else {\n        // This handles non-transactional direct operations like `storeGrantFile`\n        return { type: \"direct\", result: txResult };\n      }\n    } catch (e) {\n      const error =\n        e instanceof Error\n          ? e\n          : new Error(\"Unknown error during operation submission\");\n      // We don't create a persistent error state for an initial submission failure.\n      return { type: \"error\", error: error.message };\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 txResult = await routeAndExecuteRequest(sdk, request, options);\n\n      // For stateless relayers, we can only handle transactional results.\n      if (\"hash\" in txResult) {\n        return { type: \"submitted\", hash: txResult.hash };\n      } else {\n        // Non-transactional direct operations can return their result directly.\n        return { type: \"direct\", result: txResult };\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<\n  | TransactionResult<Contract, Fn<Contract>>\n  | { url: string }\n  | { fileId: number; transactionHash: Hash }\n> {\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    return await routeSignedOperation(sdk, typedData, signature, options);\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\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<\n  | TransactionResult<Contract, Fn<Contract>>\n  | { url: string }\n  | { fileId: number; transactionHash: Hash }\n> {\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 the TransactionResult directly\n      return 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 the TransactionResult directly\n      return 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      // The SDK has waitForTransactionEvents as a public method\n      const eventResult = await (sdk as any).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 that the SDK expects\n      return {\n        fileId,\n        transactionHash: txResult.hash,\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 { 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 a TransactionResult that the SDK expects\n      return 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":"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","names":["uuidv4"]}

package/dist/server/relayerHandler.d.ts

@@ -0,0 +1,38 @@
+import type { VanaInstance } from "../index.node";
+import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "../types/relayer";
+import type { TransactionOptions } from "../types";
+/**
+ * Universal handler for all relayer operations.
+ *
+ * This function processes both EIP-712 signed operations and direct operations,
+ * automatically routing to the appropriate SDK methods.
+ *
+ * @param sdk - Initialized Vana SDK instance
+ * @param request - The unified relayer request
+ * @returns Promise resolving to operation-specific response
+ *
+ * @category Server
+ * @example
+ * ```typescript
+ * // In your server endpoint (Next.js example):
+ * import { handleRelayerOperation } from '@opendatalabs/vana-sdk/node';
+ *
+ * export async function POST(request: NextRequest) {
+ *   try {
+ *     const body = await request.json();
+ *     const vana = getServerVanaInstance(); // Your server SDK instance
+ *
+ *     const result = await handleRelayerOperation(vana, body);
+ *
+ *     return NextResponse.json(result);
+ *   } catch (error) {
+ *     return NextResponse.json(
+ *       { error: error.message },
+ *       { status: 500 }
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare function handleRelayerOperation(sdk: VanaInstance, // The public signature is generic
+request: UnifiedRelayerRequest, options?: TransactionOptions): Promise<UnifiedRelayerResponse>;

package/dist/server/relayerHandler.js

@@ -0,0 +1,313 @@
+import { v4 as uuidv4 } from "uuid";
+import { SignatureError } from "../errors";
+import { recoverTypedDataAddress, getAddress } from "viem";
+async function handleRelayerOperation(sdk, request, options) {
+  const store = sdk.operationStore;
+  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 = sdk.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 = uuidv4();
+    try {
+      const txResult = await routeAndExecuteRequest(sdk, request, options);
+      if ("hash" in txResult) {
+        await store.set(operationId, {
+          status: "pending",
+          transactionHash: txResult.hash,
+          originalRequest: request,
+          nonce: options?.nonce,
+          retryCount: 0,
+          lastAttemptedGas: {
+            maxFeePerGas: options?.maxFeePerGas?.toString(),
+            maxPriorityFeePerGas: options?.maxPriorityFeePerGas?.toString()
+          },
+          submittedAt: Date.now()
+        });
+        return { type: "pending", operationId };
+      } else {
+        return { type: "direct", result: txResult };
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error("Unknown error during operation submission");
+      return { type: "error", error: error.message };
+    }
+  } else {
+    if (request.type === "status_check") {
+      return {
+        type: "error",
+        error: "Stateless relayer does not support operation status checks."
+      };
+    }
+    try {
+      const txResult = await routeAndExecuteRequest(sdk, request, options);
+      if ("hash" in txResult) {
+        return { type: "submitted", hash: txResult.hash };
+      } else {
+        return { type: "direct", result: txResult };
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error("Unknown error during operation submission");
+      return { type: "error", error: error.message };
+    }
+  }
+}
+async function routeAndExecuteRequest(sdk, request, options) {
+  if (request.type === "signed") {
+    const { typedData, signature, expectedUserAddress } = request;
+    let recoveredAddress;
+    try {
+      recoveredAddress = await 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 SignatureError(
+        `Signature verification failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+    if (expectedUserAddress) {
+      const normalizedExpected = getAddress(expectedUserAddress);
+      const normalizedSigner = getAddress(recoveredAddress);
+      if (normalizedSigner !== normalizedExpected) {
+        throw new SignatureError(
+          `Security verification failed: Recovered signer address (${normalizedSigner}) does not match expected user address (${normalizedExpected})`
+        );
+      }
+    }
+    return await routeSignedOperation(sdk, typedData, signature, options);
+  } else if (request.type === "direct") {
+    return await handleDirectOperation(sdk, request, options);
+  }
+  throw new Error("Invalid request type for execution");
+}
+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":
+      return sdk.permissions.submitSignedGrant(
+        {
+          ...typedData,
+          primaryType: "Permission"
+        },
+        signature,
+        options
+      );
+    case "RevokePermission":
+      return sdk.permissions.submitSignedRevoke(
+        {
+          ...typedData,
+          primaryType: "RevokePermission"
+        },
+        signature,
+        options
+      );
+    case "TrustServer":
+      return sdk.permissions.submitSignedTrustServer(
+        {
+          ...typedData,
+          primaryType: "TrustServer"
+        },
+        signature,
+        options
+      );
+    case "AddServer":
+      return sdk.permissions.submitSignedAddAndTrustServer(
+        {
+          ...typedData,
+          primaryType: "AddServer"
+        },
+        signature,
+        options
+      );
+    case "UntrustServer":
+      return sdk.permissions.submitSignedUntrustServer(
+        {
+          ...typedData,
+          primaryType: "UntrustServer"
+        },
+        signature,
+        options
+      );
+    case "ServerFilesAndPermission":
+      return sdk.permissions.submitSignedAddServerFilesAndPermissions(
+        {
+          ...typedData,
+          primaryType: "ServerFilesAndPermission"
+        },
+        signature,
+        options
+      );
+    // 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}. Supported types: Permission, RevokePermission, TrustServer, AddServer, UntrustServer, ServerFilesAndPermission`
+      );
+  }
+}
+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
+      );
+      return result;
+    }
+    case "submitFileAdditionWithPermissions": {
+      const { url, userAddress, permissions } = request.params;
+      const result = await sdk.data.addFileWithPermissions(
+        url,
+        userAddress,
+        permissions,
+        options
+      );
+      return result;
+    }
+    case "submitFileAdditionComplete": {
+      const { url, userAddress, permissions, schemaId, ownerAddress } = request.params;
+      const txResult = await sdk.data.addFileWithEncryptedPermissionsAndSchema(
+        url,
+        ownerAddress ?? userAddress,
+        permissions,
+        // Already in correct format with encrypted 'key' field
+        schemaId,
+        options
+      );
+      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 {
+        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 uploadResult = await context.storageManager.upload(
+        blob,
+        `grant-${Date.now()}.json`
+      );
+      return { url: uploadResult.url };
+    }
+    case "submitRegisterGrantee": {
+      const { owner, granteeAddress, publicKey } = request.params;
+      const result = await sdk.permissions.submitRegisterGrantee({
+        owner,
+        granteeAddress,
+        publicKey
+      });
+      return result;
+    }
+    default: {
+      const exhaustiveCheck = request;
+      return exhaustiveCheck;
+    }
+  }
+}
+export {
+  handleRelayerOperation
+};
+//# sourceMappingURL=relayerHandler.js.map

package/dist/server/relayerHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/relayerHandler.ts"],"sourcesContent":["import { v4 as uuidv4 } from \"uuid\";\nimport type { VanaInstance } from \"../index.node\";\nimport type {\n  UnifiedRelayerRequest,\n  UnifiedRelayerResponse,\n  DirectRelayerRequest,\n} from \"../types/relayer\";\nimport type {\n  TransactionResult,\n  TransactionOptions,\n  IOperationStore,\n  OperationState,\n  TransactionReceipt,\n} from \"../types\";\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 * 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, // The public signature is generic\n  request: UnifiedRelayerRequest,\n  options?: TransactionOptions,\n): Promise<UnifiedRelayerResponse> {\n  // Type assertion required: VanaInstance public interface doesn't expose operationStore\n  // to maintain API simplicity, but server-side handler needs access for stateful mode.\n  // The factory overloads guarantee this is safe for relayer-configured instances.\n  // TODO(TYPES): Consider exposing operationStore through a server-specific interface\n\n  const store = (sdk as any).operationStore as IOperationStore | undefined;\n\n  // --- STATEFUL (ROBUST) MODE ---\n  // This block executes ONLY if the developer provided an IOperationStore.\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          // The SDK stores it as a direct property\n          const publicClient = (sdk as any).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    try {\n      const txResult = await routeAndExecuteRequest(sdk, request, options);\n      // We only store state for operations that result in a transaction.\n      if (\"hash\" in txResult) {\n        await store.set(operationId, {\n          status: \"pending\",\n          transactionHash: txResult.hash,\n          originalRequest: request,\n          nonce: options?.nonce,\n          retryCount: 0,\n          lastAttemptedGas: {\n            maxFeePerGas: options?.maxFeePerGas?.toString(),\n            maxPriorityFeePerGas: options?.maxPriorityFeePerGas?.toString(),\n          },\n          submittedAt: Date.now(),\n        });\n        return { type: \"pending\", operationId };\n      } else {\n        // This handles non-transactional direct operations like `storeGrantFile`\n        return { type: \"direct\", result: txResult };\n      }\n    } catch (e) {\n      const error =\n        e instanceof Error\n          ? e\n          : new Error(\"Unknown error during operation submission\");\n      // We don't create a persistent error state for an initial submission failure.\n      return { type: \"error\", error: error.message };\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 txResult = await routeAndExecuteRequest(sdk, request, options);\n\n      // For stateless relayers, we can only handle transactional results.\n      if (\"hash\" in txResult) {\n        return { type: \"submitted\", hash: txResult.hash };\n      } else {\n        // Non-transactional direct operations can return their result directly.\n        return { type: \"direct\", result: txResult };\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<\n  | TransactionResult<Contract, Fn<Contract>>\n  | { url: string }\n  | { fileId: number; transactionHash: Hash }\n> {\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    return await routeSignedOperation(sdk, typedData, signature, options);\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\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<\n  | TransactionResult<Contract, Fn<Contract>>\n  | { url: string }\n  | { fileId: number; transactionHash: Hash }\n> {\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 the TransactionResult directly\n      return 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 the TransactionResult directly\n      return 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      // The SDK has waitForTransactionEvents as a public method\n      const eventResult = await (sdk as any).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 that the SDK expects\n      return {\n        fileId,\n        transactionHash: txResult.hash,\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 { 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 a TransactionResult that the SDK expects\n      return 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":"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","names":[]}

package/dist/storage/index.d.ts

@@ -1,10 +1,56 @@
-export { StorageError, StorageFile, StorageListOptions, StorageProvider, StorageProviderConfig, StorageUploadResult } from '../types/storage.js';
-export { GoogleDriveStorage } from './providers/google-drive.js';
-export { IpfsStorage } from './providers/ipfs.js';
-export { PinataStorage } from './providers/pinata.js';
-export { CallbackStorage } from './providers/callback-storage.js';
-export { StorageManager } from './manager.js';
-export { StorageCallbacks, StorageDownloadOptions, StorageListResult } from '../types/config.js';
-import 'viem';
-import '../types/chains.js';
-import '../types/permissions.js';
+/**
+ * Storage API for Vana SDK
+ *
+ * Provides unified interface for different storage providers
+ * to upload, download, and manage user data files.
+ *
+ * ## Storage Provider Decision Tree
+ *
+ * Choose your storage provider based on your needs:
+ *
+ * **Need full CRUD operations and metadata?**
+ * - ✅ Use `PinataStorage` - Managed IPFS with listing, deletion, and rich metadata
+ *
+ * **Want to use your own IPFS infrastructure?**
+ * - ✅ Use `IpfsStorage.forInfura()` - Connect to Infura IPFS service
+ * - ✅ Use `IpfsStorage.forLocalNode()` - Connect to local IPFS node
+ * - ✅ Use `new IpfsStorage()` - Connect to any IPFS-compatible service
+ *
+ * **Want flexible callback-based storage?**
+ * - ✅ Use `CallbackStorage` - Implement storage via custom callbacks (HTTP, WebSocket, etc.)
+ *
+ * **Need Google Drive integration?**
+ * - ✅ Use `GoogleDriveStorage` - Direct Google Drive API with folder management
+ *
+ * @example
+ * ```typescript
+ * // Managed IPFS with full features
+ * const pinata = new PinataStorage({ jwt: "your-jwt" });
+ *
+ * // Standard IPFS with Infura
+ * const ipfs = IpfsStorage.forInfura({ projectId: "...", projectSecret: "..." });
+ *
+ * // Callback-based storage (flexible)
+ * const storage = new CallbackStorage({
+ *   async upload(blob, filename) {
+ *     // Your custom upload logic
+ *     const response = await fetch('/api/upload', { method: 'POST', body: blob });
+ *     const data = await response.json();
+ *     return { url: data.url, size: blob.size, contentType: blob.type };
+ *   },
+ *   async download(identifier) {
+ *     // Your custom download logic
+ *     const response = await fetch(`/api/download/${identifier}`);
+ *     return response.blob();
+ *   }
+ * });
+ * ```
+ */
+export type { StorageProvider, StorageUploadResult, StorageFile, StorageListOptions, StorageProviderConfig, } from "../types/storage";
+export { StorageError } from "../types/storage";
+export { GoogleDriveStorage } from "./providers/google-drive";
+export { IpfsStorage } from "./providers/ipfs";
+export { PinataStorage } from "./providers/pinata";
+export { CallbackStorage } from "./providers/callback-storage";
+export { StorageManager } from "./manager";
+export type { StorageCallbacks, StorageDownloadOptions, StorageListResult, } from "../types/config";