@opendatalabs/vana-sdk 0.1.0-alpha.f54fafd → 0.1.0-alpha.f732fa2

package/dist/controllers/data.d.ts

@@ -0,0 +1,1052 @@
+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 blockchain registration on the Vana network.
+ *
+ * @remarks
+ * 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.
+ *
+ * **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()` - 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: `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 encrypted file with schema validation
+ * const result = await vana.data.upload({
+ *   content: { name: "Alice", age: 30 },
+ *   filename: "profile.json",
+ *   schemaId: 1
+ * });
+ * console.log(`File uploaded: ID ${result.fileId}, URL ${result.url}`);
+ *
+ * // Query user's files
+ * const files = await vana.data.getUserFiles({
+ *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+ * });
+ * files.forEach(file => console.log(`File ${file.id}: ${file.url}`));
+ *
+ * // Decrypt accessible file
+ * const decryptedData = await vana.data.decryptFile(files[0]);
+ * console.log("Decrypted content:", decryptedData);
+ * ```
+ *
+ * @category Data Management
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/data-registry}
+ */
+export declare class DataController extends BaseController {
+    constructor(context: ControllerContext);
+    /**
+     * Uploads data with automatic encryption and blockchain registration.
+     *
+     * @remarks
+     * 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:**
+     * - `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
+     *
+     * @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 delegation scenarios.
+     *   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 {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
+     * 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 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
+     * 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 files owned by a specific user address.
+     *
+     * @remarks
+     * 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
+     * const files = await vana.data.getUserFiles({
+     *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+     * });
+     *
+     * files.forEach(file => {
+     *   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[]>;
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const total = await vana.data.getTotalFilesCount();
+     * console.log(`Total files: ${total}`);
+     *
+     * // Calculate pagination
+     * const pages = Math.ceil(total / 20);
+     * ```
+     */
+    getTotalFilesCount(): Promise<number>;
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * 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}`);
+     * ```
+     */
+    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">>;
+    /**
+     * Registers a data refiner for processing templates.
+     *
+     * @remarks
+     * 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: "Sentiment Analyzer",
+     *   schemaId: 42,
+     *   refinementInstructionUrl: "ipfs://QmXxx..."
+     * });
+     * console.log(`Refiner ${result.refinerId} created`);
+     * ```
+     */
+    addRefiner(params: AddRefinerParams): Promise<AddRefinerResult>;
+    /**
+     * Retrieves refiner configuration by ID.
+     *
+     * @remarks
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const refiner = await vana.data.getRefiner(1);
+     * console.log(`Refiner: ${refiner.name}`);
+     * console.log(`DLP: ${refiner.dlpId}`);
+     * console.log(`Schema: ${refiner.schemaId}`);
+     * ```
+     */
+    getRefiner(refinerId: number): Promise<Refiner>;
+    /**
+     * Validates schema ID existence.
+     *
+     * @remarks
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const valid = await vana.data.isValidSchemaId(42);
+     * if (valid) {
+     *   // Safe to use schema 42
+     *   await vana.data.upload({ schemaId: 42, ... });
+     * }
+     * ```
+     */
+    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>;
+}