@opendatalabs/vana-sdk 0.1.0-alpha.761813a → 0.1.0-alpha.8eb4e46

package/dist/index.node.js

@@ -251,65 +251,9 @@ var init_browser = __esm({
         try {
           const eccrypto2 = await import("eccrypto-js");
           const uncompressedKey = processWalletPublicKey(publicKey);
-          const iv = Buffer.from([
-            1,
-            2,
-            3,
-            4,
-            5,
-            6,
-            7,
-            8,
-            9,
-            10,
-            11,
-            12,
-            13,
-            14,
-            15,
-            16
-          ]);
-          const ephemeralKey = Buffer.from([
-            17,
-            34,
-            51,
-            68,
-            85,
-            102,
-            119,
-            136,
-            153,
-            170,
-            187,
-            204,
-            221,
-            238,
-            255,
-            0,
-            16,
-            32,
-            48,
-            64,
-            80,
-            96,
-            112,
-            128,
-            144,
-            160,
-            176,
-            192,
-            208,
-            224,
-            240,
-            0
-          ]);
           const encryptedBuffer = await eccrypto2.encrypt(
             uncompressedKey,
-            Buffer.from(data),
-            {
-              iv,
-              ephemPrivateKey: ephemeralKey
-            }
+            Buffer.from(data)
           );
           const result = Buffer.concat([
             encryptedBuffer.iv,
@@ -678,6 +622,9 @@ function isWalletConfig(config) {
 function isChainConfig(config) {
   return "chainId" in config && !("walletClient" in config);
 }
+function hasStorageConfig(config) {
+  return config.storage?.providers !== void 0 && Object.keys(config.storage.providers).length > 0;
+}
 
 // src/types/chains.ts
 function isVanaChainId(chainId) {
@@ -973,55 +920,6 @@ function isReplicateAPIResponse(value) {
     obj.status
   );
 }
-function isIdentityServerOutput(value) {
-  console.debug("\u{1F50D} Type Guard: Checking value:", value);
-  console.debug("\u{1F50D} Type Guard: Value type:", typeof value);
-  if (typeof value !== "object" || value === null) {
-    console.debug("\u{1F50D} Type Guard: Failed - not object or null");
-    return false;
-  }
-  const obj = value;
-  console.debug("\u{1F50D} Type Guard: Object keys:", Object.keys(obj));
-  console.debug(
-    "\u{1F50D} Type Guard: user_address:",
-    obj.user_address,
-    typeof obj.user_address
-  );
-  if (typeof obj.user_address !== "string") {
-    console.debug("\u{1F50D} Type Guard: Failed - user_address not string");
-    return false;
-  }
-  console.debug(
-    "\u{1F50D} Type Guard: personal_server:",
-    obj.personal_server,
-    typeof obj.personal_server
-  );
-  if (typeof obj.personal_server !== "object" || obj.personal_server === null) {
-    console.debug("\u{1F50D} Type Guard: Failed - personal_server not object or null");
-    return false;
-  }
-  const personalServer = obj.personal_server;
-  console.debug(
-    "\u{1F50D} Type Guard: Personal server keys:",
-    Object.keys(personalServer)
-  );
-  console.debug("\u{1F50D} Type Guard: address:", personalServer.address);
-  console.debug("\u{1F50D} Type Guard: public_key:", personalServer.public_key);
-  const hasAddress = "address" in personalServer;
-  const hasPublicKey = "public_key" in personalServer;
-  console.debug(
-    "\u{1F50D} Type Guard: Has address:",
-    hasAddress,
-    "Has public_key:",
-    hasPublicKey
-  );
-  return hasAddress && hasPublicKey;
-}
-function isPersonalServerOutput(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const obj = value;
-  return "user_address" in obj && "identity" in obj && typeof obj.user_address === "string" && typeof obj.identity === "object";
-}
 function isAPIResponse(value) {
   if (typeof value !== "object" || value === null) return false;
   const obj = value;
@@ -33614,7 +33512,7 @@ function getAbi(contract) {
 import { keccak256, toHex } from "viem";
 function createGrantFile(params) {
   const grantFile = {
-    grantee: params.to,
+    grantee: params.grantee,
     operation: params.operation,
     parameters: params.parameters
   };
@@ -34034,7 +33932,7 @@ var PermissionsController = class {
    * @example
    * ```typescript
    * const txHash = await vana.permissions.grant({
-   *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+   *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
    *   operation: "llm_inference",
    *   parameters: {
    *     model: "gpt-4",
@@ -34063,7 +33961,7 @@ var PermissionsController = class {
    * @example
    * ```typescript
    * const { preview, confirm } = await vana.permissions.prepareGrant({
-   *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+   *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
    *   operation: "llm_inference",
    *   files: [1, 2, 3],
    *   parameters: { model: "gpt-4", prompt: "Analyze my social media data" }
@@ -34112,9 +34010,13 @@ var PermissionsController = class {
       console.debug("\u{1F50D} Debug - Grant URL from params:", grantUrl);
       if (!grantUrl) {
         if (!this.context.relayerCallbacks?.storeGrantFile && !this.context.storageManager) {
-          throw new Error(
-            "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
-          );
+          if (this.context.validateStorageRequired) {
+            this.context.validateStorageRequired();
+          } else {
+            throw new Error(
+              "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
+            );
+          }
         }
         if (this.context.relayerCallbacks?.storeGrantFile) {
           grantUrl = await this.context.relayerCallbacks.storeGrantFile(grantFile);
@@ -34138,7 +34040,7 @@ var PermissionsController = class {
         grantUrl
       );
       const typedData = await this.composePermissionGrantMessage({
-        to: params.to,
+        grantee: params.grantee,
         operation: params.operation,
         // Placeholder - real data is in IPFS
         files: params.files,
@@ -34185,7 +34087,7 @@ var PermissionsController = class {
    * @example
    * ```typescript
    * const { typedData, signature } = await vana.permissions.createAndSign({
-   *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+   *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
    *   operation: "data_analysis",
    *   parameters: { analysisType: "sentiment" },
    * });
@@ -34201,9 +34103,13 @@ var PermissionsController = class {
       console.debug("\u{1F50D} Debug - Grant URL from params:", grantUrl);
       if (!grantUrl) {
         if (!this.context.relayerCallbacks?.storeGrantFile && !this.context.storageManager) {
-          throw new Error(
-            "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
-          );
+          if (this.context.validateStorageRequired) {
+            this.context.validateStorageRequired();
+          } else {
+            throw new Error(
+              "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
+            );
+          }
         }
         if (this.context.relayerCallbacks?.storeGrantFile) {
           grantUrl = await this.context.relayerCallbacks.storeGrantFile(grantFile);
@@ -34227,7 +34133,7 @@ var PermissionsController = class {
         grantUrl
       );
       const typedData = await this.composePermissionGrantMessage({
-        to: params.to,
+        grantee: params.grantee,
         operation: params.operation,
         // Placeholder - real data is in IPFS
         files: params.files,
@@ -34578,7 +34484,7 @@ var PermissionsController = class {
    * Composes the EIP-712 typed data for PermissionGrant (new simplified format).
    *
    * @param params - The parameters for composing the permission grant message
-   * @param params.to - The recipient address for the permission grant
+   * @param params.grantee - The recipient address for the permission grant
    * @param params.operation - The type of operation being granted permission for
    * @param params.files - Array of file IDs that the permission applies to
    * @param params.grantUrl - URL where the grant details are stored
@@ -34671,36 +34577,45 @@ var PermissionsController = class {
     return addresses[0];
   }
   /**
-   * Retrieves all permissions granted by the current user using subgraph queries.
+   * Gets on-chain permission grant data without expensive off-chain resolution.
    *
    * @remarks
-   * This method queries the Vana subgraph to find permissions directly granted by the user
-   * using the Permission entity. It efficiently handles millions of permissions by leveraging
-   * indexed subgraph data instead of scanning contract logs. The method fetches complete
-   * grant files from IPFS to provide detailed permission information including operation
-   * parameters and grantee details.
-   * @param params - Optional query parameters
-   * @param params.limit - Maximum number of permissions to return (default: 50)
-   * @param params.subgraphUrl - Optional subgraph URL to override the default endpoint
-   * @returns A Promise that resolves to an array of `GrantedPermission` objects
-   * @throws {BlockchainError} When subgraph is unavailable or returns invalid data
+   * This method provides a fast, performance-focused way to retrieve permission grants
+   * by querying only the subgraph without making expensive IPFS or individual contract calls.
+   * It eliminates the N+1 query problem of the legacy `getUserPermissions()` method.
+   *
+   * The returned data contains all on-chain information but does NOT include resolved
+   * operation details, parameters, or file IDs. Use `retrieveGrantFile()` separately
+   * for specific grants when detailed data is needed.
+   *
+   * **Performance**: Completes in ~100-500ms regardless of permission count.
+   * **Reliability**: Single point of failure (subgraph) with clear RPC fallback path.
+   *
+   * @param options - Options for retrieving permissions (limit, subgraph URL)
+   * @returns A Promise that resolves to an array of `OnChainPermissionGrant` objects
+   * @throws {BlockchainError} When subgraph query fails
+   * @throws {NetworkError} When network requests fail
    * @example
    * ```typescript
-   * // Get all permissions granted by current user
-   * const permissions = await vana.permissions.getUserPermissions();
+   * // Fast: Get all on-chain permission data
+   * const grants = await vana.permissions.getUserPermissionGrantsOnChain({ limit: 20 });
    *
-   * permissions.forEach(permission => {
-   *   console.log(`Granted ${permission.operation} to ${permission.grantee}`);
+   * // Display in UI immediately
+   * grants.forEach(grant => {
+   *   console.log(`Permission ${grant.id}: ${grant.grantUrl}`);
    * });
    *
-   * // Limit results
-   * const recent = await vana.permissions.getUserPermissions({ limit: 10 });
+   * // Lazy load detailed data for specific permission when user clicks
+   * const grantFile = await retrieveGrantFile(grants[0].grantUrl);
+   * console.log(`Operation: ${grantFile.operation}`);
+   * console.log(`Parameters:`, grantFile.parameters);
    * ```
    */
-  async getUserPermissions(params) {
+  async getUserPermissionGrantsOnChain(options = {}) {
+    const { limit = 50, subgraphUrl } = options;
     try {
       const userAddress = await this.getUserAddress();
-      const graphqlEndpoint = params?.subgraphUrl || this.context.subgraphUrl;
+      const graphqlEndpoint = subgraphUrl || this.context.subgraphUrl;
       if (!graphqlEndpoint) {
         throw new BlockchainError(
           "subgraphUrl is required. Please provide a valid subgraph endpoint or configure it in Vana constructor."
@@ -34722,16 +34637,6 @@ var PermissionsController = class {
           }
         }
       `;
-      console.info("Query:", query);
-      console.info(
-        "Body:",
-        JSON.stringify({
-          query,
-          variables: {
-            userId: userAddress.toLowerCase()
-          }
-        })
-      );
       const response = await fetch(graphqlEndpoint, {
         method: "POST",
         headers: {
@@ -34750,7 +34655,6 @@ var PermissionsController = class {
         );
       }
       const result = await response.json();
-      console.info("Result:", result);
       if (result.errors) {
         throw new BlockchainError(
           `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
@@ -34758,64 +34662,32 @@ var PermissionsController = class {
       }
       const userData = result.data?.user;
       if (!userData || !userData.permissions?.length) {
-        console.warn("No permissions found for user:", userAddress);
         return [];
       }
-      const userPermissions = [];
-      const limit = params?.limit || 50;
-      const permissionsToProcess = userData.permissions.slice(0, limit);
-      for (const permission of permissionsToProcess) {
-        try {
-          let operation;
-          let files = [];
-          let parameters;
-          let granteeAddress;
-          try {
-            const grantFile = await retrieveGrantFile(permission.grant);
-            operation = grantFile.operation;
-            parameters = grantFile.parameters;
-            granteeAddress = grantFile.grantee;
-          } catch {
-          }
-          try {
-            const fileIds = await this.getPermissionFileIds(
-              BigInt(permission.id)
-            );
-            files = fileIds.map((id) => Number(id));
-          } catch {
-          }
-          userPermissions.push({
-            id: BigInt(permission.id),
-            files,
-            operation: operation || "",
-            parameters: parameters || {},
-            grant: permission.grant,
-            grantor: userAddress.toLowerCase(),
-            // Current user is the grantor
-            grantee: granteeAddress || userAddress,
-            // Application that received permission
-            active: true,
-            // Default to active if not specified
-            grantedAt: Number(permission.addedAtBlock),
-            nonce: Number(permission.nonce)
-          });
-        } catch (error) {
-          console.error(
-            "SDK Error: Failed to process permission:",
-            permission.id,
-            error
-          );
-        }
-      }
-      return userPermissions.sort((a, b) => {
+      const onChainGrants = userData.permissions.slice(0, limit).map((permission) => ({
+        id: BigInt(permission.id),
+        grantUrl: permission.grant,
+        grantSignature: permission.grantSignature,
+        grantHash: permission.grantHash,
+        nonce: BigInt(permission.nonce),
+        addedAtBlock: BigInt(permission.addedAtBlock),
+        addedAtTimestamp: BigInt(permission.addedAtTimestamp || "0"),
+        transactionHash: permission.transactionHash || "",
+        grantor: userAddress,
+        active: true
+        // TODO: Add revocation status from subgraph when available
+      }));
+      return onChainGrants.sort((a, b) => {
         if (a.id < b.id) return 1;
         if (a.id > b.id) return -1;
         return 0;
       });
     } catch (error) {
-      console.error("Failed to fetch user permissions:", error);
+      if (error instanceof BlockchainError || error instanceof NetworkError) {
+        throw error;
+      }
       throw new BlockchainError(
-        `Failed to fetch user permissions: ${error instanceof Error ? error.message : "Unknown error"}`
+        `Failed to fetch user permission grants: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -35577,32 +35449,19 @@ async function decryptWithPrivateKey(encryptedData, privateKey, platformAdapter)
     throw new Error(`Failed to decrypt with private key: ${error}`);
   }
 }
-async function encryptUserData(data, walletSignature, platformAdapter) {
+async function encryptBlobWithSignedKey(data, key, platformAdapter) {
   try {
     const dataBuffer = data instanceof Blob ? await data.arrayBuffer() : new TextEncoder().encode(data);
     const dataArray = new Uint8Array(dataBuffer);
     const encrypted = await platformAdapter.crypto.encryptWithPassword(
       dataArray,
-      walletSignature
+      key
     );
     return new Blob([encrypted], {
       type: "application/octet-stream"
     });
   } catch (error) {
-    throw new Error(`Failed to encrypt user data: ${error}`);
-  }
-}
-async function decryptUserData(encryptedData, walletSignature, platformAdapter) {
-  try {
-    const encryptedBuffer = encryptedData instanceof Blob ? await encryptedData.arrayBuffer() : new TextEncoder().encode(encryptedData);
-    const encryptedArray = new Uint8Array(encryptedBuffer);
-    const decrypted = await platformAdapter.crypto.decryptWithPassword(
-      encryptedArray,
-      walletSignature
-    );
-    return new Blob([decrypted], { type: "text/plain" });
-  } catch (error) {
-    throw new Error(`Failed to decrypt user data: ${error}`);
+    throw new Error(`Failed to encrypt data: ${error}`);
   }
 }
 async function generateEncryptionKeyPair(platformAdapter) {
@@ -35619,60 +35478,25 @@ async function generatePGPKeyPair(platformAdapter, options) {
     throw new Error(`Failed to generate PGP key pair: ${error}`);
   }
 }
+async function decryptBlobWithSignedKey(encryptedData, key, platformAdapter) {
+  try {
+    const encryptedBuffer = encryptedData instanceof Blob ? await encryptedData.arrayBuffer() : new TextEncoder().encode(encryptedData);
+    const encryptedArray = new Uint8Array(encryptedBuffer);
+    const decrypted = await platformAdapter.crypto.decryptWithPassword(
+      encryptedArray,
+      key
+    );
+    return new Blob([decrypted], { type: "text/plain" });
+  } catch (error) {
+    throw new Error(`Failed to decrypt data: ${error}`);
+  }
+}
 
 // src/controllers/data.ts
 var DataController = class {
   constructor(context) {
     this.context = context;
   }
-  /**
-   * Uploads user data with automatic encryption and blockchain registration.
-   *
-   * @remarks
-   * This is the primary method for uploading user data to the Vana network. It handles
-   * the complete workflow including content normalization, schema validation, encryption,
-   * storage upload, permission granting, and blockchain registration.
-   *
-   * The method automatically:
-   * - Normalizes input content to a Blob
-   * - Validates data against schema if provided
-   * - Generates encryption keys and encrypts the data
-   * - Uploads to the configured storage provider
-   * - Grants permissions to specified applications
-   * - Registers the file on the blockchain
-   *
-   * @param params - Upload parameters including content, filename, schema, and permissions
-   * @returns Promise resolving to upload results with file ID and transaction hash
-   * @throws {Error} When wallet is not connected or storage is not configured
-   * @throws {SchemaValidationError} When schema validation fails
-   * @throws {Error} When upload or blockchain registration fails
-   * @example
-   * ```typescript
-   * // Basic file upload
-   * const result = await vana.data.upload({
-   *   content: "My personal data",
-   *   filename: "diary.txt"
-   * });
-   *
-   * // Upload with schema validation
-   * const result = await vana.data.upload({
-   *   content: { name: "John", age: 30 },
-   *   filename: "profile.json",
-   *   schemaId: 1
-   * });
-   *
-   * // Upload with permissions
-   * const result = await vana.data.upload({
-   *   content: "Data for AI analysis",
-   *   filename: "analysis.txt",
-   *   permissions: [{
-   *     to: "0x1234...",
-   *     operation: "llm_inference",
-   *     parameters: { model: "gpt-4" }
-   *   }]
-   * });
-   * ```
-   */
   async upload(params) {
     const {
       content,
@@ -35680,7 +35504,8 @@ var DataController = class {
       schemaId,
       permissions = [],
       encrypt: encrypt3 = true,
-      providerName
+      providerName,
+      owner
     } = params;
     try {
       let blob;
@@ -35737,23 +35562,28 @@ var DataController = class {
           this.context.walletClient,
           DEFAULT_ENCRYPTION_SEED
         );
-        finalBlob = await encryptUserData(
+        finalBlob = await encryptBlobWithSignedKey(
           blob,
           encryptionKey,
           this.context.platform
         );
       }
       if (!this.context.storageManager) {
-        throw new Error(
-          "Storage manager not configured. Please provide storage providers in VanaConfig."
-        );
+        if (this.context.validateStorageRequired) {
+          this.context.validateStorageRequired();
+          throw new Error("Storage validation failed");
+        } else {
+          throw new Error(
+            "Storage manager not configured. Please provide storage providers in VanaConfig."
+          );
+        }
       }
       const uploadResult = await this.context.storageManager.upload(
         finalBlob,
         filename,
         providerName
       );
-      const userAddress = await this.getUserAddress();
+      const userAddress = owner || await this.getUserAddress();
       let encryptedPermissions = [];
       if (permissions.length > 0 && encrypt3) {
         const userEncryptionKey = await generateEncryptionKey(
@@ -35765,7 +35595,7 @@ var DataController = class {
             const publicKey = permission.publicKey;
             if (!publicKey) {
               throw new Error(
-                `Public key required for permission to ${permission.to}`
+                `Public key required for permission to ${permission.grantee} when encryption is enabled`
               );
             }
             const encryptedKey = await encryptWithWalletPublicKey(
@@ -35774,7 +35604,7 @@ var DataController = class {
               this.context.platform
             );
             return {
-              account: permission.to,
+              account: permission.grantee,
               key: encryptedKey
             };
           })
@@ -35787,7 +35617,8 @@ var DataController = class {
             url: uploadResult.url,
             userAddress,
             permissions: encryptedPermissions,
-            schemaId: schemaId || 0
+            schemaId: schemaId || 0,
+            ownerAddress: owner
           }
         );
       } else if (this.context.relayerCallbacks?.submitFileAddition) {
@@ -35823,6 +35654,142 @@ var DataController = class {
       );
     }
   }
+  /**
+   * Decrypts a file owned by the user using their wallet signature.
+   *
+   * @remarks
+   * This is the high-level convenience method for decrypting user files, serving as the
+   * symmetrical counterpart to the `upload` method. It handles the complete decryption
+   * workflow including key generation, URL protocol detection, content fetching, and
+   * decryption.
+   *
+   * The method automatically:
+   * - Generates the decryption key from the user's wallet signature
+   * - Determines the appropriate fetch method based on the file URL protocol
+   * - Fetches the encrypted content from IPFS or standard HTTP URLs
+   * - Decrypts the content using the generated key
+   *
+   * For IPFS URLs, the method uses gateway fallback for improved reliability. For
+   * standard HTTP URLs, it uses a simple fetch. If you need custom authentication
+   * headers or specific gateway configurations, use the low-level primitives directly.
+   *
+   * @param file - The user file to decrypt (typically from getUserFiles)
+   * @param encryptionSeed - Optional custom encryption seed (defaults to Vana standard)
+   * @returns Promise resolving to the decrypted file content as a Blob
+   * @throws {Error} When the wallet is not connected
+   * @throws {Error} When fetching the encrypted content fails
+   * @throws {Error} When decryption fails (wrong key or corrupted data)
+   * @example
+   * ```typescript
+   * // Basic file decryption
+   * const files = await vana.data.getUserFiles({ owner: userAddress });
+   * const decryptedBlob = await vana.data.decryptFile(files[0]);
+   *
+   * // Convert to text
+   * const text = await decryptedBlob.text();
+   * console.log('Decrypted content:', text);
+   *
+   * // Convert to JSON
+   * const json = JSON.parse(await decryptedBlob.text());
+   * console.log('Decrypted data:', json);
+   *
+   * // With custom encryption seed
+   * const decryptedBlob = await vana.data.decryptFile(
+   *   files[0],
+   *   "My custom encryption seed"
+   * );
+   *
+   * // Save to file (in Node.js)
+   * const buffer = await decryptedBlob.arrayBuffer();
+   * fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
+   * ```
+   */
+  async decryptFile(file, encryptionSeed) {
+    try {
+      const encryptionKey = await generateEncryptionKey(
+        this.context.walletClient,
+        encryptionSeed || DEFAULT_ENCRYPTION_SEED
+      );
+      let encryptedBlob;
+      try {
+        if (file.url.startsWith("ipfs://")) {
+          encryptedBlob = await this.fetchFromIPFS(file.url);
+        } else {
+          encryptedBlob = await this.fetch(file.url);
+        }
+      } catch (fetchError) {
+        const errorMessage = fetchError instanceof Error ? fetchError.message : "Unknown error";
+        if (errorMessage.includes("Failed to fetch IPFS content") && errorMessage.includes("from all gateways")) {
+          throw new Error(
+            "Network error: Cannot access the file URL. The file may be stored on a server that's not accessible or has CORS restrictions."
+          );
+        } else if (errorMessage.includes("Empty response")) {
+          throw new Error("File is empty or could not be retrieved");
+        } else if (errorMessage.includes("Network error:") || errorMessage.includes("Failed to fetch")) {
+          throw new Error(
+            "Network error: Cannot access the file URL. The file may be stored on a server that's not accessible or has CORS restrictions."
+          );
+        } else if (errorMessage.includes("HTTP error!")) {
+          const statusMatch = errorMessage.match(/status: (\d+)/);
+          const status = statusMatch ? statusMatch[1] : "unknown";
+          if (status === "500") {
+            throw new Error(
+              "Network error: Cannot access the file URL. The file may be stored on a server that's not accessible or has CORS restrictions."
+            );
+          } else if (status === "403") {
+            throw new Error(
+              "Access denied. You may not have permission to access this file"
+            );
+          } else if (status === "404") {
+            throw new Error(
+              "File not found: The encrypted file is no longer available at the stored URL."
+            );
+          } else {
+            throw new Error(
+              "Network error: Cannot access the file URL. The file may be stored on a server that's not accessible or has CORS restrictions."
+            );
+          }
+        }
+        throw fetchError;
+      }
+      if (encryptedBlob.size === 0) {
+        throw new Error("File is empty or could not be retrieved");
+      }
+      let decryptedBlob;
+      try {
+        decryptedBlob = await decryptBlobWithSignedKey(
+          encryptedBlob,
+          encryptionKey,
+          this.context.platform
+        );
+      } catch (decryptError) {
+        const errorMessage = decryptError instanceof Error ? decryptError.message : "Unknown error";
+        if (errorMessage.includes("not a valid OpenPGP message")) {
+          throw new Error(
+            "Invalid file format: This file doesn't appear to be encrypted with the Vana protocol"
+          );
+        } else if (errorMessage.includes("Session key decryption failed")) {
+          throw new Error("Wrong encryption key");
+        } else if (errorMessage.includes("Error decrypting message")) {
+          throw new Error("Wrong encryption key");
+        } else if (errorMessage.includes("File not found")) {
+          throw new Error(
+            "File not found: The encrypted file is no longer available"
+          );
+        } else {
+          throw decryptError;
+        }
+      }
+      return decryptedBlob;
+    } catch (error) {
+      if (error instanceof Error && (error.message.includes("Network error:") || error.message.includes("Invalid file format:") || error.message.includes("Wrong encryption key") || error.message.includes("Access denied") || error.message.includes("File not found:") || error.message.includes("File is empty"))) {
+        throw error;
+      }
+      throw new Error(
+        `Failed to decrypt file: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
   /**
    * Retrieves all data files owned by a specific user address.
    *
@@ -36573,81 +36540,6 @@ var DataController = class {
       );
     }
   }
-  /**
-   * Decrypts a file that was encrypted using the Vana protocol.
-   *
-   * @param file - The UserFile object containing the file URL and metadata
-   * @param encryptionSeed - Optional custom encryption seed (defaults to Vana standard)
-   * @returns Promise resolving to the decrypted file as a Blob
-   *
-   * This method handles the complete flow of:
-   * 1. Generating the encryption key from the user's wallet signature
-   * 2. Fetching the encrypted file from the stored URL
-   * 3. Decrypting the file using the canonical Vana decryption method
-   */
-  async decryptFile(file, encryptionSeed = DEFAULT_ENCRYPTION_SEED) {
-    try {
-      const encryptionKey = await generateEncryptionKey(
-        this.context.walletClient,
-        encryptionSeed
-      );
-      const fetchUrl = this.convertToDownloadUrl(file.url);
-      console.debug(
-        `Fetching encrypted file from URL: ${fetchUrl} (original: ${file.url})`
-      );
-      const response = await fetch(fetchUrl);
-      if (!response.ok) {
-        if (response.status === 404) {
-          throw new Error(
-            "File not found. The encrypted file may have been moved or deleted."
-          );
-        } else if (response.status === 403) {
-          throw new Error(
-            "Access denied. You may not have permission to access this file."
-          );
-        } else {
-          throw new Error(
-            `Network error: ${response.status} ${response.statusText}`
-          );
-        }
-      }
-      const encryptedBlob = await response.blob();
-      console.debug(
-        `Retrieved blob of size: ${encryptedBlob.size} bytes, type: ${encryptedBlob.type}`
-      );
-      if (encryptedBlob.size === 0) {
-        throw new Error("File is empty or could not be retrieved.");
-      }
-      const decryptedBlob = await decryptUserData(
-        encryptedBlob,
-        encryptionKey,
-        this.context.platform
-      );
-      return decryptedBlob;
-    } catch (error) {
-      console.error("Failed to decrypt file:", error);
-      if (error instanceof Error) {
-        if (error.message.includes("Session key decryption failed") || error.message.includes("Error decrypting message")) {
-          throw new Error(
-            "Wrong encryption key. This file may have been encrypted with a different wallet or encryption seed. Try using the same wallet that originally encrypted this file."
-          );
-        } else if (error.message.includes("Failed to fetch") || error.message.includes("Network error")) {
-          throw new Error(
-            "Network error: Cannot access the file URL. The file may be stored on a server that's not accessible or has CORS restrictions."
-          );
-        } else if (error.message.includes("File not found")) {
-          throw new Error(
-            "File not found: The encrypted file is no longer available at the stored URL."
-          );
-        } else if (error.message.includes("not a valid OpenPGP message") || error.message.includes("does not conform to a valid OpenPGP format")) {
-          throw new Error(
-            "Invalid file format: This file doesn't appear to be encrypted with the Vana protocol."
-          );
-        }
-      }
-      throw error;
-    }
-  }
   /**
    * Registers a file URL directly on the blockchain with a schema ID.
    *
@@ -36708,26 +36600,6 @@ var DataController = class {
       );
     }
   }
-  /**
-   * Converts IPFS and Google Drive URLs to direct download URLs for fetching.
-   *
-   * @param url - The URL to convert to a direct download URL
-   * @returns The converted direct download URL or the original URL if not a special URL
-   */
-  convertToDownloadUrl(url) {
-    if (url.startsWith("ipfs://")) {
-      const hash = url.replace("ipfs://", "");
-      return `https://ipfs.io/ipfs/${hash}`;
-    }
-    if (url.includes("drive.google.com/file/d/")) {
-      const fileIdMatch = url.match(/\/file\/d\/([a-zA-Z0-9-_]+)/);
-      if (fileIdMatch) {
-        const fileId = fileIdMatch[1];
-        return `https://drive.google.com/uc?id=${fileId}&export=download`;
-      }
-    }
-    return url;
-  }
   /**
    * Gets the user's address from the wallet client.
    *
@@ -37221,7 +37093,7 @@ var DataController = class {
         this.context.walletClient,
         DEFAULT_ENCRYPTION_SEED
       );
-      const encryptedData = await encryptUserData(
+      const encryptedData = await encryptBlobWithSignedKey(
         data,
         userEncryptionKey,
         this.context.platform
@@ -37385,12 +37257,13 @@ var DataController = class {
         privateKey,
         this.context.platform
       );
-      const response = await fetch(this.convertToDownloadUrl(file.url));
-      if (!response.ok) {
-        throw new Error(`Failed to download file: ${response.statusText}`);
+      let encryptedData;
+      if (file.url.startsWith("ipfs://")) {
+        encryptedData = await this.fetchFromIPFS(file.url);
+      } else {
+        encryptedData = await this.fetch(file.url);
       }
-      const encryptedData = await response.blob();
-      const decryptedData = await decryptUserData(
+      const decryptedData = await decryptBlobWithSignedKey(
         encryptedData,
         userEncryptionKey,
         this.context.platform
@@ -37403,6 +37276,162 @@ var DataController = class {
       );
     }
   }
+  /**
+   * Simple network-agnostic fetch utility for retrieving file content.
+   *
+   * @remarks
+   * This is a thin wrapper around the global fetch API that returns the response as a Blob.
+   * It provides a consistent interface for fetching encrypted content before decryption.
+   * For IPFS URLs, consider using fetchFromIPFS for better reliability.
+   *
+   * @param url - The URL to fetch content from
+   * @returns Promise resolving to the fetched content as a Blob
+   * @throws {Error} When the fetch fails or returns a non-ok response
+   *
+   * @example
+   * ```typescript
+   * // Fetch and decrypt a file
+   * const encryptionKey = await generateEncryptionKey(walletClient);
+   * const encryptedBlob = await vana.data.fetch(file.url);
+   * const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
+   *
+   * // With custom headers for authentication
+   * const response = await fetch(file.url, {
+   *   headers: { 'Authorization': 'Bearer token' }
+   * });
+   * const encryptedBlob = await response.blob();
+   * ```
+   */
+  async fetch(url) {
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(
+          `HTTP error! status: ${response.status} ${response.statusText}`
+        );
+      }
+      const blob = await response.blob();
+      if (blob.size === 0) {
+        throw new Error("Empty response");
+      }
+      return blob;
+    } catch (error) {
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        throw new Error(
+          `Network error: Failed to fetch from ${url}. The URL may be invalid or the server may not be accessible.`
+        );
+      }
+      throw error;
+    }
+  }
+  /**
+   * Specialized IPFS fetcher with gateway fallback mechanism.
+   *
+   * @remarks
+   * This method provides robust IPFS content fetching by trying multiple gateways
+   * in sequence until one succeeds. It supports both ipfs:// URLs and raw CIDs.
+   *
+   * The default gateway list includes public gateways, but you should provide
+   * your own gateways for production use to ensure reliability and privacy.
+   *
+   * @param url - The IPFS URL (ipfs://...) or CID to fetch
+   * @param options - Optional configuration
+   * @param options.gateways - Array of IPFS gateway URLs to try (must end with /)
+   * @returns Promise resolving to the fetched content as a Blob
+   * @throws {Error} When all gateways fail to fetch the content
+   *
+   * @example
+   * ```typescript
+   * // Fetch from IPFS with custom gateways
+   * const encryptedBlob = await vana.data.fetchFromIPFS(file.url, {
+   *   gateways: [
+   *     'https://my-private-gateway.com/ipfs/',
+   *     'https://dweb.link/ipfs/',
+   *     'https://ipfs.io/ipfs/'
+   *   ]
+   * });
+   *
+   * // Decrypt the fetched content
+   * const encryptionKey = await generateEncryptionKey(walletClient);
+   * const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
+   *
+   * // With raw CID
+   * const blob = await vana.data.fetchFromIPFS('QmXxx...', {
+   *   gateways: ['https://ipfs.io/ipfs/']
+   * });
+   * ```
+   */
+  async fetchFromIPFS(url, options) {
+    const defaultGateways = [
+      "https://dweb.link/ipfs/",
+      "https://ipfs.io/ipfs/"
+    ];
+    const gateways = options?.gateways || this.context.ipfsGateways || defaultGateways;
+    let cid;
+    if (url.startsWith("ipfs://")) {
+      cid = url.replace("ipfs://", "");
+    } else if (url.startsWith("Qm") || url.startsWith("bafy")) {
+      cid = url;
+    } else {
+      throw new Error(
+        `Invalid IPFS URL format. Expected ipfs://... or a raw CID, got: ${url}`
+      );
+    }
+    const errors = [];
+    for (let i = 0; i < gateways.length; i++) {
+      const gateway = gateways[i];
+      const isLastGateway = i === gateways.length - 1;
+      const gatewayUrl = gateway.endsWith("/") ? `${gateway}${cid}` : `${gateway}/${cid}`;
+      try {
+        console.debug(`Trying IPFS gateway: ${gatewayUrl}`);
+        const response = await fetch(gatewayUrl);
+        if (response.ok) {
+          const blob = await response.blob();
+          if (blob.size > 0) {
+            console.debug(`Successfully fetched from gateway: ${gateway}`);
+            return blob;
+          } else {
+            if (isLastGateway) {
+              throw new Error("Empty response");
+            }
+            errors.push({
+              gateway,
+              error: "Empty response"
+            });
+          }
+        } else {
+          if (isLastGateway) {
+            if (response.status === 403) {
+              throw new Error(`HTTP error! status: 403 ${response.statusText}`);
+            } else if (response.status === 404) {
+              throw new Error(`HTTP error! status: 404 ${response.statusText}`);
+            } else {
+              throw new Error(
+                `HTTP error! status: ${response.status} ${response.statusText}`
+              );
+            }
+          }
+          errors.push({
+            gateway,
+            error: `HTTP ${response.status} ${response.statusText}`
+          });
+        }
+      } catch (error) {
+        if (isLastGateway && error instanceof Error && (error.message.includes("Empty response") || error.message.includes("HTTP error!"))) {
+          throw error;
+        }
+        errors.push({
+          gateway,
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+      }
+    }
+    const errorDetails = errors.map((e) => `${e.gateway}: ${e.error}`).join("\n  ");
+    throw new Error(
+      `Failed to fetch IPFS content ${cid} from all gateways:
+  ${errorDetails}`
+    );
+  }
   /**
    * Validates a data schema against the Vana meta-schema.
    *
@@ -37591,9 +37620,14 @@ var SchemaController = class {
       };
       validateDataSchema(dataSchema);
       if (!this.context.storageManager) {
-        throw new Error(
-          "Storage manager not configured. Please provide storage providers in VanaConfig."
-        );
+        if (this.context.validateStorageRequired) {
+          this.context.validateStorageRequired();
+          throw new Error("Storage validation failed");
+        } else {
+          throw new Error(
+            "Storage manager not configured. Please provide storage providers in VanaConfig."
+          );
+        }
       }
       const schemaBlob = new Blob([JSON.stringify(schemaDefinition)], {
         type: "application/json"
@@ -37865,6 +37899,7 @@ var ServerController = class {
       }
       const serverResponse = await response.json();
       return {
+        kind: serverResponse.personal_server.kind,
         address: serverResponse.personal_server.address,
         public_key: serverResponse.personal_server.public_key,
         base_url: this.PERSONAL_SERVER_BASE_URL || "",
@@ -39478,175 +39513,151 @@ var PinataStorage = class {
   }
 };
 
-// src/storage/providers/server-proxy.ts
-var ServerProxyStorage = class {
-  constructor(config) {
-    this.config = config;
-    if (!config.uploadUrl) {
-      throw new StorageError(
-        "Upload URL is required",
-        "MISSING_UPLOAD_URL",
-        "server-proxy"
-      );
-    }
-    if (!config.downloadUrl) {
-      throw new StorageError(
-        "Download URL is required",
-        "MISSING_DOWNLOAD_URL",
-        "server-proxy"
+// src/storage/providers/callback-storage.ts
+var CallbackStorage = class {
+  constructor(callbacks) {
+    this.callbacks = callbacks;
+    if (!callbacks.upload || !callbacks.download) {
+      throw new Error(
+        "CallbackStorage requires both upload and download callbacks"
       );
     }
   }
   /**
-   * Uploads a file through your server endpoint
+   * Upload a file using the provided callback
    *
-   * @remarks
-   * This method sends the file to your configured upload endpoint via FormData.
-   * Your server is responsible for handling the actual storage implementation
-   * and must return a JSON response with `success: true` and an `identifier` field.
-   *
-   * @param file - The file to upload
-   * @param filename - Optional custom filename
-   * @returns Promise that resolves to the server-provided identifier
-   * @throws {StorageError} When the upload fails or server returns an error
-   *
-   * @example
-   * ```typescript
-   * const identifier = await serverStorage.upload(fileBlob, { name: "report.pdf" });
-   * console.log("File uploaded with identifier:", identifier);
-   * ```
+   * @param file - The blob to upload
+   * @param filename - Optional filename for the upload
+   * @returns The upload result with URL and metadata
    */
   async upload(file, filename) {
     try {
-      const formData = new FormData();
-      formData.append("file", file);
-      if (filename) {
-        formData.append("name", filename);
-      }
-      const response = await fetch(this.config.uploadUrl, {
-        method: "POST",
-        body: formData
-      });
-      if (!response.ok) {
-        const _errorText = await response.text();
-        throw new StorageError(
-          `Server upload failed: ${response.status} ${response.statusText}`,
-          "UPLOAD_FAILED",
-          "server-proxy"
-        );
-      }
-      const result = await response.json();
-      if (!result.success) {
+      const result = await this.callbacks.upload(file, filename);
+      if (!result.url || result.url.trim() === "") {
         throw new StorageError(
-          `Upload failed: ${result.error || "Unknown server error"}`,
-          "UPLOAD_FAILED",
-          "server-proxy"
+          "Upload callback returned invalid result: missing or empty url",
+          "INVALID_UPLOAD_RESULT",
+          "callback-storage"
         );
       }
-      if (!result.identifier) {
-        throw new StorageError(
-          "Server upload succeeded but no identifier returned",
-          "NO_IDENTIFIER_RETURNED",
-          "server-proxy"
-        );
-      }
-      return {
-        url: result.url || result.identifier,
-        size: file.size,
-        contentType: file.type || "application/octet-stream"
-      };
+      return result;
     } catch (error) {
       if (error instanceof StorageError) {
         throw error;
       }
       throw new StorageError(
-        `Server proxy upload error: ${error instanceof Error ? error.message : "Unknown error"}`,
+        `Upload failed: ${error instanceof Error ? error.message : String(error)}`,
         "UPLOAD_ERROR",
-        "server-proxy"
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
       );
     }
   }
   /**
-   * Downloads a file through your server endpoint
+   * Download a file using the provided callback
    *
-   * @remarks
-   * This method sends the identifier to your configured download endpoint via POST request.
-   * Your server is responsible for retrieving the file from your storage backend
-   * and returning the file content as a blob response.
-   *
-   * @param url - The server-provided URL or identifier from upload
-   * @returns Promise that resolves to the downloaded file content
-   * @throws {StorageError} When the download fails or file is not found
-   *
-   * @example
-   * ```typescript
-   * const fileBlob = await serverStorage.download("file-123");
-   * const url = URL.createObjectURL(fileBlob);
-   * ```
+   * @param url - The URL or identifier to download
+   * @returns The downloaded blob
    */
   async download(url) {
     try {
-      const identifier = this.extractIdentifierFromUrl(url);
-      const response = await fetch(this.config.downloadUrl, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ identifier })
-      });
-      if (!response.ok) {
-        const _errorText = await response.text();
+      const identifier = this.callbacks.extractIdentifier ? this.callbacks.extractIdentifier(url) : url;
+      const blob = await this.callbacks.download(identifier);
+      if (!(blob instanceof Blob)) {
         throw new StorageError(
-          `Server download failed: ${response.status} ${response.statusText}`,
-          "DOWNLOAD_FAILED",
-          "server-proxy"
+          "Download callback returned invalid result: expected Blob",
+          "INVALID_DOWNLOAD_RESULT",
+          "callback-storage"
         );
       }
-      return await response.blob();
+      return blob;
     } catch (error) {
       if (error instanceof StorageError) {
         throw error;
       }
       throw new StorageError(
-        `Server proxy download error: ${error instanceof Error ? error.message : "Unknown error"}`,
+        `Download failed: ${error instanceof Error ? error.message : String(error)}`,
         "DOWNLOAD_ERROR",
-        "server-proxy"
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
       );
     }
   }
-  async list(_options) {
-    throw new StorageError(
-      "List operation is not supported by server proxy storage",
-      "LIST_NOT_SUPPORTED",
-      "server-proxy"
-    );
-  }
-  async delete(_url) {
-    throw new StorageError(
-      "Delete operation is not supported by server proxy storage",
-      "DELETE_NOT_SUPPORTED",
-      "server-proxy"
-    );
+  /**
+   * List files using the provided callback (if available)
+   *
+   * @param options - Optional list options including filters and pagination
+   * @returns Array of storage files
+   */
+  async list(options) {
+    if (!this.callbacks.list) {
+      throw new StorageError(
+        "List operation not supported - no list callback provided",
+        "NOT_SUPPORTED",
+        "callback-storage"
+      );
+    }
+    try {
+      const result = await this.callbacks.list(options?.namePattern, options);
+      return result.items.map((item, index) => ({
+        id: item.identifier,
+        name: item.identifier.split("/").pop() || `file-${index}`,
+        url: item.identifier,
+        size: item.size || 0,
+        contentType: "application/octet-stream",
+        createdAt: item.lastModified || /* @__PURE__ */ new Date(),
+        metadata: item.metadata
+      }));
+    } catch (error) {
+      throw new StorageError(
+        `List failed: ${error instanceof Error ? error.message : String(error)}`,
+        "LIST_ERROR",
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
   }
   /**
-   * Extract identifier from URL or return as-is
+   * Delete a file using the provided callback (if available)
    *
-   * @param url - URL or identifier string
-   * @returns identifier string
+   * @param url - The URL or identifier to delete
+   * @returns True if deletion succeeded
    */
-  extractIdentifierFromUrl(url) {
-    return url;
+  async delete(url) {
+    if (!this.callbacks.delete) {
+      throw new StorageError(
+        "Delete operation not supported - no delete callback provided",
+        "NOT_SUPPORTED",
+        "callback-storage"
+      );
+    }
+    try {
+      const identifier = this.callbacks.extractIdentifier ? this.callbacks.extractIdentifier(url) : url;
+      return await this.callbacks.delete(identifier);
+    } catch (error) {
+      throw new StorageError(
+        `Delete failed: ${error instanceof Error ? error.message : String(error)}`,
+        "DELETE_ERROR",
+        "callback-storage",
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
   }
+  /**
+   * Get provider configuration
+   *
+   * @returns Provider configuration metadata
+   */
   getConfig() {
     return {
-      name: "Server Proxy",
-      type: "server-proxy",
+      name: "callback-storage",
+      type: "callback",
       requiresAuth: false,
       features: {
         upload: true,
         download: true,
-        list: false,
-        delete: false
+        list: !!this.callbacks.list,
+        delete: !!this.callbacks.delete
       }
     };
   }
@@ -39876,6 +39887,47 @@ function getAllChains() {
 }
 
 // src/core.ts
+var VanaCoreFactory = class {
+  /**
+   * Creates a VanaCore instance that enforces storage requirements at compile time.
+   * Use this factory when you know you'll need storage-dependent operations.
+   *
+   * @param platform - The platform adapter for environment-specific operations
+   * @param config - Configuration that includes required storage providers
+   * @returns VanaCore instance with storage validation
+   * @example
+   * ```typescript
+   * const vanaCore = VanaCoreFactory.createWithStorage(platformAdapter, {
+   *   walletClient: myWalletClient,
+   *   storage: {
+   *     providers: { ipfs: new IPFSStorage() },
+   *     defaultProvider: 'ipfs'
+   *   }
+   * });
+   * ```
+   */
+  static createWithStorage(platform, config) {
+    const core = new VanaCore(platform, config);
+    return core;
+  }
+  /**
+   * Creates a VanaCore instance without storage requirements.
+   * Storage-dependent operations will fail at runtime if not configured.
+   *
+   * @param platform - The platform adapter for environment-specific operations
+   * @param config - Basic configuration without required storage
+   * @returns VanaCore instance
+   * @example
+   * ```typescript
+   * const vanaCore = VanaCoreFactory.create(platformAdapter, {
+   *   walletClient: myWalletClient
+   * });
+   * ```
+   */
+  static create(platform, config) {
+    return new VanaCore(platform, config);
+  }
+};
 var VanaCore = class {
   /** Manages gasless data access permissions and trusted server registry. */
   permissions;
@@ -39891,12 +39943,18 @@ var VanaCore = class {
   platform;
   relayerCallbacks;
   storageManager;
+  hasRequiredStorage;
+  ipfsGateways;
   /**
    * Initializes a new VanaCore client instance with the provided configuration.
    *
    * @remarks
    * The constructor validates the configuration, initializes storage providers if configured,
    * creates wallet and public clients, and sets up all SDK controllers with shared context.
+   *
+   * IMPORTANT: This constructor will validate storage requirements at runtime to fail fast.
+   * Methods that require storage will throw runtime errors if storage is not configured.
+   *
    * @param platform - The platform adapter for environment-specific operations
    * @param config - The configuration object specifying wallet or chain settings
    * @throws {InvalidConfigurationError} When the configuration is invalid or incomplete
@@ -39912,6 +39970,8 @@ var VanaCore = class {
     this.platform = platform;
     this.validateConfig(config);
     this.relayerCallbacks = config.relayerCallbacks;
+    this.ipfsGateways = config.ipfsGateways;
+    this.hasRequiredStorage = hasStorageConfig(config);
     if (config.storage?.providers) {
       this.storageManager = new StorageManager();
       for (const [name, provider] of Object.entries(config.storage.providers)) {
@@ -39966,8 +40026,11 @@ var VanaCore = class {
       relayerCallbacks: this.relayerCallbacks,
       storageManager: this.storageManager,
       subgraphUrl,
-      platform: this.platform
+      platform: this.platform,
       // Pass the platform adapter to controllers
+      validateStorageRequired: this.validateStorageRequired.bind(this),
+      hasStorage: this.hasStorage.bind(this),
+      ipfsGateways: this.ipfsGateways
     };
     this.permissions = new PermissionsController(sharedContext);
     this.data = new DataController(sharedContext);
@@ -39975,6 +40038,58 @@ var VanaCore = class {
     this.server = new ServerController(sharedContext);
     this.protocol = new ProtocolController(sharedContext);
   }
+  /**
+   * Validates that storage is available for storage-dependent operations.
+   * This method enforces the fail-fast principle by checking storage availability
+   * at method call time rather than during expensive operations.
+   *
+   * @throws {InvalidConfigurationError} When storage is required but not configured
+   * @example
+   * ```typescript
+   * // This will throw if storage is not configured
+   * vana.validateStorageRequired();
+   * await vana.data.uploadFile(file); // Safe to proceed
+   * ```
+   */
+  validateStorageRequired() {
+    if (!this.hasRequiredStorage) {
+      throw new InvalidConfigurationError(
+        "Storage configuration is required for this operation. Please configure storage providers in VanaConfig.storage, provide a relayerCallbacks.storeGrantFile implementation, or pass pre-stored URLs to avoid this dependency. \n\nFor better type safety, consider using VanaCoreFactory.createWithStorage() with VanaConfigWithStorage to catch this error at compile time."
+      );
+    }
+  }
+  /**
+   * Checks whether storage is configured without throwing an error.
+   *
+   * @returns True if storage is properly configured
+   * @example
+   * ```typescript
+   * if (vana.hasStorage()) {
+   *   await vana.data.uploadFile(file);
+   * } else {
+   *   console.warn('Storage not configured - using pre-stored URLs only');
+   * }
+   * ```
+   */
+  hasStorage() {
+    return this.hasRequiredStorage;
+  }
+  /**
+   * Type guard to check if this instance has storage enabled at compile time.
+   * Use this when you need TypeScript to understand that storage is available.
+   *
+   * @returns True if storage is configured, with type narrowing
+   * @example
+   * ```typescript
+   * if (vana.isStorageEnabled()) {
+   *   // TypeScript knows storage is available here
+   *   await vana.data.uploadFile(file);
+   * }
+   * ```
+   */
+  isStorageEnabled() {
+    return this.hasRequiredStorage;
+  }
   /**
    * Validates the provided configuration object against all requirements.
    *
@@ -40163,23 +40278,23 @@ var VanaCore = class {
     return this.platform;
   }
   /**
-   * Encrypts user data using the Vana protocol standard encryption.
+   * Encrypts data using the Vana protocol standard encryption.
    * This method automatically uses the correct platform adapter for the current environment.
    *
    * @param data The data to encrypt (string or Blob)
-   * @param walletSignature The wallet signature to use as encryption key
+   * @param key The key to use as encryption key
    * @returns The encrypted data as Blob
    * @example
    * ```typescript
    * const encryptionKey = await generateEncryptionKey(walletClient);
-   * const encrypted = await vana.encryptUserData("sensitive data", encryptionKey);
+   * const encrypted = await vana.encryptBlob("sensitive data", encryptionKey);
    * ```
    */
-  async encryptUserData(data, walletSignature) {
-    return encryptUserData(data, walletSignature, this.platform);
+  async encryptBlob(data, key) {
+    return encryptBlobWithSignedKey(data, key, this.platform);
   }
   /**
-   * Decrypts user data using the Vana protocol standard decryption.
+   * Decrypts data that was encrypted using the Vana protocol.
    * This method automatically uses the correct platform adapter for the current environment.
    *
    * @param encryptedData The encrypted data (string or Blob)
@@ -40188,12 +40303,16 @@ var VanaCore = class {
    * @example
    * ```typescript
    * const encryptionKey = await generateEncryptionKey(walletClient);
-   * const decrypted = await vana.decryptUserData(encryptedData, encryptionKey);
+   * const decrypted = await vana.decryptBlob(encryptedData, encryptionKey);
    * const text = await decrypted.text();
    * ```
    */
-  async decryptUserData(encryptedData, walletSignature) {
-    return decryptUserData(encryptedData, walletSignature, this.platform);
+  async decryptBlob(encryptedData, walletSignature) {
+    return decryptBlobWithSignedKey(
+      encryptedData,
+      walletSignature,
+      this.platform
+    );
   }
 };
 
@@ -40224,7 +40343,7 @@ function createValidatedGrant(params) {
   try {
     validateGrant(grantFile, {
       schema: true,
-      grantee: params.to,
+      grantee: params.grantee,
       operation: params.operation
     });
   } catch (error) {
@@ -41087,31 +41206,22 @@ var ApiClient = class {
 };
 
 // src/index.node.ts
-var VanaNode = class extends VanaCore {
-  /**
-   * Creates a Vana SDK instance configured for Node.js environments.
-   *
-   * @param config - SDK configuration object (wallet client or chain config)
-   * @example
-   * ```typescript
-   * // With wallet client
-   * const vana = new Vana({ walletClient });
-   *
-   * // With chain configuration
-   * const vana = new Vana({ chainId: 14800, account });
-   * ```
-   */
+var VanaNodeImpl = class extends VanaCore {
   constructor(config) {
     super(new NodePlatformAdapter(), config);
   }
 };
-var index_node_default = VanaNode;
+function Vana(config) {
+  return new VanaNodeImpl(config);
+}
+var index_node_default = Vana;
 export {
   ApiClient,
   AsyncQueue,
   BaseController,
   BlockchainError,
   BrowserPlatformAdapter,
+  CallbackStorage,
   CircuitBreaker,
   ContractFactory,
   ContractNotFoundError,
@@ -41146,16 +41256,16 @@ export {
   SchemaValidator,
   SerializationError,
   ServerController,
-  ServerProxyStorage,
   ServerUrlMismatchError,
   SignatureError,
   StorageError,
   StorageManager,
   UserRejectedRequestError,
-  VanaNode as Vana,
+  Vana,
   VanaCore,
+  VanaCoreFactory,
   VanaError,
-  VanaNode,
+  VanaNodeImpl,
   __contractCache,
   chains,
   checkGrantAccess,
@@ -41170,13 +41280,13 @@ export {
   createPlatformAdapterFor,
   createPlatformAdapterSafe,
   createValidatedGrant,
-  decryptUserData,
+  decryptBlobWithSignedKey,
   decryptWithPrivateKey,
   decryptWithWalletPrivateKey,
   index_node_default as default,
   detectPlatform,
+  encryptBlobWithSignedKey,
   encryptFileKey,
-  encryptUserData,
   encryptWithWalletPublicKey,
   extractIpfsHash,
   fetchAndValidateSchema,
@@ -41201,9 +41311,7 @@ export {
   handleRelayerRequest,
   isAPIResponse,
   isGrantExpired,
-  isIdentityServerOutput,
   isIpfsUrl,
-  isPersonalServerOutput,
   isPlatformSupported,
   isReplicateAPIResponse,
   moksha,