@opendatalabs/vana-sdk 0.1.0-alpha.2b6935d → 0.1.0-alpha.2e77fcc

package/dist/types/blockchain.d.ts

@@ -1,10 +1,23 @@
 /**
- * Core blockchain types for the Vana SDK
+ * Defines core blockchain interaction types.
+ *
+ * @remarks
+ * This module provides fundamental types for blockchain transactions,
+ * including transaction requests, confirmation options, and results.
+ * These types form the basis for all blockchain interactions in the SDK.
+ *
+ * @category Types
+ * @module types/blockchain
  */
 import type { Hash, Address } from "viem";
 /**
- * Represents a transaction that has been submitted to the blockchain
- * This is what contract calls return before confirmation
+ * Represents a submitted blockchain transaction awaiting confirmation.
+ *
+ * @remarks
+ * Returned immediately after transaction submission, before confirmation.
+ * Use `waitForTransactionEvents` to wait for confirmation and retrieve events.
+ *
+ * @category Blockchain
  */
 export interface TransactionRequest {
     /** Transaction hash */
@@ -19,7 +32,13 @@ export interface TransactionRequest {
     args?: readonly unknown[];
 }
 /**
- * Options for waiting for transaction confirmation
+ * Configures transaction confirmation waiting behavior.
+ *
+ * @remarks
+ * Controls how long and how often to check for transaction confirmation.
+ * Adjust based on network congestion and application requirements.
+ *
+ * @category Blockchain
  */
 export interface TransactionWaitOptions {
     /** Number of confirmations to wait for (default: 1) */
@@ -30,7 +49,14 @@ export interface TransactionWaitOptions {
     pollingInterval?: number;
 }
 /**
- * Base result for all confirmed transactions
+ * Represents a confirmed blockchain transaction with metadata.
+ *
+ * @remarks
+ * Contains essential transaction information after confirmation including
+ * gas usage, block number, and function details. Extended by specific
+ * result types with parsed events.
+ *
+ * @category Blockchain
  */
 export interface TransactionResult {
     /** Transaction hash */
@@ -47,11 +73,13 @@ export interface TransactionResult {
     functionName: string;
 }
 /**
- * Event arguments are dynamically typed based on the contract mappings.
- * The parseTransaction function will:
- * 1. Return expectedEvents with typed args for mapped functions
- * 2. Return allEvents with all parsed events from the transaction
+ * @remarks
+ * Event typing strategy:
+ * - Event arguments are dynamically typed based on contract mappings
+ * - `parseTransaction` returns `expectedEvents` with typed args for mapped functions
+ * - `allEvents` contains all parsed events from the transaction
+ * - This approach lets the mapping file drive types rather than requiring
+ *   specific result interfaces per event type
  *
- * This approach avoids the need for specific result interfaces per event type,
- * letting the mapping file drive the types instead.
+ * @internal
  */

package/dist/types/chains.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Supported Vana chain IDs\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Supported Vana chains\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Chain configuration mapping\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Type guard to check if a chain ID is supported\n *\n * @param chainId - The chain ID to validate\n * @returns True if the chain ID is a supported Vana chain ID\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Type guard to check if a chain is a Vana chain\n *\n * @param chain - The chain object to validate\n * @returns True if the chain is a supported Vana chain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AAQO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}
+{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Represents the supported Vana network chain identifiers.\n *\n * @remarks\n * The Vana protocol operates on two primary networks:\n * - `14800`: Moksha testnet for development and testing\n * - `1480`: Vana mainnet for production deployment\n *\n * Use these chain IDs when configuring the SDK or checking network compatibility.\n *\n * @category Blockchain\n * @see {@link https://docs.vana.org/docs/networks | Network Documentation}\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Extends viem's Chain type with Vana-specific chain constraints.\n *\n * @remarks\n * Ensures type safety for Vana-specific chains by restricting the chain ID\n * to supported networks. This type provides full viem Chain compatibility\n * while guaranteeing the chain is a valid Vana network.\n *\n * @category Blockchain\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Maps Vana chain IDs to their complete chain configurations.\n *\n * @remarks\n * Provides type-safe access to chain configurations indexed by chain ID.\n * Use this for dynamic chain selection based on runtime chain ID values.\n *\n * @category Blockchain\n * @example\n * ```typescript\n * const configs: ChainConfig = {\n *   14800: mokshaTestnet,\n *   1480: vanaMainnet\n * };\n * const chain = configs[chainId];\n * ```\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Validates whether a chain ID represents a supported Vana network.\n *\n * @remarks\n * Type guard for runtime validation of chain IDs from external sources.\n * Use when accepting user input or processing network configurations.\n *\n * @param chainId - The chain ID to validate\n * @returns `true` if the chain ID is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * const chainId = parseInt(process.env.CHAIN_ID);\n *\n * if (!isVanaChainId(chainId)) {\n *   throw new Error(`Unsupported chain ID: ${chainId}`);\n * }\n *\n * // TypeScript now knows chainId is VanaChainId\n * const config = getChainConfig(chainId);\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Validates whether a Chain object represents a supported Vana network.\n *\n * @remarks\n * Type guard for validating viem Chain objects as Vana chains.\n * Ensures both type safety and runtime validation for chain compatibility.\n *\n * @param chain - The chain object to validate\n * @returns `true` if the chain is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * import { mainnet, mokshaTestnet } from 'viem/chains';\n *\n * if (isVanaChain(chain)) {\n *   // TypeScript knows this is a VanaChain\n *   console.log(`Connected to Vana network: ${chain.id}`);\n * } else {\n *   console.error('Please connect to a Vana network');\n * }\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4EO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AA0BO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}

package/dist/types/chains.d.ts

@@ -1,31 +1,98 @@
 import type { Chain } from "viem";
 /**
- * Supported Vana chain IDs
+ * Represents the supported Vana network chain identifiers.
+ *
+ * @remarks
+ * The Vana protocol operates on two primary networks:
+ * - `14800`: Moksha testnet for development and testing
+ * - `1480`: Vana mainnet for production deployment
+ *
+ * Use these chain IDs when configuring the SDK or checking network compatibility.
+ *
+ * @category Blockchain
+ * @see {@link https://docs.vana.org/docs/networks | Network Documentation}
  */
 export type VanaChainId = 14800 | 1480;
 /**
- * Supported Vana chains
+ * Extends viem's Chain type with Vana-specific chain constraints.
+ *
+ * @remarks
+ * Ensures type safety for Vana-specific chains by restricting the chain ID
+ * to supported networks. This type provides full viem Chain compatibility
+ * while guaranteeing the chain is a valid Vana network.
+ *
+ * @category Blockchain
  */
 export type VanaChain = Chain & {
     id: VanaChainId;
 };
 /**
- * Chain configuration mapping
+ * Maps Vana chain IDs to their complete chain configurations.
+ *
+ * @remarks
+ * Provides type-safe access to chain configurations indexed by chain ID.
+ * Use this for dynamic chain selection based on runtime chain ID values.
+ *
+ * @category Blockchain
+ * @example
+ * ```typescript
+ * const configs: ChainConfig = {
+ *   14800: mokshaTestnet,
+ *   1480: vanaMainnet
+ * };
+ * const chain = configs[chainId];
+ * ```
  */
 export type ChainConfig = {
     [K in VanaChainId]: VanaChain;
 };
 /**
- * Type guard to check if a chain ID is supported
+ * Validates whether a chain ID represents a supported Vana network.
+ *
+ * @remarks
+ * Type guard for runtime validation of chain IDs from external sources.
+ * Use when accepting user input or processing network configurations.
  *
  * @param chainId - The chain ID to validate
- * @returns True if the chain ID is a supported Vana chain ID
+ * @returns `true` if the chain ID is a supported Vana network, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const chainId = parseInt(process.env.CHAIN_ID);
+ *
+ * if (!isVanaChainId(chainId)) {
+ *   throw new Error(`Unsupported chain ID: ${chainId}`);
+ * }
+ *
+ * // TypeScript now knows chainId is VanaChainId
+ * const config = getChainConfig(chainId);
+ * ```
+ *
+ * @category Blockchain
  */
 export declare function isVanaChainId(chainId: number): chainId is VanaChainId;
 /**
- * Type guard to check if a chain is a Vana chain
+ * Validates whether a Chain object represents a supported Vana network.
+ *
+ * @remarks
+ * Type guard for validating viem Chain objects as Vana chains.
+ * Ensures both type safety and runtime validation for chain compatibility.
  *
  * @param chain - The chain object to validate
- * @returns True if the chain is a supported Vana chain
+ * @returns `true` if the chain is a supported Vana network, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { mainnet, mokshaTestnet } from 'viem/chains';
+ *
+ * if (isVanaChain(chain)) {
+ *   // TypeScript knows this is a VanaChain
+ *   console.log(`Connected to Vana network: ${chain.id}`);
+ * } else {
+ *   console.error('Please connect to a Vana network');
+ * }
+ * ```
+ *
+ * @category Blockchain
  */
 export declare function isVanaChain(chain: Chain): chain is VanaChain;

package/dist/types/chains.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Supported Vana chain IDs\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Supported Vana chains\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Chain configuration mapping\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Type guard to check if a chain ID is supported\n *\n * @param chainId - The chain ID to validate\n * @returns True if the chain ID is a supported Vana chain ID\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Type guard to check if a chain is a Vana chain\n *\n * @param chain - The chain object to validate\n * @returns True if the chain is a supported Vana chain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":"AA2BO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AAQO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}
+{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Represents the supported Vana network chain identifiers.\n *\n * @remarks\n * The Vana protocol operates on two primary networks:\n * - `14800`: Moksha testnet for development and testing\n * - `1480`: Vana mainnet for production deployment\n *\n * Use these chain IDs when configuring the SDK or checking network compatibility.\n *\n * @category Blockchain\n * @see {@link https://docs.vana.org/docs/networks | Network Documentation}\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Extends viem's Chain type with Vana-specific chain constraints.\n *\n * @remarks\n * Ensures type safety for Vana-specific chains by restricting the chain ID\n * to supported networks. This type provides full viem Chain compatibility\n * while guaranteeing the chain is a valid Vana network.\n *\n * @category Blockchain\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Maps Vana chain IDs to their complete chain configurations.\n *\n * @remarks\n * Provides type-safe access to chain configurations indexed by chain ID.\n * Use this for dynamic chain selection based on runtime chain ID values.\n *\n * @category Blockchain\n * @example\n * ```typescript\n * const configs: ChainConfig = {\n *   14800: mokshaTestnet,\n *   1480: vanaMainnet\n * };\n * const chain = configs[chainId];\n * ```\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Validates whether a chain ID represents a supported Vana network.\n *\n * @remarks\n * Type guard for runtime validation of chain IDs from external sources.\n * Use when accepting user input or processing network configurations.\n *\n * @param chainId - The chain ID to validate\n * @returns `true` if the chain ID is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * const chainId = parseInt(process.env.CHAIN_ID);\n *\n * if (!isVanaChainId(chainId)) {\n *   throw new Error(`Unsupported chain ID: ${chainId}`);\n * }\n *\n * // TypeScript now knows chainId is VanaChainId\n * const config = getChainConfig(chainId);\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Validates whether a Chain object represents a supported Vana network.\n *\n * @remarks\n * Type guard for validating viem Chain objects as Vana chains.\n * Ensures both type safety and runtime validation for chain compatibility.\n *\n * @param chain - The chain object to validate\n * @returns `true` if the chain is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * import { mainnet, mokshaTestnet } from 'viem/chains';\n *\n * if (isVanaChain(chain)) {\n *   // TypeScript knows this is a VanaChain\n *   console.log(`Connected to Vana network: ${chain.id}`);\n * } else {\n *   console.error('Please connect to a Vana network');\n * }\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":"AA4EO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AA0BO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}

package/dist/types/config.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { WalletClient, PublicClient, Account, Address, Chain } from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\n\nimport type { RelayerConfig } from \"./relayer\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configuration for storage providers used by the SDK.\n *\n * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)\n * and specify which one to use by default for file operations.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'your-key', secretKey: 'your-secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Configuration with wallet client and optional public client\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWallet extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnly extends BaseConfig {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnly extends BaseConfig {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Configuration with wallet client and optional public client that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnlyWithStorage\n  extends BaseConfigWithStorage {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * The SDK supports three initialization modes:\n * 1. Full mode with wallet client for signing transactions\n * 2. Read-only mode with public client and address for read operations\n * 3. Minimal mode with just an address and optional chain\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Mode 1: Full configuration with wallet client\n * const configWithWallet: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   })\n * };\n *\n * // Mode 2: Read-only with public client and address\n * const configReadOnly: VanaConfig = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...'\n * };\n *\n * // Mode 3: Minimal with just address\n * const configMinimal: VanaConfig = {\n *   address: '0x1234...',\n *   chain: moksha // optional\n * };\n * ```\n */\nexport type VanaConfig =\n  | VanaConfigWithWallet\n  | VanaConfigReadOnly\n  | VanaConfigAddressOnly\n  | WalletConfig\n  | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n * Supports all three initialization modes with required storage.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Full configuration with wallet client and storage\n * const configWithWallet: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n *\n * // Read-only configuration with storage\n * const configReadOnly: VanaConfigWithStorage = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...',\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | VanaConfigWithWalletWithStorage\n  | VanaConfigReadOnlyWithStorage\n  | VanaConfigAddressOnlyWithStorage\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer configuration */\n  relayerConfig?: RelayerConfig;\n}\n\n/**\n * Validates whether a configuration object has a wallet client (any wallet-based config).\n *\n * @param config - The configuration object to check\n * @returns True if the config contains a walletClient\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Read-only or chain config');\n * }\n * ```\n */\nexport function isWalletConfig(\n  config: VanaConfig,\n): config is VanaConfigWithWallet | WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a read-only config with public client.\n *\n * @param config - The configuration object to check\n * @returns True if the config has publicClient and address but no walletClient\n * @example\n * ```typescript\n * if (isReadOnlyConfig(config)) {\n *   console.log('Read-only mode with address:', config.address);\n * }\n * ```\n */\nexport function isReadOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigReadOnly {\n  return (\n    \"publicClient\" in config &&\n    \"address\" in config &&\n    !(\"walletClient\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is an address-only config.\n *\n * @param config - The configuration object to check\n * @returns True if the config has only address (and optionally chain) but no clients\n * @example\n * ```typescript\n * if (isAddressOnlyConfig(config)) {\n *   console.log('Address-only mode:', config.address);\n * }\n * ```\n */\nexport function isAddressOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigAddressOnly {\n  return (\n    \"address\" in config &&\n    !(\"publicClient\" in config) &&\n    !(\"walletClient\" in config) &&\n    !(\"chainId\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8oBO,SAAS,eACd,QAC+C;AAC/C,SAAO,kBAAkB;AAC3B;AAcO,SAAS,iBACd,QAC8B;AAC9B,SACE,kBAAkB,UAClB,aAAa,UACb,EAAE,kBAAkB;AAExB;AAcO,SAAS,oBACd,QACiC;AACjC,SACE,aAAa,UACb,EAAE,kBAAkB,WACpB,EAAE,kBAAkB,WACpB,EAAE,aAAa;AAEnB;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}
+{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { WalletClient, PublicClient, Account, Address, Chain } from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\n\nimport type { RelayerConfig } from \"./relayer\";\nimport type { IOperationStore } from \"./operations\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configures storage providers for SDK file operations.\n *\n * @remarks\n * Supports multiple backends with automatic fallback.\n * IPFS for decentralization, Pinata for reliability,\n * Google Drive for development, custom for flexibility.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'key', secretKey: 'secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n\n  /**\n   * Optional operation store for tracking async relayed transactions.\n   * When provided with a relayer, enables resilient transaction management\n   * with polling support for pending operations.\n   *\n   * @example\n   * ```typescript\n   * const vana = createVana({\n   *   walletClient,\n   *   relayer: '/api/relay',\n   *   operationStore: myOperationStore\n   * });\n   * ```\n   */\n  operationStore?: IOperationStore;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n\n  /**\n   * Optional operation store for tracking async relayed transactions.\n   * When provided with a relayer, enables resilient transaction management\n   * with polling support for pending operations.\n   */\n  operationStore?: IOperationStore;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Configuration with wallet client and optional public client\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWallet extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnly extends BaseConfig {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnly extends BaseConfig {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Configuration with wallet client and optional public client that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnlyWithStorage\n  extends BaseConfigWithStorage {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * The SDK supports three initialization modes:\n * 1. Full mode with wallet client for signing transactions\n * 2. Read-only mode with public client and address for read operations\n * 3. Minimal mode with just an address and optional chain\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Mode 1: Full configuration with wallet client\n * const configWithWallet: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   })\n * };\n *\n * // Mode 2: Read-only with public client and address\n * const configReadOnly: VanaConfig = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...'\n * };\n *\n * // Mode 3: Minimal with just address\n * const configMinimal: VanaConfig = {\n *   address: '0x1234...',\n *   chain: moksha // optional\n * };\n * ```\n */\nexport type VanaConfig =\n  | VanaConfigWithWallet\n  | VanaConfigReadOnly\n  | VanaConfigAddressOnly\n  | WalletConfig\n  | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n * Supports all three initialization modes with required storage.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Full configuration with wallet client and storage\n * const configWithWallet: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n *\n * // Read-only configuration with storage\n * const configReadOnly: VanaConfigWithStorage = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...',\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | VanaConfigWithWalletWithStorage\n  | VanaConfigReadOnlyWithStorage\n  | VanaConfigAddressOnlyWithStorage\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer configuration */\n  relayerConfig?: RelayerConfig;\n}\n\n/**\n * Validates whether a configuration object has a wallet client (any wallet-based config).\n *\n * @param config - The configuration object to check\n * @returns True if the config contains a walletClient\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Read-only or chain config');\n * }\n * ```\n */\nexport function isWalletConfig(\n  config: VanaConfig,\n): config is VanaConfigWithWallet | WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a read-only config with public client.\n *\n * @param config - The configuration object to check\n * @returns True if the config has publicClient and address but no walletClient\n * @example\n * ```typescript\n * if (isReadOnlyConfig(config)) {\n *   console.log('Read-only mode with address:', config.address);\n * }\n * ```\n */\nexport function isReadOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigReadOnly {\n  return (\n    \"publicClient\" in config &&\n    \"address\" in config &&\n    !(\"walletClient\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is an address-only config.\n *\n * @param config - The configuration object to check\n * @returns True if the config has only address (and optionally chain) but no clients\n * @example\n * ```typescript\n * if (isAddressOnlyConfig(config)) {\n *   console.log('Address-only mode:', config.address);\n * }\n * ```\n */\nexport function isAddressOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigAddressOnly {\n  return (\n    \"address\" in config &&\n    !(\"publicClient\" in config) &&\n    !(\"walletClient\" in config) &&\n    !(\"chainId\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n\n/**\n * Marker interface to enforce the presence of operationStore at compile time.\n * This interface is used to ensure that certain operations requiring a relayer\n * can only be called when the SDK has been properly configured with an operation store.\n *\n * @category Configuration\n */\nexport interface RelayerRequiredMarker {\n  readonly __relayerConfigured: true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyqBO,SAAS,eACd,QAC+C;AAC/C,SAAO,kBAAkB;AAC3B;AAcO,SAAS,iBACd,QAC8B;AAC9B,SACE,kBAAkB,UAClB,aAAa,UACb,EAAE,kBAAkB;AAExB;AAcO,SAAS,oBACd,QACiC;AACjC,SACE,aAAa,UACb,EAAE,kBAAkB,WACpB,EAAE,kBAAkB,WACpB,EAAE,aAAa;AAEnB;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}

package/dist/types/config.d.ts

@@ -2,6 +2,7 @@ import type { WalletClient, PublicClient, Account, Address, Chain } from "viem";
 import type { VanaChainId, VanaChain } from "./chains";
 import type { StorageProvider, StorageUploadResult, StorageListOptions } from "./storage";
 import type { RelayerConfig } from "./relayer";
+import type { IOperationStore } from "./operations";
 /**
  * Marker interface to indicate that a Vana instance has storage configured.
  * Used for compile-time type safety to ensure storage-dependent methods
@@ -13,10 +14,12 @@ export interface StorageRequiredMarker {
     readonly __storageRequired: true;
 }
 /**
- * Configuration for storage providers used by the SDK.
+ * Configures storage providers for SDK file operations.
  *
- * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)
- * and specify which one to use by default for file operations.
+ * @remarks
+ * Supports multiple backends with automatic fallback.
+ * IPFS for decentralization, Pinata for reliability,
+ * Google Drive for development, custom for flexibility.
  *
  * **Provider Selection:**
  * - IPFS: Decentralized, permanent storage ideal for production
@@ -30,7 +33,7 @@ export interface StorageRequiredMarker {
  * const storage: StorageConfig = {
  *   providers: {
  *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),
- *     pinata: new PinataStorage({ apiKey: 'your-key', secretKey: 'your-secret' })
+ *     pinata: new PinataStorage({ apiKey: 'key', secretKey: 'secret' })
  *   },
  *   defaultProvider: 'ipfs'
  * };
@@ -303,6 +306,21 @@ export interface BaseConfig {
      * @example 'https://my-personal-server.example.com'
      */
     defaultPersonalServerUrl?: string;
+    /**
+     * Optional operation store for tracking async relayed transactions.
+     * When provided with a relayer, enables resilient transaction management
+     * with polling support for pending operations.
+     *
+     * @example
+     * ```typescript
+     * const vana = createVana({
+     *   walletClient,
+     *   relayer: '/api/relay',
+     *   operationStore: myOperationStore
+     * });
+     * ```
+     */
+    operationStore?: IOperationStore;
 }
 /**
  * Base configuration interface that requires storage for storage-dependent operations
@@ -358,6 +376,12 @@ export interface BaseConfigWithStorage {
      * @example 'https://my-personal-server.example.com'
      */
     defaultPersonalServerUrl?: string;
+    /**
+     * Optional operation store for tracking async relayed transactions.
+     * When provided with a relayer, enables resilient transaction management
+     * with polling support for pending operations.
+     */
+    operationStore?: IOperationStore;
 }
 /**
  * Configuration with wallet client
@@ -684,3 +708,13 @@ export interface ConfigValidationResult {
     /** List of validation warnings */
     warnings: string[];
 }
+/**
+ * Marker interface to enforce the presence of operationStore at compile time.
+ * This interface is used to ensure that certain operations requiring a relayer
+ * can only be called when the SDK has been properly configured with an operation store.
+ *
+ * @category Configuration
+ */
+export interface RelayerRequiredMarker {
+    readonly __relayerConfigured: true;
+}

package/dist/types/config.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { WalletClient, PublicClient, Account, Address, Chain } from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\n\nimport type { RelayerConfig } from \"./relayer\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configuration for storage providers used by the SDK.\n *\n * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)\n * and specify which one to use by default for file operations.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'your-key', secretKey: 'your-secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Configuration with wallet client and optional public client\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWallet extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnly extends BaseConfig {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnly extends BaseConfig {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Configuration with wallet client and optional public client that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnlyWithStorage\n  extends BaseConfigWithStorage {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * The SDK supports three initialization modes:\n * 1. Full mode with wallet client for signing transactions\n * 2. Read-only mode with public client and address for read operations\n * 3. Minimal mode with just an address and optional chain\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Mode 1: Full configuration with wallet client\n * const configWithWallet: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   })\n * };\n *\n * // Mode 2: Read-only with public client and address\n * const configReadOnly: VanaConfig = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...'\n * };\n *\n * // Mode 3: Minimal with just address\n * const configMinimal: VanaConfig = {\n *   address: '0x1234...',\n *   chain: moksha // optional\n * };\n * ```\n */\nexport type VanaConfig =\n  | VanaConfigWithWallet\n  | VanaConfigReadOnly\n  | VanaConfigAddressOnly\n  | WalletConfig\n  | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n * Supports all three initialization modes with required storage.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Full configuration with wallet client and storage\n * const configWithWallet: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n *\n * // Read-only configuration with storage\n * const configReadOnly: VanaConfigWithStorage = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...',\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | VanaConfigWithWalletWithStorage\n  | VanaConfigReadOnlyWithStorage\n  | VanaConfigAddressOnlyWithStorage\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer configuration */\n  relayerConfig?: RelayerConfig;\n}\n\n/**\n * Validates whether a configuration object has a wallet client (any wallet-based config).\n *\n * @param config - The configuration object to check\n * @returns True if the config contains a walletClient\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Read-only or chain config');\n * }\n * ```\n */\nexport function isWalletConfig(\n  config: VanaConfig,\n): config is VanaConfigWithWallet | WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a read-only config with public client.\n *\n * @param config - The configuration object to check\n * @returns True if the config has publicClient and address but no walletClient\n * @example\n * ```typescript\n * if (isReadOnlyConfig(config)) {\n *   console.log('Read-only mode with address:', config.address);\n * }\n * ```\n */\nexport function isReadOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigReadOnly {\n  return (\n    \"publicClient\" in config &&\n    \"address\" in config &&\n    !(\"walletClient\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is an address-only config.\n *\n * @param config - The configuration object to check\n * @returns True if the config has only address (and optionally chain) but no clients\n * @example\n * ```typescript\n * if (isAddressOnlyConfig(config)) {\n *   console.log('Address-only mode:', config.address);\n * }\n * ```\n */\nexport function isAddressOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigAddressOnly {\n  return (\n    \"address\" in config &&\n    !(\"publicClient\" in config) &&\n    !(\"walletClient\" in config) &&\n    !(\"chainId\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n"],"mappings":"AA8oBO,SAAS,eACd,QAC+C;AAC/C,SAAO,kBAAkB;AAC3B;AAcO,SAAS,iBACd,QAC8B;AAC9B,SACE,kBAAkB,UAClB,aAAa,UACb,EAAE,kBAAkB;AAExB;AAcO,SAAS,oBACd,QACiC;AACjC,SACE,aAAa,UACb,EAAE,kBAAkB,WACpB,EAAE,kBAAkB,WACpB,EAAE,aAAa;AAEnB;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}
+{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { WalletClient, PublicClient, Account, Address, Chain } from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\n\nimport type { RelayerConfig } from \"./relayer\";\nimport type { IOperationStore } from \"./operations\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configures storage providers for SDK file operations.\n *\n * @remarks\n * Supports multiple backends with automatic fallback.\n * IPFS for decentralization, Pinata for reliability,\n * Google Drive for development, custom for flexibility.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'key', secretKey: 'secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n\n  /**\n   * Optional operation store for tracking async relayed transactions.\n   * When provided with a relayer, enables resilient transaction management\n   * with polling support for pending operations.\n   *\n   * @example\n   * ```typescript\n   * const vana = createVana({\n   *   walletClient,\n   *   relayer: '/api/relay',\n   *   operationStore: myOperationStore\n   * });\n   * ```\n   */\n  operationStore?: IOperationStore;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n\n  /**\n   * Optional operation store for tracking async relayed transactions.\n   * When provided with a relayer, enables resilient transaction management\n   * with polling support for pending operations.\n   */\n  operationStore?: IOperationStore;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Configuration with wallet client and optional public client\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWallet extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnly extends BaseConfig {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnly extends BaseConfig {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Configuration with wallet client and optional public client that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnlyWithStorage\n  extends BaseConfigWithStorage {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * The SDK supports three initialization modes:\n * 1. Full mode with wallet client for signing transactions\n * 2. Read-only mode with public client and address for read operations\n * 3. Minimal mode with just an address and optional chain\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Mode 1: Full configuration with wallet client\n * const configWithWallet: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   })\n * };\n *\n * // Mode 2: Read-only with public client and address\n * const configReadOnly: VanaConfig = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...'\n * };\n *\n * // Mode 3: Minimal with just address\n * const configMinimal: VanaConfig = {\n *   address: '0x1234...',\n *   chain: moksha // optional\n * };\n * ```\n */\nexport type VanaConfig =\n  | VanaConfigWithWallet\n  | VanaConfigReadOnly\n  | VanaConfigAddressOnly\n  | WalletConfig\n  | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n * Supports all three initialization modes with required storage.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Full configuration with wallet client and storage\n * const configWithWallet: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n *\n * // Read-only configuration with storage\n * const configReadOnly: VanaConfigWithStorage = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...',\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | VanaConfigWithWalletWithStorage\n  | VanaConfigReadOnlyWithStorage\n  | VanaConfigAddressOnlyWithStorage\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer configuration */\n  relayerConfig?: RelayerConfig;\n}\n\n/**\n * Validates whether a configuration object has a wallet client (any wallet-based config).\n *\n * @param config - The configuration object to check\n * @returns True if the config contains a walletClient\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Read-only or chain config');\n * }\n * ```\n */\nexport function isWalletConfig(\n  config: VanaConfig,\n): config is VanaConfigWithWallet | WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a read-only config with public client.\n *\n * @param config - The configuration object to check\n * @returns True if the config has publicClient and address but no walletClient\n * @example\n * ```typescript\n * if (isReadOnlyConfig(config)) {\n *   console.log('Read-only mode with address:', config.address);\n * }\n * ```\n */\nexport function isReadOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigReadOnly {\n  return (\n    \"publicClient\" in config &&\n    \"address\" in config &&\n    !(\"walletClient\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is an address-only config.\n *\n * @param config - The configuration object to check\n * @returns True if the config has only address (and optionally chain) but no clients\n * @example\n * ```typescript\n * if (isAddressOnlyConfig(config)) {\n *   console.log('Address-only mode:', config.address);\n * }\n * ```\n */\nexport function isAddressOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigAddressOnly {\n  return (\n    \"address\" in config &&\n    !(\"publicClient\" in config) &&\n    !(\"walletClient\" in config) &&\n    !(\"chainId\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n\n/**\n * Marker interface to enforce the presence of operationStore at compile time.\n * This interface is used to ensure that certain operations requiring a relayer\n * can only be called when the SDK has been properly configured with an operation store.\n *\n * @category Configuration\n */\nexport interface RelayerRequiredMarker {\n  readonly __relayerConfigured: true;\n}\n"],"mappings":"AAyqBO,SAAS,eACd,QAC+C;AAC/C,SAAO,kBAAkB;AAC3B;AAcO,SAAS,iBACd,QAC8B;AAC9B,SACE,kBAAkB,UAClB,aAAa,UACb,EAAE,kBAAkB;AAExB;AAcO,SAAS,oBACd,QACiC;AACjC,SACE,aAAa,UACb,EAAE,kBAAkB,WACpB,EAAE,kBAAkB,WACpB,EAAE,aAAa;AAEnB;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}

package/dist/types/contracts.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/contracts.ts"],"sourcesContent":["import type { Abi, Address, Hash, GetContractReturnType } from \"viem\";\n\n/**\n * Union type of all canonical Vana contract names\n */\nexport type VanaContractName =\n  | \"DataPortabilityPermissions\"\n  | \"DataPortabilityServers\"\n  | \"DataPortabilityGrantees\"\n  | \"DataRegistry\"\n  | \"TeePool\"\n  | \"ComputeEngine\"\n  | \"TeePoolPhala\"\n  | \"DataRefinerRegistry\"\n  | \"QueryEngine\"\n  | \"ComputeInstructionRegistry\"\n  | \"TeePoolEphemeralStandard\"\n  | \"TeePoolPersistentStandard\"\n  | \"TeePoolPersistentGpu\"\n  | \"TeePoolDedicatedStandard\"\n  | \"TeePoolDedicatedGpu\"\n  | \"VanaEpoch\"\n  | \"DLPRegistry\"\n  | \"DLPRegistryTreasury\"\n  | \"DLPPerformance\"\n  | \"DLPRewardDeployer\"\n  | \"DLPRewardDeployerTreasury\"\n  | \"DLPRewardSwap\"\n  | \"SwapHelper\"\n  | \"VanaPoolStaking\"\n  | \"VanaPoolEntity\"\n  | \"VanaPoolTreasury\"\n  | \"DAT\"\n  | \"DATFactory\"\n  | \"DATPausable\"\n  | \"DATVotes\"\n  | \"DataLiquidityPool\"\n  | \"DLPRoot\";\n\n/**\n * Contract information with typed address and ABI\n */\nexport interface ContractInfo<TAbi extends Abi = Abi> {\n  /** The contract's deployed address */\n  address: Address;\n  /** The contract's ABI */\n  abi: TAbi;\n}\n\n/**\n * Contract deployment information\n */\nexport interface ContractDeployment {\n  /** The contract's deployed address */\n  address: Address;\n  /** Block number where contract was deployed */\n  blockNumber: bigint;\n  /** Transaction hash of deployment */\n  transactionHash: Hash;\n}\n\n/**\n * Typed contract instance\n */\nexport type VanaContractInstance<TAbi extends Abi = Abi> =\n  GetContractReturnType<TAbi>;\n\n/**\n * Contract addresses mapping by chain and contract name\n */\nexport type ContractAddresses = {\n  [chainId: number]: {\n    [contractName in VanaContractName]?: Address;\n  };\n};\n\n/**\n * Contract method parameters for typed interactions\n */\nexport type ContractMethodParams<\n  TAbi extends Abi,\n  TFunctionName extends string,\n> = TAbi extends readonly unknown[]\n  ? TAbi[number] extends {\n      name: TFunctionName;\n      type: \"function\";\n      inputs: infer TInputs;\n    }\n    ? TInputs extends readonly unknown[]\n      ? {\n          [K in keyof TInputs]: TInputs[K] extends {\n            name: infer TName;\n            type: infer TType;\n          }\n            ? TName extends string\n              ? TType extends \"address\"\n                ? Address\n                : TType extends \"uint256\"\n                  ? bigint\n                  : TType extends \"string\"\n                    ? string\n                    : TType extends \"bool\"\n                      ? boolean\n                      : TType extends \"bytes32\"\n                        ? Hash\n                        : unknown\n              : never\n            : never;\n        }\n      : never\n    : never\n  : never;\n\n/**\n * Contract method return type for typed interactions\n */\nexport type ContractMethodReturnType<\n  TAbi extends Abi,\n  TFunctionName extends string,\n> = TAbi extends readonly unknown[]\n  ? TAbi[number] extends {\n      name: TFunctionName;\n      type: \"function\";\n      outputs: infer TOutputs;\n    }\n    ? TOutputs extends readonly unknown[]\n      ? TOutputs[\"length\"] extends 1\n        ? TOutputs[0] extends { type: infer TType }\n          ? TType extends \"address\"\n            ? Address\n            : TType extends \"uint256\"\n              ? bigint\n              : TType extends \"string\"\n                ? string\n                : TType extends \"bool\"\n                  ? boolean\n                  : TType extends \"bytes32\"\n                    ? Hash\n                    : unknown\n          : unknown\n        : {\n            [K in keyof TOutputs]: TOutputs[K] extends {\n              name: infer TName;\n              type: infer TType;\n            }\n              ? TName extends string\n                ? TType extends \"address\"\n                  ? Address\n                  : TType extends \"uint256\"\n                    ? bigint\n                    : TType extends \"string\"\n                      ? string\n                      : TType extends \"bool\"\n                        ? boolean\n                        : TType extends \"bytes32\"\n                          ? Hash\n                          : unknown\n                : never\n              : never;\n          }\n      : never\n    : never\n  : never;\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/contracts.ts"],"sourcesContent":["/**\n * Defines types for smart contract interactions.\n *\n * @remarks\n * This module provides comprehensive type definitions for Vana protocol\n * smart contracts including contract names, deployment information, and\n * advanced TypeScript utility types for type-safe contract interactions.\n *\n * @category Types\n * @module types/contracts\n */\n\nimport type { Abi, Address, Hash, GetContractReturnType } from \"viem\";\n\n/**\n * Enumerates all supported Vana protocol contract names.\n *\n * @remarks\n * Use these names with `getContractController()` to get typed contract\n * instances. Each name corresponds to a specific protocol contract with\n * its own ABI and functionality.\n *\n * @category Contracts\n */\nexport type VanaContractName =\n  | \"DataPortabilityPermissions\"\n  | \"DataPortabilityServers\"\n  | \"DataPortabilityGrantees\"\n  | \"DataRegistry\"\n  | \"TeePool\"\n  | \"ComputeEngine\"\n  | \"TeePoolPhala\"\n  | \"DataRefinerRegistry\"\n  | \"QueryEngine\"\n  | \"ComputeInstructionRegistry\"\n  | \"TeePoolEphemeralStandard\"\n  | \"TeePoolPersistentStandard\"\n  | \"TeePoolPersistentGpu\"\n  | \"TeePoolDedicatedStandard\"\n  | \"TeePoolDedicatedGpu\"\n  | \"VanaEpoch\"\n  | \"DLPRegistry\"\n  | \"DLPRegistryTreasury\"\n  | \"DLPPerformance\"\n  | \"DLPRewardDeployer\"\n  | \"DLPRewardDeployerTreasury\"\n  | \"DLPRewardSwap\"\n  | \"SwapHelper\"\n  | \"VanaPoolStaking\"\n  | \"VanaPoolEntity\"\n  | \"VanaPoolTreasury\"\n  | \"DAT\"\n  | \"DATFactory\"\n  | \"DATPausable\"\n  | \"DATVotes\"\n  | \"DataLiquidityPool\"\n  | \"DLPRoot\";\n\n/**\n * Provides contract deployment information with typed ABI.\n *\n * @remarks\n * Contains the minimum information needed to interact with a\n * deployed contract: its address and ABI.\n *\n * @typeParam TAbi - The contract's ABI type for full type safety\n *\n * @category Contracts\n */\nexport interface ContractInfo<TAbi extends Abi = Abi> {\n  /** The contract's deployed address */\n  address: Address;\n  /** The contract's ABI */\n  abi: TAbi;\n}\n\n/**\n * Tracks contract deployment metadata.\n *\n * @remarks\n * Records when and how a contract was deployed to the blockchain,\n * useful for verification and debugging.\n *\n * @category Contracts\n */\nexport interface ContractDeployment {\n  /** The contract's deployed address */\n  address: Address;\n  /** Block number where contract was deployed */\n  blockNumber: bigint;\n  /** Transaction hash of deployment */\n  transactionHash: Hash;\n}\n\n/**\n * Represents a fully typed contract instance.\n *\n * @remarks\n * Alias for viem's GetContractReturnType, providing a contract\n * instance with all methods fully typed based on the ABI.\n *\n * @typeParam TAbi - The contract's ABI type\n *\n * @category Contracts\n */\nexport type VanaContractInstance<TAbi extends Abi = Abi> =\n  GetContractReturnType<TAbi>;\n\n/**\n * Maps contract addresses by chain ID and contract name.\n *\n * @remarks\n * Hierarchical mapping structure for multi-chain contract deployments.\n * Used internally for address resolution across different networks.\n *\n * @category Contracts\n */\nexport type ContractAddresses = {\n  [chainId: number]: {\n    [contractName in VanaContractName]?: Address;\n  };\n};\n\n/**\n * Extracts typed parameters for a contract method from its ABI.\n *\n * @remarks\n * Advanced utility type that provides type-safe parameter extraction\n * from contract ABIs. Maps Solidity types to TypeScript types automatically.\n *\n * @typeParam TAbi - The contract's ABI type\n * @typeParam TFunctionName - The name of the function to extract parameters for\n *\n * @internal\n */\nexport type ContractMethodParams<\n  TAbi extends Abi,\n  TFunctionName extends string,\n> = TAbi extends readonly unknown[]\n  ? TAbi[number] extends {\n      name: TFunctionName;\n      type: \"function\";\n      inputs: infer TInputs;\n    }\n    ? TInputs extends readonly unknown[]\n      ? {\n          [K in keyof TInputs]: TInputs[K] extends {\n            name: infer TName;\n            type: infer TType;\n          }\n            ? TName extends string\n              ? TType extends \"address\"\n                ? Address\n                : TType extends \"uint256\"\n                  ? bigint\n                  : TType extends \"string\"\n                    ? string\n                    : TType extends \"bool\"\n                      ? boolean\n                      : TType extends \"bytes32\"\n                        ? Hash\n                        : unknown\n              : never\n            : never;\n        }\n      : never\n    : never\n  : never;\n\n/**\n * Extracts typed return values for a contract method from its ABI.\n *\n * @remarks\n * Advanced utility type that provides type-safe return type extraction\n * from contract ABIs. Handles single values and tuples appropriately.\n *\n * @typeParam TAbi - The contract's ABI type\n * @typeParam TFunctionName - The name of the function to extract return type for\n *\n * @internal\n */\nexport type ContractMethodReturnType<\n  TAbi extends Abi,\n  TFunctionName extends string,\n> = TAbi extends readonly unknown[]\n  ? TAbi[number] extends {\n      name: TFunctionName;\n      type: \"function\";\n      outputs: infer TOutputs;\n    }\n    ? TOutputs extends readonly unknown[]\n      ? TOutputs[\"length\"] extends 1\n        ? TOutputs[0] extends { type: infer TType }\n          ? TType extends \"address\"\n            ? Address\n            : TType extends \"uint256\"\n              ? bigint\n              : TType extends \"string\"\n                ? string\n                : TType extends \"bool\"\n                  ? boolean\n                  : TType extends \"bytes32\"\n                    ? Hash\n                    : unknown\n          : unknown\n        : {\n            [K in keyof TOutputs]: TOutputs[K] extends {\n              name: infer TName;\n              type: infer TType;\n            }\n              ? TName extends string\n                ? TType extends \"address\"\n                  ? Address\n                  : TType extends \"uint256\"\n                    ? bigint\n                    : TType extends \"string\"\n                      ? string\n                      : TType extends \"bool\"\n                        ? boolean\n                        : TType extends \"bytes32\"\n                          ? Hash\n                          : unknown\n                : never\n              : never;\n          }\n      : never\n    : never\n  : never;\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}