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

package/dist/controllers/data.d.ts

@@ -1,95 +1,122 @@
 import type { Address } from "viem";
+import type { TransactionOptions, TransactionResult } from "../types/operations";
 import type { StorageUploadResult } from "../types/storage";
-import type { UserFile, UploadParams, UploadResult, UploadEncryptedFileResult, Refiner, AddRefinerParams, AddRefinerResult, UpdateSchemaIdParams, UpdateSchemaIdResult, TrustedServer, GetUserTrustedServersParams, EncryptedUploadParams, UnencryptedUploadParams } from "../types/index";
-import type { TransactionResult } from "../types/operations";
+import type { UserFile, UploadParams, UploadResult, UploadEncryptedFileResult, Refiner, AddRefinerParams, AddRefinerResult, UpdateSchemaIdParams, UpdateSchemaIdResult, TrustedServer, GetUserTrustedServersParams, EncryptedUploadParams, UnencryptedUploadParams, EncryptFileOptions, EncryptFileResult, DecryptFileOptions, UploadFileWithPermissionsParams, AddFilePermissionParams, DecryptFileWithPermissionOptions } from "../types/index";
 import type { ControllerContext } from "./permissions";
+import { BaseController } from "./base";
+import type { ConsistencyOptions, PaginationOptions } from "../types/options";
 import { type DataSchema } from "../utils/schemaValidation";
 /**
- * Manages encrypted user data files and their blockchain registration on the Vana network.
+ * Manages encrypted user data files and blockchain registration on the Vana network.
  *
  * @remarks
- * This controller handles the complete file lifecycle from encrypted upload to
- * blockchain registration and decryption. It provides methods for querying user files,
- * uploading new encrypted content, managing file schemas, and handling permissions for
- * secure data sharing. All operations respect the user's privacy through client-side
- * encryption before any data leaves the user's device.
+ * The DataController provides comprehensive file lifecycle management from encrypted upload
+ * through blockchain registration to decryption. Client-side encryption ensures data privacy
+ * before transmission. The controller integrates with multiple storage providers (IPFS, Pinata,
+ * Google Drive) and supports both gasless transactions via relayers and direct blockchain interaction.
  *
- * The controller integrates with multiple storage providers (IPFS, Pinata, Google Drive)
- * and supports both gasless transactions via relayers and direct blockchain interaction.
- * File metadata and access permissions are stored on the Vana blockchain while encrypted
- * file content is stored on decentralized storage networks.
+ * **Architecture:**
+ * Files use dual storage: encrypted content on decentralized storage (IPFS/Pinata/Google Drive),
+ * metadata and permissions on blockchain. This design minimizes on-chain data while maintaining
+ * decentralization and access control.
  *
  * **Method Selection:**
- * - `upload()` handles encryption, storage, and blockchain registration automatically
- * - `getUserFiles()` queries existing file metadata from blockchain and subgraph
- * - `decryptFile()` decrypts files for which you have access permissions
- * - `getFileById()` retrieves specific file metadata when you have the file ID
+ * - `upload()` - Complete workflow: encryption, storage, blockchain registration
+ * - `getUserFiles()` - Query file metadata from blockchain/subgraph
+ * - `decryptFile()` - Decrypt files you have permission to access
+ * - `getFileById()` - Retrieve specific file metadata by ID
  *
  * **Storage Requirements:**
- * Methods requiring storage configuration: `upload()`
- * Methods working without storage: `getUserFiles()`, `decryptFile()`, `getFileById()`
+ * - Methods requiring storage: `upload()`, `encryptFile()`
+ * - Methods working without storage: `getUserFiles()`, `decryptFile()`, `getFileById()`
+ *
+ * **Permission Model:**
+ * - File permissions (decryption access) are handled during upload
+ * - Operation permissions (what can be done with data) use `vana.permissions.grant()`
+ *
  * @example
  * ```typescript
- * // Upload an encrypted file with automatic schema validation
+ * // Upload encrypted file with schema validation
  * const result = await vana.data.upload({
- *   content: "My personal data",
- *   filename: "personal-data.json"
+ *   content: { name: "Alice", age: 30 },
+ *   filename: "profile.json",
+ *   schemaId: 1
  * });
+ * console.log(`File uploaded: ID ${result.fileId}, URL ${result.url}`);
  *
- * // Query files owned by a user
+ * // Query user's files
  * const files = await vana.data.getUserFiles({
- *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+ *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
  * });
+ * files.forEach(file => console.log(`File ${file.id}: ${file.url}`));
  *
- * // Decrypt accessible file content
+ * // Decrypt accessible file
  * const decryptedData = await vana.data.decryptFile(files[0]);
+ * console.log("Decrypted content:", decryptedData);
  * ```
+ *
  * @category Data Management
- * @see {@link https://docs.vana.com/developer/data-registry | Vana Data Registry Documentation} for conceptual overview
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/data-registry}
  */
