@opendatalabs/vana-sdk 0.1.0-alpha.c3ea747 → 0.1.0-alpha.c4bed73

package/dist/index.browser.d.ts

@@ -1,4 +1,4 @@
-import { Chain, Address, Hash, WalletClient, Account, Abi, GetContractReturnType, PublicClient } from 'viem';
+import { Chain, Address, Hash, WalletClient, Account, Abi, GetContractReturnType, TransactionReceipt as TransactionReceipt$1, PublicClient } from 'viem';
 export { Abi, Account, Address, Chain, GetContractReturnType, Hash, PublicClient, WalletClient } from 'viem';
 import { Abi as Abi$1 } from 'abitype';
 
@@ -984,6 +984,8 @@ interface ServerFilesAndPermissionParams {
     grant: string;
     /** File URLs */
     fileUrls: string[];
+    /** Schema IDs for each file - use 0 for files without schema validation */
+    schemaIds: number[];
     /** Server address */
     serverAddress: Address;
     /** Server URL */
@@ -1009,6 +1011,8 @@ interface ServerFilesAndPermissionTypedData extends GenericTypedData {
         grant: string;
         /** File URLs */
         fileUrls: string[];
+        /** Schema IDs for each file - use 0 for files without schema validation */
+        schemaIds: bigint[];
         /** Server address */
         serverAddress: Address;
         /** Server URL */
@@ -1019,6 +1023,39 @@ interface ServerFilesAndPermissionTypedData extends GenericTypedData {
         filePermissions: Permission[][];
     };
 }
+/**
+ * Input structure for FilePermission typed data
+ *
+ * @category Permissions
+ */
+interface FilePermissionInput extends RecordCompatible {
+    /** User nonce */
+    nonce: bigint;
+    /** File ID to grant permission for */
+    fileId: number;
+    /** Account address to grant permission to */
+    account: Address;
+    /** Encrypted key for the permission */
+    encryptedKey: string;
+}
+/**
+ * EIP-712 typed data for FilePermission
+ *
+ * @category Permissions
+ */
+interface FilePermissionTypedData extends GenericTypedData {
+    /** EIP-712 types */
+    types: {
+        FilePermission: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+    /** Primary type */
+    primaryType: "FilePermission";
+    /** Message to sign */
+    message: FilePermissionInput;
+}
 
 /**
  * Marker interface to indicate that a Vana instance has storage configured.
@@ -1243,6 +1280,22 @@ interface RelayerCallbacks {
      * @returns Promise resolving to the storage URL
      */
     storeGrantFile?: (grantData: GrantFile) => Promise<string>;
+    /**
+     * Submit a signed file permission transaction for relay
+     *
+     * @param params - Complete parameters for file permission
+     * @param params.fileId - The file ID to grant permission for
+     * @param params.account - The account address to grant permission to
+     * @param params.encryptedKey - The encrypted key for the permission
+     * @param params.userAddress - The user's address (owner of the file)
+     * @returns Promise resolving to the transaction hash
+     */
+    submitFilePermission?: (params: {
+        fileId: number;
+        account: Address;
+        encryptedKey: string;
+        userAddress: Address;
+    }) => Promise<Hash>;
 }
 /**
  * Storage callback functions for flexible storage operations.
@@ -1748,6 +1801,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.
@@ -2159,33 +2218,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',
- *   type: 'JSON',
- *   url: 'ipfs://QmSchema...', // Schema definition file
- *   description: 'Schema for validating social media profile data'
+ *   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',
+ *   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
@@ -2441,6 +2551,18 @@ declare const contractAbis: {
         }];
         readonly name: "InvalidPermissionsLength";
         readonly type: "error";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "filesLength";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "schemaIdsLength";
+            readonly type: "uint256";
+        }];
+        readonly name: "InvalidSchemaIdsLength";
+        readonly type: "error";
     }, {
         readonly inputs: readonly [];
         readonly name: "InvalidSignature";
@@ -2717,6 +2839,10 @@ declare const contractAbis: {
                 readonly internalType: "string[]";
                 readonly name: "fileUrls";
                 readonly type: "string[]";
+            }, {
+                readonly internalType: "uint256[]";
+                readonly name: "schemaIds";
+                readonly type: "uint256[]";
             }, {
                 readonly internalType: "address";
                 readonly name: "serverAddress";
@@ -3699,7 +3825,7 @@ declare const contractAbis: {
             readonly name: "addServerInput";
             readonly type: "tuple";
         }];
-        readonly name: "addAndTrustServerOnBehalf";
+        readonly name: "addAndTrustServerByManager";
         readonly outputs: readonly [];
         readonly stateMutability: "nonpayable";
         readonly type: "function";
@@ -4087,6 +4213,20 @@ declare const contractAbis: {
         readonly outputs: readonly [];
         readonly stateMutability: "nonpayable";
         readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "userAddress";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "serverId";
+            readonly type: "uint256";
+        }];
+        readonly name: "trustServerByManager";
+        readonly outputs: readonly [];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
     }, {
         readonly inputs: readonly [{
             readonly components: readonly [{
@@ -5145,6 +5285,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 [{
@@ -5571,6 +5736,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";
@@ -5689,6 +5864,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";
@@ -5906,6 +6085,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";
@@ -28710,6 +28899,95 @@ type VanaContract = keyof ContractAbis;
  */
 declare function getAbi<T extends VanaContract>(contract: T): ContractAbis[T];
 
+/**
+ * Comprehensive mapping of SDK transaction operations to blockchain events.
+ * Used by the generic transaction parser to know which contract and event
+ * to look for when parsing transaction results.
+ */
+declare const EVENT_MAPPINGS: {
+    readonly grant: {
+        readonly contract: "DataPortabilityPermissions";
+        readonly event: "PermissionAdded";
+    };
+    readonly revoke: {
+        readonly contract: "DataPortabilityPermissions";
+        readonly event: "PermissionRevoked";
+    };
+    readonly revokePermission: {
+        readonly contract: "DataPortabilityPermissions";
+        readonly event: "PermissionRevoked";
+    };
+    readonly addServerFilesAndPermissions: {
+        readonly contract: "DataPortabilityPermissions";
+        readonly event: "PermissionAdded";
+    };
+    readonly trustServer: {
+        readonly contract: "DataPortabilityServers";
+        readonly event: "ServerTrusted";
+    };
+    readonly untrustServer: {
+        readonly contract: "DataPortabilityServers";
+        readonly event: "ServerUntrusted";
+    };
+    readonly registerServer: {
+        readonly contract: "DataPortabilityServers";
+        readonly event: "ServerRegistered";
+    };
+    readonly updateServer: {
+        readonly contract: "DataPortabilityServers";
+        readonly event: "ServerUpdated";
+    };
+    readonly addAndTrustServer: {
+        readonly contract: "DataPortabilityServers";
+        readonly event: "ServerTrusted";
+    };
+    readonly addFile: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAddedV2";
+    };
+    readonly addFileWithPermissionsAndSchema: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAddedV2";
+    };
+    readonly addFileWithSchema: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAddedV2";
+    };
+    readonly addFileWithPermissions: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAddedV2";
+    };
+    readonly addRefinement: {
+        readonly contract: "DataRegistry";
+        readonly event: "RefinementAdded";
+    };
+    readonly addRefiner: {
+        readonly contract: "DataRefinerRegistry";
+        readonly event: "RefinerAdded";
+    };
+    readonly updateSchemaId: {
+        readonly contract: "DataRefinerRegistry";
+        readonly event: "SchemaAdded";
+    };
+    readonly addSchema: {
+        readonly contract: "DataRefinerRegistry";
+        readonly event: "SchemaAdded";
+    };
+    readonly updateRefinement: {
+        readonly contract: "DataRegistry";
+        readonly event: "RefinementUpdated";
+    };
+    readonly addFilePermission: {
+        readonly contract: "DataRegistry";
+        readonly event: "PermissionGranted";
+    };
+    readonly registerGrantee: {
+        readonly contract: "DataPortabilityGrantees";
+        readonly event: "GranteeRegistered";
+    };
+};
+type TransactionOperation = keyof typeof EVENT_MAPPINGS;
+
 /**
  * Base interface for all transaction results.
  * Contains the event data plus transaction metadata.
@@ -28747,6 +29025,50 @@ interface PermissionRevokeResult extends BaseTransactionResult {
     /** ID of the permission that was revoked */
     permissionId: bigint;
 }
