@opendatalabs/vana-sdk 0.1.0-alpha.761813a → 0.1.0-alpha.7e4db82

package/dist/index.browser.d.ts

@@ -158,37 +158,56 @@ declare class StorageError extends Error {
 }
 
 /**
- * Represents a granted permission from the DataPermissions contract.
+ * Represents on-chain permission grant data without expensive off-chain resolution.
  *
- * This interface describes the structure of permissions that have been granted
- * on-chain, including all the metadata and parameters associated with the permission.
- * Used when querying user permissions or checking access rights.
+ * This interface contains only the fast, on-chain data that can be retrieved
+ * efficiently from the subgraph without making individual IPFS or contract calls.
+ * Use this for fast permission listing in UIs, then call `retrieveGrantFile()`
+ * on specific grants when detailed data is needed.
  *
  * @category Permissions
+ * @example
+ * ```typescript
+ * // Fast: Get all on-chain permission data
+ * const grants = await vana.permissions.getUserPermissionGrantsOnChain();
+ *
+ * // Lazy: Resolve detailed data for specific permission when needed
+ * const grantFile = await retrieveGrantFile(grants[0].grantUrl);
+ * console.log('Operation:', grantFile.operation);
+ * ```
  */
-interface GrantedPermission {
+interface OnChainPermissionGrant {
     /** Unique identifier for the permission */
     id: bigint;
-    /** Array of file IDs included in the permission */
-    files: number[];
-    /** Type of operation permitted (e.g., "llm_inference") */
-    operation?: string;
-    /** The grant URL containing all permission details */
-    grant: string;
-    /** The parameters associated with the permission */
-    parameters?: Record<string, unknown>;
-    /** Optional nonce used when granting the permission */
-    nonce?: number;
-    /** Optional block number when permission was granted */
-    grantedAt?: number;
+    /** The grant URL containing detailed permission parameters (IPFS link) */
+    grantUrl: string;
+    /** Cryptographic signature that authorized this permission */
+    grantSignature: string;
+    /** Hash of the grant file content for integrity verification */
+    grantHash: string;
+    /** Nonce used when granting the permission */
+    nonce: bigint;
+    /** Block number when permission was granted */
+    addedAtBlock: bigint;
+    /** Timestamp when permission was added */
+    addedAtTimestamp: bigint;
+    /** Transaction hash of the grant transaction */
+    transactionHash: string;
     /** Address that granted the permission */
     grantor: Address;
-    /** Address that received the permission */
-    grantee: Address;
-    /** Whether the permission is still active */
+    /** Whether the permission is still active (not revoked) */
     active: boolean;
-    /** Expiration timestamp if applicable */
-    expiresAt?: number;
+}
+/**
+ * Options for retrieving user permissions
+ *
+ * @category Permissions
+ */
+interface GetUserPermissionsOptions {
+    /** Maximum number of permissions to retrieve */
+    limit?: number;
+    /** Custom subgraph URL to use for querying */
+    subgraphUrl?: string;
 }
 /**
  * Parameters for granting data access permission to an application.
@@ -201,7 +220,7 @@ interface GrantedPermission {
  * @example
  * ```typescript
  * const params: GrantPermissionParams = {
- *   to: '0x1234...', // Application address
+ *   grantee: '0x1234...', // Application address
  *   operation: 'llm_inference',
  *   files: [1, 2, 3], // File IDs to grant access to
  *   parameters: {
@@ -214,7 +233,7 @@ interface GrantedPermission {
  */
 interface GrantPermissionParams$1 {
     /** The on-chain identity of the application */
-    to: Address;
+    grantee: Address;
     /** The class of computation, e.g., "llm_inference" */
     operation: string;
     /** Array of file IDs to grant permission for */
@@ -227,6 +246,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.
@@ -340,6 +361,8 @@ interface PermissionInputMessage {
     grant: string;
     /** File IDs */
     fileIds: bigint[];
+    /** Grantee ID */
+    granteeId: bigint;
 }
 /**
  * Contract RevokePermissionInput structure
@@ -493,6 +516,41 @@ interface QueryPermissionsParams {
     /** Offset for pagination */
     offset?: number;
 }
+/**
+ * Granted permission details
+ *
+ * @category Permissions
+ */
+interface GrantedPermission {
+    /** Unique identifier for the permission */
+    id: bigint;
+    /** Array of file IDs that the permission applies to */
+    files: number[];
+    /** The type of operation being granted permission for */
+    operation: string;
+    /** Grant file reference (IPFS hash or URL) */
+    grant: string;
+    /** Address of the application granted permission */
+    grantee: Address;
+    /** Address of the user who granted permission */
+    grantor: Address;
+    /** Custom parameters for the operation */
+    parameters: Record<string, unknown>;
+    /** Whether the permission is still active */
+    active: boolean;
+    /** Data status for the permission */
+    dataStatus?: string;
+    /** Nonce used for the permission */
+    nonce?: number;
+    /** Timestamp when permission was granted */
+    grantedAt?: number;
+    /** Optional expiration timestamp */
+    expiresAt?: number;
+    /** Transaction hash of the grant transaction */
+    transactionHash?: string;
+    /** Block number when permission was granted */
+    blockNumber?: bigint;
+}
 /**
  * Permission query result
  *
@@ -715,6 +773,16 @@ interface ServerTrustStatus {
     trustIndex?: number;
 }
 
+/**
+ * Marker interface to indicate that a Vana instance has storage configured.
+ * Used for compile-time type safety to ensure storage-dependent methods
+ * are only called on properly configured instances.
+ *
+ * @category Configuration
+ */
+interface StorageRequiredMarker {
+    readonly __storageRequired: true;
+}
 /**
  * Configuration for storage providers used by the SDK.
  *
@@ -863,7 +931,7 @@ interface RelayerCallbacks {
     storeGrantFile?: (grantData: GrantFile) => Promise<string>;
 }
 /**
- * Base configuration interface
+ * Base configuration interface without storage requirements
  *
  * @category Configuration
  */
@@ -881,6 +949,42 @@ interface BaseConfig {
      * Can be overridden per method call if needed.
      */
     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.
+     *
+     * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']
+     */
+    ipfsGateways?: string[];
+}
+/**
+ * Base configuration interface that requires storage for storage-dependent operations
+ *
+ * @category Configuration
+ */
+interface BaseConfigWithStorage {
+    /**
+     * Optional relayer callback functions for handling gasless transactions.
+     * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.
+     */
+    relayerCallbacks?: RelayerCallbacks;
+    /** Required storage providers configuration for file upload/download */
+    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.
+     */
+    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.
+     *
+     * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']
+     */
+    ipfsGateways?: string[];
 }
 /**
  * Configuration with wallet client
@@ -893,6 +997,17 @@ interface WalletConfig extends BaseConfig {
         chain: VanaChain;
     };
 }
+/**
+ * Configuration with wallet client that requires storage
+ *
+ * @category Configuration
+ */
+interface WalletConfigWithStorage extends BaseConfigWithStorage {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient & {
+        chain: VanaChain;
+    };
+}
 /**
  * Configuration with chain and account details
  *
@@ -906,6 +1021,19 @@ interface ChainConfig extends BaseConfig {
     /** Optional account for signing transactions */
     account?: Account;
 }
+/**
+ * Configuration with chain and account details that requires storage
+ *
+ * @category Configuration
+ */
+interface ChainConfigWithStorage extends BaseConfigWithStorage {
+    /** The chain ID for Vana network */
+    chainId: VanaChainId;
+    /** RPC URL for the chain (optional, will use default for the chain if not provided) */
+    rpcUrl?: string;
+    /** Optional account for signing transactions */
+    account?: Account;
+}
 /**
  * Main configuration interface for initializing the Vana SDK.
  *
@@ -945,6 +1073,32 @@ interface ChainConfig extends BaseConfig {
  * ```
  */
 type VanaConfig = WalletConfig | ChainConfig;
