@opendatalabs/vana-sdk 0.1.0-alpha.8eb4e46 → 0.1.0-alpha.a145c3c

package/dist/index.browser.d.ts

@@ -236,7 +236,8 @@ interface GrantPermissionParams$1 {
     grantee: Address;
     /** The class of computation, e.g., "llm_inference" */
     operation: string;
-    /** Array of file IDs to grant permission for */
+    /** Array of file IDs to grant permission for.
+     *   Obtain file IDs from `vana.data.getUserFiles()` or from upload results via `vana.data.upload().fileId`. */
     files: number[];
     /** The full, off-chain parameters (e.g., LLM prompt) */
     parameters: Record<string, unknown>;
@@ -785,6 +786,12 @@ interface StorageRequiredMarker {
  * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)
  * and specify which one to use by default for file operations.
  *
+ * **Provider Selection:**
+ * - IPFS: Decentralized, permanent storage ideal for production
+ * - Pinata: Managed IPFS with guaranteed availability
+ * - Google Drive: Centralized, suitable for development/testing
+ * - Custom providers: Implement StorageProvider interface
+ *
  * @category Configuration
  * @example
  * ```typescript
@@ -798,9 +805,12 @@ interface StorageRequiredMarker {
  * ```
  */
 interface StorageConfig {
-    /** Map of provider name to storage provider instance */
+    /** Map of provider name to storage provider instance.
+     *   Common provider names: "ipfs", "pinata", "googledrive", "s3".
+     *   Custom names allowed for custom provider implementations. */
     providers: Record<string, StorageProvider>;
-    /** Default provider name to use when none specified */
+    /** Default provider name to use when none specified.
+     *   Must match a key in the providers map. Falls back to first provider if not specified. */
     defaultProvider?: string;
 }
 /**
@@ -901,10 +911,9 @@ interface RelayerCallbacks {
      *
      * @param params - Complete parameters for file addition
      * @param params.url - The file URL to register
-     * @param params.userAddress - The user's address (defaults to connected wallet if not specified)
+     * @param params.userAddress - The user's address
      * @param params.permissions - Array of encrypted permissions (empty array if none)
      * @param params.schemaId - Schema ID for validation (0 if none)
-     * @param params.ownerAddress - Optional owner address (defaults to userAddress if not specified)
      * @returns Promise resolving to object with fileId and transactionHash
      */
     submitFileAdditionComplete?: (params: {
@@ -915,7 +924,6 @@ interface RelayerCallbacks {
             key: string;
         }>;
         schemaId: number;
-        ownerAddress?: Address;
     }) => Promise<{
         fileId: number;
         transactionHash: Hash;
@@ -928,121 +936,6 @@ interface RelayerCallbacks {
      */
     storeGrantFile?: (grantData: GrantFile) => Promise<string>;
 }
-/**
- * Storage callback functions for flexible storage operations.
- *
- * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide
- * custom callback functions to handle storage operations in any way they choose.
- * This pattern matches the relayer callbacks approach, providing maximum flexibility.
- *
- * @category Configuration
- * @example
- * ```typescript
- * const storageCallbacks: StorageCallbacks = {
- *   async upload(blob, filename, metadata) {
- *     // Custom implementation - could be HTTP, S3, local filesystem, etc.
- *     const formData = new FormData();
- *     formData.append('file', blob, filename);
- *     const response = await fetch('/api/storage/upload', {
- *       method: 'POST',
- *       body: formData
- *     });
- *     const data = await response.json();
- *     return {
- *       url: data.url,
- *       size: blob.size,
- *       contentType: blob.type,
- *       metadata: data.metadata
- *     };
- *   },
- *
- *   async download(identifier) {
- *     const response = await fetch(`/api/storage/download/${identifier}`);
- *     return response.blob();
- *   }
- * };
- * ```
- */
-interface StorageCallbacks {
-    /**
-     * Upload a blob to storage
-     *
-     * @param blob - The data to upload
-     * @param filename - Optional filename hint
-     * @param metadata - Optional metadata for the upload
-     * @returns Upload result with identifier and metadata
-     */
-    upload: (blob: Blob, filename?: string, metadata?: Record<string, unknown>) => Promise<StorageUploadResult>;
-    /**
-     * Download data from storage
-     *
-     * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)
-     * @param options - Optional download options
-     * @returns The downloaded data as a Blob
-     */
-    download: (identifier: string, options?: StorageDownloadOptions) => Promise<Blob>;
-    /**
-     * List stored items (optional)
-     *
-     * @param prefix - Optional prefix to filter results
-     * @param options - Optional listing options
-     * @returns Array of storage items with metadata
-     */
-    list?: (prefix?: string, options?: StorageListOptions) => Promise<StorageListResult>;
-    /**
-     * Delete a stored item (optional)
-     *
-     * @param identifier - The storage identifier to delete
-     * @returns Promise that resolves to true if deletion succeeded
-     */
-    delete?: (identifier: string) => Promise<boolean>;
-    /**
-     * Extract identifier from a URL or return as-is (optional)
-     * Used for backward compatibility with URL-based systems
-     *
-     * @param url - The URL to extract from
-     * @returns The extracted identifier
-     */
-    extractIdentifier?: (url: string) => string;
-}
-/**
- * Options for storage download operations
- *
- * @category Configuration
- */
-interface StorageDownloadOptions {
-    /** Optional HTTP headers */
-    headers?: Record<string, string>;
-    /** Optional abort signal for cancellation */
-    signal?: AbortSignal;
-    /** Optional byte range for partial downloads */
-    range?: {
-        start?: number;
-        end?: number;
-    };
-}
-/**
- * Result from storage list operations
- *
- * @category Configuration
- */
-interface StorageListResult {
-    /** Array of storage items */
-    items: Array<{
-        /** Item identifier */
-        identifier: string;
-        /** Item size in bytes */
-        size?: number;
-        /** Last modified timestamp */
-        lastModified?: Date;
-        /** Item metadata */
-        metadata?: Record<string, unknown>;
-    }>;
-    /** Continuation token for pagination */
-    continuationToken?: string;
-    /** Whether more results are available */
-    hasMore?: boolean;
-}
 /**
  * Base configuration interface without storage requirements
  *
@@ -1054,18 +947,22 @@ interface BaseConfig {
      * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.
      */
     relayerCallbacks?: RelayerCallbacks;
-    /** Optional storage providers configuration for file upload/download */
+    /** Optional storage providers configuration for file upload/download.
+     *   Required for: upload(), grant() without pre-stored URLs, schema operations.
+     *   See StorageConfig for provider selection guidance. */
     storage?: StorageConfig;
     /**
      * Optional subgraph URL for querying user files and permissions.
      * If not provided, defaults to the built-in subgraph URL for the current chain.
      * Can be overridden per method call if needed.
+     * Obtain chain-specific URLs from Vana documentation or deployment info.
      */
     subgraphUrl?: string;
     /**
      * Optional default IPFS gateways to use for fetching files.
      * These gateways will be used by default in fetchFromIPFS unless overridden per-call.
      * If not provided, the SDK will use public gateways.
+     * Order matters: first successful gateway is used.
      *
      * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']
      */
@@ -1127,11 +1024,17 @@ interface WalletConfigWithStorage extends BaseConfigWithStorage {
  * @category Configuration
  */
 interface ChainConfig extends BaseConfig {
-    /** The chain ID for Vana network */
+    /** The chain ID for Vana network.
+     *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).
+     *   Use chain constants from '@vana/sdk' for type safety. */
     chainId: VanaChainId;
-    /** RPC URL for the chain (optional, will use default for the chain if not provided) */
+    /** RPC URL for the chain (optional, will use default for the chain if not provided).
+     *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).
+     *   Override for custom nodes or local development. */
     rpcUrl?: string;
-    /** Optional account for signing transactions */
+    /** Optional account for signing transactions.
+     *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.
+     *   Required for write operations; read-only operations work without account. */
     account?: Account;
 }
 /**
@@ -1389,7 +1292,8 @@ interface UserFile$1 {
     ownerAddress: Address;
     /** Block number when this file was registered on-chain. */
     addedAtBlock: bigint;
-    /** Schema identifier for data validation and structure definition. */
+    /** Schema identifier for data validation and structure definition.
+     *   Obtain schema IDs from `vana.schemas.list()` or when creating schemas via `vana.schemas.create()`. */
     schemaId?: number;
     /** Unix timestamp when the file was registered on-chain. */
     addedAtTimestamp?: bigint;
@@ -1485,8 +1389,6 @@ interface UploadParams {
     encrypt?: boolean;
     /** Optional storage provider name. */
     providerName?: string;
-    /** Optional owner address (defaults to current wallet address). */
-    owner?: Address;
 }
 /**
  * Upload parameters with encryption enabled (requires EncryptedPermissionParams).
@@ -1522,15 +1424,16 @@ interface UnencryptedUploadParams extends Omit<UploadParams, "encrypt"> {
 interface PermissionParams {
     /** The address of the application to grant permission to. */
     grantee: Address;
-    /** The operation type (e.g., "llm_inference"). */
+    /** The operation type (e.g., "llm_inference", "data_analysis", "compute_task"). */
     operation: string;
-    /** Additional parameters for the permission. */
+    /** Additional parameters for the permission (operation-specific configuration). */
     parameters: Record<string, unknown>;
-    /** Optional nonce for the permission. */
+    /** Optional nonce for the permission (auto-generated if not provided). */
     nonce?: bigint;
-    /** Optional expiration timestamp. */
+    /** Optional expiration timestamp (Unix seconds, no expiration if not provided). */
     expiresAt?: number;
-    /** Public key of the recipient to encrypt the data key for (required for upload with permissions). */
+    /** Public key of the recipient to encrypt the data key for (required for upload with permissions).
+     *   Obtain via `vana.server.getIdentity(recipientAddress).public_key` for personal servers. */
     publicKey?: string;
 }
 /**
@@ -1598,11 +1501,11 @@ interface UploadFileParams {
     content: Uint8Array | Buffer | string;
     /** Descriptive metadata for file organization and tracking. */
     metadata?: FileMetadata;
-    /** Storage provider name or uses configured default if unspecified. */
+    /** Storage provider name ("ipfs" or custom provider, uses configured default if unspecified). */
     storageProvider?: string;
-    /** Enables automatic encryption before upload to storage. */
+    /** Enables automatic encryption before upload to storage (defaults to false). */
     encrypt?: boolean;
-    /** Custom encryption key or generates one automatically if encryption enabled. */
+    /** Custom encryption key (auto-generated if encryption enabled and not provided). */
     encryptionKey?: string;
 }
 /**
@@ -2440,96 +2343,88 @@ declare class PinataStorage implements StorageProvider {
     private isValidCID;
 }
 
+interface ServerProxyConfig {
+    /** Server endpoint for file uploads */
+    uploadUrl: string;
+    /** Server endpoint for file downloads */
+    downloadUrl: string;
+}
 /**
- * Storage provider that delegates all operations to user-provided callbacks.
+ * Delegates storage operations to your server endpoints
  *
- * This provider follows the same flexible pattern as relayer callbacks,
- * allowing users to implement storage operations in any way they choose
- * (HTTP, WebSocket, direct cloud APIs, local filesystem, etc.).
+ * @remarks
+ * This provider is completely agnostic about the actual storage backend used by
+ * your server. It simply proxies upload and download requests to your configured
+ * endpoints, allowing you to implement any storage strategy (IPFS, S3, local filesystem, etc.)
+ * on the server side while maintaining a consistent client interface.
  *
  * @category Storage
+ *
  * @example
  * ```typescript
- * // HTTP-based implementation
- * const httpCallbacks: StorageCallbacks = {
- *   async upload(blob, filename) {
- *     const formData = new FormData();
- *     formData.append('file', blob, filename);
- *     const response = await fetch('/api/storage/upload', {
- *       method: 'POST',
- *       body: formData
- *     });
- *     const data = await response.json();
- *     return {
- *       url: data.url,
- *       size: blob.size,
- *       contentType: blob.type
- *     };
- *   },
- *   async download(identifier) {
- *     const response = await fetch(`/api/storage/download/${identifier}`);
- *     return response.blob();
- *   }
- * };
+ * const serverStorage = new ServerProxyStorage({
+ *   uploadUrl: "/api/files/upload",
+ *   downloadUrl: "/api/files/download"
+ * });
  *
- * const storage = new CallbackStorage(httpCallbacks);
- *
- * // Direct S3 implementation
- * const s3Callbacks: StorageCallbacks = {
- *   async upload(blob, filename) {
- *     const url = await getPresignedUploadUrl(filename);
- *     await fetch(url, { method: 'PUT', body: blob });
- *     return {
- *       url: `s3://my-bucket/${filename}`,
- *       size: blob.size,
- *       contentType: blob.type
- *     };
- *   },
- *   async download(identifier) {
- *     const url = await getPresignedDownloadUrl(identifier);
- *     const response = await fetch(url);
- *     return response.blob();
- *   }
- * };
+ * // Upload file through your server
+ * const identifier = await serverStorage.upload(fileBlob, { name: "document.pdf" });
+ *
+ * // Download file through your server
+ * const file = await serverStorage.download(identifier);
  * ```
  */