+/**
+ * Result of a successful server trust operation.
+ * Contains data from the ServerTrusted blockchain event.
+ */
+interface ServerTrustResult extends BaseTransactionResult {
+    /** Address of the user who trusted the server */
+    user: Address;
+    /** Address/ID of the trusted server */
+    serverId: Address;
+    /** URL of the trusted server */
+    serverUrl: string;
+}
+/**
+ * Result of a successful server untrust operation.
+ * Contains data from the ServerUntrusted blockchain event.
+ */
+interface ServerUntrustResult extends BaseTransactionResult {
+    /** Address of the user who untrusted the server */
+    user: Address;
+    /** Address/ID of the untrusted server */
+    serverId: Address;
+}
+/**
+ * Result of a successful server update operation.
+ * Contains data from the ServerUpdated blockchain event.
+ */
+interface ServerUpdateResult extends BaseTransactionResult {
+    /** ID of the server that was updated */
+    serverId: bigint;
+    /** New URL of the server */
+    url: string;
+}
+/**
+ * Result of a successful grantee registration operation.
+ * Contains data from the GranteeRegistered blockchain event.
+ */
+interface GranteeRegisterResult extends BaseTransactionResult {
+    /** Unique grantee ID assigned by the registry */
+    granteeId: bigint;
+    /** Address of the registered grantee */
+    granteeAddress: Address;
+    /** Display name of the grantee */
+    name: string;
+}
 /**
  * Result of a successful file permission addition operation.
  * Contains data from the FilePermissionAdded blockchain event.
@@ -28760,6 +29082,80 @@ interface FilePermissionResult extends BaseTransactionResult {
     encryptedKey: string;
 }
 
+/**
+ * Provides a unified interface for blockchain transaction results with lazy-loaded event parsing.
+ *
+ * @remarks
+ * TransactionHandle enables immediate access to transaction hashes while providing optional
+ * lazy-loaded access to receipts and parsed event data. All transaction-submitting methods
+ * in the SDK return this handle, allowing developers to choose between immediate hash access
+ * or waiting for event data. Results are memoized to prevent redundant network calls.
+ *
+ * @category Transactions
+ * @example
+ * ```typescript
+ * // Immediate hash access
+ * const tx = await sdk.permissions.submitSignedGrant(typedData, signature);
+ * console.log(`Transaction submitted: ${tx.hash}`);
+ *
+ * // Wait for and parse events
+ * const eventData = await tx.waitForEvents();
+ * console.log(`Permission ID: ${eventData.permissionId}`);
+ *
+ * // Check receipt for gas usage
+ * const receipt = await tx.waitForReceipt();
+ * console.log(`Gas used: ${receipt.gasUsed}`);
+ * ```
+ */
+declare class TransactionHandle<TEventData = unknown> {
+    private readonly context;
+    readonly hash: Hash;
+    private readonly operation?;
+    private _receipt?;
+    private _eventData?;
+    private _receiptPromise?;
+    private _eventPromise?;
+    constructor(context: ControllerContext$1, hash: Hash, operation?: TransactionOperation | undefined);
+    /**
+     * Waits for transaction confirmation and returns the receipt.
+     * Results are memoized - multiple calls return the same promise.
+     *
+     * @param options Optional timeout configuration
+     * @param options.timeout Timeout in milliseconds (default: 30000)
+     * @returns Transaction receipt with gas usage, logs, and status
+     */
+    waitForReceipt(options?: {
+        timeout?: number;
+    }): Promise<TransactionReceipt$1>;
+    /**
+     * Waits for transaction confirmation and parses emitted events.
+     * Results are memoized - multiple calls return the same promise.
+     *
+     * @returns Parsed event data with transaction metadata
+     * @throws {Error} If no operation was specified for event parsing
+     */
+    waitForEvents(): Promise<TEventData>;
+    /**
+     * Enables string coercion for backwards compatibility.
+     * Allows TransactionHandle to be used anywhere a Hash is expected.
+     *
+     * @example
+     * ```typescript
+     * const hash: Hash = tx; // Works via toString()
+     * console.log(`Transaction: ${tx}`); // Prints hash
+     * ```
+     * @returns The transaction hash as a string
+     */
+    toString(): string;
+    /**
+     * JSON serialization support.
+     * Returns the hash when serialized to JSON.
+     *
+     * @returns The transaction hash for JSON serialization
+     */
+    toJSON(): string;
+}
+
 /**
  * Google Drive Storage Provider for Vana SDK
  *
@@ -29798,30 +30194,31 @@ declare class PermissionsController {
      */
     grant(params: GrantPermissionParams$1): Promise<PermissionGrantResult>;
     /**
-     * Submits a permission grant transaction and returns the transaction hash immediately.
+     * Submits a permission grant transaction and returns a handle for flexible result access.
      *
-     * This is the lower-level method that provides maximum control over transaction timing.
-     * Use this when you want to handle transaction confirmation and event parsing separately,
-     * or when submitting multiple transactions in batch.
+     * @remarks
+     * This lower-level method provides maximum control over transaction timing.
+     * Returns a TransactionHandle that allows immediate hash access or optional event parsing.
+     * Use this when handling multiple transactions or when you need granular control.
      *
      * @param params - The permission grant configuration object
-     * @returns Promise that resolves to the transaction hash when successfully submitted
+     * @returns Promise resolving to TransactionHandle with hash and event parsing capabilities
      * @throws {RelayerError} When gasless transaction submission fails
      * @throws {SignatureError} When user rejects the signature request
      * @throws {SerializationError} When grant data cannot be serialized
      * @throws {BlockchainError} When permission grant preparation fails
      * @example
      * ```typescript
-     * // Submit transaction and handle confirmation later
-     * const txHash = await vana.permissions.submitPermissionGrant(params);
-     * console.log(`Transaction submitted: ${txHash}`);
+     * // Submit transaction and get immediate hash access
+     * const tx = await vana.permissions.submitPermissionGrant(params);
+     * console.log(`Transaction submitted: ${tx.hash}`);
      *
-     * // Later, when you need the permission data:
-     * const result = await parseTransactionResult(context, txHash, 'grant');
-     * console.log(`Permission ID: ${result.permissionId}`);
+     * // Optionally wait for and parse events
+     * const eventData = await tx.waitForEvents();
+     * console.log(`Permission ID: ${eventData.permissionId}`);
      * ```
      */
