@opendatalabs/vana-sdk 0.1.0-alpha.a25bcc7 → 0.1.0-alpha.a6b60fc

package/dist/types/operations.d.ts

@@ -2,8 +2,15 @@ import type { Hash, TransactionReceipt as ViemReceipt, Address } from "viem";
 import type { GetOperationResponse } from "../generated/server/server-exports";
 import type { Contract, Fn } from "../generated/event-types";
 /**
- * Server operation result as a plain object.
+ * Represents a server-side operation status and result.
+ *
+ * @remarks
+ * Operations track asynchronous server processes like data refinement or ML inference.
+ * Poll operation status using `vana.server.waitForOperation()` until completion.
  * Fully serializable for API responses and cross-process communication.
+ *
+ * @category Operations
+ * @see {@link https://docs.vana.org/docs/operations | Operations Guide}
  */
 export interface Operation<T = unknown> {
     /** Unique operation identifier */
@@ -26,7 +33,27 @@ export interface Operation<T = unknown> {
  *
  * @remarks
  * Transaction results MUST include contract and function for proper event parsing.
- * This is a strongly-typed, heuristic-free design following POJO architecture.
+ * This strongly-typed design enables automatic event extraction without heuristics.
+ * Use `vana.waitForTransactionEvents()` to retrieve typed events from the receipt.
+ *
+ * **Architecture:**
+ * POJOs (Plain Old JavaScript Objects) ensure serialization safety and framework
+ * independence. Contract and function fields enable deterministic event parsing.
+ *
+ * @category Operations
+ * @example
+ * ```typescript
+ * const result: TransactionResult = {
+ *   hash: '0x123...',
+ *   from: '0x456...',
+ *   contract: 'DataRegistry',
+ *   fn: 'addFile',
+ *   chainId: 14800
+ * };
+ *
+ * // Wait for events
+ * const events = await vana.waitForTransactionEvents(result);
+ * ```
  */
 export interface TransactionResult<C extends Contract = Contract, F extends Fn<C> = Fn<C>> {
     /** Transaction hash for tracking and confirmation */
@@ -47,14 +74,26 @@ export interface TransactionResult<C extends Contract = Contract, F extends Fn<C
     to?: Address;
 }
 /**
- * Extended transaction receipt with Vana-specific fields
+ * Extends viem's TransactionReceipt with Vana-specific event data.
+ *
+ * @remarks
+ * Includes parsed event data when available after transaction confirmation.
+ * Use this for detailed transaction analysis and event processing.
+ *
+ * @category Operations
  */
 export interface TransactionReceipt extends ViemReceipt {
     /** Parsed event data if available */
     events?: unknown;
 }
 /**
- * Options for polling operations
+ * Configures polling behavior for asynchronous operations.
+ *
+ * @remarks
+ * Controls how frequently and how long to poll for operation completion.
+ * Lower intervals provide faster updates but increase server load.
+ *
+ * @category Operations
  */
 export interface PollingOptions {
     /** Polling interval in milliseconds (default: 500) */
@@ -63,7 +102,13 @@ export interface PollingOptions {
     timeout?: number;
 }
 /**
- * Options for waiting for transaction confirmation
+ * Configures transaction confirmation waiting behavior.
+ *
+ * @remarks
+ * Controls confirmation depth and timeout for transaction finality.
+ * Higher confirmations provide more security against chain reorganizations.
+ *
+ * @category Operations
  */
 export interface TransactionWaitOptions {
     /** Number of confirmations to wait for (default: 1) */
@@ -76,36 +121,108 @@ export interface TransactionWaitOptions {
 /**
  * Validates whether an object conforms to the Operation interface.
  *
- * @param obj - The object to validate as an Operation.
- * @returns `true` if the object has required Operation properties, `false` otherwise.
+ * @remarks
+ * Type guard for runtime validation of operation objects from external sources.
+ * Use when deserializing operations from API responses or storage.
+ *
+ * @param obj - The object to validate as an Operation
+ * @returns `true` if the object has required Operation properties, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/api/operation/123');
+ * const data = await response.json();
+ *
+ * if (isOperation(data)) {
+ *   console.log(`Operation ${data.id}: ${data.status}`);
+ * }
+ * ```
+ *
+ * @category Operations
  */
 export declare function isOperation(obj: unknown): obj is Operation;
 /**
  * Validates whether an object conforms to the TransactionResult interface.
  *
- * @param obj - The object to validate as a TransactionResult.
- * @returns `true` if the object has a valid transaction hash, `false` otherwise.
+ * @remarks
+ * Type guard for runtime validation of transaction results.
+ * Checks for required hash field with proper `0x` prefix.
+ *
+ * @param obj - The object to validate as a TransactionResult
+ * @returns `true` if the object has a valid transaction hash, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isTransactionResult(result)) {
+ *   await vana.waitForTransactionEvents(result);
+ * }
+ * ```
+ *
+ * @category Operations
  */
 export declare function isTransactionResult(obj: unknown): obj is TransactionResult;
 /**
  * Converts a server response to an Operation POJO.
  *
- * @param response - The raw server response containing operation status data.
- * @returns An Operation object with normalized fields for client consumption.
+ * @remarks
+ * Normalizes server responses into consistent Operation format.
+ * Separates success results from error messages based on status.
+ *
+ * @param response - The raw server response containing operation status data
+ * @returns An Operation object with normalized fields for client consumption
+ *
+ * @example
+ * ```typescript
+ * const serverResponse = await api.getOperation('op-123');
+ * const operation = toOperation<MLResult>(serverResponse);
+ *
+ * if (operation.status === 'succeeded') {
+ *   console.log('Result:', operation.result);
+ * }
+ * ```
+ *
+ * @category Operations
  */
 export declare function toOperation<T>(response: GetOperationResponse): Operation<T>;
 /**
  * Extracts the operation ID from flexible input types.
  *
- * @param opOrId - An Operation object containing an `id` field or a raw operation ID string.
- * @returns The operation ID string for use in API calls.
+ * @remarks
+ * Utility for handling both Operation objects and raw ID strings.
+ * Enables flexible API design accepting either format.
+ *
+ * @param opOrId - An Operation object containing an `id` field or a raw operation ID string
+ * @returns The operation ID string for use in API calls
+ *
+ * @example
+ * ```typescript
+ * // Works with both formats
+ * await vana.server.getOperation(operation); // Operation object
+ * await vana.server.getOperation('op-123');  // ID string
+ * ```
+ *
+ * @category Operations
  */
 export declare function getOperationId(opOrId: Operation | string): string;
 /**
  * Extracts the transaction hash from flexible input types.
  *
- * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string.
- * @returns The transaction hash as a `0x`-prefixed string.
+ * @remarks
+ * Utility for handling TransactionResult objects, hash objects, or raw hash strings.
+ * Enables consistent hash extraction across different transaction representations.
+ *
+ * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string
+ * @returns The transaction hash as a `0x`-prefixed string
+ *
+ * @example
+ * ```typescript
+ * // All these work
+ * const hash1 = getTransactionHash(transactionResult);
+ * const hash2 = getTransactionHash({ hash: '0x123...' });
+ * const hash3 = getTransactionHash('0x123...');
+ * ```
+ *
+ * @category Operations
  */
 export declare function getTransactionHash(txOrHash: TransactionResult | {
     hash: Hash;

package/dist/types/operations.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type { GetOperationResponse } from \"../generated/server/server-exports\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n/**\n * Server operation result as a plain object.\n * Fully serializable for API responses and cross-process communication.\n */\nexport interface Operation<T = unknown> {\n  /** Unique operation identifier */\n  id: string;\n  /** Current operation status */\n  status: \"starting\" | \"running\" | \"succeeded\" | \"failed\" | \"canceled\";\n  /** Unix timestamp when operation was created */\n  createdAt: number;\n  /** Unix timestamp when operation was last updated */\n  updatedAt?: number;\n  /** Operation result when status is 'succeeded' */\n  result?: T;\n  /** Error message when status is 'failed' */\n  error?: string;\n  /** Additional operation metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Represents a submitted blockchain transaction as a self-describing POJO.\n *\n * @remarks\n * Transaction results MUST include contract and function for proper event parsing.\n * This is a strongly-typed, heuristic-free design following POJO architecture.\n */\nexport interface TransactionResult<\n  C extends Contract = Contract,\n  F extends Fn<C> = Fn<C>,\n> {\n  /** Transaction hash for tracking and confirmation */\n  hash: Hash;\n  /** Sender's wallet address */\n  from: Address;\n  /** Contract that was called (required for event parsing) */\n  contract: C;\n  /** Function that was called (required for event parsing) */\n  fn: F;\n  /** Network chain ID where transaction was submitted */\n  chainId?: number;\n  /** Transaction value in wei (for payable functions) */\n  value?: bigint;\n  /** Transaction sequence number for the sender */\n  nonce?: number;\n  /** Contract address (if different from standard deployment) */\n  to?: Address;\n}\n\n/**\n * Extended transaction receipt with Vana-specific fields\n */\nexport interface TransactionReceipt extends ViemReceipt {\n  /** Parsed event data if available */\n  events?: unknown;\n}\n\n/**\n * Options for polling operations\n */\nexport interface PollingOptions {\n  /** Polling interval in milliseconds (default: 500) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Options for waiting for transaction confirmation\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Polling interval in milliseconds (default: 1000) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Validates whether an object conforms to the Operation interface.\n *\n * @param obj - The object to validate as an Operation.\n * @returns `true` if the object has required Operation properties, `false` otherwise.\n */\nexport function isOperation(obj: unknown): obj is Operation {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    typeof (obj as Record<string, unknown>).id === \"string\" &&\n    typeof (obj as Record<string, unknown>).status === \"string\"\n  );\n}\n\n/**\n * Validates whether an object conforms to the TransactionResult interface.\n *\n * @param obj - The object to validate as a TransactionResult.\n * @returns `true` if the object has a valid transaction hash, `false` otherwise.\n */\nexport function isTransactionResult(obj: unknown): obj is TransactionResult {\n  if (typeof obj !== \"object\" || obj === null || !(\"hash\" in obj)) {\n    return false;\n  }\n  const { hash } = obj as Record<string, unknown>;\n  return typeof hash === \"string\" && hash.startsWith(\"0x\");\n}\n\n/**\n * Converts a server response to an Operation POJO.\n *\n * @param response - The raw server response containing operation status data.\n * @returns An Operation object with normalized fields for client consumption.\n */\nexport function toOperation<T>(response: GetOperationResponse): Operation<T> {\n  return {\n    id: response.id,\n    status: response.status as Operation[\"status\"],\n    createdAt: Date.now(), // Server doesn't provide this, so we use current time\n    result:\n      response.status === \"succeeded\" ? (response.result as T) : undefined,\n    error:\n      response.status === \"failed\" ? (response.result ?? undefined) : undefined,\n  };\n}\n\n/**\n * Extracts the operation ID from flexible input types.\n *\n * @param opOrId - An Operation object containing an `id` field or a raw operation ID string.\n * @returns The operation ID string for use in API calls.\n */\nexport function getOperationId(opOrId: Operation | string): string {\n  return typeof opOrId === \"string\" ? opOrId : opOrId.id;\n}\n\n/**\n * Extracts the transaction hash from flexible input types.\n *\n * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string.\n * @returns The transaction hash as a `0x`-prefixed string.\n */\nexport function getTransactionHash(\n  txOrHash: TransactionResult | { hash: Hash } | Hash,\n): Hash {\n  if (typeof txOrHash === \"string\") {\n    return txOrHash;\n  }\n  return txOrHash.hash;\n}\n"],"mappings":"AA0FO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,QAAQ,OACR,YAAY,OACZ,OAAQ,IAAgC,OAAO,YAC/C,OAAQ,IAAgC,WAAW;AAEvD;AAQO,SAAS,oBAAoB,KAAwC;AAC1E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,UAAU,MAAM;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,EAAE,KAAK,IAAI;AACjB,SAAO,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI;AACzD;AAQO,SAAS,YAAe,UAA8C;AAC3E,SAAO;AAAA,IACL,IAAI,SAAS;AAAA,IACb,QAAQ,SAAS;AAAA,IACjB,WAAW,KAAK,IAAI;AAAA;AAAA,IACpB,QACE,SAAS,WAAW,cAAe,SAAS,SAAe;AAAA,IAC7D,OACE,SAAS,WAAW,WAAY,SAAS,UAAU,SAAa;AAAA,EACpE;AACF;AAQO,SAAS,eAAe,QAAoC;AACjE,SAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;AAQO,SAAS,mBACd,UACM;AACN,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AACA,SAAO,SAAS;AAClB;","names":[]}
+{"version":3,"sources":["../../src/types/operations.ts"],"sourcesContent":["import type { Hash, TransactionReceipt as ViemReceipt, Address } from \"viem\";\nimport type { GetOperationResponse } from \"../generated/server/server-exports\";\nimport type { Contract, Fn } from \"../generated/event-types\";\n\n/**\n * Represents a server-side operation status and result.\n *\n * @remarks\n * Operations track asynchronous server processes like data refinement or ML inference.\n * Poll operation status using `vana.server.waitForOperation()` until completion.\n * Fully serializable for API responses and cross-process communication.\n *\n * @category Operations\n * @see {@link https://docs.vana.org/docs/operations | Operations Guide}\n */\nexport interface Operation<T = unknown> {\n  /** Unique operation identifier */\n  id: string;\n  /** Current operation status */\n  status: \"starting\" | \"running\" | \"succeeded\" | \"failed\" | \"canceled\";\n  /** Unix timestamp when operation was created */\n  createdAt: number;\n  /** Unix timestamp when operation was last updated */\n  updatedAt?: number;\n  /** Operation result when status is 'succeeded' */\n  result?: T;\n  /** Error message when status is 'failed' */\n  error?: string;\n  /** Additional operation metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Represents a submitted blockchain transaction as a self-describing POJO.\n *\n * @remarks\n * Transaction results MUST include contract and function for proper event parsing.\n * This strongly-typed design enables automatic event extraction without heuristics.\n * Use `vana.waitForTransactionEvents()` to retrieve typed events from the receipt.\n *\n * **Architecture:**\n * POJOs (Plain Old JavaScript Objects) ensure serialization safety and framework\n * independence. Contract and function fields enable deterministic event parsing.\n *\n * @category Operations\n * @example\n * ```typescript\n * const result: TransactionResult = {\n *   hash: '0x123...',\n *   from: '0x456...',\n *   contract: 'DataRegistry',\n *   fn: 'addFile',\n *   chainId: 14800\n * };\n *\n * // Wait for events\n * const events = await vana.waitForTransactionEvents(result);\n * ```\n */\nexport interface TransactionResult<\n  C extends Contract = Contract,\n  F extends Fn<C> = Fn<C>,\n> {\n  /** Transaction hash for tracking and confirmation */\n  hash: Hash;\n  /** Sender's wallet address */\n  from: Address;\n  /** Contract that was called (required for event parsing) */\n  contract: C;\n  /** Function that was called (required for event parsing) */\n  fn: F;\n  /** Network chain ID where transaction was submitted */\n  chainId?: number;\n  /** Transaction value in wei (for payable functions) */\n  value?: bigint;\n  /** Transaction sequence number for the sender */\n  nonce?: number;\n  /** Contract address (if different from standard deployment) */\n  to?: Address;\n}\n\n/**\n * Extends viem's TransactionReceipt with Vana-specific event data.\n *\n * @remarks\n * Includes parsed event data when available after transaction confirmation.\n * Use this for detailed transaction analysis and event processing.\n *\n * @category Operations\n */\nexport interface TransactionReceipt extends ViemReceipt {\n  /** Parsed event data if available */\n  events?: unknown;\n}\n\n/**\n * Configures polling behavior for asynchronous operations.\n *\n * @remarks\n * Controls how frequently and how long to poll for operation completion.\n * Lower intervals provide faster updates but increase server load.\n *\n * @category Operations\n */\nexport interface PollingOptions {\n  /** Polling interval in milliseconds (default: 500) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Configures transaction confirmation waiting behavior.\n *\n * @remarks\n * Controls confirmation depth and timeout for transaction finality.\n * Higher confirmations provide more security against chain reorganizations.\n *\n * @category Operations\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Polling interval in milliseconds (default: 1000) */\n  pollingInterval?: number;\n  /** Maximum time to wait in milliseconds (default: 30000) */\n  timeout?: number;\n}\n\n/**\n * Validates whether an object conforms to the Operation interface.\n *\n * @remarks\n * Type guard for runtime validation of operation objects from external sources.\n * Use when deserializing operations from API responses or storage.\n *\n * @param obj - The object to validate as an Operation\n * @returns `true` if the object has required Operation properties, `false` otherwise\n *\n * @example\n * ```typescript\n * const response = await fetch('/api/operation/123');\n * const data = await response.json();\n *\n * if (isOperation(data)) {\n *   console.log(`Operation ${data.id}: ${data.status}`);\n * }\n * ```\n *\n * @category Operations\n */\nexport function isOperation(obj: unknown): obj is Operation {\n  return (\n    typeof obj === \"object\" &&\n    obj !== null &&\n    \"id\" in obj &&\n    \"status\" in obj &&\n    typeof (obj as Record<string, unknown>).id === \"string\" &&\n    typeof (obj as Record<string, unknown>).status === \"string\"\n  );\n}\n\n/**\n * Validates whether an object conforms to the TransactionResult interface.\n *\n * @remarks\n * Type guard for runtime validation of transaction results.\n * Checks for required hash field with proper `0x` prefix.\n *\n * @param obj - The object to validate as a TransactionResult\n * @returns `true` if the object has a valid transaction hash, `false` otherwise\n *\n * @example\n * ```typescript\n * if (isTransactionResult(result)) {\n *   await vana.waitForTransactionEvents(result);\n * }\n * ```\n *\n * @category Operations\n */\nexport function isTransactionResult(obj: unknown): obj is TransactionResult {\n  if (typeof obj !== \"object\" || obj === null || !(\"hash\" in obj)) {\n    return false;\n  }\n  const { hash } = obj as Record<string, unknown>;\n  return typeof hash === \"string\" && hash.startsWith(\"0x\");\n}\n\n/**\n * Converts a server response to an Operation POJO.\n *\n * @remarks\n * Normalizes server responses into consistent Operation format.\n * Separates success results from error messages based on status.\n *\n * @param response - The raw server response containing operation status data\n * @returns An Operation object with normalized fields for client consumption\n *\n * @example\n * ```typescript\n * const serverResponse = await api.getOperation('op-123');\n * const operation = toOperation<MLResult>(serverResponse);\n *\n * if (operation.status === 'succeeded') {\n *   console.log('Result:', operation.result);\n * }\n * ```\n *\n * @category Operations\n */\nexport function toOperation<T>(response: GetOperationResponse): Operation<T> {\n  return {\n    id: response.id,\n    status: response.status as Operation[\"status\"],\n    createdAt: Date.now(), // Server doesn't provide this, so we use current time\n    result:\n      response.status === \"succeeded\" ? (response.result as T) : undefined,\n    error:\n      response.status === \"failed\" ? (response.result ?? undefined) : undefined,\n  };\n}\n\n/**\n * Extracts the operation ID from flexible input types.\n *\n * @remarks\n * Utility for handling both Operation objects and raw ID strings.\n * Enables flexible API design accepting either format.\n *\n * @param opOrId - An Operation object containing an `id` field or a raw operation ID string\n * @returns The operation ID string for use in API calls\n *\n * @example\n * ```typescript\n * // Works with both formats\n * await vana.server.getOperation(operation); // Operation object\n * await vana.server.getOperation('op-123');  // ID string\n * ```\n *\n * @category Operations\n */\nexport function getOperationId(opOrId: Operation | string): string {\n  return typeof opOrId === \"string\" ? opOrId : opOrId.id;\n}\n\n/**\n * Extracts the transaction hash from flexible input types.\n *\n * @remarks\n * Utility for handling TransactionResult objects, hash objects, or raw hash strings.\n * Enables consistent hash extraction across different transaction representations.\n *\n * @param txOrHash - A TransactionResult object, any object with a `hash` field, or a raw hash string\n * @returns The transaction hash as a `0x`-prefixed string\n *\n * @example\n * ```typescript\n * // All these work\n * const hash1 = getTransactionHash(transactionResult);\n * const hash2 = getTransactionHash({ hash: '0x123...' });\n * const hash3 = getTransactionHash('0x123...');\n * ```\n *\n * @category Operations\n */\nexport function getTransactionHash(\n  txOrHash: TransactionResult | { hash: Hash } | Hash,\n): Hash {\n  if (typeof txOrHash === \"string\") {\n    return txOrHash;\n  }\n  return txOrHash.hash;\n}\n"],"mappings":"AAuJO,SAAS,YAAY,KAAgC;AAC1D,SACE,OAAO,QAAQ,YACf,QAAQ,QACR,QAAQ,OACR,YAAY,OACZ,OAAQ,IAAgC,OAAO,YAC/C,OAAQ,IAAgC,WAAW;AAEvD;AAqBO,SAAS,oBAAoB,KAAwC;AAC1E,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,UAAU,MAAM;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,EAAE,KAAK,IAAI;AACjB,SAAO,OAAO,SAAS,YAAY,KAAK,WAAW,IAAI;AACzD;AAwBO,SAAS,YAAe,UAA8C;AAC3E,SAAO;AAAA,IACL,IAAI,SAAS;AAAA,IACb,QAAQ,SAAS;AAAA,IACjB,WAAW,KAAK,IAAI;AAAA;AAAA,IACpB,QACE,SAAS,WAAW,cAAe,SAAS,SAAe;AAAA,IAC7D,OACE,SAAS,WAAW,WAAY,SAAS,UAAU,SAAa;AAAA,EACpE;AACF;AAqBO,SAAS,eAAe,QAAoC;AACjE,SAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;AAsBO,SAAS,mBACd,UACM;AACN,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AACA,SAAO,SAAS;AAClB;","names":[]}

package/dist/types/permissions.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/permissions.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Base interface for types that need to be compatible with Record<string, unknown>\n *\n * @category Permissions\n */\nexport interface RecordCompatible {\n  [key: string]: unknown;\n}\n\n/**\n * Represents on-chain permission grant data without expensive off-chain resolution.\n *\n * This interface contains only the fast, on-chain data that can be retrieved\n * efficiently from the subgraph without making individual IPFS or contract calls.\n * Use this for fast permission listing in UIs, then call `retrieveGrantFile()`\n * on specific grants when detailed data is needed.\n *\n * @category Permissions\n * @example\n * ```typescript\n * // Fast: Get all on-chain permission data\n * const grants = await vana.permissions.getUserPermissionGrantsOnChain();\n *\n * // Lazy: Resolve detailed data for specific permission when needed\n * const grantFile = await retrieveGrantFile(grants[0].grantUrl);\n * console.log('Operation:', grantFile.operation);\n * ```\n */\nexport interface OnChainPermissionGrant {\n  /** Unique identifier for the permission */\n  id: bigint;\n  /** The grant URL containing detailed permission parameters (IPFS link) */\n  grantUrl: string;\n  /** Cryptographic signature that authorized this permission */\n  grantSignature: string;\n  /** Nonce used when granting the permission */\n  nonce: bigint;\n  /** Block number when permission started */\n  startBlock: bigint;\n  /** Block number when permission was granted */\n  addedAtBlock: bigint;\n  /** Timestamp when permission was added */\n  addedAtTimestamp: bigint;\n  /** Transaction hash of the grant transaction */\n  transactionHash: string;\n  /** Address that granted the permission */\n  grantor: Address;\n  /** Grantee information */\n  grantee: {\n    /** Grantee ID */\n    id: string;\n    /** Grantee address */\n    address: string;\n  };\n  /** Whether the permission is still active (not revoked) */\n  active: boolean;\n}\n\n/**\n * Options for retrieving user permissions\n *\n * @category Permissions\n */\nexport interface GetUserPermissionsOptions {\n  /** Maximum number of permissions to retrieve */\n  limit?: number;\n  /** Custom subgraph URL to use for querying */\n  subgraphUrl?: string;\n}\n\n/**\n * Parameters for granting data access permission to an application.\n *\n * This interface defines the required and optional parameters when granting\n * an application permission to access specific files for a particular operation.\n * Used with `vana.permissions.grant()`.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const params: GrantPermissionParams = {\n *   grantee: '0x1234...', // Application address\n *   operation: 'llm_inference',\n *   files: [1, 2, 3], // File IDs to grant access to\n *   parameters: {\n *     model: 'gpt-4',\n *     maxTokens: 1000,\n *     prompt: 'Analyze my data'\n *   }\n * };\n * ```\n */\nexport interface GrantPermissionParams {\n  /** The on-chain identity of the application */\n  grantee: Address;\n  /** The class of computation, e.g., \"llm_inference\" */\n  operation: string;\n  /**\n   * Array of file IDs to grant permission for.\n   * Obtain file IDs from `vana.data.getUserFiles()` or from upload results via `vana.data.upload().fileId`.\n   */\n  files: number[];\n  /** The full, off-chain parameters (e.g., LLM prompt) */\n  parameters: Record<string, unknown>;\n  /** Optional pre-stored grant URL to avoid duplicate IPFS storage */\n  grantUrl?: string;\n  /** Optional nonce for the permission */\n  nonce?: bigint;\n  /** Optional expiration time for the permission */\n  expiresAt?: number;\n}\n\n/**\n * Parameters for revoking a previously granted data access permission.\n *\n * Used with `PermissionsController.revoke()` to remove an application's access\n * to user data. Once revoked, the application can no longer use the permission\n * to access the specified files.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const revokeParams: RevokePermissionParams = {\n *   permissionId: 123n // Permission ID to revoke\n * };\n *\n * await vana.permissions.revoke(revokeParams);\n * ```\n */\nexport interface RevokePermissionParams {\n  /** The permission ID to revoke */\n  permissionId: bigint;\n}\n\n/**\n * Parameters for checking if a specific permission exists and is valid.\n *\n * Used to verify whether an application has active permission to access\n * specific user files for a particular operation before attempting to use the data.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const checkParams: CheckPermissionParams = {\n *   application: '0x1234...', // App address\n *   operation: 'llm_inference',\n *   files: [1, 2, 3], // File IDs to check\n *   parameters: { model: 'gpt-4' }, // Operation parameters\n *   user: '0xabcd...' // Optional specific user\n * };\n *\n * const hasPermission = await vana.permissions.check(checkParams);\n * ```\n */\nexport interface CheckPermissionParams {\n  /** The application address */\n  application: Address;\n  /** The operation type */\n  operation: string;\n  /** The file IDs */\n  files: number[];\n  /** The grant parameters */\n  parameters: Record<string, unknown>;\n  /** The user address */\n  user?: Address;\n}\n\n/**\n * Permission check result\n *\n * @category Permissions\n */\nexport interface PermissionCheckResult {\n  /** Whether the permission exists and is valid */\n  exists: boolean;\n  /** The permission details if it exists */\n  permission?: GrantedPermission;\n  /** Reason why permission is invalid (if applicable) */\n  reason?: string;\n}\n\n/**\n * EIP-712 domain definition for PermissionGrant signatures\n *\n * @category Permissions\n */\nexport interface PermissionGrantDomain {\n  /** Domain name */\n  name: string;\n  /** Domain version */\n  version: string;\n  /** Chain ID */\n  chainId: number;\n  /** Verifying contract address */\n  verifyingContract: Address;\n}\n\n/**\n * EIP-712 Permission message structure (current contract format)\n *\n * @category Permissions\n */\nexport interface PermissionGrantMessage {\n  /** Application address */\n  application: Address;\n  /** File IDs */\n  files: number[];\n  /** Operation type */\n  operation: string;\n  /** Grant URL */\n  grant: string;\n  /** Parameters as JSON string */\n  parameters: string;\n  /** Nonce */\n  nonce: bigint;\n}\n\n/**\n * EIP-712 PermissionInput message structure (new simplified format)\n *\n * @category Permissions\n */\nexport interface PermissionInputMessage extends RecordCompatible {\n  /** Nonce */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** File IDs */\n  fileIds: bigint[];\n}\n\n/**\n * Contract PermissionInput structure\n *\n * @category Permissions\n */\nexport interface PermissionInput {\n  /** Nonce */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** File IDs to grant permission for */\n  fileIds: bigint[];\n}\n\n/**\n * Contract RevokePermissionInput structure\n *\n * @category Permissions\n */\nexport interface RevokePermissionInput extends RecordCompatible {\n  /** Nonce */\n  nonce: bigint;\n  /** Permission ID to revoke */\n  permissionId: bigint;\n}\n\n/**\n * Contract Permission Info structure returned from the contract\n *\n * @category Permissions\n */\nexport interface PermissionInfo {\n  /** Permission ID */\n  id: bigint;\n  /** Address that granted the permission */\n  grantor: Address;\n  /** Nonce used when creating */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** Signature bytes (removed in newer contract versions) */\n  signature?: `0x${string}`;\n  /** Start block */\n  startBlock: bigint;\n  /** End block */\n  endBlock: bigint;\n  /** File IDs associated with this permission */\n  fileIds: readonly bigint[];\n}\n\n/**\n * EIP-712 Permission message structure (simplified future format)\n *\n * @category Permissions\n */\nexport interface SimplifiedPermissionMessage {\n  /** Application address */\n  application: Address;\n  /** Grant URL */\n  grant: string;\n  /** Nonce */\n  nonce: bigint;\n}\n\n/**\n * Grant file structure containing permission details.\n *\n * Grant files contain the complete specification of what an application is permitted\n * to do with user data, including operation parameters and file access rights.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const grantFile: GrantFile = {\n *   grantee: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',\n *   operation: 'llm_inference',\n *   parameters: {\n *     prompt: 'Analyze this data: {{data}}',\n *     model: 'gpt-4',\n *     maxTokens: 2000,\n *     temperature: 0.7\n *   },\n *   expires: 1736467579\n * };\n * ```\n */\nexport interface GrantFile {\n  /** EVM address of the application authorized to use this grant */\n  grantee: Address;\n  /** Operation the grantee is authorized to perform */\n  operation: string;\n  /** Operation-specific parameters */\n  parameters: Record<string, unknown>;\n  /** Optional Unix timestamp when grant expires (seconds since epoch per POSIX.1-2008) */\n  expires?: number;\n}\n\n/**\n * EIP-712 typed data structure for Permission\n *\n * @category Permissions\n */\nexport interface PermissionGrantTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    Permission: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"Permission\";\n  /** Message to sign */\n  message: PermissionInputMessage;\n}\n\n/**\n * Generic EIP-712 typed data structure\n *\n * @category Permissions\n */\nexport interface GenericTypedData extends RecordCompatible {\n  /** EIP-712 domain */\n  domain: PermissionGrantDomain;\n  /** EIP-712 types */\n  types: Record<string, Array<{ name: string; type: string }>>;\n  /** Primary type */\n  primaryType: string;\n  /** Message to sign */\n  message: Record<string, unknown>;\n}\n\n/**\n * Represents EIP-712 typed data for permission revocation.\n *\n * @remarks\n * Used when revoking previously granted permissions through gasless transactions.\n * The message contains a nonce and the permission ID to revoke.\n *\n * @category Permissions\n */\nexport interface RevokePermissionTypedData extends GenericTypedData {\n  /** EIP-712 type definitions for the RevokePermission structure */\n  types: {\n    RevokePermission: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** The primary type identifier for revocation operations */\n  primaryType: \"RevokePermission\";\n  /** The structured message containing revocation parameters */\n  message: RevokePermissionInput;\n}\n\n/**\n * Defines all valid primary types for EIP-712 typed data in the Vana SDK.\n *\n * @remarks\n * These literal types ensure compile-time safety when handling typed data operations.\n * Each corresponds to a specific blockchain operation type.\n *\n * @category Permissions\n */\nexport type TypedDataPrimaryType =\n  | \"Permission\"\n  | \"RevokePermission\"\n  | \"TrustServer\"\n  | \"UntrustServer\"\n  | \"AddServer\"\n  | \"RegisterGrantee\"\n  | \"ServerFilesAndPermission\";\n\n/**\n * Represents the union of all specific typed data interfaces.\n *\n * @remarks\n * Enables type-safe handling of any typed data structure in the SDK.\n * Used internally by relayer handlers and signature verification.\n *\n * @category Permissions\n */\nexport type SpecificTypedData =\n  | PermissionGrantTypedData\n  | RevokePermissionTypedData\n  | TrustServerTypedData\n  | UntrustServerTypedData\n  | AddAndTrustServerTypedData\n  | RegisterGranteeTypedData\n  | ServerFilesAndPermissionTypedData;\n\n/**\n * Permission operation types\n *\n * @category Permissions\n */\nexport type PermissionOperation =\n  | \"llm_inference\"\n  | \"data_analysis\"\n  | \"model_training\"\n  | \"data_sharing\"\n  | \"compute_task\"\n  | string;\n\n/**\n * Permission status\n *\n * @category Permissions\n */\nexport type PermissionStatus = \"active\" | \"revoked\" | \"expired\" | \"pending\";\n\n/**\n * Parameters for querying permissions\n *\n * @category Permissions\n */\nexport interface QueryPermissionsParams {\n  /** Filter by grantor address */\n  grantor?: Address;\n  /** Filter by grantee address */\n  grantee?: Address;\n  /** Filter by operation type */\n  operation?: PermissionOperation;\n  /** Filter by file IDs */\n  files?: number[];\n  /** Filter by status */\n  status?: PermissionStatus;\n  /** Starting block number */\n  fromBlock?: bigint;\n  /** Ending block number */\n  toBlock?: bigint;\n  /** Maximum number of results */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n}\n\n/**\n * Granted permission details\n *\n * @category Permissions\n */\nexport interface GrantedPermission {\n  /** Unique identifier for the permission */\n  id: bigint;\n  /** Array of file IDs that the permission applies to */\n  files: number[];\n  /** The type of operation being granted permission for */\n  operation: string;\n  /** Grant file reference (IPFS hash or URL) */\n  grant: string;\n  /** Address of the application granted permission */\n  grantee: Address;\n  /** Address of the user who granted permission */\n  grantor: Address;\n  /** Custom parameters for the operation */\n  parameters: Record<string, unknown>;\n  /** Whether the permission is still active */\n  active: boolean;\n  /** Data status for the permission */\n  dataStatus?: string;\n  /** Nonce used for the permission */\n  nonce?: number;\n  /** Timestamp when permission was granted */\n  grantedAt?: number;\n  /** Optional expiration timestamp */\n  expiresAt?: number;\n  /** Transaction hash of the grant transaction */\n  transactionHash?: string;\n  /** Block number when permission was granted */\n  blockNumber?: bigint;\n}\n\n/**\n * Permission query result\n *\n * @category Permissions\n */\nexport interface PermissionQueryResult {\n  /** Array of permissions matching the query */\n  permissions: GrantedPermission[];\n  /** Total number of permissions (for pagination) */\n  total: number;\n  /** Whether there are more results available */\n  hasMore: boolean;\n}\n\n/**\n * Permission analytics data\n *\n * @category Permissions\n */\nexport interface PermissionAnalytics {\n  /** Total number of permissions granted */\n  totalPermissions: number;\n  /** Number of active permissions */\n  activePermissions: number;\n  /** Number of revoked permissions */\n  revokedPermissions: number;\n  /** Number of expired permissions */\n  expiredPermissions: number;\n  /** Most common operation types */\n  topOperations: Array<{\n    operation: PermissionOperation;\n    count: number;\n  }>;\n  /** Most active applications */\n  topApplications: Array<{\n    application: Address;\n    count: number;\n  }>;\n}\n\n/**\n * Server information\n *\n * @category Permissions\n */\nexport interface Server {\n  /** Server ID (numeric) */\n  id: number;\n  /** Server owner address */\n  owner: Address;\n  /** Server URL */\n  url: string;\n  /** Server address */\n  serverAddress: Address;\n  /** Server public key */\n  publicKey: string;\n}\n\n/**\n * Contract ServerInfo structure returned from the contract\n *\n * @category Permissions\n */\nexport interface ServerInfo {\n  /** Server ID */\n  id: bigint;\n  /** Server owner address */\n  owner: Address;\n  /** Server address */\n  serverAddress: Address;\n  /** Server public key */\n  publicKey: string;\n  /** Server URL */\n  url: string;\n}\n\n/**\n * Parameters for adding and trusting a server\n *\n * @category Permissions\n */\nexport interface AddAndTrustServerParams {\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  publicKey: string;\n}\n\n/**\n * Parameters for trusting a server (legacy)\n *\n * @category Permissions\n * @deprecated Use AddAndTrustServerParams instead\n */\nexport interface TrustServerParams {\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * Parameters for untrusting a server\n *\n * @category Permissions\n */\nexport interface UntrustServerParams {\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * Input for adding and trusting a server with signature (gasless)\n *\n * @category Permissions\n */\nexport interface AddAndTrustServerInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  publicKey: string;\n}\n\n/**\n * Input for trusting a server with signature (gasless)\n *\n * @category Permissions\n * @deprecated Use AddAndTrustServerInput instead\n */\nexport interface TrustServerInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * Input for untrusting a server with signature (gasless)\n *\n * @category Permissions\n */\nexport interface UntrustServerInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * EIP-712 typed data for AddAndTrustServer\n *\n * @category Permissions\n */\nexport interface AddAndTrustServerTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    AddServer: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"AddServer\";\n  /** Message to sign */\n  message: AddAndTrustServerInput;\n}\n\n/**\n * EIP-712 typed data for TrustServer\n *\n * @category Permissions\n * @deprecated Use AddAndTrustServerTypedData instead\n */\nexport interface TrustServerTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    TrustServer: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"TrustServer\";\n  /** Message to sign */\n  message: TrustServerInput;\n}\n\n/**\n * EIP-712 typed data for UntrustServer\n *\n * @category Permissions\n */\nexport interface UntrustServerTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    UntrustServer: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"UntrustServer\";\n  /** Message to sign */\n  message: UntrustServerInput;\n}\n\n/**\n * Permission event data\n *\n * @category Permissions\n */\nexport interface PermissionEvent {\n  /** Event type */\n  type: \"granted\" | \"revoked\" | \"expired\";\n  /** Permission details */\n  permission: GrantedPermission;\n  /** Block number where event occurred */\n  blockNumber: bigint;\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Event timestamp */\n  timestamp: number;\n}\n\n/**\n * Enhanced trusted server information with trust status\n *\n * @category Permissions\n */\nexport interface TrustedServerInfo {\n  /** Server ID */\n  id: bigint;\n  /** Server owner address */\n  owner: Address;\n  /** Server address */\n  serverAddress: Address;\n  /** Server public key */\n  publicKey: string;\n  /** Server URL */\n  url: string;\n  /** Start block when trust relationship began */\n  startBlock: bigint;\n  /** End block when trust relationship ended (0 if still active) */\n  endBlock: bigint;\n}\n\n/**\n * Paginated result for trusted server queries\n *\n * @category Permissions\n */\nexport interface PaginatedTrustedServers {\n  /** Array of server IDs (numeric) */\n  servers: number[];\n  /** Total number of trusted servers */\n  total: number;\n  /** Offset used for this query */\n  offset: number;\n  /** Limit used for this query */\n  limit: number;\n  /** Whether there are more servers beyond this page */\n  hasMore: boolean;\n}\n\n/**\n * Options for querying trusted servers\n *\n * @category Permissions\n */\nexport interface TrustedServerQueryOptions {\n  /** User address to query (defaults to current user) */\n  userAddress?: Address;\n  /** Maximum number of servers to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Whether to include full server info or just IDs */\n  includeServerInfo?: boolean;\n}\n\n/**\n * Result of batch server info requests\n *\n * @category Permissions\n */\nexport interface BatchServerInfoResult {\n  /** Successfully retrieved server info */\n  servers: Map<number, Server>;\n  /** Server IDs that failed to retrieve */\n  failed: number[];\n}\n\n/**\n * Server trust status information\n *\n * @category Permissions\n */\nexport interface ServerTrustStatus {\n  /** Server ID being checked (numeric) */\n  serverId: number;\n  /** Whether the server is trusted by the user */\n  isTrusted: boolean;\n  /** Index in user's trusted server list (if trusted) */\n  trustIndex?: number;\n}\n\n/**\n * Grantee information\n *\n * @category Permissions\n */\nexport interface Grantee {\n  /** Grantee ID (numeric) */\n  id: number;\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  address: Address;\n  /** Grantee public key */\n  publicKey: string;\n  /** Permission IDs associated with this grantee */\n  permissionIds: number[];\n}\n\n/**\n * Contract GranteeInfo structure returned from the contract\n *\n * @category Permissions\n */\nexport interface GranteeInfo {\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  granteeAddress: Address;\n  /** Grantee public key */\n  publicKey: string;\n  /** Permission IDs associated with this grantee */\n  permissionIds: readonly bigint[];\n}\n\n/**\n * Parameters for registering a grantee\n *\n * @category Permissions\n */\nexport interface RegisterGranteeParams {\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  granteeAddress: Address;\n  /** Grantee public key */\n  publicKey: string;\n}\n\n/**\n * Input for registering a grantee with signature (gasless)\n *\n * @category Permissions\n */\nexport interface RegisterGranteeInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  granteeAddress: Address;\n  /** Grantee public key */\n  publicKey: string;\n}\n\n/**\n * EIP-712 typed data for RegisterGrantee\n *\n * @category Permissions\n */\nexport interface RegisterGranteeTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    RegisterGrantee: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"RegisterGrantee\";\n  /** Message to sign */\n  message: RegisterGranteeInput;\n}\n\n/**\n * Options for querying grantees\n *\n * @category Permissions\n */\nexport interface GranteeQueryOptions {\n  /** Maximum number of grantees to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Whether to include permission info or just basic info */\n  includePermissions?: boolean;\n}\n\n/**\n * Paginated result for grantee queries\n *\n * @category Permissions\n */\nexport interface PaginatedGrantees {\n  /** Array of grantees */\n  grantees: Grantee[];\n  /** Total number of grantees */\n  total: number;\n  /** Offset used for this query */\n  offset: number;\n  /** Limit used for this query */\n  limit: number;\n  /** Whether there are more grantees beyond this page */\n  hasMore: boolean;\n}\n\n/**\n * Contract Permission structure as used in ServerFilesAndPermissionInput\n *\n * @category Permissions\n */\nexport interface Permission {\n  /** Account address for the permission */\n  account: Address;\n  /** Permission key */\n  key: string;\n}\n\n/**\n * Contract ServerFilesAndPermissionInput structure\n *\n * @category Permissions\n */\nexport interface ServerFilesAndPermissionInput {\n  /** User nonce */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** File URLs */\n  fileUrls: string[];\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  serverPublicKey: string;\n  /** File permissions array - permissions for each file */\n  filePermissions: Permission[][];\n}\n\n/**\n * Parameters for server files and permissions operations\n *\n * @category Permissions\n */\nexport interface ServerFilesAndPermissionParams {\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL or grant data */\n  grant: string;\n  /** File URLs */\n  fileUrls: string[];\n  /** Schema IDs for each file - use 0 for files without schema validation */\n  schemaIds: number[];\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  serverPublicKey: string;\n  /** File permissions array - permissions for each file */\n  filePermissions: Permission[][];\n}\n\n/**\n * EIP-712 typed data for server files and permissions messages\n *\n * @category Permissions\n */\nexport interface ServerFilesAndPermissionTypedData extends GenericTypedData {\n  /** Message data structure */\n  message: {\n    /** User nonce */\n    nonce: bigint;\n    /** Grantee ID */\n    granteeId: bigint;\n    /** Grant URL */\n    grant: string;\n    /** File URLs */\n    fileUrls: string[];\n    /** Schema IDs for each file - use 0 for files without schema validation */\n    schemaIds: bigint[];\n    /** Server address */\n    serverAddress: Address;\n    /** Server URL */\n    serverUrl: string;\n    /** Server public key */\n    serverPublicKey: string;\n    /** File permissions array - permissions for each file */\n    filePermissions: Permission[][];\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/permissions.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Base interface for types that need to be compatible with Record<string, unknown>\n *\n * @category Permissions\n */\nexport interface RecordCompatible {\n  [key: string]: unknown;\n}\n\n/**\n * Contains on-chain permission data for efficient retrieval.\n *\n * @remarks\n * Provides fast access to permission metadata from subgraph without\n * IPFS calls. For detailed parameters, resolve `grantUrl` separately.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const grants = await vana.permissions.getUserPermissionGrantsOnChain();\n *\n * // Resolve details when needed\n * const details = await retrieveGrantFile(grants[0].grantUrl);\n * console.log(`Operation: ${details.operation}`);\n * ```\n */\nexport interface OnChainPermissionGrant {\n  /** Unique identifier for the permission */\n  id: bigint;\n  /** The grant URL containing detailed permission parameters (IPFS link) */\n  grantUrl: string;\n  /** Cryptographic signature that authorized this permission */\n  grantSignature: string;\n  /** Nonce used when granting the permission */\n  nonce: bigint;\n  /** Block number when permission started */\n  startBlock: bigint;\n  /** Block number when permission was granted */\n  addedAtBlock: bigint;\n  /** Timestamp when permission was added */\n  addedAtTimestamp: bigint;\n  /** Transaction hash of the grant transaction */\n  transactionHash: string;\n  /** Address that granted the permission */\n  grantor: Address;\n  /** Grantee information */\n  grantee: {\n    /** Grantee ID */\n    id: string;\n    /** Grantee address */\n    address: string;\n  };\n  /** Whether the permission is still active (not revoked) */\n  active: boolean;\n}\n\n/**\n * Options for retrieving user permissions\n *\n * @category Permissions\n */\nexport interface GetUserPermissionsOptions {\n  /** Maximum number of permissions to retrieve */\n  limit?: number;\n  /** Custom subgraph URL to use for querying */\n  subgraphUrl?: string;\n}\n\n/**\n * Defines parameters for granting file access permissions.\n *\n * @remarks\n * Specifies application, operation, files, and parameters for\n * permission grants via `vana.permissions.grant()`.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const params: GrantPermissionParams = {\n *   grantee: '0x1234...',\n *   operation: 'llm_inference',\n *   files: [1, 2, 3],\n *   parameters: { model: 'gpt-4', maxTokens: 1000 }\n * };\n * const result = await vana.permissions.grant(params);\n * ```\n */\nexport interface GrantPermissionParams {\n  /** The on-chain identity of the application */\n  grantee: Address;\n  /** The class of computation, e.g., \"llm_inference\" */\n  operation: string;\n  /**\n   * Array of file IDs to grant permission for.\n   * Obtain file IDs from `vana.data.getUserFiles()` or from upload results via `vana.data.upload().fileId`.\n   */\n  files: number[];\n  /** The full, off-chain parameters (e.g., LLM prompt) */\n  parameters: Record<string, unknown>;\n  /** Optional pre-stored grant URL to avoid duplicate IPFS storage */\n  grantUrl?: string;\n  /** Optional nonce for the permission */\n  nonce?: bigint;\n  /** Optional expiration time for the permission */\n  expiresAt?: number;\n}\n\n/**\n * Parameters for revoking a previously granted data access permission.\n *\n * Used with `PermissionsController.revoke()` to remove an application's access\n * to user data. Once revoked, the application can no longer use the permission\n * to access the specified files.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const revokeParams: RevokePermissionParams = {\n *   permissionId: 123n // Permission ID to revoke\n * };\n *\n * await vana.permissions.revoke(revokeParams);\n * ```\n */\nexport interface RevokePermissionParams {\n  /** The permission ID to revoke */\n  permissionId: bigint;\n}\n\n/**\n * Parameters for checking if a specific permission exists and is valid.\n *\n * Used to verify whether an application has active permission to access\n * specific user files for a particular operation before attempting to use the data.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const checkParams: CheckPermissionParams = {\n *   application: '0x1234...', // App address\n *   operation: 'llm_inference',\n *   files: [1, 2, 3], // File IDs to check\n *   parameters: { model: 'gpt-4' }, // Operation parameters\n *   user: '0xabcd...' // Optional specific user\n * };\n *\n * const hasPermission = await vana.permissions.check(checkParams);\n * ```\n */\nexport interface CheckPermissionParams {\n  /** The application address */\n  application: Address;\n  /** The operation type */\n  operation: string;\n  /** The file IDs */\n  files: number[];\n  /** The grant parameters */\n  parameters: Record<string, unknown>;\n  /** The user address */\n  user?: Address;\n}\n\n/**\n * Permission check result\n *\n * @category Permissions\n */\nexport interface PermissionCheckResult {\n  /** Whether the permission exists and is valid */\n  exists: boolean;\n  /** The permission details if it exists */\n  permission?: GrantedPermission;\n  /** Reason why permission is invalid (if applicable) */\n  reason?: string;\n}\n\n/**\n * EIP-712 domain definition for PermissionGrant signatures\n *\n * @category Permissions\n */\nexport interface PermissionGrantDomain {\n  /** Domain name */\n  name: string;\n  /** Domain version */\n  version: string;\n  /** Chain ID */\n  chainId: number;\n  /** Verifying contract address */\n  verifyingContract: Address;\n}\n\n/**\n * EIP-712 Permission message structure (current contract format)\n *\n * @category Permissions\n */\nexport interface PermissionGrantMessage {\n  /** Application address */\n  application: Address;\n  /** File IDs */\n  files: number[];\n  /** Operation type */\n  operation: string;\n  /** Grant URL */\n  grant: string;\n  /** Parameters as JSON string */\n  parameters: string;\n  /** Nonce */\n  nonce: bigint;\n}\n\n/**\n * EIP-712 PermissionInput message structure (new simplified format)\n *\n * @category Permissions\n */\nexport interface PermissionInputMessage extends RecordCompatible {\n  /** Nonce */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** File IDs */\n  fileIds: bigint[];\n}\n\n/**\n * Contract PermissionInput structure\n *\n * @category Permissions\n */\nexport interface PermissionInput {\n  /** Nonce */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** File IDs to grant permission for */\n  fileIds: bigint[];\n}\n\n/**\n * Contract RevokePermissionInput structure\n *\n * @category Permissions\n */\nexport interface RevokePermissionInput extends RecordCompatible {\n  /** Nonce */\n  nonce: bigint;\n  /** Permission ID to revoke */\n  permissionId: bigint;\n}\n\n/**\n * Contract Permission Info structure returned from the contract\n *\n * @category Permissions\n */\nexport interface PermissionInfo {\n  /** Permission ID */\n  id: bigint;\n  /** Address that granted the permission */\n  grantor: Address;\n  /** Nonce used when creating */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** Signature bytes (removed in newer contract versions) */\n  signature?: `0x${string}`;\n  /** Start block */\n  startBlock: bigint;\n  /** End block */\n  endBlock: bigint;\n  /** File IDs associated with this permission */\n  fileIds: readonly bigint[];\n}\n\n/**\n * EIP-712 Permission message structure (simplified future format)\n *\n * @category Permissions\n */\nexport interface SimplifiedPermissionMessage {\n  /** Application address */\n  application: Address;\n  /** Grant URL */\n  grant: string;\n  /** Nonce */\n  nonce: bigint;\n}\n\n/**\n * Grant file structure containing permission details.\n *\n * Grant files contain the complete specification of what an application is permitted\n * to do with user data, including operation parameters and file access rights.\n *\n * @category Permissions\n * @example\n * ```typescript\n * const grantFile: GrantFile = {\n *   grantee: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',\n *   operation: 'llm_inference',\n *   parameters: {\n *     prompt: 'Analyze this data: {{data}}',\n *     model: 'gpt-4',\n *     maxTokens: 2000,\n *     temperature: 0.7\n *   },\n *   expires: 1736467579\n * };\n * ```\n */\nexport interface GrantFile {\n  /** EVM address of the application authorized to use this grant */\n  grantee: Address;\n  /** Operation the grantee is authorized to perform */\n  operation: string;\n  /** Operation-specific parameters */\n  parameters: Record<string, unknown>;\n  /** Optional Unix timestamp when grant expires (seconds since epoch per POSIX.1-2008) */\n  expires?: number;\n}\n\n/**\n * EIP-712 typed data structure for Permission\n *\n * @category Permissions\n */\nexport interface PermissionGrantTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    Permission: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"Permission\";\n  /** Message to sign */\n  message: PermissionInputMessage;\n}\n\n/**\n * Generic EIP-712 typed data structure\n *\n * @category Permissions\n */\nexport interface GenericTypedData extends RecordCompatible {\n  /** EIP-712 domain */\n  domain: PermissionGrantDomain;\n  /** EIP-712 types */\n  types: Record<string, Array<{ name: string; type: string }>>;\n  /** Primary type */\n  primaryType: string;\n  /** Message to sign */\n  message: Record<string, unknown>;\n}\n\n/**\n * Represents EIP-712 typed data for permission revocation.\n *\n * @remarks\n * Used when revoking previously granted permissions through gasless transactions.\n * The message contains a nonce and the permission ID to revoke.\n *\n * @category Permissions\n */\nexport interface RevokePermissionTypedData extends GenericTypedData {\n  /** EIP-712 type definitions for the RevokePermission structure */\n  types: {\n    RevokePermission: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** The primary type identifier for revocation operations */\n  primaryType: \"RevokePermission\";\n  /** The structured message containing revocation parameters */\n  message: RevokePermissionInput;\n}\n\n/**\n * Defines all valid primary types for EIP-712 typed data in the Vana SDK.\n *\n * @remarks\n * These literal types ensure compile-time safety when handling typed data operations.\n * Each corresponds to a specific blockchain operation type.\n *\n * @category Permissions\n */\nexport type TypedDataPrimaryType =\n  | \"Permission\"\n  | \"RevokePermission\"\n  | \"TrustServer\"\n  | \"UntrustServer\"\n  | \"AddServer\"\n  | \"RegisterGrantee\"\n  | \"ServerFilesAndPermission\";\n\n/**\n * Represents the union of all specific typed data interfaces.\n *\n * @remarks\n * Enables type-safe handling of any typed data structure in the SDK.\n * Used internally by relayer handlers and signature verification.\n *\n * @category Permissions\n */\nexport type SpecificTypedData =\n  | PermissionGrantTypedData\n  | RevokePermissionTypedData\n  | TrustServerTypedData\n  | UntrustServerTypedData\n  | AddAndTrustServerTypedData\n  | RegisterGranteeTypedData\n  | ServerFilesAndPermissionTypedData;\n\n/**\n * Permission operation types\n *\n * @category Permissions\n */\nexport type PermissionOperation =\n  | \"llm_inference\"\n  | \"data_analysis\"\n  | \"model_training\"\n  | \"data_sharing\"\n  | \"compute_task\"\n  | string;\n\n/**\n * Permission status\n *\n * @category Permissions\n */\nexport type PermissionStatus = \"active\" | \"revoked\" | \"expired\" | \"pending\";\n\n/**\n * Parameters for querying permissions\n *\n * @category Permissions\n */\nexport interface QueryPermissionsParams {\n  /** Filter by grantor address */\n  grantor?: Address;\n  /** Filter by grantee address */\n  grantee?: Address;\n  /** Filter by operation type */\n  operation?: PermissionOperation;\n  /** Filter by file IDs */\n  files?: number[];\n  /** Filter by status */\n  status?: PermissionStatus;\n  /** Starting block number */\n  fromBlock?: bigint;\n  /** Ending block number */\n  toBlock?: bigint;\n  /** Maximum number of results */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n}\n\n/**\n * Granted permission details\n *\n * @category Permissions\n */\nexport interface GrantedPermission {\n  /** Unique identifier for the permission */\n  id: bigint;\n  /** Array of file IDs that the permission applies to */\n  files: number[];\n  /** The type of operation being granted permission for */\n  operation: string;\n  /** Grant file reference (IPFS hash or URL) */\n  grant: string;\n  /** Address of the application granted permission */\n  grantee: Address;\n  /** Address of the user who granted permission */\n  grantor: Address;\n  /** Custom parameters for the operation */\n  parameters: Record<string, unknown>;\n  /** Whether the permission is still active */\n  active: boolean;\n  /** Data status for the permission */\n  dataStatus?: string;\n  /** Nonce used for the permission */\n  nonce?: number;\n  /** Timestamp when permission was granted */\n  grantedAt?: number;\n  /** Optional expiration timestamp */\n  expiresAt?: number;\n  /** Transaction hash of the grant transaction */\n  transactionHash?: string;\n  /** Block number when permission was granted */\n  blockNumber?: bigint;\n}\n\n/**\n * Permission query result\n *\n * @category Permissions\n */\nexport interface PermissionQueryResult {\n  /** Array of permissions matching the query */\n  permissions: GrantedPermission[];\n  /** Total number of permissions (for pagination) */\n  total: number;\n  /** Whether there are more results available */\n  hasMore: boolean;\n}\n\n/**\n * Permission analytics data\n *\n * @category Permissions\n */\nexport interface PermissionAnalytics {\n  /** Total number of permissions granted */\n  totalPermissions: number;\n  /** Number of active permissions */\n  activePermissions: number;\n  /** Number of revoked permissions */\n  revokedPermissions: number;\n  /** Number of expired permissions */\n  expiredPermissions: number;\n  /** Most common operation types */\n  topOperations: Array<{\n    operation: PermissionOperation;\n    count: number;\n  }>;\n  /** Most active applications */\n  topApplications: Array<{\n    application: Address;\n    count: number;\n  }>;\n}\n\n/**\n * Server information\n *\n * @category Permissions\n */\nexport interface Server {\n  /** Server ID (numeric) */\n  id: number;\n  /** Server owner address */\n  owner: Address;\n  /** Server URL */\n  url: string;\n  /** Server address */\n  serverAddress: Address;\n  /** Server public key */\n  publicKey: string;\n}\n\n/**\n * Contract ServerInfo structure returned from the contract\n *\n * @category Permissions\n */\nexport interface ServerInfo {\n  /** Server ID */\n  id: bigint;\n  /** Server owner address */\n  owner: Address;\n  /** Server address */\n  serverAddress: Address;\n  /** Server public key */\n  publicKey: string;\n  /** Server URL */\n  url: string;\n}\n\n/**\n * Parameters for adding and trusting a server\n *\n * @category Permissions\n */\nexport interface AddAndTrustServerParams {\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  publicKey: string;\n}\n\n/**\n * Parameters for trusting a server (legacy)\n *\n * @category Permissions\n * @deprecated Use AddAndTrustServerParams instead\n */\nexport interface TrustServerParams {\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * Parameters for untrusting a server\n *\n * @category Permissions\n */\nexport interface UntrustServerParams {\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * Input for adding and trusting a server with signature (gasless)\n *\n * @category Permissions\n */\nexport interface AddAndTrustServerInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  publicKey: string;\n}\n\n/**\n * Input for trusting a server with signature (gasless)\n *\n * @category Permissions\n * @deprecated Use AddAndTrustServerInput instead\n */\nexport interface TrustServerInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * Input for untrusting a server with signature (gasless)\n *\n * @category Permissions\n */\nexport interface UntrustServerInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Server ID (numeric) */\n  serverId: number;\n}\n\n/**\n * EIP-712 typed data for AddAndTrustServer\n *\n * @category Permissions\n */\nexport interface AddAndTrustServerTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    AddServer: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"AddServer\";\n  /** Message to sign */\n  message: AddAndTrustServerInput;\n}\n\n/**\n * EIP-712 typed data for TrustServer\n *\n * @category Permissions\n * @deprecated Use AddAndTrustServerTypedData instead\n */\nexport interface TrustServerTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    TrustServer: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"TrustServer\";\n  /** Message to sign */\n  message: TrustServerInput;\n}\n\n/**\n * EIP-712 typed data for UntrustServer\n *\n * @category Permissions\n */\nexport interface UntrustServerTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    UntrustServer: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"UntrustServer\";\n  /** Message to sign */\n  message: UntrustServerInput;\n}\n\n/**\n * Permission event data\n *\n * @category Permissions\n */\nexport interface PermissionEvent {\n  /** Event type */\n  type: \"granted\" | \"revoked\" | \"expired\";\n  /** Permission details */\n  permission: GrantedPermission;\n  /** Block number where event occurred */\n  blockNumber: bigint;\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Event timestamp */\n  timestamp: number;\n}\n\n/**\n * Enhanced trusted server information with trust status\n *\n * @category Permissions\n */\nexport interface TrustedServerInfo {\n  /** Server ID */\n  id: bigint;\n  /** Server owner address */\n  owner: Address;\n  /** Server address */\n  serverAddress: Address;\n  /** Server public key */\n  publicKey: string;\n  /** Server URL */\n  url: string;\n  /** Start block when trust relationship began */\n  startBlock: bigint;\n  /** End block when trust relationship ended (0 if still active) */\n  endBlock: bigint;\n}\n\n/**\n * Paginated result for trusted server queries\n *\n * @category Permissions\n */\nexport interface PaginatedTrustedServers {\n  /** Array of server IDs (numeric) */\n  servers: number[];\n  /** Total number of trusted servers */\n  total: number;\n  /** Offset used for this query */\n  offset: number;\n  /** Limit used for this query */\n  limit: number;\n  /** Whether there are more servers beyond this page */\n  hasMore: boolean;\n}\n\n/**\n * Options for querying trusted servers\n *\n * @category Permissions\n */\nexport interface TrustedServerQueryOptions {\n  /** User address to query (defaults to current user) */\n  userAddress?: Address;\n  /** Maximum number of servers to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Whether to include full server info or just IDs */\n  includeServerInfo?: boolean;\n}\n\n/**\n * Result of batch server info requests\n *\n * @category Permissions\n */\nexport interface BatchServerInfoResult {\n  /** Successfully retrieved server info */\n  servers: Map<number, Server>;\n  /** Server IDs that failed to retrieve */\n  failed: number[];\n}\n\n/**\n * Server trust status information\n *\n * @category Permissions\n */\nexport interface ServerTrustStatus {\n  /** Server ID being checked (numeric) */\n  serverId: number;\n  /** Whether the server is trusted by the user */\n  isTrusted: boolean;\n  /** Index in user's trusted server list (if trusted) */\n  trustIndex?: number;\n}\n\n/**\n * Grantee information\n *\n * @category Permissions\n */\nexport interface Grantee {\n  /** Grantee ID (numeric) */\n  id: number;\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  address: Address;\n  /** Grantee public key */\n  publicKey: string;\n  /** Permission IDs associated with this grantee */\n  permissionIds: number[];\n}\n\n/**\n * Contract GranteeInfo structure returned from the contract\n *\n * @category Permissions\n */\nexport interface GranteeInfo {\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  granteeAddress: Address;\n  /** Grantee public key */\n  publicKey: string;\n  /** Permission IDs associated with this grantee */\n  permissionIds: readonly bigint[];\n}\n\n/**\n * Parameters for registering a grantee\n *\n * @category Permissions\n */\nexport interface RegisterGranteeParams {\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  granteeAddress: Address;\n  /** Grantee public key */\n  publicKey: string;\n}\n\n/**\n * Input for registering a grantee with signature (gasless)\n *\n * @category Permissions\n */\nexport interface RegisterGranteeInput extends RecordCompatible {\n  /** User nonce */\n  nonce: bigint;\n  /** Grantee owner address */\n  owner: Address;\n  /** Grantee address */\n  granteeAddress: Address;\n  /** Grantee public key */\n  publicKey: string;\n}\n\n/**\n * EIP-712 typed data for RegisterGrantee\n *\n * @category Permissions\n */\nexport interface RegisterGranteeTypedData extends GenericTypedData {\n  /** EIP-712 types */\n  types: {\n    RegisterGrantee: Array<{\n      name: string;\n      type: string;\n    }>;\n  };\n  /** Primary type */\n  primaryType: \"RegisterGrantee\";\n  /** Message to sign */\n  message: RegisterGranteeInput;\n}\n\n/**\n * Options for querying grantees\n *\n * @category Permissions\n */\nexport interface GranteeQueryOptions {\n  /** Maximum number of grantees to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Whether to include permission info or just basic info */\n  includePermissions?: boolean;\n}\n\n/**\n * Paginated result for grantee queries\n *\n * @category Permissions\n */\nexport interface PaginatedGrantees {\n  /** Array of grantees */\n  grantees: Grantee[];\n  /** Total number of grantees */\n  total: number;\n  /** Offset used for this query */\n  offset: number;\n  /** Limit used for this query */\n  limit: number;\n  /** Whether there are more grantees beyond this page */\n  hasMore: boolean;\n}\n\n/**\n * Contract Permission structure as used in ServerFilesAndPermissionInput\n *\n * @category Permissions\n */\nexport interface Permission {\n  /** Account address for the permission */\n  account: Address;\n  /** Permission key */\n  key: string;\n}\n\n/**\n * Contract ServerFilesAndPermissionInput structure\n *\n * @category Permissions\n */\nexport interface ServerFilesAndPermissionInput {\n  /** User nonce */\n  nonce: bigint;\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL */\n  grant: string;\n  /** File URLs */\n  fileUrls: string[];\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  serverPublicKey: string;\n  /** File permissions array - permissions for each file */\n  filePermissions: Permission[][];\n}\n\n/**\n * Parameters for server files and permissions operations\n *\n * @category Permissions\n */\nexport interface ServerFilesAndPermissionParams {\n  /** Grantee ID */\n  granteeId: bigint;\n  /** Grant URL or grant data */\n  grant: string;\n  /** File URLs */\n  fileUrls: string[];\n  /** Schema IDs for each file - use 0 for files without schema validation */\n  schemaIds: number[];\n  /** Server address */\n  serverAddress: Address;\n  /** Server URL */\n  serverUrl: string;\n  /** Server public key */\n  serverPublicKey: string;\n  /** File permissions array - permissions for each file */\n  filePermissions: Permission[][];\n}\n\n/**\n * EIP-712 typed data for server files and permissions messages\n *\n * @category Permissions\n */\nexport interface ServerFilesAndPermissionTypedData extends GenericTypedData {\n  /** Message data structure */\n  message: {\n    /** User nonce */\n    nonce: bigint;\n    /** Grantee ID */\n    granteeId: bigint;\n    /** Grant URL */\n    grant: string;\n    /** File URLs */\n    fileUrls: string[];\n    /** Schema IDs for each file - use 0 for files without schema validation */\n    schemaIds: bigint[];\n    /** Server address */\n    serverAddress: Address;\n    /** Server URL */\n    serverUrl: string;\n    /** Server public key */\n    serverPublicKey: string;\n    /** File permissions array - permissions for each file */\n    filePermissions: Permission[][];\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/permissions.d.ts

@@ -8,22 +8,20 @@ export interface RecordCompatible {
     [key: string]: unknown;
 }
 /**
- * Represents on-chain permission grant data without expensive off-chain resolution.
+ * Contains on-chain permission data for efficient retrieval.
  *
- * This interface contains only the fast, on-chain data that can be retrieved
- * efficiently from the subgraph without making individual IPFS or contract calls.
- * Use this for fast permission listing in UIs, then call `retrieveGrantFile()`
- * on specific grants when detailed data is needed.
+ * @remarks
+ * Provides fast access to permission metadata from subgraph without
+ * IPFS calls. For detailed parameters, resolve `grantUrl` separately.
  *
  * @category Permissions
  * @example
  * ```typescript
- * // Fast: Get all on-chain permission data
  * const grants = await vana.permissions.getUserPermissionGrantsOnChain();
  *
- * // Lazy: Resolve detailed data for specific permission when needed
- * const grantFile = await retrieveGrantFile(grants[0].grantUrl);
- * console.log('Operation:', grantFile.operation);
+ * // Resolve details when needed
+ * const details = await retrieveGrantFile(grants[0].grantUrl);
+ * console.log(`Operation: ${details.operation}`);
  * ```
  */
 export interface OnChainPermissionGrant {
@@ -67,25 +65,22 @@ export interface GetUserPermissionsOptions {
     subgraphUrl?: string;
 }
 /**
- * Parameters for granting data access permission to an application.
+ * Defines parameters for granting file access permissions.
  *
- * This interface defines the required and optional parameters when granting
- * an application permission to access specific files for a particular operation.
- * Used with `vana.permissions.grant()`.
+ * @remarks
+ * Specifies application, operation, files, and parameters for
+ * permission grants via `vana.permissions.grant()`.
  *
  * @category Permissions
  * @example
  * ```typescript
  * const params: GrantPermissionParams = {
- *   grantee: '0x1234...', // Application address
+ *   grantee: '0x1234...',
  *   operation: 'llm_inference',
- *   files: [1, 2, 3], // File IDs to grant access to
- *   parameters: {
- *     model: 'gpt-4',
- *     maxTokens: 1000,
- *     prompt: 'Analyze my data'
- *   }
+ *   files: [1, 2, 3],
+ *   parameters: { model: 'gpt-4', maxTokens: 1000 }
  * };
+ * const result = await vana.permissions.grant(params);
  * ```
  */
 export interface GrantPermissionParams {

package/dist/types/personal.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/personal.ts"],"sourcesContent":["/**\n * Parameters for the `vana.personal.postRequest` method.\n */\nexport interface PostRequestParams {\n  /** The permission ID */\n  permissionId: number;\n}\n\n/**\n * Parameters for the `vana.server.createOperation` method.\n */\nexport interface CreateOperationParams {\n  /** The permission ID */\n  permissionId: number;\n}\n\n/**\n * Parameters for personal server operations.\n */\nexport interface InitPersonalServerParams {\n  /** The user's wallet address */\n  userAddress: string;\n}\n\n/**\n * Extended personal server identity information including connection details.\n * This combines the base PersonalServerModel with additional metadata\n * needed for client connections.\n */\nexport interface PersonalServerIdentity {\n  /** Resource type identifier */\n  kind: string;\n  /** The server's Ethereum address */\n  address: string;\n  /** The server's public key for encryption */\n  publicKey: string;\n  /** The base URL for connecting to this server */\n  baseUrl: string;\n  /** Human-readable name for this server */\n  name: string;\n}\n\n// Server response types are now auto-generated from OpenAPI spec in server.ts\n// Import types from ../types/server-exports for easy usage\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/personal.ts"],"sourcesContent":["/**\n * Defines parameters for posting data requests to personal servers.\n *\n * @remarks\n * Used to initiate data access requests that require user permission.\n * The permission ID references a previously granted permission that\n * authorizes the requester to access specific user data.\n *\n * @example\n * ```typescript\n * const params: PostRequestParams = {\n *   permissionId: 123\n * };\n *\n * const response = await vana.personal.postRequest(params);\n * console.log('Request posted:', response.requestId);\n * ```\n *\n * @category Personal Server\n */\nexport interface PostRequestParams {\n  /**\n   * References a granted permission authorizing data access.\n   * Obtain via permission granting flow or query existing permissions.\n   * @throws {PermissionNotFoundError} If permission ID is invalid.\n   */\n  permissionId: number;\n}\n\n/**\n * Defines parameters for creating server-side operations.\n *\n * @remarks\n * Initiates asynchronous operations on the personal server that\n * process user data according to granted permissions. Operations\n * run in the background and can be monitored via their operation ID.\n *\n * @example\n * ```typescript\n * const params: CreateOperationParams = {\n *   permissionId: 456\n * };\n *\n * const operation = await vana.server.createOperation(params);\n * // Monitor operation status\n * const status = await vana.server.getOperationStatus(operation.id);\n * ```\n *\n * @category Personal Server\n */\nexport interface CreateOperationParams {\n  /**\n   * References the permission scope for this operation.\n   * Determines what data and actions are allowed.\n   * @throws {InsufficientPermissionsError} If permission scope is inadequate.\n   */\n  permissionId: number;\n}\n\n/**\n * Defines parameters for initializing personal server connections.\n *\n * @remarks\n * Establishes secure communication channels with a user's personal\n * data server. The server manages encrypted user data and enforces\n * permission-based access control. Initialization includes key exchange\n * and session establishment.\n *\n * @example\n * ```typescript\n * const params: InitPersonalServerParams = {\n *   userAddress: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'\n * };\n *\n * const server = await vana.personal.initServer(params);\n * console.log('Connected to server:', server.baseUrl);\n * ```\n *\n * @category Personal Server\n */\nexport interface InitPersonalServerParams {\n  /**\n   * Identifies the user whose personal server to connect to.\n   * Must be a valid Ethereum address in hex format.\n   * @example '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'\n   */\n  userAddress: string;\n}\n\n/**\n * Represents comprehensive personal server identity and connection information.\n *\n * @remarks\n * Combines core server identity with connection metadata required for\n * establishing secure communication. Personal servers are user-controlled\n * nodes that store and serve encrypted personal data according to\n * user-defined permissions. This interface provides all necessary\n * information to connect to and interact with a personal server.\n *\n * @example\n * ```typescript\n * const identity: PersonalServerIdentity = {\n *   kind: 'PersonalServer',\n *   address: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',\n *   publicKey: '0x04...', // 65-byte uncompressed public key\n *   baseUrl: 'https://ps.user.vana.com',\n *   name: 'User Personal Server #1'\n * };\n *\n * // Use identity to establish encrypted connection\n * const encrypted = await crypto.encrypt(data, identity.publicKey);\n * const response = await fetch(`${identity.baseUrl}/api/data`, {\n *   method: 'POST',\n *   body: encrypted\n * });\n * ```\n *\n * @category Personal Server\n */\nexport interface PersonalServerIdentity {\n  /**\n   * Identifies the resource type for API disambiguation.\n   * Always 'PersonalServer' for personal server instances.\n   */\n  kind: string;\n\n  /**\n   * Uniquely identifies the server on the blockchain.\n   * Used for permission verification and identity proofs.\n   * @example '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'\n   */\n  address: string;\n\n  /**\n   * Enables end-to-end encryption for data transmission.\n   * Must be in uncompressed format (65 bytes with 0x04 prefix).\n   * @example '0x04...' (130 hex characters)\n   */\n  publicKey: string;\n\n  /**\n   * Provides the HTTPS endpoint for server API requests.\n   * Should not include trailing slashes or API paths.\n   * @example 'https://ps.user.vana.com'\n   */\n  baseUrl: string;\n\n  /**\n   * Displays a user-friendly identifier for the server.\n   * Used in UI components and logging for clarity.\n   * @example 'Primary Data Server'\n   */\n  name: string;\n}\n\n/**\n * @remarks\n * Additional server response types are auto-generated from the OpenAPI\n * specification and available in the server-exports module. Import those\n * types directly when working with server API responses.\n *\n * @see {@link ../types/server-exports | Server Export Types}\n */\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/personal.d.ts

@@ -1,38 +1,155 @@
 /**
- * Parameters for the `vana.personal.postRequest` method.
+ * Defines parameters for posting data requests to personal servers.
+ *
+ * @remarks
+ * Used to initiate data access requests that require user permission.
+ * The permission ID references a previously granted permission that
+ * authorizes the requester to access specific user data.
+ *
+ * @example
+ * ```typescript
+ * const params: PostRequestParams = {
+ *   permissionId: 123
+ * };
+ *
+ * const response = await vana.personal.postRequest(params);
+ * console.log('Request posted:', response.requestId);
+ * ```
+ *
+ * @category Personal Server
  */
 export interface PostRequestParams {
-    /** The permission ID */
+    /**
+     * References a granted permission authorizing data access.
+     * Obtain via permission granting flow or query existing permissions.
+     * @throws {PermissionNotFoundError} If permission ID is invalid.
+     */
     permissionId: number;
 }
 /**
- * Parameters for the `vana.server.createOperation` method.
+ * Defines parameters for creating server-side operations.
+ *
+ * @remarks
+ * Initiates asynchronous operations on the personal server that
+ * process user data according to granted permissions. Operations
+ * run in the background and can be monitored via their operation ID.
+ *
+ * @example
+ * ```typescript
+ * const params: CreateOperationParams = {
+ *   permissionId: 456
+ * };
+ *
+ * const operation = await vana.server.createOperation(params);
+ * // Monitor operation status
+ * const status = await vana.server.getOperationStatus(operation.id);
+ * ```
+ *
+ * @category Personal Server
  */
 export interface CreateOperationParams {
-    /** The permission ID */
+    /**
+     * References the permission scope for this operation.
+     * Determines what data and actions are allowed.
+     * @throws {InsufficientPermissionsError} If permission scope is inadequate.
+     */
     permissionId: number;
 }
 /**
- * Parameters for personal server operations.
+ * Defines parameters for initializing personal server connections.
+ *
+ * @remarks
+ * Establishes secure communication channels with a user's personal
+ * data server. The server manages encrypted user data and enforces
+ * permission-based access control. Initialization includes key exchange
+ * and session establishment.
+ *
+ * @example
+ * ```typescript
+ * const params: InitPersonalServerParams = {
+ *   userAddress: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+ * };
+ *
+ * const server = await vana.personal.initServer(params);
+ * console.log('Connected to server:', server.baseUrl);
+ * ```
+ *
+ * @category Personal Server
  */
 export interface InitPersonalServerParams {
-    /** The user's wallet address */
+    /**
+     * Identifies the user whose personal server to connect to.
+     * Must be a valid Ethereum address in hex format.
+     * @example '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+     */
     userAddress: string;
 }
 /**
- * Extended personal server identity information including connection details.
- * This combines the base PersonalServerModel with additional metadata
- * needed for client connections.
+ * Represents comprehensive personal server identity and connection information.
+ *
+ * @remarks
+ * Combines core server identity with connection metadata required for
+ * establishing secure communication. Personal servers are user-controlled
+ * nodes that store and serve encrypted personal data according to
+ * user-defined permissions. This interface provides all necessary
+ * information to connect to and interact with a personal server.
+ *
+ * @example
+ * ```typescript
+ * const identity: PersonalServerIdentity = {
+ *   kind: 'PersonalServer',
+ *   address: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   publicKey: '0x04...', // 65-byte uncompressed public key
+ *   baseUrl: 'https://ps.user.vana.com',
+ *   name: 'User Personal Server #1'
+ * };
+ *
+ * // Use identity to establish encrypted connection
+ * const encrypted = await crypto.encrypt(data, identity.publicKey);
+ * const response = await fetch(`${identity.baseUrl}/api/data`, {
+ *   method: 'POST',
+ *   body: encrypted
+ * });
+ * ```
+ *
+ * @category Personal Server
  */
 export interface PersonalServerIdentity {
-    /** Resource type identifier */
+    /**
+     * Identifies the resource type for API disambiguation.
+     * Always 'PersonalServer' for personal server instances.
+     */
     kind: string;
-    /** The server's Ethereum address */
+    /**
+     * Uniquely identifies the server on the blockchain.
+     * Used for permission verification and identity proofs.
+     * @example '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+     */
     address: string;
-    /** The server's public key for encryption */
+    /**
+     * Enables end-to-end encryption for data transmission.
+     * Must be in uncompressed format (65 bytes with 0x04 prefix).
+     * @example '0x04...' (130 hex characters)
+     */
     publicKey: string;
-    /** The base URL for connecting to this server */
+    /**
+     * Provides the HTTPS endpoint for server API requests.
+     * Should not include trailing slashes or API paths.
+     * @example 'https://ps.user.vana.com'
+     */
     baseUrl: string;
-    /** Human-readable name for this server */
+    /**
+     * Displays a user-friendly identifier for the server.
+     * Used in UI components and logging for clarity.
+     * @example 'Primary Data Server'
+     */
     name: string;
 }
+/**
+ * @remarks
+ * Additional server response types are auto-generated from the OpenAPI
+ * specification and available in the server-exports module. Import those
+ * types directly when working with server API responses.
+ *
+ * @see {@link ../types/server-exports | Server Export Types}
+ */