@opendatalabs/vana-sdk 0.1.0-alpha.cb72de2 → 0.1.0-alpha.d44f792

package/dist/index.node.d.ts

@@ -805,12 +805,16 @@ 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. */
+     *   Custom names allowed for custom provider implementations.
+     */
     providers: Record<string, StorageProvider>;
-    /** Default provider name to use when none specified.
-     *   Must match a key in the providers map. Falls back to first provider if not 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;
 }
 /**
@@ -878,7 +882,21 @@ interface RelayerCallbacks {
     /**
      * Submit a file addition for relay
      *
-     * @deprecated Use submitFileAdditionComplete for full support.
+     * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.
+     * Will be removed in v3.0.0.
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old:
+     * await submitFileAddition(url, userAddress);
+     *
+     * // New:
+     * await submitFileAdditionComplete({
+     *   url,
+     *   userAddress,
+     *   permissions: [] // Optional
+     * });
+     * ```
      * @param url - The file URL to register
      * @param userAddress - The user's address
      * @returns Promise resolving to object with fileId and transactionHash
@@ -890,7 +908,21 @@ interface RelayerCallbacks {
     /**
      * Submit a file addition with permissions for relay
      *
-     * @deprecated Use submitFileAdditionComplete for full support.
+     * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.
+     * Will be removed in v3.0.0.
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old:
+     * await submitFileAdditionWithPermissions(url, userAddress, permissions);
+     *
+     * // New:
+     * await submitFileAdditionComplete({
+     *   url,
+     *   userAddress,
+     *   permissions
+     * });
+     * ```
      * @param url - The file URL to register
      * @param userAddress - The user's address
      * @param permissions - Array of encrypted permissions
@@ -1064,9 +1096,11 @@ 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. */
+     *   See StorageConfig for provider selection guidance.
+     */
     storage?: StorageConfig;
     /**
      * Optional subgraph URL for querying user files and permissions.
@@ -1141,17 +1175,23 @@ 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. */
+     *   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. */
+     *   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. */
+     *   Required for write operations; read-only operations work without account.
+     */
     account?: Account;
 }
 /**
@@ -27442,7 +27482,7 @@ declare class CallbackStorage implements StorageProvider {
  * const result2 = await storage.upload(fileBlob, 'myfile.json', 'pinata');
  * ```
  * @category Storage
- * @see {@link [URL_PLACEHOLDER] | Storage Providers Guide} for configuration details
+ * @see {@link https://docs.vana.com/developer/vana-sdk-documentation/core-modules/storage-providers | Storage Providers Guide} for configuration details
  */
 declare class StorageManager {
     private providers;
@@ -27847,7 +27887,7 @@ interface ControllerContext$1 {
  * const permissions = await vana.permissions.getUserPermissionGrantsOnChain();
  * ```
  * @category Permissions
- * @see {@link [URL_PLACEHOLDER] | Vana Permissions System} for conceptual overview
+ * @see {@link https://docs.vana.com/developer/permissions | Vana Permissions System} for conceptual overview
  */
 declare class PermissionsController {
     private readonly context;
@@ -27922,6 +27962,8 @@ declare class PermissionsController {
      * until the returned `confirm()` function is called.
      * @param params - The permission grant parameters
      * @returns A promise resolving to a preview object and confirm function
+     * @throws {SerializationError} When grant parameters are invalid or cannot be serialized
+     * @throws {BlockchainError} When grant validation fails or preparation encounters an error
      * @example
      * ```typescript
      * const { preview, confirm } = await vana.permissions.prepareGrant({
@@ -28045,7 +28087,7 @@ declare class PermissionsController {
      * use `submitPermissionRevoke()` instead.
      *
      * @param params - Parameters for revoking the permission
-     * @param params.permissionId - Permission identifier as bigint for contract compatibility.
+     * @param params.permissionId - Permission identifier (accepts bigint, number, or string).
      *   Obtain from permission grants via `getUserPermissionGrantsOnChain()`.
      * @returns Promise resolving to revocation data from PermissionRevoked event
      * @throws {BlockchainError} When revocation fails or event parsing fails
@@ -28087,12 +28129,20 @@ declare class PermissionsController {
      *
      * @param params - Parameters for revoking the permission
      * @returns Promise resolving to transaction hash
+     * @throws {BlockchainError} When chain ID is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {RelayerError} When gasless submission fails
+     * @throws {PermissionError} When revocation fails for any other reason
      */
     revokeWithSignature(params: RevokePermissionParams): Promise<Hash>;
     /**
      * Retrieves the user's current nonce from the DataPermissions contract.
      *
      * @returns Promise resolving to the user's current nonce value
+     * @throws {Error} When wallet account is not available
+     * @throws {Error} When chain ID is not available
+     * @throws {NonceError} When reading nonce from contract fails
      */
     private getUserNonce;
     /**
@@ -28168,6 +28218,7 @@ declare class PermissionsController {
      *
      * @param fileId - The file ID to query permissions for
      * @returns Promise resolving to array of permission IDs
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getFilePermissionIds(fileId: bigint): Promise<bigint[]>;
     /**
@@ -28175,6 +28226,7 @@ declare class PermissionsController {
      *
      * @param permissionId - The permission ID to query files for
      * @returns Promise resolving to array of file IDs
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getPermissionFileIds(permissionId: bigint): Promise<bigint[]>;
     /**
@@ -28182,6 +28234,7 @@ declare class PermissionsController {
      *
      * @param permissionId - The permission ID to check
      * @returns Promise resolving to boolean indicating if permission is active
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     isActivePermission(permissionId: bigint): Promise<boolean>;
     /**
@@ -28189,6 +28242,7 @@ declare class PermissionsController {
      *
      * @param permissionId - The permission ID to query
      * @returns Promise resolving to permission info
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getPermissionInfo(permissionId: bigint): Promise<PermissionInfo>;
     /**
@@ -28203,7 +28257,12 @@ declare class PermissionsController {
      * Trusts a server for data processing.
      *
      * @param params - Parameters for trusting the server
+     * @param params.serverId - The server's Ethereum address
+     * @param params.serverUrl - The server's URL endpoint
      * @returns Promise resolving to transaction hash
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @throws {BlockchainError} When chain ID is unavailable or transaction fails
+     * @throws {Error} When wallet account is not available
      * @example
      * ```typescript
      * // Trust a server by providing its ID and URL
@@ -28224,6 +28283,12 @@ declare class PermissionsController {
      *
      * @param params - Parameters for trusting the server
      * @returns Promise resolving to transaction hash
+     * @throws {BlockchainError} When chain ID is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {RelayerError} When gasless submission fails
+     * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
+     * @throws {BlockchainError} When trust operation fails for any other reason
      */
     trustServerWithSignature(params: TrustServerParams): Promise<Hash>;
     /**
@@ -28237,14 +28302,25 @@ declare class PermissionsController {
      * Untrusts a server.
      *
      * @param params - Parameters for untrusting the server
+     * @param params.serverId - The server's Ethereum address to untrust
      * @returns Promise resolving to transaction hash
+     * @throws {Error} When wallet account is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @throws {BlockchainError} When untrust transaction fails
      */
     untrustServer(params: UntrustServerParams): Promise<Hash>;
     /**
      * Untrusts a server using a signature (gasless transaction).
      *
      * @param params - Parameters for untrusting the server
+     * @param params.serverId - The server's Ethereum address to untrust
      * @returns Promise resolving to transaction hash
+     * @throws {Error} When wallet account is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {RelayerError} When gasless submission fails
+     * @throws {BlockchainError} When untrust transaction fails
      */
     untrustServerWithSignature(params: UntrustServerParams): Promise<Hash>;
     /**
@@ -28252,6 +28328,7 @@ declare class PermissionsController {
      *
      * @param userAddress - Optional user address (defaults to current user)
      * @returns Promise resolving to array of trusted server addresses
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getTrustedServers(userAddress?: Address): Promise<Address[]>;
     /**
@@ -28259,6 +28336,7 @@ declare class PermissionsController {
      *
      * @param serverId - Server address
      * @returns Promise resolving to server information
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getServerInfo(serverId: Address): Promise<Server>;
     /**
@@ -28266,6 +28344,7 @@ declare class PermissionsController {
      *
      * @param userAddress - Optional user address (defaults to current user)
      * @returns Promise resolving to the number of trusted servers
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getTrustedServersCount(userAddress?: Address): Promise<number>;
     /**
@@ -28273,6 +28352,7 @@ declare class PermissionsController {
      *
      * @param options - Query options including pagination parameters
      * @returns Promise resolving to paginated trusted servers
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getTrustedServersPaginated(options?: TrustedServerQueryOptions): Promise<PaginatedTrustedServers>;
     /**
@@ -28280,6 +28360,7 @@ declare class PermissionsController {
      *
      * @param options - Query options
      * @returns Promise resolving to array of trusted server info
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getTrustedServersWithInfo(options?: TrustedServerQueryOptions): Promise<TrustedServerInfo[]>;
     /**
@@ -28287,6 +28368,7 @@ declare class PermissionsController {
      *
      * @param serverIds - Array of server IDs to query
      * @returns Promise resolving to batch result with successes and failures
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
      */
     getServerInfoBatch(serverIds: Address[]): Promise<BatchServerInfoResult>;
     /**
@@ -29706,30 +29788,147 @@ interface RelayerWebhookPayload {
 /**
  * Makes all properties in T optional except for those in K
  *
+ * @remarks
+ * This utility type is useful when you want to create a variant of an interface
+ * where most properties are optional, but specific properties remain required.
+ * Commonly used for update operations where only certain fields must be provided.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * // Only 'id' is required, all other properties are optional
+ * type UserUpdate = PartialExcept<User, 'id'>;
+ *
+ * const update: UserUpdate = {
+ *   id: '123', // Required
+ *   name: 'John' // Optional
+ *   // email and age are also optional
+ * };
+ * ```
  * @category Reference
  */
 type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;
 /**
  * Makes all properties in T required except for those in K
  *
+ * @remarks
+ * This utility type is useful when you want to create a variant of an interface
+ * where most properties are required, but specific properties remain optional.
+ * Commonly used for creation operations where most fields are mandatory.
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   apiUrl: string;
+ *   timeout?: number;
+ *   retries?: number;
+ *   debug?: boolean;
+ * }
+ *
+ * // All properties required except 'debug'
+ * type StrictConfig = RequiredExcept<Config, 'debug'>;
+ *
+ * const config: StrictConfig = {
+ *   apiUrl: 'https://api.vana.com', // Required
+ *   timeout: 5000, // Required (was optional, now required)
+ *   retries: 3, // Required (was optional, now required)
+ *   // debug remains optional
+ * };
+ * ```
  * @category Reference
  */
 type RequiredExcept<T, K extends keyof T> = Required<T> & Partial<Pick<T, K>>;
 /**
  * Extracts the return type of a promise
  *
+ * @remarks
+ * This utility type unwraps the type contained within a Promise.
+ * If the type is not a Promise, it returns the type unchanged.
+ * Note: TypeScript 4.5+ includes a built-in Awaited type with similar functionality.
+ *
+ * @example
+ * ```typescript
+ * type AsyncString = Promise<string>;
+ * type SyncString = string;
+ *
+ * // Extracts 'string' from Promise<string>
+ * type Result1 = Awaited<AsyncString>; // string
+ *
+ * // Returns 'string' unchanged since it's not a Promise
+ * type Result2 = Awaited<SyncString>; // string
+ *
+ * // Practical usage with async functions
+ * async function fetchUser(): Promise<{ id: string; name: string }> {
+ *   // ...
+ * }
+ *
+ * type User = Awaited<ReturnType<typeof fetchUser>>; // { id: string; name: string }
+ * ```
  * @category Reference
  */
 type Awaited<T> = T extends Promise<infer U> ? U : T;
 /**
  * Creates a type that accepts either T or a Promise<T>
  *
+ * @remarks
+ * This utility type is useful for functions that can work with both
+ * synchronous and asynchronous values. It allows flexible APIs that
+ * can accept immediate values or promises that resolve to those values.
+ *
+ * @example
+ * ```typescript
+ * // Function that accepts either a value or a promise of that value
+ * async function processData(data: MaybePromise<string>): Promise<string> {
+ *   // await works on both promises and regular values
+ *   const resolved = await data;
+ *   return resolved.toUpperCase();
+ * }
+ *
+ * // Both calls are valid:
+ * processData('hello'); // Synchronous value
+ * processData(Promise.resolve('world')); // Asynchronous value
+ *
+ * // Common use case in SDK callbacks
+ * interface StorageProvider {
+ *   // Provider can implement sync or async file reading
+ *   read(path: string): MaybePromise<Buffer>;
+ * }
+ * ```
  * @category Reference
  */
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Creates a type that accepts either T or an array of T
  *
+ * @remarks
+ * This utility type is useful for functions that can accept either a single
+ * value or an array of values, providing a more flexible API. The implementation
+ * can normalize the input to always work with arrays internally.
+ *
+ * @example
+ * ```typescript
+ * // Function that accepts either a single ID or multiple IDs
+ * function deleteItems(ids: MaybeArray<string>): void {
+ *   // Normalize to array
+ *   const idArray = Array.isArray(ids) ? ids : [ids];
+ *   idArray.forEach(id => console.log(`Deleting ${id}`));
+ * }
+ *
+ * // Both calls are valid:
+ * deleteItems('item-1'); // Single item
+ * deleteItems(['item-1', 'item-2', 'item-3']); // Multiple items
+ *
+ * // Common use case in permissions
+ * interface GrantPermissionsParams {
+ *   permissions: MaybeArray<Permission>;
+ * }
+ * ```
  * @category Reference
  */
 type MaybeArray<T> = T | T[];
@@ -29763,8 +29962,35 @@ interface PaginationParams {
     cursor?: string;
 }
 /**
- * Pagination result
+ * Pagination result containing items and metadata for navigating large datasets.
+ *
+ * @remarks
+ * This interface standardizes paginated responses across the SDK, providing
+ * consistent metadata for implementing pagination UI components and handling
+ * multi-page data fetching. Supports both offset-based and cursor-based pagination.
  *
+ * @example
+ * ```typescript
+ * // Fetching paginated user files
+ * async function getAllUserFiles(userAddress: string): Promise<File[]> {
+ *   const allFiles: File[] = [];
+ *   let cursor: string | undefined;
+ *
+ *   do {
+ *     const result: PaginationResult<File> = await vana.data.getUserFiles({
+ *       owner: userAddress,
+ *       pagination: { limit: 50, cursor }
+ *     });
+ *
+ *     allFiles.push(...result.items);
+ *     cursor = result.nextCursor;
+ *
+ *     console.log(`Fetched ${result.count} of ${result.total} files`);
+ *   } while (result.hasMore);
+ *
+ *   return allFiles;
+ * }
+ * ```
  * @category Reference
  */
 interface PaginationResult<T> {
@@ -29780,8 +30006,33 @@ interface PaginationResult<T> {
     nextCursor?: string;
 }
 /**
- * Block range parameters
+ * Block range parameters for filtering blockchain events and transactions.
+ *
+ * @remarks
+ * Used to specify a range of blocks when querying blockchain data.
+ * Both parameters are optional - omitting fromBlock starts from genesis,
+ * omitting toBlock goes to the latest block. Be cautious with large ranges
+ * as they may result in heavy RPC loads or timeouts.
  *
+ * @example
+ * ```typescript
+ * // Get events from the last 1000 blocks
+ * const currentBlock = await vana.protocol.getBlockNumber();
+ * const events = await vana.protocol.getEvents({
+ *   blockRange: {
+ *     fromBlock: currentBlock - 1000n,
+ *     toBlock: currentBlock
+ *   }
+ * });
+ *
+ * // Get all historical events (use with caution)
+ * const allEvents = await vana.protocol.getEvents({
+ *   blockRange: {
+ *     fromBlock: 0n
+ *     // toBlock omitted = up to latest
+ *   }
+ * });
+ * ```
  * @category Reference
  */
 interface BlockRange {
@@ -29791,8 +30042,34 @@ interface BlockRange {
     toBlock?: bigint;
 }
 /**
- * Transaction options
+ * Transaction options for customizing blockchain transaction parameters.
  *
+ * @remarks
+ * Provides fine-grained control over transaction execution. Supports both
+ * legacy (gasPrice) and EIP-1559 (maxFeePerGas) transaction types. When
+ * not specified, the SDK will use appropriate defaults based on network
+ * conditions. Use these options to optimize for speed or cost.
+ *
+ * @example
+ * ```typescript
+ * // High priority transaction with EIP-1559 pricing
+ * await vana.permissions.grant(params, {
+ *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei
+ *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip
+ * });
+ *
+ * // Legacy transaction with specific gas limit
+ * await vana.data.registerFile(params, {
+ *   gasLimit: 500000n,
+ *   gasPrice: 50n * 10n ** 9n // 50 gwei
+ * });
+ *
+ * // Send ETH with the transaction
+ * await vana.protocol.execute(params, {
+ *   value: 10n ** 18n, // 1 ETH
+ *   gasLimit: 21000n
+ * });
+ * ```
  * @category Reference
  */
 interface TransactionOptions {
@@ -29810,8 +30087,37 @@ interface TransactionOptions {
     value?: bigint;
 }
 /**
- * Transaction receipt with additional metadata
+ * Transaction receipt with additional metadata for tracking transaction results.
+ *
+ * @remarks
+ * Provides comprehensive information about executed transactions including
+ * gas usage, success status, and emitted events. Use the logs array to
+ * decode events emitted by smart contracts during transaction execution.
+ * The receipt is available after a transaction is mined and included in a block.
+ *
+ * @example
+ * ```typescript
+ * // Execute transaction and wait for receipt
+ * const receipt = await vana.permissions.grant({
+ *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   dataId: 123
+ * });
  *
+ * // Check transaction success
+ * if (receipt.status === 'success') {
+ *   console.log(`Gas used: ${receipt.gasUsed}`);
+ *   console.log(`Block: ${receipt.blockNumber}`);
+ *
+ *   // Decode events from logs
+ *   receipt.logs.forEach(log => {
+ *     if (log.topics[0] === PERMISSION_GRANTED_TOPIC) {
+ *       console.log('Permission granted event detected');
+ *     }
+ *   });
+ * } else {
+ *   console.error('Transaction reverted');
+ * }
+ * ```
  * @category Reference
  */
 interface TransactionReceipt {
@@ -29835,8 +30141,45 @@ interface TransactionReceipt {
     }>;
 }
 /**
- * Response wrapper for API results
+ * Response wrapper for API results providing consistent error handling.
+ *
+ * @remarks
+ * Standardizes API responses across the SDK, making it easy to handle
+ * both successful and failed requests. The generic type parameter T
+ * represents the expected data type for successful responses. Check
+ * the success flag before accessing data to ensure type safety.
  *
+ * @example
+ * ```typescript
+ * // Handling API responses
+ * async function fetchUserData(userId: string): Promise<User | null> {
+ *   const response: ApiResponse<User> = await api.getUser(userId);
+ *
+ *   if (response.success) {
+ *     console.log('User fetched:', response.data.name);
+ *     // Access metadata if available
+ *     if (response.metadata?.cached) {
+ *       console.log('Data was cached');
+ *     }
+ *     return response.data;
+ *   } else {
+ *     console.error('Failed to fetch user:', response.error);
+ *     return null;
+ *   }
+ * }
+ *
+ * // Type-safe error handling
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * const result: ApiResponse<UserData> = await api.call('/users/123');
+ * if (result.success) {
+ *   // TypeScript knows result.data is UserData here
+ *   console.log(result.data.name);
+ * }
+ * ```
  * @category Reference
  */
 interface ApiResponse<T> {
@@ -29850,8 +30193,35 @@ interface ApiResponse<T> {
     metadata?: Record<string, unknown>;
 }
 /**
- * Cache configuration
+ * Cache configuration for optimizing repeated data fetches.
+ *
+ * @remarks
+ * Configures in-memory caching behavior to reduce redundant API calls and
+ * improve performance. The cache automatically evicts expired entries based
+ * on TTL and removes least-recently-used items when maxSize is reached.
+ * Use appropriate TTL values based on your data freshness requirements.
  *
+ * @example
+ * ```typescript
+ * // Short-lived cache for frequently changing data
+ * const userCache: CacheConfig = {
+ *   ttl: 60000, // 1 minute
+ *   maxSize: 100, // Store up to 100 users
+ *   prefix: 'user:' // Cache keys like 'user:123'
+ * };
+ *
+ * // Long-lived cache for stable data
+ * const schemaCache: CacheConfig = {
+ *   ttl: 3600000, // 1 hour
+ *   maxSize: 1000, // Store up to 1000 schemas
+ *   prefix: 'schema:'
+ * };
+ *
+ * // Disable caching by setting TTL to 0
+ * const noCache: CacheConfig = {
+ *   ttl: 0 // No caching
+ * };
+ * ```
  * @category Reference
  */
 interface CacheConfig {
@@ -29863,8 +30233,51 @@ interface CacheConfig {
     prefix?: string;
 }
 /**
- * Validation result
+ * Validation result for data integrity checks and schema validation.
+ *
+ * @remarks
+ * Provides detailed feedback about validation outcomes, distinguishing between
+ * errors (which prevent processing) and warnings (which indicate potential issues).
+ * Used throughout the SDK for validating permissions, file formats, schemas,
+ * and API parameters before operations.
+ *
+ * @example
+ * ```typescript
+ * // Validating user input
+ * function validateFileUpload(file: File): ValidationResult {
+ *   const errors: string[] = [];
+ *   const warnings: string[] = [];
+ *
+ *   // Check file size
+ *   if (file.size > 100 * 1024 * 1024) {
+ *     errors.push('File size exceeds 100MB limit');
+ *   } else if (file.size > 50 * 1024 * 1024) {
+ *     warnings.push('Large file may take time to upload');
+ *   }
+ *
+ *   // Check file type
+ *   if (!file.type.startsWith('image/')) {
+ *     errors.push('Only image files are allowed');
+ *   }
+ *
+ *   return {
+ *     valid: errors.length === 0,
+ *     errors,
+ *     warnings
+ *   };
+ * }
  *
+ * // Using validation result
+ * const result = validateFileUpload(file);
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors.join(', '));
+ * } else {
+ *   if (result.warnings.length > 0) {
+ *     console.warn('Warnings:', result.warnings.join(', '));
+ *   }
+ *   // Proceed with upload
+ * }
+ * ```
  * @category Reference
  */
 interface ValidationResult {
@@ -29876,8 +30289,41 @@ interface ValidationResult {
     warnings: string[];
 }
 /**
- * Status information
+ * Status information for health checks and service monitoring.
+ *
+ * @remarks
+ * Used to report the health status of various SDK components including
+ * storage providers, RPC connections, and personal servers. The details
+ * field can contain provider-specific information for debugging.
+ * Timestamps use Unix epoch milliseconds.
+ *
+ * @example
+ * ```typescript
+ * // Checking storage provider health
+ * const status: StatusInfo = await storage.getStatus();
+ *
+ * if (!status.healthy) {
+ *   console.error(`Storage unhealthy: ${status.message}`);
+ *   // Check how long the issue has persisted
+ *   const downtime = Date.now() - status.lastCheck;
+ *   if (downtime > 300000) { // 5 minutes
+ *     // Switch to backup provider
+ *   }
+ * }
  *
+ * // Detailed status with custom fields
+ * const serverStatus: StatusInfo = {
+ *   healthy: true,
+ *   message: 'All systems operational',
+ *   lastCheck: Date.now(),
+ *   details: {
+ *     uptime: 3600000, // 1 hour
+ *     requestsServed: 1234,
+ *     avgResponseTime: 145, // ms
+ *     activeConnections: 23
+ *   }
+ * };
+ * ```
  * @category Reference
  */
 interface StatusInfo {
@@ -29891,8 +30337,34 @@ interface StatusInfo {
     details?: Record<string, unknown>;
 }
 /**
- * Rate limit information
+ * Rate limit information for API throttling and quota management.
+ *
+ * @remarks
+ * Provides visibility into rate limiting status to help applications
+ * implement appropriate backoff strategies. Rate limits protect services
+ * from overload and ensure fair resource usage. Use this information
+ * to pace requests and avoid hitting limits.
+ *
+ * @example
+ * ```typescript
+ * // Check rate limit before making requests
+ * const rateLimit: RateLimitInfo = await api.getRateLimit();
+ *
+ * console.log(`Requests: ${rateLimit.requests}/${rateLimit.limit}`);
+ * console.log(`Resets in: ${rateLimit.resetTime} seconds`);
  *
+ * // Implement backoff if approaching limit
+ * if (rateLimit.requests >= rateLimit.limit * 0.9) {
+ *   console.warn('Approaching rate limit, slowing down');
+ *   await new Promise(resolve =>
+ *     setTimeout(resolve, rateLimit.resetTime * 1000)
+ *   );
+ * }
+ *
+ * // Calculate requests per second allowed
+ * const rps = rateLimit.limit / rateLimit.window;
+ * console.log(`Max ${rps} requests per second allowed`);
+ * ```
  * @category Reference
  */
 interface RateLimitInfo {
@@ -29906,8 +30378,40 @@ interface RateLimitInfo {
     resetTime: number;
 }
 /**
- * File upload progress
+ * File upload progress tracking for user feedback and monitoring.
+ *
+ * @remarks
+ * Provides real-time progress information during file uploads, enabling
+ * applications to show progress bars and estimated completion times.
+ * The speed calculation is typically based on a rolling average to
+ * smooth out network fluctuations.
  *
+ * @example
+ * ```typescript
+ * // Upload with progress tracking
+ * await vana.data.upload(file, {
+ *   onProgress: (progress: UploadProgress) => {
+ *     // Update progress bar
+ *     progressBar.style.width = `${progress.percentage}%`;
+ *
+ *     // Show upload speed
+ *     const speedMBps = (progress.speed / 1024 / 1024).toFixed(2);
+ *     speedDisplay.textContent = `${speedMBps} MB/s`;
+ *
+ *     // Show time remaining
+ *     const minutes = Math.floor(progress.estimatedTimeRemaining / 60);
+ *     const seconds = progress.estimatedTimeRemaining % 60;
+ *     timeDisplay.textContent = `${minutes}:${seconds.toString().padStart(2, '0')}`;
+ *
+ *     // Log progress milestones
+ *     if (progress.percentage === 25 ||
+ *         progress.percentage === 50 ||
+ *         progress.percentage === 75) {
+ *       console.log(`Upload ${progress.percentage}% complete`);
+ *     }
+ *   }
+ * });
+ * ```
  * @category Reference
  */
 interface UploadProgress {
@@ -29923,8 +30427,41 @@ interface UploadProgress {
     estimatedTimeRemaining: number;
 }
 /**
- * Network information
+ * Network information for blockchain connectivity and monitoring.
+ *
+ * @remarks
+ * Provides comprehensive details about the connected blockchain network,
+ * including configuration URLs and real-time status. Use this information
+ * to verify network connectivity, display network details to users, and
+ * construct explorer links for transactions.
+ *
+ * @example
+ * ```typescript
+ * // Get current network info
+ * const network: NetworkInfo = await vana.protocol.getNetworkInfo();
+ *
+ * console.log(`Connected to: ${network.chainName} (ID: ${network.chainId})`);
+ * console.log(`Current block: ${network.currentBlock}`);
+ *
+ * // Check network health
+ * if (network.status !== 'healthy') {
+ *   console.warn(`Network ${network.status}: consider switching RPC`);
+ * }
+ *
+ * // Generate explorer link for transaction
+ * function getExplorerLink(txHash: string): string {
+ *   if (!network.explorerUrl) {
+ *     return `Transaction: ${txHash}`;
+ *   }
+ *   return `${network.explorerUrl}/tx/${txHash}`;
+ * }
  *
+ * // Verify expected network
+ * const EXPECTED_CHAIN_ID = 1337; // Vana testnet
+ * if (network.chainId !== EXPECTED_CHAIN_ID) {
+ *   throw new Error(`Wrong network! Expected ${EXPECTED_CHAIN_ID}, got ${network.chainId}`);
+ * }
+ * ```
  * @category Reference
  */
 interface NetworkInfo {
@@ -29942,8 +30479,39 @@ interface NetworkInfo {
     status: "healthy" | "degraded" | "down";
 }
 /**
- * Gas estimate information
+ * Gas estimate information for transaction cost prediction.
+ *
+ * @remarks
+ * Provides detailed gas pricing estimates to help users understand transaction
+ * costs before execution. Supports both legacy (gasPrice) and EIP-1559
+ * (maxFeePerGas) pricing models. The estimatedCost is calculated based on
+ * current network conditions and may vary by the time of actual execution.
+ *
+ * @example
+ * ```typescript
+ * // Get gas estimate before transaction
+ * const estimate: GasEstimate = await vana.permissions.estimateGas({
+ *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   dataId: 123
+ * });
+ *
+ * // Convert to human-readable format
+ * const costInEth = Number(estimate.estimatedCost) / 1e18;
+ * console.log(`Estimated cost: ${costInEth.toFixed(6)} ETH`);
  *
+ * // Check if user has sufficient balance
+ * const balance = await vana.protocol.getBalance(userAddress);
+ * if (balance < estimate.estimatedCost) {
+ *   throw new Error(`Insufficient balance. Need ${costInEth} ETH`);
+ * }
+ *
+ * // Use estimate for transaction with buffer
+ * await vana.permissions.grant(params, {
+ *   gasLimit: estimate.gasLimit * 110n / 100n, // 10% buffer
+ *   maxFeePerGas: estimate.maxFeePerGas,
+ *   maxPriorityFeePerGas: estimate.maxPriorityFeePerGas
+ * });
+ * ```
  * @category Reference
  */
 interface GasEstimate {
@@ -30474,7 +31042,7 @@ interface GrantPermissionParams {
  * const decryptedData = await vana.data.decryptFile(files[0]);
  * ```
  * @category Data Management
- * @see {@link [URL_PLACEHOLDER] | Vana Data Registry Documentation} for conceptual overview
+ * @see {@link https://docs.vana.com/developer/data-registry | Vana Data Registry Documentation} for conceptual overview
  */
 declare class DataController {
     private readonly context;
@@ -30495,23 +31063,32 @@ declare class DataController {
      * - Grants file decryption permissions to specified accounts
      * - Registers the file on the blockchain
      *
+     * **TypeScript Overloads:**
+     * This method has three overloads to ensure type safety:
+     * 1. `EncryptedUploadParams` - When `encrypt: true` (default), permissions require publicKey
+     * 2. `UnencryptedUploadParams` - When `encrypt: false`, permissions are optional
+     * 3. `UploadParams` - General signature for runtime determination
+     *
      * IMPORTANT: The permissions parameter only grants decryption access to the file.
      * To grant operation permissions (like "llm_inference"), use vana.permissions.grant()
      * after uploading. This separation ensures clear distinction between:
-     * - File permissions: Who can decrypt and read the encrypted file
-     * - Operation permissions: What operations can be performed on the data
+     * - File permissions: Who can decrypt and read the encrypted file (handled here)
+     * - Operation permissions: What operations can be performed on the data (handled separately)
      *
      * @param params - Upload parameters including content, filename, schema, and permissions
-     * @param params.permissions.publicKey - The recipient's public key for encryption.
+     * @param params.permissions[].account - The recipient's wallet address that will access the data.
+     * @param params.permissions[].publicKey - The recipient's public key for encryption (hex string with 0x prefix).
      *   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.
+     * @param params.schemaId - Optional schema ID for data validation. Get available schemas from `vana.schemas.list()`.
+     * @param params.owner - Optional owner address if uploading on behalf of another user (requires delegation).
      * @returns Promise resolving to upload results with file ID and transaction hash
-     * @throws {Error} When 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.
+     * @throws {Error} When storage manager is not configured - "Storage manager not configured. Please provide storage providers in VanaConfig."
+     * @throws {Error} When no wallet addresses available - "No addresses available in wallet client"
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When relay callback doesn't support required features - "The configured relay callback does not support schemas or permissions"
+     * @throws {Error} When schema fetch fails - "Failed to fetch schema definition: {status}"
+     * @throws {SchemaValidationError} When data doesn't match schema - includes specific validation errors
+     * @throws {Error} General upload failures - "Upload failed: {specific error message}"
      * @example
      * ```typescript
      * // Basic file upload
@@ -30546,12 +31123,12 @@ declare class DataController {
      * // });
      *
      * // 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
-     *   // No permissions needed for public unencrypted data
-     * });
+     * } as const);  // 'as const' ensures TypeScript infers encrypt: false literally
      *
      * // Upload on behalf of another user (delegation)
      * const result = await vana.data.upload({
@@ -30559,10 +31136,8 @@ declare class DataController {
      *   filename: "delegated.txt",
      *   owner: "0x5678...", // Different from connected wallet
      *   permissions: [{
-     *     grantee: "0x1234...",
-     *     operation: "process",
-     *     parameters: { type: "analysis" },
-     *     publicKey: "0x04..."
+     *     account: "0x1234...",   // Address that can decrypt
+     *     publicKey: "0x04..."    // Their public key for encryption
      *   }]
      * });
      * ```
@@ -30592,9 +31167,14 @@ declare class DataController {
      * @param file - The user file to decrypt (typically from getUserFiles)
      * @param encryptionSeed - Optional custom encryption seed (defaults to Vana standard)
      * @returns Promise resolving to the decrypted file content as a Blob
-     * @throws {Error} When the wallet is not connected
-     * @throws {Error} When fetching the encrypted content fails
-     * @throws {Error} When decryption fails (wrong key or corrupted data)
+     * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
+     * @throws {Error} "Network error: Cannot access the file URL" - When file URL is inaccessible (CORS, server down)
+     * @throws {Error} "File not found: The encrypted file is no longer available" - When file returns 404
+     * @throws {Error} "Access denied" - When file returns 403 (no permission)
+     * @throws {Error} "File is empty or could not be retrieved" - When file has no content
+     * @throws {Error} "Invalid file format: This file doesn't appear to be encrypted with the Vana protocol" - When file is not properly encrypted
+     * @throws {Error} "Wrong encryption key" - When decryption fails due to incorrect key/seed
+     * @throws {Error} "Failed to decrypt file: {error}" - General decryption failures
      * @example
      * ```typescript
      * // Basic file decryption
@@ -30628,11 +31208,20 @@ declare class DataController {
      * This method queries the Vana subgraph to find files directly owned by the user.
      * It efficiently handles large datasets by using the File entity's owner field
      * and returns complete file metadata without additional contract calls.
+     *
+     * **Deduplication Behavior:**
+     * The method automatically deduplicates files by ID, keeping only the latest version
+     * (highest timestamp) when duplicate file IDs are found. This handles cases where
+     * the subgraph may contain multiple entries for the same file due to re-indexing
+     * or blockchain reorganizations.
      * @param params - The query parameters object
      * @param params.owner - The wallet address of the file owner to query
      * @param params.subgraphUrl - Optional subgraph URL to override the default endpoint
-     * @returns A Promise that resolves to an array of UserFile objects with metadata
-     * @throws {Error} When the subgraph is unavailable or returns invalid data
+     * @returns A Promise that resolves to an array of UserFile objects with metadata, sorted by latest timestamp first
+     * @throws {Error} When subgraphUrl is not provided and not configured - "subgraphUrl is required"
+     * @throws {Error} When subgraph request fails - "Subgraph request failed: {status} {statusText}"
+     * @throws {Error} When subgraph returns errors - "Subgraph errors: {error messages}"
+     * @throws {Error} When JSON parsing fails - "Failed to fetch user files from subgraph: {error}"
      * @example
      * ```typescript
      * // Query files for a specific user
@@ -30755,6 +31344,9 @@ declare class DataController {
      *
      * @param fileId - The file ID to look up
      * @returns Promise resolving to UserFile object
+     * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+     * @throws {Error} "File not found" - When file ID doesn't exist or returns empty data
+     * @throws {Error} "Failed to fetch file {fileId}: {error}" - General contract read failures
      * @example
      * ```typescript
      * try {
@@ -30779,7 +31371,21 @@ declare class DataController {
     /**
      * Uploads an encrypted file to storage and registers it on the blockchain.
      *
-     * @deprecated Use vana.data.upload() instead for the high-level API with automatic encryption
+     * @deprecated Since v2.0.0 - Use vana.data.upload() instead for the high-level API with automatic encryption
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old way (deprecated):
+     * const encrypted = await encryptBlob(data, key);
+     * const result = await vana.data.uploadEncryptedFile(encrypted, filename);
+     *
+     * // New way:
+     * const result = await vana.data.upload({
+     *   content: data,
+     *   filename: filename,
+     *   encrypt: true  // Handles encryption automatically
+     * });
+     * ```
      * @param encryptedFile - The encrypted file blob to upload
      * @param filename - Optional filename for the upload
      * @param providerName - Optional storage provider to use
@@ -30794,7 +31400,22 @@ declare class DataController {
     /**
      * Uploads an encrypted file to storage and registers it on the blockchain with a schema.
      *
-     * @deprecated Use vana.data.upload() instead for the high-level API with automatic encryption and schema validation
+     * @deprecated Since v2.0.0 - Use vana.data.upload() instead for the high-level API with automatic encryption and schema validation
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old way (deprecated):
+     * const encrypted = await encryptBlob(data, key);
+     * const result = await vana.data.uploadEncryptedFileWithSchema(encrypted, schemaId, filename);
+     *
+     * // New way:
+     * const result = await vana.data.upload({
+     *   content: data,
+     *   filename: filename,
+     *   schemaId: schemaId,  // Automatic validation
+     *   encrypt: true
+     * });
+     * ```
      * @param encryptedFile - The encrypted file blob to upload
      * @param schemaId - The schema ID to associate with the file
      * @param filename - Optional filename for the upload
@@ -30866,7 +31487,24 @@ declare class DataController {
     /**
      * Adds a new schema to the DataRefinerRegistry.
      *
-     * @deprecated Use vana.schemas.create() instead for the high-level API with automatic IPFS upload
+     * @deprecated Since v2.0.0 - Use vana.schemas.create() instead for the high-level API with automatic IPFS upload
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old way (deprecated):
+     * const result = await vana.data.addSchema({
+     *   name: "UserProfile",
+     *   type: "JSON",
+     *   definitionUrl: "ipfs://..."
+     * });
+     *
+     * // New way:
+     * const result = await vana.schemas.create({
+     *   name: "UserProfile",
+     *   type: "JSON",
+     *   definition: schemaObject  // Automatically uploads to IPFS
+     * });
+     * ```
      * @param params - Schema parameters including name, type, and definition URL
      * @returns Promise resolving to the new schema ID and transaction hash
      */
@@ -30874,7 +31512,16 @@ declare class DataController {
     /**
      * Retrieves a schema by its ID.
      *
-     * @deprecated Use vana.schemas.get() instead
+     * @deprecated Since v2.0.0 - Use vana.schemas.get() instead
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old way (deprecated):
+     * const schema = await vana.data.getSchema(schemaId);
+     *
+     * // New way:
+     * const schema = await vana.schemas.get(schemaId);
+     * ```
      * @param schemaId - The schema ID to retrieve
      * @returns Promise resolving to the schema information
      */
@@ -30882,7 +31529,16 @@ declare class DataController {
     /**
      * Gets the total number of schemas in the registry.
      *
-     * @deprecated Use vana.schemas.count() instead
+     * @deprecated Since v2.0.0 - Use vana.schemas.count() instead
+     *
+     * Migration guide:
+     * ```typescript
+     * // Old way (deprecated):
+     * const count = await vana.data.getSchemasCount();
+     *
+     * // New way:
+     * const count = await vana.schemas.count();
+     * ```
      * @returns Promise resolving to the total schema count
      */
     getSchemasCount(): Promise<number>;
@@ -30953,8 +31609,11 @@ declare class DataController {
      *
      * @param fileId - The ID of the file to add permissions for
      * @param account - The address of the account to grant permission to
-     * @param publicKey - The public key to encrypt the user's encryption key with
+     * @param publicKey - The public key to encrypt the user's encryption key with (hex string with 0x prefix)
      * @returns Promise resolving to permission data from PermissionGranted event
+     * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
+     * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+     * @throws {Error} "Failed to add permission to file: {error}" - When transaction fails or user doesn't own file
      * @example
      * ```typescript
      * const result = await vana.data.addPermissionToFile(fileId, account, publicKey);
@@ -31012,7 +31671,9 @@ declare class DataController {
      *
      * @param url - The URL to fetch content from
      * @returns Promise resolving to the fetched content as a Blob
-     * @throws {Error} When the fetch fails or returns a non-ok response
+     * @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
@@ -31043,7 +31704,10 @@ declare class DataController {
      * @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} When all gateways fail to fetch the content
+     * @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
@@ -31200,7 +31864,7 @@ declare class DataController {
  * const result = await vana.server.getOperation(response.id);
  * ```
  * @category Server Management
- * @see {@link [URL_PLACEHOLDER] | Vana Personal Servers} for conceptual overview
+ * @see {@link https://docs.vana.com/developer/personal-servers | Vana Personal Servers} for conceptual overview
  */
 declare class ServerController {
     private readonly context;
@@ -31483,7 +32147,7 @@ declare function clearContractCache(contract?: VanaContract, chainId?: number):
  * const fileCount = await contract.read.filesCount();
  * ```
  * @category Advanced
- * @see {@link [URL_PLACEHOLDER] | Vana Protocol Contracts} for contract specifications
+ * @see {@link https://docs.vana.com/developer/protocol/contracts | Vana Protocol Contracts} for contract specifications
  */
 declare class ProtocolController {
     private readonly context;
@@ -31562,12 +32226,14 @@ declare class ProtocolController {
      * Gets the current chain ID from the wallet client.
      *
      * @returns The chain ID
+     * @throws {Error} When chain ID is not available from wallet client
      */
     getChainId(): number;
     /**
      * Gets the current chain name from the wallet client.
      *
      * @returns The chain name
+     * @throws {Error} When chain name is not available from wallet client
      */
     getChainName(): string;
 }
@@ -32410,6 +33076,10 @@ declare function decryptBlobWithSignedKey(encryptedData: string | Blob, key: str
 /**
  * Format a bigint or BigNumber to a regular number
  *
+ * @remarks
+ * This function converts blockchain-specific large number types to standard JavaScript
+ * numbers. Use with caution for values that may exceed safe integer range.
+ *
  * **Edge Cases:**
  * - Values exceeding JavaScript's MAX_SAFE_INTEGER (2^53-1) lose precision
  * - Negative values are supported
@@ -32417,11 +33087,26 @@ declare function decryptBlobWithSignedKey(encryptedData: string | Blob, key: str
  *
  * @param value BigInt, BigNumber or numeric string to convert
  * @returns Regular JavaScript number
+ * @example
+ * ```typescript
+ * formatNumber(1000000000000000000n) // Returns: 1000000000000000000
+ * formatNumber("123456789") // Returns: 123456789
+ * formatNumber(-100n) // Returns: -100
+ *
+ * // Precision loss example:
+ * const bigValue = 9007199254740993n; // MAX_SAFE_INTEGER + 2
+ * formatNumber(bigValue) // Returns: 9007199254740992 (lost precision)
+ * ```
  */
 declare function formatNumber(value: bigint | string | number): number;
 /**
  * Format wei value to ETH with specified decimal places
  *
+ * @remarks
+ * Converts wei (smallest ETH unit) to human-readable ETH format.
+ * 1 ETH = 10^18 wei. The function truncates rather than rounds
+ * to ensure predictable display in financial contexts.
+ *
  * **Edge Cases:**
  * - Truncates (not rounds) to specified decimal places
  * - Negative values are supported
@@ -32431,20 +33116,57 @@ declare function formatNumber(value: bigint | string | number): number;
  * @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
+ * @example
+ * ```typescript
+ * // Standard conversions
+ * formatEth(1000000000000000000n) // Returns: "1.0000"
+ * formatEth(1500000000000000000n, 2) // Returns: "1.50"
+ * formatEth("2000000000000000000") // Returns: "2.0000"
+ *
+ * // Edge cases
+ * formatEth(1000000000000000n) // Returns: "0.0010" (0.001 ETH)
+ * formatEth(100000000000000n) // Returns: "0.0001"
+ * formatEth(10000000000000n) // Returns: "0.0000" (truncated)
+ * formatEth(-1000000000000000000n) // Returns: "-1.000"
+ * ```
  */
 declare function formatEth(wei: bigint | string | number, decimals?: number): string;
 /**
  * Format a token amount based on its decimals
  *
+ * @remarks
+ * Generic token formatter that handles any ERC20-style token with
+ * configurable decimal places. Most tokens use 18 decimals like ETH,
+ * but some use different values (e.g., USDC uses 6).
+ *
  * @param amount Raw token amount
  * @param decimals Token decimals (default: 18)
  * @param displayDecimals Decimals to show in formatted output (default: 4)
  * @returns Formatted token amount as string
+ * @example
+ * ```typescript
+ * // 18 decimal token (like ETH)
+ * formatToken(1000000000000000000n) // Returns: "1.0000"
+ * formatToken(1500000000000000000n, 18, 2) // Returns: "1.50"
+ *
+ * // 6 decimal token (like USDC)
+ * formatToken(1000000n, 6) // Returns: "1.0000"
+ * formatToken(1500000n, 6, 2) // Returns: "1.50"
+ *
+ * // Whole numbers
+ * formatToken(5000000000000000000n) // Returns: "5"
+ * formatToken(5123456789000000000n, 18, 6) // Returns: "5.123456"
+ * ```
  */
 declare function formatToken(amount: bigint | string | number, decimals?: number, displayDecimals?: number): string;
 /**
  * Format an address for display (showing first 6 and last 4 characters)
  *
+ * @remarks
+ * Creates a human-readable abbreviated version of Ethereum addresses
+ * for UI display. Preserves enough characters to maintain uniqueness
+ * while saving screen space. Does not validate address format.
+ *
  * **Edge Cases:**
  * - Addresses shorter than 10 characters are returned unchanged
  * - Works with both checksummed and lowercase addresses
@@ -32452,22 +33174,80 @@ declare function formatToken(amount: bigint | string | number, decimals?: number
  *
  * @param address EVM address
  * @returns Shortened address string
+ * @example
+ * ```typescript
+ * // Standard addresses
+ * shortenAddress("0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36")
+ * // Returns: "0x742d...Bd36"
+ *
+ * // Checksummed address
+ * shortenAddress("0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36")
+ * // Returns: "0x742d...Bd36"
+ *
+ * // Edge cases
+ * shortenAddress("0x123") // Returns: "0x123" (too short)
+ * shortenAddress("") // Returns: ""
+ * shortenAddress("not-an-address") // Returns: "not-an...ress"
+ * ```
  */
 declare function shortenAddress(address: string): string;
 
 /**
  * Creates a grant file structure from permission parameters.
  *
+ * @remarks
+ * This function constructs the JSON structure that represents a permission grant
+ * in the Vana protocol. The grant file contains all necessary information for
+ * a grantee to perform operations on behalf of the grantor.
+ *
  * @param params - The permission parameters to create the grant file from
  * @returns The constructed grant file object
+ * @example
+ * ```typescript
+ * const grantFile = createGrantFile({
+ *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   operation: 'llm_inference',
+ *   parameters: {
+ *     model: 'gpt-4',
+ *     maxTokens: 1000
+ *   },
+ *   expiresAt: Date.now() + 86400000 // 24 hours
+ * });
+ *
+ * console.log(grantFile);
+ * // {
+ * //   grantee: '0x742d...',
+ * //   operation: 'llm_inference',
+ * //   parameters: { model: 'gpt-4', maxTokens: 1000 },
+ * //   expires: 1234567890
+ * // }
+ * ```
  */
 declare function createGrantFile(params: GrantPermissionParams$1): GrantFile;
 /**
  * Stores a grant file in IPFS via the relayer service.
  *
+ * @remarks
+ * This function uploads the grant file to IPFS through the relayer's upload endpoint.
+ * The returned URL can be stored on-chain as part of the permission grant, allowing
+ * anyone to retrieve the detailed permission parameters later.
+ *
  * @param grantFile - The grant file to store
  * @param relayerUrl - URL of the relayer service
  * @returns Promise resolving to the IPFS URL
+ * @throws {NetworkError} When the upload fails or relayer is unavailable
+ * @example
+ * ```typescript
+ * const grantFile = createGrantFile(params);
+ *
+ * try {
+ *   const ipfsUrl = await storeGrantFile(grantFile, 'https://relayer.vana.com');
+ *   console.log(`Grant file stored at: ${ipfsUrl}`);
+ *   // ipfsUrl: "ipfs://QmHash123..."
+ * } catch (error) {
+ *   console.error('Failed to store grant file:', error);
+ * }
+ * ```
  */
 declare function storeGrantFile(grantFile: GrantFile, relayerUrl: string): Promise<string>;
 /**
@@ -32513,15 +33293,80 @@ declare function retrieveGrantFile(grantUrl: string, _relayerUrl?: string): Prom
  * Generates a content hash for a grant file.
  * This can be used for integrity verification.
  *
+ * @remarks
+ * Creates a deterministic keccak256 hash of the grant file by first sorting
+ * all object keys recursively to ensure consistent hashing regardless of
+ * property order. This hash can be used to verify grant file integrity
+ * or as a unique identifier.
+ *
  * @param grantFile - The grant file to generate a hash for
  * @returns The keccak256 hash of the grant file as a hex string
+ * @throws {SerializationError} When the grant file cannot be serialized
+ * @example
+ * ```typescript
+ * const grantFile = {
+ *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   operation: 'read',
+ *   parameters: { version: '1.0', mode: 'full' }
+ * };
+ *
+ * const hash = getGrantFileHash(grantFile);
+ * console.log(`Grant file hash: ${hash}`);
+ * // "0x1234567890abcdef..."
+ *
+ * // Same grant file with different property order produces same hash
+ * const grantFile2 = {
+ *   operation: 'read',
+ *   parameters: { mode: 'full', version: '1.0' },
+ *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+ * };
+ *
+ * const hash2 = getGrantFileHash(grantFile2);
+ * console.log(hash === hash2); // true
+ * ```
  */
 declare function getGrantFileHash(grantFile: GrantFile): string;
 /**
  * Validates that a grant file has the required structure.
  *
+ * @remarks
+ * Performs runtime validation to ensure data conforms to the GrantFile interface.
+ * Checks for required fields (grantee, operation, parameters) and validates their
+ * types and formats. This is a type guard function that enables TypeScript to
+ * narrow the type when it returns true.
+ *
  * @param data - The data to validate as a grant file
  * @returns True if the data is a valid grant file, false otherwise
+ * @example
+ * ```typescript
+ * const unknownData = await fetch(url).then(r => r.json());
+ *
+ * if (validateGrantFile(unknownData)) {
+ *   // TypeScript now knows unknownData is a GrantFile
+ *   console.log(`Grant for operation: ${unknownData.operation}`);
+ *   console.log(`Grantee: ${unknownData.grantee}`);
+ * } else {
+ *   throw new Error('Invalid grant file format');
+ * }
+ *
+ * // Validation examples:
+ * validateGrantFile({
+ *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   operation: 'read',
+ *   parameters: {}
+ * }); // true
+ *
+ * validateGrantFile({
+ *   grantee: 'invalid-address',
+ *   operation: 'read',
+ *   parameters: {}
+ * }); // false (invalid address format)
+ *
+ * validateGrantFile({
+ *   operation: 'read',
+ *   parameters: {}
+ * }); // false (missing grantee)
+ * ```
  */
 declare function validateGrantFile(data: unknown): data is GrantFile;
 
@@ -32829,32 +33674,118 @@ declare function fetchWithFallbacks(url: string, options?: RequestInit): Promise
 /**
  * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.
  *
+ * @remarks
+ * This cache significantly improves UX by avoiding repeated wallet signature prompts
+ * for identical operations. It's particularly useful for operations that may be
+ * retried or called multiple times with the same parameters.
+ *
  * Features:
  * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)
  * - Configurable TTL (default 2 hours)
  * - Automatic cleanup of expired entries
  * - Cache keys based on wallet address + message hash
+ *
+ * @example
+ * ```typescript
+ * // Check cache before requesting signature
+ * const cached = SignatureCache.get(cache, walletAddress, messageHash);
+ * if (cached) {
+ *   return cached;
+ * }
+ *
+ * // Request signature and cache it
+ * const signature = await wallet.signTypedData(typedData);
+ * SignatureCache.set(cache, walletAddress, messageHash, signature);
+ * ```
+ * @category Utilities
  */
 declare class SignatureCache {
     private static readonly PREFIX;
     private static readonly DEFAULT_TTL_HOURS;
     /**
      * Get a cached signature if it exists and hasn't expired
+     *
+     * @param cache - Platform cache adapter instance
+     * @param walletAddress - Wallet address that created the signature
+     * @param messageHash - Hash of the message that was signed
+     * @returns The cached signature if valid, null if expired or not found
+     * @example
+     * ```typescript
+     * const messageHash = SignatureCache.hashMessage(typedData);
+     * const cached = SignatureCache.get(cache, '0x123...', messageHash);
+     * if (cached) {
+     *   console.log('Using cached signature:', cached);
+     * }
+     * ```
      */
     static get(cache: VanaCacheAdapter, walletAddress: string, messageHash: string): Hash | null;
     /**
-     * Store a signature in the cache
+     * Store a signature in the cache with configurable TTL
+     *
+     * @param cache - Platform cache adapter instance
+     * @param walletAddress - Wallet address that created the signature
+     * @param messageHash - Hash of the message that was signed
+     * @param signature - The signature to cache
+     * @param ttlHours - Time to live in hours (default: 2)
+     * @example
+     * ```typescript
+     * const signature = await wallet.signTypedData(typedData);
+     * const messageHash = SignatureCache.hashMessage(typedData);
+     *
+     * // Cache for default 2 hours
+     * SignatureCache.set(cache, walletAddress, messageHash, signature);
+     *
+     * // Cache for 24 hours
+     * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
+     * ```
      */
     static set(cache: VanaCacheAdapter, walletAddress: string, messageHash: string, signature: Hash, ttlHours?: number): void;
     /**
      * Clear all cached signatures (useful for testing or explicit cleanup)
+     *
+     * @param cache - Platform cache adapter instance
+     * @example
+     * ```typescript
+     * // Clear all signatures when user logs out
+     * SignatureCache.clear(cache);
+     *
+     * // Clear before running tests
+     * beforeEach(() => {
+     *   SignatureCache.clear(cache);
+     * });
+     * ```
      */
     static clear(cache: VanaCacheAdapter): void;
     private static getCacheKey;
+    /**
+     * Generate a deterministic hash of a message object for cache key generation
+     *
+     * @remarks
+     * Creates a consistent hash from complex objects including EIP-712 typed data.
+     * Handles BigInt serialization and produces a 32-character hash that balances
+     * uniqueness with key length constraints.
+     *
+     * @param message - The message object to hash (typically EIP-712 typed data)
+     * @returns A 32-character hash string suitable for cache keys
+     * @example
+     * ```typescript
+     * const typedData = {
+     *   domain: { name: 'Vana', version: '1' },
+     *   message: { nonce: 123n, grant: '...' }
+     * };
+     *
+     * const hash = SignatureCache.hashMessage(typedData);
+     * // Returns something like: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
+     * ```
+     */
     static hashMessage(message: object): string;
     /**
      * Custom JSON replacer that converts BigInt values to strings for serialization
      * This ensures deterministic cache key generation for EIP-712 typed data
+     *
+     * @param _key - The object key being serialized (unused)
+     * @param value - The value to serialize
+     * @returns The serialized value
      */
     private static bigIntReplacer;
 }
@@ -32868,7 +33799,7 @@ declare class SignatureCache {
  * @param ttlHours - Cache TTL in hours (default 2)
  * @returns The signature (cached or newly generated)
  */
-declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: any, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;
+declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: Record<string, unknown>, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;
 
 declare const CONTRACT_ADDRESSES: Record<number, Record<string, string>>;
 /**