@opendatalabs/vana-sdk 0.1.0-alpha.e569cae → 0.1.0-alpha.e9cead7

package/dist/index.browser.d.ts

@@ -1752,6 +1752,12 @@ interface UserFile$1 {
     transactionHash?: Address;
     /** Additional file properties and custom application data. */
     metadata?: FileMetadata;
+    /**
+     * Array of DLP IDs that have submitted proofs for this file.
+     * Each proof represents verification or processing by a Data Liquidity Pool.
+     * Obtain DLP details via `vana.data.getDLP(dlpId)`.
+     */
+    dlpIds?: number[];
 }
 /**
  * Provides optional metadata for uploaded files and content description.
@@ -2163,33 +2169,84 @@ interface BatchUploadResult {
     errors?: string[];
 }
 /**
- * Represents a data schema in the refiner registry.
+ * Schema metadata from the blockchain (without fetched definition).
+ *
+ * This represents the on-chain schema registration data before the
+ * definition has been fetched from the storage URL.
+ *
+ * @category Data Management
+ */
+interface SchemaMetadata {
+    /** Schema ID */
+    id: number;
+    /** Schema name */
+    name: string;
+    /** Schema dialect ('json' or 'sqlite') */
+    dialect: "json" | "sqlite";
+    /** URL containing the schema definition */
+    definitionUrl: string;
+}
+/**
+ * Complete schema with all definition fields populated.
+ * This is what schemas.get() returns - a schema with the definition fetched.
+ */
+interface CompleteSchema extends SchemaMetadata {
+    /** Version of the schema */
+    version: string;
+    /** Optional description of the schema */
+    description?: string;
+    /** Optional version of the dialect */
+    dialectVersion?: string;
+    /** The actual schema - JSON Schema object for 'json' dialect, DDL string for 'sqlite' */
+    schema: object | string;
+}
+/**
+ * Schema with optional definition fields.
  *
  * Schemas define the structure and validation rules for user data processed by refiners.
  * They ensure data quality and consistency across the Vana network by specifying how
  * raw user data should be formatted, validated, and processed.
  *
+ * When the definition has been fetched (via schemas.get() or schemas.list() with includeDefinitions),
+ * the version and schema fields will be populated. Otherwise, only the metadata fields are present.
+ *
  * @category Data Management
  * @example
  * ```typescript
- * const socialMediaSchema: Schema = {
+ * // Complete schema from schemas.get()
+ * const completeSchema: Schema = {
+ *   id: 5,
+ *   name: 'Social Media Profile',
+ *   dialect: 'json',
+ *   definitionUrl: 'ipfs://QmSchema...',
+ *   version: '1.0.0',
+ *   description: 'Schema for validating social media profile data',
+ *   schema: { // JSON Schema object
+ *     type: 'object',
+ *     properties: {
+ *       username: { type: 'string' }
+ *     }
+ *   }
+ * };
+ *
+ * // Metadata-only schema from schemas.list() without includeDefinitions
+ * const metadataSchema: Schema = {
  *   id: 5,
  *   name: 'Social Media Profile',
- *   type: 'JSON',
- *   url: 'ipfs://QmSchema...', // Schema definition file
- *   description: 'Schema for validating social media profile data'
+ *   dialect: 'json',
+ *   definitionUrl: 'ipfs://QmSchema...'
  * };
  * ```
  */
