@opendatalabs/vana-sdk 0.1.0-alpha.eebb656 → 0.1.0-alpha.ef15099

package/dist/controllers/data.js

@@ -1,14 +1,30 @@
 import { getContract } from "viem";
-import { getContractAddress } from "../config/addresses";
+import { PollingManager } from "../core/pollingManager";
+import { BaseController } from "./base";
+import { getContractAddress } from "../generated/addresses";
 import { getAbi } from "../generated/abi";
+import { InvalidConfigurationError } from "../errors";
 import {
-  GetUserFilesDocument,
+  GetUserFilesPaginatedDocument,
   GetFileProofsDocument,
   GetDlpDocument,
-  GetUserPermissionsDocument,
-  GetUserTrustedServersDocument
+  GetUserPermissionsPaginatedDocument,
+  GetUserTrustedServersPaginatedDocument
 } from "../generated/subgraph";
 import { print } from "graphql";
+import {
+  checkSubgraphConsistency,
+  fetchSubgraphMeta
+} from "../utils/subgraphConsistency";
+import {
+  executePaginatedQuery,
+  mapOrderByToEnum,
+  mapOrderDirection
+} from "../utils/subgraphPagination";
+import {
+  getUserFilesFromChain,
+  determineDataSource
+} from "../utils/chainQuery";
 import {
   generateEncryptionKey,
   decryptBlobWithSignedKey,
@@ -23,11 +39,12 @@ import {
   fetchAndValidateSchema
 } from "../utils/schemaValidation";
 import { gasAwareMulticall } from "../utils/multicall";
-class DataController {
+class DataController extends BaseController {
   constructor(context) {
-    this.context = context;
+    super(context);
   }
   async upload(params) {
+    this.assertWallet();
     const {
       content,
       filename,
@@ -35,12 +52,18 @@ class DataController {
       permissions = [],
       encrypt = true,
       providerName,
-      owner
+      owner,
+      schemaValidation = "strict"
     } = params;
+    if (encrypt && owner && owner.toLowerCase() !== this.context.userAddress.toLowerCase()) {
+      throw new InvalidConfigurationError(
+        "The 'owner' parameter cannot be different from the connected wallet's address when encryption is enabled. This would create an un-decryptable file."
+      );
+    }
     try {
       let isValid = true;
       let validationErrors = [];
-      if (schemaId !== void 0) {
+      if (schemaId !== void 0 && schemaValidation !== "skip") {
         try {
           const { SchemaController } = await import("./schemas");
           const schemaController = new SchemaController(this.context);
@@ -64,16 +87,20 @@ class DataController {
           }
           validateDataAgainstSchema(parsedContent, schema);
         } catch (error) {
-          isValid = false;
-          if (error instanceof Error) {
-            const errorDetails = error.errors;
-            if (errorDetails && Array.isArray(errorDetails)) {
-              validationErrors = errorDetails;
-            } else {
-              validationErrors = [error.message];
+          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);
+              }
             }
-          } else {
-            validationErrors = ["Schema validation failed"];
+            isValid = false;
+            validationErrors = error instanceof Error ? [error.message] : ["Schema validation failed"];
           }
         }
       }
@@ -83,9 +110,10 @@ class DataController {
         encrypt,
         providerName
       );
-      const userAddress = owner ?? await this.getUserAddress();
+      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,
@@ -106,29 +134,35 @@ class DataController {
         );
       }
       let result;
-      if (this.context.relayerCallbacks?.submitFileAdditionComplete) {
-        result = await this.context.relayerCallbacks.submitFileAdditionComplete(
-          {
+      if (this.context.relayer) {
+        const request = {
+          type: "direct",
+          operation: "submitFileAdditionComplete",
+          params: {
             url: uploadResult.url,
             userAddress,
             permissions: encryptedPermissions,
             schemaId: schemaId ?? 0,
             ownerAddress: owner
           }
-        );
-      } else if (this.context.relayerCallbacks?.submitFileAddition) {
-        const needsComplexRegistration = schemaId !== void 0 || encryptedPermissions.length > 0;
-        if (needsComplexRegistration) {
-          throw new Error(
-            "The configured relay callback does not support schemas or permissions. Please update your relay server implementation to provide the `submitFileAdditionComplete` callback."
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new Error(response.error);
+        }
+        if (response.type === "pending") {
+          result = await this.pollRelayerForConfirmation(
+            response.operationId,
+            void 0
+            // TODO: Add TransactionOptions to upload method signature
           );
+        } else if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "fileId" in response.result) {
+          result = response.result;
+        } else {
+          throw new Error("Invalid response from relayer");
         }
-        result = await this.context.relayerCallbacks.submitFileAddition(
-          uploadResult.url,
-          userAddress
-        );
       } else {
-        const txResult = await this._addFileWithPermissionsAndSchemaInternal(
+        const txResult = await this.addFileWithEncryptedPermissionsAndSchema(
           uploadResult.url,
           userAddress,
           encryptedPermissions,
@@ -164,35 +198,110 @@ class DataController {
     }
   }
   /**
-   * Decrypts a file owned by the user using their wallet signature.
+   * Encrypts data using wallet-derived encryption.
    *
    * @remarks
-   * This is the high-level convenience method for decrypting user files, serving as the
-   * symmetrical counterpart to the `upload` method. It handles the complete decryption
-   * workflow including key generation, URL protocol detection, content fetching, and
-   * decryption.
+   * 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 the decryption key from the user's wallet signature
-   * - Determines the appropriate fetch method based on the file URL protocol
-   * - Fetches the encrypted content from IPFS or standard HTTP URLs
-   * - Decrypts the content using the generated key
-   *
-   * For IPFS URLs, the method uses gateway fallback for improved reliability. For
-   * standard HTTP URLs, it uses a simple fetch. If you need custom authentication
-   * headers or specific gateway configurations, use the low-level primitives directly.
-   *
-   * @param file - The user file to decrypt (typically from getUserFiles)
-   * @param encryptionSeed - Optional custom encryption seed (defaults to Vana standard)
-   * @returns Promise resolving to the decrypted file content as a Blob
-   * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
-   * @throws {Error} "Network error: Cannot access the file URL" - When file URL is inaccessible (CORS, server down)
-   * @throws {Error} "File not found: The encrypted file is no longer available" - When file returns 404
-   * @throws {Error} "Access denied" - When file returns 403 (no permission)
-   * @throws {Error} "File is empty or could not be retrieved" - When file has no content
-   * @throws {Error} "Invalid file format: This file doesn't appear to be encrypted with the Vana protocol" - When file is not properly encrypted
-   * @throws {Error} "Wrong encryption key" - When decryption fails due to incorrect key/seed
-   * @throws {Error} "Failed to decrypt file: {error}" - General decryption failures
+   * - 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
@@ -218,12 +327,14 @@ class DataController {
    * fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
    * ```
    */
-  async decryptFile(file, encryptionSeed) {
+  async decryptFile(file, options) {
+    this.assertWallet();
     try {
+      this.assertWallet();
       const encryptionKey = await generateEncryptionKey(
         this.context.walletClient,
         this.context.platform,
-        encryptionSeed ?? DEFAULT_ENCRYPTION_SEED
+        options?.seed ?? DEFAULT_ENCRYPTION_SEED
       );
       let encryptedBlob;
       try {
@@ -306,99 +417,126 @@ class DataController {
     }
   }
   /**
-   * Retrieves all data files owned by a specific user address.
+   * Retrieves all files owned by a specific user address.
    *
    * @remarks
-   * This method queries the Vana subgraph to find files directly owned by the user.
-   * It efficiently handles large datasets by using the File entity's owner field
-   * and returns complete file metadata without additional contract calls.
-   *
-   * **Deduplication Behavior:**
-   * The method automatically deduplicates files by ID, keeping only the latest version
-   * (highest timestamp) when duplicate file IDs are found. This handles cases where
-   * the subgraph may contain multiple entries for the same file due to re-indexing
-   * or blockchain reorganizations.
-   * @param params - The query parameters object
-   * @param params.owner - The wallet address of the file owner to query
-   * @param params.subgraphUrl - Optional subgraph URL to override the default endpoint
-   * @returns A Promise that resolves to an array of UserFile objects with metadata, sorted by latest timestamp first
-   * @throws {Error} When subgraphUrl is not provided and not configured - "subgraphUrl is required"
-   * @throws {Error} When subgraph request fails - "Subgraph request failed: {status} {statusText}"
-   * @throws {Error} When subgraph returns errors - "Subgraph errors: {error messages}"
-   * @throws {Error} When JSON parsing fails - "Failed to fetch user files from subgraph: {error}"
+   * 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
-   * // Query files for a specific user
    * const files = await vana.data.getUserFiles({
-   *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+   *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
    * });
    *
    * files.forEach(file => {
-   *   console.log(`File ${file.id}: ${file.url} (Schema: ${file.schemaId})`);
+   *   console.log(`File ${file.id}: ${file.url}`);
+   *   console.log(`  Schema: ${file.schemaId}`);
+   *   console.log(`  DLPs: ${file.dlpIds?.join(", ") || "none"}`);
    * });
    * ```
    */
-  async getUserFiles(params) {
+  async getUserFiles(params, options) {
     const { owner, subgraphUrl } = params;
+    let dataSource = options?.source === "chain" ? "chain" : "subgraph";
+    if (options?.source === "auto" || !options?.source && options?.minBlock) {
+      const endpoint2 = subgraphUrl ?? this.context.subgraphUrl;
+      const currentBlock = await this.context.publicClient.getBlockNumber();
+      let subgraphBlock;
+      if (endpoint2) {
+        try {
+          const meta = await fetchSubgraphMeta(endpoint2);
+          subgraphBlock = meta.blockNumber;
+        } catch {
+          subgraphBlock = void 0;
+        }
+      }
+      dataSource = determineDataSource(
+        options?.source,
+        options?.minBlock,
+        currentBlock,
+        subgraphBlock
+      );
+    }
+    if (dataSource === "chain") {
+      const publicClient = this.context.publicClient;
+      const chainId = await publicClient.getChainId();
+      const contractAddress = getContractAddress(chainId, "DataRegistry");
+      const files = await getUserFilesFromChain(
+        publicClient,
+        contractAddress,
+        owner,
+        options?.minBlock ? BigInt(options.minBlock) : void 0
+      );
+      const limit = options?.fetchAll ? files.length : options?.limit ?? 100;
+      const offset = options?.offset ?? 0;
+      return files.slice(offset, offset + limit);
+    }
     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."
       );
     }
+    if (options?.minBlock || options?.waitForSync) {
+      await checkSubgraphConsistency(endpoint, options);
+    }
     try {
-      const response = await fetch(endpoint, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
+      const orderByMap = {
+        id: "id",
+        addedAtBlock: "addedAtBlock",
+        addedAtTimestamp: "addedAtTimestamp",
+        url: "url",
+        schemaId: "schemaId"
+      };
+      const allFiles = await executePaginatedQuery({
+        endpoint,
+        document: GetUserFilesPaginatedDocument,
+        baseVariables: {
+          userId: owner.toLowerCase(),
+          // Subgraph requires lowercase addresses
+          orderBy: mapOrderByToEnum(
+            options?.orderBy,
+            orderByMap,
+            "addedAtBlock"
+          ),
+          orderDirection: mapOrderDirection(
+            options?.orderDirection,
+            "asc",
+            "desc"
+          )
         },
-        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,
+        options,
+        extractItems: (data) => data?.user?.files,
+        transformItem: (file) => ({
+          id: parseInt(file.id),
           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) {
+      if (allFiles.length > 0) {
         try {
-          const fileIds = userFiles.map((f) => f.id);
+          const fileIds = allFiles.map((f) => f.id);
           let proofMap;
           try {
             proofMap = await this._fetchProofsFromSubgraph(fileIds, endpoint);
@@ -409,7 +547,7 @@ class DataController {
             );
             proofMap = await this._fetchProofsFromChain(fileIds);
           }
-          for (const file of userFiles) {
+          for (const file of allFiles) {
             const dlpIds = proofMap.get(file.id);
             if (dlpIds && dlpIds.length > 0) {
               file.dlpIds = dlpIds;
@@ -419,7 +557,7 @@ class DataController {
           console.warn("Failed to fetch proof data for files:", error);
         }
       }
-      return userFiles;
+      return allFiles;
     } catch (error) {
       console.error("Failed to fetch user files from subgraph:", error);
       throw new Error(
@@ -487,7 +625,7 @@ class DataController {
    * @returns Map of file IDs to their associated DLP IDs
    */
   async _fetchProofsFromChain(fileIds) {
-    const chainId = this.context.walletClient.chain?.id;
+    const chainId = this.context.publicClient.chain?.id;
     if (!chainId) {
       throw new Error("Chain ID not available");
     }
@@ -545,6 +683,9 @@ class DataController {
    */
   async getDLP(dlpId, options = {}) {
     const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl && (options.minBlock || options.waitForSync)) {
+      await checkSubgraphConsistency(subgraphUrl, options);
+    }
     if (subgraphUrl) {
       try {
         const response = await fetch(subgraphUrl, {
@@ -578,15 +719,15 @@ class DataController {
           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,
-          owner: result.data.dlp.owner
+          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.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -685,15 +826,15 @@ class DataController {
           name: dlp.name ?? "",
           metadata: dlp.metadata,
           status: dlp.status ? parseInt(dlp.status) : void 0,
-          address: dlp.address,
-          owner: dlp.owner
+          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.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -763,21 +904,33 @@ class DataController {
    * @returns Promise resolving to an array of permission objects
    * @throws Error if both subgraph and RPC queries fail
    */
-  async getUserPermissions(params) {
+  async getUserPermissions(params, options) {
     const { user, subgraphUrl } = params;
     const endpoint = subgraphUrl ?? this.context.subgraphUrl;
+    if (endpoint && (options?.minBlock || options?.waitForSync)) {
+      await checkSubgraphConsistency(endpoint, options);
+    }
     if (endpoint) {
       try {
-        const permissions = await this._getUserPermissionsViaSubgraph({
-          user,
-          subgraphUrl: endpoint
-        });
+        const permissions = await this._getUserPermissionsViaSubgraph(
+          {
+            user,
+            subgraphUrl: endpoint
+          },
+          options
+        );
         return permissions;
       } catch (error) {
         console.warn("Subgraph query failed, falling back to RPC:", error);
       }
     }
-    return await this._getUserPermissionsViaRpc({ user });
+    const allPermissions = await this._getUserPermissionsViaRpc({ user });
+    if (options && !options.fetchAll) {
+      const limit = options.limit ?? 100;
+      const offset = options.offset ?? 0;
+      return allPermissions.slice(offset, offset + limit);
+    }
+    return allPermissions;
   }
   /**
    * Internal method: Query user permissions via subgraph
@@ -787,46 +940,48 @@ class DataController {
    * @param params.subgraphUrl - The subgraph URL endpoint to query
    * @returns Promise resolving to an array of permission objects
    */
-  async _getUserPermissionsViaSubgraph(params) {
+  async _getUserPermissionsViaSubgraph(params, options) {
     const { user, subgraphUrl } = params;
     try {
-      const response = await fetch(subgraphUrl, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
+      const orderByMap = {
+        id: "id",
+        addedAtBlock: "addedAtBlock",
+        addedAtTimestamp: "addedAtTimestamp",
+        grant: "grant",
+        nonce: "nonce",
+        startBlock: "startBlock",
+        endBlock: "endBlock"
+      };
+      const permissions = await executePaginatedQuery({
+        endpoint: subgraphUrl,
+        document: GetUserPermissionsPaginatedDocument,
+        baseVariables: {
+          userId: user.toLowerCase(),
+          orderBy: mapOrderByToEnum(
+            options?.orderBy,
+            orderByMap,
+            "addedAtTimestamp"
+          ),
+          orderDirection: mapOrderDirection(
+            options?.orderDirection,
+            "desc",
+            "asc"
+          )
         },
-        body: JSON.stringify({
-          query: print(GetUserPermissionsDocument),
-          variables: {
-            userId: user.toLowerCase()
-          }
+        options,
+        extractItems: (data) => data?.user?.permissions,
+        transformItem: (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
         })
       });
-      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));
+      return permissions;
     } catch (error) {
       console.error("Failed to query user permissions from subgraph:", error);
       throw error;
@@ -842,7 +997,7 @@ class DataController {
   async _getUserPermissionsViaRpc(params) {
     const { user } = params;
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -959,20 +1114,28 @@ class DataController {
    * });
    * ```
    */
-  async getUserTrustedServers(params) {
-    const { user, limit = 50, offset = 0 } = params;
+  async getUserTrustedServers(params, options) {
+    const { user } = params;
     const subgraphUrl = params.subgraphUrl ?? this.context.subgraphUrl;
+    if (subgraphUrl && (options?.minBlock || options?.waitForSync)) {
+      await checkSubgraphConsistency(subgraphUrl, options);
+    }
     if (subgraphUrl) {
       try {
-        const servers = await this._getUserTrustedServersViaSubgraph({
-          user,
-          subgraphUrl
-        });
-        return limit ? servers.slice(offset, offset + limit) : servers;
+        const servers = await this._getUserTrustedServersViaSubgraph(
+          {
+            user,
+            subgraphUrl
+          },
+          options
+        );
+        return servers;
       } catch (error) {
         console.warn("Subgraph query failed, falling back to RPC:", error);
       }
     }
+    const limit = options?.fetchAll ? Number.MAX_SAFE_INTEGER : options?.limit ?? 100;
+    const offset = options?.offset ?? 0;
     const rpcResult = await this._getUserTrustedServersViaRpc({
       user,
       limit,
@@ -988,7 +1151,7 @@ class DataController {
    * @param params.subgraphUrl - The subgraph URL endpoint to query
    * @returns Promise resolving to an array of trusted server objects
    */
-  async _getUserTrustedServersViaSubgraph(params) {
+  async _getUserTrustedServersViaSubgraph(params, options) {
     const { user, subgraphUrl } = params;
     const graphqlEndpoint = subgraphUrl;
     if (!graphqlEndpoint) {
@@ -997,42 +1160,46 @@ class DataController {
       );
     }
     try {
-      const response = await fetch(graphqlEndpoint, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
+      const orderByMap = {
+        id: "id",
+        trustedAt: "trustedAt",
+        trustedAtBlock: "trustedAtBlock",
+        server: "server",
+        user: "user"
+      };
+      const serverTrusts = await executePaginatedQuery({
+        endpoint: graphqlEndpoint,
+        document: GetUserTrustedServersPaginatedDocument,
+        baseVariables: {
+          userId: user.toLowerCase(),
+          // Subgraph requires lowercase addresses
+          orderBy: mapOrderByToEnum(
+            options?.orderBy,
+            orderByMap,
+            "trustedAtBlock"
+          ),
+          orderDirection: mapOrderDirection(
+            options?.orderDirection,
+            "desc",
+            "asc"
+          )
         },
-        body: JSON.stringify({
-          query: print(GetUserTrustedServersDocument),
-          variables: {
-            userId: user.toLowerCase()
-            // Subgraph requires lowercase addresses
-          }
+        options,
+        extractItems: (data) => {
+          const trusts = data?.user?.serverTrusts ?? [];
+          return trusts.filter((trust) => !trust.untrustedAtBlock);
+        },
+        transformItem: (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
         })
       });
-      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
-      }));
+      return serverTrusts;
     } catch (error) {
       console.error("Failed to query trusted servers from subgraph:", error);
       throw error;
@@ -1050,7 +1217,7 @@ class DataController {
   async _getUserTrustedServersViaRpc(params) {
     const { user, limit, offset } = params;
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1134,23 +1301,31 @@ class DataController {
     }
   }
   /**
-   * Gets the total number of files in the registry from the contract.
+   * 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.
    *
-   * @returns Promise resolving to the total file count
    * @example
    * ```typescript
-   * const totalFiles = await vana.data.getTotalFilesCount();
-   * console.log(`Total files in registry: ${totalFiles}`);
+   * const total = await vana.data.getTotalFilesCount();
+   * console.log(`Total files: ${total}`);
    *
-   * // Use for pagination calculations
-   * const filesPerPage = 20;
-   * const totalPages = Math.ceil(totalFiles / filesPerPage);
-   * console.log(`Total pages: ${totalPages}`);
+   * // Calculate pagination
+   * const pages = Math.ceil(total / 20);
    * ```
    */
   async getTotalFilesCount() {
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1159,7 +1334,7 @@ class DataController {
       const dataRegistry = getContract({
         address: dataRegistryAddress,
         abi: dataRegistryAbi,
-        client: this.context.walletClient
+        client: this.context.publicClient
       });
       const count = await dataRegistry.read.filesCount();
       return Number(count);
@@ -1172,36 +1347,36 @@ class DataController {
     }
   }
   /**
-   * Retrieves details for a specific file by its ID.
+   * 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.
    *
-   * @param fileId - The file ID to look up
-   * @returns Promise resolving to UserFile object
-   * @throws {Error} "Chain ID not available" - When wallet chain is not configured
-   * @throws {Error} "File not found" - When file ID doesn't exist or returns empty data
-   * @throws {Error} "Failed to fetch file {fileId}: {error}" - General contract read failures
    * @example
    * ```typescript
-   * try {
-   *   const file = await vana.data.getFileById(123);
-   *   console.log('File details:', {
-   *     id: file.id,
-   *     url: file.url,
-   *     owner: file.ownerAddress,
-   *     addedAt: file.addedAtBlock
-   *   });
-   * } catch (error) {
-   *   console.error('File not found or error retrieving file:', error);
-   * }
+   * 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}`);
    * ```
-   *
-   * This method queries the DataRegistry contract directly
-   * to get file details for any file ID, regardless of user ownership.
-   * This is useful for file lookup functionality where users can search
-   * for specific files by ID.
    */
   async getFileById(fileId) {
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1210,7 +1385,7 @@ class DataController {
       const dataRegistry = getContract({
         address: dataRegistryAddress,
         abi: dataRegistryAbi,
-        client: this.context.walletClient
+        client: this.context.publicClient
       });
       const fileDetails = await dataRegistry.read.files([BigInt(fileId)]);
       if (!fileDetails) {
@@ -1268,15 +1443,17 @@ class DataController {
    * console.log(`File ${fileId} registered with schema in tx ${transactionHash}`);
    * ```
    */
-  async registerFileWithSchema(url, schemaId) {
+  async registerFileWithSchema(url, schemaId, options) {
+    this.assertWallet();
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      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 ?? await this.getUserAddress();
+      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,
@@ -1284,7 +1461,8 @@ class DataController {
         functionName: "addFileWithSchema",
         args: [url, BigInt(schemaId)],
         account,
-        chain: this.context.walletClient.chain ?? null
+        chain: this.context.walletClient.chain ?? null,
+        ...this.spreadTransactionOptions(options)
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -1306,13 +1484,6 @@ class DataController {
    * @returns Promise resolving to the user's wallet address
    * @throws {Error} When no addresses are available in wallet client
    */
-  async getUserAddress() {
-    const addresses = await this.context.walletClient.getAddresses();
-    if (addresses.length === 0) {
-      throw new Error("No addresses available in wallet client");
-    }
-    return addresses[0];
-  }
   /**
    * Adds a file with permissions to the DataRegistry contract.
    *
@@ -1329,12 +1500,14 @@ class DataController {
    * with specific permissions on the DataRegistry contract. It can be used
    * by both direct transactions and relayer services.
    */
-  async addFileWithPermissions(url, ownerAddress, permissions = []) {
+  async addFileWithPermissions(url, ownerAddress, permissions = [], options) {
+    this.assertWallet();
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      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;
@@ -1345,7 +1518,8 @@ class DataController {
         functionName: "addFileWithPermissions",
         args: [url, ownerAddress, permissions],
         account,
-        chain: this.context.walletClient.chain ?? null
+        chain: this.context.walletClient.chain ?? null,
+        ...this.spreadTransactionOptions(options)
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -1400,10 +1574,12 @@ class DataController {
    * console.log(`File ${result.fileId} registered in tx ${result.hash}`);
    * ```
    */
-  async addFileWithPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0) {
+  async addFileWithPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0, options) {
+    this.assertWallet();
     try {
       let encryptedPermissions = [];
       if (permissions.length > 0) {
+        this.assertWallet();
         const userEncryptionKey = await generateEncryptionKey(
           this.context.walletClient,
           this.context.platform,
@@ -1428,11 +1604,12 @@ class DataController {
           })
         );
       }
-      return await this._addFileWithPermissionsAndSchemaInternal(
+      return await this.addFileWithEncryptedPermissionsAndSchema(
         url,
         ownerAddress,
         encryptedPermissions,
-        schemaId
+        schemaId,
+        options
       );
     } catch (error) {
       console.error("Failed to add file with permissions and schema:", error);
@@ -1442,15 +1619,50 @@ class DataController {
     }
   }
   /**
-   * Internal method to add file with encrypted permissions and schema.
-   * @private
+   * 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 _addFileWithPermissionsAndSchemaInternal(url, ownerAddress, permissions = [], schemaId = 0) {
+  async addFileWithEncryptedPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0, options) {
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      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;
@@ -1461,7 +1673,8 @@ class DataController {
         functionName: "addFileWithPermissionsAndSchema",
         args: [url, ownerAddress, permissions, BigInt(schemaId)],
         account,
-        chain: this.context.walletClient.chain ?? null
+        chain: this.context.walletClient.chain ?? null,
+        ...this.spreadTransactionOptions(options)
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -1478,36 +1691,41 @@ class DataController {
     }
   }
   /**
-   * Adds a new refiner to the DataRefinerRegistry.
+   * Registers a data refiner for processing templates.
    *
    * @remarks
-   * Refiners are data processing templates that define how raw data should be
-   * transformed into structured formats. Each refiner is associated with a DLP
-   * (Data Liquidity Pool), has a specific schema for output, and includes
-   * instructions for the refinement process.
-   *
-   * @param params - Refiner configuration parameters
-   * @param params.dlpId - The Data Liquidity Pool ID this refiner belongs to
-   * @param params.name - Human-readable name for the refiner
-   * @param params.schemaId - Schema ID that defines the output format
-   * @param params.refinementInstructionUrl - URL containing processing instructions
-   * @returns Promise resolving to the new refiner ID and transaction hash
-   * @throws {Error} When chain ID is not available - "Chain ID not available"
-   * @throws {Error} When transaction fails - "Failed to add refiner: {error}"
+   * 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: "Social Media Sentiment Analyzer",
+   *   name: "Sentiment Analyzer",
    *   schemaId: 42,
    *   refinementInstructionUrl: "ipfs://QmXxx..."
    * });
-   * console.log(`Created refiner ${result.refinerId} in tx ${result.transactionHash}`);
+   * console.log(`Refiner ${result.refinerId} created`);
    * ```
    */
-  async addRefiner(params) {
+  async addRefiner(params, options) {
+    this.assertWallet();
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1516,7 +1734,8 @@ class DataController {
         "DataRefinerRegistry"
       );
       const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      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,
@@ -1529,7 +1748,8 @@ class DataController {
           params.refinementInstructionUrl
         ],
         account,
-        chain: this.context.walletClient.chain ?? null
+        chain: this.context.walletClient.chain ?? null,
+        ...this.spreadTransactionOptions(options)
       });
       const { tx } = await import("../utils/transactionHelpers");
       const txResult = tx({
@@ -1558,31 +1778,34 @@ class DataController {
     }
   }
   /**
-   * Retrieves a refiner by its ID.
+   * Retrieves refiner configuration by ID.
    *
    * @remarks
-   * Queries the DataRefinerRegistry contract to get complete information about
-   * a specific refiner including its DLP association, schema, and instructions.
+   * 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.
    *
-   * @param refinerId - The numeric refiner ID to retrieve
-   * @returns Promise resolving to the refiner information object
-   * @throws {Error} When chain ID is not available - "Chain ID not available"
-   * @throws {Error} When refiner doesn't exist - "Refiner with ID {refinerId} does not exist"
-   * @throws {Error} When contract read fails - "Failed to fetch refiner: {error}"
    * @example
    * ```typescript
    * const refiner = await vana.data.getRefiner(1);
-   * console.log({
-   *   name: refiner.name,
-   *   dlp: refiner.dlpId,
-   *   schema: refiner.schemaId,
-   *   instructions: refiner.refinementInstructionUrl
-   * });
+   * console.log(`Refiner: ${refiner.name}`);
+   * console.log(`DLP: ${refiner.dlpId}`);
+   * console.log(`Schema: ${refiner.schemaId}`);
    * ```
    */
   async getRefiner(refinerId) {
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1594,7 +1817,7 @@ class DataController {
       const dataRefinerRegistry = getContract({
         address: dataRefinerRegistryAddress,
         abi: dataRefinerRegistryAbi,
-        client: this.context.walletClient
+        client: this.context.publicClient
       });
       const refinerData = await dataRefinerRegistry.read.refiners([
         BigInt(refinerId)
@@ -1618,27 +1841,33 @@ class DataController {
     }
   }
   /**
-   * Validates if a schema ID exists in the registry.
+   * Validates schema ID existence.
    *
    * @remarks
-   * Checks the DataRefinerRegistry contract to determine if a given schema ID
-   * has been registered and is available for use.
+   * 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.
    *
-   * @param schemaId - The numeric schema ID to validate
-   * @returns Promise resolving to true if schema exists, false otherwise
    * @example
    * ```typescript
-   * const isValid = await vana.data.isValidSchemaId(42);
-   * if (isValid) {
-   *   console.log('Schema 42 is available for use');
-   * } else {
-   *   console.log('Schema 42 does not exist');
+   * 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.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1650,7 +1879,7 @@ class DataController {
       const dataRefinerRegistry = getContract({
         address: dataRefinerRegistryAddress,
         abi: dataRefinerRegistryAbi,
-        client: this.context.walletClient
+        client: this.context.publicClient
       });
       const isValid = await dataRefinerRegistry.read.isValidSchemaId([
         BigInt(schemaId)
@@ -1677,7 +1906,7 @@ class DataController {
    */
   async getRefinersCount() {
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1689,7 +1918,7 @@ class DataController {
       const dataRefinerRegistry = getContract({
         address: dataRefinerRegistryAddress,
         abi: dataRefinerRegistryAbi,
-        client: this.context.walletClient
+        client: this.context.publicClient
       });
       const count = await dataRefinerRegistry.read.refinersCount();
       return Number(count);
@@ -1720,9 +1949,10 @@ class DataController {
    * console.log(`Schema updated in tx ${result.transactionHash}`);
    * ```
    */
-  async updateSchemaId(params) {
+  async updateSchemaId(params, options) {
+    this.assertWallet();
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -1731,14 +1961,16 @@ class DataController {
         "DataRefinerRegistry"
       );
       const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      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
+        chain: this.context.walletClient.chain ?? null,
+        ...this.spreadTransactionOptions(options)
       });
       await this.context.publicClient.waitForTransactionReceipt({ hash });
       return {
@@ -1760,13 +1992,12 @@ class DataController {
    * 3. Encrypts the user's encryption key with the provided public key
    * 4. Registers the file with permissions
    *
-   * @param data - The file data to encrypt and upload
-   * @param permissions - Array of permissions to grant, each with account address and public key
-   * @param filename - Optional filename for the upload
-   * @param providerName - Optional storage provider to use
+   * @param params - Upload parameters including data, permissions, and options
    * @returns Promise resolving to upload result with file ID and storage URL
    */
-  async uploadFileWithPermissions(data, permissions, filename, providerName) {
+  async uploadFileWithPermissions(params) {
+    this.assertWallet();
+    const { data, permissions, filename, providerName } = params;
     try {
       const uploadResult = await this.uploadToStorage(
         data,
@@ -1775,7 +2006,7 @@ class DataController {
         // Always encrypt for uploadFileWithPermissions
         providerName
       );
-      const userAddress = await this.getUserAddress();
+      const userAddress = this.context.userAddress;
       const userEncryptionKey = await generateEncryptionKey(
         this.context.walletClient,
         this.context.platform,
@@ -1794,12 +2025,32 @@ class DataController {
           };
         })
       );
-      if (this.context.relayerCallbacks?.submitFileAdditionWithPermissions) {
-        const result = await this.context.relayerCallbacks.submitFileAdditionWithPermissions(
-          uploadResult.url,
-          userAddress,
-          encryptedPermissions
-        );
+      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);
+        }
+        let result;
+        if (response.type === "pending") {
+          result = await this.pollRelayerForConfirmation(
+            response.operationId,
+            void 0
+            // TODO: Add TransactionOptions to upload method signature
+          );
+        } else if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "fileId" in response.result) {
+          result = response.result;
+        } else {
+          throw new Error("Invalid response from relayer");
+        }
         return {
           fileId: result.fileId,
           url: uploadResult.url,
@@ -1866,6 +2117,7 @@ class DataController {
       }
       let finalBlob = blob;
       if (encrypt) {
+        this.assertWallet();
         const encryptionKey = await generateEncryptionKey(
           this.context.walletClient,
           this.context.platform,
@@ -1887,7 +2139,15 @@ class DataController {
           );
         }
       }
-      const finalFilename = filename ?? `upload-${Date.now()}.dat`;
+      const finalFilename = (() => {
+        if (filename) {
+          if (encrypt && !filename.endsWith(".enc")) {
+            return `${filename}.enc`;
+          }
+          return filename;
+        }
+        return encrypt ? `upload-${Date.now()}.enc` : `upload-${Date.now()}.dat`;
+      })();
       const uploadResult = await this.context.storageManager.upload(
         finalBlob,
         finalFilename,
@@ -1912,22 +2172,30 @@ class DataController {
    * For advanced users who need more control over transaction timing,
    * use `submitFilePermission()` instead.
    *
-   * @param fileId - The ID of the file to add permissions for
-   * @param account - The address of the account to grant permission to
-   * @param publicKey - The public key to encrypt the user's encryption key with (hex string with 0x prefix)
+   * @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, account, publicKey);
+   * 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(fileId, account, publicKey) {
-    return await this.submitFilePermission(fileId, account, publicKey);
+  async addPermissionToFile(params, options) {
+    this.assertWallet();
+    const { fileId, account, publicKey } = params;
+    return await this.submitFilePermission(fileId, account, publicKey, options);
   }
   /**
    * Submits a file permission transaction to the blockchain.
@@ -1957,7 +2225,8 @@ class DataController {
    * console.log(`Permission granted with ID: ${result.permissionId}`);
    * ```
    */
-  async submitFilePermission(fileId, account, publicKey) {
+  async submitFilePermission(fileId, account, publicKey, options) {
+    this.assertWallet();
     try {
       const userEncryptionKey = await generateEncryptionKey(
         this.context.walletClient,
@@ -1969,20 +2238,22 @@ class DataController {
         publicKey,
         this.context.platform
       );
-      const chainId = this.context.walletClient.chain?.id;
+      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 walletAccount = this.context.walletClient.account ?? await this.getUserAddress();
+      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
+        chain: this.context.walletClient.chain ?? null,
+        ...this.spreadTransactionOptions(options)
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -2007,7 +2278,7 @@ class DataController {
    */
   async getFilePermission(fileId, account) {
     try {
-      const chainId = this.context.walletClient.chain?.id;
+      const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
         throw new Error("Chain ID not available");
       }
@@ -2016,7 +2287,7 @@ class DataController {
       const dataRegistry = getContract({
         address: dataRegistryAddress,
         abi: dataRegistryAbi,
-        client: this.context.walletClient
+        client: this.context.publicClient
       });
       const encryptedKey = await dataRegistry.read.filePermissions([
         BigInt(fileId),
@@ -2040,12 +2311,13 @@ class DataController {
    *
    * @param file - The file to decrypt
    * @param privateKey - The private key to decrypt the user's encryption key
-   * @param account - The account address that has permission (defaults to current wallet account)
+   * @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, account) {
+  async decryptFileWithPermission(file, privateKey, options) {
     try {
-      const permissionAccount = account ?? await this.getUserAddress();
+      const permissionAccount = options?.account ?? this.context.userAddress;
       const encryptedKey = await this.getFilePermission(
         file.id,
         permissionAccount
@@ -2327,6 +2599,26 @@ class DataController {
   async fetchAndValidateSchema(url) {
     return fetchAndValidateSchema(url);
   }
+  /**
+   * Polls for confirmation of a relayer operation.
+   * @internal
+   */
+  async pollRelayerForConfirmation(operationId, options) {
+    if (!this.context.relayer) {
+      throw new Error("Relayer not configured for polling");
+    }
+    const pollingManager = new PollingManager(this.context.relayer);
+    const result = await pollingManager.startPolling(operationId, {
+      signal: options?.signal,
+      onStatusUpdate: options?.onStatusUpdate,
+      ...options?.pollingOptions
+    });
+    return {
+      fileId: 0,
+      // This would need to be extracted from transaction events
+      transactionHash: result.hash
+    };
+  }
 }
 export {
   DataController