@opendatalabs/vana-sdk 0.1.0-alpha.b390e7f → 0.1.0-alpha.d6bebb0

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>;
@@ -246,6 +247,8 @@ interface GrantPermissionParams$1 {
     nonce?: bigint;
     /** Optional expiration time for the permission */
     expiresAt?: number;
+    /** Optional grantee ID to use instead of resolving from address */
+    granteeId?: number;
 }
 /**
  * Parameters for revoking a previously granted data access permission.
@@ -359,6 +362,8 @@ interface PermissionInputMessage {
     grant: string;
     /** File IDs */
     fileIds: bigint[];
+    /** Grantee ID */
+    granteeId: bigint;
 }
 /**
  * Contract RevokePermissionInput structure
@@ -785,6 +790,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 +809,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,9 +915,10 @@ interface RelayerCallbacks {
      *
      * @param params - Complete parameters for file addition
      * @param params.url - The file URL to register
-     * @param params.userAddress - The user's address
+     * @param params.userAddress - The user's address (defaults to connected wallet if not specified)
      * @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: {
@@ -914,6 +929,7 @@ interface RelayerCallbacks {
             key: string;
         }>;
         schemaId: number;
+        ownerAddress?: Address;
     }) => Promise<{
         fileId: number;
         transactionHash: Hash;
@@ -1052,18 +1068,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']
      */
@@ -1125,11 +1145,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;
 }
 /**
@@ -1387,7 +1413,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;
@@ -1483,6 +1510,8 @@ 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).
@@ -1518,15 +1547,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;
 }
 /**
@@ -1594,11 +1624,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;
 }
 /**
@@ -2681,6 +2711,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
@@ -2693,6 +2732,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
@@ -2719,6 +2763,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
@@ -2805,6 +2854,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 {
     /**
@@ -2868,15 +2933,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 },
  * });
  *
@@ -2887,7 +2964,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
@@ -3055,6 +3132,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
@@ -3093,6 +3172,7 @@ declare class PermissionsController {
      * @param params.grantUrl - URL where the grant details are stored
      * @param params.serializedParameters - Serialized parameters for the operation
      * @param params.nonce - Unique number to prevent replay attacks
+     * @param params.granteeId - The ID of the grantee from the registry
      * @returns Promise resolving to the typed data structure
      */
     private composePermissionGrantMessage;
@@ -3364,9 +3444,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
@@ -5408,6 +5499,12 @@ interface GrantPermissionParams {
     parameters: Record<string, unknown>;
     /** Optional pre-stored grant URL to avoid duplicate IPFS storage */
     grantUrl?: string;
+    /** Optional nonce for the permission */
+    nonce?: bigint;
+    /** Optional expiration time for the permission */
+    expiresAt?: number;
+    /** Optional grantee ID to use instead of resolving from address */
+    granteeId?: number;
 }
 
 /**
@@ -5424,13 +5521,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({
@@ -5466,10 +5573,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
@@ -5493,7 +5606,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
      *   }]
      * });
      *
@@ -5508,6 +5621,19 @@ 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>;
@@ -6087,23 +6213,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
@@ -6112,6 +6248,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.
@@ -6120,10 +6289,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({
@@ -6163,6 +6335,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.
@@ -31058,19 +31274,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
@@ -31101,7 +31324,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
@@ -31218,19 +31442,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
  */
@@ -31403,30 +31651,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>;
@@ -31474,7 +31778,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);
@@ -31492,20 +31821,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;
@@ -31513,6 +31914,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;
@@ -31520,12 +31925,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;
@@ -31584,21 +31997,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>;
 /**
@@ -31749,6 +32234,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
  */
@@ -31756,6 +32246,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
@@ -31773,6 +32269,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
  */
@@ -32100,6 +32601,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
@@ -32107,6 +32614,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;
@@ -32127,6 +32636,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
@@ -32565,31 +33081,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;