-interface Schema {
-    /** Schema ID */
-    id: number;
-    /** Schema name */
-    name: string;
-    /** Schema dialect */
-    dialect: string;
-    /** URL containing the schema definition */
-    definitionUrl: string;
+interface Schema extends SchemaMetadata {
+    /** Version of the schema (present when definition is fetched) */
+    version?: string;
+    /** Optional description of the schema */
+    description?: string;
+    /** Optional version of the dialect */
+    dialectVersion?: string;
+    /** The actual schema - JSON Schema object for 'json' dialect, DDL string for 'sqlite' (present when definition is fetched) */
+    schema?: object | string;
 }
 /**
  * Represents a refiner with schema information
@@ -5179,6 +5236,31 @@ declare const contractAbis: {
         }];
         readonly name: "FileAdded";
         readonly type: "event";
+    }, {
+        readonly anonymous: false;
+        readonly inputs: readonly [{
+            readonly indexed: true;
+            readonly internalType: "uint256";
+            readonly name: "fileId";
+            readonly type: "uint256";
+        }, {
+            readonly indexed: true;
+            readonly internalType: "address";
+            readonly name: "ownerAddress";
+            readonly type: "address";
+        }, {
+            readonly indexed: false;
+            readonly internalType: "string";
+            readonly name: "url";
+            readonly type: "string";
+        }, {
+            readonly indexed: false;
+            readonly internalType: "uint256";
+            readonly name: "schemaId";
+            readonly type: "uint256";
+        }];
+        readonly name: "FileAddedV2";
+        readonly type: "event";
     }, {
         readonly anonymous: false;
         readonly inputs: readonly [{
@@ -5369,6 +5451,16 @@ declare const contractAbis: {
         }];
         readonly name: "Upgraded";
         readonly type: "event";
+    }, {
+        readonly inputs: readonly [];
+        readonly name: "DATA_PORTABILITY_ROLE";
+        readonly outputs: readonly [{
+            readonly internalType: "bytes32";
+            readonly name: "";
+            readonly type: "bytes32";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
     }, {
         readonly inputs: readonly [];
         readonly name: "DEFAULT_ADMIN_ROLE";
@@ -5441,6 +5533,33 @@ declare const contractAbis: {
         readonly outputs: readonly [];
         readonly stateMutability: "nonpayable";
         readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "fileId";
+            readonly type: "uint256";
+        }, {
+            readonly components: readonly [{
+                readonly internalType: "address";
+                readonly name: "account";
+                readonly type: "address";
+            }, {
+                readonly internalType: "string";
+                readonly name: "key";
+                readonly type: "string";
+            }];
+            readonly internalType: "struct IDataRegistry.Permission[]";
+            readonly name: "permissions";
+            readonly type: "tuple[]";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "schemaId";
+            readonly type: "uint256";
+        }];
+        readonly name: "addFilePermissionsAndSchema";
+        readonly outputs: readonly [];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
     }, {
         readonly inputs: readonly [{
             readonly internalType: "string";
@@ -5605,6 +5724,16 @@ declare const contractAbis: {
         }];
         readonly stateMutability: "view";
         readonly type: "function";
+    }, {
+        readonly inputs: readonly [];
+        readonly name: "emitLegacyEvents";
+        readonly outputs: readonly [{
+            readonly internalType: "bool";
+            readonly name: "";
+            readonly type: "bool";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
     }, {
         readonly inputs: readonly [{
             readonly internalType: "string";
@@ -5723,6 +5852,10 @@ declare const contractAbis: {
                 readonly internalType: "string";
                 readonly name: "url";
                 readonly type: "string";
+            }, {
+                readonly internalType: "uint256";
+                readonly name: "schemaId";
+                readonly type: "uint256";
             }, {
                 readonly internalType: "uint256";
                 readonly name: "addedAtBlock";
@@ -5940,6 +6073,16 @@ declare const contractAbis: {
         readonly outputs: readonly [];
         readonly stateMutability: "nonpayable";
         readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "bool";
+            readonly name: "newEmitLegacyEvents";
+            readonly type: "bool";
+        }];
+        readonly name: "updateEmitLegacyEvents";
+        readonly outputs: readonly [];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
     }, {
         readonly inputs: readonly [{
             readonly internalType: "address";
@@ -28788,19 +28931,19 @@ declare const EVENT_MAPPINGS: {
     };
     readonly addFile: {
         readonly contract: "DataRegistry";
-        readonly event: "FileAdded";
+        readonly event: "FileAddedV2";
     };
     readonly addFileWithPermissionsAndSchema: {
         readonly contract: "DataRegistry";
-        readonly event: "FileAdded";
+        readonly event: "FileAddedV2";
     };
     readonly addFileWithSchema: {
         readonly contract: "DataRegistry";
-        readonly event: "FileAdded";
+        readonly event: "FileAddedV2";
     };
     readonly addFileWithPermissions: {
         readonly contract: "DataRegistry";
-        readonly event: "FileAdded";
+        readonly event: "FileAddedV2";
     };
     readonly addRefinement: {
         readonly contract: "DataRegistry";
@@ -31307,10 +31450,10 @@ declare class PermissionsController {
 interface CreateSchemaParams {
     /** The name of the schema */
     name: string;
-    /** The type/category of the schema */
-    type: string;
+    /** The dialect of the schema (e.g., 'json' or 'sqlite') */
+    dialect: "json" | "sqlite";
     /** The schema definition object or JSON string */
-    definition: object | string;
+    schema: object | string;
 }
 /**
  * Result of creating a new schema.
@@ -31355,8 +31498,8 @@ interface CreateSchemaResult {
  * // Create a new schema with automatic IPFS upload
  * const result = await vana.schemas.create({
  *   name: "User Profile",
- *   type: "personal",
- *   definition: {
+ *   dialect: "json",
+ *   schema: {
  *     type: "object",
  *     properties: {
  *       name: { type: "string" },
@@ -31391,7 +31534,7 @@ declare class SchemaController {
      * - Uploads the definition to IPFS to generate a permanent URL
      * - Registers the schema on the blockchain with the generated URL
      *
-     * @param params - Schema creation parameters including name, type, and definition
+     * @param params - Schema creation parameters including name, dialect, and definition
      * @returns Promise resolving to creation results with schema ID and transaction hash
      * @throws {SchemaValidationError} When the schema definition is invalid
      * @throws {Error} When IPFS upload or blockchain registration fails
@@ -31400,8 +31543,8 @@ declare class SchemaController {
      * // Create a JSON schema for user profiles
      * const result = await vana.schemas.create({
      *   name: "User Profile",
-     *   type: "personal",
-     *   definition: {
+     *   dialect: "json",
+     *   schema: {
      *     type: "object",
      *     properties: {
      *       name: { type: "string" },
@@ -31416,27 +31559,28 @@ declare class SchemaController {
      */
     create(params: CreateSchemaParams): Promise<CreateSchemaResult>;
     /**
-     * Retrieves a schema by its ID.
+     * Retrieves a complete schema by its ID with definition fetched and flattened.
      *
      * @param schemaId - The ID of the schema to retrieve
      * @param options - Optional parameters
      * @param options.subgraphUrl - Custom subgraph URL to use instead of default
-     * @returns Promise resolving to the schema object
-     * @throws {Error} When the schema is not found or chain is unavailable
+     * @returns Promise resolving to the complete schema object with all fields populated
+     * @throws {Error} When the schema is not found, definition cannot be fetched, or chain is unavailable
      * @example
      * ```typescript
      * const schema = await vana.schemas.get(1);
-     * console.log(`Schema: ${schema.name} (${schema.type})`);
+     * console.log(`Schema: ${schema.name} (${schema.dialect})`);
+     * console.log(`Version: ${schema.version}`);
+     * console.log(`Description: ${schema.description}`);
+     * console.log('Schema:', schema.schema);
      *
-     * // With custom subgraph
-     * const schema = await vana.schemas.get(1, {
-     *   subgraphUrl: 'https://custom-subgraph.com/graphql'
-     * });
+     * // Use directly with validator (schema has all required fields)
+     * validator.validateDataAgainstSchema(data, schema);
      * ```
      */
     get(schemaId: number, options?: {
         subgraphUrl?: string;
-    }): Promise<Schema>;
+    }): Promise<CompleteSchema>;
     /**
      * Gets the total number of schemas registered on the network.
      *
@@ -31465,27 +31609,25 @@ declare class SchemaController {
      * @param options.limit - Maximum number of schemas to return
      * @param options.offset - Number of schemas to skip
      * @param options.subgraphUrl - Custom subgraph URL to use instead of default
+     * @param options.includeDefinitions - Whether to fetch and include schema definitions (default: false for performance)
      * @returns Promise resolving to an array of schemas
      * @example
      * ```typescript
-     * // Get all schemas
+     * // Get all schemas (without definitions for performance)
      * const schemas = await vana.schemas.list();
      *
+     * // Get schemas with definitions
+     * const schemas = await vana.schemas.list({ includeDefinitions: true });
+     *
      * // Get schemas with pagination
      * const schemas = await vana.schemas.list({ limit: 10, offset: 0 });
-     *
-     * // With custom subgraph
-     * const schemas = await vana.schemas.list({
-     *   limit: 10,
-     *   offset: 0,
-     *   subgraphUrl: 'https://custom-subgraph.com/graphql'
-     * });
      * ```
      */
     list(options?: {
         limit?: number;
         offset?: number;
         subgraphUrl?: string;
+        includeDefinitions?: boolean;
     }): Promise<Schema[]>;
     /**
      * Adds a schema using the legacy method (low-level API).
@@ -31532,6 +31674,13 @@ declare class SchemaController {
      * @returns Promise resolving to the user's address
      */
     private getUserAddress;
