@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.1.0

package/dist/types/config.js

@@ -0,0 +1,23 @@
+function isWalletConfig(config) {
+  return "walletClient" in config;
+}
+function isReadOnlyConfig(config) {
+  return "publicClient" in config && "address" in config && !("walletClient" in config);
+}
+function isAddressOnlyConfig(config) {
+  return "address" in config && !("publicClient" in config) && !("walletClient" in config) && !("chainId" in config);
+}
+function isChainConfig(config) {
+  return "chainId" in config && !("walletClient" in config);
+}
+function hasStorageConfig(config) {
+  return config.storage?.providers !== void 0 && Object.keys(config.storage.providers).length > 0;
+}
+export {
+  hasStorageConfig,
+  isAddressOnlyConfig,
+  isChainConfig,
+  isReadOnlyConfig,
+  isWalletConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

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

package/dist/types/contracts.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var contracts_exports = {};
+module.exports = __toCommonJS(contracts_exports);
+//# sourceMappingURL=contracts.cjs.map

package/dist/types/contracts.cjs.map

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

package/dist/types/contracts.d.ts

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

package/dist/types/contracts.js

@@ -0,0 +1 @@
+//# sourceMappingURL=contracts.js.map

package/dist/types/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/controller-context.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var controller_context_exports = {};
+module.exports = __toCommonJS(controller_context_exports);
+//# sourceMappingURL=controller-context.cjs.map

package/dist/types/controller-context.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/controller-context.ts"],"sourcesContent":["/**\n * Shared type definitions for controller contexts.\n *\n * @remarks\n * These types ensure consistency across all controllers and prevent drift.\n * Single source of truth following Rich Hickey's principles.\n */\n\nimport type { WalletClient, PublicClient, Address } from \"viem\";\nimport type { VanaPlatformAdapter } from \"../platform/interface\";\nimport type { StorageManager } from \"../storage\";\nimport type { DownloadRelayerCallbacks } from \"./config\";\nimport type { UnifiedRelayerRequest, UnifiedRelayerResponse } from \"./relayer\";\nimport type {\n  TransactionResult,\n  TransactionWaitOptions,\n  Operation,\n  PollingOptions,\n} from \"./operations\";\nimport type { IOperationStore, IRelayerStateStore } from \"./operationStore\";\nimport type {\n  Contract,\n  Fn,\n  TypedTransactionResult,\n} from \"../generated/event-types\";\n\n/**\n * Type definition for waitForTransactionEvents function.\n *\n * @remarks\n * This is THE single definition used everywhere to prevent drift.\n * If you need to change the signature, change it here.\n */\nexport type WaitForTransactionEventsFn = <C extends Contract, F extends Fn<C>>(\n  transaction: TransactionResult<C, F>,\n  options?: TransactionWaitOptions,\n) => Promise<TypedTransactionResult<C, F>>;\n\n/**\n * Type definition for waitForOperation function.\n */\nexport type WaitForOperationFn = (\n  opOrId: Operation | string,\n  options?: PollingOptions,\n) => Promise<Operation>;\n\n/**\n * Shared controller context interface.\n *\n * @remarks\n * This is the contract that all controllers depend on.\n * Changing this interface is a breaking change.\n */\nexport interface ControllerContext {\n  /** Signs transactions and messages using the user's private key. Optional to support read-only mode. */\n  walletClient?: WalletClient;\n  /** Queries blockchain state and smart contracts without signing. */\n  publicClient: PublicClient;\n  /** Address of the user for operations requiring user identification in read-only mode. */\n  userAddress: Address;\n  /** Signs application-specific operations when different from primary wallet. */\n  applicationClient?: WalletClient;\n  /** Handles gasless transaction submission through relayer services. */\n  relayer?: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;\n  /** Proxies CORS-restricted downloads through application server. */\n  downloadRelayer?: DownloadRelayerCallbacks;\n  /** Manages file upload and download operations across storage providers. */\n  storageManager?: StorageManager;\n  /** Provides subgraph endpoint for querying indexed blockchain data. */\n  subgraphUrl?: string;\n  /** Adapts SDK functionality to the current runtime environment. */\n  platform: VanaPlatformAdapter;\n  /** Validates that storage is available for storage-dependent operations. */\n  validateStorageRequired?: () => void;\n  /** Checks whether storage is configured without throwing an error. */\n  hasStorage?: () => boolean;\n  /** Default IPFS gateways to use for fetching files. */\n  ipfsGateways?: string[];\n  /** Default personal server base URL for server operations. */\n  defaultPersonalServerUrl?: string;\n  /** Waits for transaction confirmation and parses typed events. */\n  waitForTransactionEvents?: WaitForTransactionEventsFn;\n  /** Waits for an operation to complete with polling. */\n  waitForOperation?: WaitForOperationFn;\n  /** Tracks async relayed transactions for resilient management. */\n  operationStore?: IOperationStore | IRelayerStateStore;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/controller-context.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared type definitions for controller contexts.
+ *
+ * @remarks
+ * These types ensure consistency across all controllers and prevent drift.
+ * Single source of truth following Rich Hickey's principles.
+ */
+import type { WalletClient, PublicClient, Address } from "viem";
+import type { VanaPlatformAdapter } from "../platform/interface";
+import type { StorageManager } from "../storage";
+import type { DownloadRelayerCallbacks } from "./config";
+import type { UnifiedRelayerRequest, UnifiedRelayerResponse } from "./relayer";
+import type { TransactionResult, TransactionWaitOptions, Operation, PollingOptions } from "./operations";
+import type { IOperationStore, IRelayerStateStore } from "./operationStore";
+import type { Contract, Fn, TypedTransactionResult } from "../generated/event-types";
+/**
+ * Type definition for waitForTransactionEvents function.
+ *
+ * @remarks
+ * This is THE single definition used everywhere to prevent drift.
+ * If you need to change the signature, change it here.
+ */
+export type WaitForTransactionEventsFn = <C extends Contract, F extends Fn<C>>(transaction: TransactionResult<C, F>, options?: TransactionWaitOptions) => Promise<TypedTransactionResult<C, F>>;
+/**
+ * Type definition for waitForOperation function.
+ */
+export type WaitForOperationFn = (opOrId: Operation | string, options?: PollingOptions) => Promise<Operation>;
+/**
+ * Shared controller context interface.
+ *
+ * @remarks
+ * This is the contract that all controllers depend on.
+ * Changing this interface is a breaking change.
+ */
+export interface ControllerContext {
+    /** Signs transactions and messages using the user's private key. Optional to support read-only mode. */
+    walletClient?: WalletClient;
+    /** Queries blockchain state and smart contracts without signing. */
+    publicClient: PublicClient;
+    /** Address of the user for operations requiring user identification in read-only mode. */
+    userAddress: Address;
+    /** Signs application-specific operations when different from primary wallet. */
+    applicationClient?: WalletClient;
+    /** Handles gasless transaction submission through relayer services. */
+    relayer?: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;
+    /** Proxies CORS-restricted downloads through application server. */
+    downloadRelayer?: DownloadRelayerCallbacks;
+    /** Manages file upload and download operations across storage providers. */
+    storageManager?: StorageManager;
+    /** Provides subgraph endpoint for querying indexed blockchain data. */
+    subgraphUrl?: string;
+    /** Adapts SDK functionality to the current runtime environment. */
+    platform: VanaPlatformAdapter;
+    /** Validates that storage is available for storage-dependent operations. */
+    validateStorageRequired?: () => void;
+    /** Checks whether storage is configured without throwing an error. */
+    hasStorage?: () => boolean;
+    /** Default IPFS gateways to use for fetching files. */
+    ipfsGateways?: string[];
+    /** Default personal server base URL for server operations. */
+    defaultPersonalServerUrl?: string;
+    /** Waits for transaction confirmation and parses typed events. */
+    waitForTransactionEvents?: WaitForTransactionEventsFn;
+    /** Waits for an operation to complete with polling. */
+    waitForOperation?: WaitForOperationFn;
+    /** Tracks async relayed transactions for resilient management. */
+    operationStore?: IOperationStore | IRelayerStateStore;
+}

package/dist/types/controller-context.js

@@ -0,0 +1 @@
+//# sourceMappingURL=controller-context.js.map

package/dist/types/controller-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/data.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var data_exports = {};
+module.exports = __toCommonJS(data_exports);
+//# sourceMappingURL=data.cjs.map

package/dist/types/data.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/data.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Represents a file registered on the Vana blockchain.\n *\n * @remarks\n * Contains complete metadata for files uploaded to storage and registered\n * on-chain. Each file has a unique ID, owner address, and storage URL.\n * Used throughout SDK for file operations and permission management.\n *\n * @category Data Management\n */\nexport interface UserFile {\n  /** Unique identifier assigned by the Data Registry contract. */\n  id: number;\n  /** Storage URL where the encrypted file content is hosted. */\n  url: string;\n  /** Wallet address of the user who owns this file. */\n  ownerAddress: Address;\n  /** Block number when this file was registered on-chain. */\n  addedAtBlock: bigint;\n  /**\n   * Schema identifier for data validation and structure definition.\n   * Obtain schema IDs from `vana.schemas.list()` or when creating schemas via `vana.schemas.create()`.\n   */\n  schemaId?: number;\n  /** Unix timestamp when the file was registered on-chain. */\n  addedAtTimestamp?: bigint;\n  /** Transaction hash of the on-chain file registration. */\n  transactionHash?: Address;\n  /** Additional file properties and custom application data. */\n  metadata?: FileMetadata;\n  /**\n   * Array of DLP IDs that have submitted proofs for this file.\n   * Each proof represents verification or processing by a Data Liquidity Pool.\n   * Obtain DLP details via `vana.data.getDLP(dlpId)`.\n   */\n  dlpIds?: number[];\n}\n\n/**\n * Provides optional metadata for uploaded files and content description.\n *\n * @remarks\n * This interface contains descriptive information about uploaded files, including\n * file properties and custom application-specific data that can be used for\n * organization, validation, and display purposes.\n * @category Data Management\n */\nexport interface FileMetadata {\n  /** Original filename as provided by the user or application. */\n  name?: string;\n  /** Total file size in bytes for storage tracking. */\n  size?: number;\n  /** MIME type identifier for content type recognition. */\n  mimeType?: string;\n  /** Hash value for file integrity verification. */\n  checksum?: string;\n  /** ISO 8601 timestamp when the file was uploaded. */\n  uploadedAt?: string;\n  /** Application-specific metadata for custom use cases. */\n  custom?: Record<string, unknown>;\n}\n\n/**\n * High-level parameters for uploading user data with automatic encryption and blockchain registration.\n *\n * @remarks\n * This is the primary interface for uploading user data through the simplified `vana.data.upload()` method.\n * It handles the complete workflow including encryption, storage, and blockchain registration.\n *\n * When using permissions with encryption enabled (default), you must provide the public key\n * for each permission recipient.\n *\n * @example\n * ```typescript\n * // Basic file upload\n * const result = await vana.data.upload({\n *   content: \"My personal data\",\n *   filename: \"diary.txt\"\n * });\n *\n * // Upload with schema validation\n * const result = await vana.data.upload({\n *   content: { name: \"John\", age: 30 },\n *   filename: \"profile.json\",\n *   schemaId: 1\n * });\n *\n * // Upload with permissions for an app (encrypted - requires publicKey)\n * const result = await vana.data.upload({\n *   content: \"Data for AI analysis\",\n *   filename: \"analysis.txt\",\n *   permissions: [{\n *     grantee: \"0x1234...\",\n *     operation: \"llm_inference\",\n *     parameters: { model: \"gpt-4\" },\n *     publicKey: \"0x04...\" // Required when encrypt is true (default)\n *   }]\n * });\n *\n * // Upload without encryption (publicKey optional)\n * const result = await vana.data.upload({\n *   content: \"Public data\",\n *   filename: \"public.txt\",\n *   encrypt: false,\n *   permissions: [{\n *     grantee: \"0x1234...\",\n *     operation: \"read\",\n *     parameters: {}\n *   }]\n * });\n * ```\n * @category Data Management\n */\nexport interface UploadParams {\n  /** Raw file data as string, Blob, or Buffer. */\n  content: string | Blob | Buffer;\n  /** Optional filename for the uploaded file. */\n  filename?: string;\n  /** Optional schema ID for data validation. */\n  schemaId?: number;\n  /** Optional file permissions to grant decryption access during upload. */\n  permissions?: FilePermissionParams[];\n  /** Whether to encrypt the data (defaults to true). */\n  encrypt?: boolean;\n  /** Optional storage provider name. */\n  providerName?: string;\n  /** Optional owner address (defaults to current wallet address). */\n  owner?: Address;\n  /**\n   * Schema validation mode when schemaId is provided:\n   * - 'strict': Throw error on validation failure (default)\n   * - 'warn': Log warning and continue on validation failure\n   * - 'skip': Skip validation entirely\n   */\n  schemaValidation?: \"strict\" | \"warn\" | \"skip\";\n}\n\n/**\n * Upload parameters with encryption enabled.\n *\n * @remarks\n * This interface ensures type safety when using encrypted uploads with permissions.\n * When encrypt is true, any permissions must include public keys for encryption.\n * @category Data Management\n */\nexport interface EncryptedUploadParams\n  extends Omit<UploadParams, \"permissions\" | \"encrypt\"> {\n  /** File permissions with required public keys for encrypted data sharing. */\n  permissions?: FilePermissionParams[];\n  /** Encryption is enabled. */\n  encrypt: true;\n}\n\n/**\n * Upload parameters with encryption disabled.\n *\n * @remarks\n * This interface is used when uploading unencrypted data.\n * @category Data Management\n */\nexport interface UnencryptedUploadParams extends Omit<UploadParams, \"encrypt\"> {\n  /** Encryption is disabled. */\n  encrypt: false;\n}\n\n/**\n * Parameters for granting file decryption access during upload.\n *\n * @remarks\n * This interface is used to grant decryption access to specific accounts when uploading\n * encrypted files. It only handles encryption key sharing, not operation permissions.\n *\n * For granting operation permissions (like \"llm_inference\"), use the separate\n * `vana.permissions.grant()` method after uploading.\n *\n * @example\n * ```typescript\n * // Upload with decryption permission\n * const result = await vana.data.upload({\n *   content: \"data\",\n *   permissions: [{\n *     account: \"0xServerAddress...\",\n *     publicKey: \"0x04...\" // Server's public key\n *   }]\n * });\n * ```\n * @category Data Management\n */\nexport interface FilePermissionParams {\n  /** The account address that will be able to decrypt this file. */\n  account: Address;\n  /** The public key to encrypt the file's encryption key with. */\n  publicKey: string;\n}\n\n/**\n * Permission parameters for granting data access.\n *\n * @remarks\n * This interface defines parameters for granting permissions to access data.\n * It's used in the permissions system but kept here for compatibility.\n *\n * @category Data Management\n */\nexport interface PermissionParams {\n  /** The address of the application to grant permission to. */\n  grantee: Address;\n  /** The operation type (e.g., \"llm_inference\", \"data_analysis\", \"compute_task\"). */\n  operation: string;\n  /** Additional parameters for the permission (operation-specific configuration). */\n  parameters: Record<string, unknown>;\n  /** Optional nonce for the permission (auto-generated if not provided). */\n  nonce?: bigint;\n  /** Optional expiration timestamp (Unix seconds, no expiration if not provided). */\n  expiresAt?: number;\n  /**\n   * Public key of the recipient to encrypt the data key for (required for upload with permissions).\n   * Obtain via `vana.server.getIdentity(recipientAddress).public_key` for personal servers.\n   */\n  publicKey?: string;\n}\n\n/**\n * Legacy permission parameters that conflated file encryption and data access grants.\n *\n * @remarks\n * This interface was removed because it conflated two different concepts:\n * 1. File encryption permissions (handled during upload)\n * 2. Data access grants (operation permissions)\n *\n * For file uploads, use FilePermissionParams instead.\n * For data access grants, use vana.permissions.grant() after uploading.\n *\n * @deprecated Removed in v2.0.0. Use FilePermissionParams for uploads.\n * @category Data Management\n */\nexport interface LegacyPermissionParams {\n  grantee: Address;\n  operation: string;\n  parameters: Record<string, unknown>;\n  nonce?: bigint;\n  expiresAt?: number;\n  publicKey?: string;\n}\n\n/**\n * Result of the high-level upload operation.\n *\n * @remarks\n * Returned by the `vana.data.upload()` method after successful upload and blockchain registration.\n * @category Data Management\n */\nexport interface UploadResult {\n  /** The file ID assigned by the DataRegistry contract. */\n  fileId: number;\n  /** The storage URL where the file is hosted. */\n  url: string;\n  /** The transaction hash of the blockchain registration. */\n  transactionHash: Hash;\n  /** The actual file size in bytes. */\n  size: number;\n  /** Whether the data passed schema validation (if applicable). */\n  isValid?: boolean;\n  /** Validation errors if schema validation failed. */\n  validationErrors?: string[];\n  /** Permission IDs if permissions were granted during upload. */\n  permissionIds?: bigint[];\n}\n\n/**\n * Defines parameters for uploading files to storage providers with encryption options.\n *\n * @remarks\n * Used with DataController upload methods and storage operations. Supports multiple\n * content formats, optional encryption, and custom storage provider selection with\n * comprehensive metadata tracking.\n * @deprecated Use UploadParams with vana.data.upload() instead for the high-level API\n * @example\n * ```typescript\n * const uploadParams: UploadFileParams = {\n *   content: new TextEncoder().encode(JSON.stringify(userData)),\n *   metadata: {\n *     name: \"personal-profile.json\",\n *     mimeType: \"application/json\",\n *     size: 2048,\n *   },\n *   storageProvider: \"ipfs\",\n *   encrypt: true,\n * };\n *\n * const result = await vana.data.uploadFile(uploadParams);\n * ```\n * @category Data Management\n */\nexport interface UploadFileParams {\n  /** Raw file data in bytes, buffer, or string format. */\n  content: Uint8Array | Buffer | string;\n  /** Descriptive metadata for file organization and tracking. */\n  metadata?: FileMetadata;\n  /** Storage provider name (\"ipfs\" or custom provider, uses configured default if unspecified). */\n  storageProvider?: string;\n  /** Enables automatic encryption before upload to storage (defaults to false). */\n  encrypt?: boolean;\n  /** Custom encryption key (auto-generated if encryption enabled and not provided). */\n  encryptionKey?: string;\n}\n\n/**\n * Contains the result of a successful file upload operation.\n *\n * @remarks\n * This interface provides the essential information returned after uploading\n * a file to a storage provider, including access URL, size verification,\n * and encryption details when applicable.\n * @category Data Management\n */\nexport interface UploadFileResult {\n  /** Public URL where the uploaded file can be accessed. */\n  url: string;\n  /** Actual file size in bytes after upload processing. */\n  size: number;\n  /** Hash value for verifying file integrity after upload. */\n  checksum?: string;\n  /** Encryption metadata when file was encrypted before storage. */\n  encryption?: EncryptionInfo;\n}\n\n/**\n * Result of uploading an encrypted file to storage and blockchain\n *\n * @category Data Management\n */\nexport interface UploadEncryptedFileResult extends UploadFileResult {\n  /** The new file ID assigned by the DataRegistry */\n  fileId: number;\n  /** Transaction hash of the file registration */\n  transactionHash?: Hash;\n}\n\n/**\n * Encryption information for a file\n *\n * @category Data Management\n */\nexport interface EncryptionInfo {\n  /** Encryption algorithm used */\n  algorithm: string;\n  /** Key derivation function */\n  kdf?: string;\n  /** Initialization vector */\n  iv?: string;\n  /** Salt used for key derivation */\n  salt?: string;\n  /** Key identifier */\n  keyId?: string;\n}\n\n/**\n * Parameters for getting user files\n *\n * @category Data Management\n */\nexport interface GetUserFilesParams {\n  /** Owner address to filter by */\n  owner?: Address;\n  /** Starting block number for filtering */\n  fromBlock?: bigint;\n  /** Ending block number for filtering */\n  toBlock?: bigint;\n  /** Maximum number of files to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n}\n\n/**\n * Parameters for getting a specific file\n *\n * @category Data Management\n */\nexport interface GetFileParams {\n  /** File ID to retrieve */\n  fileId: number;\n  /** Whether to include metadata */\n  includeMetadata?: boolean;\n}\n\n/**\n * Parameters for downloading a file\n *\n * @category Data Management\n */\nexport interface DownloadFileParams {\n  /** File URL or ID to download */\n  file: string | number;\n  /** Storage provider to use */\n  storageProvider?: string;\n  /** Decryption key if file is encrypted */\n  decryptionKey?: string;\n}\n\n/**\n * Result of downloading a file\n *\n * @category Data Management\n */\nexport interface DownloadFileResult {\n  /** File content */\n  content: Uint8Array;\n  /** File metadata */\n  metadata?: FileMetadata;\n  /** Whether the file was encrypted */\n  wasEncrypted?: boolean;\n}\n\n/**\n * Parameters for deleting a file\n *\n * @category Data Management\n */\nexport interface DeleteFileParams {\n  /** File ID to delete */\n  fileId: number;\n  /** Whether to also delete from storage */\n  deleteFromStorage?: boolean;\n  /** Storage provider to delete from */\n  storageProvider?: string;\n}\n\n/**\n * Result of deleting a file\n *\n * @category Data Management\n */\nexport interface DeleteFileResult {\n  /** Whether the file was successfully deleted from the registry */\n  registryDeleted: boolean;\n  /** Whether the file was successfully deleted from storage */\n  storageDeleted?: boolean;\n  /** Transaction hash of the deletion */\n  transactionHash?: Hash;\n}\n\n/**\n * Options for encrypting a file\n *\n * @category Data Management\n */\nexport interface EncryptFileOptions {\n  /** Encryption seed for key derivation. Defaults to DEFAULT_ENCRYPTION_SEED */\n  seed?: string;\n  /** MIME type for the encrypted blob if input is not already a Blob */\n  mimeType?: string;\n}\n\n/**\n * Result of encrypting a file\n *\n * @category Data Management\n */\nexport interface EncryptFileResult {\n  /** The encrypted data as a Blob */\n  encryptedData: Blob;\n  /** The encryption key used (derived from wallet) */\n  encryptionKey: string;\n}\n\n/**\n * Options for decrypting a file\n *\n * @category Data Management\n */\nexport interface DecryptFileOptions {\n  /** Encryption seed for key derivation. Defaults to DEFAULT_ENCRYPTION_SEED */\n  seed?: string;\n}\n\n/**\n * Parameters for uploading a file with permissions\n *\n * @category Data Management\n */\nexport interface UploadFileWithPermissionsParams {\n  /** The file data to encrypt and upload */\n  data: Blob;\n  /** Array of permissions to grant, each with account address and public key */\n  permissions: Array<{ account: Address; publicKey: string }>;\n  /** Optional filename for the upload */\n  filename?: string;\n  /** Optional storage provider to use */\n  providerName?: string;\n}\n\n/**\n * Parameters for adding permission to a file\n *\n * @category Data Management\n */\nexport interface AddFilePermissionParams {\n  /** The file ID to grant permission for */\n  fileId: number;\n  /** The account to grant permission to */\n  account: Address;\n  /** The public key of the account for encryption */\n  publicKey: string;\n}\n\n/**\n * Options for decrypting a file with permission\n *\n * @category Data Management\n */\nexport interface DecryptFileWithPermissionOptions {\n  /** Optional account address to verify permission against */\n  account?: Address;\n}\n\n/**\n * File access permissions\n *\n * @category Data Management\n */\nexport interface FileAccessPermissions {\n  /** Whether the file can be read */\n  read: boolean;\n  /** Whether the file can be written */\n  write: boolean;\n  /** Whether the file can be deleted */\n  delete: boolean;\n  /** Whether the file can be shared */\n  share: boolean;\n}\n\n/**\n * File sharing configuration\n *\n * @category Data Management\n */\nexport interface FileSharingConfig {\n  /** Addresses that can access the file */\n  allowedAddresses?: Address[];\n  /** Expiration time for shared access */\n  expiresAt?: Date;\n  /** Required permissions for shared access */\n  permissions: FileAccessPermissions;\n}\n\n/**\n * Batch upload parameters\n *\n * @category Data Management\n */\nexport interface BatchUploadParams {\n  /** Array of files to upload */\n  files: UploadFileParams[];\n  /** Storage provider to use for all files */\n  storageProvider?: string;\n  /** Whether to encrypt all files */\n  encrypt?: boolean;\n  /** Encryption key for all files */\n  encryptionKey?: string;\n}\n\n/**\n * Batch upload result\n *\n * @category Data Management\n */\nexport interface BatchUploadResult {\n  /** Results for each uploaded file */\n  results: UploadEncryptedFileResult[];\n  /** Overall success status */\n  success: boolean;\n  /** Any errors that occurred */\n  errors?: string[];\n}\n\n/**\n * Schema metadata from the blockchain (without fetched definition).\n *\n * This represents the on-chain schema registration data before the\n * definition has been fetched from the storage URL.\n *\n * @category Data Management\n */\nexport interface SchemaMetadata {\n  /** Schema ID */\n  id: number;\n  /** Schema name */\n  name: string;\n  /** Schema dialect ('json' or 'sqlite') */\n  dialect: \"json\" | \"sqlite\";\n  /** URL containing the schema definition */\n  definitionUrl: string;\n}\n\n/**\n * Complete schema with all definition fields populated.\n * This is what schemas.get() returns - a schema with the definition fetched.\n */\nexport interface CompleteSchema extends SchemaMetadata {\n  /** Version of the schema */\n  version: string;\n  /** Optional description of the schema */\n  description?: string;\n  /** Optional version of the dialect */\n  dialectVersion?: string;\n  /** The actual schema - JSON Schema object for 'json' dialect, DDL string for 'sqlite' */\n  schema: object | string;\n}\n\n/**\n * Schema with optional definition fields.\n *\n * Schemas define the structure and validation rules for user data processed by refiners.\n * They ensure data quality and consistency across the Vana network by specifying how\n * raw user data should be formatted, validated, and processed.\n *\n * When the definition has been fetched (via schemas.get() or schemas.list() with includeDefinitions),\n * the version and schema fields will be populated. Otherwise, only the metadata fields are present.\n *\n * @category Data Management\n * @example\n * ```typescript\n * // Complete schema from schemas.get()\n * const completeSchema: Schema = {\n *   id: 5,\n *   name: 'Social Media Profile',\n *   dialect: 'json',\n *   definitionUrl: 'ipfs://QmSchema...',\n *   version: '1.0.0',\n *   description: 'Schema for validating social media profile data',\n *   schema: { // JSON Schema object\n *     type: 'object',\n *     properties: {\n *       username: { type: 'string' }\n *     }\n *   }\n * };\n *\n * // Metadata-only schema from schemas.list() without includeDefinitions\n * const metadataSchema: Schema = {\n *   id: 5,\n *   name: 'Social Media Profile',\n *   dialect: 'json',\n *   definitionUrl: 'ipfs://QmSchema...'\n * };\n * ```\n */\nexport interface Schema extends SchemaMetadata {\n  /** Version of the schema (present when definition is fetched) */\n  version?: string;\n  /** Optional description of the schema */\n  description?: string;\n  /** Optional version of the dialect */\n  dialectVersion?: string;\n  /** The actual schema - JSON Schema object for 'json' dialect, DDL string for 'sqlite' (present when definition is fetched) */\n  schema?: object | string;\n}\n\n/**\n * Represents a refiner with schema information\n *\n * @category Data Management\n */\nexport interface Refiner {\n  /** Refiner ID */\n  id: number;\n  /** DLP ID this refiner belongs to */\n  dlpId: number;\n  /** Owner address */\n  owner: Address;\n  /** Refiner name */\n  name: string;\n  /** Schema ID associated with this refiner */\n  schemaId: number;\n  /** URL containing refinement instructions */\n  refinementInstructionUrl: string;\n}\n\n/**\n * Parameters for adding a new schema\n *\n * @category Data Management\n */\nexport interface AddSchemaParams {\n  /** Schema name */\n  name: string;\n  /** Schema dialect */\n  dialect: string;\n  /** URL containing the schema definition */\n  definitionUrl: string;\n}\n\n/**\n * Result of adding a schema\n *\n * @category Data Management\n */\nexport interface AddSchemaResult {\n  /** The new schema ID assigned by the contract */\n  schemaId: number;\n  /** Transaction hash of the schema registration */\n  transactionHash: Hash;\n}\n\n/**\n * Parameters for registering a new data refiner in the Vana network.\n *\n * Refiners are processors that transform and validate user data according to specific\n * schemas and instructions. They enable applications to work with structured, verified\n * user data while maintaining privacy and user control.\n *\n * @category Data Management\n * @example\n * ```typescript\n * const refinerParams: AddRefinerParams = {\n *   dlpId: 1, // Data Liquidity Pool ID\n *   name: 'Social Media Refiner',\n *   schemaId: 5, // Pre-defined schema for social media data\n *   refinementInstructionUrl: 'ipfs://Qm...' // Instructions for data processing\n * };\n * ```\n */\nexport interface AddRefinerParams {\n  /** DLP ID this refiner belongs to */\n  dlpId: number;\n  /** Refiner name */\n  name: string;\n  /** Schema ID to associate with this refiner */\n  schemaId: number;\n  /** URL containing refinement instructions */\n  refinementInstructionUrl: string;\n}\n\n/**\n * Result of adding a refiner\n *\n * @category Data Management\n */\nexport interface AddRefinerResult {\n  /** The new refiner ID assigned by the contract */\n  refinerId: number;\n  /** Transaction hash of the refiner registration */\n  transactionHash: Hash;\n}\n\n/**\n * Parameters for updating a refiner's schema ID\n *\n * @category Data Management\n */\nexport interface UpdateSchemaIdParams {\n  /** Refiner ID to update */\n  refinerId: number;\n  /** New schema ID to associate with the refiner */\n  newSchemaId: number;\n}\n\n/**\n * Result of updating a refiner's schema ID\n *\n * @category Data Management\n */\nexport interface UpdateSchemaIdResult {\n  /** Transaction hash of the update */\n  transactionHash: Hash;\n}\n\n/**\n * Trusted server data structure\n *\n * @category Data Management\n */\nexport interface TrustedServer {\n  /** Unique identifier for the trusted server relationship */\n  id: string;\n  /** Server address (EVM address) */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Timestamp when server was trusted */\n  trustedAt: bigint;\n  /** User who trusted the server */\n  user: Address;\n  /** Index in user's trusted server list (only available in RPC mode) */\n  trustIndex?: number;\n}\n\n/**\n * Parameters for getUserTrustedServers method\n *\n * @category Data Management\n */\nexport interface GetUserTrustedServersParams {\n  /** User address to query trusted servers for */\n  user: Address;\n  /** Optional subgraph URL to override default */\n  subgraphUrl?: string;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}