@opendatalabs/vana-sdk 0.1.0-alpha.82bbb39 → 0.1.0-alpha.853aa70

package/dist/controllers/data.js

@@ -0,0 +1,2521 @@
+import { getContract } from "viem";
+import { BaseController } from "./base";
+import { getContractAddress } from "../config/addresses";
+import { getAbi } from "../generated/abi";
+import {
+  GetUserFilesDocument,
+  GetFileProofsDocument,
+  GetDlpDocument,
+  GetUserPermissionsDocument,
+  GetUserTrustedServersDocument
+} from "../generated/subgraph";
+import { print } from "graphql";
+import {
+  generateEncryptionKey,
+  decryptBlobWithSignedKey,
+  DEFAULT_ENCRYPTION_SEED,
+  encryptBlobWithSignedKey,
+  encryptWithWalletPublicKey,
+  decryptWithWalletPrivateKey
+} from "../utils/encryption";
+import {
+  validateDataSchemaAgainstMetaSchema,
+  validateDataAgainstSchema,
+  fetchAndValidateSchema
+} from "../utils/schemaValidation";
+import { gasAwareMulticall } from "../utils/multicall";
+class DataController extends BaseController {
+  constructor(context) {
+    super(context);
+  }
+  async upload(params) {
+    this.assertWallet();
+    const {
+      content,
+      filename,
+      schemaId,
+      permissions = [],
+      encrypt = true,
+      providerName,
+      owner,
+      schemaValidation = "strict"
+    } = params;
+    try {
+      let isValid = true;
+      let validationErrors = [];
+      if (schemaId !== void 0 && schemaValidation !== "skip") {
+        try {
+          const { SchemaController } = await import("./schemas");
+          const schemaController = new SchemaController(this.context);
+          const schema = await schemaController.get(schemaId);
+          let parsedContent;
+          if (typeof content === "string") {
+            try {
+              parsedContent = JSON.parse(content);
+            } catch {
+              parsedContent = content;
+            }
+          } else if (content instanceof Blob) {
+            const text = await content.text();
+            try {
+              parsedContent = JSON.parse(text);
+            } catch {
+              parsedContent = text;
+            }
+          } else {
+            parsedContent = content;
+          }
+          validateDataAgainstSchema(parsedContent, schema);
+        } catch (error) {
+          if (schemaValidation === "strict") {
+            throw error;
+          } else if (schemaValidation === "warn") {
+            console.warn(
+              '[Vana SDK] Schema validation failed, but continuing due to validation mode "warn"'
+            );
+            if (error instanceof Error) {
+              console.warn("  Validation error:", error.message);
+              if (typeof error === "object" && "errors" in error && Array.isArray(error.errors)) {
+                console.warn("  Detailed errors:", error.errors);
+              }
+            }
+            isValid = false;
+            validationErrors = error instanceof Error ? [error.message] : ["Schema validation failed"];
+          }
+        }
+      }
+      const uploadResult = await this.uploadToStorage(
+        content,
+        filename,
+        encrypt,
+        providerName
+      );
+      const userAddress = owner ?? this.context.userAddress;
+      let encryptedPermissions = [];
+      if (permissions.length > 0 && encrypt) {
+        this.assertWallet();
+        const userEncryptionKey = await generateEncryptionKey(
+          this.context.walletClient,
+          this.context.platform,
+          DEFAULT_ENCRYPTION_SEED
+        );
+        encryptedPermissions = await Promise.all(
+          permissions.map(async (permission) => {
+            const encryptedKey = await encryptWithWalletPublicKey(
+              userEncryptionKey,
+              permission.publicKey,
+              this.context.platform
+            );
+            return {
+              account: permission.account,
+              key: encryptedKey
+            };
+          })
+        );
+      }
+      let result;
+      if (this.context.relayer) {
+        const request = {
+          type: "direct",
+          operation: "submitFileAdditionComplete",
+          params: {
+            url: uploadResult.url,
+            userAddress,
+            permissions: encryptedPermissions,
+            schemaId: schemaId ?? 0,
+            ownerAddress: owner
+          }
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new Error(response.error);
+        }
+        if (response.type !== "direct" || !("fileId" in response.result)) {
+          throw new Error("Invalid response from relayer");
+        }
+        result = response.result;
+      } else {
+        const txResult = await this.addFileWithEncryptedPermissionsAndSchema(
+          uploadResult.url,
+          userAddress,
+          encryptedPermissions,
+          schemaId ?? 0
+        );
+        if (!this.context.waitForTransactionEvents) {
+          throw new Error(
+            "Cannot upload without relay: waitForTransactionEvents not configured"
+          );
+        }
+        const eventResult = await this.context.waitForTransactionEvents(txResult);
+        const fileAddedEvent = eventResult.expectedEvents.FileAdded;
+        if (!fileAddedEvent) {
+          throw new Error("FileAdded event not found in transaction");
+        }
+        result = {
+          fileId: Number(fileAddedEvent.fileId),
+          transactionHash: txResult.hash
+        };
+      }
+      return {
+        fileId: result.fileId,
+        url: uploadResult.url,
+        transactionHash: result.transactionHash,
+        size: uploadResult.size,
+        isValid,
+        validationErrors: validationErrors.length > 0 ? validationErrors : void 0
+      };
+    } catch (error) {
+      throw new Error(
+        `Upload failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Encrypts data using wallet-derived encryption.
+   *
+   * @remarks
+   * This method provides secure, wallet-based encryption for data before uploading
+   * to the Vana network. It's the counterpart to decryptFile for preparing data
+   * for secure storage.
+   *
+   * The method automatically:
+   * - Generates an encryption key from the user's wallet signature
+   * - Converts the input data to a Blob if necessary
+   * - Encrypts the data using the generated key
+   * - Returns both the encrypted data and the encryption key
+   *
+   * The encryption key returned can be stored and later used for decryption,
+   * or shared with others to grant them decryption access.
+   *
+   * @param data - The data to encrypt (Blob, string, or object)
+   * @param options - Optional encryption configuration
+   * @returns Promise resolving to encrypted data and the encryption key used
+   * @throws {Error} When wallet is not connected or encryption fails
+   * @example
+   * ```typescript
+   * // Encrypt a string
+   * const { encryptedData, encryptionKey } = await vana.data.encryptFile(
+   *   "My secret data"
+   * );
+   *
+   * // Encrypt JSON with custom MIME type
+   * const { encryptedData, encryptionKey } = await vana.data.encryptFile(
+   *   { name: "Alice", age: 30 },
+   *   { mimeType: "application/json" }
+   * );
+   *
+   * // With custom encryption seed
+   * const { encryptedData, encryptionKey } = await vana.data.encryptFile(
+   *   "Secret message",
+   *   { seed: "My custom encryption seed" }
+   * );
+   *
+   * // Upload the encrypted data
+   * const result = await vana.data.uploadToStorage(encryptedData);
+   * ```
+   */
+  async encryptFile(data, options) {
+    this.assertWallet();
+    try {
+      const encryptionKey = await generateEncryptionKey(
+        this.context.walletClient,
+        this.context.platform,
+        options?.seed ?? DEFAULT_ENCRYPTION_SEED
+      );
+      let blob;
+      if (data instanceof Blob) {
+        blob = data;
+      } else if (typeof data === "string") {
+        blob = new Blob([data], { type: options?.mimeType ?? "text/plain" });
+      } else {
+        blob = new Blob([JSON.stringify(data)], {
+          type: options?.mimeType ?? "application/json"
+        });
+      }
+      const encryptedData = await encryptBlobWithSignedKey(
+        blob,
+        encryptionKey,
+        this.context.platform
+      );
+      return {
+        encryptedData,
+        encryptionKey
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to encrypt file: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Decrypts a file using wallet-derived decryption key.
+   *
+   * @remarks
+   * Counterpart to `upload()` for decrypting user files. Automatically
+   * generates decryption key from wallet, fetches encrypted content,
+   * and decrypts. Supports IPFS (with gateway fallback) and HTTP URLs.
+   *
+   * @param file - UserFile object from `getUserFiles()`
+   * @param options - Decryption options
+   * @param options.seed - Custom encryption seed.
+   *   Defaults to standard Vana seed.
+   *
+   * @returns Decrypted content as Blob
+   *
+   * @throws {Error} No wallet connected.
+   *   Connect wallet before decrypting.
+   * @throws {Error} Network error accessing file.
+   *   Check CORS settings or server availability.
+   * @throws {Error} File not found (404).
+   *   File no longer available at stored URL.
+   * @throws {Error} Access denied (403).
+   *   No permission to access file.
+   * @throws {Error} Invalid file format.
+   *   File not encrypted with Vana protocol.
+   * @throws {Error} Wrong encryption key.
+   *   Verify seed matches upload or use default.
+   *
+   * @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, options) {
+    this.assertWallet();
+    try {
+      this.assertWallet();
+      const encryptionKey = await generateEncryptionKey(
+        this.context.walletClient,
+        this.context.platform,
+        options?.seed ?? 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 files owned by a specific user address.
+   *
+   * @remarks
+   * Queries the Vana subgraph for files owned by the specified address.
+   * Automatically deduplicates by file ID, keeping the latest version
+   * when duplicates exist from re-indexing or chain reorganizations.
+   * Enriches results with DLP proof data when available.
+   *
+   * @param params - Query configuration
+   * @param params.owner - Wallet address of the file owner
+   * @param params.subgraphUrl - Subgraph endpoint override.
+   *   Defaults to context configuration.
+   *
+   * @returns Array of UserFile objects sorted by timestamp (newest first)
+   *
+   * @throws {Error} Subgraph URL not configured.
+   *   Provide `subgraphUrl` parameter or configure in Vana constructor.
+   * @throws {Error} Subgraph request failed.
+   *   Check network connectivity and subgraph availability.
+   * @throws {Error} Subgraph returned errors.
+   *   Review query parameters and subgraph logs.
+   *
+   * @example
+   * ```typescript
+   * const files = await vana.data.getUserFiles({
+   *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+   * });
+   *
+   * files.forEach(file => {
+   *   console.log(`File ${file.id}: ${file.url}`);
+   *   console.log(`  Schema: ${file.schemaId}`);
+   *   console.log(`  DLPs: ${file.dlpIds?.join(", ") || "none"}`);
+   * });
+   * ```
+   */
+  async getUserFiles(params) {
+    const { owner, subgraphUrl } = params;
+    const endpoint = subgraphUrl ?? this.context.subgraphUrl;
+    if (!endpoint) {
+      throw new Error(
+        "subgraphUrl is required. Please provide a valid subgraph endpoint or configure it in Vana constructor."
+      );
+    }
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          query: print(GetUserFilesDocument),
+          variables: {
+            userId: owner.toLowerCase()
+            // Subgraph requires lowercase addresses
+          }
+        })
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Subgraph request failed: ${response.status} ${response.statusText}`
+        );
+      }
+      const result = await response.json();
+      if (result.errors) {
+        throw new Error(
+          `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+        );
+      }
+      const user = result.data?.user;
+      if (!user?.files?.length) {
+        console.warn("No files found for user:", owner);
+        return [];
+      }
+      const fileMap = /* @__PURE__ */ new Map();
+      user.files.forEach((file) => {
+        const fileId = parseInt(file.id);
+        const userFile = {
+          id: fileId,
+          url: file.url,
+          ownerAddress: file.owner.id,
+          addedAtBlock: BigInt(file.addedAtBlock),
+          schemaId: parseInt(file.schemaId),
+          addedAtTimestamp: BigInt(file.addedAtTimestamp),
+          transactionHash: file.transactionHash
+        };
+        const existing = fileMap.get(fileId);
+        if (!existing || userFile.addedAtTimestamp && existing.addedAtTimestamp && userFile.addedAtTimestamp > existing.addedAtTimestamp) {
+          fileMap.set(fileId, userFile);
+        }
+      });
+      const userFiles = Array.from(fileMap.values()).sort(
+        (a, b) => Number((b.addedAtTimestamp ?? 0n) - (a.addedAtTimestamp ?? 0n))
+      );
+      if (userFiles.length > 0) {
+        try {
+          const fileIds = userFiles.map((f) => f.id);
+          let proofMap;
+          try {
+            proofMap = await this._fetchProofsFromSubgraph(fileIds, endpoint);
+          } catch (subgraphError) {
+            console.debug(
+              "Failed to fetch proofs from subgraph, trying chain:",
+              subgraphError
+            );
+            proofMap = await this._fetchProofsFromChain(fileIds);
+          }
+          for (const file of userFiles) {
+            const dlpIds = proofMap.get(file.id);
+            if (dlpIds && dlpIds.length > 0) {
+              file.dlpIds = dlpIds;
+            }
+          }
+        } catch (error) {
+          console.warn("Failed to fetch proof data for files:", error);
+        }
+      }
+      return userFiles;
+    } catch (error) {
+      console.error("Failed to fetch user files from subgraph:", error);
+      throw new Error(
+        `Failed to fetch user files from subgraph: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Fetches proof data for multiple files from the subgraph.
+   *
+   * @private
+   * @param fileIds - Array of file IDs to fetch proofs for
+   * @param subgraphUrl - The subgraph endpoint URL
+   * @returns Map of file IDs to their associated DLP IDs
+   */
+  async _fetchProofsFromSubgraph(fileIds, subgraphUrl) {
+    const response = await fetch(subgraphUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        query: print(GetFileProofsDocument),
+        variables: {
+          fileIds: fileIds.map((id) => id.toString())
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    const proofMap = /* @__PURE__ */ new Map();
+    if (result.data?.dataRegistryProofs) {
+      for (const proof of result.data.dataRegistryProofs) {
+        if (proof.dlp?.id) {
+          const fileId = parseInt(proof.fileId);
+          const dlpId = parseInt(proof.dlp.id);
+          let dlpIds = proofMap.get(fileId);
+          if (!dlpIds) {
+            dlpIds = [];
+            proofMap.set(fileId, dlpIds);
+          }
+          if (!dlpIds.includes(dlpId)) {
+            dlpIds.push(dlpId);
+          }
+        }
+      }
+    }
+    return proofMap;
+  }
+  /**
+   * Fetches proof data for multiple files from the blockchain.
+   * Falls back to this when subgraph is unavailable.
+   *
+   * @private
+   * @param fileIds - Array of file IDs to fetch proofs for
+   * @returns Map of file IDs to their associated DLP IDs
+   */
+  async _fetchProofsFromChain(fileIds) {
+    const chainId = this.context.publicClient.chain?.id;
+    if (!chainId) {
+      throw new Error("Chain ID not available");
+    }
+    const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+    const dataRegistryAbi = getAbi("DataRegistry");
+    const proofMap = /* @__PURE__ */ new Map();
+    for (const fileId of fileIds) {
+      const dlpIds = [];
+      let proofIndex = 0;
+      let hasMoreProofs = true;
+      while (hasMoreProofs) {
+        try {
+          const proof = await this.context.publicClient.readContract({
+            address: dataRegistryAddress,
+            abi: dataRegistryAbi,
+            functionName: "fileProofs",
+            args: [BigInt(fileId), BigInt(proofIndex)]
+          });
+          if (proof?.data?.dlpId) {
+            const dlpId = Number(proof.data.dlpId);
+            if (!dlpIds.includes(dlpId)) {
+              dlpIds.push(dlpId);
+            }
+          }
+          proofIndex++;
+        } catch {
+          hasMoreProofs = false;
+        }
+      }
+      if (dlpIds.length > 0) {
+        proofMap.set(fileId, dlpIds);
+      }
+    }
+    return proofMap;
+  }
+  /**
+   * Retrieves information about a specific Data Liquidity Pool (DLP).
+   *
+   * @remarks
+   * DLPs are entities that process and verify data files in the Vana network.
+   * This method fetches DLP metadata including name, status, and performance rating.
+   * Uses subgraph first for efficiency, falls back to chain if unavailable.
+   *
+   * @param dlpId - The unique identifier of the DLP
+   * @param options - Optional parameters
+   * @param options.subgraphUrl - Custom subgraph URL to override default
+   * @returns Promise resolving to DLP information
+   * @throws {Error} When DLP cannot be found - "DLP not found: {dlpId}"
+   * @throws {Error} When query fails - "Failed to fetch DLP: {error}"
+   * @example
+   * ```typescript
+   * const dlp = await vana.data.getDLP(26);
+   * console.log(`DLP ${dlp.name}: ${dlp.status}`);
+   * ```
+   */
+  async getDLP(dlpId, options = {}) {
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl) {
+      try {
+        const response = await fetch(subgraphUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            query: print(GetDlpDocument),
+            variables: {
+              id: dlpId.toString()
+            }
+          })
+        });
+        if (!response.ok) {
+          throw new Error(
+            `Subgraph request failed: ${response.status} ${response.statusText}`
+          );
+        }
+        const result = await response.json();
+        if (result.errors) {
+          throw new Error(
+            `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+          );
+        }
+        if (!result.data?.dlp) {
+          throw new Error(`DLP not found: ${dlpId}`);
+        }
+        return {
+          id: parseInt(result.data.dlp.id),
+          name: result.data.dlp.name ?? "",
+          metadata: result.data.dlp.metadata ?? void 0,
+          status: result.data.dlp.status ? parseInt(result.data.dlp.status) : void 0,
+          address: result.data.dlp.address ? result.data.dlp.address : void 0,
+          owner: result.data.dlp.owner ? result.data.dlp.owner : void 0
+        };
+      } catch (error) {
+        console.debug("Subgraph query failed, falling back to chain:", error);
+      }
+    }
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dlpRegistryAddress = getContractAddress(chainId, "DLPRegistry");
+      const dlpRegistryAbi = getAbi("DLPRegistry");
+      const dlpData = await this.context.publicClient.readContract({
+        address: dlpRegistryAddress,
+        abi: dlpRegistryAbi,
+        functionName: "dlps",
+        args: [BigInt(dlpId)]
+      });
+      if (!dlpData?.name) {
+        throw new Error(`DLP not found: ${dlpId}`);
+      }
+      return {
+        id: dlpId,
+        name: dlpData.name,
+        metadata: dlpData.metadata,
+        status: dlpData.status,
+        address: dlpData.dlpAddress,
+        owner: dlpData.ownerAddress
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch DLP: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Lists all Data Liquidity Pools (DLPs) with optional pagination.
+   *
+   * @remarks
+   * Fetches a paginated list of all DLPs registered in the network.
+   * Uses subgraph for efficient querying with fallback to chain multicall.
+   *
+   * @param options - Optional parameters for pagination and filtering
+   * @param options.limit - Maximum number of DLPs to return (default: 100)
+   * @param options.offset - Number of DLPs to skip (default: 0)
+   * @param options.subgraphUrl - Custom subgraph URL to override default
+   * @returns Promise resolving to array of DLP information
+   * @throws {Error} When query fails - "Failed to list DLPs: {error}"
+   * @example
+   * ```typescript
+   * // Get first 10 DLPs
+   * const dlps = await vana.data.listDLPs({ limit: 10 });
+   * dlps.forEach(dlp => console.log(`${dlp.id}: ${dlp.name}`));
+   *
+   * // Get next page
+   * const nextPage = await vana.data.listDLPs({ limit: 10, offset: 10 });
+   * ```
+   */
+  async listDLPs(options = {}) {
+    const { limit = 100, offset = 0 } = options;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl) {
+      try {
+        const query = `
+          query ListDLPs($first: Int!, $skip: Int!) {
+            dlps(first: $first, skip: $skip, orderBy: id) {
+              id
+              name
+              metadata
+              status
+              address
+              owner
+            }
+          }
+        `;
+        const response = await fetch(subgraphUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            query,
+            variables: {
+              first: limit,
+              skip: offset
+            }
+          })
+        });
+        if (!response.ok) {
+          throw new Error(
+            `Subgraph request failed: ${response.status} ${response.statusText}`
+          );
+        }
+        const result = await response.json();
+        if (result.errors) {
+          throw new Error(
+            `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+          );
+        }
+        const dlps = result.data?.dlps ?? [];
+        return dlps.map((dlp) => ({
+          id: parseInt(dlp.id),
+          name: dlp.name ?? "",
+          metadata: dlp.metadata,
+          status: dlp.status ? parseInt(dlp.status) : void 0,
+          address: dlp.address ? dlp.address : void 0,
+          owner: dlp.owner ? dlp.owner : void 0
+        }));
+      } catch (error) {
+        console.debug("Subgraph query failed, falling back to chain:", error);
+      }
+    }
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dlpRegistryAddress = getContractAddress(chainId, "DLPRegistry");
+      const dlpRegistryAbi = getAbi("DLPRegistry");
+      const dlpCount = await this.context.publicClient.readContract({
+        address: dlpRegistryAddress,
+        abi: dlpRegistryAbi,
+        functionName: "dlpsCount",
+        args: []
+      });
+      const totalCount = Number(dlpCount);
+      const start = offset;
+      const end = Math.min(start + limit, totalCount);
+      if (end <= start) {
+        return [];
+      }
+      const calls = [];
+      for (let i = start + 1; i <= end; i++) {
+        calls.push({
+          address: dlpRegistryAddress,
+          abi: dlpRegistryAbi,
+          functionName: "dlps",
+          args: [BigInt(i)]
+        });
+      }
+      const results = await gasAwareMulticall(this.context.publicClient, {
+        contracts: calls,
+        allowFailure: true,
+        batchSize: 50
+      });
+      const dlps = [];
+      for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        if (result.status === "success" && result.result) {
+          const dlpData = result.result;
+          if (dlpData.name) {
+            dlps.push({
+              id: start + i + 1,
+              name: dlpData.name,
+              metadata: dlpData.metadata,
+              status: dlpData.status,
+              address: dlpData.dlpAddress,
+              owner: dlpData.ownerAddress
+            });
+          }
+        }
+      }
+      return dlps;
+    } catch (error) {
+      throw new Error(
+        `Failed to list DLPs: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Retrieves a list of permissions granted by a user.
+   *
+   * This method supports automatic fallback between subgraph and RPC modes:
+   * - If subgraph URL is available, tries subgraph query first
+   * - Falls back to direct contract queries via RPC if subgraph fails
+   * - RPC mode uses gasAwareMulticall for efficient batch queries
+   *
+   * @param params - Object containing the user address and optional subgraph URL
+   * @param params.user - The wallet address of the user to query permissions for
+   * @param params.subgraphUrl - Optional subgraph URL to override the default
+   * @returns Promise resolving to an array of permission objects
+   * @throws Error if both subgraph and RPC queries fail
+   */
+  async getUserPermissions(params) {
+    const { user, subgraphUrl } = params;
+    const endpoint = subgraphUrl ?? this.context.subgraphUrl;
+    if (endpoint) {
+      try {
+        const permissions = await this._getUserPermissionsViaSubgraph({
+          user,
+          subgraphUrl: endpoint
+        });
+        return permissions;
+      } catch (error) {
+        console.warn("Subgraph query failed, falling back to RPC:", error);
+      }
+    }
+    return await this._getUserPermissionsViaRpc({ user });
+  }
+  /**
+   * Internal method: Query user permissions via subgraph
+   *
+   * @param params - Query parameters object
+   * @param params.user - The user address to query permissions for
+   * @param params.subgraphUrl - The subgraph URL endpoint to query
+   * @returns Promise resolving to an array of permission objects
+   */
+  async _getUserPermissionsViaSubgraph(params) {
+    const { user, subgraphUrl } = params;
+    try {
+      const response = await fetch(subgraphUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          query: print(GetUserPermissionsDocument),
+          variables: {
+            userId: user.toLowerCase()
+          }
+        })
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Subgraph request failed: ${response.status} ${response.statusText}`
+        );
+      }
+      const result = await response.json();
+      if (result.errors) {
+        throw new Error(
+          `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
+        );
+      }
+      const userData = result.data?.user;
+      if (!userData?.permissions?.length) {
+        return [];
+      }
+      return userData.permissions.map((permission) => ({
+        id: permission.id,
+        grant: permission.grant,
+        nonce: BigInt(permission.nonce),
+        signature: permission.signature,
+        addedAtBlock: BigInt(permission.addedAtBlock),
+        addedAtTimestamp: BigInt(permission.addedAtTimestamp),
+        transactionHash: permission.transactionHash,
+        user
+      })).sort((a, b) => Number(b.addedAtTimestamp - a.addedAtTimestamp));
+    } catch (error) {
+      console.error("Failed to query user permissions from subgraph:", error);
+      throw error;
+    }
+  }
+  /**
+   * Internal method: Query user permissions via direct RPC
+   *
+   * @param params - Query parameters object
+   * @param params.user - The user address to query permissions for
+   * @returns Promise resolving to an array of permission objects
+   */
+  async _getUserPermissionsViaRpc(params) {
+    const { user } = params;
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const permissionsAddress = getContractAddress(
+        chainId,
+        "DataPortabilityPermissions"
+      );
+      const permissionsAbi = getAbi("DataPortabilityPermissions");
+      const totalCount = await this.context.publicClient.readContract({
+        address: permissionsAddress,
+        abi: permissionsAbi,
+        functionName: "userPermissionIdsLength",
+        args: [user]
+      });
+      const total = Number(totalCount);
+      if (total === 0) {
+        return [];
+      }
+      const permissionIdCalls = [];
+      for (let i = 0; i < total; i++) {
+        permissionIdCalls.push({
+          address: permissionsAddress,
+          abi: permissionsAbi,
+          functionName: "userPermissionIdsAt",
+          args: [user, BigInt(i)]
+        });
+      }
+      const permissionIdResults = await gasAwareMulticall(this.context.publicClient, {
+        contracts: permissionIdCalls
+      });
+      const permissionIds = permissionIdResults.map((result) => result).filter((id) => id && id > 0n);
+      const permissionInfoCalls = permissionIds.map(
+        (permissionId) => ({
+          address: permissionsAddress,
+          abi: permissionsAbi,
+          functionName: "permissions",
+          args: [permissionId]
+        })
+      );
+      const permissionInfoResults = await gasAwareMulticall(this.context.publicClient, {
+        contracts: permissionInfoCalls,
+        allowFailure: true
+      });
+      const permissions = permissionInfoResults.map((result, index) => {
+        const permissionId = permissionIds[index];
+        if (result.status === "success" && result.result) {
+          const permissionInfo = result.result;
+          return {
+            id: permissionId.toString(),
+            grant: permissionInfo.grant,
+            nonce: permissionInfo.nonce,
+            signature: "",
+            // Not available from RPC, will be empty
+            addedAtBlock: permissionInfo.startBlock,
+            addedAtTimestamp: BigInt(0),
+            // Not available from RPC
+            transactionHash: "0x0000000000000000000000000000000000000000",
+            // Not available from RPC
+            user
+          };
+        } else {
+          return {
+            id: permissionId.toString(),
+            grant: "",
+            nonce: BigInt(0),
+            signature: "",
+            addedAtBlock: BigInt(0),
+            addedAtTimestamp: BigInt(0),
+            transactionHash: "0x0000000000000000000000000000000000000000",
+            user
+          };
+        }
+      }).filter((permission) => permission.grant !== "");
+      return permissions;
+    } catch (error) {
+      throw new Error(
+        `RPC query failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Retrieves a list of trusted servers for a user.
+   *
+   * This method supports automatic fallback between subgraph and RPC modes:
+   * - If subgraph URL is available, tries subgraph query first for fast results
+   * - Falls back to direct contract queries via RPC if subgraph fails
+   * - RPC mode uses gasAwareMulticall for efficient batch queries
+   *
+   * @param params - Query parameters including user address and optional pagination
+   * @param params.user - The wallet address of the user to query trusted servers for
+   * @param params.subgraphUrl - Optional subgraph URL to override the default
+   * @param params.limit - Maximum number of results to return (default: 50)
+   * @param params.offset - Number of results to skip for pagination (default: 0)
+   * @returns Promise resolving to an array of trusted server objects
+   * @throws Error if both subgraph and RPC queries fail
+   * @example
+   * ```typescript
+   * // Basic usage with automatic fallback
+   * const servers = await vana.data.getUserTrustedServers({
+   *   user: '0x...'
+   * });
+   *
+   * // With pagination
+   * const servers = await vana.data.getUserTrustedServers({
+   *   user: '0x...',
+   *   limit: 10,
+   *   offset: 20
+   * });
+   *
+   * // With custom subgraph URL
+   * const servers = await vana.data.getUserTrustedServers({
+   *   user: '0x...',
+   *   subgraphUrl: 'https://custom-subgraph.com/graphql'
+   * });
+   * ```
+   */
+  async getUserTrustedServers(params) {
+    const { user, limit = 50, offset = 0 } = params;
+    const subgraphUrl = params.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl) {
+      try {
+        const servers = await this._getUserTrustedServersViaSubgraph({
+          user,
+          subgraphUrl
+        });
+        return limit ? servers.slice(offset, offset + limit) : servers;
+      } catch (error) {
+        console.warn("Subgraph query failed, falling back to RPC:", error);
+      }
+    }
+    const rpcResult = await this._getUserTrustedServersViaRpc({
+      user,
+      limit,
+      offset
+    });
+    return rpcResult.servers;
+  }
+  /**
+   * Internal method: Query trusted servers via subgraph
+   *
+   * @param params - Query parameters object
+   * @param params.user - The user address to query trusted servers for
+   * @param params.subgraphUrl - The subgraph URL endpoint to query
+   * @returns Promise resolving to an array of trusted server objects
+   */
+  async _getUserTrustedServersViaSubgraph(params) {
+    const { user, subgraphUrl } = params;
+    const graphqlEndpoint = subgraphUrl;
+    if (!graphqlEndpoint) {
+      throw new Error(
+        "subgraphUrl is required for subgraph mode. Please provide a valid subgraph endpoint or configure it in Vana constructor."
+      );
+    }
+    try {
+      const response = await fetch(graphqlEndpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          query: print(GetUserTrustedServersDocument),
+          variables: {
+            userId: user.toLowerCase()
+            // Subgraph requires lowercase addresses
+          }
+        })
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Subgraph request failed: ${response.status} ${response.statusText}`
+        );
+      }
+      const result = await response.json();
+      if (result.errors) {
+        throw new Error(
+          `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
+        );
+      }
+      if (!result.data?.user) {
+        return [];
+      }
+      return (result.data.user.serverTrusts ?? []).filter((trust) => !trust.untrustedAtBlock).map((trust) => ({
+        id: trust.server.id,
+        serverAddress: trust.server.serverAddress,
+        serverUrl: trust.server.url,
+        trustedAt: BigInt(trust.trustedAt),
+        user,
+        name: ""
+        // Not available in new schema, will be empty
+      }));
+    } catch (error) {
+      console.error("Failed to query trusted servers from subgraph:", error);
+      throw error;
+    }
+  }
+  /**
+   * Internal method: Query trusted servers via direct RPC
+   *
+   * @param params - Query parameters object
+   * @param params.user - The user address to query trusted servers for
+   * @param params.limit - Maximum number of results to return
+   * @param params.offset - Number of results to skip for pagination
+   * @returns Promise resolving to pagination result with servers, total count, and hasMore flag
+   */
+  async _getUserTrustedServersViaRpc(params) {
+    const { user, limit, offset } = params;
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const DataPortabilityServersAddress = getContractAddress(
+        chainId,
+        "DataPortabilityServers"
+      );
+      const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
+      const totalCount = await this.context.publicClient.readContract({
+        address: DataPortabilityServersAddress,
+        abi: DataPortabilityServersAbi,
+        functionName: "userServerIdsLength",
+        args: [user]
+      });
+      const total = Number(totalCount);
+      if (total === 0 || offset >= total) {
+        return {
+          servers: [],
+          total,
+          hasMore: false
+        };
+      }
+      const endIndex = Math.min(offset + limit, total);
+      const serverIdCalls = [];
+      for (let i = offset; i < endIndex; i++) {
+        serverIdCalls.push({
+          address: DataPortabilityServersAddress,
+          abi: DataPortabilityServersAbi,
+          functionName: "userServerIdsAt",
+          args: [user, BigInt(i)]
+        });
+      }
+      const serverIdResults = await gasAwareMulticall(this.context.publicClient, {
+        contracts: serverIdCalls
+      });
+      const serverIds = serverIdResults.map((result) => result).filter((id) => id && id > 0n);
+      const serverInfoCalls = serverIds.map(
+        (serverId) => ({
+          address: DataPortabilityServersAddress,
+          abi: DataPortabilityServersAbi,
+          functionName: "servers",
+          args: [serverId]
+        })
+      );
+      const serverInfoResults = await gasAwareMulticall(this.context.publicClient, {
+        contracts: serverInfoCalls,
+        allowFailure: true
+      });
+      const servers = serverInfoResults.map((result, index) => {
+        const serverId = serverIds[index];
+        if (result.status === "success" && result.result) {
+          const serverInfo = result.result;
+          return {
+            id: `${user.toLowerCase()}-${serverId.toString()}`,
+            serverAddress: serverInfo.serverAddress,
+            serverUrl: serverInfo.url,
+            trustedAt: BigInt(Date.now()),
+            user,
+            trustIndex: offset + index
+          };
+        } else {
+          return {
+            id: `${user.toLowerCase()}-${serverId.toString()}`,
+            serverAddress: "0x0000000000000000000000000000000000000000",
+            serverUrl: "",
+            trustedAt: BigInt(Date.now()),
+            user,
+            trustIndex: offset + index
+          };
+        }
+      });
+      return {
+        servers,
+        total,
+        hasMore: offset + limit < total
+      };
+    } catch (error) {
+      throw new Error(
+        `RPC query failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Retrieves total file count from Data Registry.
+   *
+   * @remarks
+   * Queries blockchain for complete file count across all users.
+   * Useful for pagination and network statistics.
+   *
+   * @returns Total number of registered files
+   *
+   * @throws {Error} Chain ID not available.
+   *   Ensure network connection.
+   * @throws {Error} Contract read failed.
+   *   Check RPC availability.
+   *
+   * @example
+   * ```typescript
+   * const total = await vana.data.getTotalFilesCount();
+   * console.log(`Total files: ${total}`);
+   *
+   * // Calculate pagination
+   * const pages = Math.ceil(total / 20);
+   * ```
+   */
+  async getTotalFilesCount() {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      const dataRegistry = getContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        client: this.context.publicClient
+      });
+      const count = await dataRegistry.read.filesCount();
+      return Number(count);
+    } catch (error) {
+      if (error instanceof Error && error.message === "Chain ID not available") {
+        throw error;
+      }
+      console.error("Failed to fetch total files count:", error);
+      return 0;
+    }
+  }
+  /**
+   * Retrieves file metadata by ID from the blockchain.
+   *
+   * @remarks
+   * Queries DataRegistry contract directly for file details.
+   * Works for any file ID regardless of ownership, enabling
+   * cross-user file discovery and verification.
+   *
+   * @param fileId - Numeric file ID to retrieve
+   *
+   * @returns UserFile object with metadata
+   *
+   * @throws {Error} Chain ID not available.
+   *   Ensure proper network connection.
+   * @throws {Error} File not found.
+   *   Verify file ID exists on-chain.
+   * @throws {Error} Contract call failed.
+   *   Check network and RPC availability.
+   *
+   * @example
+   * ```typescript
+   * const file = await vana.data.getFileById(123);
+   * console.log(`File ${file.id}:`);
+   * console.log(`  URL: ${file.url}`);
+   * console.log(`  Owner: ${file.ownerAddress}`);
+   * console.log(`  Block: ${file.addedAtBlock}`);
+   * ```
+   */
+  async getFileById(fileId) {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      const dataRegistry = getContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        client: this.context.publicClient
+      });
+      const fileDetails = await dataRegistry.read.files([BigInt(fileId)]);
+      if (!fileDetails) {
+        throw new Error("File not found");
+      }
+      if (Array.isArray(fileDetails)) {
+        const [id, url, ownerAddress, addedAtBlock] = fileDetails;
+        if (id === BigInt(0)) {
+          throw new Error("File not found");
+        }
+        return {
+          id: Number(id),
+          url,
+          ownerAddress,
+          addedAtBlock: BigInt(addedAtBlock)
+        };
+      } else {
+        if (!fileDetails.id || fileDetails.id === BigInt(0)) {
+          throw new Error("File not found");
+        }
+        return {
+          id: Number(fileDetails.id),
+          ownerAddress: fileDetails.ownerAddress,
+          url: fileDetails.url,
+          addedAtBlock: BigInt(fileDetails.addedAtBlock)
+        };
+      }
+    } catch (error) {
+      console.error("Failed to fetch file by ID:", error);
+      throw new Error(
+        `Failed to fetch file ${fileId}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Registers a file URL directly on the blockchain with a schema ID.
+   *
+   * @remarks
+   * This method registers an existing file URL on the DataRegistry contract
+   * with a schema ID, without uploading any data. Useful when you have already
+   * uploaded content to storage and just need to register it on-chain.
+   *
+   * @param url - The URL of the file to register (IPFS or HTTP/HTTPS)
+   * @param schemaId - The schema ID to associate with the file
+   * @returns Promise resolving to the file ID and transaction hash
+   * @throws {Error} When chain ID is not available - "Chain ID not available"
+   * @throws {Error} When wallet address is unavailable - "No addresses available"
+   * @throws {Error} When transaction fails - "Failed to register file with schema"
+   * @example
+   * ```typescript
+   * const { fileId, transactionHash } = await vana.data.registerFileWithSchema(
+   *   "ipfs://QmXxx...",
+   *   1
+   * );
+   * console.log(`File ${fileId} registered with schema in tx ${transactionHash}`);
+   * ```
+   */
+  async registerFileWithSchema(url, schemaId) {
+    this.assertWallet();
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      this.assertWallet();
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      const from = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        functionName: "addFileWithSchema",
+        args: [url, BigInt(schemaId)],
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from,
+        contract: "DataRegistry",
+        fn: "addFileWithSchema"
+      });
+    } catch (error) {
+      console.error("Failed to register file with schema:", error);
+      throw new Error(
+        `Registration failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Gets the user's address from the wallet client.
+   *
+   * @returns Promise resolving to the user's wallet address
+   * @throws {Error} When no addresses are available in wallet client
+   */
+  /**
+   * Adds a file with permissions to the DataRegistry contract.
+   *
+   * @param url - The file URL to register
+   * @param ownerAddress - The address of the file owner
+   * @param permissions - Array of permissions to set for the file
+   * @returns Promise resolving to file ID and transaction hash
+   * @throws {Error} When chain ID is not available
+   * @throws {ContractError} When contract execution fails
+   * @throws {Error} When transaction receipt is not available
+   * @throws {Error} When FileAdded event cannot be parsed
+   *
+   * This method handles the core logic of registering a file
+   * with specific permissions on the DataRegistry contract. It can be used
+   * by both direct transactions and relayer services.
+   */
+  async addFileWithPermissions(url, ownerAddress, permissions = [], options) {
+    this.assertWallet();
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      this.assertWallet();
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      const account = this.context.walletClient.account ?? ownerAddress;
+      const from = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        functionName: "addFileWithPermissions",
+        args: [url, ownerAddress, permissions],
+        account,
+        chain: this.context.walletClient.chain ?? null,
+        ...options && {
+          gas: options.gasLimit,
+          nonce: options.nonce,
+          // Use EIP-1559 gas pricing if available, otherwise legacy
+          ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+            maxFeePerGas: options.maxFeePerGas,
+            maxPriorityFeePerGas: options.maxPriorityFeePerGas
+          } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+        }
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from,
+        contract: "DataRegistry",
+        fn: "addFileWithPermissions"
+      });
+    } catch (error) {
+      console.error("Failed to add file with permissions:", error);
+      throw new Error(
+        `Failed to add file with permissions: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Adds a file to the registry with permissions and schema.
+   * This combines the functionality of addFileWithPermissions and schema validation.
+   *
+   * @remarks
+   * This method automatically encrypts permissions when a publicKey is provided.
+   * It generates the user's encryption key and encrypts it with each recipient's
+   * public key before registering on the blockchain.
+   *
+   * @param url - The URL of the file to register
+   * @param ownerAddress - The address of the file owner
+   * @param permissions - Array of permissions to grant, each with account and publicKey properties
+   * @param schemaId - The schema ID to associate with the file (0 for no schema)
+   * @returns Promise resolving to TransactionResult with fileId and transactionHash
+   * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+   * @throws {Error} "Failed to generate encryption key" - When encryption key generation fails
+   * @throws {Error} "Permission for {account} must include 'publicKey'" - When publicKey is missing
+   * @throws {Error} "Failed to add file with permissions and schema: {error}" - When transaction fails
+   * @example
+   * ```typescript
+   * // Get server's public key
+   * const serverIdentity = await vana.server.getIdentity({
+   *   userAddress: "0x..."
+   * });
+   *
+   * // Add file with permissions and schema
+   * const result = await vana.data.addFileWithPermissionsAndSchema(
+   *   "ipfs://QmXxx...",
+   *   ownerAddress,
+   *   [{
+   *     account: serverIdentity.address,
+   *     publicKey: serverIdentity.publicKey
+   *   }],
+   *   schemaId
+   * );
+   *
+   * console.log(`File ${result.fileId} registered in tx ${result.hash}`);
+   * ```
+   */
+  async addFileWithPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0) {
+    this.assertWallet();
+    try {
+      let encryptedPermissions = [];
+      if (permissions.length > 0) {
+        this.assertWallet();
+        const userEncryptionKey = await generateEncryptionKey(
+          this.context.walletClient,
+          this.context.platform,
+          DEFAULT_ENCRYPTION_SEED
+        );
+        encryptedPermissions = await Promise.all(
+          permissions.map(async (permission) => {
+            if (!permission.publicKey) {
+              throw new Error(
+                `Permission for ${permission.account} must include 'publicKey'`
+              );
+            }
+            const encryptedKey = await encryptWithWalletPublicKey(
+              userEncryptionKey,
+              permission.publicKey,
+              this.context.platform
+            );
+            return {
+              account: permission.account,
+              key: encryptedKey
+            };
+          })
+        );
+      }
+      return await this.addFileWithEncryptedPermissionsAndSchema(
+        url,
+        ownerAddress,
+        encryptedPermissions,
+        schemaId
+      );
+    } catch (error) {
+      console.error("Failed to add file with permissions and schema:", error);
+      throw new Error(
+        `Failed to add file with permissions and schema: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Adds a file with pre-encrypted permissions and schema to the DataRegistry.
+   *
+   * @remarks
+   * This method is designed for relay services and advanced use cases where permissions
+   * have already been encrypted client-side. Unlike `addFileWithPermissionsAndSchema()`,
+   * this method expects permissions in the encrypted format with a 'key' field instead
+   * of 'publicKey'.
+   *
+   * This is typically used by relay endpoints that receive pre-encrypted data from
+   * the client SDK's `upload()` method, avoiding double encryption.
+   *
+   * @param url - The storage URL of the file (e.g., IPFS URL)
+   * @param ownerAddress - The address that will own this file
+   * @param permissions - Array of pre-encrypted permissions with 'account' and 'key' fields
+   * @param schemaId - Optional schema ID for data validation (defaults to 0)
+   * @returns Promise resolving to transaction result with hash and contract details
+   * @throws {Error} When chain ID is not available
+   * @throws {Error} When wallet is not connected
+   * @throws {Error} When transaction fails
+   * @example
+   * ```typescript
+   * // In a relay endpoint that receives pre-encrypted permissions
+   * const result = await vana.data.addFileWithEncryptedPermissionsAndSchema(
+   *   "ipfs://QmXxx...",
+   *   ownerAddress,
+   *   [
+   *     {
+   *       account: "0xServerAddress...",
+   *       key: "encrypted_key_string" // Already encrypted by client
+   *     }
+   *   ],
+   *   schemaId
+   * );
+   *
+   * console.log(`File registered in tx ${result.hash}`);
+   * ```
+   */
+  async addFileWithEncryptedPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0, options) {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      this.assertWallet();
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      const account = this.context.walletClient.account ?? ownerAddress;
+      const from = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        functionName: "addFileWithPermissionsAndSchema",
+        args: [url, ownerAddress, permissions, BigInt(schemaId)],
+        account,
+        chain: this.context.walletClient.chain ?? null,
+        ...options && {
+          gas: options.gasLimit,
+          nonce: options.nonce,
+          // Use EIP-1559 gas pricing if available, otherwise legacy
+          ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+            maxFeePerGas: options.maxFeePerGas,
+            maxPriorityFeePerGas: options.maxPriorityFeePerGas
+          } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+        }
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from,
+        contract: "DataRegistry",
+        fn: "addFileWithPermissionsAndSchema"
+      });
+    } catch (error) {
+      console.error("Failed to add file with permissions and schema:", error);
+      throw new Error(
+        `Failed to add file with permissions and schema: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Registers a data refiner for processing templates.
+   *
+   * @remarks
+   * Refiners define data transformation rules for DLPs.
+   * Associates schema, instructions, and processing logic.
+   *
+   * @param params - Refiner configuration
+   * @param params.dlpId - Data Liquidity Pool ID
+   * @param params.name - Refiner display name
+   * @param params.schemaId - Output schema ID.
+   *   Obtain via `vana.schemas.list()`.
+   * @param params.refinementInstructionUrl - Processing instructions URL
+   *
+   * @returns Refiner ID and transaction hash
+   *
+   * @throws {Error} Chain ID not available.
+   *   Ensure network connection.
+   * @throws {Error} Transaction failed.
+   *   Check wallet balance and network status.
+   *
+   * @example
+   * ```typescript
+   * const result = await vana.data.addRefiner({
+   *   dlpId: 1,
+   *   name: "Sentiment Analyzer",
+   *   schemaId: 42,
+   *   refinementInstructionUrl: "ipfs://QmXxx..."
+   * });
+   * console.log(`Refiner ${result.refinerId} created`);
+   * ```
+   */
+  async addRefiner(params) {
+    this.assertWallet();
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      this.assertWallet();
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      const from = typeof account === "string" ? account : account.address;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        functionName: "addRefinerWithSchemaId",
+        args: [
+          BigInt(params.dlpId),
+          params.name,
+          BigInt(params.schemaId),
+          params.refinementInstructionUrl
+        ],
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      const txResult = tx({
+        hash,
+        from,
+        contract: "DataRefinerRegistry",
+        fn: "addRefinerWithSchemaId"
+      });
+      if (!this.context.waitForTransactionEvents) {
+        throw new Error("waitForTransactionEvents not configured");
+      }
+      const result = await this.context.waitForTransactionEvents(txResult);
+      const event = result.expectedEvents.RefinerAdded;
+      if (!event) {
+        throw new Error("RefinerAdded event not found in transaction");
+      }
+      return {
+        refinerId: Number(event.refinerId),
+        transactionHash: hash
+      };
+    } catch (error) {
+      console.error("Failed to add refiner:", error);
+      throw new Error(
+        `Failed to add refiner: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Retrieves refiner configuration by ID.
+   *
+   * @remarks
+   * Queries DataRefinerRegistry for refiner details.
+   * Returns DLP association, schema, and processing instructions.
+   *
+   * @param refinerId - Numeric refiner ID
+   *
+   * @returns Refiner configuration object
+   *
+   * @throws {Error} Chain ID not available.
+   *   Ensure network connection.
+   * @throws {Error} Refiner not found.
+   *   Verify refiner ID exists.
+   * @throws {Error} Contract read failed.
+   *   Check network and RPC status.
+   *
+   * @example
+   * ```typescript
+   * const refiner = await vana.data.getRefiner(1);
+   * console.log(`Refiner: ${refiner.name}`);
+   * console.log(`DLP: ${refiner.dlpId}`);
+   * console.log(`Schema: ${refiner.schemaId}`);
+   * ```
+   */
+  async getRefiner(refinerId) {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      const dataRefinerRegistry = getContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        client: this.context.publicClient
+      });
+      const refinerData = await dataRefinerRegistry.read.refiners([
+        BigInt(refinerId)
+      ]);
+      if (!refinerData) {
+        throw new Error("Refiner not found");
+      }
+      return {
+        id: refinerId,
+        dlpId: Number(refinerData.dlpId),
+        owner: refinerData.owner,
+        name: refinerData.name,
+        schemaId: Number(refinerData.schemaId),
+        refinementInstructionUrl: refinerData.refinementInstructionUrl
+      };
+    } catch (error) {
+      console.error("Failed to get refiner:", error);
+      throw new Error(
+        `Failed to get refiner ${refinerId}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Validates schema ID existence.
+   *
+   * @remarks
+   * Verifies schema registration in DataRegistry.
+   * Check before using schemas for uploads.
+   *
+   * @param schemaId - Numeric schema ID to validate
+   *
+   * @returns True if schema exists, false otherwise
+   *
+   * @throws {Error} Chain ID not available.
+   *   Ensure network connection.
+   * @throws {Error} Contract read failed.
+   *   Check RPC availability.
+   *
+   * @example
+   * ```typescript
+   * const valid = await vana.data.isValidSchemaId(42);
+   * if (valid) {
+   *   // Safe to use schema 42
+   *   await vana.data.upload({ schemaId: 42, ... });
+   * }
+   * ```
+   */
+  async isValidSchemaId(schemaId) {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      const dataRefinerRegistry = getContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        client: this.context.publicClient
+      });
+      const isValid = await dataRefinerRegistry.read.isValidSchemaId([
+        BigInt(schemaId)
+      ]);
+      return isValid;
+    } catch (error) {
+      console.error("Failed to validate schema ID:", error);
+      return false;
+    }
+  }
+  /**
+   * Gets the total number of refiners in the registry.
+   *
+   * @remarks
+   * Queries the DataRefinerRegistry contract to get the total count of all
+   * registered refiners across all DLPs.
+   *
+   * @returns Promise resolving to the total refiner count
+   * @example
+   * ```typescript
+   * const count = await vana.data.getRefinersCount();
+   * console.log(`Total refiners registered: ${count}`);
+   * ```
+   */
+  async getRefinersCount() {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      const dataRefinerRegistry = getContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        client: this.context.publicClient
+      });
+      const count = await dataRefinerRegistry.read.refinersCount();
+      return Number(count);
+    } catch (error) {
+      console.error("Failed to get refiners count:", error);
+      return 0;
+    }
+  }
+  /**
+   * Updates the schema ID for an existing refiner.
+   *
+   * @remarks
+   * Allows the owner of a refiner to update its associated schema ID.
+   * This is useful when refiner output format needs to change.
+   *
+   * @param params - Update parameters
+   * @param params.refinerId - The refiner ID to update
+   * @param params.newSchemaId - The new schema ID to set
+   * @returns Promise resolving to the transaction hash
+   * @throws {Error} When chain ID is not available - "Chain ID not available"
+   * @throws {Error} When transaction fails - "Failed to update schema ID: {error}"
+   * @example
+   * ```typescript
+   * const result = await vana.data.updateSchemaId({
+   *   refinerId: 1,
+   *   newSchemaId: 55
+   * });
+   * console.log(`Schema updated in tx ${result.transactionHash}`);
+   * ```
+   */
+  async updateSchemaId(params) {
+    this.assertWallet();
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRefinerRegistryAddress = getContractAddress(
+        chainId,
+        "DataRefinerRegistry"
+      );
+      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
+      this.assertWallet();
+      const account = this.context.walletClient.account ?? this.context.userAddress;
+      const hash = await this.context.walletClient.writeContract({
+        address: dataRefinerRegistryAddress,
+        abi: dataRefinerRegistryAbi,
+        functionName: "updateSchemaId",
+        args: [BigInt(params.refinerId), BigInt(params.newSchemaId)],
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      await this.context.publicClient.waitForTransactionReceipt({ hash });
+      return {
+        transactionHash: hash
+      };
+    } catch (error) {
+      console.error("Failed to update schema ID:", error);
+      throw new Error(
+        `Failed to update schema ID: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Uploads an encrypted file and grants permission to a party with a public key.
+   *
+   * This method handles the complete workflow:
+   * 1. Encrypts the file with the user's encryption key
+   * 2. Uploads the encrypted file to storage
+   * 3. Encrypts the user's encryption key with the provided public key
+   * 4. Registers the file with permissions
+   *
+   * @param params - Upload parameters including data, permissions, and options
+   * @returns Promise resolving to upload result with file ID and storage URL
+   */
+  async uploadFileWithPermissions(params) {
+    this.assertWallet();
+    const { data, permissions, filename, providerName } = params;
+    try {
+      const uploadResult = await this.uploadToStorage(
+        data,
+        filename,
+        true,
+        // Always encrypt for uploadFileWithPermissions
+        providerName
+      );
+      const userAddress = this.context.userAddress;
+      const userEncryptionKey = await generateEncryptionKey(
+        this.context.walletClient,
+        this.context.platform,
+        DEFAULT_ENCRYPTION_SEED
+      );
+      const encryptedPermissions = await Promise.all(
+        permissions.map(async (permission) => {
+          const encryptedKey = await encryptWithWalletPublicKey(
+            userEncryptionKey,
+            permission.publicKey,
+            this.context.platform
+          );
+          return {
+            account: permission.account,
+            key: encryptedKey
+          };
+        })
+      );
+      if (this.context.relayer) {
+        const request = {
+          type: "direct",
+          operation: "submitFileAdditionWithPermissions",
+          params: {
+            url: uploadResult.url,
+            userAddress,
+            permissions: encryptedPermissions
+          }
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new Error(response.error);
+        }
+        if (response.type !== "direct" || !("fileId" in response.result)) {
+          throw new Error("Invalid response from relayer");
+        }
+        const result = response.result;
+        return {
+          fileId: result.fileId,
+          url: uploadResult.url,
+          size: uploadResult.size,
+          transactionHash: result.transactionHash
+        };
+      } else {
+        const txResult = await this.addFileWithPermissions(
+          uploadResult.url,
+          userAddress,
+          encryptedPermissions
+        );
+        if (!this.context.waitForTransactionEvents) {
+          throw new Error(
+            "Cannot upload without relay: waitForTransactionEvents not configured"
+          );
+        }
+        const eventResult = await this.context.waitForTransactionEvents(txResult);
+        const fileAddedEvent = eventResult.expectedEvents.FileAdded;
+        if (!fileAddedEvent) {
+          throw new Error("FileAdded event not found in transaction");
+        }
+        return {
+          fileId: Number(fileAddedEvent.fileId),
+          url: uploadResult.url,
+          size: uploadResult.size,
+          transactionHash: txResult.hash
+        };
+      }
+    } catch (error) {
+      console.error("Failed to upload file with permissions:", error);
+      throw new Error(
+        `Failed to upload file with permissions: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Uploads content to storage without registering it on the blockchain.
+   * This method only handles the storage upload and returns the file URL.
+   *
+   * @param content - The content to upload (string, Blob, Buffer, or object - objects will be JSON stringified)
+   * @param filename - Optional filename for the uploaded file (defaults to timestamp-based name)
+   * @param encrypt  - Optional flag to encrypt the content before upload
+   * @param providerName - Optional specific storage provider to use
+   * @returns Promise resolving to the storage upload result with url, size, and contentType
+   */
+  async uploadToStorage(content, filename, encrypt = false, providerName) {
+    try {
+      let blob;
+      if (content instanceof Blob) {
+        blob = content;
+      } else if (typeof content === "string") {
+        blob = new Blob([content], { type: "text/plain" });
+      } else if (content instanceof Buffer) {
+        const arrayBuffer = content.buffer.slice(
+          content.byteOffset,
+          content.byteOffset + content.byteLength
+        );
+        blob = new Blob([arrayBuffer], { type: "application/octet-stream" });
+      } else {
+        blob = new Blob([JSON.stringify(content)], {
+          type: "application/json"
+        });
+      }
+      let finalBlob = blob;
+      if (encrypt) {
+        this.assertWallet();
+        const encryptionKey = await generateEncryptionKey(
+          this.context.walletClient,
+          this.context.platform,
+          DEFAULT_ENCRYPTION_SEED
+        );
+        finalBlob = await encryptBlobWithSignedKey(
+          blob,
+          encryptionKey,
+          this.context.platform
+        );
+      }
+      if (!this.context.storageManager) {
+        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 finalFilename = filename ?? encrypt ? `upload-${Date.now()}.enc` : `upload-${Date.now()}.dat`;
+      const uploadResult = await this.context.storageManager.upload(
+        finalBlob,
+        finalFilename,
+        providerName
+      );
+      return uploadResult;
+    } catch (error) {
+      throw new Error(
+        `Upload failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Adds a permission for a party to access an existing file.
+   *
+   * This method handles the complete workflow:
+   * 1. Gets the user's encryption key
+   * 2. Encrypts the user's encryption key with the provided public key
+   * 3. Adds the permission to the file
+   * 4. Returns the permission data from the blockchain event
+   *
+   * For advanced users who need more control over transaction timing,
+   * use `submitFilePermission()` instead.
+   *
+   * @param params - Parameters for adding file permission
+   * @param params.fileId - The ID of the file to grant permission for
+   * @param params.account - The recipient's wallet address that will access the file
+   * @param params.publicKey - The recipient's public key for encryption.
+   *   Obtain via `vana.server.getIdentity(account).publicKey`
+   * @returns Promise resolving to permission data from PermissionGranted event
+   * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
+   * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+   * @throws {Error} "Failed to add permission to file: {error}" - When transaction fails or user doesn't own file
+   * @example
+   * ```typescript
+   * const result = await vana.data.addPermissionToFile({
+   *   fileId: 123,
+   *   account: "0xRecipientAddress...",
+   *   publicKey: "0xRecipientPublicKey..."
+   * });
+   * console.log(`Permission granted to ${result.account} for file ${result.fileId}`);
+   * console.log(`Transaction: ${result.transactionHash}`);
+   * ```
+   */
+  async addPermissionToFile(params) {
+    this.assertWallet();
+    const { fileId, account, publicKey } = params;
+    return await this.submitFilePermission(fileId, account, publicKey);
+  }
+  /**
+   * Submits a file permission transaction to the blockchain.
+   *
+   * @remarks
+   * This method supports gasless transactions via relayer callbacks when configured.
+   * It encrypts the user's encryption key with the recipient's public key before submission.
+   * Use this when you want to handle transaction confirmation and event parsing separately.
+   *
+   * @param fileId - The ID of the file to grant permission for
+   * @param account - The recipient's wallet address that will access the file
+   * @param publicKey - The recipient's public key for encryption.
+   *   Obtain via `vana.server.getIdentity(account).publicKey`
+   * @returns Promise resolving to TransactionResult for tracking the transaction
+   * @throws {Error} When chain ID is not available
+   * @throws {Error} When encryption key generation fails
+   * @throws {Error} When public key encryption fails
+   *
+   * @example
+   * ```typescript
+   * const tx = await vana.data.submitFilePermission(
+   *   fileId,
+   *   "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+   *   recipientPublicKey
+   * );
+   * const result = await tx.waitForEvents();
+   * console.log(`Permission granted with ID: ${result.permissionId}`);
+   * ```
+   */
+  async submitFilePermission(fileId, account, publicKey) {
+    this.assertWallet();
+    try {
+      const userEncryptionKey = await generateEncryptionKey(
+        this.context.walletClient,
+        this.context.platform,
+        DEFAULT_ENCRYPTION_SEED
+      );
+      const encryptedKey = await encryptWithWalletPublicKey(
+        userEncryptionKey,
+        publicKey,
+        this.context.platform
+      );
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      this.assertWallet();
+      const walletAccount = this.context.walletClient.account ?? this.context.userAddress;
+      const txHash = await this.context.walletClient.writeContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        functionName: "addFilePermission",
+        args: [BigInt(fileId), account, encryptedKey],
+        account: walletAccount,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash: txHash,
+        from: typeof walletAccount === "string" ? walletAccount : walletAccount.address,
+        contract: "DataRegistry",
+        fn: "addFilePermission"
+      });
+    } catch (error) {
+      console.error("Failed to add permission to file:", error);
+      throw new Error(
+        `Failed to add permission to file: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Gets the encrypted key for a specific account's permission to access a file.
+   *
+   * @param fileId - The ID of the file
+   * @param account - The account address to get the permission for
+   * @returns Promise resolving to the encrypted key for that account
+   */
+  async getFilePermission(fileId, account) {
+    try {
+      const chainId = this.context.publicClient.chain?.id;
+      if (!chainId) {
+        throw new Error("Chain ID not available");
+      }
+      const dataRegistryAddress = getContractAddress(chainId, "DataRegistry");
+      const dataRegistryAbi = getAbi("DataRegistry");
+      const dataRegistry = getContract({
+        address: dataRegistryAddress,
+        abi: dataRegistryAbi,
+        client: this.context.publicClient
+      });
+      const encryptedKey = await dataRegistry.read.filePermissions([
+        BigInt(fileId),
+        account
+      ]);
+      return encryptedKey;
+    } catch (error) {
+      console.error("Failed to get file permission:", error);
+      throw new Error(
+        `Failed to get file permission: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Decrypts a file that the user has permission to access using their private key.
+   *
+   * This method handles the complete workflow for servers or other permitted parties:
+   * 1. Gets the encrypted encryption key from file permissions
+   * 2. Decrypts the encryption key using the provided private key
+   * 3. Downloads and decrypts the file data
+   *
+   * @param file - The file to decrypt
+   * @param privateKey - The private key to decrypt the user's encryption key
+   * @param options - Optional decryption configuration
+   * @param options.account - The account address that has permission (defaults to current wallet account)
+   * @returns Promise resolving to the decrypted file data
+   */
+  async decryptFileWithPermission(file, privateKey, options) {
+    try {
+      const permissionAccount = options?.account ?? this.context.userAddress;
+      const encryptedKey = await this.getFilePermission(
+        file.id,
+        permissionAccount
+      );
+      if (!encryptedKey) {
+        throw new Error(
+          `No permission found for account ${permissionAccount} to access file ${file.id}`
+        );
+      }
+      const userEncryptionKey = await decryptWithWalletPrivateKey(
+        encryptedKey,
+        privateKey,
+        this.context.platform
+      );
+      let encryptedData;
+      if (file.url.startsWith("ipfs://")) {
+        encryptedData = await this.fetchFromIPFS(file.url);
+      } else {
+        encryptedData = await this.fetch(file.url);
+      }
+      const decryptedData = await decryptBlobWithSignedKey(
+        encryptedData,
+        userEncryptionKey,
+        this.context.platform
+      );
+      return decryptedData;
+    } catch (error) {
+      console.error("Failed to decrypt file with permission:", error);
+      throw new Error(
+        `Failed to decrypt file with permission: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * 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} "HTTP error! status: {status} {statusText}" - When server returns error status
+   * @throws {Error} "Empty response" - When server returns no content
+   * @throws {Error} "Network error: Failed to fetch from {url}" - When network request fails
+   *
+   * @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 { universalFetch } = await import("../utils/download");
+      const response = await universalFetch(url, this.context.downloadRelayer);
+      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} "Invalid IPFS URL format" - When URL is not ipfs:// or valid CID
+   * @throws {Error} "Empty response" - When gateway returns no content
+   * @throws {Error} "HTTP error! status: {status}" - When gateway returns error status
+   * @throws {Error} "Failed to fetch IPFS content {cid} from all gateways" - When all gateways fail
+   *
+   * @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;
+    const { extractIpfsHash } = await import("../utils/ipfs");
+    const cid = extractIpfsHash(url);
+    if (!cid) {
+      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"
+        });
+      }
+    }
+    if (this.context.downloadRelayer && gateways.length > 0) {
+      try {
+        const relayerUrl = gateways[0].endsWith("/") ? `${gateways[0]}${cid}` : `${gateways[0]}/${cid}`;
+        return await this.context.downloadRelayer.proxyDownload(relayerUrl);
+      } catch (relayerError) {
+        errors.push({
+          gateway: "download-relayer",
+          error: `Proxy failed: ${relayerError instanceof Error ? relayerError.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 definition against the Vana meta-schema.
+   *
+   * @param schema - The data schema definition to validate
+   * @returns The validated DataSchema
+   * @throws SchemaValidationError if invalid
+   * @example
+   * ```typescript
+   * const schema = {
+   *   name: "User Profile",
+   *   version: "1.0.0",
+   *   dialect: "json",
+   *   schema: {
+   *     type: "object",
+   *     properties: {
+   *       name: { type: "string" },
+   *       age: { type: "number" }
+   *     }
+   *   }
+   * };
+   *
+   * const validatedSchema = vana.data.validateDataSchemaAgainstMetaSchema(schema);
+   * ```
+   */
+  validateDataSchemaAgainstMetaSchema(schema) {
+    return validateDataSchemaAgainstMetaSchema(schema);
+  }
+  /**
+   * Validates data against a JSON Schema from a data schema.
+   *
+   * @param data - The data to validate
+   * @param schema - The data schema containing the schema
+   * @returns Void (throws if validation fails)
+   * @throws SchemaValidationError if invalid
+   * @example
+   * ```typescript
+   * const schema = {
+   *   name: "User Profile",
+   *   version: "1.0.0",
+   *   dialect: "json",
+   *   schema: {
+   *     type: "object",
+   *     properties: {
+   *       name: { type: "string" },
+   *       age: { type: "number" }
+   *     },
+   *     required: ["name"]
+   *   }
+   * };
+   *
+   * const userData = { name: "Alice", age: 30 };
+   * vana.data.validateDataAgainstSchema(userData, schema);
+   * ```
+   */
+  validateDataAgainstSchema(data, schema) {
+    validateDataAgainstSchema(data, schema);
+  }
+  /**
+   * Fetches and validates a data schema from a URL, then returns the parsed data schema.
+   *
+   * @param url - The URL to fetch the data schema from
+   * @returns The validated data schema
+   * @throws SchemaValidationError if invalid or fetch fails
+   * @example
+   * ```typescript
+   * // Fetch and validate a schema from IPFS or HTTP
+   * const schema = await vana.data.fetchAndValidateSchema("https://example.com/schema.json");
+   * console.log(schema.name, schema.dialect);
+   *
+   * // Use the schema to validate user data
+   * if (schema.dialect === "json") {
+   *   vana.data.validateDataAgainstSchema(userData, schema);
+   * }
+   * ```
+   */
+  async fetchAndValidateSchema(url) {
+    return fetchAndValidateSchema(url);
+  }
+}
+export {
+  DataController
+};
+//# sourceMappingURL=data.js.map