+    /**
+     * Fetches and attaches definitions to an array of schemas.
+     *
+     * @param schemas - Array of schemas to fetch definitions for
+     * @private
+     */
+    private _fetchDefinitionsForSchemas;
 }
 
 /**
@@ -31573,16 +31722,16 @@ declare class SchemaValidationError extends Error {
     }>);
 }
 /**
- * Schema validation utility class
+ * Data schema validation utility class
  */
 declare class SchemaValidator {
     private ajv;
     private dataSchemaValidator;
     constructor();
     /**
-     * Validates a data schema against the Vana meta-schema
+     * Validates a data schema definition against the Vana meta-schema
      *
-     * @param schema - The data schema to validate
+     * @param schema - The data schema definition to validate
      * @throws SchemaValidationError if invalid
      * @example
      * ```typescript
@@ -31601,39 +31750,35 @@ declare class SchemaValidator {
      *   }
      * };
      *
-     * validator.validateDataSchema(schema); // throws if invalid
+     * validator.validateDataSchemaAgainstMetaSchema(schema); // throws if invalid
      * ```
      */
-    validateDataSchema(schema: unknown): asserts schema is DataSchema;
+    validateDataSchemaAgainstMetaSchema(schema: unknown): asserts schema is DataSchema;
     /**
-     * Validates data against a JSON Schema from a data schema
+     * Validates data against a JSON Schema
      *
      * @param data - The data to validate
-     * @param schema - The data schema containing the schema
+     * @param schema - The schema containing the validation rules (must have been validated or fetched from chain)
      * @throws SchemaValidationError if invalid
      * @example
      * ```typescript
      * const validator = new SchemaValidator();
      *
-     * const schema = {
+     * // Works with Schema from schemas.get()
+     * const schema = await vana.schemas.get(1);
+     * validator.validateDataAgainstSchema(userData, schema);
+     *
+     * // Also works with pre-validated DataSchema object
+     * const dataSchema = validator.validateDataSchemaAgainstMetaSchema({
      *   name: "User Profile",
      *   version: "1.0.0",
      *   dialect: "json",
-     *   schema: {
-     *     type: "object",
-     *     properties: {
-     *       name: { type: "string" },
-     *       age: { type: "number" }
-     *     },
-     *     required: ["name"]
-     *   }
-     * };
-     *
-     * const userData = { name: "Alice", age: 30 };
-     * validator.validateDataAgainstSchema(userData, schema);
+     *   schema: { type: "object", properties: { name: { type: "string" } } }
+     * });
+     * validator.validateDataAgainstSchema(userData, dataSchema);
      * ```
      */
-    validateDataAgainstSchema(data: unknown, schema: DataSchema): void;
+    validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void;
     /**
      * Validates a SQLite DDL string for basic syntax
      * Note: This is a basic validation, full SQL parsing would require a proper SQL parser
@@ -31644,9 +31789,9 @@ declare class SchemaValidator {
      */
     validateSQLiteDDL(ddl: string, dialectVersion?: string): void;
     /**
-     * Fetches and validates a schema from a URL
+     * Fetches and validates a data schema from a URL
      *
-     * @param url - The URL to fetch the schema from
+     * @param url - The URL to fetch the data schema from
      * @returns The validated data schema
      * @throws SchemaValidationError if invalid or fetch fails
      * @example
@@ -31662,13 +31807,24 @@ declare class SchemaValidator {
  */
 declare const schemaValidator: SchemaValidator;
 /**
- * Convenience function to validate a data schema
+ * Convenience function to validate a data schema definition against the Vana meta-schema
  *
- * @param schema - The data schema to validate
- * @returns void - Assertion function that doesn't return a value
+ * @param schema - The data schema definition to validate
+ * @returns The validated DataSchema
  * @throws SchemaValidationError if invalid
+ * @example
+ * ```typescript
+ * const schemaDefinition = {
+ *   name: "User Profile",
+ *   version: "1.0.0",
+ *   dialect: "json",
+ *   schema: { type: "object", properties: { name: { type: "string" } } }
+ * };
+ *
+ * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);
+ * ```
  */
-declare function validateDataSchema(schema: unknown): asserts schema is DataSchema;
+declare function validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchema;
 /**
  * Convenience function to validate data against a schema
  *
@@ -31677,11 +31833,11 @@ declare function validateDataSchema(schema: unknown): asserts schema is DataSche
  * @returns void - Function doesn't return a value
  * @throws SchemaValidationError if invalid
  */
-declare function validateDataAgainstSchema(data: unknown, schema: DataSchema): void;
+declare function validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void;
 /**
- * Convenience function to fetch and validate a schema from a URL
+ * Convenience function to fetch and validate a data schema from a URL
  *
- * @param url - The URL to fetch the schema from
+ * @param url - The URL to fetch the data schema from
  * @returns The validated data schema
  * @throws SchemaValidationError if invalid or fetch fails
  */
@@ -34172,6 +34328,89 @@ declare class DataController {
         owner: Address;
         subgraphUrl?: string;
     }): Promise<UserFile$1[]>;