-    submitPermissionGrant(params: GrantPermissionParams$1): Promise<Hash>;
+    submitPermissionGrant(params: GrantPermissionParams$1): Promise<TransactionHandle<PermissionGrantResult>>;
     /**
      * Prepares a permission grant with preview before signing.
      *
@@ -29849,15 +30246,21 @@ declare class PermissionsController {
      */
     prepareGrant(params: GrantPermissionParams$1): Promise<{
         preview: GrantFile;
-        confirm: () => Promise<Hash>;
+        confirm: () => Promise<TransactionHandle<PermissionGrantResult>>;
     }>;
     /**
-     * Internal method to complete the grant process after user confirmation.
-     * This is called by the confirm() function returned from prepareGrant().
+     * Completes the grant process after user confirmation.
+     *
+     * @remarks
+     * This internal method is called by the confirm() function returned from prepareGrant().
+     * It handles IPFS upload, signature creation, and transaction submission.
      *
      * @param params - The permission grant parameters containing user and operation details
      * @param grantFile - The prepared grant file with permissions and metadata
-     * @returns Promise resolving to the transaction hash
+     * @returns Promise resolving to TransactionHandle for flexible result access
+     * @throws {BlockchainError} When permission grant confirmation fails
+     * @throws {NetworkError} When IPFS upload fails
+     * @throws {SignatureError} When user rejects the signature
      */
     private confirmGrantInternal;
     /**
@@ -29913,49 +30316,106 @@ declare class PermissionsController {
      * );
      * ```
      */
-    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash): Promise<Hash>;
+    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash): Promise<TransactionHandle<PermissionGrantResult>>;
     /**
      * Submits an already-signed trust server transaction to the blockchain.
+     *
+     * @remarks
      * This method extracts the trust server input from typed data and submits it directly.
+     * Used internally by trust server methods after signature collection.
      *
      * @param typedData - The EIP-712 typed data for TrustServer
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionHandle for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedTrustServer(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
      */
-    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash): Promise<Hash>;
+    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash): Promise<TransactionHandle<ServerTrustResult>>;
     /**
      * Submits an already-signed add and trust server transaction to the blockchain.
+     *
+     * @remarks
      * This method extracts the add and trust server input from typed data and submits it directly.
+     * Combines server registration and trust operations in a single transaction.
      *
      * @param typedData - The EIP-712 typed data for AddAndTrustServer
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionHandle for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedAddAndTrustServer(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
      */
-    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash): Promise<Hash>;
+    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash): Promise<TransactionHandle<ServerTrustResult>>;
     /**
      * Submits an already-signed permission revoke transaction to the blockchain.
+     *
+     * @remarks
      * This method handles the revocation of previously granted permissions.
+     * Used internally by revocation methods after signature collection.
      *
      * @param typedData - The EIP-712 typed data for PermissionRevoke
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionHandle for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedRevoke(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
      */
-    submitSignedRevoke(typedData: GenericTypedData, signature: Hash): Promise<Hash>;
+    submitSignedRevoke(typedData: GenericTypedData, signature: Hash): Promise<TransactionHandle<PermissionRevokeResult>>;
     /**
      * Submits an already-signed untrust server transaction to the blockchain.
+     *
+     * @remarks
      * This method handles the removal of trusted servers.
+     * Used internally by untrust server methods after signature collection.
      *
      * @param typedData - The EIP-712 typed data for UntrustServer
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionHandle for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedUntrustServer(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
      */
-    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash): Promise<Hash>;
+    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash): Promise<TransactionHandle<ServerUntrustResult>>;
     /**
      * Submits a signed transaction directly to the blockchain.
      *
+     * @remarks
+     * Internal method used when relayer callbacks are not available. Formats the signature
+     * and submits the permission grant directly to the smart contract.
+     *
      * @param typedData - The typed data structure for the permission grant
      * @param signature - The cryptographic signature authorizing the transaction
      * @returns Promise resolving to the transaction hash
+     * @throws {BlockchainError} When contract submission fails
      */
     private submitDirectTransaction;
     /**
@@ -30002,19 +30462,33 @@ declare class PermissionsController {
      * console.log(`Revocation submitted: ${txHash}`);
      * ```
      */
-    submitPermissionRevoke(params: RevokePermissionParams): Promise<Hash>;
+    submitPermissionRevoke(params: RevokePermissionParams): Promise<TransactionHandle<PermissionRevokeResult>>;
     /**
-     * Revokes a permission with a signature (gasless transaction).
+     * Revokes a permission with a signature for gasless transactions.
+     *
+     * @remarks
+     * This method creates an EIP-712 signature for permission revocation and submits
+     * it either through relayer callbacks or directly to the blockchain. Provides
+     * gasless revocation when relayer is configured.
      *
      * @param params - Parameters for revoking the permission
-     * @returns Promise resolving to transaction hash
+     * @param params.permissionId - Permission identifier to revoke (accepts bigint, number, or string)
+     * @returns Promise resolving to TransactionHandle for transaction tracking
      * @throws {BlockchainError} When chain ID is not available
      * @throws {NonceError} When retrieving user nonce fails
      * @throws {SignatureError} When user rejects the signature request
      * @throws {RelayerError} When gasless submission fails
      * @throws {PermissionError} When revocation fails for any other reason
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitRevokeWithSignature({
+     *   permissionId: 123n
+     * });
+     * const result = await txHandle.waitForEvents();
+     * console.log(`Permission ${result.permissionId} revoked`);
+     * ```
      */
-    submitRevokeWithSignature(params: RevokePermissionParams): Promise<Hash>;
+    submitRevokeWithSignature(params: RevokePermissionParams): Promise<TransactionHandle<PermissionRevokeResult>>;
     /**
      * @deprecated Use getPermissionsUserNonce() for permission operations or getServersUserNonce() for server operations
      *
@@ -30039,6 +30513,18 @@ declare class PermissionsController {
      * const serversNonce = await this.getServersUserNonce();
      * ```
      */