+/**
+ * Configuration interface for Vana SDK that requires storage providers.
+ *
+ * Use this type when you need to ensure storage is configured for operations
+ * like file uploads, permission grants without pre-stored URLs, or schema creation.
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * // Configuration that guarantees storage availability
+ * const config: VanaConfigWithStorage = {
+ *   walletClient: createWalletClient({
+ *     account: privateKeyToAccount('0x...'),
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   storage: {
+ *     providers: {
+ *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })
+ *     },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * };
+ * ```
+ */
+type VanaConfigWithStorage = WalletConfigWithStorage | ChainConfigWithStorage;
 /**
  * Runtime configuration information
  *
@@ -993,6 +1147,22 @@ declare function isWalletConfig(config: VanaConfig): config is WalletConfig;
  * ```
  */
 declare function isChainConfig(config: VanaConfig): config is ChainConfig;
+/**
+ * Validates whether a configuration has required storage providers.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config has storage providers configured
+ * @example
+ * ```typescript
+ * if (hasStorageConfig(config)) {
+ *   // Safe to use storage-dependent operations
+ *   await vana.data.uploadFile(file);
+ * } else {
+ *   console.log('Storage not configured - some operations may fail');
+ * }
+ * ```
+ */
+declare function hasStorageConfig(config: VanaConfig): config is VanaConfigWithStorage;
 /**
  * Configuration validation options
  *
@@ -1144,6 +1314,10 @@ interface FileMetadata {
  * @remarks
  * This is the primary interface for uploading user data through the simplified `vana.data.upload()` method.
  * It handles the complete workflow including encryption, storage, and blockchain registration.
+ *
+ * When using permissions with encryption enabled (default), you must provide the public key
+ * for each permission recipient.
+ *
  * @example
  * ```typescript
  * // Basic file upload
@@ -1159,14 +1333,27 @@ interface FileMetadata {
  *   schemaId: 1
  * });
  *
- * // Upload with permissions for an app
+ * // Upload with permissions for an app (encrypted - requires publicKey)
  * const result = await vana.data.upload({
  *   content: "Data for AI analysis",
  *   filename: "analysis.txt",
  *   permissions: [{
- *     to: "0x1234...",
+ *     grantee: "0x1234...",
  *     operation: "llm_inference",
- *     parameters: { model: "gpt-4" }
+ *     parameters: { model: "gpt-4" },
+ *     publicKey: "0x04..." // Required when encrypt is true (default)
+ *   }]
+ * });
+ *
+ * // Upload without encryption (publicKey optional)
+ * const result = await vana.data.upload({
+ *   content: "Public data",
+ *   filename: "public.txt",
+ *   encrypt: false,
+ *   permissions: [{
+ *     grantee: "0x1234...",
+ *     operation: "read",
+ *     parameters: {}
  *   }]
  * });
  * ```
@@ -1186,6 +1373,30 @@ interface UploadParams {
     /** Optional storage provider name. */
     providerName?: string;
 }
+/**
+ * Upload parameters with encryption enabled (requires EncryptedPermissionParams).
+ *
+ * @remarks
+ * This interface ensures type safety when using encrypted uploads with permissions.
+ * @category Data Management
+ */
+interface EncryptedUploadParams extends Omit<UploadParams, "permissions" | "encrypt"> {
+    /** Permissions with required public keys for encrypted data sharing. */
+    permissions?: EncryptedPermissionParams[];
+    /** Encryption is enabled. */
+    encrypt: true;
+}
+/**
+ * Upload parameters with encryption disabled.
+ *
+ * @remarks
+ * This interface is used when uploading unencrypted data.
+ * @category Data Management
+ */
+interface UnencryptedUploadParams extends Omit<UploadParams, "encrypt"> {
+    /** Encryption is disabled. */
+    encrypt: false;
+}
 /**
  * Permission parameters for granting access during file upload.
  *
@@ -1195,7 +1406,7 @@ interface UploadParams {
  */
 interface PermissionParams {
     /** The address of the application to grant permission to. */
-    to: Address;
+    grantee: Address;
     /** The operation type (e.g., "llm_inference"). */
     operation: string;
     /** Additional parameters for the permission. */
@@ -1207,6 +1418,18 @@ interface PermissionParams {
     /** Public key of the recipient to encrypt the data key for (required for upload with permissions). */
     publicKey?: string;
 }
+/**
+ * Permission parameters with required public key for encrypted uploads.
+ *
+ * @remarks
+ * This type extends PermissionParams and makes publicKey required, ensuring
+ * compile-time safety when permissions are used with encryption.
+ * @category Data Management
+ */
+interface EncryptedPermissionParams extends PermissionParams {
+    /** Public key of the recipient to encrypt the data key for. */
+    publicKey: string;
+}
 /**
  * Result of the high-level upload operation.
  *
@@ -2509,6 +2732,12 @@ interface ControllerContext$1 {
     subgraphUrl?: string;
     /** Adapts SDK functionality to the current runtime environment. */
     platform: VanaPlatformAdapter;
+    /** Validates that storage is available for storage-dependent operations. */
+    validateStorageRequired?: () => void;
+    /** Checks whether storage is configured without throwing an error. */
+    hasStorage?: () => boolean;
+    /** Default IPFS gateways to use for fetching files. */
+    ipfsGateways?: string[];
 }
 /**
  * Manages gasless data access permissions and trusted server registry operations.
@@ -2527,7 +2756,7 @@ interface ControllerContext$1 {
  * ```typescript
  * // Grant permission for an app to access your data
  * const txHash = await vana.permissions.grant({
- *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+ *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
  *   operation: "llm_inference",
  *   parameters: { model: "gpt-4", maxTokens: 1000 },
  * });
@@ -2565,7 +2794,7 @@ declare class PermissionsController {
      * @example
      * ```typescript
      * const txHash = await vana.permissions.grant({
-     *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
      *   operation: "llm_inference",
      *   parameters: {
      *     model: "gpt-4",
@@ -2591,7 +2820,7 @@ declare class PermissionsController {
      * @example
      * ```typescript
      * const { preview, confirm } = await vana.permissions.prepareGrant({
-     *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
      *   operation: "llm_inference",
      *   files: [1, 2, 3],
      *   parameters: { model: "gpt-4", prompt: "Analyze my social media data" }
@@ -2634,7 +2863,7 @@ declare class PermissionsController {
      * @example
      * ```typescript
      * const { typedData, signature } = await vana.permissions.createAndSign({
-     *   to: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
      *   operation: "data_analysis",
      *   parameters: { analysisType: "sentiment" },
      * });
@@ -2739,12 +2968,13 @@ declare class PermissionsController {
      * Composes the EIP-712 typed data for PermissionGrant (new simplified format).
      *
      * @param params - The parameters for composing the permission grant message
-     * @param params.to - The recipient address for the permission grant
+     * @param params.grantee - The recipient address for the permission grant
      * @param params.operation - The type of operation being granted permission for
      * @param params.files - Array of file IDs that the permission applies to
      * @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;
@@ -2768,36 +2998,41 @@ declare class PermissionsController {
      */
     private getUserAddress;
     /**
-     * Retrieves all permissions granted by the current user using subgraph queries.
+     * Gets on-chain permission grant data without expensive off-chain resolution.
      *
      * @remarks
-     * This method queries the Vana subgraph to find permissions directly granted by the user
-     * using the Permission entity. It efficiently handles millions of permissions by leveraging
-     * indexed subgraph data instead of scanning contract logs. The method fetches complete
-     * grant files from IPFS to provide detailed permission information including operation
-     * parameters and grantee details.
-     * @param params - Optional query parameters
-     * @param params.limit - Maximum number of permissions to return (default: 50)
-     * @param params.subgraphUrl - Optional subgraph URL to override the default endpoint
-     * @returns A Promise that resolves to an array of `GrantedPermission` objects
-     * @throws {BlockchainError} When subgraph is unavailable or returns invalid data
+     * This method provides a fast, performance-focused way to retrieve permission grants
+     * by querying only the subgraph without making expensive IPFS or individual contract calls.
+     * It eliminates the N+1 query problem of the legacy `getUserPermissions()` method.
+     *
+     * The returned data contains all on-chain information but does NOT include resolved
+     * operation details, parameters, or file IDs. Use `retrieveGrantFile()` separately
+     * for specific grants when detailed data is needed.
+     *
+     * **Performance**: Completes in ~100-500ms regardless of permission count.
+     * **Reliability**: Single point of failure (subgraph) with clear RPC fallback path.
+     *
+     * @param options - Options for retrieving permissions (limit, subgraph URL)
+     * @returns A Promise that resolves to an array of `OnChainPermissionGrant` objects
+     * @throws {BlockchainError} When subgraph query fails
+     * @throws {NetworkError} When network requests fail
      * @example
      * ```typescript
-     * // Get all permissions granted by current user
-     * const permissions = await vana.permissions.getUserPermissions();
+     * // Fast: Get all on-chain permission data
+     * const grants = await vana.permissions.getUserPermissionGrantsOnChain({ limit: 20 });
      *
-     * permissions.forEach(permission => {
-     *   console.log(`Granted ${permission.operation} to ${permission.grantee}`);
+     * // Display in UI immediately
+     * grants.forEach(grant => {
+     *   console.log(`Permission ${grant.id}: ${grant.grantUrl}`);
      * });
      *
-     * // Limit results
-     * const recent = await vana.permissions.getUserPermissions({ limit: 10 });
+     * // Lazy load detailed data for specific permission when user clicks
+     * const grantFile = await retrieveGrantFile(grants[0].grantUrl);
+     * console.log(`Operation: ${grantFile.operation}`);
+     * console.log(`Parameters:`, grantFile.parameters);
      * ```
      */