+    /**
+     * Fetches proof data for multiple files from the subgraph.
+     *
+     * @private
+     * @param fileIds - Array of file IDs to fetch proofs for
+     * @param subgraphUrl - The subgraph endpoint URL
+     * @returns Map of file IDs to their associated DLP IDs
+     */
+    private _fetchProofsFromSubgraph;
+    /**
+     * Fetches proof data for multiple files from the blockchain.
+     * Falls back to this when subgraph is unavailable.
+     *
+     * @private
+     * @param fileIds - Array of file IDs to fetch proofs for
+     * @returns Map of file IDs to their associated DLP IDs
+     */
+    private _fetchProofsFromChain;
+    /**
+     * Retrieves information about a specific Data Liquidity Pool (DLP).
+     *
+     * @remarks
+     * DLPs are entities that process and verify data files in the Vana network.
+     * This method fetches DLP metadata including name, status, and performance rating.
+     * Uses subgraph first for efficiency, falls back to chain if unavailable.
+     *
+     * @param dlpId - The unique identifier of the DLP
+     * @param options - Optional parameters
+     * @param options.subgraphUrl - Custom subgraph URL to override default
+     * @returns Promise resolving to DLP information
+     * @throws {Error} When DLP cannot be found - "DLP not found: {dlpId}"
+     * @throws {Error} When query fails - "Failed to fetch DLP: {error}"
+     * @example
+     * ```typescript
+     * const dlp = await vana.data.getDLP(26);
+     * console.log(`DLP ${dlp.name}: ${dlp.status}`);
+     * ```
+     */
+    getDLP(dlpId: number, options?: {
+        subgraphUrl?: string;
+    }): Promise<{
+        id: number;
+        name: string;
+        metadata?: string;
+        status?: number;
+        address?: Address;
+        owner?: Address;
+    }>;
+    /**
+     * Lists all Data Liquidity Pools (DLPs) with optional pagination.
+     *
+     * @remarks
+     * Fetches a paginated list of all DLPs registered in the network.
+     * Uses subgraph for efficient querying with fallback to chain multicall.
+     *
+     * @param options - Optional parameters for pagination and filtering
+     * @param options.limit - Maximum number of DLPs to return (default: 100)
+     * @param options.offset - Number of DLPs to skip (default: 0)
+     * @param options.subgraphUrl - Custom subgraph URL to override default
+     * @returns Promise resolving to array of DLP information
+     * @throws {Error} When query fails - "Failed to list DLPs: {error}"
+     * @example
+     * ```typescript
+     * // Get first 10 DLPs
+     * const dlps = await vana.data.listDLPs({ limit: 10 });
+     * dlps.forEach(dlp => console.log(`${dlp.id}: ${dlp.name}`));
+     *
+     * // Get next page
+     * const nextPage = await vana.data.listDLPs({ limit: 10, offset: 10 });
+     * ```
+     */
+    listDLPs(options?: {
+        limit?: number;
+        offset?: number;
+        subgraphUrl?: string;
+    }): Promise<Array<{
+        id: number;
+        name: string;
+        metadata?: string;
+        status?: number;
+        address?: Address;
+        owner?: Address;
+    }>>;
     /**
      * Retrieves a list of permissions granted by a user.
      *
@@ -34564,19 +34803,31 @@ declare class DataController {
      */
     addPermissionToFile(fileId: number, account: Address, publicKey: string): Promise<TransactionHandle<FilePermissionResult>>;
     /**
-     * Submits a file permission transaction and returns the transaction hash immediately.
+     * Submits a file permission transaction to the blockchain.
      *
-     * This is the lower-level method that provides maximum control over transaction timing.
+     * @remarks
+     * This method supports gasless transactions via relayer callbacks when configured.
+     * It encrypts the user's encryption key with the recipient's public key before submission.
      * Use this when you want to handle transaction confirmation and event parsing separately.
      *
-     * @param fileId - The ID of the file to add permissions for
-     * @param account - The address of the account to grant permission to
-     * @param publicKey - The public key to encrypt the user's encryption key with
-     * @returns Promise resolving to the transaction hash
+     * @param fileId - The ID of the file to grant permission for
+     * @param account - The recipient's wallet address that will access the file
+     * @param publicKey - The recipient's public key for encryption.
+     *   Obtain via `vana.server.getIdentity(account).public_key`
+     * @returns Promise resolving to TransactionHandle for tracking the transaction
+     * @throws {Error} When chain ID is not available
+     * @throws {Error} When encryption key generation fails
+     * @throws {Error} When public key encryption fails
+     *
      * @example
      * ```typescript
-     * const txHash = await vana.data.submitFilePermission(fileId, account, publicKey);
-     * console.log(`Transaction submitted: ${txHash}`);
+     * const tx = await vana.data.submitFilePermission(
+     *   fileId,
+     *   "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   recipientPublicKey
+     * );
+     * const result = await tx.waitForEvents();
+     * console.log(`Permission granted with ID: ${result.permissionId}`);
      * ```
      */
     submitFilePermission(fileId: number, account: Address, publicKey: string): Promise<TransactionHandle<FilePermissionResult>>;
