@opendatalabs/vana-sdk 0.1.0-alpha.2b6935d → 0.1.0-alpha.2e77fcc

package/dist/controllers/base.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/base.ts"],"sourcesContent":["/**\n * Base controller class providing common functionality for all controllers.\n *\n * @remarks\n * This abstract class establishes the foundation for all Vana SDK controllers,\n * providing shared utilities like wallet validation and context management.\n * All controllers should extend this base class to ensure consistency and\n * shared behavior across the SDK.\n *\n * The class follows the Single Responsibility Principle by handling only\n * the core controller concerns while leaving specific functionality to\n * implementing classes.\n *\n * @category Controllers\n */\n\nimport type { WalletClient } from \"viem\";\nimport type { ControllerContext } from \"../types/controller-context\";\nimport { ReadOnlyError } from \"../errors\";\n\n/**\n * Abstract base controller that all Vana SDK controllers extend.\n *\n * @remarks\n * Provides common functionality and patterns used across all controllers,\n * including wallet validation and context management. This ensures\n * consistency and reduces code duplication throughout the SDK.\n *\n * Key features:\n * - Wallet client validation with TypeScript assertion signatures\n * - Consistent error handling for read-only scenarios\n * - Shared context management patterns\n * - Type-safe wallet operations\n *\n * @example\n * ```typescript\n * class MyController extends BaseController {\n *   async performWalletOperation() {\n *     this.assertWallet(); // Ensures wallet is available\n *     // Now this.context.walletClient is guaranteed to be available\n *     const address = await this.context.walletClient.getAddresses();\n *     return address[0];\n *   }\n * }\n * ```\n */\nexport abstract class BaseController {\n  /**\n   * Creates a new controller instance with the provided context.\n   *\n   * @param context - The controller context containing clients and configuration\n   */\n  constructor(protected readonly context: ControllerContext) {}\n\n  /**\n   * Asserts that a wallet client with an account is available for operations requiring signing.\n   *\n   * @remarks\n   * This method uses TypeScript assertion signatures to narrow the type of\n   * `this.context` to guarantee that `walletClient` with an account is available\n   * after the call succeeds. This provides compile-time safety for wallet operations\n   * while enabling clear error messages for read-only scenarios.\n   *\n   * The assertion signature ensures that after calling this method,\n   * TypeScript knows that `this.context.walletClient` is definitely available\n   * with a configured account.\n   *\n   * @throws {ReadOnlyError} When no wallet client is configured\n   * @throws {Error} When wallet client exists but no account is configured\n   *\n   * @example\n   * ```typescript\n   * async performWalletOperation() {\n   *   this.assertWallet(); // Type assertion + runtime check\n   *\n   *   // TypeScript now knows walletClient and account are available\n   *   const account = this.context.walletClient.account;\n   *   const address = typeof account === 'string' ? account : account.address;\n   * }\n   * ```\n   */\n  protected assertWallet(): asserts this is {\n    context: ControllerContext & { walletClient: WalletClient };\n  } {\n    if (!this.context.walletClient) {\n      // Get the calling method name from the stack trace for better error messages\n      const stack = new Error().stack;\n      const callingMethod =\n        stack?.split(\"\\n\")[2]?.match(/at \\w+\\.(\\w+)/)?.[1] ?? \"this operation\";\n\n      throw new ReadOnlyError(\n        callingMethod,\n        \"Initialize the SDK with a walletClient to perform this operation\",\n      );\n    }\n\n    if (!this.context.walletClient.account) {\n      // Get the calling method name from the stack trace for better error messages\n      const stack = new Error().stack;\n      const callingMethod =\n        stack?.split(\"\\n\")[2]?.match(/at \\w+\\.(\\w+)/)?.[1] ?? \"this operation\";\n\n      throw new Error(\n        `No wallet account connected. Cannot perform ${callingMethod} without an account.`,\n      );\n    }\n  }\n}\n"],"mappings":"AAkBA,SAAS,qBAAqB;AA4BvB,MAAe,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMnC,YAA+B,SAA4B;AAA5B;AAAA,EAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA6BlD,eAER;AACA,QAAI,CAAC,KAAK,QAAQ,cAAc;AAE9B,YAAM,QAAQ,IAAI,MAAM,EAAE;AAC1B,YAAM,gBACJ,OAAO,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,eAAe,IAAI,CAAC,KAAK;AAExD,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,QAAI,CAAC,KAAK,QAAQ,aAAa,SAAS;AAEtC,YAAM,QAAQ,IAAI,MAAM,EAAE;AAC1B,YAAM,gBACJ,OAAO,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,eAAe,IAAI,CAAC,KAAK;AAExD,YAAM,IAAI;AAAA,QACR,+CAA+C,aAAa;AAAA,MAC9D;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/controllers/base.ts"],"sourcesContent":["/**\n * Base controller class providing common functionality for all controllers.\n *\n * @remarks\n * This abstract class establishes the foundation for all Vana SDK controllers,\n * providing shared utilities like wallet validation and context management.\n * All controllers should extend this base class to ensure consistency and\n * shared behavior across the SDK.\n *\n * The class follows the Single Responsibility Principle by handling only\n * the core controller concerns while leaving specific functionality to\n * implementing classes.\n *\n * @category Controllers\n */\n\nimport type { WalletClient } from \"viem\";\nimport type { ControllerContext } from \"../types/controller-context\";\nimport type { TransactionOptions } from \"../types/operations\";\nimport { ReadOnlyError } from \"../errors\";\n\n/**\n * Abstract base controller that all Vana SDK controllers extend.\n *\n * @remarks\n * Provides common functionality and patterns used across all controllers,\n * including wallet validation and context management. This ensures\n * consistency and reduces code duplication throughout the SDK.\n *\n * Key features:\n * - Wallet client validation with TypeScript assertion signatures\n * - Consistent error handling for read-only scenarios\n * - Shared context management patterns\n * - Type-safe wallet operations\n *\n * @example\n * ```typescript\n * class MyController extends BaseController {\n *   async performWalletOperation() {\n *     this.assertWallet(); // Ensures wallet is available\n *     // Now this.context.walletClient is guaranteed to be available\n *     const address = await this.context.walletClient.getAddresses();\n *     return address[0];\n *   }\n * }\n * ```\n */\nexport abstract class BaseController {\n  /**\n   * Creates a new controller instance with the provided context.\n   *\n   * @param context - The controller context containing clients and configuration\n   */\n  constructor(protected readonly context: ControllerContext) {}\n\n  /**\n   * Asserts that a wallet client with an account is available for operations requiring signing.\n   *\n   * @remarks\n   * This method uses TypeScript assertion signatures to narrow the type of\n   * `this.context` to guarantee that `walletClient` with an account is available\n   * after the call succeeds. This provides compile-time safety for wallet operations\n   * while enabling clear error messages for read-only scenarios.\n   *\n   * The assertion signature ensures that after calling this method,\n   * TypeScript knows that `this.context.walletClient` is definitely available\n   * with a configured account.\n   *\n   * @throws {ReadOnlyError} When no wallet client is configured\n   * @throws {Error} When wallet client exists but no account is configured\n   *\n   * @example\n   * ```typescript\n   * async performWalletOperation() {\n   *   this.assertWallet(); // Type assertion + runtime check\n   *\n   *   // TypeScript now knows walletClient and account are available\n   *   const account = this.context.walletClient.account;\n   *   const address = typeof account === 'string' ? account : account.address;\n   * }\n   * ```\n   */\n  protected assertWallet(): asserts this is {\n    context: ControllerContext & { walletClient: WalletClient };\n  } {\n    if (!this.context.walletClient) {\n      // Get the calling method name from the stack trace for better error messages\n      const stack = new Error().stack;\n      const callingMethod =\n        stack?.split(\"\\n\")[2]?.match(/at \\w+\\.(\\w+)/)?.[1] ?? \"this operation\";\n\n      throw new ReadOnlyError(\n        callingMethod,\n        \"Initialize the SDK with a walletClient to perform this operation\",\n      );\n    }\n\n    if (!this.context.walletClient.account) {\n      // Get the calling method name from the stack trace for better error messages\n      const stack = new Error().stack;\n      const callingMethod =\n        stack?.split(\"\\n\")[2]?.match(/at \\w+\\.(\\w+)/)?.[1] ?? \"this operation\";\n\n      throw new Error(\n        `No wallet account connected. Cannot perform ${callingMethod} without an account.`,\n      );\n    }\n  }\n\n  /**\n   * Helper to safely spread transaction options for viem compatibility.\n   * Handles EIP-1559 vs legacy gas pricing correctly.\n   *\n   * @param options - Transaction options to spread\n   * @returns Properly formatted options for viem\n   * @internal\n   */\n  protected spreadTransactionOptions(options?: TransactionOptions) {\n    if (!options) return {};\n\n    const baseOptions: any = {\n      ...(options.nonce !== undefined && { nonce: options.nonce }),\n      ...(options.gas !== undefined && { gas: options.gas }),\n    };\n\n    // EIP-1559 and legacy gasPrice are mutually exclusive in viem\n    // If EIP-1559 params are provided, use them and exclude gasPrice\n    if (\n      options.maxFeePerGas !== undefined ||\n      options.maxPriorityFeePerGas !== undefined\n    ) {\n      return {\n        ...baseOptions,\n        ...(options.maxFeePerGas !== undefined && {\n          maxFeePerGas: options.maxFeePerGas,\n        }),\n        ...(options.maxPriorityFeePerGas !== undefined && {\n          maxPriorityFeePerGas: options.maxPriorityFeePerGas,\n        }),\n      };\n    }\n\n    // Otherwise, use legacy gasPrice if provided\n    if (options.gasPrice !== undefined) {\n      return {\n        ...baseOptions,\n        gasPrice: options.gasPrice,\n      };\n    }\n\n    return baseOptions;\n  }\n}\n"],"mappings":"AAmBA,SAAS,qBAAqB;AA4BvB,MAAe,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMnC,YAA+B,SAA4B;AAA5B;AAAA,EAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA6BlD,eAER;AACA,QAAI,CAAC,KAAK,QAAQ,cAAc;AAE9B,YAAM,QAAQ,IAAI,MAAM,EAAE;AAC1B,YAAM,gBACJ,OAAO,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,eAAe,IAAI,CAAC,KAAK;AAExD,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,QAAI,CAAC,KAAK,QAAQ,aAAa,SAAS;AAEtC,YAAM,QAAQ,IAAI,MAAM,EAAE;AAC1B,YAAM,gBACJ,OAAO,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,eAAe,IAAI,CAAC,KAAK;AAExD,YAAM,IAAI;AAAA,QACR,+CAA+C,aAAa;AAAA,MAC9D;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUU,yBAAyB,SAA8B;AAC/D,QAAI,CAAC,QAAS,QAAO,CAAC;AAEtB,UAAM,cAAmB;AAAA,MACvB,GAAI,QAAQ,UAAU,UAAa,EAAE,OAAO,QAAQ,MAAM;AAAA,MAC1D,GAAI,QAAQ,QAAQ,UAAa,EAAE,KAAK,QAAQ,IAAI;AAAA,IACtD;AAIA,QACE,QAAQ,iBAAiB,UACzB,QAAQ,yBAAyB,QACjC;AACA,aAAO;AAAA,QACL,GAAG;AAAA,QACH,GAAI,QAAQ,iBAAiB,UAAa;AAAA,UACxC,cAAc,QAAQ;AAAA,QACxB;AAAA,QACA,GAAI,QAAQ,yBAAyB,UAAa;AAAA,UAChD,sBAAsB,QAAQ;AAAA,QAChC;AAAA,MACF;AAAA,IACF;AAGA,QAAI,QAAQ,aAAa,QAAW;AAClC,aAAO;AAAA,QACL,GAAG;AAAA,QACH,UAAU,QAAQ;AAAA,MACpB;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/controllers/data.cjs