-declare class CallbackStorage implements StorageProvider {
-    private readonly callbacks;
-    constructor(callbacks: StorageCallbacks);
+declare class ServerProxyStorage implements StorageProvider {
+    private config;
+    constructor(config: ServerProxyConfig);
     /**
-     * Upload a file using the provided callback
+     * Uploads a file through your server endpoint
      *
-     * @param file - The blob to upload
-     * @param filename - Optional filename for the upload
-     * @returns The upload result with URL and metadata
+     * @remarks
+     * This method sends the file to your configured upload endpoint via FormData.
+     * Your server is responsible for handling the actual storage implementation
+     * and must return a JSON response with `success: true` and an `identifier` field.
+     *
+     * @param file - The file to upload
+     * @param filename - Optional custom filename
+     * @returns Promise that resolves to the server-provided identifier
+     * @throws {StorageError} When the upload fails or server returns an error
+     *
+     * @example
+     * ```typescript
+     * const identifier = await serverStorage.upload(fileBlob, { name: "report.pdf" });
+     * console.log("File uploaded with identifier:", identifier);
+     * ```
      */
     upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
     /**
-     * Download a file using the provided callback
+     * Downloads a file through your server endpoint
      *
-     * @param url - The URL or identifier to download
-     * @returns The downloaded blob
-     */
-    download(url: string): Promise<Blob>;
-    /**
-     * List files using the provided callback (if available)
+     * @remarks
+     * This method sends the identifier to your configured download endpoint via POST request.
+     * Your server is responsible for retrieving the file from your storage backend
+     * and returning the file content as a blob response.
      *
-     * @param options - Optional list options including filters and pagination
-     * @returns Array of storage files
-     */
-    list(options?: StorageListOptions): Promise<StorageFile[]>;
-    /**
-     * Delete a file using the provided callback (if available)
+     * @param url - The server-provided URL or identifier from upload
+     * @returns Promise that resolves to the downloaded file content
+     * @throws {StorageError} When the download fails or file is not found
      *
-     * @param url - The URL or identifier to delete
-     * @returns True if deletion succeeded
+     * @example
+     * ```typescript
+     * const fileBlob = await serverStorage.download("file-123");
+     * const url = URL.createObjectURL(fileBlob);
+     * ```
      */
-    delete(url: string): Promise<boolean>;
+    download(url: string): Promise<Blob>;
+    list(_options?: StorageListOptions): Promise<StorageFile[]>;
+    delete(_url: string): Promise<boolean>;
     /**
-     * Get provider configuration
+     * Extract identifier from URL or return as-is
      *
-     * @returns Provider configuration metadata
+     * @param url - URL or identifier string
+     * @returns identifier string
      */
+    private extractIdentifierFromUrl;
     getConfig(): StorageProviderConfig;
 }
 
@@ -2685,6 +2580,15 @@ declare class StorageManager {
  *
  * This interface abstracts all environment-specific dependencies to ensure
  * the SDK works seamlessly across Node.js and browser/SSR environments.
+ *
+ * **Implementation Context:**
+ * - Node.js: Uses native crypto modules and full OpenPGP support
+ * - Browser: Uses Web Crypto API and browser-compatible libraries
+ * - SSR: Automatically selects appropriate implementation based on runtime
+ *
+ * **Usage Notes:**
+ * Platform adapters are automatically selected by the SDK. Direct usage is only
+ * needed for custom implementations or testing.
  */
 /**
  * Platform type identifier
@@ -2697,6 +2601,11 @@ interface VanaCryptoAdapter {
     /**
      * Encrypt data with a public key using asymmetric cryptography
      *
+     * **Usage Context:**
+     * - Used internally for file encryption before storage
+     * - Public key format: Armored PGP public key string
+     * - Returns base64-encoded encrypted data
+     *
      * @param data The data to encrypt
      * @param publicKey The public key for encryption
      * @returns Promise resolving to encrypted data
@@ -2723,6 +2632,11 @@ interface VanaCryptoAdapter {
      * Encrypt data with a wallet's public key using ECDH cryptography
      * Uses platform-appropriate ECDH implementation (eccrypto vs eccrypto-js)
      *
+     * **Usage Context:**
+     * - Used for sharing encryption keys with permission recipients
+     * - Public key format: Compressed or uncompressed secp256k1 hex string
+     * - Compatible with Ethereum wallet public keys
+     *
      * @param data The data to encrypt (string)
      * @param publicKey The wallet's public key (secp256k1)
      * @returns Promise resolving to encrypted data as hex string
@@ -2809,6 +2723,22 @@ interface VanaHttpAdapter {
 }
 /**
  * Main platform adapter interface that combines all platform-specific functionality
+ *
+ * **Implementation Guidelines:**
+ * 1. All methods must maintain consistent behavior across platforms
+ * 2. Error types and messages should be unified
+ * 3. Data formats (encoding, serialization) must be identical
+ * 4. Performance characteristics can vary but API must be consistent
+ *
+ * **Custom Implementation Example:**
+ * ```typescript
+ * class CustomPlatformAdapter implements VanaPlatformAdapter {
+ *   crypto = new CustomCryptoAdapter();
+ *   pgp = new CustomPGPAdapter();
+ *   http = new CustomHttpAdapter();
+ *   platform = 'browser' as const;
+ * }
+ * ```
  */
 interface VanaPlatformAdapter {
     /**
@@ -2872,15 +2802,27 @@ interface ControllerContext$1 {
  * The controller also manages trusted servers that can process user data and provides
  * methods for revoking permissions when access is no longer needed.
  *
- * All permission operations support both gasless transactions via relayers and direct
- * blockchain transactions. Grant files containing detailed permission parameters are
- * stored on IPFS while permission references are recorded on the blockchain.
+ * **Permission Architecture:**
+ * Permissions use dual storage: detailed parameters stored on IPFS, references stored on blockchain.
+ * This enables complex permissions while maintaining minimal on-chain data.
+ *
+ * **Method Selection:**
+ * - `grant()` creates new permissions with automatic IPFS upload and blockchain registration
+ * - `prepareGrant()` allows preview before signing for interactive applications
+ * - `revoke()` removes permissions by ID, supporting both gasless and direct transactions
+ * - `getUserPermissionGrantsOnChain()` queries existing permissions efficiently
+ * - `trustServer()` and `untrustServer()` manage server access for data processing
+ *
+ * **Transaction Types:**
+ * Methods with gasless support: `grant()`, `revoke()`, `trustServer()`, `untrustServer()`
+ * Methods requiring direct transactions: none (all support both gasless and direct)
  * @example
  * ```typescript
  * // Grant permission for an app to access your data
  * const txHash = await vana.permissions.grant({
  *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
  *   operation: "llm_inference",
+ *   files: [1, 2, 3],
  *   parameters: { model: "gpt-4", maxTokens: 1000 },
  * });
  *
@@ -2891,7 +2833,7 @@ interface ControllerContext$1 {
  * });
  *
  * // Query current permissions
- * const permissions = await vana.permissions.getUserPermissions();
+ * const permissions = await vana.permissions.getUserPermissionGrantsOnChain();
  * ```
  * @category Permissions
  * @see {@link [URL_PLACEHOLDER] | Vana Permissions System} for conceptual overview
@@ -3059,6 +3001,8 @@ declare class PermissionsController {
      * Revokes a previously granted permission.
      *
      * @param params - Parameters for revoking the permission
+     * @param params.permissionId - Permission identifier as bigint for contract compatibility.
+     *   Obtain from permission grants via `getUserPermissionGrantsOnChain()`.
      * @returns Promise resolving to transaction hash
      * @example
      * ```typescript
@@ -3368,9 +3312,20 @@ interface CreateSchemaResult {
  * validation, IPFS upload, and blockchain registration. It provides methods for managing
  * both schemas (data structure definitions) and refiners (data processing definitions).
  *
- * Schemas are public protocol entities that define data structures and validation rules.
- * Unlike private user data, schemas are stored unencrypted on IPFS to enable public
- * access and reusability across the network.
+ * **Schema Storage:**
+ * Schemas are stored unencrypted on IPFS for public access and reusability across the network.
+ * Schema definitions use JSON Schema format for data validation and structure definition.
+ *
+ * **Method Selection:**
+ * - `create()` validates, uploads to IPFS, and registers new schemas on blockchain
+ * - `get()` retrieves existing schema metadata by ID from blockchain contracts
+ * - `count()` returns total number of registered schemas for pagination
+ * - `list()` provides paginated access to all schemas with optional filtering
+ * - `addSchema()` provides lower-level schema registration with pre-uploaded URLs
+ *
+ * **Storage Requirements:**
+ * Methods requiring storage configuration: `create()`
+ * Methods working without storage: `get()`, `count()`, `list()`, `addSchema()`
  *
  * @example
  * ```typescript
@@ -5428,13 +5383,23 @@ interface GrantPermissionParams {
  * 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.uploadEncryptedFile(
- *   encryptedBlob,
- *   "personal-data.json"
- * );
+ * 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({
@@ -5470,10 +5435,16 @@ declare class DataController {
      * for each permission recipient.
      *
      * @param params - Upload parameters including content, filename, schema, and permissions
+     * @param params.permissions.publicKey - The recipient's public key for encryption.
+     *   Obtain via `vana.server.getIdentity(userAddress).public_key` for personal servers.
+     * @param params.permissions.grantee - The application's wallet address that will access the data.
      * @returns Promise resolving to upload results with file ID and transaction hash
-     * @throws {Error} When wallet is not connected or storage is not configured
-     * @throws {SchemaValidationError} When schema validation fails
-     * @throws {Error} When upload or blockchain registration fails
+     * @throws {Error} When wallet is not connected or storage is not configured.
+     *   Configure storage providers in VanaConfig or check wallet connection.
+     * @throws {SchemaValidationError} When data format doesn't match the specified schema.
+     *   Verify data structure matches schema definition from `vana.schemas.get(schemaId)`.
+     * @throws {Error} When upload or blockchain registration fails.
+     *   Check network connection and storage provider availability.
      * @example
      * ```typescript
      * // Basic file upload
@@ -5497,7 +5468,7 @@ declare class DataController {
      *     grantee: "0x1234...",
      *     operation: "llm_inference",
      *     parameters: { model: "gpt-4" },
-     *     publicKey: "0x04..." // Required when encrypt is true (default)
+     *     publicKey: "0x04..." // Obtain via vana.server.getIdentity(userAddress).public_key
      *   }]
      * });
      *
@@ -5512,19 +5483,6 @@ declare class DataController {
      *     parameters: {}
      *   }]
      * });
-     *
-     * // 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: [{
-     *     grantee: "0x1234...",
-     *     operation: "process",
-     *     parameters: { type: "analysis" },
-     *     publicKey: "0x04..."
-     *   }]
-     * });
      * ```
      */
     upload(params: EncryptedUploadParams): Promise<UploadResult>;
@@ -6104,23 +6062,33 @@ declare class DataController {
  * cryptographic keys for secure data sharing. All server interactions use the
  * Replicate API infrastructure with proper authentication and error handling.
  *
- * Personal servers enable privacy-preserving computation on user data, while identity
- * servers provide deterministic key derivation for secure communication without
- * requiring servers to be online during key retrieval.
+ * **Server Identity System:**
+ * Personal servers use deterministic key derivation: each user address maps to a specific server identity.
+ * This enables secure communication without requiring servers to be online during key retrieval.
+ *
+ * **Method Selection:**
+ * - `getIdentity()` retrieves server public keys and addresses for encryption setup
+ * - `createOperation()` submits computation requests with signed permission verification
+ * - `getOperation()` polls operation status and retrieves results when complete
+ * - `cancelOperation()` stops running operations when cancellation is supported
+ *
+ * **Workflow Pattern:**
+ * Typical flow: Get identity → Create operation → Poll status → Retrieve results
+ *
  * @example
  * ```typescript
- * // Post a request to a personal server
- * const response = await vana.server.postRequest({
- *   permissionId: 123,
+ * // Get a server's identity including public key for encryption
+ * const identity = await vana.server.getIdentity({
+ *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
  * });
  *
- * // Get a server's identity including public key for encryption
- * const identity = await vana.server.getIdentity(
- *   "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
- * );
+ * // Create an operation using a granted permission
+ * const response = await vana.server.createOperation({
+ *   permissionId: 123,
+ * });
  *
  * // Poll for computation results
- * const result = await vana.server.pollStatus(response.urls.get);
+ * const result = await vana.server.getOperation(response.id);
  * ```
  * @category Server Management
  * @see {@link [URL_PLACEHOLDER] | Vana Personal Servers} for conceptual overview
@@ -6129,6 +6097,39 @@ declare class ServerController {
     private readonly context;
     readonly PERSONAL_SERVER_BASE_URL: string | undefined;
     constructor(context: ControllerContext$1);
+    /**
+     * Retrieves the cryptographic identity of a personal server.
+     *
+     * @remarks
+     * This method fetches the public key and metadata for a personal server,
+     * which is required for encrypting data before sharing with the server.
+     * The identity includes the server's public key, address, and operational
+     * details needed for secure communication. This information is cached
+     * by identity servers to enable offline key retrieval.
+     *
+     * @param request - Parameters containing the user address
+     * @param request.userAddress - The wallet address associated with the personal server
+     * @returns Promise resolving to the server's identity information
+     * @throws {NetworkError} When the identity service is unavailable or returns invalid data
+     * @throws {PersonalServerError} When server identity cannot be retrieved
+     * @example
+     * ```typescript
+     * // Get server identity for data encryption
+     * const identity = await vana.server.getIdentity({
+     *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+     * });
+     *
+     * console.log(`Server: ${identity.name}`);
+     * console.log(`Address: ${identity.address}`);
+     * console.log(`Public Key: ${identity.public_key}`);
+     *
+     * // Use the public key for encrypting data to share with this server
+     * const encryptedData = await encryptWithWalletPublicKey(
+     *   userData,
+     *   identity.public_key
+     * );
+     * ```
+     */
     getIdentity(request: InitPersonalServerParams): Promise<PersonalServerIdentity>;
     /**
      * Creates an operation via the personal server API.
@@ -6137,10 +6138,13 @@ declare class ServerController {
      * This method submits a computation request to the personal server API.
      * The response includes the operation ID.
      * @param params - The request parameters object
-     * @param params.permissionId - The permission ID authorizing this operation
+     * @param params.permissionId - The permission ID authorizing this operation.
+     *   Obtain from granted permissions via `vana.permissions.getUserPermissionGrantsOnChain()`.
      * @returns A Promise that resolves to an operation response with status and control URLs
-     * @throws {PersonalServerError} When server request fails or parameters are invalid
-     * @throws {NetworkError} When personal server API communication fails
+     * @throws {PersonalServerError} When server request fails or parameters are invalid.
+     *   Verify permissionId exists and is active for the target server.
+     * @throws {NetworkError} When personal server API communication fails.
+     *   Check server URL configuration and network connectivity.
      * @example
      * ```typescript
      * const response = await vana.server.createOperation({
@@ -6180,6 +6184,50 @@ declare class ServerController {
      * ```
      */
     getOperation(operationId: string): Promise<GetOperationResponse>;
+    /**
+     * Cancels a running operation on the personal server.
+     *
+     * @remarks
+     * This method attempts to cancel an operation that is currently processing
+     * on the personal server. The operation must be in a cancellable state
+     * (typically `starting` or `processing`). Not all operations support
+     * cancellation, and cancellation may not be immediate. The server will
+     * attempt to stop the operation and update its status to `canceled`.
+     *
+     * **Cancellation Behavior:**
+     * - Operations in `succeeded` or `failed` states cannot be canceled
+     * - Some long-running operations may take time to respond to cancellation
+     * - Always verify cancellation by polling the operation status afterward
+     *
+     * @param operationId - The unique identifier of the operation to cancel,
+     *   obtained from `createOperation()` response
+     * @returns Promise that resolves when the cancellation request is accepted
+     * @throws {PersonalServerError} When the operation cannot be canceled or doesn't exist.
+     *   Check operation status - it may already be completed or failed.
+     * @throws {NetworkError} When unable to reach the personal server API.
+     *   Verify server URL and network connectivity.
+     * @example
+     * ```typescript
+     * // Start a long-running operation
+     * const operation = await vana.server.createOperation({
+     *   permissionId: 123
+     * });
+     *
+     * // Cancel if needed
+     * try {
+     *   await vana.server.cancelOperation(operation.id);
+     *   console.log("Cancellation requested");
+     *
+     *   // Verify cancellation
+     *   const status = await vana.server.getOperation(operation.id);
+     *   if (status.status === "canceled") {
+     *     console.log("Operation successfully canceled");
+     *   }
+     * } catch (error) {
+     *   console.error("Failed to cancel:", error);
+     * }
+     * ```
+     */
     cancelOperation(operationId: string): Promise<void>;
     /**
      * Makes the request to the personal server API.
@@ -31075,19 +31123,26 @@ declare function clearContractCache(contract?: VanaContract, chainId?: number):
  * Most developers should use the higher-level DataController and PermissionsController
  * instead of this advanced API.
  *
+ * **Contract Selection:**
  * The controller automatically handles chain detection and provides only contracts that
  * are deployed on the current network. All contract instances are fully typed for
  * enhanced developer experience and type safety.
  *
- * **Use this controller when:**
- * - High-level controllers don't provide needed functionality
- * - You need direct contract method calls or event access
- * - You're building custom integrations or tooling
- * - You need advanced querying capabilities
+ * **Method Selection:**
+ * - `getContract()` retrieves contract address and ABI for manual interaction
+ * - `createContract()` returns fully typed contract instance with read/write methods
+ * - `getAvailableContracts()` lists all contracts deployed on current chain
+ * - `isContractAvailable()` checks if specific contract exists on current chain
+ * - `getChainId()` and `getChainName()` provide current network information
+ *
+ * **Usage Guidelines:**
+ * Use this controller when high-level controllers don't provide needed functionality.
+ * Most developers should use `vana.data.*` for files and `vana.permissions.*` for access control.
+ *
+ * **Type Safety:**
+ * Use `as const` assertion with contract names for full TypeScript type inference.
+ * Contract instances provide complete typing for all methods, parameters, and return values.
  *
- * **Most developers should use instead:**
- * - `vana.data.*` for file management operations
- * - `vana.permissions.*` for access control workflows
  * @example
  * ```typescript
  * // Get contract info for direct interaction
@@ -31118,7 +31173,8 @@ declare class ProtocolController {
      * are actually deployed on the current network.
      * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)
      * @returns An object containing the contract's address and fully typed ABI
-     * @throws {ContractNotFoundError} When the contract is not deployed on the current chain
+     * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.
+     *   Verify contract name spelling and check current network with `getChainId()`.
      * @example
      * ```typescript
      * // Get contract info with full type inference
@@ -31235,19 +31291,43 @@ declare class VanaCoreFactory {
  * @remarks
  * This environment-agnostic class contains all SDK logic and accepts a platform
  * adapter to handle environment-specific operations. It initializes all controllers
- * and manages shared context between them.
+ * and manages shared context between them, providing a unified interface for
+ * data management, permissions, smart contracts, and storage operations.
  *
  * The class uses TypeScript overloading to enforce storage requirements at compile time.
- * When storage is required for certain operations, the constructor will fail fast at runtime.
+ * Methods that require storage will throw `InvalidConfigurationError` at runtime if
+ * storage providers are not configured, implementing a fail-fast approach to prevent
+ * errors during expensive operations.
+ *
+ * **Core Architecture:**
+ * - **Controllers**: Specialized modules for different Vana features (data, permissions, etc.)
+ * - **Platform Adapters**: Environment-specific implementations (browser vs Node.js)
+ * - **Storage Managers**: Abstraction layer for multiple storage providers
+ * - **Context Sharing**: Unified configuration and services across all controllers
+ *
+ * For public usage, use the platform-specific factory functions:
+ * - Browser: `import { Vana } from '@opendatalabs/vana-sdk/browser'`
+ * - Node.js: `import { Vana } from '@opendatalabs/vana-sdk/node'`
  *
- * For public usage, use the platform-specific Vana classes that extend this core:
- * - Use `Vana({config)` from the main package import
  * @example
  * ```typescript
- * // Direct instantiation (typically used internally)
- * const core = new VanaCore({
+ * // Direct instantiation (advanced usage)
+ * import { VanaCore, BrowserPlatformAdapter } from '@opendatalabs/vana-sdk/browser';
+ *
+ * const core = new VanaCore(new BrowserPlatformAdapter(), {
  *   walletClient: myWalletClient,
- * }, platformAdapter);
+ *   storage: {
+ *     providers: { ipfs: new IPFSStorage() },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * });
+ *
+ * // Access all controllers
+ * const files = await core.data.getUserFiles();
+ * const permissions = await core.permissions.grant({
+ *   grantee: '0x742d35...',
+ *   operation: 'read'
+ * });
  * ```
  * @category Core SDK
  */
@@ -31420,30 +31500,86 @@ declare class VanaCore {
     getPlatformAdapter(): VanaPlatformAdapter;
     /**
      * Encrypts data using the Vana protocol standard encryption.
-     * This method automatically uses the correct platform adapter for the current environment.
      *
-     * @param data The data to encrypt (string or Blob)
-     * @param key The key to use as encryption key
-     * @returns The encrypted data as Blob
+     * @remarks
+     * This method implements the Vana network's standard encryption protocol using
+     * platform-appropriate cryptographic libraries. It automatically handles different
+     * input types (string or Blob) and produces encrypted output suitable for secure
+     * storage or transmission. The encryption is compatible with the network's
+     * decryption protocols and can be decrypted by authorized parties.
+     *
+     * @param data - The data to encrypt (string or Blob)
+     * @param key - The encryption key (typically generated via `generateEncryptionKey`)
+     * @returns The encrypted data as a Blob
+     * @throws {Error} When encryption fails due to invalid key or data format
      * @example
      * ```typescript
-     * const encryptionKey = await generateEncryptionKey(walletClient);
-     * const encrypted = await vana.encryptBlob("sensitive data", encryptionKey);
+     * import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
+     *
+     * // Generate encryption key from wallet signature
+     * const encryptionKey = await generateEncryptionKey(vana.walletClient);
+     *
+     * // Encrypt string data
+     * const sensitiveData = "User's private information";
+     * const encrypted = await vana.encryptBlob(sensitiveData, encryptionKey);
+     *
+     * // Encrypt file data
+     * const fileBlob = new Blob([fileContent], { type: 'application/json' });
+     * const encryptedFile = await vana.encryptBlob(fileBlob, encryptionKey);
+     *
+     * // Store encrypted data safely
+     * await storageProvider.upload(encrypted, 'encrypted-data.bin');
      * ```
      */
     encryptBlob(data: string | Blob, key: string): Promise<Blob>;
     /**
      * Decrypts data that was encrypted using the Vana protocol.
-     * This method automatically uses the correct platform adapter for the current environment.
      *
-     * @param encryptedData The encrypted data (string or Blob)
-     * @param walletSignature The wallet signature to use as decryption key
-     * @returns The decrypted data as Blob
+     * @remarks
+     * This method decrypts data that was previously encrypted using the Vana network's
+     * standard encryption protocol. It requires the same wallet signature that was used
+     * for encryption and automatically uses the appropriate platform adapter for
+     * cryptographic operations. The decrypted output maintains the original data format.
+     *
+     * @param encryptedData - The encrypted data (string or Blob)
+     * @param walletSignature - The wallet signature used as decryption key
+     * @returns The decrypted data as a Blob
+     * @throws {Error} When decryption fails due to invalid signature or corrupted data
      * @example
      * ```typescript
-     * const encryptionKey = await generateEncryptionKey(walletClient);
-     * const decrypted = await vana.decryptBlob(encryptedData, encryptionKey);
-     * const text = await decrypted.text();
+     * import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
+     *
+     * // Retrieve encrypted data from storage
+     * const encryptedBlob = await storageProvider.download('encrypted-data.bin');
+     *
+     * // Generate the same key used for encryption
+     * const decryptionKey = await generateEncryptionKey(vana.walletClient);
+     *
+     * // Decrypt the data
+     * const decrypted = await vana.decryptBlob(encryptedBlob, decryptionKey);
+     *
+     * // Convert back to original format
+     * const originalText = await decrypted.text();
+     * const originalJson = JSON.parse(originalText);
+     *
+     * console.log('Decrypted data:', originalJson);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Decrypt file downloaded from Vana network
+     * const userFiles = await vana.data.getUserFiles();
+     * const file = userFiles[0];
+     *
+     * // Download encrypted content
+     * const encrypted = await fetch(file.url).then(r => r.blob());
+     *
+     * // Decrypt with user's key
+     * const decryptionKey = await generateEncryptionKey(vana.walletClient);
+     * const decrypted = await vana.decryptBlob(encrypted, decryptionKey);
+     *
+     * // Process original data
+     * const fileContent = await decrypted.arrayBuffer();
      * ```
      */
     decryptBlob(encryptedData: string | Blob, walletSignature: string): Promise<Blob>;
@@ -31491,7 +31627,32 @@ declare class UserRejectedRequestError extends VanaError {
     constructor(message?: string);
 }
 /**
- * Error thrown when the SDK configuration is invalid.
+ * Thrown when the SDK configuration contains invalid or missing parameters.
+ *
+ * @remarks
+ * This error occurs during SDK initialization when required configuration
+ * parameters are missing, invalid, or incompatible. Common causes include
+ * missing wallet clients, invalid chain IDs, malformed storage provider
+ * configurations, or incompatible parameter combinations.
+ *
+ * Applications should catch this error during initialization and provide
+ * clear feedback to users about configuration requirements.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const vana = Vana({
+ *     chainId: 999999, // Invalid chain ID
+ *     account: null // Missing account
+ *   });
+ * } catch (error) {
+ *   if (error instanceof InvalidConfigurationError) {
+ *     console.error('Configuration error:', error.message);
+ *     // Show user-friendly configuration help
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class InvalidConfigurationError extends VanaError {
     constructor(message: string);
@@ -31509,20 +31670,92 @@ declare class ContractNotFoundError extends VanaError {
     constructor(contractName: string, chainId: number);
 }
 /**
- * Error thrown when a blockchain operation fails.
+ * Thrown when blockchain operations fail due to network, contract, or transaction issues.
+ *
+ * @remarks
+ * This error encompasses various blockchain-related failures including network
+ * connectivity issues, contract execution failures, insufficient gas, invalid
+ * transaction parameters, or smart contract reverts. The original error is
+ * preserved to provide detailed debugging information while maintaining a
+ * consistent SDK error interface.
+ *
+ * Common causes:
+ * - Network connectivity problems
+ * - Insufficient gas or gas price too low
+ * - Contract function reverts
+ * - Invalid transaction parameters
+ * - Blockchain congestion or downtime
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await vana.permissions.grant({
+ *     grantee: '0x742d35...',
+ *     operation: 'read'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof BlockchainError) {
+ *     console.error('Blockchain operation failed:', error.message);
+ *
+ *     // Check if it's a network issue
+ *     if (error.originalError?.message.includes('network')) {
+ *       // Retry with exponential backoff
+ *       await retryOperation();
+ *     }
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class BlockchainError extends VanaError {
     readonly originalError?: Error | undefined;
     constructor(message: string, originalError?: Error | undefined);
 }
 /**
- * Error thrown when parameter serialization fails.
+ * Thrown when data serialization or deserialization operations fail.
+ *
+ * @remarks
+ * This error occurs when the SDK cannot properly serialize parameters for
+ * blockchain transactions, IPFS storage, or API calls. Common causes include
+ * circular references in objects, unsupported data types, or malformed JSON.
+ * It's typically encountered during grant file creation, storage operations,
+ * or when preparing transaction data.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Object with circular reference causes serialization error
+ *   const obj = { name: 'test' };
+ *   obj.self = obj; // Circular reference
+ *
+ *   await vana.data.upload({
+ *     content: obj,
+ *     filename: 'data.json'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof SerializationError) {
+ *     console.error('Data serialization failed:', error.message);
+ *     // Clean data before retry
+ *     const cleanedData = removeCircularReferences(obj);
+ *     await vana.data.upload({
+ *       content: cleanedData,
+ *       filename: 'data.json'
+ *     });
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class SerializationError extends VanaError {
     constructor(message: string);
 }
 /**
  * Error thrown when a signature operation fails.
+ *
+ * @remarks
+ * Recovery strategies: Check wallet connection and account unlock status,
+ * retry operation with explicit user interaction, or for gasless operations
+ * consider switching to direct transactions.
  */
 declare class SignatureError extends VanaError {
     readonly originalError?: Error | undefined;
@@ -31530,6 +31763,10 @@ declare class SignatureError extends VanaError {
 }
 /**
  * Error thrown when a network operation fails.
+ *
+ * @remarks
+ * Recovery strategies: Check network connectivity, retry with exponential backoff,
+ * verify API endpoints are accessible, or switch to alternative network providers.
  */
 declare class NetworkError extends VanaError {
     readonly originalError?: Error | undefined;
@@ -31537,12 +31774,20 @@ declare class NetworkError extends VanaError {
 }
 /**
  * Error thrown when the nonce retrieval fails.
+ *
+ * @remarks
+ * Recovery strategies: Retry nonce retrieval after brief delay, check wallet connection
+ * and account status, or use manual nonce specification if supported by the operation.
  */
 declare class NonceError extends VanaError {
     constructor(message: string);
 }
 /**
  * Error thrown when a personal server operation fails.
+ *
+ * @remarks
+ * Recovery strategies: Verify server URL accessibility, check server trust status via
+ * `vana.permissions.getUserTrustedServers()`, or retry after server becomes available.
  */
 declare class PersonalServerError extends VanaError {
     readonly originalError?: Error | undefined;
@@ -31601,21 +31846,93 @@ declare const DEFAULT_ENCRYPTION_SEED = "Please sign to retrieve your encryption
  */
 declare function generateEncryptionKey(wallet: WalletClient, seed?: string): Promise<string>;
 /**
- * Encrypt data with a wallet's public key using platform-appropriate cryptography
+ * Encrypts data using a wallet's public key for secure sharing with specific recipients.
  *
- * @param data The data to encrypt (as string or Blob)
- * @param publicKey The public key for encryption
- * @param platformAdapter - The platform adapter for crypto operations
- * @returns The encrypted data
+ * @remarks
+ * This function implements asymmetric encryption using the recipient's public key,
+ * enabling secure data sharing where only the holder of the corresponding private key
+ * can decrypt the data. It automatically handles different data types and uses
+ * platform-appropriate cryptographic libraries for maximum compatibility.
+ *
+ * This is commonly used when granting permissions to applications or servers,
+ * where the data needs to be encrypted for a specific recipient's public key.
+ *
+ * @param data - The data to encrypt (string or Blob)
+ * @param publicKey - The recipient's public key in hexadecimal format
+ * @param platformAdapter - The platform adapter providing cryptographic operations
+ * @returns Promise resolving to the encrypted data as a string
+ * @throws {Error} When encryption fails due to invalid key or data format
+ * @example
+ * ```typescript
+ * // Encrypt data for a specific application's public key
+ * const appPublicKey = "0x04a1b2c3..."; // Application's public key
+ * const sensitiveData = "User's private information";
+ *
+ * const encrypted = await encryptWithWalletPublicKey(
+ *   sensitiveData,
+ *   appPublicKey,
+ *   platformAdapter
+ * );
+ *
+ * console.log('Encrypted for app:', encrypted);
+ *
+ * // Encrypt file data for server processing
+ * const fileBlob = new File(['{"name":"John","age":30}'], 'profile.json');
+ * const encryptedFile = await encryptWithWalletPublicKey(
+ *   fileBlob,
+ *   serverPublicKey,
+ *   platformAdapter
+ * );
+ * ```
  */
 declare function encryptWithWalletPublicKey(data: string | Blob, publicKey: string, platformAdapter: VanaPlatformAdapter): Promise<string>;
 /**
- * Decrypt data with a wallet's private key using platform-appropriate cryptography
+ * Decrypts data that was encrypted with the corresponding public key.
  *
- * @param encryptedData The encrypted data
- * @param privateKey The private key for decryption
- * @param platformAdapter - The platform adapter for crypto operations
- * @returns The decrypted data as string
+ * @remarks
+ * This function performs asymmetric decryption using the recipient's private key
+ * to decrypt data that was encrypted with the corresponding public key. It's the
+ * counterpart to `encryptWithWalletPublicKey` and is typically used by applications
+ * or servers to decrypt data that was shared with them by users.
+ *
+ * The function automatically handles platform-specific cryptographic operations
+ * and provides consistent behavior across browser and Node.js environments.
+ *
+ * @param encryptedData - The encrypted data string to decrypt
+ * @param privateKey - The private key corresponding to the public key used for encryption
+ * @param platformAdapter - The platform adapter providing cryptographic operations
+ * @returns Promise resolving to the decrypted data as a string
+ * @throws {Error} When decryption fails due to invalid key, corrupted data, or key mismatch
+ * @example
+ * ```typescript
+ * // Decrypt data received from a user (server-side)
+ * const encryptedUserData = "encrypted_string_from_user";
+ * const serverPrivateKey = process.env.SERVER_PRIVATE_KEY;
+ *
+ * const decrypted = await decryptWithWalletPrivateKey(
+ *   encryptedUserData,
+ *   serverPrivateKey,
+ *   platformAdapter
+ * );
+ *
+ * const userData = JSON.parse(decrypted);
+ * console.log('User data:', userData);
+ *
+ * // Handle decryption errors gracefully
+ * try {
+ *   const result = await decryptWithWalletPrivateKey(
+ *     encryptedData,
+ *     privateKey,
+ *     platformAdapter
+ *   );
+ * } catch (error) {
+ *   if (error.message.includes('invalid key')) {
+ *     console.error('Key mismatch - data not encrypted for this recipient');
+ *   } else {
+ *     console.error('Decryption failed:', error.message);
+ *   }
+ * }
+ * ```
  */
 declare function decryptWithWalletPrivateKey(encryptedData: string, privateKey: string, platformAdapter: VanaPlatformAdapter): Promise<string>;
 /**
@@ -31766,6 +32083,11 @@ declare function decryptBlobWithSignedKey(encryptedData: string | Blob, key: str
 /**
  * Format a bigint or BigNumber to a regular number
  *
+ * **Edge Cases:**
+ * - Values exceeding JavaScript's MAX_SAFE_INTEGER (2^53-1) lose precision
+ * - Negative values are supported
+ * - String values must be valid numeric strings or will return NaN
+ *
  * @param value BigInt, BigNumber or numeric string to convert
  * @returns Regular JavaScript number
  */
@@ -31773,6 +32095,12 @@ declare function formatNumber(value: bigint | string | number): number;
 /**
  * Format wei value to ETH with specified decimal places
  *
+ * **Edge Cases:**
+ * - Truncates (not rounds) to specified decimal places
+ * - Negative values are supported
+ * - Zero values return "0.0000" (based on decimals)
+ * - Very small values may display as "0.0000" due to truncation
+ *
  * @param wei Value in wei (as bigint, string, or number)
  * @param decimals Number of decimal places to display (default: 4)
  * @returns Formatted ETH value as string
@@ -31790,6 +32118,11 @@ declare function formatToken(amount: bigint | string | number, decimals?: number
 /**
  * Format an address for display (showing first 6 and last 4 characters)
  *
+ * **Edge Cases:**
+ * - Addresses shorter than 10 characters are returned unchanged
+ * - Works with both checksummed and lowercase addresses
+ * - Does not validate address format
+ *
  * @param address EVM address
  * @returns Shortened address string
  */
@@ -32117,6 +32450,12 @@ declare function convertIpfsUrl(url: string, gateway?: string): string;
 /**
  * Extract IPFS hash from various URL formats
  *
+ * **Edge Cases:**
+ * - Returns null for non-IPFS URLs or malformed hashes
+ * - Handles both CIDv0 (starts with Qm) and CIDv1 formats
+ * - Minimum 46 characters required for standalone hash detection
+ * - Gateway paths with subdirectories are not supported
+ *
  * @param url - The URL to extract hash from
  * @returns The IPFS hash or null if not found
  * @example
@@ -32124,6 +32463,8 @@ declare function convertIpfsUrl(url: string, gateway?: string): string;
  * extractIpfsHash("ipfs://QmHash123") // Returns: "QmHash123"
  * extractIpfsHash("https://gateway.pinata.cloud/ipfs/QmHash123") // Returns: "QmHash123"
  * extractIpfsHash("QmHash123456789012345678901234567890123456") // Returns: "QmHash123456789012345678901234567890123456"
+ * extractIpfsHash("https://example.com/file.json") // Returns: null (not IPFS)
+ * extractIpfsHash("ipfs://QmHash/subdirectory") // Returns: null (subdirectories not supported)
  * ```
  */
 declare function extractIpfsHash(url: string): string | null;
@@ -32144,6 +32485,13 @@ declare function convertIpfsUrlWithFallbacks(url: string): string[];
 /**
  * Fetch content from IPFS with automatic gateway fallbacks
  *
+ * **Edge Cases:**
+ * - Non-IPFS URLs are fetched directly without fallback
+ * - 10-second timeout per gateway attempt to prevent hanging
+ * - Rate-limited gateways (429) are skipped immediately
+ * - Exponential backoff between retries (1s, 2s, 3s, etc.)
+ * - AbortSignal in options is merged with timeout signal
+ *
  * @param url - The IPFS URL to fetch
  * @param options - Optional fetch options
  * @returns Promise resolving to Response object
@@ -32582,31 +32930,94 @@ declare class VanaBrowserImpl extends VanaCore {
 /**
  * Creates a new Vana SDK instance configured for browser environments.
  *
- * This function automatically provides the correct TypeScript types based on your configuration:
- * - With storage config: All methods including storage-dependent ones are available
- * - Without storage: Storage-dependent methods are not available at compile time
- *
- * @param config - The configuration object containing wallet client and optional storage settings
- * @returns A Vana SDK instance configured for browser use
+ * @remarks
+ * This is the primary entry point for browser applications using the Vana SDK. The function
+ * automatically detects your configuration type and provides compile-time type safety:
+ * - **With storage configured**: All methods including file upload/download are available
+ * - **Without storage**: Storage-dependent methods throw runtime errors and are excluded from TypeScript
+ *
+ * The SDK supports multiple wallet configurations (direct WalletClient or chain config),
+ * various storage providers (IPFS, Pinata, Google Drive), and gasless transactions via relayers.
+ * All operations are optimized for browser environments with proper bundle size optimization.
+ *
+ * @param config - Configuration object containing wallet, storage, and relayer settings
+ * @returns A fully configured Vana SDK instance for browser use
+ * @throws {InvalidConfigurationError} When configuration parameters are invalid or missing
  * @example
  * ```typescript
- * // With storage - all methods available
+ * import { Vana } from '@opendatalabs/vana-sdk/browser';
+ * import { createWalletClient, custom } from 'viem';
+ * import { IPFSStorage } from '@opendatalabs/vana-sdk/browser';
+ *
+ * // Complete setup with storage and wallet
+ * const walletClient = createWalletClient({
+ *   chain: mokshaTestnet,
+ *   transport: custom(window.ethereum)
+ * });
+ *
  * const vana = Vana({
  *   walletClient,
- *   storage: { providers: { ipfs: new IPFSStorage() }, defaultProvider: 'ipfs' }
+ *   storage: {
+ *     providers: {
+ *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),
+ *       pinata: new PinataStorage({ apiKey: process.env.PINATA_KEY })
+ *     },
+ *     defaultProvider: 'ipfs'
+ *   },
+ *   relayerCallbacks: {
+ *     async submitPermissionGrant(typedData, signature) {
+ *       const response = await fetch('/api/relay/grant', {
+ *         method: 'POST',
+ *         body: JSON.stringify({ typedData, signature })
+ *       });
+ *       return (await response.json()).transactionHash;
+ *     }
+ *   }
  * });
- * await vana.data.uploadFile(file); // ✅ Works - TypeScript knows storage is available
  *
- * // Without storage - storage methods unavailable at compile time
- * const vanaNoStorage = Vana({ walletClient });
- * // await vanaNoStorage.data.uploadFile(file); // ❌ TypeScript error
+ * // All operations now available
+ * const files = await vana.data.getUserFiles();
+ * const permissions = await vana.permissions.getUserPermissions();
+ * await vana.data.upload({ content: 'My data', filename: 'data.txt' });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal setup without storage (read-only operations)
+ * const vanaReadOnly = Vana({ walletClient });
+ *
+ * // These work without storage
+ * const files = await vanaReadOnly.data.getUserFiles();
+ * const permissions = await vanaReadOnly.permissions.getUserPermissions();
  *
- * // Runtime check still available
- * if (vanaNoStorage.isStorageEnabled()) {
- *   // TypeScript now knows storage methods are safe to use
- *   await vanaNoStorage.data.uploadFile(file); // ✅ Works
+ * // This would throw a runtime error
+ * // await vanaReadOnly.data.upload(params); // ❌ InvalidConfigurationError
+ *
+ * // Safe runtime check
+ * if (vanaReadOnly.isStorageEnabled()) {
+ *   await vanaReadOnly.data.upload(params); // ✅ TypeScript allows this
+ * } else {
+ *   console.log('Storage not configured - upload unavailable');
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Using chain configuration instead of wallet client
+ * const vana = Vana({
+ *   chainId: 14800, // Moksha testnet
+ *   account: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   rpcUrl: 'https://rpc.moksha.vana.org',
+ *   storage: {
+ *     providers: { ipfs: new IPFSStorage() },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link https://docs.vana.org/docs/sdk/getting-started | Getting Started Guide} for setup tutorials
+ * @see {@link VanaCore} for the underlying implementation details
+ * @category Core SDK
  */
 declare function Vana(config: VanaConfigWithStorage): VanaBrowserImpl & StorageRequiredMarker;
 declare function Vana(config: VanaConfig): VanaBrowserImpl;
@@ -32617,4 +33028,4 @@ declare function Vana(config: VanaConfig): VanaBrowserImpl;
  */
 type VanaInstance = VanaBrowserImpl;
 
-export { type $defs, type APIResponse, type AddRefinerParams, type AddRefinerResult, type AddSchemaParams, type AddSchemaResult, type AllKeys, ApiClient, type ApiClientConfig, type ApiResponse, AsyncQueue, type AsyncResult, type AuthenticationErrorResponse, type Awaited, type BaseConfig, type BaseConfigWithStorage, BaseController, type BatchServerInfoResult, type BatchUploadParams, type BatchUploadResult, type BlockRange, BlockchainError, type BlockchainErrorResponse, type Brand, BrowserPlatformAdapter, type Cache, type CacheConfig, CallbackStorage, type ChainConfig, type ChainConfigWithStorage, type CheckPermissionParams, CircuitBreaker, type ComputeErrorResponse, type ConditionalOptional, type ConfigValidationOptions, type ConfigValidationResult, type ContractAddresses, type ContractCall, type ContractDeployment, ContractFactory, type ContractInfo, type ContractMethodParams, type ContractMethodReturnType, ContractNotFoundError, type Controller, type ControllerContext, type CreateOperationParams, type CreateOperationRequest, type CreateOperationResponse, type CreateSchemaParams, type CreateSchemaResult, DEFAULT_ENCRYPTION_SEED, DEFAULT_IPFS_GATEWAY, DataController, type DataSchema, type DecryptionErrorResponse, type DeepPartial, type DeepReadonly, type DeleteFileParams, type DeleteFileResult, type DownloadFileParams, type DownloadFileResult, type EncryptedPermissionParams, type EncryptedUploadParams, type EncryptionInfo, type ErrorResponse, EventEmitter, type EventFilter, type EventLog, type Factory, type FileAccessErrorResponse, type FileAccessPermissions, type FileMetadata, type FileSharingConfig, type GasEstimate, type GenericRequest, type GenericResponse, type GenericTypedData, type GetFileParams, type GetOperationResponse, type GetUserFilesParams, type GetUserPermissionsOptions, type GetUserTrustedServersParams, type GetUserTrustedServersResult, GoogleDriveStorage, GrantExpiredError, type GrantFile, type GrantPermissionParams, GrantSchemaError, GrantValidationError, type GrantValidationErrorResponse, type GrantValidationOptions, type GrantValidationResult, type GrantedPermission, GranteeMismatchError, type HttpMethod, IPFS_GATEWAYS, type IdentityResponseModel, type InitPersonalServerParams, type InternalServerErrorResponse, InvalidConfigurationError, IpfsStorage, type MaybeArray, type MaybePromise, MemoryCache, type Middleware, MiddlewarePipeline, NetworkError, type NetworkInfo, type Nominal, type NonNullable, NonceError, type NotFoundErrorResponse, type Observable, type Observer, type OmitByType, type OnChainPermissionGrant, type OperationErrorResponse, OperationNotAllowedError, type OptionalKeys, type PaginatedTrustedServers, type PaginationParams, type PaginationResult, type PartialExcept, type PermissionAnalytics, type PermissionCheckResult, PermissionError, type PermissionEvent, type PermissionGrantDomain, type PermissionGrantMessage, type PermissionGrantTypedData, type PermissionInfo, type PermissionInputMessage, type PermissionOperation, type PermissionParams, type PermissionQueryResult, type PermissionStatus, PermissionsController, PersonalServerError, type PersonalServerIdentity, type PersonalServerModel, type PickByType, type PinataListResponse, type PinataPin, PinataStorage, type PinataUploadResponse, type Plugin, type PostRequestParams, type PromiseResult, ProtocolController, type QueryPermissionsParams, type RateLimitInfo, RateLimiter, type RateLimiterConfig, type Refiner, type RelayerCallbacks, type RelayerConfig, RelayerError, type RelayerErrorResponse, type RelayerMetrics, type RelayerQueueInfo, type RelayerRequestOptions, type RelayerStatus, type RelayerStorageResponse, type RelayerStoreParams, type RelayerSubmitParams, type RelayerTransactionResponse, type RelayerTransactionStatus, type RelayerWebhookConfig, type RelayerWebhookPayload, type ReplicateAPIResponse, type ReplicateStatus, type Repository, type RequestOptions, type RequireKeys, type RequiredExcept, type RetryConfig, RetryUtility, type RevokePermissionInput, type RevokePermissionParams, type RuntimeConfig, type Schema, SchemaValidationError, SchemaValidator, SerializationError, type Server, type components as ServerComponents, ServerController, type $defs as ServerDefs, type operations as ServerOperations, type paths as ServerPaths, type ServerTrustStatus, ServerUrlMismatchError, type webhooks as ServerWebhooks, type Service, SignatureError, type SimplifiedPermissionMessage, type StateMachine, type StatusInfo, type StorageCallbacks, type StorageConfig, type StorageDownloadOptions, StorageError, type StorageFile, type StorageListOptions, type StorageListResult, StorageManager, type StorageProvider, type StorageProviderConfig, type StorageRequiredMarker, type StorageUploadResult, type TimeRange, type TransactionOptions, type TransactionReceipt, type Transformer, type TrustServerInput, type TrustServerParams, type TrustServerTypedData, type TrustedServer, type TrustedServerInfo, type TrustedServerQueryMode, type TrustedServerQueryOptions, type UnencryptedUploadParams, type UntrustServerInput, type UntrustServerParams, type UntrustServerTypedData, type UpdateSchemaIdParams, type UpdateSchemaIdResult, type UploadEncryptedFileResult, type UploadFileParams, type UploadFileResult, type UploadParams, type UploadProgress, type UploadResult, type UserFile, UserRejectedRequestError, type ValidationErrorResponse, type ValidationResult, type Validator, Vana, VanaBrowserImpl, type VanaChain, type VanaChainConfig, type VanaChainId, type VanaConfig, type VanaConfigWithStorage, type VanaContract, type VanaContract as VanaContractAbi, type VanaContractInstance, type VanaContractName, VanaCore, VanaCoreFactory, VanaError, type VanaInstance, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createPlatformAdapterSafe, createValidatedGrant, decryptBlobWithSignedKey, decryptWithPrivateKey, decryptWithWalletPrivateKey, Vana as default, detectPlatform, encryptBlobWithSignedKey, encryptFileKey, encryptWithWalletPublicKey, extractIpfsHash, fetchAndValidateSchema, fetchWithFallbacks, formatEth, formatNumber, formatToken, generateEncryptionKey, generateEncryptionKeyPair, generatePGPKeyPair, getAbi, getAllChains, getChainConfig, getContractAddress, getContractController, getContractInfo, getEncryptionParameters, getGatewayUrls, getGrantFileHash, getGrantTimeRemaining, getPlatformCapabilities, hasStorageConfig, isAPIResponse, isChainConfig, isGrantExpired, isIpfsUrl, isPlatformSupported, isReplicateAPIResponse, isVanaChain, isVanaChainId, isWalletConfig, moksha, mokshaTestnet, type operations, parseReplicateOutput, type paths, retrieveAndValidateGrant, retrieveGrantFile, safeParseJSON, schemaValidator, shortenAddress, storeGrantFile, summarizeGrant, validateDataAgainstSchema, validateDataSchema, validateGrant, validateGrantExpiry, validateGrantFile, validateGranteeAccess, validateOperationAccess, vanaMainnet, type webhooks };
+export { type $defs, type APIResponse, type AddRefinerParams, type AddRefinerResult, type AddSchemaParams, type AddSchemaResult, type AllKeys, ApiClient, type ApiClientConfig, type ApiResponse, AsyncQueue, type AsyncResult, type AuthenticationErrorResponse, type Awaited, type BaseConfig, type BaseConfigWithStorage, BaseController, type BatchServerInfoResult, type BatchUploadParams, type BatchUploadResult, type BlockRange, BlockchainError, type BlockchainErrorResponse, type Brand, BrowserPlatformAdapter, type Cache, type CacheConfig, type ChainConfig, type ChainConfigWithStorage, type CheckPermissionParams, CircuitBreaker, type ComputeErrorResponse, type ConditionalOptional, type ConfigValidationOptions, type ConfigValidationResult, type ContractAddresses, type ContractCall, type ContractDeployment, ContractFactory, type ContractInfo, type ContractMethodParams, type ContractMethodReturnType, ContractNotFoundError, type Controller, type ControllerContext, type CreateOperationParams, type CreateOperationRequest, type CreateOperationResponse, type CreateSchemaParams, type CreateSchemaResult, DEFAULT_ENCRYPTION_SEED, DEFAULT_IPFS_GATEWAY, DataController, type DataSchema, type DecryptionErrorResponse, type DeepPartial, type DeepReadonly, type DeleteFileParams, type DeleteFileResult, type DownloadFileParams, type DownloadFileResult, type EncryptedPermissionParams, type EncryptedUploadParams, type EncryptionInfo, type ErrorResponse, EventEmitter, type EventFilter, type EventLog, type Factory, type FileAccessErrorResponse, type FileAccessPermissions, type FileMetadata, type FileSharingConfig, type GasEstimate, type GenericRequest, type GenericResponse, type GenericTypedData, type GetFileParams, type GetOperationResponse, type GetUserFilesParams, type GetUserPermissionsOptions, type GetUserTrustedServersParams, type GetUserTrustedServersResult, GoogleDriveStorage, GrantExpiredError, type GrantFile, type GrantPermissionParams, GrantSchemaError, GrantValidationError, type GrantValidationErrorResponse, type GrantValidationOptions, type GrantValidationResult, type GrantedPermission, GranteeMismatchError, type HttpMethod, IPFS_GATEWAYS, type IdentityResponseModel, type InitPersonalServerParams, type InternalServerErrorResponse, InvalidConfigurationError, IpfsStorage, type MaybeArray, type MaybePromise, MemoryCache, type Middleware, MiddlewarePipeline, NetworkError, type NetworkInfo, type Nominal, type NonNullable, NonceError, type NotFoundErrorResponse, type Observable, type Observer, type OmitByType, type OnChainPermissionGrant, type OperationErrorResponse, OperationNotAllowedError, type OptionalKeys, type PaginatedTrustedServers, type PaginationParams, type PaginationResult, type PartialExcept, type PermissionAnalytics, type PermissionCheckResult, PermissionError, type PermissionEvent, type PermissionGrantDomain, type PermissionGrantMessage, type PermissionGrantTypedData, type PermissionInfo, type PermissionInputMessage, type PermissionOperation, type PermissionParams, type PermissionQueryResult, type PermissionStatus, PermissionsController, PersonalServerError, type PersonalServerIdentity, type PersonalServerModel, type PickByType, type PinataListResponse, type PinataPin, PinataStorage, type PinataUploadResponse, type Plugin, type PostRequestParams, type PromiseResult, ProtocolController, type QueryPermissionsParams, type RateLimitInfo, RateLimiter, type RateLimiterConfig, type Refiner, type RelayerCallbacks, type RelayerConfig, RelayerError, type RelayerErrorResponse, type RelayerMetrics, type RelayerQueueInfo, type RelayerRequestOptions, type RelayerStatus, type RelayerStorageResponse, type RelayerStoreParams, type RelayerSubmitParams, type RelayerTransactionResponse, type RelayerTransactionStatus, type RelayerWebhookConfig, type RelayerWebhookPayload, type ReplicateAPIResponse, type ReplicateStatus, type Repository, type RequestOptions, type RequireKeys, type RequiredExcept, type RetryConfig, RetryUtility, type RevokePermissionInput, type RevokePermissionParams, type RuntimeConfig, type Schema, SchemaValidationError, SchemaValidator, SerializationError, type Server, type components as ServerComponents, ServerController, type $defs as ServerDefs, type operations as ServerOperations, type paths as ServerPaths, ServerProxyStorage, type ServerTrustStatus, ServerUrlMismatchError, type webhooks as ServerWebhooks, type Service, SignatureError, type SimplifiedPermissionMessage, type StateMachine, type StatusInfo, type StorageConfig, StorageError, type StorageFile, type StorageListOptions, StorageManager, type StorageProvider, type StorageProviderConfig, type StorageRequiredMarker, type StorageUploadResult, type TimeRange, type TransactionOptions, type TransactionReceipt, type Transformer, type TrustServerInput, type TrustServerParams, type TrustServerTypedData, type TrustedServer, type TrustedServerInfo, type TrustedServerQueryMode, type TrustedServerQueryOptions, type UnencryptedUploadParams, type UntrustServerInput, type UntrustServerParams, type UntrustServerTypedData, type UpdateSchemaIdParams, type UpdateSchemaIdResult, type UploadEncryptedFileResult, type UploadFileParams, type UploadFileResult, type UploadParams, type UploadProgress, type UploadResult, type UserFile, UserRejectedRequestError, type ValidationErrorResponse, type ValidationResult, type Validator, Vana, VanaBrowserImpl, type VanaChain, type VanaChainConfig, type VanaChainId, type VanaConfig, type VanaConfigWithStorage, type VanaContract, type VanaContract as VanaContractAbi, type VanaContractInstance, type VanaContractName, VanaCore, VanaCoreFactory, VanaError, type VanaInstance, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createPlatformAdapterSafe, createValidatedGrant, decryptBlobWithSignedKey, decryptWithPrivateKey, decryptWithWalletPrivateKey, Vana as default, detectPlatform, encryptBlobWithSignedKey, encryptFileKey, encryptWithWalletPublicKey, extractIpfsHash, fetchAndValidateSchema, fetchWithFallbacks, formatEth, formatNumber, formatToken, generateEncryptionKey, generateEncryptionKeyPair, generatePGPKeyPair, getAbi, getAllChains, getChainConfig, getContractAddress, getContractController, getContractInfo, getEncryptionParameters, getGatewayUrls, getGrantFileHash, getGrantTimeRemaining, getPlatformCapabilities, hasStorageConfig, isAPIResponse, isChainConfig, isGrantExpired, isIpfsUrl, isPlatformSupported, isReplicateAPIResponse, isVanaChain, isVanaChainId, isWalletConfig, moksha, mokshaTestnet, type operations, parseReplicateOutput, type paths, retrieveAndValidateGrant, retrieveGrantFile, safeParseJSON, schemaValidator, shortenAddress, storeGrantFile, summarizeGrant, validateDataAgainstSchema, validateDataSchema, validateGrant, validateGrantExpiry, validateGrantFile, validateGranteeAccess, validateOperationAccess, vanaMainnet, type webhooks };