@@ -34675,10 +34926,10 @@ declare class DataController {
         gateways?: string[];
     }): Promise<Blob>;
     /**
-     * Validates a data schema against the Vana meta-schema.
+     * Validates a data schema definition against the Vana meta-schema.
      *
-     * @param schema - The data schema to validate
-     * @returns Assertion that schema is valid (throws if invalid)
+     * @param schema - The data schema definition to validate
+     * @returns The validated DataSchema
      * @throws SchemaValidationError if invalid
      * @example
      * ```typescript
@@ -34695,10 +34946,10 @@ declare class DataController {
      *   }
      * };
      *
-     * vana.data.validateDataSchema(schema);
+     * const validatedSchema = vana.data.validateDataSchemaAgainstMetaSchema(schema);
      * ```
      */
-    validateDataSchema(schema: unknown): asserts schema is DataSchema;
+    validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchema;
     /**
      * Validates data against a JSON Schema from a data schema.
      *
@@ -34728,9 +34979,9 @@ declare class DataController {
      */
     validateDataAgainstSchema(data: unknown, schema: DataSchema): void;
     /**
-     * Fetches and validates a schema from a URL, then returns the parsed data schema.
+     * Fetches and validates a data schema from a URL, then returns the parsed data schema.
      *
-     * @param url - The URL to fetch the schema from
+     * @param url - The URL to fetch the data schema from
      * @returns The validated data schema
      * @throws SchemaValidationError if invalid or fetch fails
      * @example
@@ -34746,24 +34997,53 @@ declare class DataController {
      * ```
      */
     fetchAndValidateSchema(url: string): Promise<DataSchema>;