@@ -258,35 +258,33 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * Decrypts a file owned by the user using their wallet signature.
+   * Decrypts a file using wallet-derived decryption key.
    *
    * @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.
+   * 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.
    *
-   * 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
    * @example
    * ```typescript
    * // Basic file decryption
@@ -402,35 +400,38 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * 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"}`);
    * });
    * ```
    */
@@ -1230,18 +1231,26 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * 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() {
@@ -1268,32 +1277,32 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * 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 {
@@ -1364,7 +1373,7 @@ class DataController extends import_base.BaseController {
    * 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.publicClient.chain?.id;
@@ -1382,7 +1391,8 @@ class DataController extends import_base.BaseController {
         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({
@@ -1420,7 +1430,7 @@ class DataController extends import_base.BaseController {
    * 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.publicClient.chain?.id;
@@ -1438,7 +1448,8 @@ class DataController extends import_base.BaseController {
         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({
@@ -1493,7 +1504,7 @@ class DataController extends import_base.BaseController {
    * 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 = [];
@@ -1527,7 +1538,8 @@ class DataController extends import_base.BaseController {
         url,
         ownerAddress,
         encryptedPermissions,
-        schemaId
+        schemaId,
+        options
       );
     } catch (error) {
       console.error("Failed to add file with permissions and schema:", error);
@@ -1574,7 +1586,7 @@ class DataController extends import_base.BaseController {
    * console.log(`File registered in tx ${result.hash}`);
    * ```
    */