+    /**
+     * @deprecated Use getPermissionsUserNonce() for permission operations or getServersUserNonce() for server operations
+     *
+     * Retrieves the user's current nonce from the DataPortabilityServers contract.
+     *
+     * @remarks
+     * This method is deprecated in favor of more specific nonce methods that target
+     * the appropriate contract for the operation being performed.
+     *
+     * @returns Promise resolving to the user's current nonce as a bigint
+     * @throws {NonceError} When retrieving the nonce fails
+     */
     private getUserNonce;
     /**
      * Retrieves the user's current nonce from the DataPortabilityServers contract.
@@ -30054,6 +30540,16 @@ declare class PermissionsController {
      * console.log(`Current servers nonce: ${nonce}`);
      * ```
      */
+    /**
+     * Retrieves the user's current nonce from the DataPortabilityServers contract.
+     *
+     * @remarks
+     * Used for server-related operations (trust/untrust) to prevent replay attacks.
+     * The nonce must be incremented with each server operation.
+     *
+     * @returns Promise resolving to the user's current nonce as a bigint
+     * @throws {NonceError} When retrieving the nonce fails
+     */
     private getServersUserNonce;
     /**
      * Retrieves the user's current nonce from the DataPortabilityPermissions contract.
@@ -30069,6 +30565,16 @@ declare class PermissionsController {
      * console.log(`Current permissions nonce: ${nonce}`);
      * ```
      */
+    /**
+     * Retrieves the user's current nonce from the DataPortabilityPermissions contract.
+     *
+     * @remarks
+     * Used for permission-related operations (grant/revoke) to prevent replay attacks.
+     * The nonce must be incremented with each permission operation.
+     *
+     * @returns Promise resolving to the user's current nonce as a bigint
+     * @throws {NonceError} When retrieving the nonce fails
+     */
     private getPermissionsUserNonce;
     /**
      * Composes the EIP-712 typed data for PermissionGrant (new simplified format).
@@ -30090,6 +30596,7 @@ declare class PermissionsController {
      * @param params.granteeId - Grantee ID
      * @param params.grant - Grant URL or grant data
      * @param params.fileUrls - Array of file URLs
+     * @param params.schemaIds - Schema IDs for each file
      * @param params.serverAddress - Server address
      * @param params.serverUrl - Server URL
      * @param params.serverPublicKey - Server public key
@@ -30195,7 +30702,7 @@ declare class PermissionsController {
      * console.log('Now trusting servers:', trustedServers);
      * ```
      */
-    addAndTrustServer(params: AddAndTrustServerParams): Promise<Hash>;
+    addAndTrustServer(params: AddAndTrustServerParams): Promise<TransactionHandle<ServerTrustResult>>;
     /**
      * Trusts a server for data processing (legacy method).
      *
@@ -30203,14 +30710,14 @@ declare class PermissionsController {
      * @returns Promise resolving to transaction hash
      * @deprecated Use addAndTrustServer instead
      */
-    submitTrustServer(params: TrustServerParams): Promise<Hash>;
+    submitTrustServer(params: TrustServerParams): Promise<TransactionHandle<ServerTrustResult>>;
     /**
      * Adds and trusts a server using a signature (gasless transaction).
      *
      * @param params - Parameters for adding and trusting the server
-     * @returns Promise resolving to transaction hash
+     * @returns Promise resolving to TransactionHandle with ServerTrustResult event data
      */
-    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams): Promise<Hash>;
+    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams): Promise<TransactionHandle<ServerTrustResult>>;
     /**
      * Trusts a server using a signature (gasless transaction - legacy method).
      *
@@ -30224,13 +30731,24 @@ declare class PermissionsController {
      * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
      * @throws {BlockchainError} When trust operation fails for any other reason
      */
-    submitTrustServerWithSignature(params: TrustServerParams): Promise<Hash>;
+    submitTrustServerWithSignature(params: TrustServerParams): Promise<TransactionHandle<ServerTrustResult>>;
     /**
      * Submits a direct untrust server transaction (without signature).
      *
      * @param params - The untrust server parameters containing server details
      * @returns Promise resolving to the transaction hash
      */
+    /**
+     * Submits an untrust server transaction directly to the blockchain.
+     *
+     * @remarks
+     * Internal method used for direct blockchain submission of untrust server operations
+     * when relayer callbacks are not available.
+     *
+     * @param params - The untrust server parameters
+     * @returns Promise resolving to TransactionHandle for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     */
     private submitDirectUntrustTransaction;
     /**
      * Removes a server from the user's trusted servers list in the DataPortabilityServers contract.
@@ -30260,7 +30778,7 @@ declare class PermissionsController {
      * console.log('Still trusting servers:', trustedServers);
      * ```
      */
-    submitUntrustServer(params: UntrustServerParams): Promise<Hash>;
+    submitUntrustServer(params: UntrustServerParams): Promise<TransactionHandle<ServerUntrustResult>>;
     /**
      * Untrusts a server using a signature (gasless transaction).
      *
@@ -30273,7 +30791,7 @@ declare class PermissionsController {
      * @throws {RelayerError} When gasless submission fails
      * @throws {BlockchainError} When untrust transaction fails
      */
-    submitUntrustServerWithSignature(params: UntrustServerParams): Promise<Hash>;
+    submitUntrustServerWithSignature(params: UntrustServerParams): Promise<TransactionHandle<ServerUntrustResult>>;
     /**
      * Retrieves all servers trusted by a user from the DataPortabilityServers contract.
      *
@@ -30324,22 +30842,60 @@ declare class PermissionsController {
     /**
      * Gets server information for multiple servers efficiently.
      *
-     * @param serverIds - Array of server IDs to query
-     * @returns Promise resolving to batch result with successes and failures
+     * @remarks
+     * This method uses multicall to fetch information for multiple servers in a single
+     * blockchain call, improving performance when querying many servers. Failed lookups
+     * are returned separately for error handling.
+     *
+     * @param serverIds - Array of numeric server IDs to query
+     * @returns Promise resolving to batch result containing successful lookups and failed IDs
      * @throws {BlockchainError} When reading from contract fails or chain is unavailable
+     * @example
+     * ```typescript
+     * const result = await vana.permissions.getServerInfoBatch([1, 2, 3, 999]);
+     *
+     * // Process successful lookups
+     * result.servers.forEach((server, id) => {
+     *   console.log(`Server ${id}: ${server.url}`);
+     * });
+     *
+     * // Handle failed lookups
+     * if (result.failed.length > 0) {
+     *   console.log(`Failed to fetch: ${result.failed.join(', ')}`);
+     * }
+     * ```
      */
     getServerInfoBatch(serverIds: number[]): Promise<BatchServerInfoResult>;
     /**
      * Checks whether a specific server is trusted by a user.
      *
-     * @param serverId - Server ID to check (numeric)
+     * @remarks
+     * This method queries the user's trusted server list and checks if the specified
+     * server is present. Returns both the trust status and the index in the trust list
+     * if trusted.
+     *
+     * @param serverId - Numeric server ID to check
      * @param userAddress - Optional user address (defaults to current user)
-     * @returns Promise resolving to server trust status
+     * @returns Promise resolving to server trust status with trust index if applicable
+     * @throws {BlockchainError} When reading from contract fails
+     * @example
+     * ```typescript
+     * const status = await vana.permissions.checkServerTrustStatus(1);
+     * if (status.isTrusted) {
+     *   console.log(`Server is trusted at index ${status.trustIndex}`);
+     * } else {
+     *   console.log('Server is not trusted');
+     * }
+     * ```
      */
     checkServerTrustStatus(serverId: number, userAddress?: Address): Promise<ServerTrustStatus>;
     /**
      * Composes EIP-712 typed data for AddAndTrustServer.
      *
+     * @remarks
+     * Creates the complete typed data structure required for EIP-712 signature generation
+     * when adding and trusting a new server in a single transaction.
+     *
      * @param input - The add and trust server input data containing server details
      * @returns Promise resolving to the typed data structure for server add and trust
      */