-export declare class DataController {
-    private readonly context;
+export declare class DataController extends BaseController {
     constructor(context: ControllerContext);
     /**
-     * Uploads user data with automatic encryption and blockchain registration.
+     * Uploads data with automatic encryption and blockchain registration.
      *
      * @remarks
-     * This is the primary method for uploading user data to the Vana network. It handles
-     * the complete workflow including content normalization, schema validation, encryption,
-     * storage upload, file permission granting, and blockchain registration.
-     *
-     * The method automatically:
-     * - Normalizes input content to a Blob
-     * - Validates data against schema if provided
-     * - Generates encryption keys and encrypts the data
-     * - Uploads to the configured storage provider
-     * - Grants file decryption permissions to specified accounts
-     * - Registers the file on the blockchain
+     * Primary method for uploading data to Vana. Handles complete workflow:
+     * content normalization, schema validation, encryption, storage upload,
+     * permission granting, and blockchain registration.
+     *
+     * **Automatic Processing:**
+     * - Normalizes content to Blob format
+     * - Validates against schema if provided
+     * - Generates encryption keys
+     * - Uploads to configured storage
+     * - Grants decryption permissions
+     * - Registers on blockchain
      *
      * **TypeScript Overloads:**
-     * This method has three overloads to ensure type safety:
-     * 1. `EncryptedUploadParams` - When `encrypt: true` (default), permissions require publicKey
-     * 2. `UnencryptedUploadParams` - When `encrypt: false`, permissions are optional
-     * 3. `UploadParams` - General signature for runtime determination
-     *
-     * IMPORTANT: The permissions parameter only grants decryption access to the file.
-     * To grant operation permissions (like "llm_inference"), use vana.permissions.grant()
-     * after uploading. This separation ensures clear distinction between:
-     * - File permissions: Who can decrypt and read the encrypted file (handled here)
-     * - Operation permissions: What operations can be performed on the data (handled separately)
-     *
-     * @param params - Upload parameters including content, filename, schema, and permissions
-     * @param params.permissions - Optional array of file permissions for granting decryption access
-     * @param params.schemaId - Optional schema ID for data validation. Get available schemas from `vana.schemas.list()`.
-     * @param params.owner - Optional owner address if uploading on behalf of another user (requires delegation).
-     * @returns Promise resolving to upload results with file ID and transaction hash
-     * @throws {Error} When storage manager is not configured - "Storage manager not configured. Please provide storage providers in VanaConfig."
-     * @throws {Error} When no wallet addresses available - "No addresses available in wallet client"
-     * @throws {Error} When chain ID is not available - "Chain ID not available"
-     * @throws {Error} When relay callback doesn't support required features - "The configured relay callback does not support schemas or permissions"
-     * @throws {Error} When schema fetch fails - "Failed to fetch schema definition: {status}"
-     * @throws {SchemaValidationError} When data doesn't match schema - includes specific validation errors
-     * @throws {Error} General upload failures - "Upload failed: {specific error message}"
+     * - `EncryptedUploadParams`: When `encrypt: true` (default), permissions require `publicKey`
+     * - `UnencryptedUploadParams`: When `encrypt: false`, permissions optional
+     * - `UploadParams`: General signature for runtime determination
+     *
+     * **Permission Separation:**
+     * - File permissions (here): Decryption access only
+     * - Operation permissions: Use `vana.permissions.grant()` separately
+     *
+     * **Owner/Encryption Constraint:**
+     * When encryption is enabled (default), the `owner` parameter must match
+     * the connected wallet address. This ensures only the wallet that performs
+     * encryption can decrypt the file. For delegation scenarios where the owner
+     * differs from the connected wallet, set `encrypt: false`.
+     *
+     * @param params - Upload configuration object
+     * @param params.content - Data to upload (string, object, or Blob)
+     * @param params.filename - Name for the uploaded file
+     * @param params.permissions - Decryption access grants.
+     *   Each requires `account` and `publicKey` for encryption.
+     * @param params.schemaId - Schema for validation.
+     *   Obtain via `vana.schemas.list()`.
+     * @param params.owner - Owner address for blockchain registration.
+     *   Must match connected wallet when encryption is enabled.
+     *   For delegation scenarios, disable encryption with `encrypt: false`.
+     *   Defaults to connected wallet address.
+     * @param params.encrypt - Enable encryption (default: `true`)
+     * @param params.providerName - Storage provider override
+     *
+     * @returns Upload result with file ID, URL, and transaction hash
+     *
+     * @throws {InvalidConfigurationError} When encryption is enabled and owner differs from wallet.
+     *   Set `encrypt: false` for delegation scenarios, or omit `owner` to use connected wallet.
+     * @throws {Error} Storage not configured.
+     *   Configure storage providers in `VanaConfig`.
+     * @throws {Error} No wallet addresses available.
+     *   Ensure wallet is connected.
+     * @throws {SchemaValidationError} Data doesn't match schema.
+     *   Verify data structure matches schema from `vana.schemas.get(schemaId)`.
+     * @throws {Error} Upload failed with specific error message.
+     *
      * @example
      * ```typescript
      * // Basic file upload
@@ -131,15 +158,12 @@ export declare class DataController {
      *   encrypt: false
      * } as const);  // 'as const' ensures TypeScript infers encrypt: false literally
      *
-     * // Upload on behalf of another user (delegation)
+     * // Upload on behalf of another user (delegation without encryption)
      * const result = await vana.data.upload({
      *   content: "User's data",
      *   filename: "delegated.txt",
-     *   owner: "0x5678...", // Different from connected wallet
-     *   permissions: [{
-     *     account: "0x1234...",   // Address that can decrypt
-     *     publicKey: "0x04..."    // Their public key for encryption
-     *   }]
+     *   owner: "0x5678...",  // Different from connected wallet
+     *   encrypt: false        // Required when owner differs from wallet
      * });
      * ```
      */
@@ -147,35 +171,78 @@ export declare class DataController {
     upload(params: UnencryptedUploadParams): Promise<UploadResult>;
     upload(params: UploadParams): Promise<UploadResult>;
     /**
-     * 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);
+     * ```
+     */
+    encryptFile(data: Blob | string | object, options?: EncryptFileOptions): Promise<EncryptFileResult>;
+    /**
+     * 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
@@ -201,44 +268,47 @@ export declare class DataController {
      * fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
      * ```
      */
-    decryptFile(file: UserFile, encryptionSeed?: string): Promise<Blob>;
+    decryptFile(file: UserFile, options?: DecryptFileOptions): Promise<Blob>;
     /**
-     * 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"}`);
      * });
      * ```
      */
     getUserFiles(params: {
         owner: Address;
         subgraphUrl?: string;
-    }): Promise<UserFile[]>;
+    }, options?: ConsistencyOptions & PaginationOptions): Promise<UserFile[]>;
     /**
      * Fetches proof data for multiple files from the subgraph.
      *
@@ -279,6 +349,8 @@ export declare class DataController {
      */
     getDLP(dlpId: number, options?: {
         subgraphUrl?: string;
+        minBlock?: number;
+        waitForSync?: number;
     }): Promise<{
         id: number;
         name: string;
@@ -339,7 +411,7 @@ export declare class DataController {
     getUserPermissions(params: {
         user: Address;
         subgraphUrl?: string;
-    }): Promise<Array<{
+    }, options?: ConsistencyOptions & PaginationOptions): Promise<Array<{
         id: string;
         grant: string;
         nonce: bigint;
@@ -402,7 +474,7 @@ export declare class DataController {
      * });
      * ```
      */
-    getUserTrustedServers(params: GetUserTrustedServersParams): Promise<TrustedServer[]>;
+    getUserTrustedServers(params: GetUserTrustedServersParams, options?: ConsistencyOptions & PaginationOptions): Promise<TrustedServer[]>;
     /**
      * Internal method: Query trusted servers via subgraph
      *
@@ -423,48 +495,56 @@ export declare class DataController {
      */
     private _getUserTrustedServersViaRpc;
     /**
-     * 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);
      * ```
      */
     getTotalFilesCount(): Promise<number>;
     /**
-     * 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.
      */
     getFileById(fileId: number): Promise<UserFile>;
     /**
@@ -490,14 +570,13 @@ export declare class DataController {
      * console.log(`File ${fileId} registered with schema in tx ${transactionHash}`);
      * ```
      */
-    registerFileWithSchema(url: string, schemaId: number): Promise<TransactionResult<"DataRegistry", "addFileWithSchema">>;
+    registerFileWithSchema(url: string, schemaId: number, options?: TransactionOptions): Promise<TransactionResult<"DataRegistry", "addFileWithSchema">>;
     /**
      * Gets the user's address from the wallet client.
      *
      * @returns Promise resolving to the user's wallet address
      * @throws {Error} When no addresses are available in wallet client
      */
-    private getUserAddress;
     /**
      * Adds a file with permissions to the DataRegistry contract.
      *
@@ -517,7 +596,7 @@ export declare class DataController {
     addFileWithPermissions(url: string, ownerAddress: Address, permissions?: Array<{
         account: Address;
         key: string;
-    }>): Promise<TransactionResult<"DataRegistry", "addFileWithPermissions">>;
+    }>, options?: TransactionOptions): Promise<TransactionResult<"DataRegistry", "addFileWithPermissions">>;
     /**
      * Adds a file to the registry with permissions and schema.
      * This combines the functionality of addFileWithPermissions and schema validation.
@@ -560,81 +639,131 @@ export declare class DataController {
     addFileWithPermissionsAndSchema(url: string, ownerAddress: Address, permissions?: Array<{
         account: Address;
         publicKey: string;
-    }>, schemaId?: number): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
+    }>, schemaId?: number, options?: TransactionOptions): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
     /**
-     * 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}`);
+     * ```
      */
-    private _addFileWithPermissionsAndSchemaInternal;
+    addFileWithEncryptedPermissionsAndSchema(url: string, ownerAddress: Address, permissions?: Array<{
+        account: Address;
+        key: string;
+    }>, schemaId?: number, options?: TransactionOptions): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
     /**
-     * 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`);
      * ```
      */
-    addRefiner(params: AddRefinerParams): Promise<AddRefinerResult>;
+    addRefiner(params: AddRefinerParams, options?: TransactionOptions): Promise<AddRefinerResult>;
     /**
-     * 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}`);
      * ```
      */
     getRefiner(refinerId: number): Promise<Refiner>;
     /**
-     * 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, ... });
      * }
      * ```
      */
@@ -676,7 +805,7 @@ export declare class DataController {
      * console.log(`Schema updated in tx ${result.transactionHash}`);
      * ```
      */
-    updateSchemaId(params: UpdateSchemaIdParams): Promise<UpdateSchemaIdResult>;
+    updateSchemaId(params: UpdateSchemaIdParams, options?: TransactionOptions): Promise<UpdateSchemaIdResult>;
     /**
      * Uploads an encrypted file and grants permission to a party with a public key.
      *
@@ -686,16 +815,10 @@ export declare 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
      */
-    uploadFileWithPermissions(data: Blob, permissions: Array<{
-        account: Address;
-        publicKey: string;
-    }>, filename?: string, providerName?: string): Promise<UploadEncryptedFileResult>;
+    uploadFileWithPermissions(params: UploadFileWithPermissionsParams): Promise<UploadEncryptedFileResult>;
     /**
      * Uploads content to storage without registering it on the blockchain.
      * This method only handles the storage upload and returns the file URL.
@@ -719,21 +842,27 @@ export declare 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}`);
      * ```
      */
-    addPermissionToFile(fileId: number, account: Address, publicKey: string): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
+    addPermissionToFile(params: AddFilePermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
     /**
      * Submits a file permission transaction to the blockchain.
      *
@@ -762,7 +891,7 @@ export declare class DataController {
      * console.log(`Permission granted with ID: ${result.permissionId}`);
      * ```
      */
-    submitFilePermission(fileId: number, account: Address, publicKey: string): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
+    submitFilePermission(fileId: number, account: Address, publicKey: string, options?: TransactionOptions): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
     /**
      * Gets the encrypted key for a specific account's permission to access a file.
      *
@@ -781,10 +910,11 @@ export declare 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
      */
-    decryptFileWithPermission(file: UserFile, privateKey: string, account?: Address): Promise<Blob>;
+    decryptFileWithPermission(file: UserFile, privateKey: string, options?: DecryptFileWithPermissionOptions): Promise<Blob>;
     /**
      * Simple network-agnostic fetch utility for retrieving file content.
      *
@@ -929,4 +1059,9 @@ export declare class DataController {
      * ```
      */
     fetchAndValidateSchema(url: string): Promise<DataSchema>;
+    /**
+     * Polls for confirmation of a relayer operation.
+     * @internal
+     */
+    private pollRelayerForConfirmation;
 }