-  async addFileWithEncryptedPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0) {
+  async addFileWithEncryptedPermissionsAndSchema(url, ownerAddress, permissions = [], schemaId = 0, options) {
     try {
       const chainId = this.context.publicClient.chain?.id;
       if (!chainId) {
@@ -1591,7 +1603,8 @@ class DataController extends import_base.BaseController {
         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({
@@ -1608,34 +1621,38 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * 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.publicClient.chain?.id;
@@ -1661,7 +1678,8 @@ class DataController extends import_base.BaseController {
           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({
@@ -1690,26 +1708,29 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * 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) {
@@ -1750,21 +1771,27 @@ class DataController extends import_base.BaseController {
     }
   }
   /**
-   * 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, ... });
    * }
    * ```
    */
@@ -1852,7 +1879,7 @@ class DataController extends import_base.BaseController {
    * console.log(`Schema updated in tx ${result.transactionHash}`);
    * ```
    */
-  async updateSchemaId(params) {
+  async updateSchemaId(params, options) {
     this.assertWallet();
     try {
       const chainId = this.context.publicClient.chain?.id;
@@ -1872,7 +1899,8 @@ class DataController extends import_base.BaseController {
         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 {
@@ -2078,10 +2106,10 @@ class DataController extends import_base.BaseController {
    * console.log(`Transaction: ${result.transactionHash}`);
    * ```
    */
-  async addPermissionToFile(params) {
+  async addPermissionToFile(params, options) {
     this.assertWallet();
     const { fileId, account, publicKey } = params;
-    return await this.submitFilePermission(fileId, account, publicKey);
+    return await this.submitFilePermission(fileId, account, publicKey, options);
   }
   /**
    * Submits a file permission transaction to the blockchain.
@@ -2111,7 +2139,7 @@ class DataController extends import_base.BaseController {
    * 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 (0, import_encryption.generateEncryptionKey)(
@@ -2138,7 +2166,8 @@ class DataController extends import_base.BaseController {
         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({