@@ -30421,7 +30977,7 @@ declare class PermissionsController {
      * console.log(`Grantee registered in transaction: ${txHash}`);
      * ```
      */
-    submitRegisterGrantee(params: RegisterGranteeParams): Promise<Hash>;
+    submitRegisterGrantee(params: RegisterGranteeParams): Promise<TransactionHandle<GranteeRegisterResult>>;
     /**
      * Registers a grantee with a signature (gasless transaction)
      *
@@ -30437,7 +30993,7 @@ declare class PermissionsController {
      * });
      * ```
      */
-    submitRegisterGranteeWithSignature(params: RegisterGranteeParams): Promise<Hash>;
+    submitRegisterGranteeWithSignature(params: RegisterGranteeParams): Promise<TransactionHandle<GranteeRegisterResult>>;
     /**
      * Submits a signed register grantee transaction via relayer
      *
@@ -30450,7 +31006,7 @@ declare class PermissionsController {
      * const result = await vana.permissions.submitSignedRegisterGrantee(typedData, signature);
      * ```
      */
-    submitSignedRegisterGrantee(typedData: RegisterGranteeTypedData, signature: Hash): Promise<Hash>;
+    submitSignedRegisterGrantee(typedData: RegisterGranteeTypedData, signature: Hash): Promise<TransactionHandle<GranteeRegisterResult>>;
     /**
      * Retrieves all registered grantees from the DataPortabilityGrantees contract.
      *
@@ -30737,7 +31293,7 @@ declare class PermissionsController {
      * @param url - New URL for the server
      * @returns Promise resolving to transaction hash
      */
-    submitUpdateServer(serverId: bigint, url: string): Promise<Hash>;
+    submitUpdateServer(serverId: bigint, url: string): Promise<TransactionHandle<ServerUpdateResult>>;
     /**
      * Get all permission IDs for a user
      *
@@ -30777,49 +31333,106 @@ declare class PermissionsController {
      * @throws {BlockchainError} When permission addition fails
      * @throws {NetworkError} When network communication fails
      */
-    submitAddPermission(params: ServerFilesAndPermissionParams): Promise<Hash>;
+    submitAddPermission(params: ServerFilesAndPermissionParams): Promise<TransactionHandle<PermissionGrantResult>>;
     /**
      * Submits an already-signed add permission transaction to the blockchain.
      * This method supports both relayer-based gasless transactions and direct transactions.
      *
      * @param typedData - The EIP-712 typed data for AddPermission
      * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
+     * @returns Promise resolving to TransactionHandle with PermissionGrantResult event data
      * @throws {RelayerError} When gasless transaction submission fails
      * @throws {BlockchainError} When permission addition fails
      * @throws {NetworkError} When network communication fails
      */
-    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash): Promise<Hash>;
+    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash): Promise<TransactionHandle<PermissionGrantResult>>;
     /**
-     * Submit server files and permissions with signature to the blockchain (supports gasless transactions)
+     * Submits server files and permissions with signature to the blockchain, supporting schema validation and gasless transactions.
+     *
+     * @remarks
+     * This method validates files against their specified schemas before submission.
+     * Schema validation ensures data conforms to expected formats before on-chain registration.
+     * Files with schemaId = 0 bypass validation. The method supports atomic batch operations
+     * where all files and permissions are registered in a single transaction.
      *
      * @param params - Parameters for adding server files and permissions
-     * @returns Promise resolving to transaction hash
-     * @throws {RelayerError} When gasless transaction submission fails
+     * @param params.granteeId - The ID of the permission grantee
+     * @param params.grant - Grant URL containing permission parameters (typically IPFS)
+     * @param params.fileUrls - Array of file URLs to register
+     * @param params.schemaIds - Schema IDs for each file. Use 0 for files without schema validation.
+     *   Array length must match fileUrls length.
+     * @param params.serverAddress - Server wallet address for decryption permissions
+     * @param params.serverUrl - Server endpoint URL
+     * @param params.serverPublicKey - Server's public key for encryption.
+     *   Obtain via `vana.server.getIdentity(userAddress).public_key`.
+     * @param params.filePermissions - Nested array of permissions for each file
+     * @returns TransactionHandle with immediate hash access and event parsing capability
+     * @throws {Error} When schemaIds array length doesn't match fileUrls array length
+     * @throws {SchemaValidationError} When file data doesn't match the specified schema.
+     *   Verify data structure matches schema definition from `vana.schemas.get(schemaId)`.
+     * @throws {RelayerError} When gasless transaction submission fails.
+     *   Retry without relayer configuration to submit direct transaction.
      * @throws {SignatureError} When user rejects the signature request
      * @throws {BlockchainError} When server files and permissions addition fails
-     * @throws {NetworkError} When network communication fails
+     * @throws {NetworkError} When network communication fails.
+     *   Check network connection or configure alternative gateways.
+     *
+     * @example
+     * ```typescript
+     * const result = await vana.permissions.submitAddServerFilesAndPermissions({
+     *   granteeId: BigInt(1),
+     *   grant: "ipfs://QmXxx...",
+     *   fileUrls: ["https://storage.example.com/data.json"],
+     *   schemaIds: [123], // LinkedIn profile schema ID
+     *   serverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
+     *   serverUrl: "https://server.example.com",
+     *   serverPublicKey: serverInfo.public_key,
+     *   filePermissions: [[{
+     *     account: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
+     *     key: encryptedKey
+     *   }]]
+     * });
+     * const events = await result.waitForEvents();
+     * console.log(`Permission ID: ${events.permissionId}`);
+     * ```
      */