+}
+
+/**
+ * Configuration options for polling server operations.
+ */
+interface PollingOptions {
+    /** Polling interval in milliseconds (default: 500) */
+    pollingInterval?: number;
+    /** Maximum time to wait in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Provides a Promise-based interface for server operation lifecycle management.
+ *
+ * @remarks
+ * OperationHandle enables immediate access to operation IDs while providing
+ * Promise-based methods for waiting on results. This pattern matches
+ * TransactionHandle for consistency across the SDK's async operations.
+ *
+ * @category Server Operations
+ */
+declare class OperationHandle<T = unknown> {
+    private readonly controller;
+    readonly id: string;
+    private _resultPromise?;
+    constructor(controller: ServerController, id: string);
     /**
-     * Retrieves a schema by ID and fetches its definition URL to get the full data schema.
+     * Waits for the operation to complete and returns the result.
      *
-     * @param schemaId - The schema ID to retrieve and validate
-     * @returns The validated data schema
-     * @throws SchemaValidationError if schema is invalid
+     * @remarks
+     * Results are memoized - multiple calls return the same promise.
+     * The method polls the server at regular intervals until the operation
+     * succeeds, fails, or times out.
+     *
+     * @param options - Optional polling configuration
+     * @returns The operation result when completed
+     * @throws {PersonalServerError} When the operation fails or times out
      * @example
      * ```typescript
-     * // Get schema from registry and validate its schema
-     * const schema = await vana.data.getValidatedSchema(123);
-     *
-     * // Use it to validate user data
-     * if (schema.dialect === "json") {
-     *   vana.data.validateDataAgainstSchema(userData, schema);
-     * }
+     * const result = await handle.waitForResult({
+     *   timeout: 60000,
+     *   pollingInterval: 500
+     * });
      * ```
      */
-    getValidatedSchema(schemaId: number): Promise<DataSchema>;
+    waitForResult(options?: PollingOptions): Promise<T>;
+    private pollForCompletion;
 }
 
 /**
@@ -34846,54 +35126,47 @@ declare class ServerController {
      */
     getIdentity(request: InitPersonalServerParams): Promise<PersonalServerIdentity>;
     /**
-     * Creates an operation via the personal server API.
+     * Creates a server operation and returns a handle for lifecycle management.
      *
      * @remarks
-     * This method submits a computation request to the personal server API.
-     * The response includes the operation ID.
-     * @param params - The request parameters object
+     * This method submits a computation request to the personal server and returns
+     * an OperationHandle that provides Promise-based methods for waiting on results.
+     * The handle pattern matches TransactionHandle for consistency across async operations.
+     *
+     * @param params - The operation request parameters
      * @param params.permissionId - The permission ID authorizing this operation.
-     *   Obtain from granted permissions via `vana.permissions.getUserPermissionGrantsOnChain()`.
-     * @returns A Promise that resolves to an operation response with status and control URLs
-     * @throws {PersonalServerError} When server request fails or parameters are invalid.
-     *   Verify permissionId exists and is active for the target server.
-     * @throws {NetworkError} When personal server API communication fails.
-     *   Check server URL configuration and network connectivity.
+     *   Obtain via `vana.permissions.getUserPermissionGrantsOnChain()`.
+     * @returns An OperationHandle providing access to the operation ID and result methods
+     * @throws {PersonalServerError} When the server request fails or parameters are invalid
+     * @throws {NetworkError} When personal server API communication fails
      * @example
      * ```typescript
-     * const response = await vana.server.createOperation({
-     *   permissionId: 123,
+     * const operation = await vana.server.createOperation({
+     *   permissionId: 123
      * });
+     * console.log(`Operation ID: ${operation.id}`);
      *
-     * console.log(`Operation created: ${response.id}`);
+     * // Wait for completion
+     * const result = await operation.waitForResult();
+     * console.log("Result:", result);
      * ```
      */
-    createOperation(params: CreateOperationParams): Promise<CreateOperationResponse>;
+    createOperation<T = unknown>(params: CreateOperationParams): Promise<OperationHandle<T>>;
     /**
-     * Polls the status of a computation request for updates and results.
+     * Retrieves the current status and result of a server operation.
      *
      * @remarks
-     * This method checks the current status of a computation request by querying
-     * the personal server API using the provided operation ID. It returns the current
-     * status, any available output, and error information. The method can be
-     * called periodically until the operation completes or fails.
-     *
-     * Common status values include: `starting`, `processing`, `succeeded`, `failed`, `canceled`.
-     * @param operationId - The operation ID returned from the initial request submission
-     * @returns A Promise that resolves to the current operation response with status and results
-     * @throws {NetworkError} When the polling request fails or returns invalid data
+     * Common status values: `starting`, `running`, `succeeded`, `failed`, `canceled`.
+     * When status is `succeeded`, the result field contains the operation output.
+     *
+     * @param operationId - The ID of the operation to query
+     * @returns The operation response containing status, result, and metadata
+     * @throws {NetworkError} When the API request fails or returns invalid data
      * @example
      * ```typescript
-     * // Poll until completion
-     * let result = await vana.server.getOperation(response.id);
-     *
-     * while (result.status === "processing") {
-     *   await new Promise(resolve => setTimeout(resolve, 1000));
-     *   result = await vana.server.getOperation(response.id);
-     * }
-     *
-     * if (result.status === "succeeded") {
-     *   console.log("Computation completed:", result.output);
+     * const status = await vana.server.getOperation(operationId);
+     * if (status.status === 'succeeded') {
+     *   console.log('Result:', JSON.parse(status.result));
      * }
      * ```
      */
@@ -37458,4 +37731,4 @@ declare function Vana(config: VanaConfig): VanaBrowserImpl;
  */
 type VanaInstance = VanaBrowserImpl;
 
-export { type $defs, type APIResponse, type AddAndTrustServerInput, type AddAndTrustServerParams, type AddAndTrustServerTypedData, type AddRefinerParams, type AddRefinerResult, type AddSchemaParams, type AddSchemaResult, type AllKeys, ApiClient, type ApiClientConfig, type ApiResponse, AsyncQueue, type AsyncResult, type AuthenticationErrorResponse, type Awaited, type BaseConfig, type BaseConfigWithStorage, BaseController, type BatchServerInfoResult, type BatchUploadParams, type BatchUploadResult, type BlockRange, BlockchainError, type BlockchainErrorResponse, type Brand, BrowserPlatformAdapter, type Cache, type CacheConfig, CallbackStorage, type ChainConfig, type ChainConfigWithStorage, type CheckPermissionParams, CircuitBreaker, type ComputeErrorResponse, type ConditionalOptional, type ConfigValidationOptions, type ConfigValidationResult, type ContractAddresses, type ContractCall, type ContractDeployment, ContractFactory, type ContractInfo, type ContractMethodParams, type ContractMethodReturnType, ContractNotFoundError, type Controller, type ControllerContext, type CreateOperationParams, type CreateOperationRequest, type CreateOperationResponse, type CreateSchemaParams, type CreateSchemaResult, DEFAULT_ENCRYPTION_SEED, DEFAULT_IPFS_GATEWAY, DataController, type DataSchema, type DecryptionErrorResponse, type DeepPartial, type DeepReadonly, type DeleteFileParams, type DeleteFileResult, type DownloadFileParams, type DownloadFileResult, type EncryptedUploadParams, type EncryptionInfo, type ErrorResponse, EventEmitter, type EventFilter, type EventLog, type Factory, type FileAccessErrorResponse, type FileAccessPermissions, type FileMetadata, type FilePermissionParams, type FileSharingConfig, type GasEstimate, type GenericRequest, type GenericResponse, type GenericTypedData, type GetFileParams, type GetOperationResponse, type GetUserFilesParams, type GetUserPermissionsOptions, type GetUserTrustedServersParams, GoogleDriveStorage, GrantExpiredError, type GrantFile, type GrantPermissionParams, GrantSchemaError, GrantValidationError, type GrantValidationErrorResponse, type GrantValidationOptions, type GrantValidationResult, type GrantedPermission, type Grantee, type GranteeInfo, GranteeMismatchError, type GranteeQueryOptions, type HttpMethod, IPFS_GATEWAYS, type IdentityResponseModel, type InitPersonalServerParams, type InternalServerErrorResponse, InvalidConfigurationError, IpfsStorage, type LegacyPermissionParams, type MaybeArray, type MaybePromise, MemoryCache, type Middleware, MiddlewarePipeline, NetworkError, type NetworkInfo, type Nominal, type NonNullable, NonceError, type NotFoundErrorResponse, type Observable, type Observer, type OmitByType, type OnChainPermissionGrant, type OperationErrorResponse, OperationNotAllowedError, type OptionalKeys, type PaginatedGrantees, type PaginatedTrustedServers, type PaginationParams, type PaginationResult, type PartialExcept, type Permission, type PermissionAnalytics, type PermissionCheckResult, PermissionError, type PermissionEvent, type PermissionGrantDomain, type PermissionGrantMessage, type PermissionGrantTypedData, type PermissionInfo, type PermissionInputMessage, type PermissionOperation, type PermissionQueryResult, type PermissionStatus, PermissionsController, PersonalServerError, type PersonalServerIdentity, type PersonalServerModel, type PickByType, type PinataListResponse, type PinataPin, PinataStorage, type PinataUploadResponse, type Plugin, type PostRequestParams, type PromiseResult, ProtocolController, type QueryPermissionsParams, type RateLimitInfo, RateLimiter, type RateLimiterConfig, type Refiner, type RegisterGranteeInput, type RegisterGranteeParams, type RegisterGranteeTypedData, type RelayerCallbacks, type RelayerConfig, RelayerError, type RelayerErrorResponse, type RelayerMetrics, type RelayerQueueInfo, type RelayerRequestOptions, type RelayerStatus, type RelayerStorageResponse, type RelayerStoreParams, type RelayerSubmitParams, type RelayerTransactionResponse, type RelayerTransactionStatus, type RelayerWebhookConfig, type RelayerWebhookPayload, type ReplicateAPIResponse, type ReplicateStatus, type Repository, type RequestOptions, type RequireKeys, type RequiredExcept, type RetryConfig, RetryUtility, type RevokePermissionInput, type RevokePermissionParams, type RuntimeConfig, type Schema, SchemaValidationError, SchemaValidator, SerializationError, type Server, type components as ServerComponents, ServerController, type $defs as ServerDefs, type ServerFilesAndPermissionParams, type ServerFilesAndPermissionTypedData, type ServerInfo, type operations as ServerOperations, type paths as ServerPaths, type ServerTrustStatus, ServerUrlMismatchError, type webhooks as ServerWebhooks, type Service, SignatureCache, SignatureError, type SimplifiedPermissionMessage, type StateMachine, type StatusInfo, type StorageCallbacks, type StorageConfig, type StorageDownloadOptions, StorageError, type StorageFile, type StorageListOptions, type StorageListResult, StorageManager, type StorageProvider, type StorageProviderConfig, type StorageRequiredMarker, type StorageUploadResult, type TimeRange, TransactionHandle, type TransactionOptions, type TransactionReceipt, type Transformer, type TrustServerInput, type TrustServerParams, type TrustServerTypedData, type TrustedServer, type TrustedServerInfo, type TrustedServerQueryOptions, type UnencryptedUploadParams, type UntrustServerInput, type UntrustServerParams, type UntrustServerTypedData, type UpdateSchemaIdParams, type UpdateSchemaIdResult, type UploadEncryptedFileResult, type UploadFileParams, type UploadFileResult, type UploadParams, type UploadProgress, type UploadResult, type UserFile, UserRejectedRequestError, type ValidationErrorResponse, type ValidationResult, type Validator, Vana, VanaBrowserImpl, type VanaChain, type VanaChainConfig, type VanaChainId, type VanaConfig, type VanaConfigWithStorage, type VanaContract, type VanaContract as VanaContractAbi, type VanaContractInstance, type VanaContractName, VanaCore, VanaCoreFactory, VanaError, type VanaInstance, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createPlatformAdapterSafe, createValidatedGrant, decryptBlobWithSignedKey, decryptWithPrivateKey, decryptWithWalletPrivateKey, Vana as default, detectPlatform, encryptBlobWithSignedKey, encryptFileKey, encryptWithWalletPublicKey, extractIpfsHash, fetchAndValidateSchema, fetchWithFallbacks, formatEth, formatNumber, formatToken, generateEncryptionKey, generateEncryptionKeyPair, generatePGPKeyPair, getAbi, getAllChains, getChainConfig, getContractAddress, getContractController, getContractInfo, getEncryptionParameters, getGatewayUrls, getGrantFileHash, getGrantTimeRemaining, getPlatformCapabilities, hasStorageConfig, isAPIResponse, isChainConfig, isGrantExpired, isIpfsUrl, isPlatformSupported, isReplicateAPIResponse, isVanaChain, isVanaChainId, isWalletConfig, moksha, mokshaTestnet, type operations, parseReplicateOutput, type paths, retrieveAndValidateGrant, retrieveGrantFile, safeParseJSON, schemaValidator, shortenAddress, storeGrantFile, summarizeGrant, validateDataAgainstSchema, validateDataSchema, validateGrant, validateGrantExpiry, validateGrantFile, validateGranteeAccess, validateOperationAccess, vanaMainnet, type webhooks, withSignatureCache };
+export { type $defs, type APIResponse, type AddAndTrustServerInput, type AddAndTrustServerParams, type AddAndTrustServerTypedData, type AddRefinerParams, type AddRefinerResult, type AddSchemaParams, type AddSchemaResult, type AllKeys, ApiClient, type ApiClientConfig, type ApiResponse, AsyncQueue, type AsyncResult, type AuthenticationErrorResponse, type Awaited, type BaseConfig, type BaseConfigWithStorage, BaseController, type BatchServerInfoResult, type BatchUploadParams, type BatchUploadResult, type BlockRange, BlockchainError, type BlockchainErrorResponse, type Brand, BrowserPlatformAdapter, type Cache, type CacheConfig, CallbackStorage, type ChainConfig, type ChainConfigWithStorage, type CheckPermissionParams, CircuitBreaker, type CompleteSchema, type ComputeErrorResponse, type ConditionalOptional, type ConfigValidationOptions, type ConfigValidationResult, type ContractAddresses, type ContractCall, type ContractDeployment, ContractFactory, type ContractInfo, type ContractMethodParams, type ContractMethodReturnType, ContractNotFoundError, type Controller, type ControllerContext, type CreateOperationParams, type CreateOperationRequest, type CreateOperationResponse, type CreateSchemaParams, type CreateSchemaResult, DEFAULT_ENCRYPTION_SEED, DEFAULT_IPFS_GATEWAY, DataController, type DataSchema, type DecryptionErrorResponse, type DeepPartial, type DeepReadonly, type DeleteFileParams, type DeleteFileResult, type DownloadFileParams, type DownloadFileResult, type EncryptedUploadParams, type EncryptionInfo, type ErrorResponse, EventEmitter, type EventFilter, type EventLog, type Factory, type FileAccessErrorResponse, type FileAccessPermissions, type FileMetadata, type FilePermissionParams, type FileSharingConfig, type GasEstimate, type GenericRequest, type GenericResponse, type GenericTypedData, type GetFileParams, type GetOperationResponse, type GetUserFilesParams, type GetUserPermissionsOptions, type GetUserTrustedServersParams, GoogleDriveStorage, GrantExpiredError, type GrantFile, type GrantPermissionParams, GrantSchemaError, GrantValidationError, type GrantValidationErrorResponse, type GrantValidationOptions, type GrantValidationResult, type GrantedPermission, type Grantee, type GranteeInfo, GranteeMismatchError, type GranteeQueryOptions, type HttpMethod, IPFS_GATEWAYS, type IdentityResponseModel, type InitPersonalServerParams, type InternalServerErrorResponse, InvalidConfigurationError, IpfsStorage, type LegacyPermissionParams, type MaybeArray, type MaybePromise, MemoryCache, type Middleware, MiddlewarePipeline, NetworkError, type NetworkInfo, type Nominal, type NonNullable, NonceError, type NotFoundErrorResponse, type Observable, type Observer, type OmitByType, type OnChainPermissionGrant, type OperationErrorResponse, OperationNotAllowedError, type OptionalKeys, type PaginatedGrantees, type PaginatedTrustedServers, type PaginationParams, type PaginationResult, type PartialExcept, type Permission, type PermissionAnalytics, type PermissionCheckResult, PermissionError, type PermissionEvent, type PermissionGrantDomain, type PermissionGrantMessage, type PermissionGrantTypedData, type PermissionInfo, type PermissionInputMessage, type PermissionOperation, type PermissionQueryResult, type PermissionStatus, PermissionsController, PersonalServerError, type PersonalServerIdentity, type PersonalServerModel, type PickByType, type PinataListResponse, type PinataPin, PinataStorage, type PinataUploadResponse, type Plugin, type PostRequestParams, type PromiseResult, ProtocolController, type QueryPermissionsParams, type RateLimitInfo, RateLimiter, type RateLimiterConfig, type Refiner, type RegisterGranteeInput, type RegisterGranteeParams, type RegisterGranteeTypedData, type RelayerCallbacks, type RelayerConfig, RelayerError, type RelayerErrorResponse, type RelayerMetrics, type RelayerQueueInfo, type RelayerRequestOptions, type RelayerStatus, type RelayerStorageResponse, type RelayerStoreParams, type RelayerSubmitParams, type RelayerTransactionResponse, type RelayerTransactionStatus, type RelayerWebhookConfig, type RelayerWebhookPayload, type ReplicateAPIResponse, type ReplicateStatus, type Repository, type RequestOptions, type RequireKeys, type RequiredExcept, type RetryConfig, RetryUtility, type RevokePermissionInput, type RevokePermissionParams, type RuntimeConfig, type Schema, type SchemaMetadata, SchemaValidationError, SchemaValidator, SerializationError, type Server, type components as ServerComponents, ServerController, type $defs as ServerDefs, type ServerFilesAndPermissionParams, type ServerFilesAndPermissionTypedData, type ServerInfo, type operations as ServerOperations, type paths as ServerPaths, type ServerTrustStatus, ServerUrlMismatchError, type webhooks as ServerWebhooks, type Service, SignatureCache, SignatureError, type SimplifiedPermissionMessage, type StateMachine, type StatusInfo, type StorageCallbacks, type StorageConfig, type StorageDownloadOptions, StorageError, type StorageFile, type StorageListOptions, type StorageListResult, StorageManager, type StorageProvider, type StorageProviderConfig, type StorageRequiredMarker, type StorageUploadResult, type TimeRange, TransactionHandle, type TransactionOptions, type TransactionReceipt, type Transformer, type TrustServerInput, type TrustServerParams, type TrustServerTypedData, type TrustedServer, type TrustedServerInfo, type TrustedServerQueryOptions, type UnencryptedUploadParams, type UntrustServerInput, type UntrustServerParams, type UntrustServerTypedData, type UpdateSchemaIdParams, type UpdateSchemaIdResult, type UploadEncryptedFileResult, type UploadFileParams, type UploadFileResult, type UploadParams, type UploadProgress, type UploadResult, type UserFile, UserRejectedRequestError, type ValidationErrorResponse, type ValidationResult, type Validator, Vana, VanaBrowserImpl, type VanaChain, type VanaChainConfig, type VanaChainId, type VanaConfig, type VanaConfigWithStorage, type VanaContract, type VanaContract as VanaContractAbi, type VanaContractInstance, type VanaContractName, VanaCore, VanaCoreFactory, VanaError, type VanaInstance, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createPlatformAdapterSafe, createValidatedGrant, decryptBlobWithSignedKey, decryptWithPrivateKey, decryptWithWalletPrivateKey, Vana as default, detectPlatform, encryptBlobWithSignedKey, encryptFileKey, encryptWithWalletPublicKey, extractIpfsHash, fetchAndValidateSchema, fetchWithFallbacks, formatEth, formatNumber, formatToken, generateEncryptionKey, generateEncryptionKeyPair, generatePGPKeyPair, getAbi, getAllChains, getChainConfig, getContractAddress, getContractController, getContractInfo, getEncryptionParameters, getGatewayUrls, getGrantFileHash, getGrantTimeRemaining, getPlatformCapabilities, hasStorageConfig, isAPIResponse, isChainConfig, isGrantExpired, isIpfsUrl, isPlatformSupported, isReplicateAPIResponse, isVanaChain, isVanaChainId, isWalletConfig, moksha, mokshaTestnet, type operations, parseReplicateOutput, type paths, retrieveAndValidateGrant, retrieveGrantFile, safeParseJSON, schemaValidator, shortenAddress, storeGrantFile, summarizeGrant, validateDataAgainstSchema, validateDataSchemaAgainstMetaSchema, validateGrant, validateGrantExpiry, validateGrantFile, validateGranteeAccess, validateOperationAccess, vanaMainnet, type webhooks, withSignatureCache };