-    getUserPermissions(params?: {
-        limit?: number;
-        subgraphUrl?: string;
-    }): Promise<GrantedPermission[]>;
+    getUserPermissionGrantsOnChain(options?: GetUserPermissionsOptions): Promise<OnChainPermissionGrant[]>;
     /**
      * Gets all permission IDs for a specific file.
      *
@@ -3316,14 +3551,21 @@ interface InitPersonalServerParams {
     /** The user's wallet address */
     userAddress: string;
 }
+/**
+ * Extended personal server identity information including connection details.
+ * This combines the base PersonalServerModel with additional metadata
+ * needed for client connections.
+ */
 interface PersonalServerIdentity {
-    /** Derived address for the personal server */
+    /** Resource type identifier */
+    kind: string;
+    /** The server's Ethereum address */
     address: string;
-    /** Public key for encryption */
+    /** The server's public key for encryption */
     public_key: string;
-    /** Base URL for the personal server */
+    /** The base URL for connecting to this server */
     base_url: string;
-    /** Name of the personal server */
+    /** Human-readable name for this server */
     name: string;
 }
 
@@ -3838,9 +4080,22 @@ interface components {
 type $defs = Record<string, never>;
 type operations = Record<string, never>;
 
+type CreateOperationRequest = components["schemas"]["CreateOperationRequest"];
 type CreateOperationResponse = components["schemas"]["CreateOperationResponse"];
 type GetOperationResponse = components["schemas"]["GetOperationResponse"];
-type OperationCreatedResponse = CreateOperationResponse;
+type IdentityResponseModel = components["schemas"]["IdentityResponseModel"];
+type PersonalServerModel = components["schemas"]["PersonalServerModel"];
+type ErrorResponse = components["schemas"]["ErrorResponse"];
+type ValidationErrorResponse = components["schemas"]["ValidationErrorResponse"];
+type AuthenticationErrorResponse = components["schemas"]["AuthenticationErrorResponse"];
+type NotFoundErrorResponse = components["schemas"]["NotFoundErrorResponse"];
+type BlockchainErrorResponse = components["schemas"]["BlockchainErrorResponse"];
+type FileAccessErrorResponse = components["schemas"]["FileAccessErrorResponse"];
+type ComputeErrorResponse = components["schemas"]["ComputeErrorResponse"];
+type DecryptionErrorResponse = components["schemas"]["DecryptionErrorResponse"];
+type GrantValidationErrorResponse = components["schemas"]["GrantValidationErrorResponse"];
+type OperationErrorResponse = components["schemas"]["OperationErrorResponse"];
+type InternalServerErrorResponse = components["schemas"]["InternalServerErrorResponse"];
 
 /**
  * Types for external API responses used by the Vana SDK
@@ -3893,43 +4148,6 @@ interface ReplicateAPIResponse {
         total_time?: number;
     };
 }
-/**
- * Identity Server Output Types
- * These define the expected structure of output from Vana's identity server
- */
-/** Output from the identity server model */
-interface IdentityServerOutput {
-    /** User's EVM address */
-    user_address: string;
-    /** Personal server information */
-    personal_server: {
-        /** Derived address for the personal server */
-        address: string;
-        /** Public key for encryption */
-        public_key: string;
-    };
-}
-/** Identity server response with typed output */
-interface IdentityServerResponse extends Omit<ReplicateAPIResponse, "output"> {
-    /** Parsed identity server output */
-    output?: IdentityServerOutput | string;
-}
-/**
- * Personal Server Output Types
- * These define the expected structure of output from Vana's personal server
- */
-/** Output from the personal server model */
-interface PersonalServerOutput {
-    /** User's EVM address */
-    user_address: string;
-    /** Identity information */
-    identity: {
-        /** Additional metadata */
-        metadata?: Record<string, unknown>;
-        /** Derived address (alternative location) */
-        derivedAddress?: string;
-    };
-}
 /**
  * Storage Provider API Types
  */
@@ -4002,38 +4220,6 @@ interface APIResponse<T = unknown> {
  * ```
  */
 declare function isReplicateAPIResponse(value: unknown): value is ReplicateAPIResponse;
-/**
- * Validates whether a value is a valid IdentityServerOutput.
- *
- * @param value - The value to check
- * @returns True if the value matches the IdentityServerOutput structure
- * @example
- * ```typescript
- * const output = response.output;
- *
- * if (isIdentityServerOutput(output)) {
- *   console.log('User address:', output.user_address);
- *   console.log('Server address:', output.personal_server.address);
- * }
- * ```
- */
-declare function isIdentityServerOutput(value: unknown): value is IdentityServerOutput;
-/**
- * Validates whether a value is a valid PersonalServerOutput.
- *
- * @param value - The value to check
- * @returns True if the value matches the PersonalServerOutput structure
- * @example
- * ```typescript
- * const output = response.output;
- *
- * if (isPersonalServerOutput(output)) {
- *   console.log('User address:', output.user_address);
- *   console.log('Identity metadata:', output.identity.metadata);
- * }
- * ```
- */
-declare function isPersonalServerOutput(value: unknown): value is PersonalServerOutput;
 /**
  * Validates whether a value is a valid APIResponse.
  *
@@ -4066,7 +4252,7 @@ declare function isAPIResponse<T>(value: unknown): value is APIResponse<T>;
  * @example
  * ```typescript
  * const jsonStr = '{"user_address": "0x123...", "identity": {}}';
- * const result = safeParseJSON(jsonStr, isPersonalServerOutput);
+ * const result = safeParseJSON(jsonStr, isAPIResponse);
  *
  * if (result) {
  *   console.log('Parsed server output:', result.user_address);
@@ -4085,7 +4271,7 @@ declare function safeParseJSON<T>(jsonString: string, typeGuard: (value: unknown
  * @example
  * ```typescript
  * const response = await replicateClient.get(predictionId);
- * const output = parseReplicateOutput(response, isIdentityServerOutput);
+ * const output = parseReplicateOutput(response, isReplicateAPIResponse);
  *
  * if (output) {
  *   console.log('Identity server result:', output.user_address);
@@ -5095,7 +5281,7 @@ interface UserFile {
  */
 interface GrantPermissionParams {
     /** The on-chain identity of the application */
-    to: Address;
+    grantee: Address;
     /** The class of computation, e.g., "llm_inference" */
     operation: string;
     /** Array of file IDs to grant permission for */
@@ -5104,6 +5290,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;
 }
 
 /**
@@ -5158,6 +5350,9 @@ declare class DataController {
      * - Grants permissions to specified applications
      * - Registers the file on the blockchain
      *
+     * When using permissions with encryption enabled (default), you must provide the public key
+     * for each permission recipient.
+     *
      * @param params - Upload parameters including content, filename, schema, and permissions
      * @returns Promise resolving to upload results with file ID and transaction hash
      * @throws {Error} When wallet is not connected or storage is not configured
@@ -5178,19 +5373,85 @@ declare class DataController {
      *   schemaId: 1
      * });
      *
-     * // Upload with permissions
+     * // Upload with permissions (encrypted - requires publicKey)
      * const result = await vana.data.upload({
      *   content: "Data for AI analysis",
      *   filename: "analysis.txt",
      *   permissions: [{
-     *     to: "0x1234...",
+     *     grantee: "0x1234...",
      *     operation: "llm_inference",
-     *     parameters: { model: "gpt-4" }
+     *     parameters: { model: "gpt-4" },
+     *     publicKey: "0x04..." // Required when encrypt is true (default)
+     *   }]
+     * });
+     *
+     * // Upload without encryption
+     * const result = await vana.data.upload({
+     *   content: "Public data",
+     *   filename: "public.txt",
+     *   encrypt: false,
+     *   permissions: [{
+     *     grantee: "0x1234...",
+     *     operation: "read",
+     *     parameters: {}
      *   }]
      * });
      * ```
      */
+    upload(params: EncryptedUploadParams): Promise<UploadResult>;
+    upload(params: UnencryptedUploadParams): Promise<UploadResult>;
     upload(params: UploadParams): Promise<UploadResult>;
+    /**
+     * Decrypts a file owned by the user using their wallet signature.
+     *
+     * @remarks
+     * This is the high-level convenience method for decrypting user files, serving as the
+     * symmetrical counterpart to the `upload` method. It handles the complete decryption
+     * workflow including key generation, URL protocol detection, content fetching, and
+     * decryption.
+     *
+     * The method automatically:
+     * - Generates the decryption key from the user's wallet signature
+     * - Determines the appropriate fetch method based on the file URL protocol
+     * - Fetches the encrypted content from IPFS or standard HTTP URLs
+     * - Decrypts the content using the generated key
+     *
+     * For IPFS URLs, the method uses gateway fallback for improved reliability. For
+     * standard HTTP URLs, it uses a simple fetch. If you need custom authentication
+     * headers or specific gateway configurations, use the low-level primitives directly.
+     *
+     * @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)
+     * @example
+     * ```typescript
+     * // Basic file decryption
+     * const files = await vana.data.getUserFiles({ owner: userAddress });
+     * const decryptedBlob = await vana.data.decryptFile(files[0]);
+     *
+     * // Convert to text
+     * const text = await decryptedBlob.text();
+     * console.log('Decrypted content:', text);
+     *
+     * // Convert to JSON
+     * const json = JSON.parse(await decryptedBlob.text());
+     * console.log('Decrypted data:', json);
+     *
+     * // With custom encryption seed
+     * const decryptedBlob = await vana.data.decryptFile(
+     *   files[0],
+     *   "My custom encryption seed"
+     * );
+     *
+     * // Save to file (in Node.js)
+     * const buffer = await decryptedBlob.arrayBuffer();
+     * fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
+     * ```
+     */
+    decryptFile(file: UserFile$1, encryptionSeed?: string): Promise<Blob>;
     /**
      * Retrieves all data files owned by a specific user address.
      *
@@ -5377,19 +5638,6 @@ declare class DataController {
      * 3. Returning the assigned file ID and storage URL
      */
     uploadEncryptedFileWithSchema(encryptedFile: Blob, schemaId: number, filename?: string, providerName?: string): Promise<UploadEncryptedFileResult>;
-    /**
-     * Decrypts a file that was encrypted using the Vana protocol.
-     *
-     * @param file - The UserFile object containing the file URL and metadata
-     * @param encryptionSeed - Optional custom encryption seed (defaults to Vana standard)
-     * @returns Promise resolving to the decrypted file as a Blob
-     *
-     * This method handles the complete flow of:
-     * 1. Generating the encryption key from the user's wallet signature
-     * 2. Fetching the encrypted file from the stored URL
-     * 3. Decrypting the file using the canonical Vana decryption method
-     */
-    decryptFile(file: UserFile$1, encryptionSeed?: string): Promise<Blob>;
     /**
      * Registers a file URL directly on the blockchain with a schema ID.
      *
@@ -5404,13 +5652,6 @@ declare class DataController {
         fileId: number;
         transactionHash: Address;
     }>;
-    /**
-     * Converts IPFS and Google Drive URLs to direct download URLs for fetching.
-     *
-     * @param url - The URL to convert to a direct download URL
-     * @returns The converted direct download URL or the original URL if not a special URL
-     */
-    private convertToDownloadUrl;
     /**
      * Gets the user's address from the wallet client.
      *
@@ -5565,6 +5806,73 @@ declare class DataController {
      * @returns Promise resolving to the decrypted file data
      */
     decryptFileWithPermission(file: UserFile$1, privateKey: string, account?: Address): Promise<Blob>;
+    /**
+     * Simple network-agnostic fetch utility for retrieving file content.
+     *
+     * @remarks
+     * This is a thin wrapper around the global fetch API that returns the response as a Blob.
+     * It provides a consistent interface for fetching encrypted content before decryption.
+     * For IPFS URLs, consider using fetchFromIPFS for better reliability.
+     *
+     * @param url - The URL to fetch content from
+     * @returns Promise resolving to the fetched content as a Blob
+     * @throws {Error} When the fetch fails or returns a non-ok response
+     *
+     * @example
+     * ```typescript
+     * // Fetch and decrypt a file
+     * const encryptionKey = await generateEncryptionKey(walletClient);
+     * const encryptedBlob = await vana.data.fetch(file.url);
+     * const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
+     *
+     * // With custom headers for authentication
+     * const response = await fetch(file.url, {
+     *   headers: { 'Authorization': 'Bearer token' }
+     * });
+     * const encryptedBlob = await response.blob();
+     * ```
+     */
+    fetch(url: string): Promise<Blob>;
+    /**
+     * Specialized IPFS fetcher with gateway fallback mechanism.
+     *
+     * @remarks
+     * This method provides robust IPFS content fetching by trying multiple gateways
+     * in sequence until one succeeds. It supports both ipfs:// URLs and raw CIDs.
+     *
+     * The default gateway list includes public gateways, but you should provide
+     * your own gateways for production use to ensure reliability and privacy.
+     *
+     * @param url - The IPFS URL (ipfs://...) or CID to fetch
+     * @param options - Optional configuration
+     * @param options.gateways - Array of IPFS gateway URLs to try (must end with /)
+     * @returns Promise resolving to the fetched content as a Blob
+     * @throws {Error} When all gateways fail to fetch the content
+     *
+     * @example
+     * ```typescript
+     * // Fetch from IPFS with custom gateways
+     * const encryptedBlob = await vana.data.fetchFromIPFS(file.url, {
+     *   gateways: [
+     *     'https://my-private-gateway.com/ipfs/',
+     *     'https://dweb.link/ipfs/',
+     *     'https://ipfs.io/ipfs/'
+     *   ]
+     * });
+     *
+     * // Decrypt the fetched content
+     * const encryptionKey = await generateEncryptionKey(walletClient);
+     * const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
+     *
+     * // With raw CID
+     * const blob = await vana.data.fetchFromIPFS('QmXxx...', {
+     *   gateways: ['https://ipfs.io/ipfs/']
+     * });
+     * ```
+     */
+    fetchFromIPFS(url: string, options?: {
+        gateways?: string[];
+    }): Promise<Blob>;
     /**
      * Validates a data schema against the Vana meta-schema.
      *
@@ -30753,6 +31061,45 @@ declare class ProtocolController {
     getChainName(): string;
 }
 
+/**
+ * Factory functions for creating VanaCore instances with proper type safety
+ */
+declare class VanaCoreFactory {
+    /**
+     * Creates a VanaCore instance that enforces storage requirements at compile time.
+     * Use this factory when you know you'll need storage-dependent operations.
+     *
+     * @param platform - The platform adapter for environment-specific operations
+     * @param config - Configuration that includes required storage providers
+     * @returns VanaCore instance with storage validation
+     * @example
+     * ```typescript
+     * const vanaCore = VanaCoreFactory.createWithStorage(platformAdapter, {
+     *   walletClient: myWalletClient,
+     *   storage: {
+     *     providers: { ipfs: new IPFSStorage() },
+     *     defaultProvider: 'ipfs'
+     *   }
+     * });
+     * ```
+     */
+    static createWithStorage(platform: VanaPlatformAdapter, config: VanaConfigWithStorage): VanaCore & StorageRequiredMarker;
+    /**
+     * Creates a VanaCore instance without storage requirements.
+     * Storage-dependent operations will fail at runtime if not configured.
+     *
+     * @param platform - The platform adapter for environment-specific operations
+     * @param config - Basic configuration without required storage
+     * @returns VanaCore instance
+     * @example
+     * ```typescript
+     * const vanaCore = VanaCoreFactory.create(platformAdapter, {
+     *   walletClient: myWalletClient
+     * });
+     * ```
+     */
+    static create(platform: VanaPlatformAdapter, config: VanaConfig): VanaCore;
+}
 /**
  * Provides the core SDK functionality for interacting with the Vana network.
  *
@@ -30761,8 +31108,11 @@ declare class ProtocolController {
  * adapter to handle environment-specific operations. It initializes all controllers
  * and manages shared context between them.
  *
+ * 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.
+ *
  * For public usage, use the platform-specific Vana classes that extend this core:
- * - Use `new Vana(config)` from the main package import
+ * - Use `Vana({config)` from the main package import
  * @example
  * ```typescript
  * // Direct instantiation (typically used internally)
@@ -30787,12 +31137,18 @@ declare class VanaCore {
     protected platform: VanaPlatformAdapter;
     private readonly relayerCallbacks?;
     private readonly storageManager?;
+    private readonly hasRequiredStorage;
+    private readonly ipfsGateways?;
     /**
      * Initializes a new VanaCore client instance with the provided configuration.
      *
      * @remarks
      * The constructor validates the configuration, initializes storage providers if configured,
      * creates wallet and public clients, and sets up all SDK controllers with shared context.
+     *
+     * IMPORTANT: This constructor will validate storage requirements at runtime to fail fast.
+     * Methods that require storage will throw runtime errors if storage is not configured.
+     *
      * @param platform - The platform adapter for environment-specific operations
      * @param config - The configuration object specifying wallet or chain settings
      * @throws {InvalidConfigurationError} When the configuration is invalid or incomplete
@@ -30805,6 +31161,48 @@ declare class VanaCore {
      * ```
      */
     constructor(platform: VanaPlatformAdapter, config: VanaConfig);
+    /**
+     * Validates that storage is available for storage-dependent operations.
+     * This method enforces the fail-fast principle by checking storage availability
+     * at method call time rather than during expensive operations.
+     *
+     * @throws {InvalidConfigurationError} When storage is required but not configured
+     * @example
+     * ```typescript
+     * // This will throw if storage is not configured
+     * vana.validateStorageRequired();
+     * await vana.data.uploadFile(file); // Safe to proceed
+     * ```
+     */
+    validateStorageRequired(): void;
+    /**
+     * Checks whether storage is configured without throwing an error.
+     *
+     * @returns True if storage is properly configured
+     * @example
+     * ```typescript
+     * if (vana.hasStorage()) {
+     *   await vana.data.uploadFile(file);
+     * } else {
+     *   console.warn('Storage not configured - using pre-stored URLs only');
+     * }
+     * ```
+     */
+    hasStorage(): boolean;
+    /**
+     * Type guard to check if this instance has storage enabled at compile time.
+     * Use this when you need TypeScript to understand that storage is available.
+     *
+     * @returns True if storage is configured, with type narrowing
+     * @example
+     * ```typescript
+     * if (vana.isStorageEnabled()) {
+     *   // TypeScript knows storage is available here
+     *   await vana.data.uploadFile(file);
+     * }
+     * ```
+     */
+    isStorageEnabled(): this is VanaCore & StorageRequiredMarker;
     /**
      * Validates the provided configuration object against all requirements.
      *
@@ -30892,21 +31290,21 @@ declare class VanaCore {
      */
     getPlatformAdapter(): VanaPlatformAdapter;
     /**
-     * Encrypts user data using the Vana protocol standard encryption.
+     * 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 walletSignature The wallet signature to use as encryption key
+     * @param key The key to use as encryption key
      * @returns The encrypted data as Blob
      * @example
      * ```typescript
      * const encryptionKey = await generateEncryptionKey(walletClient);
-     * const encrypted = await vana.encryptUserData("sensitive data", encryptionKey);
+     * const encrypted = await vana.encryptBlob("sensitive data", encryptionKey);
      * ```
      */
-    encryptUserData(data: string | Blob, walletSignature: string): Promise<Blob>;
+    encryptBlob(data: string | Blob, key: string): Promise<Blob>;
     /**
-     * Decrypts user data using the Vana protocol standard decryption.
+     * 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)
@@ -30915,11 +31313,11 @@ declare class VanaCore {
      * @example
      * ```typescript
      * const encryptionKey = await generateEncryptionKey(walletClient);
-     * const decrypted = await vana.decryptUserData(encryptedData, encryptionKey);
+     * const decrypted = await vana.decryptBlob(encryptedData, encryptionKey);
      * const text = await decrypted.text();
      * ```
      */
-    decryptUserData(encryptedData: string | Blob, walletSignature: string): Promise<Blob>;
+    decryptBlob(encryptedData: string | Blob, walletSignature: string): Promise<Blob>;
 }
 
 /**
@@ -31120,23 +31518,44 @@ declare function getEncryptionParameters(platformAdapter: VanaPlatformAdapter):
  */
 declare function decryptWithPrivateKey(encryptedData: string, privateKey: string, platformAdapter: VanaPlatformAdapter): Promise<string>;
 /**
- * Encrypt user data using PGP with platform-appropriate configuration
+ * Encrypts data using a signed key generated from the user's wallet signature.
+ *
+ * @remarks
+ * This is a pure cryptographic primitive that encrypts data using the Vana protocol's
+ * standard encryption method. The key parameter must be a signature generated by the
+ * `generateEncryptionKey` utility - this ensures deterministic key generation from the
+ * user's wallet, enabling the same key to be regenerated for decryption.
+ *
+ * This function uses password-based encryption with the signature as the password,
+ * providing symmetric encryption that can be decrypted with the same signature.
  *
  * @param data The data to encrypt (string or Blob)
- * @param walletSignature The wallet signature to use as password
- * @param platformAdapter - The platform adapter for crypto operations
+ * @param key The signed key from `generateEncryptionKey` - MUST be a wallet signature
+ * @param platformAdapter The platform adapter for crypto operations
  * @returns The encrypted data as Blob
- */
-declare function encryptUserData(data: string | Blob, walletSignature: string, platformAdapter: VanaPlatformAdapter): Promise<Blob>;
-/**
- * Decrypt user data using PGP with platform-appropriate configuration
+ * @throws {Error} When encryption fails
  *
- * @param encryptedData The encrypted data (string or Blob)
- * @param walletSignature The wallet signature to use as password
- * @param platformAdapter - The platform adapter for crypto operations
- * @returns The decrypted data as Blob
+ * @example
+ * ```typescript
+ * // Generate the encryption key from wallet signature
+ * const encryptionKey = await generateEncryptionKey(walletClient);
+ *
+ * // Encrypt data with the signed key
+ * const encryptedBlob = await encryptBlobWithSignedKey(
+ *   "My sensitive data",
+ *   encryptionKey,
+ *   platformAdapter
+ * );
+ *
+ * // Later, decrypt with the same key
+ * const decryptedBlob = await decryptBlobWithSignedKey(
+ *   encryptedBlob,
+ *   encryptionKey,
+ *   platformAdapter
+ * );
+ * ```
  */
-declare function decryptUserData(encryptedData: string | Blob, walletSignature: string, platformAdapter: VanaPlatformAdapter): Promise<Blob>;
+declare function encryptBlobWithSignedKey(data: string | Blob, key: string, platformAdapter: VanaPlatformAdapter): Promise<Blob>;
 /**
  * Generate a new key pair for asymmetric encryption
  *
@@ -31165,6 +31584,55 @@ declare function generatePGPKeyPair(platformAdapter: VanaPlatformAdapter, option
     publicKey: string;
     privateKey: string;
 }>;
+/**
+ * Decrypts data using a signed key generated from the user's wallet signature.
+ *
+ * @remarks
+ * This is a pure cryptographic primitive for decrypting data that was encrypted using
+ * `encryptBlobWithSignedKey`. It is network-agnostic and only handles decryption - it does
+ * not fetch data from any URL or make network requests. To decrypt a file from a URL, you
+ * must first fetch the encrypted blob using one of the fetch utilities, then pass it to
+ * this function.
+ *
+ * The key parameter must be the same signature that was used for encryption, typically
+ * generated by the `generateEncryptionKey` utility. This ensures that only the user who
+ * encrypted the data (or someone with the same wallet signature) can decrypt it.
+ *
+ * @param encryptedData The encrypted data to decrypt (string or Blob)
+ * @param key The signed key from `generateEncryptionKey` - MUST be the same wallet signature used for encryption
+ * @param platformAdapter The platform adapter for crypto operations
+ * @returns Promise resolving to the decrypted blob
+ * @throws {Error} When decryption fails due to wrong key or corrupted data
+ *
+ * @example
+ * ```typescript
+ * // Generate the same encryption key used for encryption
+ * const encryptionKey = await generateEncryptionKey(walletClient);
+ *
+ * // Fetch and decrypt using the high-level API
+ * const file = await vana.data.getUserFiles({ owner: "0x..." })[0];
+ * const decryptedBlob = await vana.data.decryptFile(file);
+ *
+ * // Or use the low-level primitives directly
+ * const encryptedBlob = await vana.data.fetch(file.url);
+ * const decryptedBlob = await decryptBlobWithSignedKey(
+ *   encryptedBlob,
+ *   encryptionKey,
+ *   platformAdapter
+ * );
+ *
+ * // With IPFS gateway fallback
+ * const encryptedBlob = await vana.data.fetchFromIPFS(file.url, {
+ *   gateways: ['https://my-gateway.com/ipfs/', 'https://ipfs.io/ipfs/']
+ * });
+ * const decryptedBlob = await decryptBlobWithSignedKey(
+ *   encryptedBlob,
+ *   encryptionKey,
+ *   platformAdapter
+ * );
+ * ```
+ */
+declare function decryptBlobWithSignedKey(encryptedData: string | Blob, key: string, platformAdapter: VanaPlatformAdapter): Promise<Blob>;
 
 /**
  * Format a bigint or BigNumber to a regular number
@@ -31214,11 +31682,42 @@ declare function createGrantFile(params: GrantPermissionParams$1): GrantFile;
  */
 declare function storeGrantFile(grantFile: GrantFile, relayerUrl: string): Promise<string>;
 /**
- * Retrieves a grant file from any URL.
+ * Retrieves detailed grant file data from IPFS or HTTP storage.
+ *
+ * @remarks
+ * **This is Step 2 of the performant two-step permission API.**
+ *
+ * Use this method to resolve detailed permission data (operation, parameters, etc.)
+ * for specific grants after first getting the fast on-chain data using
+ * `getUserPermissionGrantsOnChain()`. This design eliminates N+1 query problems
+ * by allowing selective lazy-loading of expensive off-chain data.
+ *
+ * **Performance**: Single network request per grant file (typically 100-500ms).
+ * **Reliability**: Tries multiple IPFS gateways as fallbacks if primary URL fails.
+ *
+ * @param grantUrl - The grant file URL from OnChainPermissionGrant.grantUrl
+ * @param _relayerUrl - URL of the relayer service (optional, unused)
+ * @returns Promise resolving to the complete grant file with operation details
+ * @throws {NetworkError} When all retrieval attempts fail
+ * @throws {SerializationError} When grant file format is invalid
+ * @example
+ * ```typescript
+ * // Step 1: Fast on-chain data (no N+1 queries)
+ * const grants = await vana.permissions.getUserPermissionGrantsOnChain();
+ *
+ * // Step 2: Lazy-load details for specific grant when needed
+ * const grantFile = await retrieveGrantFile(grants[0].grantUrl);
+ *
+ * console.log(`Operation: ${grantFile.operation}`);
+ * console.log(`Grantee: ${grantFile.grantee}`);
+ * console.log(`Parameters:`, grantFile.parameters);
  *
- * @param grantUrl - The grant file URL (supports HTTP/HTTPS, ipfs:// protocol, or IPFS gateway URLs)
- * @param _relayerUrl - URL of the relayer service (optional)
- * @returns Promise resolving to the grant file
+ * // Only fetch details for grants user actually wants to see
+ * for (const grant of selectedGrants) {
+ *   const details = await retrieveGrantFile(grant.grantUrl);
+ *   displayGrantDetails(details);
+ * }
+ * ```
  */
 declare function retrieveGrantFile(grantUrl: string, _relayerUrl?: string): Promise<GrantFile>;
 /**
@@ -31945,39 +32444,48 @@ declare class ApiClient {
 }
 
 /**
- * The Vana SDK class pre-configured for browser environments.
- * Automatically uses the browser platform adapter for crypto operations and file systems.
+ * Internal implementation class for browser environments.
+ * This class is not exported directly - use the Vana factory function instead.
+ */
+declare class VanaBrowserImpl extends VanaCore {
+    constructor(config: VanaConfig);
+}
+/**
+ * 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
  * @example
  * ```typescript
- * const vana = new Vana({ walletClient });
+ * // With storage - all methods available
+ * const vana = Vana({
+ *   walletClient,
+ *   storage: { providers: { ipfs: new IPFSStorage() }, defaultProvider: 'ipfs' }
+ * });
+ * await vana.data.uploadFile(file); // ✅ Works - TypeScript knows storage is available
  *
- * // Upload and encrypt user data
- * const file = await vana.data.uploadAndStoreFile(dataBlob, schema);
+ * // Without storage - storage methods unavailable at compile time
+ * const vanaNoStorage = Vana({ walletClient });
+ * // await vanaNoStorage.data.uploadFile(file); // ❌ TypeScript error
  *
- * // Grant permissions to DLPs
- * await vana.permissions.grantPermission({
- *   account: dlpAddress,
- *   fileId: file.id,
- *   permissions: ['read']
- * });
+ * // Runtime check still available
+ * if (vanaNoStorage.isStorageEnabled()) {
+ *   // TypeScript now knows storage methods are safe to use
+ *   await vanaNoStorage.data.uploadFile(file); // ✅ Works
+ * }
  * ```
  */
-declare class VanaBrowser extends VanaCore {
-    /**
-     * Creates a Vana SDK instance configured for browser environments.
-     *
-     * @param config - SDK configuration object (wallet client or chain config)
-     * @example
-     * ```typescript
-     * // With wallet client
-     * const vana = new Vana({ walletClient });
-     *
-     * // With chain configuration
-     * const vana = new Vana({ chainId: 14800, account });
-     * ```
-     */
-    constructor(config: VanaConfig);
-}
+declare function Vana(config: VanaConfigWithStorage): VanaBrowserImpl & StorageRequiredMarker;
+declare function Vana(config: VanaConfig): VanaBrowserImpl;
+/**
+ * The type of a Vana SDK instance in browser environments.
+ *
+ * @see {@link Vana}
+ */
+type VanaInstance = VanaBrowserImpl;
 
-export { type $defs, type APIResponse, type AddRefinerParams, type AddRefinerResult, type AddSchemaParams, type AddSchemaResult, type AllKeys, ApiClient, type ApiClientConfig, type ApiResponse, AsyncQueue, type AsyncResult, type Awaited, type BaseConfig, BaseController, type BatchServerInfoResult, type BatchUploadParams, type BatchUploadResult, type BlockRange, BlockchainError, type Brand, BrowserPlatformAdapter, type Cache, type CacheConfig, type ChainConfig, type CheckPermissionParams, CircuitBreaker, type ConditionalOptional, type ConfigValidationOptions, type ConfigValidationResult, type ContractAddresses, type ContractCall, type ContractDeployment, ContractFactory, type ContractInfo, type ContractMethodParams, type ContractMethodReturnType, ContractNotFoundError, type Controller, type ControllerContext, type CreateOperationParams, type CreateOperationResponse, type CreateSchemaParams, type CreateSchemaResult, DEFAULT_ENCRYPTION_SEED, DEFAULT_IPFS_GATEWAY, DataController, type DataSchema, type DeepPartial, type DeepReadonly, type DeleteFileParams, type DeleteFileResult, type DownloadFileParams, type DownloadFileResult, type EncryptionInfo, EventEmitter, type EventFilter, type EventLog, type Factory, type FileAccessPermissions, type FileMetadata, type FileSharingConfig, type GasEstimate, type GenericRequest, type GenericResponse, type GenericTypedData, type GetFileParams, type GetOperationResponse, type GetUserFilesParams, type GetUserTrustedServersParams, type GetUserTrustedServersResult, GoogleDriveStorage, GrantExpiredError, type GrantFile, type GrantPermissionParams, GrantSchemaError, GrantValidationError, type GrantValidationOptions, type GrantValidationResult, type GrantedPermission, GranteeMismatchError, type HttpMethod, IPFS_GATEWAYS, type IdentityServerOutput, type IdentityServerResponse, type InitPersonalServerParams, InvalidConfigurationError, IpfsStorage, type MaybeArray, type MaybePromise, MemoryCache, type Middleware, MiddlewarePipeline, NetworkError, type NetworkInfo, type Nominal, type NonNullable, NonceError, type Observable, type Observer, type OmitByType, type OperationCreatedResponse, OperationNotAllowedError, type OptionalKeys, type PaginatedTrustedServers, type PaginationParams, type PaginationResult, type PartialExcept, type PermissionAnalytics, type PermissionCheckResult, PermissionError, type PermissionEvent, type PermissionGrantDomain, type PermissionGrantMessage, type PermissionGrantTypedData, type PermissionInfo, type PermissionInputMessage, type PermissionOperation, type PermissionParams, type PermissionQueryResult, type PermissionStatus, PermissionsController, PersonalServerError, type PersonalServerIdentity, type PersonalServerOutput, type PickByType, type PinataListResponse, type PinataPin, PinataStorage, type PinataUploadResponse, type Plugin, type PostRequestParams, type PromiseResult, ProtocolController, type QueryPermissionsParams, type RateLimitInfo, RateLimiter, type RateLimiterConfig, type Refiner, type RelayerCallbacks, type RelayerConfig, RelayerError, type RelayerErrorResponse, type RelayerMetrics, type RelayerQueueInfo, type RelayerRequestOptions, type RelayerStatus, type RelayerStorageResponse, type RelayerStoreParams, type RelayerSubmitParams, type RelayerTransactionResponse, type RelayerTransactionStatus, type RelayerWebhookConfig, type RelayerWebhookPayload, type ReplicateAPIResponse, type ReplicateStatus, type Repository, type RequestOptions, type RequireKeys, type RequiredExcept, type RetryConfig, RetryUtility, type RevokePermissionInput, type RevokePermissionParams, type RuntimeConfig, type Schema, SchemaValidationError, SchemaValidator, SerializationError, type Server, type components as ServerComponents, ServerController, type $defs as ServerDefs, type operations as ServerOperations, type paths as ServerPaths, ServerProxyStorage, type ServerTrustStatus, ServerUrlMismatchError, type webhooks as ServerWebhooks, type Service, SignatureError, type SimplifiedPermissionMessage, type StateMachine, type StatusInfo, type StorageConfig, StorageError, type StorageFile, type StorageListOptions, StorageManager, type StorageProvider, type StorageProviderConfig, type StorageUploadResult, type TimeRange, type TransactionOptions, type TransactionReceipt, type Transformer, type TrustServerInput, type TrustServerParams, type TrustServerTypedData, type TrustedServer, type TrustedServerInfo, type TrustedServerQueryMode, type TrustedServerQueryOptions, type UntrustServerInput, type UntrustServerParams, type UntrustServerTypedData, type UpdateSchemaIdParams, type UpdateSchemaIdResult, type UploadEncryptedFileResult, type UploadFileParams, type UploadFileResult, type UploadParams, type UploadProgress, type UploadResult, type UserFile, UserRejectedRequestError, type ValidationResult, type Validator, VanaBrowser as Vana, VanaBrowser, type VanaChain, type VanaChainConfig, type VanaChainId, type VanaConfig, type VanaContract, type VanaContract as VanaContractAbi, type VanaContractInstance, type VanaContractName, VanaError, type VanaPlatformAdapter, type WalletConfig, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createPlatformAdapterSafe, createValidatedGrant, decryptUserData, decryptWithPrivateKey, decryptWithWalletPrivateKey, VanaBrowser as default, detectPlatform, encryptFileKey, encryptUserData, encryptWithWalletPublicKey, extractIpfsHash, fetchAndValidateSchema, fetchWithFallbacks, formatEth, formatNumber, formatToken, generateEncryptionKey, generateEncryptionKeyPair, generatePGPKeyPair, getAbi, getAllChains, getChainConfig, getContractAddress, getContractController, getContractInfo, getEncryptionParameters, getGatewayUrls, getGrantFileHash, getGrantTimeRemaining, getPlatformCapabilities, isAPIResponse, isChainConfig, isGrantExpired, isIdentityServerOutput, isIpfsUrl, isPersonalServerOutput, isPlatformSupported, isReplicateAPIResponse, isVanaChain, isVanaChainId, isWalletConfig, moksha, mokshaTestnet, type operations, parseReplicateOutput, type paths, retrieveAndValidateGrant, retrieveGrantFile, safeParseJSON, schemaValidator, shortenAddress, storeGrantFile, summarizeGrant, validateDataAgainstSchema, validateDataSchema, validateGrant, validateGrantExpiry, validateGrantFile, validateGranteeAccess, validateOperationAccess, vanaMainnet, type webhooks };
+export { type $defs, type APIResponse, type AddRefinerParams, type AddRefinerResult, type AddSchemaParams, type AddSchemaResult, type AllKeys, ApiClient, type ApiClientConfig, type ApiResponse, AsyncQueue, type AsyncResult, type AuthenticationErrorResponse, type Awaited, type BaseConfig, type BaseConfigWithStorage, BaseController, type BatchServerInfoResult, type BatchUploadParams, type BatchUploadResult, type BlockRange, BlockchainError, type BlockchainErrorResponse, type Brand, BrowserPlatformAdapter, type Cache, type CacheConfig, type ChainConfig, type ChainConfigWithStorage, type CheckPermissionParams, CircuitBreaker, type ComputeErrorResponse, type ConditionalOptional, type ConfigValidationOptions, type ConfigValidationResult, type ContractAddresses, type ContractCall, type ContractDeployment, ContractFactory, type ContractInfo, type ContractMethodParams, type ContractMethodReturnType, ContractNotFoundError, type Controller, type ControllerContext, type CreateOperationParams, type CreateOperationRequest, type CreateOperationResponse, type CreateSchemaParams, type CreateSchemaResult, DEFAULT_ENCRYPTION_SEED, DEFAULT_IPFS_GATEWAY, DataController, type DataSchema, type DecryptionErrorResponse, type DeepPartial, type DeepReadonly, type DeleteFileParams, type DeleteFileResult, type DownloadFileParams, type DownloadFileResult, type EncryptedPermissionParams, type EncryptedUploadParams, type EncryptionInfo, type ErrorResponse, EventEmitter, type EventFilter, type EventLog, type Factory, type FileAccessErrorResponse, type FileAccessPermissions, type FileMetadata, type FileSharingConfig, type GasEstimate, type GenericRequest, type GenericResponse, type GenericTypedData, type GetFileParams, type GetOperationResponse, type GetUserFilesParams, type GetUserPermissionsOptions, type GetUserTrustedServersParams, type GetUserTrustedServersResult, GoogleDriveStorage, GrantExpiredError, type GrantFile, type GrantPermissionParams, GrantSchemaError, GrantValidationError, type GrantValidationErrorResponse, type GrantValidationOptions, type GrantValidationResult, type GrantedPermission, GranteeMismatchError, type HttpMethod, IPFS_GATEWAYS, type IdentityResponseModel, type InitPersonalServerParams, type InternalServerErrorResponse, InvalidConfigurationError, IpfsStorage, type MaybeArray, type MaybePromise, MemoryCache, type Middleware, MiddlewarePipeline, NetworkError, type NetworkInfo, type Nominal, type NonNullable, NonceError, type NotFoundErrorResponse, type Observable, type Observer, type OmitByType, type OnChainPermissionGrant, type OperationErrorResponse, OperationNotAllowedError, type OptionalKeys, type PaginatedTrustedServers, type PaginationParams, type PaginationResult, type PartialExcept, type PermissionAnalytics, type PermissionCheckResult, PermissionError, type PermissionEvent, type PermissionGrantDomain, type PermissionGrantMessage, type PermissionGrantTypedData, type PermissionInfo, type PermissionInputMessage, type PermissionOperation, type PermissionParams, type PermissionQueryResult, type PermissionStatus, PermissionsController, PersonalServerError, type PersonalServerIdentity, type PersonalServerModel, type PickByType, type PinataListResponse, type PinataPin, PinataStorage, type PinataUploadResponse, type Plugin, type PostRequestParams, type PromiseResult, ProtocolController, type QueryPermissionsParams, type RateLimitInfo, RateLimiter, type RateLimiterConfig, type Refiner, type RelayerCallbacks, type RelayerConfig, RelayerError, type RelayerErrorResponse, type RelayerMetrics, type RelayerQueueInfo, type RelayerRequestOptions, type RelayerStatus, type RelayerStorageResponse, type RelayerStoreParams, type RelayerSubmitParams, type RelayerTransactionResponse, type RelayerTransactionStatus, type RelayerWebhookConfig, type RelayerWebhookPayload, type ReplicateAPIResponse, type ReplicateStatus, type Repository, type RequestOptions, type RequireKeys, type RequiredExcept, type RetryConfig, RetryUtility, type RevokePermissionInput, type RevokePermissionParams, type RuntimeConfig, type Schema, SchemaValidationError, SchemaValidator, SerializationError, type Server, type components as ServerComponents, ServerController, type $defs as ServerDefs, type operations as ServerOperations, type paths as ServerPaths, ServerProxyStorage, type ServerTrustStatus, ServerUrlMismatchError, type webhooks as ServerWebhooks, type Service, SignatureError, type SimplifiedPermissionMessage, type StateMachine, type StatusInfo, type StorageConfig, StorageError, type StorageFile, type StorageListOptions, StorageManager, type StorageProvider, type StorageProviderConfig, type StorageRequiredMarker, type StorageUploadResult, type TimeRange, type TransactionOptions, type TransactionReceipt, type Transformer, type TrustServerInput, type TrustServerParams, type TrustServerTypedData, type TrustedServer, type TrustedServerInfo, type TrustedServerQueryMode, type TrustedServerQueryOptions, type UnencryptedUploadParams, type UntrustServerInput, type UntrustServerParams, type UntrustServerTypedData, type UpdateSchemaIdParams, type UpdateSchemaIdResult, type UploadEncryptedFileResult, type UploadFileParams, type UploadFileResult, type UploadParams, type UploadProgress, type UploadResult, type UserFile, UserRejectedRequestError, type ValidationErrorResponse, type ValidationResult, type Validator, Vana, VanaBrowserImpl, type VanaChain, type VanaChainConfig, type VanaChainId, type VanaConfig, type VanaConfigWithStorage, type VanaContract, type VanaContract as VanaContractAbi, type VanaContractInstance, type VanaContractName, VanaCore, VanaCoreFactory, VanaError, type VanaInstance, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createPlatformAdapterSafe, createValidatedGrant, decryptBlobWithSignedKey, decryptWithPrivateKey, decryptWithWalletPrivateKey, Vana as default, detectPlatform, encryptBlobWithSignedKey, encryptFileKey, encryptWithWalletPublicKey, extractIpfsHash, fetchAndValidateSchema, fetchWithFallbacks, formatEth, formatNumber, formatToken, generateEncryptionKey, generateEncryptionKeyPair, generatePGPKeyPair, getAbi, getAllChains, getChainConfig, getContractAddress, getContractController, getContractInfo, getEncryptionParameters, getGatewayUrls, getGrantFileHash, getGrantTimeRemaining, getPlatformCapabilities, hasStorageConfig, isAPIResponse, isChainConfig, isGrantExpired, isIpfsUrl, isPlatformSupported, isReplicateAPIResponse, isVanaChain, isVanaChainId, isWalletConfig, moksha, mokshaTestnet, type operations, parseReplicateOutput, type paths, retrieveAndValidateGrant, retrieveGrantFile, safeParseJSON, schemaValidator, shortenAddress, storeGrantFile, summarizeGrant, validateDataAgainstSchema, validateDataSchema, validateGrant, validateGrantExpiry, validateGrantFile, validateGranteeAccess, validateOperationAccess, vanaMainnet, type webhooks };