-    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams): Promise<Hash>;
+    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams): Promise<TransactionHandle<PermissionGrantResult>>;
     /**
      * Submits an already-signed add server files and permissions transaction to the blockchain.
-     * This method supports both relayer-based gasless transactions and direct transactions.
+     *
+     * @remarks
+     * This method returns a TransactionHandle that provides immediate access to the transaction hash
+     * while allowing lazy-loaded access to parsed event data. Use `waitForEvents()` to retrieve
+     * the permission ID and other event details after transaction confirmation.
      *
      * @param typedData - The EIP-712 typed data for AddServerFilesAndPermissions
      * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
+     * @returns TransactionHandle with immediate hash access and optional event parsing
      * @throws {RelayerError} When gasless transaction submission fails
      * @throws {BlockchainError} When server files and permissions addition fails
      * @throws {NetworkError} When network communication fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await vana.permissions.submitSignedAddServerFilesAndPermissions(
+     *   typedData,
+     *   signature
+     * );
+     * console.log(`Transaction submitted: ${tx.hash}`);
+     *
+     * // Wait for confirmation and get the permission ID
+     * const { permissionId } = await tx.waitForEvents();
+     * console.log(`Permission created with ID: ${permissionId}`);
+     * ```
      */
-    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash): Promise<Hash>;
+    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash): Promise<TransactionHandle<PermissionGrantResult>>;
     /**
      * Submit permission revocation with signature to the blockchain
      *
      * @param permissionId - Permission ID to revoke
      * @returns Promise resolving to transaction hash
      */
-    submitRevokePermission(permissionId: bigint): Promise<Hash>;
+    submitRevokePermission(permissionId: bigint): Promise<TransactionHandle<PermissionRevokeResult>>;
     /**
      * Submits a signed add permission transaction directly to the blockchain.
      *
@@ -30849,10 +31462,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.
@@ -30897,8 +31510,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" },
@@ -30933,7 +31546,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
@@ -30942,8 +31555,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" },
@@ -30958,27 +31571,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.
      *
@@ -31007,27 +31621,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).
@@ -31074,6 +31686,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;
 }
 
 /**
@@ -31115,16 +31734,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
@@ -31143,39 +31762,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
@@ -31186,9 +31801,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
@@ -31204,13 +31819,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
  *
@@ -31219,11 +31845,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
  */
@@ -33714,6 +34340,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.
      *
