@opendatalabs/vana-sdk 2.3.0 → 3.0.0

package/dist/controllers/data.d.ts

@@ -1,1067 +0,0 @@
-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, 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 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
-     *
-     * **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
-     * 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 without encryption)
-     * const result = await vana.data.upload({
-     *   content: "User's data",
-     *   filename: "delegated.txt",
-     *   owner: "0x5678...",  // Different from connected wallet
-     *   encrypt: false        // Required when owner differs from wallet
-     * });
-     * ```
-     */
-    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;
-    }, options?: ConsistencyOptions & PaginationOptions): 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;
-        minBlock?: number;
-        waitForSync?: number;
-    }): 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;
-    }, options?: ConsistencyOptions & PaginationOptions): 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, options?: ConsistencyOptions & PaginationOptions): 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, 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
-     */
-    /**
-     * 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;
-    }>, 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.
-     *
-     * @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, options?: TransactionOptions): 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, options?: TransactionOptions): 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, options?: TransactionOptions): 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, options?: TransactionOptions): 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, options?: TransactionOptions): 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, options?: TransactionOptions): 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>;
-    /**
-     * Polls for confirmation of a relayer operation.
-     * @internal
-     */
-    private pollRelayerForConfirmation;
-}