@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dc68f39

package/dist/types/utils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/utils.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Makes all properties in T optional except for those in K\n *\n * @remarks\n * This utility type is useful when you want to create a variant of an interface\n * where most properties are optional, but specific properties remain required.\n * Commonly used for update operations where only certain fields must be provided.\n *\n * @example\n * ```typescript\n * interface User {\n *   id: string;\n *   name: string;\n *   email: string;\n *   age: number;\n * }\n *\n * // Only 'id' is required, all other properties are optional\n * type UserUpdate = PartialExcept<User, 'id'>;\n *\n * const update: UserUpdate = {\n *   id: '123', // Required\n *   name: 'John' // Optional\n *   // email and age are also optional\n * };\n * ```\n * @category Reference\n */\nexport type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;\n\n/**\n * Makes all properties in T required except for those in K\n *\n * @remarks\n * This utility type is useful when you want to create a variant of an interface\n * where most properties are required, but specific properties remain optional.\n * Commonly used for creation operations where most fields are mandatory.\n *\n * @example\n * ```typescript\n * interface Config {\n *   apiUrl: string;\n *   timeout?: number;\n *   retries?: number;\n *   debug?: boolean;\n * }\n *\n * // All properties required except 'debug'\n * type StrictConfig = RequiredExcept<Config, 'debug'>;\n *\n * const config: StrictConfig = {\n *   apiUrl: 'https://api.vana.com', // Required\n *   timeout: 5000, // Required (was optional, now required)\n *   retries: 3, // Required (was optional, now required)\n *   // debug remains optional\n * };\n * ```\n * @category Reference\n */\nexport type RequiredExcept<T, K extends keyof T> = Required<T> &\n  Partial<Pick<T, K>>;\n\n/**\n * Extracts the return type of a promise\n *\n * @remarks\n * This utility type unwraps the type contained within a Promise.\n * If the type is not a Promise, it returns the type unchanged.\n * Note: TypeScript 4.5+ includes a built-in Awaited type with similar functionality.\n *\n * @example\n * ```typescript\n * type AsyncString = Promise<string>;\n * type SyncString = string;\n *\n * // Extracts 'string' from Promise<string>\n * type Result1 = Awaited<AsyncString>; // string\n *\n * // Returns 'string' unchanged since it's not a Promise\n * type Result2 = Awaited<SyncString>; // string\n *\n * // Practical usage with async functions\n * async function fetchUser(): Promise<{ id: string; name: string }> {\n *   // ...\n * }\n *\n * type User = Awaited<ReturnType<typeof fetchUser>>; // { id: string; name: string }\n * ```\n * @category Reference\n */\nexport type Awaited<T> = T extends Promise<infer U> ? U : T;\n\n/**\n * Creates a type that accepts either T or a Promise<T>\n *\n * @remarks\n * This utility type is useful for functions that can work with both\n * synchronous and asynchronous values. It allows flexible APIs that\n * can accept immediate values or promises that resolve to those values.\n *\n * @example\n * ```typescript\n * // Function that accepts either a value or a promise of that value\n * async function processData(data: MaybePromise<string>): Promise<string> {\n *   // await works on both promises and regular values\n *   const resolved = await data;\n *   return resolved.toUpperCase();\n * }\n *\n * // Both calls are valid:\n * processData('hello'); // Synchronous value\n * processData(Promise.resolve('world')); // Asynchronous value\n *\n * // Common use case in SDK callbacks\n * interface StorageProvider {\n *   // Provider can implement sync or async file reading\n *   read(path: string): MaybePromise<Buffer>;\n * }\n * ```\n * @category Reference\n */\nexport type MaybePromise<T> = T | Promise<T>;\n\n/**\n * Creates a type that accepts either T or an array of T\n *\n * @remarks\n * This utility type is useful for functions that can accept either a single\n * value or an array of values, providing a more flexible API. The implementation\n * can normalize the input to always work with arrays internally.\n *\n * @example\n * ```typescript\n * // Function that accepts either a single ID or multiple IDs\n * function deleteItems(ids: MaybeArray<string>): void {\n *   // Normalize to array\n *   const idArray = Array.isArray(ids) ? ids : [ids];\n *   idArray.forEach(id => console.log(`Deleting ${id}`));\n * }\n *\n * // Both calls are valid:\n * deleteItems('item-1'); // Single item\n * deleteItems(['item-1', 'item-2', 'item-3']); // Multiple items\n *\n * // Common use case in permissions\n * interface GrantPermissionsParams {\n *   permissions: MaybeArray<Permission>;\n * }\n * ```\n * @category Reference\n */\nexport type MaybeArray<T> = T | T[];\n\n/**\n * Pagination parameters for controlling result set size and navigation.\n *\n * Used across SDK methods that return lists of items to control how many items\n * are returned and to navigate through large result sets efficiently.\n *\n * @category Reference\n * @example\n * ```typescript\n * const pagination: PaginationParams = {\n *   limit: 20, // Return 20 items\n *   offset: 40, // Skip first 40 items (page 3)\n *   cursor: 'eyJpZCI6MTIzfQ==' // Or use cursor-based pagination\n * };\n *\n * const files = await vana.data.getUserFiles({\n *   owner: userAddress,\n *   pagination\n * });\n * ```\n */\nexport interface PaginationParams {\n  /** Maximum number of items to return */\n  limit?: number;\n  /** Number of items to skip */\n  offset?: number;\n  /** Cursor for cursor-based pagination */\n  cursor?: string;\n}\n\n/**\n * Pagination result containing items and metadata for navigating large datasets.\n *\n * @remarks\n * This interface standardizes paginated responses across the SDK, providing\n * consistent metadata for implementing pagination UI components and handling\n * multi-page data fetching. Supports both offset-based and cursor-based pagination.\n *\n * @example\n * ```typescript\n * // Fetching paginated user files\n * async function getAllUserFiles(userAddress: string): Promise<File[]> {\n *   const allFiles: File[] = [];\n *   let cursor: string | undefined;\n *\n *   do {\n *     const result: PaginationResult<File> = await vana.data.getUserFiles({\n *       owner: userAddress,\n *       pagination: { limit: 50, cursor }\n *     });\n *\n *     allFiles.push(...result.items);\n *     cursor = result.nextCursor;\n *\n *     console.log(`Fetched ${result.count} of ${result.total} files`);\n *   } while (result.hasMore);\n *\n *   return allFiles;\n * }\n * ```\n * @category Reference\n */\nexport interface PaginationResult<T> {\n  /** Array of items */\n  items: T[];\n  /** Total number of items available */\n  total: number;\n  /** Number of items returned */\n  count: number;\n  /** Whether there are more items available */\n  hasMore: boolean;\n  /** Cursor for next page */\n  nextCursor?: string;\n}\n\n/**\n * Block range parameters for filtering blockchain events and transactions.\n *\n * @remarks\n * Used to specify a range of blocks when querying blockchain data.\n * Both parameters are optional - omitting fromBlock starts from genesis,\n * omitting toBlock goes to the latest block. Be cautious with large ranges\n * as they may result in heavy RPC loads or timeouts.\n *\n * @example\n * ```typescript\n * // Get events from the last 1000 blocks\n * const currentBlock = await vana.protocol.getBlockNumber();\n * const events = await vana.protocol.getEvents({\n *   blockRange: {\n *     fromBlock: currentBlock - 1000n,\n *     toBlock: currentBlock\n *   }\n * });\n *\n * // Get all historical events (use with caution)\n * const allEvents = await vana.protocol.getEvents({\n *   blockRange: {\n *     fromBlock: 0n\n *     // toBlock omitted = up to latest\n *   }\n * });\n * ```\n * @category Reference\n */\nexport interface BlockRange {\n  /** Starting block number */\n  fromBlock?: bigint;\n  /** Ending block number */\n  toBlock?: bigint;\n}\n\n/**\n * Transaction options for customizing blockchain transaction parameters.\n *\n * @remarks\n * Provides fine-grained control over transaction execution. Supports both\n * legacy (gasPrice) and EIP-1559 (maxFeePerGas) transaction types. When\n * not specified, the SDK will use appropriate defaults based on network\n * conditions. Use these options to optimize for speed or cost.\n *\n * @example\n * ```typescript\n * // High priority transaction with EIP-1559 pricing\n * await vana.permissions.grant(params, {\n *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei\n *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip\n * });\n *\n * // Legacy transaction with specific gas limit\n * await vana.data.registerFile(params, {\n *   gasLimit: 500000n,\n *   gasPrice: 50n * 10n ** 9n // 50 gwei\n * });\n *\n * // Send ETH with the transaction\n * await vana.protocol.execute(params, {\n *   value: 10n ** 18n, // 1 ETH\n *   gasLimit: 21000n\n * });\n * ```\n * @category Reference\n */\nexport interface TransactionOptions {\n  /** Gas limit */\n  gasLimit?: bigint;\n  /** Gas price */\n  gasPrice?: bigint;\n  /** Max fee per gas (EIP-1559) */\n  maxFeePerGas?: bigint;\n  /** Max priority fee per gas (EIP-1559) */\n  maxPriorityFeePerGas?: bigint;\n  /** Nonce */\n  nonce?: number;\n  /** Value to send with transaction */\n  value?: bigint;\n}\n\n/**\n * Transaction receipt with additional metadata for tracking transaction results.\n *\n * @remarks\n * Provides comprehensive information about executed transactions including\n * gas usage, success status, and emitted events. Use the logs array to\n * decode events emitted by smart contracts during transaction execution.\n * The receipt is available after a transaction is mined and included in a block.\n *\n * @example\n * ```typescript\n * // Execute transaction and wait for receipt\n * const receipt = await vana.permissions.grant({\n *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   dataId: 123\n * });\n *\n * // Check transaction success\n * if (receipt.status === 'success') {\n *   console.log(`Gas used: ${receipt.gasUsed}`);\n *   console.log(`Block: ${receipt.blockNumber}`);\n *\n *   // Decode events from logs\n *   receipt.logs.forEach(log => {\n *     if (log.topics[0] === PERMISSION_GRANTED_TOPIC) {\n *       console.log('Permission granted event detected');\n *     }\n *   });\n * } else {\n *   console.error('Transaction reverted');\n * }\n * ```\n * @category Reference\n */\nexport interface TransactionReceipt {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Block number */\n  blockNumber: bigint;\n  /** Block hash */\n  blockHash: Hash;\n  /** Gas used */\n  gasUsed: bigint;\n  /** Transaction status */\n  status: \"success\" | \"reverted\";\n  /** Contract address if contract deployment */\n  contractAddress?: Address;\n  /** Event logs */\n  logs: Array<{\n    address: Address;\n    topics: Hash[];\n    data: string;\n  }>;\n}\n\n/**\n * Response wrapper for API results providing consistent error handling.\n *\n * @remarks\n * Standardizes API responses across the SDK, making it easy to handle\n * both successful and failed requests. The generic type parameter T\n * represents the expected data type for successful responses. Check\n * the success flag before accessing data to ensure type safety.\n *\n * @example\n * ```typescript\n * // Handling API responses\n * async function fetchUserData(userId: string): Promise<User | null> {\n *   const response: ApiResponse<User> = await api.getUser(userId);\n *\n *   if (response.success) {\n *     console.log('User fetched:', response.data.name);\n *     // Access metadata if available\n *     if (response.metadata?.cached) {\n *       console.log('Data was cached');\n *     }\n *     return response.data;\n *   } else {\n *     console.error('Failed to fetch user:', response.error);\n *     return null;\n *   }\n * }\n *\n * // Type-safe error handling\n * interface UserData {\n *   id: string;\n *   name: string;\n * }\n *\n * const result: ApiResponse<UserData> = await api.call('/users/123');\n * if (result.success) {\n *   // TypeScript knows result.data is UserData here\n *   console.log(result.data.name);\n * }\n * ```\n * @category Reference\n */\nexport interface ApiResponse<T> {\n  /** Response data */\n  data: T;\n  /** Success status */\n  success: boolean;\n  /** Error message if not successful */\n  error?: string;\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Retry configuration for handling transient failures with exponential backoff.\n *\n * @remarks\n * Configures automatic retry behavior for operations that may fail due to\n * temporary issues like network problems or rate limits. Supports exponential\n * backoff to avoid overwhelming services. The shouldRetry function allows\n * custom logic to determine which errors warrant a retry attempt.\n *\n * @example\n * ```typescript\n * // Simple retry configuration\n * const basicRetry: RetryConfig = {\n *   attempts: 3,\n *   delay: 1000 // 1 second between retries\n * };\n *\n * // Exponential backoff configuration\n * const exponentialRetry: RetryConfig = {\n *   attempts: 5,\n *   delay: 1000,\n *   backoffMultiplier: 2, // Double delay each time\n *   maxDelay: 30000, // Cap at 30 seconds\n *   shouldRetry: (error) => {\n *     // Only retry network and timeout errors\n *     return error.name === 'NetworkError' ||\n *            error.message.includes('timeout');\n *   }\n * };\n *\n * // Usage with SDK\n * const vana = new Vana({\n *   retryConfig: exponentialRetry\n * });\n * ```\n * @category Reference\n */\nexport interface RetryConfig {\n  /** Number of retry attempts */\n  attempts: number;\n  /** Delay between retries in milliseconds */\n  delay: number;\n  /** Backoff multiplier */\n  backoffMultiplier?: number;\n  /** Maximum delay in milliseconds */\n  maxDelay?: number;\n  /** Function to determine if error should be retried */\n  shouldRetry?: (error: Error) => boolean;\n}\n\n/**\n * Cache configuration for optimizing repeated data fetches.\n *\n * @remarks\n * Configures in-memory caching behavior to reduce redundant API calls and\n * improve performance. The cache automatically evicts expired entries based\n * on TTL and removes least-recently-used items when maxSize is reached.\n * Use appropriate TTL values based on your data freshness requirements.\n *\n * @example\n * ```typescript\n * // Short-lived cache for frequently changing data\n * const userCache: CacheConfig = {\n *   ttl: 60000, // 1 minute\n *   maxSize: 100, // Store up to 100 users\n *   prefix: 'user:' // Cache keys like 'user:123'\n * };\n *\n * // Long-lived cache for stable data\n * const schemaCache: CacheConfig = {\n *   ttl: 3600000, // 1 hour\n *   maxSize: 1000, // Store up to 1000 schemas\n *   prefix: 'schema:'\n * };\n *\n * // Disable caching by setting TTL to 0\n * const noCache: CacheConfig = {\n *   ttl: 0 // No caching\n * };\n * ```\n * @category Reference\n */\nexport interface CacheConfig {\n  /** Cache TTL in milliseconds */\n  ttl: number;\n  /** Maximum cache size */\n  maxSize?: number;\n  /** Cache key prefix */\n  prefix?: string;\n}\n\n/**\n * Validation result for data integrity checks and schema validation.\n *\n * @remarks\n * Provides detailed feedback about validation outcomes, distinguishing between\n * errors (which prevent processing) and warnings (which indicate potential issues).\n * Used throughout the SDK for validating permissions, file formats, schemas,\n * and API parameters before operations.\n *\n * @example\n * ```typescript\n * // Validating user input\n * function validateFileUpload(file: File): ValidationResult {\n *   const errors: string[] = [];\n *   const warnings: string[] = [];\n *\n *   // Check file size\n *   if (file.size > 100 * 1024 * 1024) {\n *     errors.push('File size exceeds 100MB limit');\n *   } else if (file.size > 50 * 1024 * 1024) {\n *     warnings.push('Large file may take time to upload');\n *   }\n *\n *   // Check file type\n *   if (!file.type.startsWith('image/')) {\n *     errors.push('Only image files are allowed');\n *   }\n *\n *   return {\n *     valid: errors.length === 0,\n *     errors,\n *     warnings\n *   };\n * }\n *\n * // Using validation result\n * const result = validateFileUpload(file);\n * if (!result.valid) {\n *   console.error('Validation failed:', result.errors.join(', '));\n * } else {\n *   if (result.warnings.length > 0) {\n *     console.warn('Warnings:', result.warnings.join(', '));\n *   }\n *   // Proceed with upload\n * }\n * ```\n * @category Reference\n */\nexport interface ValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors */\n  errors: string[];\n  /** Validation warnings */\n  warnings: string[];\n}\n\n/**\n * Status information for health checks and service monitoring.\n *\n * @remarks\n * Used to report the health status of various SDK components including\n * storage providers, RPC connections, and personal servers. The details\n * field can contain provider-specific information for debugging.\n * Timestamps use Unix epoch milliseconds.\n *\n * @example\n * ```typescript\n * // Checking storage provider health\n * const status: StatusInfo = await storage.getStatus();\n *\n * if (!status.healthy) {\n *   console.error(`Storage unhealthy: ${status.message}`);\n *   // Check how long the issue has persisted\n *   const downtime = Date.now() - status.lastCheck;\n *   if (downtime > 300000) { // 5 minutes\n *     // Switch to backup provider\n *   }\n * }\n *\n * // Detailed status with custom fields\n * const serverStatus: StatusInfo = {\n *   healthy: true,\n *   message: 'All systems operational',\n *   lastCheck: Date.now(),\n *   details: {\n *     uptime: 3600000, // 1 hour\n *     requestsServed: 1234,\n *     avgResponseTime: 145, // ms\n *     activeConnections: 23\n *   }\n * };\n * ```\n * @category Reference\n */\nexport interface StatusInfo {\n  /** Whether the service is healthy */\n  healthy: boolean;\n  /** Status message */\n  message?: string;\n  /** Last check timestamp */\n  lastCheck: number;\n  /** Additional status details */\n  details?: Record<string, unknown>;\n}\n\n/**\n * Rate limit information for API throttling and quota management.\n *\n * @remarks\n * Provides visibility into rate limiting status to help applications\n * implement appropriate backoff strategies. Rate limits protect services\n * from overload and ensure fair resource usage. Use this information\n * to pace requests and avoid hitting limits.\n *\n * @example\n * ```typescript\n * // Check rate limit before making requests\n * const rateLimit: RateLimitInfo = await api.getRateLimit();\n *\n * console.log(`Requests: ${rateLimit.requests}/${rateLimit.limit}`);\n * console.log(`Resets in: ${rateLimit.resetTime} seconds`);\n *\n * // Implement backoff if approaching limit\n * if (rateLimit.requests >= rateLimit.limit * 0.9) {\n *   console.warn('Approaching rate limit, slowing down');\n *   await new Promise(resolve =>\n *     setTimeout(resolve, rateLimit.resetTime * 1000)\n *   );\n * }\n *\n * // Calculate requests per second allowed\n * const rps = rateLimit.limit / rateLimit.window;\n * console.log(`Max ${rps} requests per second allowed`);\n * ```\n * @category Reference\n */\nexport interface RateLimitInfo {\n  /** Current request count */\n  requests: number;\n  /** Maximum requests allowed */\n  limit: number;\n  /** Time window in seconds */\n  window: number;\n  /** Time until reset in seconds */\n  resetTime: number;\n}\n\n/**\n * File upload progress tracking for user feedback and monitoring.\n *\n * @remarks\n * Provides real-time progress information during file uploads, enabling\n * applications to show progress bars and estimated completion times.\n * The speed calculation is typically based on a rolling average to\n * smooth out network fluctuations.\n *\n * @example\n * ```typescript\n * // Upload with progress tracking\n * await vana.data.upload(file, {\n *   onProgress: (progress: UploadProgress) => {\n *     // Update progress bar\n *     progressBar.style.width = `${progress.percentage}%`;\n *\n *     // Show upload speed\n *     const speedMBps = (progress.speed / 1024 / 1024).toFixed(2);\n *     speedDisplay.textContent = `${speedMBps} MB/s`;\n *\n *     // Show time remaining\n *     const minutes = Math.floor(progress.estimatedTimeRemaining / 60);\n *     const seconds = progress.estimatedTimeRemaining % 60;\n *     timeDisplay.textContent = `${minutes}:${seconds.toString().padStart(2, '0')}`;\n *\n *     // Log progress milestones\n *     if (progress.percentage === 25 ||\n *         progress.percentage === 50 ||\n *         progress.percentage === 75) {\n *       console.log(`Upload ${progress.percentage}% complete`);\n *     }\n *   }\n * });\n * ```\n * @category Reference\n */\nexport interface UploadProgress {\n  /** Bytes uploaded */\n  loaded: number;\n  /** Total bytes to upload */\n  total: number;\n  /** Upload percentage (0-100) */\n  percentage: number;\n  /** Upload speed in bytes per second */\n  speed: number;\n  /** Estimated time remaining in seconds */\n  estimatedTimeRemaining: number;\n}\n\n/**\n * Network information for blockchain connectivity and monitoring.\n *\n * @remarks\n * Provides comprehensive details about the connected blockchain network,\n * including configuration URLs and real-time status. Use this information\n * to verify network connectivity, display network details to users, and\n * construct explorer links for transactions.\n *\n * @example\n * ```typescript\n * // Get current network info\n * const network: NetworkInfo = await vana.protocol.getNetworkInfo();\n *\n * console.log(`Connected to: ${network.chainName} (ID: ${network.chainId})`);\n * console.log(`Current block: ${network.currentBlock}`);\n *\n * // Check network health\n * if (network.status !== 'healthy') {\n *   console.warn(`Network ${network.status}: consider switching RPC`);\n * }\n *\n * // Generate explorer link for transaction\n * function getExplorerLink(txHash: string): string {\n *   if (!network.explorerUrl) {\n *     return `Transaction: ${txHash}`;\n *   }\n *   return `${network.explorerUrl}/tx/${txHash}`;\n * }\n *\n * // Verify expected network\n * const EXPECTED_CHAIN_ID = 1337; // Vana testnet\n * if (network.chainId !== EXPECTED_CHAIN_ID) {\n *   throw new Error(`Wrong network! Expected ${EXPECTED_CHAIN_ID}, got ${network.chainId}`);\n * }\n * ```\n * @category Reference\n */\nexport interface NetworkInfo {\n  /** Chain ID */\n  chainId: number;\n  /** Chain name */\n  chainName: string;\n  /** RPC URL */\n  rpcUrl: string;\n  /** Block explorer URL */\n  explorerUrl?: string;\n  /** Current block number */\n  currentBlock: bigint;\n  /** Network status */\n  status: \"healthy\" | \"degraded\" | \"down\";\n}\n\n/**\n * Gas estimate information for transaction cost prediction.\n *\n * @remarks\n * Provides detailed gas pricing estimates to help users understand transaction\n * costs before execution. Supports both legacy (gasPrice) and EIP-1559\n * (maxFeePerGas) pricing models. The estimatedCost is calculated based on\n * current network conditions and may vary by the time of actual execution.\n *\n * @example\n * ```typescript\n * // Get gas estimate before transaction\n * const estimate: GasEstimate = await vana.permissions.estimateGas({\n *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   dataId: 123\n * });\n *\n * // Convert to human-readable format\n * const costInEth = Number(estimate.estimatedCost) / 1e18;\n * console.log(`Estimated cost: ${costInEth.toFixed(6)} ETH`);\n *\n * // Check if user has sufficient balance\n * const balance = await vana.protocol.getBalance(userAddress);\n * if (balance < estimate.estimatedCost) {\n *   throw new Error(`Insufficient balance. Need ${costInEth} ETH`);\n * }\n *\n * // Use estimate for transaction with buffer\n * await vana.permissions.grant(params, {\n *   gasLimit: estimate.gasLimit * 110n / 100n, // 10% buffer\n *   maxFeePerGas: estimate.maxFeePerGas,\n *   maxPriorityFeePerGas: estimate.maxPriorityFeePerGas\n * });\n * ```\n * @category Reference\n */\nexport interface GasEstimate {\n  /** Gas limit */\n  gasLimit: bigint;\n  /** Gas price */\n  gasPrice: bigint;\n  /** Max fee per gas */\n  maxFeePerGas?: bigint;\n  /** Max priority fee per gas */\n  maxPriorityFeePerGas?: bigint;\n  /** Estimated cost in wei */\n  estimatedCost: bigint;\n}\n\n/**\n * Time range parameters for filtering operations by time period.\n *\n * Used in various SDK methods to specify date/time ranges for queries,\n * analytics, and data filtering operations. Times are specified as Unix timestamps.\n *\n * @category Reference\n * @example\n * ```typescript\n * const lastWeek: TimeRange = {\n *   from: Date.now() - (7 * 24 * 60 * 60 * 1000), // 7 days ago\n *   to: Date.now()\n * };\n *\n * const permissions = await vana.permissions.getUserPermissions({\n *   timeRange: lastWeek\n * });\n * ```\n */\nexport interface TimeRange {\n  /** Start time (Unix timestamp) */\n  from?: number;\n  /** End time (Unix timestamp) */\n  to?: number;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/utils.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Makes all properties in T optional except for those in K\n *\n * @remarks\n * This utility type is useful when you want to create a variant of an interface\n * where most properties are optional, but specific properties remain required.\n * Commonly used for update operations where only certain fields must be provided.\n *\n * @example\n * ```typescript\n * interface User {\n *   id: string;\n *   name: string;\n *   email: string;\n *   age: number;\n * }\n *\n * // Only 'id' is required, all other properties are optional\n * type UserUpdate = PartialExcept<User, 'id'>;\n *\n * const update: UserUpdate = {\n *   id: '123', // Required\n *   name: 'John' // Optional\n *   // email and age are also optional\n * };\n * ```\n * @category Reference\n */\nexport type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;\n\n/**\n * Makes all properties in T required except for those in K\n *\n * @remarks\n * This utility type is useful when you want to create a variant of an interface\n * where most properties are required, but specific properties remain optional.\n * Commonly used for creation operations where most fields are mandatory.\n *\n * @example\n * ```typescript\n * interface Config {\n *   apiUrl: string;\n *   timeout?: number;\n *   retries?: number;\n *   debug?: boolean;\n * }\n *\n * // All properties required except 'debug'\n * type StrictConfig = RequiredExcept<Config, 'debug'>;\n *\n * const config: StrictConfig = {\n *   apiUrl: 'https://api.vana.com', // Required\n *   timeout: 5000, // Required (was optional, now required)\n *   retries: 3, // Required (was optional, now required)\n *   // debug remains optional\n * };\n * ```\n * @category Reference\n */\nexport type RequiredExcept<T, K extends keyof T> = Required<T> &\n  Partial<Pick<T, K>>;\n\n/**\n * Extracts the return type of a promise\n *\n * @remarks\n * This utility type unwraps the type contained within a Promise.\n * If the type is not a Promise, it returns the type unchanged.\n * Note: TypeScript 4.5+ includes a built-in Awaited type with similar functionality.\n *\n * @example\n * ```typescript\n * type AsyncString = Promise<string>;\n * type SyncString = string;\n *\n * // Extracts 'string' from Promise<string>\n * type Result1 = Awaited<AsyncString>; // string\n *\n * // Returns 'string' unchanged since it's not a Promise\n * type Result2 = Awaited<SyncString>; // string\n *\n * // Practical usage with async functions\n * async function fetchUser(): Promise<{ id: string; name: string }> {\n *   // ...\n * }\n *\n * type User = Awaited<ReturnType<typeof fetchUser>>; // { id: string; name: string }\n * ```\n * @category Reference\n */\nexport type Awaited<T> = T extends Promise<infer U> ? U : T;\n\n/**\n * Creates a type that accepts either T or a Promise<T>\n *\n * @remarks\n * This utility type is useful for functions that can work with both\n * synchronous and asynchronous values. It allows flexible APIs that\n * can accept immediate values or promises that resolve to those values.\n *\n * @example\n * ```typescript\n * // Function that accepts either a value or a promise of that value\n * async function processData(data: MaybePromise<string>): Promise<string> {\n *   // await works on both promises and regular values\n *   const resolved = await data;\n *   return resolved.toUpperCase();\n * }\n *\n * // Both calls are valid:\n * processData('hello'); // Synchronous value\n * processData(Promise.resolve('world')); // Asynchronous value\n *\n * // Common use case in SDK callbacks\n * interface StorageProvider {\n *   // Provider can implement sync or async file reading\n *   read(path: string): MaybePromise<Buffer>;\n * }\n * ```\n * @category Reference\n */\nexport type MaybePromise<T> = T | Promise<T>;\n\n/**\n * Creates a type that accepts either T or an array of T\n *\n * @remarks\n * This utility type is useful for functions that can accept either a single\n * value or an array of values, providing a more flexible API. The implementation\n * can normalize the input to always work with arrays internally.\n *\n * @example\n * ```typescript\n * // Function that accepts either a single ID or multiple IDs\n * function deleteItems(ids: MaybeArray<string>): void {\n *   // Normalize to array\n *   const idArray = Array.isArray(ids) ? ids : [ids];\n *   idArray.forEach(id => console.log(`Deleting ${id}`));\n * }\n *\n * // Both calls are valid:\n * deleteItems('item-1'); // Single item\n * deleteItems(['item-1', 'item-2', 'item-3']); // Multiple items\n *\n * // Common use case in permissions\n * interface GrantPermissionsParams {\n *   permissions: MaybeArray<Permission>;\n * }\n * ```\n * @category Reference\n */\nexport type MaybeArray<T> = T | T[];\n\n/**\n * Pagination parameters for controlling result set size and navigation.\n *\n * Used across SDK methods that return lists of items to control how many items\n * are returned and to navigate through large result sets efficiently.\n *\n * @category Reference\n * @example\n * ```typescript\n * const pagination: PaginationParams = {\n *   limit: 20, // Return 20 items\n *   offset: 40, // Skip first 40 items (page 3)\n *   cursor: 'eyJpZCI6MTIzfQ==' // Or use cursor-based pagination\n * };\n *\n * const files = await vana.data.getUserFiles({\n *   owner: userAddress,\n *   pagination\n * });\n * ```\n */\nexport interface PaginationParams {\n  /** Maximum number of items to return */\n  limit?: number;\n  /** Number of items to skip */\n  offset?: number;\n  /** Cursor for cursor-based pagination */\n  cursor?: string;\n}\n\n/**\n * Pagination result containing items and metadata for navigating large datasets.\n *\n * @remarks\n * This interface standardizes paginated responses across the SDK, providing\n * consistent metadata for implementing pagination UI components and handling\n * multi-page data fetching. Supports both offset-based and cursor-based pagination.\n *\n * @example\n * ```typescript\n * // Fetching paginated user files\n * async function getAllUserFiles(userAddress: string): Promise<File[]> {\n *   const allFiles: File[] = [];\n *   let cursor: string | undefined;\n *\n *   do {\n *     const result: PaginationResult<File> = await vana.data.getUserFiles({\n *       owner: userAddress,\n *       pagination: { limit: 50, cursor }\n *     });\n *\n *     allFiles.push(...result.items);\n *     cursor = result.nextCursor;\n *\n *     console.log(`Fetched ${result.count} of ${result.total} files`);\n *   } while (result.hasMore);\n *\n *   return allFiles;\n * }\n * ```\n * @category Reference\n */\nexport interface PaginationResult<T> {\n  /** Array of items */\n  items: T[];\n  /** Total number of items available */\n  total: number;\n  /** Number of items returned */\n  count: number;\n  /** Whether there are more items available */\n  hasMore: boolean;\n  /** Cursor for next page */\n  nextCursor?: string;\n}\n\n/**\n * Block range parameters for filtering blockchain events and transactions.\n *\n * @remarks\n * Used to specify a range of blocks when querying blockchain data.\n * Both parameters are optional - omitting fromBlock starts from genesis,\n * omitting toBlock goes to the latest block. Be cautious with large ranges\n * as they may result in heavy RPC loads or timeouts.\n *\n * @example\n * ```typescript\n * // Get events from the last 1000 blocks\n * const currentBlock = await vana.protocol.getBlockNumber();\n * const events = await vana.protocol.getEvents({\n *   blockRange: {\n *     fromBlock: currentBlock - 1000n,\n *     toBlock: currentBlock\n *   }\n * });\n *\n * // Get all historical events (use with caution)\n * const allEvents = await vana.protocol.getEvents({\n *   blockRange: {\n *     fromBlock: 0n\n *     // toBlock omitted = up to latest\n *   }\n * });\n * ```\n * @category Reference\n */\nexport interface BlockRange {\n  /** Starting block number */\n  fromBlock?: bigint;\n  /** Ending block number */\n  toBlock?: bigint;\n}\n\n/**\n * Transaction options for customizing blockchain transaction parameters.\n *\n * @remarks\n * Provides fine-grained control over transaction execution. Supports both\n * legacy (gasPrice) and EIP-1559 (maxFeePerGas) transaction types. When\n * not specified, the SDK will use appropriate defaults based on network\n * conditions. Use these options to optimize for speed or cost.\n *\n * @example\n * ```typescript\n * // High priority transaction with EIP-1559 pricing\n * await vana.permissions.grant(params, {\n *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei\n *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip\n *   timeout: 180000, // 3 minutes\n * });\n *\n * // Legacy transaction with specific gas limit\n * await vana.data.registerFile(params, {\n *   gasLimit: 500000n,\n *   gasPrice: 50n * 10n ** 9n, // 50 gwei\n *   timeout: 600000, // 10 minutes\n * });\n *\n * // Send ETH with the transaction\n * await vana.protocol.execute(params, {\n *   value: 10n ** 18n, // 1 ETH\n *   gasLimit: 21000n\n * });\n * ```\n * @category Reference\n */\nexport interface TransactionOptions {\n  /** Gas limit */\n  gasLimit?: bigint;\n  /** Gas price */\n  gasPrice?: bigint;\n  /** Max fee per gas (EIP-1559) */\n  maxFeePerGas?: bigint;\n  /** Max priority fee per gas (EIP-1559) */\n  maxPriorityFeePerGas?: bigint;\n  /** Nonce */\n  nonce?: number;\n  /** Value to send with transaction */\n  value?: bigint;\n  /** Transaction timeout in milliseconds for receipt waiting (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Transaction receipt with additional metadata for tracking transaction results.\n *\n * @remarks\n * Provides comprehensive information about executed transactions including\n * gas usage, success status, and emitted events. Use the logs array to\n * decode events emitted by smart contracts during transaction execution.\n * The receipt is available after a transaction is mined and included in a block.\n *\n * @example\n * ```typescript\n * // Execute transaction and wait for receipt\n * const receipt = await vana.permissions.grant({\n *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   dataId: 123\n * });\n *\n * // Check transaction success\n * if (receipt.status === 'success') {\n *   console.log(`Gas used: ${receipt.gasUsed}`);\n *   console.log(`Block: ${receipt.blockNumber}`);\n *\n *   // Decode events from logs\n *   receipt.logs.forEach(log => {\n *     if (log.topics[0] === PERMISSION_GRANTED_TOPIC) {\n *       console.log('Permission granted event detected');\n *     }\n *   });\n * } else {\n *   console.error('Transaction reverted');\n * }\n * ```\n * @category Reference\n */\nexport interface TransactionReceipt {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Block number */\n  blockNumber: bigint;\n  /** Block hash */\n  blockHash: Hash;\n  /** Gas used */\n  gasUsed: bigint;\n  /** Transaction status */\n  status: \"success\" | \"reverted\";\n  /** Contract address if contract deployment */\n  contractAddress?: Address;\n  /** Event logs */\n  logs: Array<{\n    address: Address;\n    topics: Hash[];\n    data: string;\n  }>;\n}\n\n/**\n * Response wrapper for API results providing consistent error handling.\n *\n * @remarks\n * Standardizes API responses across the SDK, making it easy to handle\n * both successful and failed requests. The generic type parameter T\n * represents the expected data type for successful responses. Check\n * the success flag before accessing data to ensure type safety.\n *\n * @example\n * ```typescript\n * // Handling API responses\n * async function fetchUserData(userId: string): Promise<User | null> {\n *   const response: ApiResponse<User> = await api.getUser(userId);\n *\n *   if (response.success) {\n *     console.log('User fetched:', response.data.name);\n *     // Access metadata if available\n *     if (response.metadata?.cached) {\n *       console.log('Data was cached');\n *     }\n *     return response.data;\n *   } else {\n *     console.error('Failed to fetch user:', response.error);\n *     return null;\n *   }\n * }\n *\n * // Type-safe error handling\n * interface UserData {\n *   id: string;\n *   name: string;\n * }\n *\n * const result: ApiResponse<UserData> = await api.call('/users/123');\n * if (result.success) {\n *   // TypeScript knows result.data is UserData here\n *   console.log(result.data.name);\n * }\n * ```\n * @category Reference\n */\nexport interface ApiResponse<T> {\n  /** Response data */\n  data: T;\n  /** Success status */\n  success: boolean;\n  /** Error message if not successful */\n  error?: string;\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Retry configuration for handling transient failures with exponential backoff.\n *\n * @remarks\n * Configures automatic retry behavior for operations that may fail due to\n * temporary issues like network problems or rate limits. Supports exponential\n * backoff to avoid overwhelming services. The shouldRetry function allows\n * custom logic to determine which errors warrant a retry attempt.\n *\n * @example\n * ```typescript\n * // Simple retry configuration\n * const basicRetry: RetryConfig = {\n *   attempts: 3,\n *   delay: 1000 // 1 second between retries\n * };\n *\n * // Exponential backoff configuration\n * const exponentialRetry: RetryConfig = {\n *   attempts: 5,\n *   delay: 1000,\n *   backoffMultiplier: 2, // Double delay each time\n *   maxDelay: 30000, // Cap at 30 seconds\n *   shouldRetry: (error) => {\n *     // Only retry network and timeout errors\n *     return error.name === 'NetworkError' ||\n *            error.message.includes('timeout');\n *   }\n * };\n *\n * // Usage with SDK\n * const vana = new Vana({\n *   retryConfig: exponentialRetry\n * });\n * ```\n * @category Reference\n */\nexport interface RetryConfig {\n  /** Number of retry attempts */\n  attempts: number;\n  /** Delay between retries in milliseconds */\n  delay: number;\n  /** Backoff multiplier */\n  backoffMultiplier?: number;\n  /** Maximum delay in milliseconds */\n  maxDelay?: number;\n  /** Function to determine if error should be retried */\n  shouldRetry?: (error: Error) => boolean;\n}\n\n/**\n * Cache configuration for optimizing repeated data fetches.\n *\n * @remarks\n * Configures in-memory caching behavior to reduce redundant API calls and\n * improve performance. The cache automatically evicts expired entries based\n * on TTL and removes least-recently-used items when maxSize is reached.\n * Use appropriate TTL values based on your data freshness requirements.\n *\n * @example\n * ```typescript\n * // Short-lived cache for frequently changing data\n * const userCache: CacheConfig = {\n *   ttl: 60000, // 1 minute\n *   maxSize: 100, // Store up to 100 users\n *   prefix: 'user:' // Cache keys like 'user:123'\n * };\n *\n * // Long-lived cache for stable data\n * const schemaCache: CacheConfig = {\n *   ttl: 3600000, // 1 hour\n *   maxSize: 1000, // Store up to 1000 schemas\n *   prefix: 'schema:'\n * };\n *\n * // Disable caching by setting TTL to 0\n * const noCache: CacheConfig = {\n *   ttl: 0 // No caching\n * };\n * ```\n * @category Reference\n */\nexport interface CacheConfig {\n  /** Cache TTL in milliseconds */\n  ttl: number;\n  /** Maximum cache size */\n  maxSize?: number;\n  /** Cache key prefix */\n  prefix?: string;\n}\n\n/**\n * Validation result for data integrity checks and schema validation.\n *\n * @remarks\n * Provides detailed feedback about validation outcomes, distinguishing between\n * errors (which prevent processing) and warnings (which indicate potential issues).\n * Used throughout the SDK for validating permissions, file formats, schemas,\n * and API parameters before operations.\n *\n * @example\n * ```typescript\n * // Validating user input\n * function validateFileUpload(file: File): ValidationResult {\n *   const errors: string[] = [];\n *   const warnings: string[] = [];\n *\n *   // Check file size\n *   if (file.size > 100 * 1024 * 1024) {\n *     errors.push('File size exceeds 100MB limit');\n *   } else if (file.size > 50 * 1024 * 1024) {\n *     warnings.push('Large file may take time to upload');\n *   }\n *\n *   // Check file type\n *   if (!file.type.startsWith('image/')) {\n *     errors.push('Only image files are allowed');\n *   }\n *\n *   return {\n *     valid: errors.length === 0,\n *     errors,\n *     warnings\n *   };\n * }\n *\n * // Using validation result\n * const result = validateFileUpload(file);\n * if (!result.valid) {\n *   console.error('Validation failed:', result.errors.join(', '));\n * } else {\n *   if (result.warnings.length > 0) {\n *     console.warn('Warnings:', result.warnings.join(', '));\n *   }\n *   // Proceed with upload\n * }\n * ```\n * @category Reference\n */\nexport interface ValidationResult {\n  /** Whether validation passed */\n  valid: boolean;\n  /** Validation errors */\n  errors: string[];\n  /** Validation warnings */\n  warnings: string[];\n}\n\n/**\n * Status information for health checks and service monitoring.\n *\n * @remarks\n * Used to report the health status of various SDK components including\n * storage providers, RPC connections, and personal servers. The details\n * field can contain provider-specific information for debugging.\n * Timestamps use Unix epoch milliseconds.\n *\n * @example\n * ```typescript\n * // Checking storage provider health\n * const status: StatusInfo = await storage.getStatus();\n *\n * if (!status.healthy) {\n *   console.error(`Storage unhealthy: ${status.message}`);\n *   // Check how long the issue has persisted\n *   const downtime = Date.now() - status.lastCheck;\n *   if (downtime > 300000) { // 5 minutes\n *     // Switch to backup provider\n *   }\n * }\n *\n * // Detailed status with custom fields\n * const serverStatus: StatusInfo = {\n *   healthy: true,\n *   message: 'All systems operational',\n *   lastCheck: Date.now(),\n *   details: {\n *     uptime: 3600000, // 1 hour\n *     requestsServed: 1234,\n *     avgResponseTime: 145, // ms\n *     activeConnections: 23\n *   }\n * };\n * ```\n * @category Reference\n */\nexport interface StatusInfo {\n  /** Whether the service is healthy */\n  healthy: boolean;\n  /** Status message */\n  message?: string;\n  /** Last check timestamp */\n  lastCheck: number;\n  /** Additional status details */\n  details?: Record<string, unknown>;\n}\n\n/**\n * Rate limit information for API throttling and quota management.\n *\n * @remarks\n * Provides visibility into rate limiting status to help applications\n * implement appropriate backoff strategies. Rate limits protect services\n * from overload and ensure fair resource usage. Use this information\n * to pace requests and avoid hitting limits.\n *\n * @example\n * ```typescript\n * // Check rate limit before making requests\n * const rateLimit: RateLimitInfo = await api.getRateLimit();\n *\n * console.log(`Requests: ${rateLimit.requests}/${rateLimit.limit}`);\n * console.log(`Resets in: ${rateLimit.resetTime} seconds`);\n *\n * // Implement backoff if approaching limit\n * if (rateLimit.requests >= rateLimit.limit * 0.9) {\n *   console.warn('Approaching rate limit, slowing down');\n *   await new Promise(resolve =>\n *     setTimeout(resolve, rateLimit.resetTime * 1000)\n *   );\n * }\n *\n * // Calculate requests per second allowed\n * const rps = rateLimit.limit / rateLimit.window;\n * console.log(`Max ${rps} requests per second allowed`);\n * ```\n * @category Reference\n */\nexport interface RateLimitInfo {\n  /** Current request count */\n  requests: number;\n  /** Maximum requests allowed */\n  limit: number;\n  /** Time window in seconds */\n  window: number;\n  /** Time until reset in seconds */\n  resetTime: number;\n}\n\n/**\n * File upload progress tracking for user feedback and monitoring.\n *\n * @remarks\n * Provides real-time progress information during file uploads, enabling\n * applications to show progress bars and estimated completion times.\n * The speed calculation is typically based on a rolling average to\n * smooth out network fluctuations.\n *\n * @example\n * ```typescript\n * // Upload with progress tracking\n * await vana.data.upload(file, {\n *   onProgress: (progress: UploadProgress) => {\n *     // Update progress bar\n *     progressBar.style.width = `${progress.percentage}%`;\n *\n *     // Show upload speed\n *     const speedMBps = (progress.speed / 1024 / 1024).toFixed(2);\n *     speedDisplay.textContent = `${speedMBps} MB/s`;\n *\n *     // Show time remaining\n *     const minutes = Math.floor(progress.estimatedTimeRemaining / 60);\n *     const seconds = progress.estimatedTimeRemaining % 60;\n *     timeDisplay.textContent = `${minutes}:${seconds.toString().padStart(2, '0')}`;\n *\n *     // Log progress milestones\n *     if (progress.percentage === 25 ||\n *         progress.percentage === 50 ||\n *         progress.percentage === 75) {\n *       console.log(`Upload ${progress.percentage}% complete`);\n *     }\n *   }\n * });\n * ```\n * @category Reference\n */\nexport interface UploadProgress {\n  /** Bytes uploaded */\n  loaded: number;\n  /** Total bytes to upload */\n  total: number;\n  /** Upload percentage (0-100) */\n  percentage: number;\n  /** Upload speed in bytes per second */\n  speed: number;\n  /** Estimated time remaining in seconds */\n  estimatedTimeRemaining: number;\n}\n\n/**\n * Network information for blockchain connectivity and monitoring.\n *\n * @remarks\n * Provides comprehensive details about the connected blockchain network,\n * including configuration URLs and real-time status. Use this information\n * to verify network connectivity, display network details to users, and\n * construct explorer links for transactions.\n *\n * @example\n * ```typescript\n * // Get current network info\n * const network: NetworkInfo = await vana.protocol.getNetworkInfo();\n *\n * console.log(`Connected to: ${network.chainName} (ID: ${network.chainId})`);\n * console.log(`Current block: ${network.currentBlock}`);\n *\n * // Check network health\n * if (network.status !== 'healthy') {\n *   console.warn(`Network ${network.status}: consider switching RPC`);\n * }\n *\n * // Generate explorer link for transaction\n * function getExplorerLink(txHash: string): string {\n *   if (!network.explorerUrl) {\n *     return `Transaction: ${txHash}`;\n *   }\n *   return `${network.explorerUrl}/tx/${txHash}`;\n * }\n *\n * // Verify expected network\n * const EXPECTED_CHAIN_ID = 1337; // Vana testnet\n * if (network.chainId !== EXPECTED_CHAIN_ID) {\n *   throw new Error(`Wrong network! Expected ${EXPECTED_CHAIN_ID}, got ${network.chainId}`);\n * }\n * ```\n * @category Reference\n */\nexport interface NetworkInfo {\n  /** Chain ID */\n  chainId: number;\n  /** Chain name */\n  chainName: string;\n  /** RPC URL */\n  rpcUrl: string;\n  /** Block explorer URL */\n  explorerUrl?: string;\n  /** Current block number */\n  currentBlock: bigint;\n  /** Network status */\n  status: \"healthy\" | \"degraded\" | \"down\";\n}\n\n/**\n * Gas estimate information for transaction cost prediction.\n *\n * @remarks\n * Provides detailed gas pricing estimates to help users understand transaction\n * costs before execution. Supports both legacy (gasPrice) and EIP-1559\n * (maxFeePerGas) pricing models. The estimatedCost is calculated based on\n * current network conditions and may vary by the time of actual execution.\n *\n * @example\n * ```typescript\n * // Get gas estimate before transaction\n * const estimate: GasEstimate = await vana.permissions.estimateGas({\n *   grantee: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   dataId: 123\n * });\n *\n * // Convert to human-readable format\n * const costInEth = Number(estimate.estimatedCost) / 1e18;\n * console.log(`Estimated cost: ${costInEth.toFixed(6)} ETH`);\n *\n * // Check if user has sufficient balance\n * const balance = await vana.protocol.getBalance(userAddress);\n * if (balance < estimate.estimatedCost) {\n *   throw new Error(`Insufficient balance. Need ${costInEth} ETH`);\n * }\n *\n * // Use estimate for transaction with buffer\n * await vana.permissions.grant(params, {\n *   gasLimit: estimate.gasLimit * 110n / 100n, // 10% buffer\n *   maxFeePerGas: estimate.maxFeePerGas,\n *   maxPriorityFeePerGas: estimate.maxPriorityFeePerGas\n * });\n * ```\n * @category Reference\n */\nexport interface GasEstimate {\n  /** Gas limit */\n  gasLimit: bigint;\n  /** Gas price */\n  gasPrice: bigint;\n  /** Max fee per gas */\n  maxFeePerGas?: bigint;\n  /** Max priority fee per gas */\n  maxPriorityFeePerGas?: bigint;\n  /** Estimated cost in wei */\n  estimatedCost: bigint;\n}\n\n/**\n * Time range parameters for filtering operations by time period.\n *\n * Used in various SDK methods to specify date/time ranges for queries,\n * analytics, and data filtering operations. Times are specified as Unix timestamps.\n *\n * @category Reference\n * @example\n * ```typescript\n * const lastWeek: TimeRange = {\n *   from: Date.now() - (7 * 24 * 60 * 60 * 1000), // 7 days ago\n *   to: Date.now()\n * };\n *\n * const permissions = await vana.permissions.getUserPermissions({\n *   timeRange: lastWeek\n * });\n * ```\n */\nexport interface TimeRange {\n  /** Start time (Unix timestamp) */\n  from?: number;\n  /** End time (Unix timestamp) */\n  to?: number;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/utils.d.ts

@@ -1,5 +1,4 @@
-import { Hash, Address } from 'viem';
-
+import type { Address, Hash } from "viem";
 /**
  * Makes all properties in T optional except for those in K
  *
@@ -28,7 +27,7 @@ import { Hash, Address } from 'viem';
  * ```
  * @category Reference
  */
-type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;
+export type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;
 /**
  * Makes all properties in T required except for those in K
  *
@@ -58,7 +57,7 @@ type PartialExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;
  * ```
  * @category Reference
  */
-type RequiredExcept<T, K extends keyof T> = Required<T> & Partial<Pick<T, K>>;
+export type RequiredExcept<T, K extends keyof T> = Required<T> & Partial<Pick<T, K>>;
 /**
  * Extracts the return type of a promise
  *
@@ -87,7 +86,7 @@ type RequiredExcept<T, K extends keyof T> = Required<T> & Partial<Pick<T, K>>;
  * ```
  * @category Reference
  */
-type Awaited<T> = T extends Promise<infer U> ? U : T;
+export type Awaited<T> = T extends Promise<infer U> ? U : T;
 /**
  * Creates a type that accepts either T or a Promise<T>
  *
@@ -117,7 +116,7 @@ type Awaited<T> = T extends Promise<infer U> ? U : T;
  * ```
  * @category Reference
  */
-type MaybePromise<T> = T | Promise<T>;
+export type MaybePromise<T> = T | Promise<T>;
 /**
  * Creates a type that accepts either T or an array of T
  *
@@ -146,7 +145,7 @@ type MaybePromise<T> = T | Promise<T>;
  * ```
  * @category Reference
  */
-type MaybeArray<T> = T | T[];
+export type MaybeArray<T> = T | T[];
 /**
  * Pagination parameters for controlling result set size and navigation.
  *
@@ -168,7 +167,7 @@ type MaybeArray<T> = T | T[];
  * });
  * ```
  */
-interface PaginationParams {
+export interface PaginationParams {
     /** Maximum number of items to return */
     limit?: number;
     /** Number of items to skip */
@@ -208,7 +207,7 @@ interface PaginationParams {
  * ```
  * @category Reference
  */
-interface PaginationResult<T> {
+export interface PaginationResult<T> {
     /** Array of items */
     items: T[];
     /** Total number of items available */
@@ -250,7 +249,7 @@ interface PaginationResult<T> {
  * ```
  * @category Reference
  */
-interface BlockRange {
+export interface BlockRange {
     /** Starting block number */
     fromBlock?: bigint;
     /** Ending block number */
@@ -271,12 +270,14 @@ interface BlockRange {
  * await vana.permissions.grant(params, {
  *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei
  *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip
+ *   timeout: 180000, // 3 minutes
  * });
  *
  * // Legacy transaction with specific gas limit
  * await vana.data.registerFile(params, {
  *   gasLimit: 500000n,
- *   gasPrice: 50n * 10n ** 9n // 50 gwei
+ *   gasPrice: 50n * 10n ** 9n, // 50 gwei
+ *   timeout: 600000, // 10 minutes
  * });
  *
  * // Send ETH with the transaction
@@ -287,7 +288,7 @@ interface BlockRange {
  * ```
  * @category Reference
  */
-interface TransactionOptions {
+export interface TransactionOptions {
     /** Gas limit */
     gasLimit?: bigint;
     /** Gas price */
@@ -300,6 +301,8 @@ interface TransactionOptions {
     nonce?: number;
     /** Value to send with transaction */
     value?: bigint;
+    /** Transaction timeout in milliseconds for receipt waiting (default: 30000) */
+    timeout?: number;
 }
 /**
  * Transaction receipt with additional metadata for tracking transaction results.
@@ -335,7 +338,7 @@ interface TransactionOptions {
  * ```
  * @category Reference
  */
-interface TransactionReceipt {
+export interface TransactionReceipt {
     /** Transaction hash */
     transactionHash: Hash;
     /** Block number */
@@ -397,7 +400,7 @@ interface TransactionReceipt {
  * ```
  * @category Reference
  */
-interface ApiResponse<T> {
+export interface ApiResponse<T> {
     /** Response data */
     data: T;
     /** Success status */
@@ -444,7 +447,7 @@ interface ApiResponse<T> {
  * ```
  * @category Reference
  */
-interface RetryConfig {
+export interface RetryConfig {
     /** Number of retry attempts */
     attempts: number;
     /** Delay between retries in milliseconds */
@@ -488,7 +491,7 @@ interface RetryConfig {
  * ```
  * @category Reference
  */
-interface CacheConfig {
+export interface CacheConfig {
     /** Cache TTL in milliseconds */
     ttl: number;
     /** Maximum cache size */
@@ -544,7 +547,7 @@ interface CacheConfig {
  * ```
  * @category Reference
  */
-interface ValidationResult {
+export interface ValidationResult {
     /** Whether validation passed */
     valid: boolean;
     /** Validation errors */
@@ -590,7 +593,7 @@ interface ValidationResult {
  * ```
  * @category Reference
  */
-interface StatusInfo {
+export interface StatusInfo {
     /** Whether the service is healthy */
     healthy: boolean;
     /** Status message */
@@ -631,7 +634,7 @@ interface StatusInfo {
  * ```
  * @category Reference
  */
-interface RateLimitInfo {
+export interface RateLimitInfo {
     /** Current request count */
     requests: number;
     /** Maximum requests allowed */
@@ -678,7 +681,7 @@ interface RateLimitInfo {
  * ```
  * @category Reference
  */
-interface UploadProgress {
+export interface UploadProgress {
     /** Bytes uploaded */
     loaded: number;
     /** Total bytes to upload */
@@ -728,7 +731,7 @@ interface UploadProgress {
  * ```
  * @category Reference
  */
-interface NetworkInfo {
+export interface NetworkInfo {
     /** Chain ID */
     chainId: number;
     /** Chain name */
@@ -778,7 +781,7 @@ interface NetworkInfo {
  * ```
  * @category Reference
  */
-interface GasEstimate {
+export interface GasEstimate {
     /** Gas limit */
     gasLimit: bigint;
     /** Gas price */
@@ -809,11 +812,9 @@ interface GasEstimate {
  * });
  * ```
  */
-interface TimeRange {
+export interface TimeRange {
     /** Start time (Unix timestamp) */
     from?: number;
     /** End time (Unix timestamp) */
     to?: number;
 }
-
-export type { ApiResponse, Awaited, BlockRange, CacheConfig, GasEstimate, MaybeArray, MaybePromise, NetworkInfo, PaginationParams, PaginationResult, PartialExcept, RateLimitInfo, RequiredExcept, RetryConfig, StatusInfo, TimeRange, TransactionOptions, TransactionReceipt, UploadProgress, ValidationResult };

package/dist/types.d.ts

@@ -1,43 +1,9 @@
-export { BaseConfig, BaseConfigWithStorage, ChainConfig, ChainConfigWithStorage, ConfigValidationOptions, ConfigValidationResult, DownloadRelayerCallbacks, RelayerCallbacks, RuntimeConfig, StorageConfig, StorageRequiredMarker, VanaConfig, VanaConfigWithStorage, WalletConfig, WalletConfigWithStorage, hasStorageConfig, isChainConfig, isWalletConfig } from './types/config.js';
-export { VanaChain, VanaChainId, isVanaChain, isVanaChainId } from './types/chains.js';
-export { ContractAddresses, ContractDeployment, ContractInfo, ContractMethodParams, ContractMethodReturnType, VanaContractInstance, VanaContractName } from './types/contracts.js';
-export { StorageError, StorageFile, StorageListOptions, StorageProvider, StorageProviderConfig, StorageUploadResult } from './types/storage.js';
-export { AddRefinerParams, AddRefinerResult, AddSchemaParams, AddSchemaResult, BatchUploadParams, BatchUploadResult, CompleteSchema, DeleteFileParams, DeleteFileResult, DownloadFileParams, DownloadFileResult, EncryptedUploadParams, EncryptionInfo, FileAccessPermissions, FileMetadata, FilePermissionParams, FileSharingConfig, GetFileParams, GetUserFilesParams, GetUserTrustedServersParams, LegacyPermissionParams, Refiner, Schema, SchemaMetadata, TrustedServer, UnencryptedUploadParams, UpdateSchemaIdParams, UpdateSchemaIdResult, UploadEncryptedFileResult, UploadFileParams, UploadFileResult, UploadParams, UploadResult } from './types/data.js';
-export { CreateSchemaParams, CreateSchemaResult } from './controllers/schemas.js';
-export { DataSchema, SchemaValidationError, SchemaValidator, fetchAndValidateSchema, validateDataAgainstSchema, validateDataSchemaAgainstMetaSchema } from './utils/schemaValidation.js';
-export { AddAndTrustServerInput, AddAndTrustServerParams, AddAndTrustServerTypedData, BatchServerInfoResult, CheckPermissionParams, GenericTypedData, GetUserPermissionsOptions, GrantFile, GrantedPermission, Grantee, GranteeInfo, GranteeQueryOptions, OnChainPermissionGrant, PaginatedGrantees, PaginatedTrustedServers, Permission, PermissionAnalytics, PermissionCheckResult, PermissionEvent, PermissionGrantDomain, PermissionGrantMessage, PermissionGrantTypedData, PermissionInfo, PermissionInputMessage, PermissionOperation, PermissionQueryResult, PermissionStatus, QueryPermissionsParams, RegisterGranteeInput, RegisterGranteeParams, RegisterGranteeTypedData, RevokePermissionInput, RevokePermissionParams, RevokePermissionTypedData, Server, ServerFilesAndPermissionParams, ServerFilesAndPermissionTypedData, ServerInfo, ServerTrustStatus, SimplifiedPermissionMessage, SpecificTypedData, TrustServerInput, TrustServerParams, TrustServerTypedData, TrustedServerInfo, TrustedServerQueryOptions, TypedDataPrimaryType, UntrustServerInput, UntrustServerParams, UntrustServerTypedData } from './types/permissions.js';
-export { CreateOperationParams, InitPersonalServerParams, PersonalServerIdentity, PostRequestParams } from './types/personal.js';
-export { AuthenticationErrorResponse, BlockchainErrorResponse, ComputeErrorResponse, CreateOperationRequest, CreateOperationResponse, DecryptionErrorResponse, ErrorResponse, FileAccessErrorResponse, GetOperationResponse, GrantValidationErrorResponse, IdentityResponseModel, InternalServerErrorResponse, NotFoundErrorResponse, OperationErrorResponse, PersonalServerModel, ValidationErrorResponse } from './generated/server/server-exports.js';
-export { APIResponse, PinataListResponse, PinataPin, PinataUploadResponse, ReplicateAPIResponse, ReplicateStatus, isAPIResponse, isReplicateAPIResponse, parseReplicateOutput, safeParseJSON } from './types/external-apis.js';
-export { RelayerConfig, RelayerErrorResponse, RelayerMetrics, RelayerQueueInfo, RelayerRequestOptions, RelayerStatus, RelayerStorageResponse, RelayerStoreParams, RelayerSubmitParams, RelayerTransactionResponse, RelayerTransactionStatus, RelayerWebhookConfig, RelayerWebhookPayload } from './types/relayer.js';
-export { ApiResponse, Awaited, BlockRange, CacheConfig, GasEstimate, MaybeArray, MaybePromise, NetworkInfo, PaginationParams, PaginationResult, PartialExcept, RateLimitInfo, RequiredExcept, StatusInfo, TimeRange, TransactionOptions, TransactionReceipt, UploadProgress, ValidationResult } from './types/utils.js';
-export { AllKeys, AsyncResult, Brand, Cache, ConditionalOptional, ContractCall, Controller, ControllerContext, DeepPartial, DeepReadonly, EventFilter, EventLog, Factory, GenericRequest, GenericResponse, Middleware, Nominal, NonNullable, Observable, Observer, OmitByType, OptionalKeys, PickByType, Plugin, PromiseResult, RateLimiterConfig, Repository, RequireKeys, RetryConfig, Service, StateMachine, Transformer, Validator } from './types/generics.js';
-import { Address } from 'viem';
-export { Abi, Account, Address, Chain, GetContractReturnType, Hash, PublicClient, WalletClient } from 'viem';
-export { $defs, components as ServerComponents, $defs as ServerDefs, operations as ServerOperations, paths as ServerPaths, webhooks as ServerWebhooks, components, operations, paths, webhooks } from './generated/server/server.js';
-import './permissions-eo8YeLGf.js';
-import './types/operations.js';
-import './config/eventMappings.js';
-import './generated/abi/index.js';
-import './generated/abi/DataPortabilityPermissionsImplementation.js';
-import './generated/abi/DataPortabilityServersImplementation.js';
-import './generated/abi/DataPortabilityGranteesImplementation.js';
-import './generated/abi/VanaEpochImplementation.js';
-import './generated/abi/DLPRegistryImplementation.js';
-import './generated/abi/DLPTreasuryImplementation.js';
-import './generated/abi/DLPRewardDeployerTreasuryImplementation.js';
-import './generated/abi/DLPPerformanceImplementation.js';
-import './generated/abi/DLPRewardDeployerImplementation.js';
-import './generated/abi/DLPRootImplementation.js';
-import './generated/abi/DataLiquidityPoolImplementation.js';
-import './generated/abi/DLPRegistryTreasuryImplementation.js';
-import './storage/manager.js';
-import './platform/interface.js';
-
+export * from "./types/index";
+import type { Address } from "viem";
 /**
  * Represents a user's registered data file.
  */
-interface UserFile {
+export interface UserFile {
     /** Unique identifier for the file */
     id: number;
     /** URL where the file is stored */
@@ -50,7 +16,7 @@ interface UserFile {
 /**
  * Parameters for the `vana.permissions.grant` method.
  */
-interface GrantPermissionParams {
+export interface GrantPermissionParams {
     /** The on-chain identity of the application */
     grantee: Address;
     /** The class of computation, e.g., "llm_inference" */
@@ -62,5 +28,3 @@ interface GrantPermissionParams {
     /** Optional pre-stored grant URL to avoid duplicate IPFS storage */
     grantUrl?: string;
 }
-
-export type { GrantPermissionParams, UserFile };

package/dist/utils/__tests__/parseTransaction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/pojo-serialization.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/signatureCache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/transaction-edge-cases.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/transactionHelpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/urlResolver.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for URL resolver utilities
+ */
+export {};

package/dist/utils/blockchain/registry.cjs

@@ -26,7 +26,7 @@ var import_viem = require("viem");
 var import_addresses = require("../../config/addresses");
 var import_abi = require("../../generated/abi");
 async function fetchSchemaFromChain(context, schemaId) {
-  const chainId = context.walletClient.chain?.id;
+  const chainId = context.walletClient?.chain?.id ?? context.publicClient.chain?.id;
   if (!chainId) {
     throw new Error("Chain ID not available");
   }
@@ -56,7 +56,7 @@ async function fetchSchemaFromChain(context, schemaId) {
   };
 }
 async function fetchSchemaCountFromChain(context) {
-  const chainId = context.walletClient.chain?.id;
+  const chainId = context.walletClient?.chain?.id ?? context.publicClient.chain?.id;
   if (!chainId) {
     throw new Error("Chain ID not available");
   }

package/dist/utils/blockchain/registry.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/utils/blockchain/registry.ts"],"sourcesContent":["import { getContract } from \"viem\";\nimport { PublicClient, WalletClient } from \"viem\";\nimport { getContractAddress } from \"../../config/addresses\";\nimport { getAbi } from \"../../generated/abi\";\nimport { SchemaMetadata } from \"../../types/index\";\n\n/**\n * Shared context for blockchain operations.\n * Only includes the minimal required fields to avoid coupling.\n */\ninterface BlockchainContext {\n  walletClient: WalletClient;\n  publicClient: PublicClient;\n}\n\n/**\n * Contract data structure returned by the blockchain.\n *\n * @internal\n */\ninterface SchemaContractData {\n  name: string;\n  dialect: string;\n  definitionUrl: string;\n}\n\n/**\n * Fetches schema metadata from the blockchain by its ID.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @param schemaId - The ID of the schema to fetch\n * @returns The schema metadata with id, name, dialect, and definitionUrl\n * @throws Error if chain ID is not available, schema not found, or data is incomplete\n *\n * @internal\n */\nexport async function fetchSchemaFromChain(\n  context: BlockchainContext,\n  schemaId: number,\n): Promise<SchemaMetadata> {\n  const chainId = context.walletClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const schemaData = await dataRefinerRegistry.read.schemas([BigInt(schemaId)]);\n\n  if (!schemaData) {\n    throw new Error(`Schema with ID ${schemaId} not found`);\n  }\n\n  const schemaObj = schemaData as unknown as SchemaContractData;\n\n  if (!schemaObj.name || !schemaObj.dialect || !schemaObj.definitionUrl) {\n    throw new Error(\"Incomplete schema data\");\n  }\n\n  return {\n    id: schemaId,\n    name: schemaObj.name,\n    dialect: schemaObj.dialect as \"json\" | \"sqlite\",\n    definitionUrl: schemaObj.definitionUrl,\n  };\n}\n\n/**\n * Fetches the total count of schemas from the blockchain.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @returns The total number of schemas\n * @throws Error if chain ID is not available or operation fails\n *\n * @internal\n */\nexport async function fetchSchemaCountFromChain(\n  context: BlockchainContext,\n): Promise<number> {\n  const chainId = context.walletClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const count = await dataRefinerRegistry.read.schemasCount();\n  return Number(count);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAA4B;AAE5B,uBAAmC;AACnC,iBAAuB;AAiCvB,eAAsB,qBACpB,SACA,UACyB;AACzB,QAAM,UAAU,QAAQ,aAAa,OAAO;AAC5C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,iCAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,6BAAyB,mBAAO,qBAAqB;AAE3D,QAAM,0BAAsB,yBAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,aAAa,MAAM,oBAAoB,KAAK,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE5E,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kBAAkB,QAAQ,YAAY;AAAA,EACxD;AAEA,QAAM,YAAY;AAElB,MAAI,CAAC,UAAU,QAAQ,CAAC,UAAU,WAAW,CAAC,UAAU,eAAe;AACrE,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM,UAAU;AAAA,IAChB,SAAS,UAAU;AAAA,IACnB,eAAe,UAAU;AAAA,EAC3B;AACF;AAWA,eAAsB,0BACpB,SACiB;AACjB,QAAM,UAAU,QAAQ,aAAa,OAAO;AAC5C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,iCAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,6BAAyB,mBAAO,qBAAqB;AAE3D,QAAM,0BAAsB,yBAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,QAAQ,MAAM,oBAAoB,KAAK,aAAa;AAC1D,SAAO,OAAO,KAAK;AACrB;","names":[]}
+{"version":3,"sources":["../../../src/utils/blockchain/registry.ts"],"sourcesContent":["import { getContract } from \"viem\";\nimport type { PublicClient, WalletClient } from \"viem\";\nimport { getContractAddress } from \"../../config/addresses\";\nimport { getAbi } from \"../../generated/abi\";\nimport type { SchemaMetadata } from \"../../types/index\";\n\n/**\n * Shared context for blockchain operations.\n * Only includes the minimal required fields to avoid coupling.\n */\ninterface BlockchainContext {\n  walletClient?: WalletClient;\n  publicClient: PublicClient;\n}\n\n/**\n * Contract data structure returned by the blockchain.\n *\n * @internal\n */\ninterface SchemaContractData {\n  name: string;\n  dialect: string;\n  definitionUrl: string;\n}\n\n/**\n * Fetches schema metadata from the blockchain by its ID.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @param schemaId - The ID of the schema to fetch\n * @returns The schema metadata with id, name, dialect, and definitionUrl\n * @throws Error if chain ID is not available, schema not found, or data is incomplete\n *\n * @internal\n */\nexport async function fetchSchemaFromChain(\n  context: BlockchainContext,\n  schemaId: number,\n): Promise<SchemaMetadata> {\n  const chainId =\n    context.walletClient?.chain?.id ?? context.publicClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const schemaData = await dataRefinerRegistry.read.schemas([BigInt(schemaId)]);\n\n  if (!schemaData) {\n    throw new Error(`Schema with ID ${schemaId} not found`);\n  }\n\n  // TODO(TYPES): Contract read returns unknown type from viem library.\n  // Future improvement: Create typed contract interface when viem adds support\n  // or implement a contract type generator from ABI definitions.\n  const schemaObj = schemaData as unknown as SchemaContractData;\n\n  if (!schemaObj.name || !schemaObj.dialect || !schemaObj.definitionUrl) {\n    throw new Error(\"Incomplete schema data\");\n  }\n\n  return {\n    id: schemaId,\n    name: schemaObj.name,\n    dialect: schemaObj.dialect as \"json\" | \"sqlite\",\n    definitionUrl: schemaObj.definitionUrl,\n  };\n}\n\n/**\n * Fetches the total count of schemas from the blockchain.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @returns The total number of schemas\n * @throws Error if chain ID is not available or operation fails\n *\n * @internal\n */\nexport async function fetchSchemaCountFromChain(\n  context: BlockchainContext,\n): Promise<number> {\n  const chainId =\n    context.walletClient?.chain?.id ?? context.publicClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const count = await dataRefinerRegistry.read.schemasCount();\n  return Number(count);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAA4B;AAE5B,uBAAmC;AACnC,iBAAuB;AAiCvB,eAAsB,qBACpB,SACA,UACyB;AACzB,QAAM,UACJ,QAAQ,cAAc,OAAO,MAAM,QAAQ,aAAa,OAAO;AACjE,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,iCAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,6BAAyB,mBAAO,qBAAqB;AAE3D,QAAM,0BAAsB,yBAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,aAAa,MAAM,oBAAoB,KAAK,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE5E,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kBAAkB,QAAQ,YAAY;AAAA,EACxD;AAKA,QAAM,YAAY;AAElB,MAAI,CAAC,UAAU,QAAQ,CAAC,UAAU,WAAW,CAAC,UAAU,eAAe;AACrE,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM,UAAU;AAAA,IAChB,SAAS,UAAU;AAAA,IACnB,eAAe,UAAU;AAAA,EAC3B;AACF;AAWA,eAAsB,0BACpB,SACiB;AACjB,QAAM,UACJ,QAAQ,cAAc,OAAO,MAAM,QAAQ,aAAa,OAAO;AACjE,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,iCAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,6BAAyB,mBAAO,qBAAqB;AAE3D,QAAM,0BAAsB,yBAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,QAAQ,MAAM,oBAAoB,KAAK,aAAa;AAC1D,SAAO,OAAO,KAAK;AACrB;","names":[]}

package/dist/utils/blockchain/registry.d.ts

@@ -1,12 +1,11 @@
-import { WalletClient, PublicClient } from 'viem';
-import { SchemaMetadata } from '../../types/data.js';
-
+import type { PublicClient, WalletClient } from "viem";
+import type { SchemaMetadata } from "../../types/index";
 /**
  * Shared context for blockchain operations.
  * Only includes the minimal required fields to avoid coupling.
  */
 interface BlockchainContext {
-    walletClient: WalletClient;
+    walletClient?: WalletClient;
     publicClient: PublicClient;
 }
 /**
@@ -19,7 +18,7 @@ interface BlockchainContext {
  *
  * @internal
  */
-declare function fetchSchemaFromChain(context: BlockchainContext, schemaId: number): Promise<SchemaMetadata>;
+export declare function fetchSchemaFromChain(context: BlockchainContext, schemaId: number): Promise<SchemaMetadata>;
 /**
  * Fetches the total count of schemas from the blockchain.
  *
@@ -29,6 +28,5 @@ declare function fetchSchemaFromChain(context: BlockchainContext, schemaId: numb
  *
  * @internal
  */
-declare function fetchSchemaCountFromChain(context: BlockchainContext): Promise<number>;
-
-export { fetchSchemaCountFromChain, fetchSchemaFromChain };
+export declare function fetchSchemaCountFromChain(context: BlockchainContext): Promise<number>;
+export {};

package/dist/utils/blockchain/registry.js

@@ -2,7 +2,7 @@ import { getContract } from "viem";
 import { getContractAddress } from "../../config/addresses";
 import { getAbi } from "../../generated/abi";
 async function fetchSchemaFromChain(context, schemaId) {
-  const chainId = context.walletClient.chain?.id;
+  const chainId = context.walletClient?.chain?.id ?? context.publicClient.chain?.id;
   if (!chainId) {
     throw new Error("Chain ID not available");
   }
@@ -32,7 +32,7 @@ async function fetchSchemaFromChain(context, schemaId) {
   };
 }
 async function fetchSchemaCountFromChain(context) {
-  const chainId = context.walletClient.chain?.id;
+  const chainId = context.walletClient?.chain?.id ?? context.publicClient.chain?.id;
   if (!chainId) {
     throw new Error("Chain ID not available");
   }

package/dist/utils/blockchain/registry.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/utils/blockchain/registry.ts"],"sourcesContent":["import { getContract } from \"viem\";\nimport { PublicClient, WalletClient } from \"viem\";\nimport { getContractAddress } from \"../../config/addresses\";\nimport { getAbi } from \"../../generated/abi\";\nimport { SchemaMetadata } from \"../../types/index\";\n\n/**\n * Shared context for blockchain operations.\n * Only includes the minimal required fields to avoid coupling.\n */\ninterface BlockchainContext {\n  walletClient: WalletClient;\n  publicClient: PublicClient;\n}\n\n/**\n * Contract data structure returned by the blockchain.\n *\n * @internal\n */\ninterface SchemaContractData {\n  name: string;\n  dialect: string;\n  definitionUrl: string;\n}\n\n/**\n * Fetches schema metadata from the blockchain by its ID.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @param schemaId - The ID of the schema to fetch\n * @returns The schema metadata with id, name, dialect, and definitionUrl\n * @throws Error if chain ID is not available, schema not found, or data is incomplete\n *\n * @internal\n */\nexport async function fetchSchemaFromChain(\n  context: BlockchainContext,\n  schemaId: number,\n): Promise<SchemaMetadata> {\n  const chainId = context.walletClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const schemaData = await dataRefinerRegistry.read.schemas([BigInt(schemaId)]);\n\n  if (!schemaData) {\n    throw new Error(`Schema with ID ${schemaId} not found`);\n  }\n\n  const schemaObj = schemaData as unknown as SchemaContractData;\n\n  if (!schemaObj.name || !schemaObj.dialect || !schemaObj.definitionUrl) {\n    throw new Error(\"Incomplete schema data\");\n  }\n\n  return {\n    id: schemaId,\n    name: schemaObj.name,\n    dialect: schemaObj.dialect as \"json\" | \"sqlite\",\n    definitionUrl: schemaObj.definitionUrl,\n  };\n}\n\n/**\n * Fetches the total count of schemas from the blockchain.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @returns The total number of schemas\n * @throws Error if chain ID is not available or operation fails\n *\n * @internal\n */\nexport async function fetchSchemaCountFromChain(\n  context: BlockchainContext,\n): Promise<number> {\n  const chainId = context.walletClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const count = await dataRefinerRegistry.read.schemasCount();\n  return Number(count);\n}\n"],"mappings":"AAAA,SAAS,mBAAmB;AAE5B,SAAS,0BAA0B;AACnC,SAAS,cAAc;AAiCvB,eAAsB,qBACpB,SACA,UACyB;AACzB,QAAM,UAAU,QAAQ,aAAa,OAAO;AAC5C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,6BAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,yBAAyB,OAAO,qBAAqB;AAE3D,QAAM,sBAAsB,YAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,aAAa,MAAM,oBAAoB,KAAK,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE5E,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kBAAkB,QAAQ,YAAY;AAAA,EACxD;AAEA,QAAM,YAAY;AAElB,MAAI,CAAC,UAAU,QAAQ,CAAC,UAAU,WAAW,CAAC,UAAU,eAAe;AACrE,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM,UAAU;AAAA,IAChB,SAAS,UAAU;AAAA,IACnB,eAAe,UAAU;AAAA,EAC3B;AACF;AAWA,eAAsB,0BACpB,SACiB;AACjB,QAAM,UAAU,QAAQ,aAAa,OAAO;AAC5C,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,6BAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,yBAAyB,OAAO,qBAAqB;AAE3D,QAAM,sBAAsB,YAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,QAAQ,MAAM,oBAAoB,KAAK,aAAa;AAC1D,SAAO,OAAO,KAAK;AACrB;","names":[]}
+{"version":3,"sources":["../../../src/utils/blockchain/registry.ts"],"sourcesContent":["import { getContract } from \"viem\";\nimport type { PublicClient, WalletClient } from \"viem\";\nimport { getContractAddress } from \"../../config/addresses\";\nimport { getAbi } from \"../../generated/abi\";\nimport type { SchemaMetadata } from \"../../types/index\";\n\n/**\n * Shared context for blockchain operations.\n * Only includes the minimal required fields to avoid coupling.\n */\ninterface BlockchainContext {\n  walletClient?: WalletClient;\n  publicClient: PublicClient;\n}\n\n/**\n * Contract data structure returned by the blockchain.\n *\n * @internal\n */\ninterface SchemaContractData {\n  name: string;\n  dialect: string;\n  definitionUrl: string;\n}\n\n/**\n * Fetches schema metadata from the blockchain by its ID.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @param schemaId - The ID of the schema to fetch\n * @returns The schema metadata with id, name, dialect, and definitionUrl\n * @throws Error if chain ID is not available, schema not found, or data is incomplete\n *\n * @internal\n */\nexport async function fetchSchemaFromChain(\n  context: BlockchainContext,\n  schemaId: number,\n): Promise<SchemaMetadata> {\n  const chainId =\n    context.walletClient?.chain?.id ?? context.publicClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const schemaData = await dataRefinerRegistry.read.schemas([BigInt(schemaId)]);\n\n  if (!schemaData) {\n    throw new Error(`Schema with ID ${schemaId} not found`);\n  }\n\n  // TODO(TYPES): Contract read returns unknown type from viem library.\n  // Future improvement: Create typed contract interface when viem adds support\n  // or implement a contract type generator from ABI definitions.\n  const schemaObj = schemaData as unknown as SchemaContractData;\n\n  if (!schemaObj.name || !schemaObj.dialect || !schemaObj.definitionUrl) {\n    throw new Error(\"Incomplete schema data\");\n  }\n\n  return {\n    id: schemaId,\n    name: schemaObj.name,\n    dialect: schemaObj.dialect as \"json\" | \"sqlite\",\n    definitionUrl: schemaObj.definitionUrl,\n  };\n}\n\n/**\n * Fetches the total count of schemas from the blockchain.\n *\n * @param context - The blockchain context containing wallet and public clients\n * @returns The total number of schemas\n * @throws Error if chain ID is not available or operation fails\n *\n * @internal\n */\nexport async function fetchSchemaCountFromChain(\n  context: BlockchainContext,\n): Promise<number> {\n  const chainId =\n    context.walletClient?.chain?.id ?? context.publicClient.chain?.id;\n  if (!chainId) {\n    throw new Error(\"Chain ID not available\");\n  }\n\n  const dataRefinerRegistryAddress = getContractAddress(\n    chainId,\n    \"DataRefinerRegistry\",\n  );\n  const dataRefinerRegistryAbi = getAbi(\"DataRefinerRegistry\");\n\n  const dataRefinerRegistry = getContract({\n    address: dataRefinerRegistryAddress,\n    abi: dataRefinerRegistryAbi,\n    client: context.publicClient,\n  });\n\n  const count = await dataRefinerRegistry.read.schemasCount();\n  return Number(count);\n}\n"],"mappings":"AAAA,SAAS,mBAAmB;AAE5B,SAAS,0BAA0B;AACnC,SAAS,cAAc;AAiCvB,eAAsB,qBACpB,SACA,UACyB;AACzB,QAAM,UACJ,QAAQ,cAAc,OAAO,MAAM,QAAQ,aAAa,OAAO;AACjE,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,6BAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,yBAAyB,OAAO,qBAAqB;AAE3D,QAAM,sBAAsB,YAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,aAAa,MAAM,oBAAoB,KAAK,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE5E,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kBAAkB,QAAQ,YAAY;AAAA,EACxD;AAKA,QAAM,YAAY;AAElB,MAAI,CAAC,UAAU,QAAQ,CAAC,UAAU,WAAW,CAAC,UAAU,eAAe;AACrE,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM,UAAU;AAAA,IAChB,SAAS,UAAU;AAAA,IACnB,eAAe,UAAU;AAAA,EAC3B;AACF;AAWA,eAAsB,0BACpB,SACiB;AACjB,QAAM,UACJ,QAAQ,cAAc,OAAO,MAAM,QAAQ,aAAa,OAAO;AACjE,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AAEA,QAAM,6BAA6B;AAAA,IACjC;AAAA,IACA;AAAA,EACF;AACA,QAAM,yBAAyB,OAAO,qBAAqB;AAE3D,QAAM,sBAAsB,YAAY;AAAA,IACtC,SAAS;AAAA,IACT,KAAK;AAAA,IACL,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,QAAQ,MAAM,oBAAoB,KAAK,aAAa;AAC1D,SAAO,OAAO,KAAK;AACrB;","names":[]}

package/dist/utils/blockchain/registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/crypto-utils.cjs

@@ -20,7 +20,6 @@ var crypto_utils_exports = {};
 __export(crypto_utils_exports, {
   assertUncompressedPublicKey: () => assertUncompressedPublicKey,
   bytesEqual: () => bytesEqual,
-  concatBytes: () => concatBytes,
   copyBytes: () => copyBytes,
   generateSeed: () => generateSeed,
   isValidPrivateKeyFormat: () => isValidPrivateKeyFormat,
@@ -31,16 +30,6 @@ __export(crypto_utils_exports, {
 });
 module.exports = __toCommonJS(crypto_utils_exports);
 var import_viem = require("viem");
-function concatBytes(...arrays) {
-  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const arr of arrays) {
-    result.set(arr, offset);
-    offset += arr.length;
-  }
-  return result;
-}
 function processWalletPublicKey(publicKey) {
   return typeof publicKey === "string" ? (0, import_viem.fromHex)(
     publicKey.startsWith("0x") ? publicKey : `0x${publicKey}`,
@@ -108,7 +97,6 @@ function assertUncompressedPublicKey(publicKey) {
 0 && (module.exports = {
   assertUncompressedPublicKey,
   bytesEqual,
-  concatBytes,
   copyBytes,
   generateSeed,
   isValidPrivateKeyFormat,

package/dist/utils/crypto-utils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/crypto-utils.ts"],"sourcesContent":["/**\n * Provides platform-agnostic cryptographic utility functions.\n *\n * @remarks\n * This module contains utility functions for cryptographic operations that work\n * consistently across Node.js and browser environments. All functions use `Uint8Array`\n * exclusively for binary data to ensure cross-platform compatibility.\n *\n * @category Cryptography\n */\n\nimport { fromHex } from \"viem\";\n\n/**\n * Concatenates multiple Uint8Arrays into a single array.\n *\n * @param arrays - The byte arrays to concatenate in order.\n * @returns A new Uint8Array containing all input arrays concatenated.\n *\n * @example\n * ```typescript\n * const combined = concatBytes(\n *   new Uint8Array([1, 2]),\n *   new Uint8Array([3, 4])\n * );\n * console.log(combined); // Uint8Array([1, 2, 3, 4])\n * ```\n */\nexport function concatBytes(...arrays: Uint8Array[]): Uint8Array {\n  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);\n  const result = new Uint8Array(totalLength);\n  let offset = 0;\n  for (const arr of arrays) {\n    result.set(arr, offset);\n    offset += arr.length;\n  }\n  return result;\n}\n\n/**\n * Processes a wallet public key for cryptographic operations.\n *\n * @remarks\n * Converts hex string public keys to Uint8Array format.\n * For normalization to uncompressed format, use the crypto provider's\n * normalizeToUncompressed method.\n *\n * @param publicKey - The wallet public key as hex string or byte array.\n * @returns The public key as a Uint8Array.\n *\n * @example\n * ```typescript\n * const keyBytes = processWalletPublicKey(\"0x04...\");\n * const normalized = provider.normalizeToUncompressed(keyBytes);\n * ```\n */\nexport function processWalletPublicKey(\n  publicKey: string | Uint8Array,\n): Uint8Array {\n  // Convert to bytes if hex string\n  return typeof publicKey === \"string\"\n    ? fromHex(\n        (publicKey.startsWith(\"0x\")\n          ? publicKey\n          : `0x${publicKey}`) as `0x${string}`,\n        \"bytes\",\n      )\n    : publicKey;\n}\n\n/**\n * Processes a wallet private key for cryptographic operations.\n *\n * @param privateKey - The wallet private key as hex string or byte array.\n * @returns The private key as a Uint8Array.\n *\n * @example\n * ```typescript\n * const key = processWalletPrivateKey(\"0x...\");\n * console.log(key.length); // 32 (secp256k1 private key)\n * ```\n */\nexport function processWalletPrivateKey(\n  privateKey: string | Uint8Array,\n): Uint8Array {\n  // Convert to bytes\n  return typeof privateKey === \"string\"\n    ? fromHex(\n        (privateKey.startsWith(\"0x\")\n          ? privateKey\n          : `0x${privateKey}`) as `0x${string}`,\n        \"bytes\",\n      )\n    : privateKey;\n}\n\n/**\n * Parses legacy eccrypto-format encrypted data buffer.\n * Format: [iv(16)][ephemPublicKey(65)][ciphertext(variable)][mac(32)]\n *\n * @param encryptedBuffer - Buffer containing encrypted data in eccrypto format\n * @returns Parsed encrypted data components\n */\nexport function parseEncryptedDataBuffer(encryptedBuffer: Uint8Array): {\n  iv: Uint8Array;\n  ephemPublicKey: Uint8Array;\n  ciphertext: Uint8Array;\n  mac: Uint8Array;\n} {\n  return {\n    iv: encryptedBuffer.slice(0, 16),\n    ephemPublicKey: encryptedBuffer.slice(16, 81), // 65 bytes for uncompressed public key\n    ciphertext: encryptedBuffer.slice(81, -32),\n    mac: encryptedBuffer.slice(-32),\n  };\n}\n\n/**\n * Generates a deterministic seed from a message for key derivation\n *\n * @param message - Message to derive seed from\n * @returns Seed as Uint8Array\n */\nexport function generateSeed(message: string): Uint8Array {\n  // Use encoding utils for consistent string-to-bytes conversion\n  const encoder = new TextEncoder();\n  return encoder.encode(message);\n}\n\n/**\n * Compares two Uint8Arrays for equality\n *\n * @param a - First array\n * @param b - Second array\n * @returns True if arrays are equal\n */\nexport function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) return false;\n  }\n  return true;\n}\n\n/**\n * Creates a copy of a Uint8Array\n *\n * @param bytes - Array to copy\n * @returns New array with same contents\n */\nexport function copyBytes(bytes: Uint8Array): Uint8Array {\n  return new Uint8Array(bytes);\n}\n\n/**\n * Validates a secp256k1 public key format\n *\n * @param publicKey - Public key to validate\n * @returns True if valid format (33, 65, or 64 bytes)\n */\nexport function isValidPublicKeyFormat(publicKey: Uint8Array): boolean {\n  const len = publicKey.length;\n\n  // Compressed (33 bytes)\n  if (len === 33) {\n    return publicKey[0] === 0x02 || publicKey[0] === 0x03;\n  }\n\n  // Uncompressed (65 bytes)\n  if (len === 65) {\n    return publicKey[0] === 0x04;\n  }\n\n  // Raw coordinates (64 bytes - no prefix)\n  if (len === 64) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Validates a secp256k1 private key format\n *\n * @param privateKey - Private key to validate\n * @returns True if valid format (32 bytes)\n */\nexport function isValidPrivateKeyFormat(privateKey: Uint8Array): boolean {\n  return privateKey.length === 32;\n}\n\n/**\n * Asserts that a public key is in uncompressed format (65 bytes with 0x04 prefix).\n * This validation function only checks format, it does not transform keys.\n * For key normalization (including decompression), use the crypto provider's\n * normalizeToUncompressed method.\n *\n * @param publicKey - Public key to validate\n * @throws {Error} When public key is not in uncompressed format\n */\nexport function assertUncompressedPublicKey(publicKey: Uint8Array): void {\n  if (publicKey.length !== 65) {\n    throw new Error(\n      `Public key must be uncompressed (65 bytes), got ${publicKey.length} bytes. ` +\n        `Use provider.normalizeToUncompressed() to convert compressed keys.`,\n    );\n  }\n\n  if (publicKey[0] !== 0x04) {\n    throw new Error(\n      `Uncompressed public key must start with 0x04 prefix, got 0x${publicKey[0].toString(16).padStart(2, \"0\")}`,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,kBAAwB;AAiBjB,SAAS,eAAe,QAAkC;AAC/D,QAAM,cAAc,OAAO,OAAO,CAAC,KAAK,QAAQ,MAAM,IAAI,QAAQ,CAAC;AACnE,QAAM,SAAS,IAAI,WAAW,WAAW;AACzC,MAAI,SAAS;AACb,aAAW,OAAO,QAAQ;AACxB,WAAO,IAAI,KAAK,MAAM;AACtB,cAAU,IAAI;AAAA,EAChB;AACA,SAAO;AACT;AAmBO,SAAS,uBACd,WACY;AAEZ,SAAO,OAAO,cAAc,eACxB;AAAA,IACG,UAAU,WAAW,IAAI,IACtB,YACA,KAAK,SAAS;AAAA,IAClB;AAAA,EACF,IACA;AACN;AAcO,SAAS,wBACd,YACY;AAEZ,SAAO,OAAO,eAAe,eACzB;AAAA,IACG,WAAW,WAAW,IAAI,IACvB,aACA,KAAK,UAAU;AAAA,IACnB;AAAA,EACF,IACA;AACN;AASO,SAAS,yBAAyB,iBAKvC;AACA,SAAO;AAAA,IACL,IAAI,gBAAgB,MAAM,GAAG,EAAE;AAAA,IAC/B,gBAAgB,gBAAgB,MAAM,IAAI,EAAE;AAAA;AAAA,IAC5C,YAAY,gBAAgB,MAAM,IAAI,GAAG;AAAA,IACzC,KAAK,gBAAgB,MAAM,GAAG;AAAA,EAChC;AACF;AAQO,SAAS,aAAa,SAA6B;AAExD,QAAM,UAAU,IAAI,YAAY;AAChC,SAAO,QAAQ,OAAO,OAAO;AAC/B;AASO,SAAS,WAAW,GAAe,GAAwB;AAChE,MAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,QAAI,EAAE,CAAC,MAAM,EAAE,CAAC,EAAG,QAAO;AAAA,EAC5B;AACA,SAAO;AACT;AAQO,SAAS,UAAU,OAA+B;AACvD,SAAO,IAAI,WAAW,KAAK;AAC7B;AAQO,SAAS,uBAAuB,WAAgC;AACrE,QAAM,MAAM,UAAU;AAGtB,MAAI,QAAQ,IAAI;AACd,WAAO,UAAU,CAAC,MAAM,KAAQ,UAAU,CAAC,MAAM;AAAA,EACnD;AAGA,MAAI,QAAQ,IAAI;AACd,WAAO,UAAU,CAAC,MAAM;AAAA,EAC1B;AAGA,MAAI,QAAQ,IAAI;AACd,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAQO,SAAS,wBAAwB,YAAiC;AACvE,SAAO,WAAW,WAAW;AAC/B;AAWO,SAAS,4BAA4B,WAA6B;AACvE,MAAI,UAAU,WAAW,IAAI;AAC3B,UAAM,IAAI;AAAA,MACR,mDAAmD,UAAU,MAAM;AAAA,IAErE;AAAA,EACF;AAEA,MAAI,UAAU,CAAC,MAAM,GAAM;AACzB,UAAM,IAAI;AAAA,MACR,8DAA8D,UAAU,CAAC,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC;AAAA,IAC1G;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/crypto-utils.ts"],"sourcesContent":["/**\n * Provides platform-agnostic cryptographic utility functions.\n *\n * @remarks\n * This module contains utility functions for cryptographic operations that work\n * consistently across Node.js and browser environments. All functions use `Uint8Array`\n * exclusively for binary data to ensure cross-platform compatibility.\n *\n * @category Cryptography\n */\n\nimport { fromHex } from \"viem\";\n\n/**\n * Processes a wallet public key for cryptographic operations.\n *\n * @remarks\n * Converts hex string public keys to Uint8Array format.\n * For normalization to uncompressed format, use the crypto provider's\n * normalizeToUncompressed method.\n *\n * @param publicKey - The wallet public key as hex string or byte array.\n * @returns The public key as a Uint8Array.\n *\n * @example\n * ```typescript\n * const keyBytes = processWalletPublicKey(\"0x04...\");\n * const normalized = provider.normalizeToUncompressed(keyBytes);\n * ```\n */\nexport function processWalletPublicKey(\n  publicKey: string | Uint8Array,\n): Uint8Array {\n  // Convert to bytes if hex string\n  return typeof publicKey === \"string\"\n    ? fromHex(\n        (publicKey.startsWith(\"0x\")\n          ? publicKey\n          : `0x${publicKey}`) as `0x${string}`,\n        \"bytes\",\n      )\n    : publicKey;\n}\n\n/**\n * Processes a wallet private key for cryptographic operations.\n *\n * @param privateKey - The wallet private key as hex string or byte array.\n * @returns The private key as a Uint8Array.\n *\n * @example\n * ```typescript\n * const key = processWalletPrivateKey(\"0x...\");\n * console.log(key.length); // 32 (secp256k1 private key)\n * ```\n */\nexport function processWalletPrivateKey(\n  privateKey: string | Uint8Array,\n): Uint8Array {\n  // Convert to bytes\n  return typeof privateKey === \"string\"\n    ? fromHex(\n        (privateKey.startsWith(\"0x\")\n          ? privateKey\n          : `0x${privateKey}`) as `0x${string}`,\n        \"bytes\",\n      )\n    : privateKey;\n}\n\n/**\n * Parses legacy eccrypto-format encrypted data buffer.\n * Format: [iv(16)][ephemPublicKey(65)][ciphertext(variable)][mac(32)]\n *\n * @param encryptedBuffer - Buffer containing encrypted data in eccrypto format\n * @returns Parsed encrypted data components\n */\nexport function parseEncryptedDataBuffer(encryptedBuffer: Uint8Array): {\n  iv: Uint8Array;\n  ephemPublicKey: Uint8Array;\n  ciphertext: Uint8Array;\n  mac: Uint8Array;\n} {\n  return {\n    iv: encryptedBuffer.slice(0, 16),\n    ephemPublicKey: encryptedBuffer.slice(16, 81), // 65 bytes for uncompressed public key\n    ciphertext: encryptedBuffer.slice(81, -32),\n    mac: encryptedBuffer.slice(-32),\n  };\n}\n\n/**\n * Generates a deterministic seed from a message for key derivation\n *\n * @param message - Message to derive seed from\n * @returns Seed as Uint8Array\n */\nexport function generateSeed(message: string): Uint8Array {\n  // Use encoding utils for consistent string-to-bytes conversion\n  const encoder = new TextEncoder();\n  return encoder.encode(message);\n}\n\n/**\n * Compares two Uint8Arrays for equality\n *\n * @param a - First array\n * @param b - Second array\n * @returns True if arrays are equal\n */\nexport function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) return false;\n  }\n  return true;\n}\n\n/**\n * Creates a copy of a Uint8Array\n *\n * @param bytes - Array to copy\n * @returns New array with same contents\n */\nexport function copyBytes(bytes: Uint8Array): Uint8Array {\n  return new Uint8Array(bytes);\n}\n\n/**\n * Validates a secp256k1 public key format\n *\n * @param publicKey - Public key to validate\n * @returns True if valid format (33, 65, or 64 bytes)\n */\nexport function isValidPublicKeyFormat(publicKey: Uint8Array): boolean {\n  const len = publicKey.length;\n\n  // Compressed (33 bytes)\n  if (len === 33) {\n    return publicKey[0] === 0x02 || publicKey[0] === 0x03;\n  }\n\n  // Uncompressed (65 bytes)\n  if (len === 65) {\n    return publicKey[0] === 0x04;\n  }\n\n  // Raw coordinates (64 bytes - no prefix)\n  if (len === 64) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Validates a secp256k1 private key format\n *\n * @param privateKey - Private key to validate\n * @returns True if valid format (32 bytes)\n */\nexport function isValidPrivateKeyFormat(privateKey: Uint8Array): boolean {\n  return privateKey.length === 32;\n}\n\n/**\n * Asserts that a public key is in uncompressed format (65 bytes with 0x04 prefix).\n * This validation function only checks format, it does not transform keys.\n * For key normalization (including decompression), use the crypto provider's\n * normalizeToUncompressed method.\n *\n * @param publicKey - Public key to validate\n * @throws {Error} When public key is not in uncompressed format\n */\nexport function assertUncompressedPublicKey(publicKey: Uint8Array): void {\n  if (publicKey.length !== 65) {\n    throw new Error(\n      `Public key must be uncompressed (65 bytes), got ${publicKey.length} bytes. ` +\n        `Use provider.normalizeToUncompressed() to convert compressed keys.`,\n    );\n  }\n\n  if (publicKey[0] !== 0x04) {\n    throw new Error(\n      `Uncompressed public key must start with 0x04 prefix, got 0x${publicKey[0].toString(16).padStart(2, \"0\")}`,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,kBAAwB;AAmBjB,SAAS,uBACd,WACY;AAEZ,SAAO,OAAO,cAAc,eACxB;AAAA,IACG,UAAU,WAAW,IAAI,IACtB,YACA,KAAK,SAAS;AAAA,IAClB;AAAA,EACF,IACA;AACN;AAcO,SAAS,wBACd,YACY;AAEZ,SAAO,OAAO,eAAe,eACzB;AAAA,IACG,WAAW,WAAW,IAAI,IACvB,aACA,KAAK,UAAU;AAAA,IACnB;AAAA,EACF,IACA;AACN;AASO,SAAS,yBAAyB,iBAKvC;AACA,SAAO;AAAA,IACL,IAAI,gBAAgB,MAAM,GAAG,EAAE;AAAA,IAC/B,gBAAgB,gBAAgB,MAAM,IAAI,EAAE;AAAA;AAAA,IAC5C,YAAY,gBAAgB,MAAM,IAAI,GAAG;AAAA,IACzC,KAAK,gBAAgB,MAAM,GAAG;AAAA,EAChC;AACF;AAQO,SAAS,aAAa,SAA6B;AAExD,QAAM,UAAU,IAAI,YAAY;AAChC,SAAO,QAAQ,OAAO,OAAO;AAC/B;AASO,SAAS,WAAW,GAAe,GAAwB;AAChE,MAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,QAAI,EAAE,CAAC,MAAM,EAAE,CAAC,EAAG,QAAO;AAAA,EAC5B;AACA,SAAO;AACT;AAQO,SAAS,UAAU,OAA+B;AACvD,SAAO,IAAI,WAAW,KAAK;AAC7B;AAQO,SAAS,uBAAuB,WAAgC;AACrE,QAAM,MAAM,UAAU;AAGtB,MAAI,QAAQ,IAAI;AACd,WAAO,UAAU,CAAC,MAAM,KAAQ,UAAU,CAAC,MAAM;AAAA,EACnD;AAGA,MAAI,QAAQ,IAAI;AACd,WAAO,UAAU,CAAC,MAAM;AAAA,EAC1B;AAGA,MAAI,QAAQ,IAAI;AACd,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAQO,SAAS,wBAAwB,YAAiC;AACvE,SAAO,WAAW,WAAW;AAC/B;AAWO,SAAS,4BAA4B,WAA6B;AACvE,MAAI,UAAU,WAAW,IAAI;AAC3B,UAAM,IAAI;AAAA,MACR,mDAAmD,UAAU,MAAM;AAAA,IAErE;AAAA,EACF;AAEA,MAAI,UAAU,CAAC,MAAM,GAAM;AACzB,UAAM,IAAI;AAAA,MACR,8DAA8D,UAAU,CAAC,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC;AAAA,IAC1G;AAAA,EACF;AACF;","names":[]}