@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dc68f39

package/dist/controllers/data.js

@@ -1,4 +1,5 @@
 import { getContract } from "viem";
+import { BaseController } from "./base";
 import { getContractAddress } from "../config/addresses";
 import { getAbi } from "../generated/abi";
 import {
@@ -23,11 +24,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,
@@ -52,15 +54,29 @@ class DataController {
             } 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) {
           isValid = false;
-          validationErrors = [
-            error instanceof Error ? error.message : "Schema validation failed"
-          ];
+          if (error instanceof Error) {
+            const errorDetails = error.errors;
+            if (errorDetails && Array.isArray(errorDetails)) {
+              validationErrors = errorDetails;
+            } else {
+              validationErrors = [error.message];
+            }
+          } else {
+            validationErrors = ["Schema validation failed"];
+          }
         }
       }
       const uploadResult = await this.uploadToStorage(
@@ -69,9 +85,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,
@@ -98,7 +115,7 @@ class DataController {
             url: uploadResult.url,
             userAddress,
             permissions: encryptedPermissions,
-            schemaId: schemaId || 0,
+            schemaId: schemaId ?? 0,
             ownerAddress: owner
           }
         );
@@ -114,12 +131,26 @@ class DataController {
           userAddress
         );
       } else {
-        result = await this.addFileWithPermissionsAndSchema(
+        const txResult = await this.addFileWithEncryptedPermissionsAndSchema(
           uploadResult.url,
           userAddress,
           encryptedPermissions,
-          schemaId || 0
+          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,
@@ -135,6 +166,83 @@ class DataController {
       );
     }
   }
+  /**
+   * 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 owned by the user using their wallet signature.
    *
@@ -190,12 +298,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 {
@@ -312,7 +422,7 @@ class DataController {
    */
   async getUserFiles(params) {
     const { owner, subgraphUrl } = params;
-    const endpoint = subgraphUrl || this.context.subgraphUrl;
+    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."
@@ -344,7 +454,7 @@ class DataController {
         );
       }
       const user = result.data?.user;
-      if (!user || !user.files?.length) {
+      if (!user?.files?.length) {
         console.warn("No files found for user:", owner);
         return [];
       }
@@ -366,7 +476,7 @@ class DataController {
         }
       });
       const userFiles = Array.from(fileMap.values()).sort(
-        (a, b) => Number((b.addedAtTimestamp || 0n) - (a.addedAtTimestamp || 0n))
+        (a, b) => Number((b.addedAtTimestamp ?? 0n) - (a.addedAtTimestamp ?? 0n))
       );
       if (userFiles.length > 0) {
         try {
@@ -437,10 +547,11 @@ class DataController {
         if (proof.dlp?.id) {
           const fileId = parseInt(proof.fileId);
           const dlpId = parseInt(proof.dlp.id);
-          if (!proofMap.has(fileId)) {
-            proofMap.set(fileId, []);
+          let dlpIds = proofMap.get(fileId);
+          if (!dlpIds) {
+            dlpIds = [];
+            proofMap.set(fileId, dlpIds);
           }
-          const dlpIds = proofMap.get(fileId);
           if (!dlpIds.includes(dlpId)) {
             dlpIds.push(dlpId);
           }
@@ -458,7 +569,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");
     }
@@ -515,7 +626,7 @@ class DataController {
    * ```
    */
   async getDLP(dlpId, options = {}) {
-    const subgraphUrl = options.subgraphUrl || this.context.subgraphUrl;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
     if (subgraphUrl) {
       try {
         const response = await fetch(subgraphUrl, {
@@ -546,18 +657,18 @@ class DataController {
         }
         return {
           id: parseInt(result.data.dlp.id),
-          name: result.data.dlp.name || "",
-          metadata: result.data.dlp.metadata || void 0,
+          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");
       }
@@ -569,7 +680,7 @@ class DataController {
         functionName: "dlps",
         args: [BigInt(dlpId)]
       });
-      if (!dlpData || !dlpData.name) {
+      if (!dlpData?.name) {
         throw new Error(`DLP not found: ${dlpId}`);
       }
       return {
@@ -611,7 +722,7 @@ class DataController {
    */
   async listDLPs(options = {}) {
     const { limit = 100, offset = 0 } = options;
-    const subgraphUrl = options.subgraphUrl || this.context.subgraphUrl;
+    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
     if (subgraphUrl) {
       try {
         const query = `
@@ -650,21 +761,21 @@ class DataController {
             `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
           );
         }
-        const dlps = result.data?.dlps || [];
+        const dlps = result.data?.dlps ?? [];
         return dlps.map((dlp) => ({
           id: parseInt(dlp.id),
-          name: dlp.name || "",
+          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");
       }
@@ -736,7 +847,7 @@ class DataController {
    */
   async getUserPermissions(params) {
     const { user, subgraphUrl } = params;
-    const endpoint = subgraphUrl || this.context.subgraphUrl;
+    const endpoint = subgraphUrl ?? this.context.subgraphUrl;
     if (endpoint) {
       try {
         const permissions = await this._getUserPermissionsViaSubgraph({
@@ -785,7 +896,7 @@ class DataController {
         );
       }
       const userData = result.data?.user;
-      if (!userData || !userData.permissions?.length) {
+      if (!userData?.permissions?.length) {
         return [];
       }
       return userData.permissions.map((permission) => ({
@@ -813,7 +924,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");
       }
@@ -932,7 +1043,7 @@ class DataController {
    */
   async getUserTrustedServers(params) {
     const { user, limit = 50, offset = 0 } = params;
-    const subgraphUrl = params.subgraphUrl || this.context.subgraphUrl;
+    const subgraphUrl = params.subgraphUrl ?? this.context.subgraphUrl;
     if (subgraphUrl) {
       try {
         const servers = await this._getUserTrustedServersViaSubgraph({
@@ -995,7 +1106,7 @@ class DataController {
       if (!result.data?.user) {
         return [];
       }
-      return (result.data.user.serverTrusts || []).filter((trust) => !trust.untrustedAtBlock).map((trust) => ({
+      return (result.data.user.serverTrusts ?? []).filter((trust) => !trust.untrustedAtBlock).map((trust) => ({
         id: trust.server.id,
         serverAddress: trust.server.serverAddress,
         serverUrl: trust.server.url,
@@ -1021,7 +1132,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");
       }
@@ -1121,7 +1232,7 @@ class DataController {
    */
   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");
       }
@@ -1130,7 +1241,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,7 +1283,7 @@ class DataController {
    */
   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");
       }
@@ -1181,7 +1292,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) {
@@ -1240,34 +1351,32 @@ class DataController {
    * ```
    */
   async registerFileWithSchema(url, schemaId) {
+    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 userAddress = await this.getUserAddress();
-      const txHash = await this.context.walletClient.writeContract({
+      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: this.context.walletClient.account || userAddress,
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from,
+        contract: "DataRegistry",
+        fn: "addFileWithSchema"
       });
-      const receipt = await this.context.publicClient.waitForTransactionReceipt(
-        {
-          hash: txHash,
-          confirmations: 1
-        }
-      );
-      const { parseFileAddedEvent } = await import("../utils/eventParsing");
-      const eventData = parseFileAddedEvent(receipt);
-      return {
-        fileId: Number(eventData.fileId),
-        transactionHash: txHash
-      };
     } catch (error) {
       console.error("Failed to register file with schema:", error);
       throw new Error(
@@ -1281,13 +1390,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.
    *
@@ -1305,33 +1407,32 @@ class DataController {
    * by both direct transactions and relayer services.
    */
   async addFileWithPermissions(url, ownerAddress, permissions = []) {
+    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 txHash = await this.context.walletClient.writeContract({
+      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: this.context.walletClient.account || ownerAddress,
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from,
+        contract: "DataRegistry",
+        fn: "addFileWithPermissions"
       });
-      const receipt = await this.context.publicClient.waitForTransactionReceipt(
-        {
-          hash: txHash,
-          confirmations: 1
-        }
-      );
-      const { parseFileAddedEvent } = await import("../utils/eventParsing");
-      const eventData = parseFileAddedEvent(receipt);
-      return {
-        fileId: Number(eventData.fileId),
-        transactionHash: txHash
-      };
     } catch (error) {
       console.error("Failed to add file with permissions:", error);
       throw new Error(
@@ -1343,44 +1444,148 @@ class DataController {
    * 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 (account and encrypted key)
+   * @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 object with fileId and transactionHash
-   * @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
+   * @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) {
     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 txHash = await this.context.walletClient.writeContract({
+      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: this.context.walletClient.account || ownerAddress,
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient.chain ?? null
+      });
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from,
+        contract: "DataRegistry",
+        fn: "addFileWithPermissionsAndSchema"
       });
-      const receipt = await this.context.publicClient.waitForTransactionReceipt(
-        {
-          hash: txHash,
-          confirmations: 1
-        }
-      );
-      const { parseFileAddedEvent } = await import("../utils/eventParsing");
-      const eventData = parseFileAddedEvent(receipt);
-      return {
-        fileId: Number(eventData.fileId),
-        transactionHash: txHash
-      };
     } catch (error) {
       console.error("Failed to add file with permissions and schema:", error);
       throw new Error(
@@ -1417,8 +1622,9 @@ class DataController {
    * ```
    */
   async addRefiner(params) {
+    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");
       }
@@ -1427,7 +1633,10 @@ class DataController {
         "DataRefinerRegistry"
       );
       const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const txHash = await this.context.walletClient.writeContract({
+      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",
@@ -1437,20 +1646,27 @@ class DataController {
           BigInt(params.schemaId),
           params.refinementInstructionUrl
         ],
-        account: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient.chain ?? null
       });
-      const receipt = await this.context.publicClient.waitForTransactionReceipt(
-        {
-          hash: txHash,
-          confirmations: 1
-        }
-      );
-      const { parseRefinerAddedEvent } = await import("../utils/eventParsing");
-      const eventData = parseRefinerAddedEvent(receipt);
+      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(eventData.refinerId),
-        transactionHash: txHash
+        refinerId: Number(event.refinerId),
+        transactionHash: hash
       };
     } catch (error) {
       console.error("Failed to add refiner:", error);
@@ -1484,7 +1700,7 @@ class DataController {
    */
   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");
       }
@@ -1496,7 +1712,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)
@@ -1540,7 +1756,7 @@ class DataController {
    */
   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");
       }
@@ -1552,7 +1768,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)
@@ -1579,7 +1795,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");
       }
@@ -1591,7 +1807,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);
@@ -1623,8 +1839,9 @@ class DataController {
    * ```
    */
   async updateSchemaId(params) {
+    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");
       }
@@ -1633,20 +1850,19 @@ class DataController {
         "DataRefinerRegistry"
       );
       const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const txHash = await this.context.walletClient.writeContract({
+      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: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
-      });
-      await this.context.publicClient.waitForTransactionReceipt({
-        hash: txHash,
-        timeout: 3e4
+        account,
+        chain: this.context.walletClient.chain ?? null
       });
+      await this.context.publicClient.waitForTransactionReceipt({ hash });
       return {
-        transactionHash: txHash
+        transactionHash: hash
       };
     } catch (error) {
       console.error("Failed to update schema ID:", error);
@@ -1664,13 +1880,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,
@@ -1679,7 +1894,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,
@@ -1698,26 +1913,41 @@ class DataController {
           };
         })
       );
-      let result;
       if (this.context.relayerCallbacks?.submitFileAdditionWithPermissions) {
-        result = await this.context.relayerCallbacks.submitFileAdditionWithPermissions(
+        const result = await this.context.relayerCallbacks.submitFileAdditionWithPermissions(
           uploadResult.url,
           userAddress,
           encryptedPermissions
         );
+        return {
+          fileId: result.fileId,
+          url: uploadResult.url,
+          size: uploadResult.size,
+          transactionHash: result.transactionHash
+        };
       } else {
-        result = await this.addFileWithPermissions(
+        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
+        };
       }
-      return {
-        fileId: result.fileId,
-        url: uploadResult.url,
-        size: uploadResult.size,
-        transactionHash: result.transactionHash
-      };
     } catch (error) {
       console.error("Failed to upload file with permissions:", error);
       throw new Error(
@@ -1755,6 +1985,7 @@ class DataController {
       }
       let finalBlob = blob;
       if (encrypt) {
+        this.assertWallet();
         const encryptionKey = await generateEncryptionKey(
           this.context.walletClient,
           this.context.platform,
@@ -1776,7 +2007,7 @@ class DataController {
           );
         }
       }
-      const finalFilename = filename || `upload-${Date.now()}.dat`;
+      const finalFilename = filename ?? `upload-${Date.now()}.dat`;
       const uploadResult = await this.context.storageManager.upload(
         finalBlob,
         finalFilename,
@@ -1801,21 +2032,29 @@ 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) {
+  async addPermissionToFile(params) {
+    this.assertWallet();
+    const { fileId, account, publicKey } = params;
     return await this.submitFilePermission(fileId, account, publicKey);
   }
   /**
@@ -1829,7 +2068,7 @@ class DataController {
    * @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).public_key`
+   *   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
@@ -1847,6 +2086,7 @@ class DataController {
    * ```
    */
   async submitFilePermission(fileId, account, publicKey) {
+    this.assertWallet();
     try {
       const userEncryptionKey = await generateEncryptionKey(
         this.context.walletClient,
@@ -1858,24 +2098,29 @@ 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");
+      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: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
+        account: walletAccount,
+        chain: this.context.walletClient.chain ?? null
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash: txHash,
-        from: this.context.walletClient.account?.address
-      };
+        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(
@@ -1892,7 +2137,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");
       }
@@ -1901,7 +2146,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),
@@ -1925,12 +2170,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
@@ -1994,11 +2240,8 @@ class DataController {
    */
   async fetch(url) {
     try {
-      const { fetchWithRelayer } = await import("../utils/download");
-      const response = await fetchWithRelayer(
-        url,
-        this.context.downloadRelayer
-      );
+      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}`
@@ -2063,7 +2306,7 @@ class DataController {
       "https://dweb.link/ipfs/",
       "https://ipfs.io/ipfs/"
     ];
-    const gateways = options?.gateways || this.context.ipfsGateways || defaultGateways;
+    const gateways = options?.gateways ?? this.context.ipfsGateways ?? defaultGateways;
     const { extractIpfsHash } = await import("../utils/ipfs");
     const cid = extractIpfsHash(url);
     if (!cid) {
@@ -2192,7 +2435,7 @@ class DataController {
    * ```
    */
   validateDataAgainstSchema(data, schema) {
-    return validateDataAgainstSchema(data, schema);
+    validateDataAgainstSchema(data, schema);
   }
   /**
    * Fetches and validates a data schema from a URL, then returns the parsed data schema.