@opendatalabs/vana-sdk 0.1.0-alpha.f9cc6ed → 0.1.0-alpha.fd33fc9

package/dist/controllers/data.d.ts

@@ -0,0 +1,1014 @@
+import type { Address } from "viem";
+import type { StorageUploadResult } from "../types/storage";
+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 { TransactionResult } from "../types/operations";
+import type { ControllerContext } from "./permissions";
+import { BaseController } from "./base";
+import { type DataSchema } from "../utils/schemaValidation";
+/**
+ * Manages encrypted user data files and their 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 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.
+ *
+ * **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
+ *
+ * **Storage Requirements:**
+ * Methods requiring storage configuration: `upload()`
+ * Methods working without storage: `getUserFiles()`, `decryptFile()`, `getFileById()`
+ * @example
+ * ```typescript
+ * // Upload an encrypted file with automatic schema validation
+ * const result = await vana.data.upload({
+ *   content: "My personal data",
+ *   filename: "personal-data.json"
+ * });
+ *
+ * // Query files owned by a user
+ * const files = await vana.data.getUserFiles({
+ *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+ * });
+ *
+ * // Decrypt accessible file content
+ * const decryptedData = await vana.data.decryptFile(files[0]);
+ * ```
+ * @category Data Management
+ * @see {@link https://docs.vana.com/developer/data-registry | Vana Data Registry Documentation} for conceptual overview
+ */
+export declare class DataController extends BaseController {
+    constructor(context: ControllerContext);
+    /**
+     * Uploads user 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
+     *
+     * **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}"
+     * @example
+     * ```typescript
+     * // Basic file upload
+     * const result = await vana.data.upload({
+     *   content: "My personal data",
+     *   filename: "diary.txt"
+     * });
+     *
+     * // Upload with schema validation
+     * const result = await vana.data.upload({
+     *   content: { name: "John", age: 30 },
+     *   filename: "profile.json",
+     *   schemaId: 1
+     * });
+     *
+     * // Upload with file permissions (for decryption access)
+     * const result = await vana.data.upload({
+     *   content: "Data for AI analysis",
+     *   filename: "analysis.txt",
+     *   permissions: [{
+     *     account: "0x1234...", // Server address that can decrypt
+     *     publicKey: "0x04..."  // Server's public key for encryption
+     *   }]
+     * });
+     *
+     * // After upload, grant operation permissions separately:
+     * // await vana.permissions.grant({
+     * //   grantee: "0x1234...",
+     * //   fileIds: [result.fileId],
+     * //   operation: "llm_inference",
+     * //   parameters: { model: "gpt-4" }
+     * // });
+     *
+     * // Upload without encryption (public data)
+     * // Note: Cast to UnencryptedUploadParams for TypeScript
+     * const result = await vana.data.upload({
+     *   content: "Public data",
+     *   filename: "public.txt",
+     *   encrypt: false
+     * } as const);  // 'as const' ensures TypeScript infers encrypt: false literally
+     *
+     * // Upload on behalf of another user (delegation)
+     * 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
+     *   }]
+     * });
+     * ```
+     */
+    upload(params: EncryptedUploadParams): Promise<UploadResult>;
+    upload(params: UnencryptedUploadParams): Promise<UploadResult>;
+    upload(params: UploadParams): Promise<UploadResult>;
+    /**
+     * 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);
+     * ```
+     */
+    encryptFile(data: Blob | string | object, options?: EncryptFileOptions): Promise<EncryptFileResult>;
+    /**
+     * Decrypts a file owned by the user using their wallet signature.
+     *
+     * @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.
+     *
+     * 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
+     * const files = await vana.data.getUserFiles({ owner: userAddress });
+     * const decryptedBlob = await vana.data.decryptFile(files[0]);
+     *
+     * // Convert to text
+     * const text = await decryptedBlob.text();
+     * console.log('Decrypted content:', text);
+     *
+     * // Convert to JSON
+     * const json = JSON.parse(await decryptedBlob.text());
+     * console.log('Decrypted data:', json);
+     *
+     * // With custom encryption seed
+     * const decryptedBlob = await vana.data.decryptFile(
+     *   files[0],
+     *   "My custom encryption seed"
+     * );
+     *
+     * // Save to file (in Node.js)
+     * const buffer = await decryptedBlob.arrayBuffer();
+     * fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
+     * ```
+     */
+    decryptFile(file: UserFile, options?: DecryptFileOptions): Promise<Blob>;
+    /**
+     * Retrieves all data 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}"
+     * @example
+     * ```typescript
+     * // Query files for a specific user
+     * const files = await vana.data.getUserFiles({
+     *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     * });
+     *
+     * files.forEach(file => {
+     *   console.log(`File ${file.id}: ${file.url} (Schema: ${file.schemaId})`);
+     * });
+     * ```
+     */
+    getUserFiles(params: {
+        owner: Address;
+        subgraphUrl?: string;
+    }): Promise<UserFile[]>;
+    /**
+     * Fetches proof data for multiple files from the subgraph.
+     *
+     * @private
+     * @param fileIds - Array of file IDs to fetch proofs for
+     * @param subgraphUrl - The subgraph endpoint URL
+     * @returns Map of file IDs to their associated DLP IDs
+     */
+    private _fetchProofsFromSubgraph;
+    /**
+     * Fetches proof data for multiple files from the blockchain.
+     * Falls back to this when subgraph is unavailable.
+     *
+     * @private
+     * @param fileIds - Array of file IDs to fetch proofs for
+     * @returns Map of file IDs to their associated DLP IDs
+     */
+    private _fetchProofsFromChain;
+    /**
+     * Retrieves information about a specific Data Liquidity Pool (DLP).
+     *
+     * @remarks
+     * DLPs are entities that process and verify data files in the Vana network.
+     * This method fetches DLP metadata including name, status, and performance rating.
+     * Uses subgraph first for efficiency, falls back to chain if unavailable.
+     *
+     * @param dlpId - The unique identifier of the DLP
+     * @param options - Optional parameters
+     * @param options.subgraphUrl - Custom subgraph URL to override default
+     * @returns Promise resolving to DLP information
+     * @throws {Error} When DLP cannot be found - "DLP not found: {dlpId}"
+     * @throws {Error} When query fails - "Failed to fetch DLP: {error}"
+     * @example
+     * ```typescript
+     * const dlp = await vana.data.getDLP(26);
+     * console.log(`DLP ${dlp.name}: ${dlp.status}`);
+     * ```
+     */
+    getDLP(dlpId: number, options?: {
+        subgraphUrl?: string;
+    }): Promise<{
+        id: number;
+        name: string;
+        metadata?: string;
+        status?: number;
+        address?: Address;
+        owner?: Address;
+    }>;
+    /**
+     * Lists all Data Liquidity Pools (DLPs) with optional pagination.
+     *
+     * @remarks
+     * Fetches a paginated list of all DLPs registered in the network.
+     * Uses subgraph for efficient querying with fallback to chain multicall.
+     *
+     * @param options - Optional parameters for pagination and filtering
+     * @param options.limit - Maximum number of DLPs to return (default: 100)
+     * @param options.offset - Number of DLPs to skip (default: 0)
+     * @param options.subgraphUrl - Custom subgraph URL to override default
+     * @returns Promise resolving to array of DLP information
+     * @throws {Error} When query fails - "Failed to list DLPs: {error}"
+     * @example
+     * ```typescript
+     * // Get first 10 DLPs
+     * const dlps = await vana.data.listDLPs({ limit: 10 });
+     * dlps.forEach(dlp => console.log(`${dlp.id}: ${dlp.name}`));
+     *
+     * // Get next page
+     * const nextPage = await vana.data.listDLPs({ limit: 10, offset: 10 });
+     * ```
+     */
+    listDLPs(options?: {
+        limit?: number;
+        offset?: number;
+        subgraphUrl?: string;
+    }): Promise<Array<{
+        id: number;
+        name: string;
+        metadata?: string;
+        status?: number;
+        address?: Address;
+        owner?: Address;
+    }>>;
+    /**
+     * Retrieves a list of permissions granted by a user.
+     *
+     * This method supports automatic fallback between subgraph and RPC modes:
+     * - If subgraph URL is available, tries subgraph query first
+     * - Falls back to direct contract queries via RPC if subgraph fails
+     * - RPC mode uses gasAwareMulticall for efficient batch queries
+     *
+     * @param params - Object containing the user address and optional subgraph URL
+     * @param params.user - The wallet address of the user to query permissions for
+     * @param params.subgraphUrl - Optional subgraph URL to override the default
+     * @returns Promise resolving to an array of permission objects
+     * @throws Error if both subgraph and RPC queries fail
+     */
+    getUserPermissions(params: {
+        user: Address;
+        subgraphUrl?: string;
+    }): Promise<Array<{
+        id: string;
+        grant: string;
+        nonce: bigint;
+        signature: string;
+        addedAtBlock: bigint;
+        addedAtTimestamp: bigint;
+        transactionHash: Address;
+        user: Address;
+    }>>;
+    /**
+     * Internal method: Query user permissions via subgraph
+     *
+     * @param params - Query parameters object
+     * @param params.user - The user address to query permissions for
+     * @param params.subgraphUrl - The subgraph URL endpoint to query
+     * @returns Promise resolving to an array of permission objects
+     */
+    private _getUserPermissionsViaSubgraph;
+    /**
+     * Internal method: Query user permissions via direct RPC
+     *
+     * @param params - Query parameters object
+     * @param params.user - The user address to query permissions for
+     * @returns Promise resolving to an array of permission objects
+     */
+    private _getUserPermissionsViaRpc;
+    /**
+     * Retrieves a list of trusted servers for a user.
+     *
+     * This method supports automatic fallback between subgraph and RPC modes:
+     * - If subgraph URL is available, tries subgraph query first for fast results
+     * - Falls back to direct contract queries via RPC if subgraph fails
+     * - RPC mode uses gasAwareMulticall for efficient batch queries
+     *
+     * @param params - Query parameters including user address and optional pagination
+     * @param params.user - The wallet address of the user to query trusted servers for
+     * @param params.subgraphUrl - Optional subgraph URL to override the default
+     * @param params.limit - Maximum number of results to return (default: 50)
+     * @param params.offset - Number of results to skip for pagination (default: 0)
+     * @returns Promise resolving to an array of trusted server objects
+     * @throws Error if both subgraph and RPC queries fail
+     * @example
+     * ```typescript
+     * // Basic usage with automatic fallback
+     * const servers = await vana.data.getUserTrustedServers({
+     *   user: '0x...'
+     * });
+     *
+     * // With pagination
+     * const servers = await vana.data.getUserTrustedServers({
+     *   user: '0x...',
+     *   limit: 10,
+     *   offset: 20
+     * });
+     *
+     * // With custom subgraph URL
+     * const servers = await vana.data.getUserTrustedServers({
+     *   user: '0x...',
+     *   subgraphUrl: 'https://custom-subgraph.com/graphql'
+     * });
+     * ```
+     */
+    getUserTrustedServers(params: GetUserTrustedServersParams): Promise<TrustedServer[]>;
+    /**
+     * Internal method: Query trusted servers via subgraph
+     *
+     * @param params - Query parameters object
+     * @param params.user - The user address to query trusted servers for
+     * @param params.subgraphUrl - The subgraph URL endpoint to query
+     * @returns Promise resolving to an array of trusted server objects
+     */
+    private _getUserTrustedServersViaSubgraph;
+    /**
+     * Internal method: Query trusted servers via direct RPC
+     *
+     * @param params - Query parameters object
+     * @param params.user - The user address to query trusted servers for
+     * @param params.limit - Maximum number of results to return
+     * @param params.offset - Number of results to skip for pagination
+     * @returns Promise resolving to pagination result with servers, total count, and hasMore flag
+     */
+    private _getUserTrustedServersViaRpc;
+    /**
+     * Gets the total number of files in the registry from the contract.
+     *
+     * @returns Promise resolving to the total file count
+     * @example
+     * ```typescript
+     * const totalFiles = await vana.data.getTotalFilesCount();
+     * console.log(`Total files in registry: ${totalFiles}`);
+     *
+     * // Use for pagination calculations
+     * const filesPerPage = 20;
+     * const totalPages = Math.ceil(totalFiles / filesPerPage);
+     * console.log(`Total pages: ${totalPages}`);
+     * ```
+     */
+    getTotalFilesCount(): Promise<number>;
+    /**
+     * Retrieves details for a specific file by its ID.
+     *
+     * @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);
+     * }
+     * ```
+     *
+     * 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>;
+    /**
+     * Registers a file URL directly on the blockchain with a schema ID.
+     *
+     * @remarks
+     * This method registers an existing file URL on the DataRegistry contract
+     * with a schema ID, without uploading any data. Useful when you have already
+     * uploaded content to storage and just need to register it on-chain.
+     *
+     * @param url - The URL of the file to register (IPFS or HTTP/HTTPS)
+     * @param schemaId - The schema ID to associate with the file
+     * @returns Promise resolving to the file ID and transaction hash
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When wallet address is unavailable - "No addresses available"
+     * @throws {Error} When transaction fails - "Failed to register file with schema"
+     * @example
+     * ```typescript
+     * const { fileId, transactionHash } = await vana.data.registerFileWithSchema(
+     *   "ipfs://QmXxx...",
+     *   1
+     * );
+     * console.log(`File ${fileId} registered with schema in tx ${transactionHash}`);
+     * ```
+     */
+    registerFileWithSchema(url: string, schemaId: number): 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
+     */
+    /**
+     * Adds a file with permissions to the DataRegistry contract.
+     *
+     * @param url - The file URL to register
+     * @param ownerAddress - The address of the file owner
+     * @param permissions - Array of permissions to set for the file
+     * @returns Promise resolving to file ID and transaction hash
+     * @throws {Error} When chain ID is not available
+     * @throws {ContractError} When contract execution fails
+     * @throws {Error} When transaction receipt is not available
+     * @throws {Error} When FileAdded event cannot be parsed
+     *
+     * This method handles the core logic of registering a file
+     * with specific permissions on the DataRegistry contract. It can be used
+     * by both direct transactions and relayer services.
+     */
+    addFileWithPermissions(url: string, ownerAddress: Address, permissions?: Array<{
+        account: Address;
+        key: string;
+    }>): Promise<TransactionResult<"DataRegistry", "addFileWithPermissions">>;
+    /**
+     * Adds a file to the registry with permissions and schema.
+     * This combines the functionality of addFileWithPermissions and schema validation.
+     *
+     * @remarks
+     * This method automatically encrypts permissions when a publicKey is provided.
+     * It generates the user's encryption key and encrypts it with each recipient's
+     * public key before registering on the blockchain.
+     *
+     * @param url - The URL of the file to register
+     * @param ownerAddress - The address of the file owner
+     * @param permissions - Array of permissions to grant, each with account and publicKey properties
+     * @param schemaId - The schema ID to associate with the file (0 for no schema)
+     * @returns Promise resolving to TransactionResult with fileId and transactionHash
+     * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+     * @throws {Error} "Failed to generate encryption key" - When encryption key generation fails
+     * @throws {Error} "Permission for {account} must include 'publicKey'" - When publicKey is missing
+     * @throws {Error} "Failed to add file with permissions and schema: {error}" - When transaction fails
+     * @example
+     * ```typescript
+     * // Get server's public key
+     * const serverIdentity = await vana.server.getIdentity({
+     *   userAddress: "0x..."
+     * });
+     *
+     * // Add file with permissions and schema
+     * const result = await vana.data.addFileWithPermissionsAndSchema(
+     *   "ipfs://QmXxx...",
+     *   ownerAddress,
+     *   [{
+     *     account: serverIdentity.address,
+     *     publicKey: serverIdentity.publicKey
+     *   }],
+     *   schemaId
+     * );
+     *
+     * console.log(`File ${result.fileId} registered in tx ${result.hash}`);
+     * ```
+     */
+    addFileWithPermissionsAndSchema(url: string, ownerAddress: Address, permissions?: Array<{
+        account: Address;
+        publicKey: string;
+    }>, schemaId?: number): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
+    /**
+     * 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}`);
+     * ```
+     */
+    addFileWithEncryptedPermissionsAndSchema(url: string, ownerAddress: Address, permissions?: Array<{
+        account: Address;
+        key: string;
+    }>, schemaId?: number): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
+    /**
+     * Adds a new refiner to the DataRefinerRegistry.
+     *
+     * @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}"
+     * @example
+     * ```typescript
+     * const result = await vana.data.addRefiner({
+     *   dlpId: 1,
+     *   name: "Social Media Sentiment Analyzer",
+     *   schemaId: 42,
+     *   refinementInstructionUrl: "ipfs://QmXxx..."
+     * });
+     * console.log(`Created refiner ${result.refinerId} in tx ${result.transactionHash}`);
+     * ```
+     */
+    addRefiner(params: AddRefinerParams): Promise<AddRefinerResult>;
+    /**
+     * Retrieves a refiner by its ID.
+     *
+     * @remarks
+     * Queries the DataRefinerRegistry contract to get complete information about
+     * a specific refiner including its DLP association, schema, and instructions.
+     *
+     * @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
+     * });
+     * ```
+     */
+    getRefiner(refinerId: number): Promise<Refiner>;
+    /**
+     * Validates if a schema ID exists in the registry.
+     *
+     * @remarks
+     * Checks the DataRefinerRegistry contract to determine if a given schema ID
+     * has been registered and is available for use.
+     *
+     * @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');
+     * }
+     * ```
+     */
+    isValidSchemaId(schemaId: number): Promise<boolean>;
+    /**
+     * Gets the total number of refiners in the registry.
+     *
+     * @remarks
+     * Queries the DataRefinerRegistry contract to get the total count of all
+     * registered refiners across all DLPs.
+     *
+     * @returns Promise resolving to the total refiner count
+     * @example
+     * ```typescript
+     * const count = await vana.data.getRefinersCount();
+     * console.log(`Total refiners registered: ${count}`);
+     * ```
+     */
+    getRefinersCount(): Promise<number>;
+    /**
+     * Updates the schema ID for an existing refiner.
+     *
+     * @remarks
+     * Allows the owner of a refiner to update its associated schema ID.
+     * This is useful when refiner output format needs to change.
+     *
+     * @param params - Update parameters
+     * @param params.refinerId - The refiner ID to update
+     * @param params.newSchemaId - The new schema ID to set
+     * @returns Promise resolving to the transaction hash
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When transaction fails - "Failed to update schema ID: {error}"
+     * @example
+     * ```typescript
+     * const result = await vana.data.updateSchemaId({
+     *   refinerId: 1,
+     *   newSchemaId: 55
+     * });
+     * console.log(`Schema updated in tx ${result.transactionHash}`);
+     * ```
+     */
+    updateSchemaId(params: UpdateSchemaIdParams): Promise<UpdateSchemaIdResult>;
+    /**
+     * Uploads an encrypted file and grants permission to a party with a public key.
+     *
+     * This method handles the complete workflow:
+     * 1. Encrypts the file with the user's encryption key
+     * 2. Uploads the encrypted file to storage
+     * 3. Encrypts the user's encryption key with the provided public key
+     * 4. Registers the file with permissions
+     *
+     * @param params - Upload parameters including data, permissions, and options
+     * @returns Promise resolving to upload result with file ID and storage URL
+     */
+    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.
+     *
+     * @param content - The content to upload (string, Blob, Buffer, or object - objects will be JSON stringified)
+     * @param filename - Optional filename for the uploaded file (defaults to timestamp-based name)
+     * @param encrypt  - Optional flag to encrypt the content before upload
+     * @param providerName - Optional specific storage provider to use
+     * @returns Promise resolving to the storage upload result with url, size, and contentType
+     */
+    uploadToStorage(content: string | Blob | Buffer | object, filename?: string, encrypt?: boolean, providerName?: string): Promise<StorageUploadResult>;
+    /**
+     * Adds a permission for a party to access an existing file.
+     *
+     * This method handles the complete workflow:
+     * 1. Gets the user's encryption key
+     * 2. Encrypts the user's encryption key with the provided public key
+     * 3. Adds the permission to the file
+     * 4. Returns the permission data from the blockchain event
+     *
+     * For advanced users who need more control over transaction timing,
+     * use `submitFilePermission()` instead.
+     *
+     * @param params - Parameters for adding file permission
+     * @param params.fileId - The ID of the file to grant permission for
+     * @param params.account - The recipient's wallet address that will access the file
+     * @param params.publicKey - The recipient's public key for encryption.
+     *   Obtain via `vana.server.getIdentity(account).publicKey`
+     * @returns Promise resolving to permission data from PermissionGranted event
+     * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
+     * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+     * @throws {Error} "Failed to add permission to file: {error}" - When transaction fails or user doesn't own file
+     * @example
+     * ```typescript
+     * const result = await vana.data.addPermissionToFile({
+     *   fileId: 123,
+     *   account: "0xRecipientAddress...",
+     *   publicKey: "0xRecipientPublicKey..."
+     * });
+     * console.log(`Permission granted to ${result.account} for file ${result.fileId}`);
+     * console.log(`Transaction: ${result.transactionHash}`);
+     * ```
+     */
+    addPermissionToFile(params: AddFilePermissionParams): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
+    /**
+     * Submits a file permission transaction to the blockchain.
+     *
+     * @remarks
+     * This method supports gasless transactions via relayer callbacks when configured.
+     * It encrypts the user's encryption key with the recipient's public key before submission.
+     * Use this when you want to handle transaction confirmation and event parsing separately.
+     *
+     * @param fileId - The ID of the file to grant permission for
+     * @param account - The recipient's wallet address that will access the file
+     * @param publicKey - The recipient's public key for encryption.
+     *   Obtain via `vana.server.getIdentity(account).publicKey`
+     * @returns Promise resolving to TransactionResult for tracking the transaction
+     * @throws {Error} When chain ID is not available
+     * @throws {Error} When encryption key generation fails
+     * @throws {Error} When public key encryption fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await vana.data.submitFilePermission(
+     *   fileId,
+     *   "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   recipientPublicKey
+     * );
+     * const result = await tx.waitForEvents();
+     * console.log(`Permission granted with ID: ${result.permissionId}`);
+     * ```
+     */
+    submitFilePermission(fileId: number, account: Address, publicKey: string): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
+    /**
+     * Gets the encrypted key for a specific account's permission to access a file.
+     *
+     * @param fileId - The ID of the file
+     * @param account - The account address to get the permission for
+     * @returns Promise resolving to the encrypted key for that account
+     */
+    getFilePermission(fileId: number, account: Address): Promise<string>;
+    /**
+     * Decrypts a file that the user has permission to access using their private key.
+     *
+     * This method handles the complete workflow for servers or other permitted parties:
+     * 1. Gets the encrypted encryption key from file permissions
+     * 2. Decrypts the encryption key using the provided private key
+     * 3. Downloads and decrypts the file data
+     *
+     * @param file - The file to decrypt
+     * @param privateKey - The private key to decrypt the user's encryption key
+     * @param options - Optional decryption configuration
+     * @param options.account - The account address that has permission (defaults to current wallet account)
+     * @returns Promise resolving to the decrypted file data
+     */
+    decryptFileWithPermission(file: UserFile, privateKey: string, options?: DecryptFileWithPermissionOptions): Promise<Blob>;
+    /**
+     * Simple network-agnostic fetch utility for retrieving file content.
+     *
+     * @remarks
+     * This is a thin wrapper around the global fetch API that returns the response as a Blob.
+     * It provides a consistent interface for fetching encrypted content before decryption.
+     * For IPFS URLs, consider using fetchFromIPFS for better reliability.
+     *
+     * @param url - The URL to fetch content from
+     * @returns Promise resolving to the fetched content as a Blob
+     * @throws {Error} "HTTP error! status: {status} {statusText}" - When server returns error status
+     * @throws {Error} "Empty response" - When server returns no content
+     * @throws {Error} "Network error: Failed to fetch from {url}" - When network request fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch and decrypt a file
+     * const encryptionKey = await generateEncryptionKey(walletClient);
+     * const encryptedBlob = await vana.data.fetch(file.url);
+     * const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
+     *
+     * // With custom headers for authentication
+     * const response = await fetch(file.url, {
+     *   headers: { 'Authorization': 'Bearer token' }
+     * });
+     * const encryptedBlob = await response.blob();
+     * ```
+     */
+    fetch(url: string): Promise<Blob>;
+    /**
+     * Specialized IPFS fetcher with gateway fallback mechanism.
+     *
+     * @remarks
+     * This method provides robust IPFS content fetching by trying multiple gateways
+     * in sequence until one succeeds. It supports both ipfs:// URLs and raw CIDs.
+     *
+     * The default gateway list includes public gateways, but you should provide
+     * your own gateways for production use to ensure reliability and privacy.
+     *
+     * @param url - The IPFS URL (ipfs://...) or CID to fetch
+     * @param options - Optional configuration
+     * @param options.gateways - Array of IPFS gateway URLs to try (must end with /)
+     * @returns Promise resolving to the fetched content as a Blob
+     * @throws {Error} "Invalid IPFS URL format" - When URL is not ipfs:// or valid CID
+     * @throws {Error} "Empty response" - When gateway returns no content
+     * @throws {Error} "HTTP error! status: {status}" - When gateway returns error status
+     * @throws {Error} "Failed to fetch IPFS content {cid} from all gateways" - When all gateways fail
+     *
+     * @example
+     * ```typescript
+     * // Fetch from IPFS with custom gateways
+     * const encryptedBlob = await vana.data.fetchFromIPFS(file.url, {
+     *   gateways: [
+     *     'https://my-private-gateway.com/ipfs/',
+     *     'https://dweb.link/ipfs/',
+     *     'https://ipfs.io/ipfs/'
+     *   ]
+     * });
+     *
+     * // Decrypt the fetched content
+     * const encryptionKey = await generateEncryptionKey(walletClient);
+     * const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
+     *
+     * // With raw CID
+     * const blob = await vana.data.fetchFromIPFS('QmXxx...', {
+     *   gateways: ['https://ipfs.io/ipfs/']
+     * });
+     * ```
+     */
+    fetchFromIPFS(url: string, options?: {
+        gateways?: string[];
+    }): Promise<Blob>;
+    /**
+     * Validates a data schema definition against the Vana meta-schema.
+     *
+     * @param schema - The data schema definition to validate
+     * @returns The validated DataSchema
+     * @throws SchemaValidationError if invalid
+     * @example
+     * ```typescript
+     * const schema = {
+     *   name: "User Profile",
+     *   version: "1.0.0",
+     *   dialect: "json",
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       age: { type: "number" }
+     *     }
+     *   }
+     * };
+     *
+     * const validatedSchema = vana.data.validateDataSchemaAgainstMetaSchema(schema);
+     * ```
+     */
+    validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchema;
+    /**
+     * Validates data against a JSON Schema from a data schema.
+     *
+     * @param data - The data to validate
+     * @param schema - The data schema containing the schema
+     * @returns Void (throws if validation fails)
+     * @throws SchemaValidationError if invalid
+     * @example
+     * ```typescript
+     * const schema = {
+     *   name: "User Profile",
+     *   version: "1.0.0",
+     *   dialect: "json",
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       age: { type: "number" }
+     *     },
+     *     required: ["name"]
+     *   }
+     * };
+     *
+     * const userData = { name: "Alice", age: 30 };
+     * vana.data.validateDataAgainstSchema(userData, schema);
+     * ```
+     */
+    validateDataAgainstSchema(data: unknown, schema: DataSchema): void;
+    /**
+     * Fetches and validates a data schema from a URL, then returns the parsed data schema.
+     *
+     * @param url - The URL to fetch the data schema from
+     * @returns The validated data schema
+     * @throws SchemaValidationError if invalid or fetch fails
+     * @example
+     * ```typescript
+     * // Fetch and validate a schema from IPFS or HTTP
+     * const schema = await vana.data.fetchAndValidateSchema("https://example.com/schema.json");
+     * console.log(schema.name, schema.dialect);
+     *
+     * // Use the schema to validate user data
+     * if (schema.dialect === "json") {
+     *   vana.data.validateDataAgainstSchema(userData, schema);
+     * }
+     * ```
+     */
+    fetchAndValidateSchema(url: string): Promise<DataSchema>;
+}