@@ -33862,12 +34571,25 @@ declare class DataController {
     /**
      * Registers a file URL directly on the blockchain with a schema ID.
      *
-     * @param url - The URL of the file to register
+     * @remarks
+     * This method registers an existing file URL on the DataRegistry contract
+     * with a schema ID, without uploading any data. Useful when you have already
+     * uploaded content to storage and just need to register it on-chain.
+     *
+     * @param url - The URL of the file to register (IPFS or HTTP/HTTPS)
      * @param schemaId - The schema ID to associate with the file
      * @returns Promise resolving to the file ID and transaction hash
-     *
-     * This method registers an existing file URL on the DataRegistry
-     * contract with a schema ID, without uploading any data.
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When wallet address is unavailable - "No addresses available"
+     * @throws {Error} When transaction fails - "Failed to register file with schema"
+     * @example
+     * ```typescript
+     * const { fileId, transactionHash } = await vana.data.registerFileWithSchema(
+     *   "ipfs://QmXxx...",
+     *   1
+     * );
+     * console.log(`File ${fileId} registered with schema in tx ${transactionHash}`);
+     * ```
      */
     registerFileWithSchema(url: string, schemaId: number): Promise<{
         fileId: number;
@@ -33927,35 +34649,112 @@ declare class DataController {
     /**
      * Adds a new refiner to the DataRefinerRegistry.
      *
-     * @param params - Refiner parameters including DLP ID, name, schema ID, and instruction URL
+     * @remarks
+     * Refiners are data processing templates that define how raw data should be
+     * transformed into structured formats. Each refiner is associated with a DLP
+     * (Data Liquidity Pool), has a specific schema for output, and includes
+     * instructions for the refinement process.
+     *
+     * @param params - Refiner configuration parameters
+     * @param params.dlpId - The Data Liquidity Pool ID this refiner belongs to
+     * @param params.name - Human-readable name for the refiner
+     * @param params.schemaId - Schema ID that defines the output format
+     * @param params.refinementInstructionUrl - URL containing processing instructions
      * @returns Promise resolving to the new refiner ID and transaction hash
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When transaction fails - "Failed to add refiner: {error}"
+     * @example
+     * ```typescript
+     * const result = await vana.data.addRefiner({
+     *   dlpId: 1,
+     *   name: "Social Media Sentiment Analyzer",
+     *   schemaId: 42,
+     *   refinementInstructionUrl: "ipfs://QmXxx..."
+     * });
+     * console.log(`Created refiner ${result.refinerId} in tx ${result.transactionHash}`);
+     * ```
      */
     addRefiner(params: AddRefinerParams): Promise<AddRefinerResult>;
     /**
      * Retrieves a refiner by its ID.
      *
-     * @param refinerId - The refiner ID to retrieve
-     * @returns Promise resolving to the refiner information
+     * @remarks
+     * Queries the DataRefinerRegistry contract to get complete information about
+     * a specific refiner including its DLP association, schema, and instructions.
+     *
+     * @param refinerId - The numeric refiner ID to retrieve
+     * @returns Promise resolving to the refiner information object
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When refiner doesn't exist - "Refiner with ID {refinerId} does not exist"
+     * @throws {Error} When contract read fails - "Failed to fetch refiner: {error}"
+     * @example
+     * ```typescript
+     * const refiner = await vana.data.getRefiner(1);
+     * console.log({
+     *   name: refiner.name,
+     *   dlp: refiner.dlpId,
+     *   schema: refiner.schemaId,
+     *   instructions: refiner.refinementInstructionUrl
+     * });
+     * ```
      */
     getRefiner(refinerId: number): Promise<Refiner>;
     /**
      * Validates if a schema ID exists in the registry.
      *
-     * @param schemaId - The schema ID to validate
-     * @returns Promise resolving to boolean indicating if the schema ID is valid
+     * @remarks
+     * Checks the DataRefinerRegistry contract to determine if a given schema ID
+     * has been registered and is available for use.
+     *
+     * @param schemaId - The numeric schema ID to validate
+     * @returns Promise resolving to true if schema exists, false otherwise
+     * @example
+     * ```typescript
+     * const isValid = await vana.data.isValidSchemaId(42);
+     * if (isValid) {
+     *   console.log('Schema 42 is available for use');
+     * } else {
+     *   console.log('Schema 42 does not exist');
+     * }
+     * ```
      */
     isValidSchemaId(schemaId: number): Promise<boolean>;
     /**
      * Gets the total number of refiners in the registry.
      *
+     * @remarks
+     * Queries the DataRefinerRegistry contract to get the total count of all
+     * registered refiners across all DLPs.
+     *
      * @returns Promise resolving to the total refiner count
+     * @example
+     * ```typescript
+     * const count = await vana.data.getRefinersCount();
+     * console.log(`Total refiners registered: ${count}`);
+     * ```
      */
     getRefinersCount(): Promise<number>;
     /**
      * Updates the schema ID for an existing refiner.
      *
-     * @param params - Parameters including refiner ID and new schema ID
+     * @remarks
+     * Allows the owner of a refiner to update its associated schema ID.
+     * This is useful when refiner output format needs to change.
+     *
+     * @param params - Update parameters
+     * @param params.refinerId - The refiner ID to update
+     * @param params.newSchemaId - The new schema ID to set
      * @returns Promise resolving to the transaction hash
+     * @throws {Error} When chain ID is not available - "Chain ID not available"
+     * @throws {Error} When transaction fails - "Failed to update schema ID: {error}"
+     * @example
+     * ```typescript
+     * const result = await vana.data.updateSchemaId({
+     *   refinerId: 1,
+     *   newSchemaId: 55
+     * });
+     * console.log(`Schema updated in tx ${result.transactionHash}`);
+     * ```
      */
     updateSchemaId(params: UpdateSchemaIdParams): Promise<UpdateSchemaIdResult>;
     /**
@@ -34014,24 +34813,47 @@ declare class DataController {
      * console.log(`Transaction: ${result.transactionHash}`);
      * ```
      */
-    addPermissionToFile(fileId: number, account: Address, publicKey: string): Promise<FilePermissionResult>;
+    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<Hash>;
+    submitFilePermission(fileId: number, account: Address, publicKey: string): Promise<TransactionHandle<FilePermissionResult>>;
+    /**
+     * Composes the EIP-712 typed data for FilePermission.
+     *
+     * @param params - The parameters for composing the file permission message
+     * @param params.nonce - The user's nonce for preventing replay attacks
+     * @param params.fileId - The ID of the file to grant permission for
+     * @param params.account - The account address to grant permission to
+     * @param params.encryptedKey - The encrypted key for the permission
+     * @returns Promise resolving to the typed data structure
+     */
+    private composeFilePermissionMessage;
     /**
      * Gets the encrypted key for a specific account's permission to access a file.
      *
@@ -34127,10 +34949,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
@@ -34147,10 +34969,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.
      *
@@ -34180,9 +35002,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
@@ -34198,24 +35020,6 @@ declare class DataController {
      * ```
      */
     fetchAndValidateSchema(url: string): Promise<DataSchema>;
-    /**
-     * Retrieves a schema by ID and fetches its definition URL to get the full data schema.
-     *
-     * @param schemaId - The schema ID to retrieve and validate
-     * @returns The validated data schema
-     * @throws SchemaValidationError if schema is invalid
-     * @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);
-     * }
-     * ```
-     */
-    getValidatedSchema(schemaId: number): Promise<DataSchema>;
 }
 
 /**
@@ -34418,6 +35222,31 @@ interface Chains {
 }
 declare const chains: Chains;
 
+/**
+ * Creates or retrieves a cached public client for blockchain read operations.
+ *
+ * @remarks
+ * This function provides an optimized way to access blockchain data by maintaining
+ * a cached client instance per chain. The client is used for reading contract state,
+ * querying events, and other read-only blockchain operations. It automatically
+ * handles HTTP transport configuration and chain switching.
+ *
+ * @param chainId - The chain ID to connect to (defaults to Moksha testnet)
+ * @returns A public client configured for the specified chain with caching optimization
+ * @throws {Error} When the specified chain ID is not supported by the SDK
+ * @example
+ * ```typescript
+ * // Get client for default chain (Moksha testnet)
+ * const client = createClient();
+ *
+ * // Get client for specific chain
+ * const mainnetClient = createClient(14800);
+ *
+ * // Use client for blockchain reads
+ * const blockNumber = await client.getBlockNumber();
+ * ```
+ * @category Blockchain
+ */
 declare const createClient: (chainId?: keyof typeof chains) => PublicClient & {
     chain: Chain;
 };
@@ -35136,51 +35965,157 @@ declare class SerializationError extends VanaError {
     constructor(message: string);
 }
 /**
- * Error thrown when a signature operation fails.
+ * Thrown when a signature operation fails or cannot be completed.
  *
  * @remarks
- * Recovery strategies: Check wallet connection and account unlock status,
- * retry operation with explicit user interaction, or for gasless operations
- * consider switching to direct transactions.
+ * This error occurs when wallet signature operations fail due to disconnection,
+ * locked accounts, or other wallet-related issues. It preserves the original
+ * error for debugging while providing consistent error handling across the SDK.
+ *
+ * Recovery strategies:
+ * - Check wallet connection and account unlock status
+ * - Retry operation with explicit user interaction
+ * - For gasless operations, consider switching to direct transactions
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await vana.permissions.grant({ grantee: '0x...' });
+ * } catch (error) {
+ *   if (error instanceof SignatureError) {
+ *     // Prompt user to unlock wallet
+ *     await promptWalletUnlock();
+ *     // Retry operation
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class SignatureError extends VanaError {
     readonly originalError?: Error | undefined;
     constructor(message: string, originalError?: Error | undefined);
 }
 /**
- * Error thrown when a network operation fails.
+ * Thrown when network communication fails during API calls or blockchain interactions.
  *
  * @remarks
- * Recovery strategies: Check network connectivity, retry with exponential backoff,
- * verify API endpoints are accessible, or switch to alternative network providers.
+ * This error encompasses network connectivity issues, API unavailability,
+ * timeout errors, and CORS restrictions. It's commonly encountered during
+ * IPFS operations, subgraph queries, or RPC calls.
+ *
+ * Recovery strategies:
+ * - Check network connectivity
+ * - Retry with exponential backoff
+ * - Verify API endpoints are accessible
+ * - Switch to alternative network providers or gateways
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const files = await vana.data.getUserFiles({ owner: '0x...' });
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     // Implement retry with exponential backoff
+ *     await retryWithBackoff(() => vana.data.getUserFiles({ owner: '0x...' }));
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class NetworkError extends VanaError {
     readonly originalError?: Error | undefined;
     constructor(message: string, originalError?: Error | undefined);
 }
 /**
- * Error thrown when the nonce retrieval fails.
+ * Thrown when transaction nonce retrieval fails during gasless operations.
  *
  * @remarks
- * Recovery strategies: Retry nonce retrieval after brief delay, check wallet connection
- * and account status, or use manual nonce specification if supported by the operation.
+ * This error occurs when the SDK cannot retrieve the user's current nonce from
+ * smart contracts, preventing gasless transaction submission. Nonces are critical
+ * for preventing replay attacks in signed transactions.
+ *
+ * Recovery strategies:
+ * - Retry nonce retrieval after brief delay
+ * - Check wallet connection and account status
+ * - Use manual nonce specification if supported by the operation
+ * - Switch to direct transactions as fallback
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await vana.permissions.grant({ grantee: '0x...' });
+ * } catch (error) {
+ *   if (error instanceof NonceError) {
+ *     // Wait and retry
+ *     await delay(1000);
+ *     await vana.permissions.grant({ grantee: '0x...' });
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class NonceError extends VanaError {
     constructor(message: string);
 }
 /**
- * Error thrown when a personal server operation fails.
+ * Thrown when personal server operations fail or cannot be completed.
  *
  * @remarks
- * Recovery strategies: Verify server URL accessibility, check server trust status via
- * `vana.permissions.getUserTrustedServers()`, or retry after server becomes available.
+ * This error occurs during interactions with personal servers for computation
+ * requests, identity retrieval, or operation status checks. Common causes include
+ * server unavailability, untrusted server status, or invalid permission grants.
+ *
+ * Recovery strategies:
+ * - Verify server URL accessibility
+ * - Check server trust status via `vana.permissions.getTrustedServers()`
+ * - Ensure valid permissions exist for the operation
+ * - Retry after server becomes available
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await vana.server.createOperation({ permissionId: 123 });
+ * } catch (error) {
+ *   if (error instanceof PersonalServerError) {
+ *     // Check if server is trusted
+ *     const trustedServers = await vana.permissions.getTrustedServers();
+ *     if (!trustedServers.includes(serverId)) {
+ *       await vana.permissions.trustServer({ serverId });
+ *     }
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class PersonalServerError extends VanaError {
     readonly originalError?: Error | undefined;
     constructor(message: string, originalError?: Error | undefined);
 }
 /**
- * Error thrown when trying to register a server with a URL that doesn't match the existing registration.
+ * Thrown when attempting to register a server with a URL different from its existing registration.
+ *
+ * @remarks
+ * This error occurs when trying to add or trust a server that's already registered
+ * on-chain with a different URL. Server URLs are immutable once registered to
+ * maintain consistency and security. Applications should use the existing URL
+ * or register a new server with a different ID.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await vana.permissions.addAndTrustServer({
+ *     serverId: 1,
+ *     serverUrl: 'https://new-url.com',
+ *     publicKey: '0x...'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ServerUrlMismatchError) {
+ *     console.log(`Server already registered with: ${error.existingUrl}`);
+ *     // Use existing URL or register new server
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class ServerUrlMismatchError extends VanaError {
     constructor(existingUrl: string, providedUrl: string, serverId: string);
@@ -35189,7 +36124,25 @@ declare class ServerUrlMismatchError extends VanaError {
     readonly serverId: string;
 }
 /**
- * Error thrown when a permission operation fails.
+ * Thrown when permission grant, revoke, or validation operations fail.
+ *
+ * @remarks
+ * This error occurs during permission management operations including grants,
+ * revocations, and permission validation checks. Common causes include invalid
+ * grantee addresses, expired permissions, or insufficient privileges.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await vana.permissions.revoke({ permissionId: 999999 });
+ * } catch (error) {
+ *   if (error instanceof PermissionError) {
+ *     console.error('Permission operation failed:', error.message);
+ *     // Permission may not exist or user may not be owner
+ *   }
+ * }
+ * ```
+ * @category Error Handling
  */
 declare class PermissionError extends VanaError {
     readonly originalError?: Error | undefined;
@@ -36197,21 +37150,53 @@ declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: stri
 
 declare const CONTRACT_ADDRESSES: Record<number, Record<string, string>>;
 /**
- * Retrieves the deployed contract address for a specific contract on a given chain.
+ * Retrieves the deployed contract address for a specific Vana protocol contract on a given chain.
  *
- * @param chainId - The chain ID to look up the contract on
- * @param contract - The contract name to get the address for
- * @returns The contract address as a hex string
- * @throws {Error} When contract address not found for the specified contract and chain
+ * @remarks
+ * This function provides type-safe access to contract addresses across all supported Vana networks.
+ * It automatically searches both current and legacy contract registries to ensure backwards
+ * compatibility while providing clear error messages for unsupported combinations.
+ *
+ * The function validates that both the chain ID and contract name are supported before
+ * attempting address lookup, helping developers identify deployment or configuration issues
+ * early in the development process.
+ *
+ * **Supported Chains:**
+ * - 14800: Vana Mainnet
+ * - 1480: Moksha Testnet
+ *
+ * **Contract Categories:**
+ * - Data Management: DataRegistry, DataRefinerRegistry
+ * - Permissions: DataPortabilityPermissions, DataPortabilityServers, DataPortabilityGrantees
+ * - Computing: TeePoolPhala, TeePoolDedicatedGpu, etc.
+ * - Token & Governance: DATImplementation, VanaPoolStaking, etc.
+ *
+ * @param chainId - The chain ID to look up the contract on (14800 for mainnet, 1480 for testnet)
+ * @param contract - The contract name to get the address for (use TypeScript autocomplete for available options)
+ * @returns The contract address as a checksummed hex string (0x...)
+ * @throws {Error} When contract address not found for the specified contract and chain combination.
+ *   This typically indicates the contract is not deployed on the requested network.
  * @example
  * ```typescript
+ * // Get core protocol contract addresses
+ * const dataRegistry = getContractAddress(14800, 'DataRegistry');
+ * const permissions = getContractAddress(14800, 'DataPortabilityPermissions');
+ * const trustedServers = getContractAddress(14800, 'DataPortabilityServers');
+ *
+ * // Handle unsupported combinations gracefully
  * try {
- *   const dataRegistryAddress = getContractAddress(1480, 'DataRegistry');
- *   console.log('DataRegistry address:', dataRegistryAddress);
+ *   const address = getContractAddress(1480, 'DataRegistry');
+ *   console.log('DataRegistry testnet address:', address);
  * } catch (error) {
- *   console.error('Contract not deployed on this chain:', error.message);
+ *   console.error('Contract not available on testnet:', error.message);
+ *   // Fallback to mainnet or show user-friendly error
  * }
+ *
+ * // TypeScript provides autocomplete for contract names
+ * const poolAddress = getContractAddress(14800, 'TeePoolPhala'); // ✅ Valid
+ * // const invalid = getContractAddress(14800, 'InvalidContract'); // ❌ TypeScript error
  * ```
+ * @category Configuration
  */
 declare const getContractAddress: (chainId: keyof typeof CONTRACT_ADDRESSES, contract: VanaContract) => `0x${string}`;
 
@@ -36729,4 +37714,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, 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 FilePermissionInput, type FilePermissionParams, type FilePermissionTypedData, 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 };