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

package/dist/index.node.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';
 
@@ -157,6 +157,14 @@ declare class StorageError extends Error {
     });
 }
 
+/**
+ * Base interface for types that need to be compatible with Record<string, unknown>
+ *
+ * @category Permissions
+ */
+interface RecordCompatible {
+    [key: string]: unknown;
+}
 /**
  * Represents on-chain permission grant data without expensive off-chain resolution.
  *
@@ -355,7 +363,7 @@ interface PermissionGrantMessage {
  *
  * @category Permissions
  */
-interface PermissionInputMessage {
+interface PermissionInputMessage extends RecordCompatible {
     /** Nonce */
     nonce: bigint;
     /** Grantee ID */
@@ -370,7 +378,7 @@ interface PermissionInputMessage {
  *
  * @category Permissions
  */
-interface RevokePermissionInput {
+interface RevokePermissionInput extends RecordCompatible {
     /** Nonce */
     nonce: bigint;
     /** Permission ID to revoke */
@@ -451,9 +459,7 @@ interface GrantFile {
  *
  * @category Permissions
  */
-interface PermissionGrantTypedData {
-    /** EIP-712 domain */
-    domain: PermissionGrantDomain;
+interface PermissionGrantTypedData extends GenericTypedData {
     /** EIP-712 types */
     types: {
         Permission: Array<{
@@ -471,7 +477,7 @@ interface PermissionGrantTypedData {
  *
  * @category Permissions
  */
-interface GenericTypedData {
+interface GenericTypedData extends RecordCompatible {
     /** EIP-712 domain */
     domain: PermissionGrantDomain;
     /** EIP-712 types */
@@ -665,7 +671,7 @@ interface UntrustServerParams {
  *
  * @category Permissions
  */
-interface AddAndTrustServerInput {
+interface AddAndTrustServerInput extends RecordCompatible {
     /** User nonce */
     nonce: bigint;
     /** Server address */
@@ -681,7 +687,7 @@ interface AddAndTrustServerInput {
  * @category Permissions
  * @deprecated Use AddAndTrustServerInput instead
  */
-interface TrustServerInput {
+interface TrustServerInput extends RecordCompatible {
     /** User nonce */
     nonce: bigint;
     /** Server ID (numeric) */
@@ -692,7 +698,7 @@ interface TrustServerInput {
  *
  * @category Permissions
  */
-interface UntrustServerInput {
+interface UntrustServerInput extends RecordCompatible {
     /** User nonce */
     nonce: bigint;
     /** Server ID (numeric) */
@@ -703,9 +709,7 @@ interface UntrustServerInput {
  *
  * @category Permissions
  */
-interface AddAndTrustServerTypedData {
-    /** EIP-712 domain */
-    domain: PermissionGrantDomain;
+interface AddAndTrustServerTypedData extends GenericTypedData {
     /** EIP-712 types */
     types: {
         AddServer: Array<{
@@ -724,9 +728,7 @@ interface AddAndTrustServerTypedData {
  * @category Permissions
  * @deprecated Use AddAndTrustServerTypedData instead
  */
-interface TrustServerTypedData {
-    /** EIP-712 domain */
-    domain: PermissionGrantDomain;
+interface TrustServerTypedData extends GenericTypedData {
     /** EIP-712 types */
     types: {
         TrustServer: Array<{
@@ -744,9 +746,7 @@ interface TrustServerTypedData {
  *
  * @category Permissions
  */
-interface UntrustServerTypedData {
-    /** EIP-712 domain */
-    domain: PermissionGrantDomain;
+interface UntrustServerTypedData extends GenericTypedData {
     /** EIP-712 types */
     types: {
         UntrustServer: Array<{
@@ -903,7 +903,7 @@ interface RegisterGranteeParams {
  *
  * @category Permissions
  */
-interface RegisterGranteeInput extends Record<string, unknown> {
+interface RegisterGranteeInput extends RecordCompatible {
     /** User nonce */
     nonce: bigint;
     /** Grantee owner address */
@@ -918,9 +918,7 @@ interface RegisterGranteeInput extends Record<string, unknown> {
  *
  * @category Permissions
  */
-interface RegisterGranteeTypedData {
-    /** EIP-712 domain */
-    domain: PermissionGrantDomain;
+interface RegisterGranteeTypedData extends GenericTypedData {
     /** EIP-712 types */
     types: {
         RegisterGrantee: Array<{
@@ -986,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 */
@@ -1011,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 */
@@ -2184,8 +2186,8 @@ interface Schema {
     id: number;
     /** Schema name */
     name: string;
-    /** Schema type */
-    type: string;
+    /** Schema dialect */
+    dialect: string;
     /** URL containing the schema definition */
     definitionUrl: string;
 }
@@ -2216,8 +2218,8 @@ interface Refiner {
 interface AddSchemaParams {
     /** Schema name */
     name: string;
-    /** Schema type */
-    type: string;
+    /** Schema dialect */
+    dialect: string;
     /** URL containing the schema definition */
     definitionUrl: string;
 }
@@ -2292,13 +2294,7 @@ interface UpdateSchemaIdResult {
     transactionHash: Hash;
 }
 /**
- * Query mode for trusted server retrieval
- *
- * @category Data Management
- */
-type TrustedServerQueryMode = "subgraph" | "rpc" | "auto";
-/**
- * Trusted server data structure (unified format for both subgraph and RPC modes)
+ * Trusted server data structure
  *
  * @category Data Management
  */
@@ -2317,39 +2313,20 @@ interface TrustedServer {
     trustIndex?: number;
 }
 /**
- * Parameters for getUserTrustedServers with dual-mode support
+ * Parameters for getUserTrustedServers method
  *
  * @category Data Management
  */
 interface GetUserTrustedServersParams {
-    /** User address to query */
+    /** User address to query trusted servers for */
     user: Address;
-    /** Query mode: 'subgraph' (fast, requires subgraph), 'rpc' (direct contract), or 'auto' (tries subgraph first) */
-    mode?: TrustedServerQueryMode;
-    /** Subgraph URL (required for subgraph mode) */
+    /** Optional subgraph URL to override default */
     subgraphUrl?: string;
-    /** Pagination limit (applies to RPC mode) */
+    /** Maximum number of results */
     limit?: number;
-    /** Pagination offset (applies to RPC mode) */
+    /** Number of results to skip */
     offset?: number;
 }
-/**
- * Result of getUserTrustedServers query
- *
- * @category Data Management
- */
-interface GetUserTrustedServersResult {
-    /** Array of trusted servers */
-    servers: TrustedServer[];
-    /** Query mode that was actually used */
-    usedMode: TrustedServerQueryMode;
-    /** Total count (only available in RPC mode) */
-    total?: number;
-    /** Whether there are more servers (pagination info for RPC mode) */
-    hasMore?: boolean;
-    /** Any warnings or fallback information */
-    warnings?: string[];
-}
 
 declare const contractAbis: {
     readonly DataPortabilityPermissions: readonly [{
@@ -2468,6 +2445,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";
@@ -2744,6 +2733,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";
@@ -3726,7 +3719,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";
@@ -4114,6 +4107,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 [{
@@ -28737,6 +28744,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: "FileAdded";
+    };
+    readonly addFileWithPermissionsAndSchema: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAdded";
+    };
+    readonly addFileWithSchema: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAdded";
+    };
+    readonly addFileWithPermissions: {
+        readonly contract: "DataRegistry";
+        readonly event: "FileAdded";
+    };
+    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.
@@ -28774,6 +28870,62 @@ 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 addition operation.
+ * Contains data from the FileAdded blockchain event.
+ */
+interface FileAddedResult extends BaseTransactionResult {
+    /** Unique file ID assigned by the registry */
+    fileId: bigint;
+    /** Address of the file owner */
+    ownerAddress: Address;
+    /** URL where the file is stored */
+    url: string;
+}
 /**
  * Result of a successful file permission addition operation.
  * Contains data from the FilePermissionAdded blockchain event.
@@ -28787,6 +28939,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
  *
@@ -29825,30 +30051,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.
      *
@@ -29876,15 +30103,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;
     /**
@@ -29940,49 +30173,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;
     /**
@@ -30029,19 +30319,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
      *
@@ -30066,6 +30370,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.
@@ -30081,6 +30397,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.
@@ -30096,6 +30422,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).
@@ -30117,6 +30453,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
@@ -30222,7 +30559,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).
      *
@@ -30230,14 +30567,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).
      *
@@ -30251,13 +30588,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.
@@ -30287,7 +30635,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).
      *
@@ -30300,7 +30648,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.
      *
@@ -30351,22 +30699,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
      */
@@ -30448,7 +30834,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)
      *
@@ -30464,7 +30850,7 @@ declare class PermissionsController {
      * });
      * ```
      */
-    submitRegisterGranteeWithSignature(params: RegisterGranteeParams): Promise<Hash>;
+    submitRegisterGranteeWithSignature(params: RegisterGranteeParams): Promise<TransactionHandle<GranteeRegisterResult>>;
     /**
      * Submits a signed register grantee transaction via relayer
      *
@@ -30477,7 +30863,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.
      *
@@ -30764,7 +31150,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
      *
@@ -30804,49 +31190,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.
      *
@@ -30988,33 +31431,52 @@ declare class SchemaController {
      * Retrieves a schema by its ID.
      *
      * @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
      * @example
      * ```typescript
      * const schema = await vana.schemas.get(1);
      * console.log(`Schema: ${schema.name} (${schema.type})`);
+     *
+     * // With custom subgraph
+     * const schema = await vana.schemas.get(1, {
+     *   subgraphUrl: 'https://custom-subgraph.com/graphql'
+     * });
      * ```
      */
-    get(schemaId: number): Promise<Schema>;
+    get(schemaId: number, options?: {
+        subgraphUrl?: string;
+    }): Promise<Schema>;
     /**
      * Gets the total number of schemas registered on the network.
      *
+     * @param options - Optional parameters
+     * @param options.subgraphUrl - Custom subgraph URL to use instead of default
      * @returns Promise resolving to the total schema count
      * @throws {Error} When the count cannot be retrieved
      * @example
      * ```typescript
      * const count = await vana.schemas.count();
      * console.log(`Total schemas: ${count}`);
+     *
+     * // With custom subgraph
+     * const count = await vana.schemas.count({
+     *   subgraphUrl: 'https://custom-subgraph.com/graphql'
+     * });
      * ```
      */
-    count(): Promise<number>;
+    count(options?: {
+        subgraphUrl?: string;
+    }): Promise<number>;
     /**
      * Lists all schemas with pagination.
      *
      * @param options - Optional parameters for listing schemas
      * @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
      * @returns Promise resolving to an array of schemas
      * @example
      * ```typescript
@@ -31023,11 +31485,19 @@ declare class SchemaController {
      *
      * // 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;
     }): Promise<Schema[]>;
     /**
      * Adds a schema using the legacy method (low-level API).
@@ -31037,6 +31507,36 @@ declare class SchemaController {
      * @returns Promise resolving to the add schema result
      */
     addSchema(params: AddSchemaParams): Promise<AddSchemaResult>;
+    /**
+     * Internal method: Query schema via subgraph
+     *
+     * @param params - Query parameters
+     * @param params.schemaId - The ID of the schema to retrieve
+     * @param params.subgraphUrl - The subgraph URL to query
+     * @returns Promise resolving to the schema object
+     * @private
+     */
+    private _getSchemaViaSubgraph;
+    /**
+     * Internal method: List schemas via subgraph
+     *
+     * @param params - Query parameters
+     * @param params.limit - Maximum number of schemas to return
+     * @param params.offset - Number of schemas to skip
+     * @param params.subgraphUrl - The subgraph URL to query
+     * @returns Promise resolving to an array of schemas
+     * @private
+     */
+    private _listSchemasViaSubgraph;
+    /**
+     * Internal method: Count schemas via subgraph
+     *
+     * @param params - Query parameters
+     * @param params.subgraphUrl - The subgraph URL to query
+     * @returns Promise resolving to the total schema count
+     * @private
+     */
+    private _countSchemasViaSubgraph;
     /**
      * Gets the user's wallet address.
      *
@@ -33685,19 +34185,18 @@ declare class DataController {
         subgraphUrl?: string;
     }): Promise<UserFile$1[]>;
     /**
-     * Retrieves a list of permissions granted by a user using the new subgraph entities.
+     * Retrieves a list of permissions granted by a user.
      *
-     * This method queries the Vana subgraph to find permissions directly granted by the user
-     * using the new Permission entity. It efficiently handles millions of permissions by:
-     * 1. Querying the subgraph for user's directly granted permissions
-     * 2. Returning complete permission information from subgraph
-     * 3. No need for additional contract calls as all data comes from subgraph
+     * This method supports automatic fallback between subgraph and RPC modes:
+     * - If subgraph URL is available, tries subgraph query first
+     * - Falls back to direct contract queries via RPC if subgraph fails
+     * - RPC mode uses gasAwareMulticall for efficient batch queries
      *
      * @param params - Object containing the user address and optional subgraph URL
      * @param params.user - The wallet address of the user to query permissions for
      * @param params.subgraphUrl - Optional subgraph URL to override the default
      * @returns Promise resolving to an array of permission objects
-     * @throws Error if subgraph is unavailable or returns invalid data
+     * @throws Error if both subgraph and RPC queries fail
      */
     getUserPermissions(params: {
         user: Address;
@@ -33713,43 +34212,59 @@ declare class DataController {
         user: Address;
     }>>;
     /**
-     * Retrieves a list of trusted servers for a user using the new subgraph entities.
+     * Internal method: Query user permissions via subgraph
+     *
+     * @param params - Query parameters object
+     * @param params.user - The user address to query permissions for
+     * @param params.subgraphUrl - The subgraph URL endpoint to query
+     * @returns Promise resolving to an array of permission objects
+     */
+    private _getUserPermissionsViaSubgraph;
+    /**
+     * Internal method: Query user permissions via direct RPC
      *
-     * This method queries the Vana subgraph to find trusted servers directly associated with the user
-     * with support for both subgraph and direct RPC queries.
+     * @param params - Query parameters object
+     * @param params.user - The user address to query permissions for
+     * @returns Promise resolving to an array of permission objects
+     */
+    private _getUserPermissionsViaRpc;
+    /**
+     * Retrieves a list of trusted servers for a user.
      *
-     * This method supports multiple query modes:
-     * - 'subgraph': Fast query via subgraph (requires subgraphUrl)
-     * - 'rpc': Direct contract queries (slower but no external dependencies)
-     * - 'auto': Try subgraph first, fallback to RPC if unavailable
+     * This method supports automatic fallback between subgraph and RPC modes:
+     * - If subgraph URL is available, tries subgraph query first for fast results
+     * - Falls back to direct contract queries via RPC if subgraph fails
+     * - RPC mode uses gasAwareMulticall for efficient batch queries
      *
-     * @param params - Query parameters including user address and mode selection
-     * @returns Promise resolving to trusted servers with metadata about the query
-     * @throws Error if query fails in both modes (when using 'auto')
+     * @param params - Query parameters including user address and optional pagination
+     * @param params.user - The wallet address of the user to query trusted servers for
+     * @param params.subgraphUrl - Optional subgraph URL to override the default
+     * @param params.limit - Maximum number of results to return (default: 50)
+     * @param params.offset - Number of results to skip for pagination (default: 0)
+     * @returns Promise resolving to an array of trusted server objects
+     * @throws Error if both subgraph and RPC queries fail
      * @example
      * ```typescript
-     * // Use subgraph for fast queries
-     * const result = await vana.data.getUserTrustedServers({
-     *   user: '0x...',
-     *   mode: 'subgraph',
-     *   subgraphUrl: 'https://...'
+     * // Basic usage with automatic fallback
+     * const servers = await vana.data.getUserTrustedServers({
+     *   user: '0x...'
      * });
      *
-     * // Use direct RPC (no external dependencies)
-     * const result = await vana.data.getUserTrustedServers({
+     * // With pagination
+     * const servers = await vana.data.getUserTrustedServers({
      *   user: '0x...',
-     *   mode: 'rpc',
-     *   limit: 10
+     *   limit: 10,
+     *   offset: 20
      * });
      *
-     * // Auto-fallback mode
-     * const result = await vana.data.getUserTrustedServers({
+     * // With custom subgraph URL
+     * const servers = await vana.data.getUserTrustedServers({
      *   user: '0x...',
-     *   mode: 'auto' // tries subgraph first, falls back to RPC
+     *   subgraphUrl: 'https://custom-subgraph.com/graphql'
      * });
      * ```
      */
-    getUserTrustedServers(params: GetUserTrustedServersParams): Promise<GetUserTrustedServersResult>;
+    getUserTrustedServers(params: GetUserTrustedServersParams): Promise<TrustedServer[]>;
     /**
      * Internal method: Query trusted servers via subgraph
      *
@@ -33814,75 +34329,28 @@ declare class DataController {
      * for specific files by ID.
      */
     getFileById(fileId: number): Promise<UserFile$1>;
-    /**
-     * Uploads an encrypted file to storage and registers it on the blockchain.
-     *
-     * @deprecated Since v2.0.0 - Use vana.data.upload() instead for the high-level API with automatic encryption
-     *
-     * Migration guide:
-     * ```typescript
-     * // Old way (deprecated):
-     * const encrypted = await encryptBlob(data, key);
-     * const result = await vana.data.uploadEncryptedFile(encrypted, filename);
-     *
-     * // New way:
-     * const result = await vana.data.upload({
-     *   content: data,
-     *   filename: filename,
-     *   encrypt: true  // Handles encryption automatically
-     * });
-     * ```
-     * @param encryptedFile - The encrypted file blob to upload
-     * @param filename - Optional filename for the upload
-     * @param providerName - Optional storage provider to use
-     * @returns Promise resolving to upload result with file ID and storage URL
-     *
-     * This method handles the complete flow of:
-     * 1. Uploading the encrypted file to the specified storage provider
-     * 2. Registering the file URL on the DataRegistry contract via relayer
-     * 3. Returning the assigned file ID and storage URL
-     */
-    uploadEncryptedFile(encryptedFile: Blob, filename?: string, providerName?: string): Promise<UploadEncryptedFileResult>;
-    /**
-     * Uploads an encrypted file to storage and registers it on the blockchain with a schema.
-     *
-     * @deprecated Since v2.0.0 - Use vana.data.upload() instead for the high-level API with automatic encryption and schema validation
-     *
-     * Migration guide:
-     * ```typescript
-     * // Old way (deprecated):
-     * const encrypted = await encryptBlob(data, key);
-     * const result = await vana.data.uploadEncryptedFileWithSchema(encrypted, schemaId, filename);
-     *
-     * // New way:
-     * const result = await vana.data.upload({
-     *   content: data,
-     *   filename: filename,
-     *   schemaId: schemaId,  // Automatic validation
-     *   encrypt: true
-     * });
-     * ```
-     * @param encryptedFile - The encrypted file blob to upload
-     * @param schemaId - The schema ID to associate with the file
-     * @param filename - Optional filename for the upload
-     * @param providerName - Optional storage provider to use
-     * @returns Promise resolving to upload result with file ID and storage URL
-     *
-     * This method handles the complete flow of:
-     * 1. Uploading the encrypted file to the specified storage provider
-     * 2. Registering the file URL on the DataRegistry contract with a schema ID
-     * 3. Returning the assigned file ID and storage URL
-     */
-    uploadEncryptedFileWithSchema(encryptedFile: Blob, schemaId: number, filename?: string, providerName?: string): Promise<UploadEncryptedFileResult>;
     /**
      * 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;
@@ -33940,95 +34408,114 @@ declare class DataController {
         transactionHash: string;
     }>;
     /**
-     * Adds a new schema to the DataRefinerRegistry.
-     *
-     * @deprecated Since v2.0.0 - Use vana.schemas.create() instead for the high-level API with automatic IPFS upload
+     * Adds a new refiner to the DataRefinerRegistry.
      *
-     * Migration guide:
+     * @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
-     * // Old way (deprecated):
-     * const result = await vana.data.addSchema({
-     *   name: "UserProfile",
-     *   type: "JSON",
-     *   definitionUrl: "ipfs://..."
-     * });
-     *
-     * // New way:
-     * const result = await vana.schemas.create({
-     *   name: "UserProfile",
-     *   type: "JSON",
-     *   definition: schemaObject  // Automatically uploads to IPFS
+     * 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}`);
      * ```
-     * @param params - Schema parameters including name, type, and definition URL
-     * @returns Promise resolving to the new schema ID and transaction hash
      */
-    addSchema(params: AddSchemaParams): Promise<AddSchemaResult>;
+    addRefiner(params: AddRefinerParams): Promise<AddRefinerResult>;
     /**
-     * Retrieves a schema by its ID.
+     * Retrieves a refiner by its ID.
      *
-     * @deprecated Since v2.0.0 - Use vana.schemas.get() instead
+     * @remarks
+     * Queries the DataRefinerRegistry contract to get complete information about
+     * a specific refiner including its DLP association, schema, and instructions.
      *
-     * Migration guide:
+     * @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
-     * // Old way (deprecated):
-     * const schema = await vana.data.getSchema(schemaId);
-     *
-     * // New way:
-     * const schema = await vana.schemas.get(schemaId);
+     * const refiner = await vana.data.getRefiner(1);
+     * console.log({
+     *   name: refiner.name,
+     *   dlp: refiner.dlpId,
+     *   schema: refiner.schemaId,
+     *   instructions: refiner.refinementInstructionUrl
+     * });
      * ```
-     * @param schemaId - The schema ID to retrieve
-     * @returns Promise resolving to the schema information
      */
-    getSchema(schemaId: number): Promise<Schema>;
+    getRefiner(refinerId: number): Promise<Refiner>;
     /**
-     * Gets the total number of schemas in the registry.
+     * Validates if a schema ID exists in the registry.
      *
-     * @deprecated Since v2.0.0 - Use vana.schemas.count() instead
+     * @remarks
+     * Checks the DataRefinerRegistry contract to determine if a given schema ID
+     * has been registered and is available for use.
      *
-     * Migration guide:
+     * @param schemaId - The numeric schema ID to validate
+     * @returns Promise resolving to true if schema exists, false otherwise
+     * @example
      * ```typescript
-     * // Old way (deprecated):
-     * const count = await vana.data.getSchemasCount();
-     *
-     * // New way:
-     * const count = await vana.schemas.count();
+     * 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');
+     * }
      * ```
-     * @returns Promise resolving to the total schema count
-     */
-    getSchemasCount(): Promise<number>;
-    /**
-     * Adds a new refiner to the DataRefinerRegistry.
-     *
-     * @param params - Refiner parameters including DLP ID, name, schema ID, and instruction URL
-     * @returns Promise resolving to the new refiner ID and transaction hash
-     */
-    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
-     */
-    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
      */
     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>;
     /**
@@ -34050,6 +34537,17 @@ declare class DataController {
         account: Address;
         publicKey: string;
     }>, filename?: string, providerName?: string): Promise<UploadEncryptedFileResult>;
+    /**
+     * Uploads content to storage without registering it on the blockchain.
+     * This method only handles the storage upload and returns the file URL.
+     *
+     * @param content - The content to upload (string, Blob, Buffer, or object - objects will be JSON stringified)
+     * @param filename - Optional filename for the uploaded file (defaults to timestamp-based name)
+     * @param encrypt  - Optional flag to encrypt the content before upload
+     * @param providerName - Optional specific storage provider to use
+     * @returns Promise resolving to the storage upload result with url, size, and contentType
+     */
+    uploadToStorage(content: string | Blob | Buffer | object, filename?: string, encrypt?: boolean, providerName?: string): Promise<StorageUploadResult>;
     /**
      * Adds a permission for a party to access an existing file.
      *
@@ -34076,7 +34574,7 @@ 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.
      *
@@ -34093,7 +34591,7 @@ declare class DataController {
      * console.log(`Transaction submitted: ${txHash}`);
      * ```
      */
-    submitFilePermission(fileId: number, account: Address, publicKey: string): Promise<Hash>;
+    submitFilePermission(fileId: number, account: Address, publicKey: string): Promise<TransactionHandle<FilePermissionResult>>;
     /**
      * Gets the encrypted key for a specific account's permission to access a file.
      *
@@ -34480,6 +34978,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;
 };
@@ -35198,51 +35721,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);
@@ -35251,7 +35880,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;
@@ -36259,21 +36906,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}`;
 
@@ -36443,6 +37122,8 @@ declare class CircuitBreaker {
     reset(): void;
 }
 
+/** Union type of all possible transaction results from relayer operations */
+type RelayerTransactionResult = PermissionGrantResult | PermissionRevokeResult | ServerTrustResult | ServerUntrustResult | GranteeRegisterResult | FileAddedResult;
 /**
  * Payload structure for relayer requests.
  * Contains the EIP-712 typed data, signature, and optional expected user address for security verification.
@@ -36464,7 +37145,7 @@ interface RelayerRequestPayload {
  * 1. Verifies the signature against the typed data
  * 2. Optionally checks the signer matches the expected user address
  * 3. Routes to the appropriate SDK method based on primaryType
- * 4. Returns the resulting transaction hash
+ * 4. Returns the transaction handle with hash and event parsing capability
  *
  * Supported transaction types:
  * - Permission: Permission grants
@@ -36477,7 +37158,7 @@ interface RelayerRequestPayload {
  *
  * @param sdk - Initialized Vana SDK instance
  * @param payload - Request payload containing typed data, signature, and optional security check
- * @returns Promise resolving to the transaction hash
+ * @returns Promise resolving to TransactionHandle with hash and event parsing capability
  * @throws {SignatureError} When signature verification fails or signer mismatch occurs
  * @throws {Error} When primaryType is unsupported or SDK operations fail
  * @category Server
@@ -36491,15 +37172,24 @@ interface RelayerRequestPayload {
  *     const body = await request.json();
  *     const vana = await createRelayerVana();
  *
- *     const txHash = await handleRelayerRequest(vana, {
+ *     const tx = await handleRelayerRequest(vana, {
  *       typedData: body.typedData,
  *       signature: body.signature,
  *       expectedUserAddress: body.expectedUserAddress
  *     });
  *
+ *     // Option 1: Return just the hash immediately
  *     return NextResponse.json({
  *       success: true,
- *       transactionHash: txHash
+ *       transactionHash: tx.hash
+ *     });
+ *
+ *     // Option 2: Wait for transaction confirmation and return event data
+ *     const eventData = await tx.waitForEvents();
+ *     return NextResponse.json({
+ *       success: true,
+ *       transactionHash: tx.hash,
+ *       ...eventData // Include parsed event data like permissionId, fileId, etc.
  *     });
  *   } catch (error) {
  *     return NextResponse.json({
@@ -36510,13 +37200,14 @@ interface RelayerRequestPayload {
  * }
  * ```
  */
-declare function handleRelayerRequest(sdk: VanaInstance, payload: RelayerRequestPayload): Promise<Hash>;
+declare function handleRelayerRequest(sdk: VanaInstance, payload: RelayerRequestPayload): Promise<TransactionHandle<RelayerTransactionResult>>;
 
 /**
  * Node.js implementation of the Vana Platform Adapter
  *
- * This implementation uses Node.js-specific libraries and configurations
- * to provide crypto, PGP, and HTTP functionality.
+ * WARNING: Dependencies that access globals during init
+ * MUST be dynamically imported to support Turbopack.
+ * See: https://github.com/vercel/next.js/issues/82632
  */
 
 /**
@@ -36536,6 +37227,10 @@ declare class NodePlatformAdapter implements VanaPlatformAdapter {
  *
  * This implementation uses browser-compatible libraries and configurations
  * to provide crypto, PGP, and HTTP functionality without Node.js dependencies.
+ *
+ * WARNING: Dependencies that access globals during init
+ * MUST be dynamically imported to support Turbopack.
+ * See: https://github.com/vercel/next.js/issues/82632
  */
 
 /**
@@ -36924,4 +37619,4 @@ declare function Vana(config: VanaConfig): VanaNodeImpl;
  */
 type VanaInstance = VanaNodeImpl;
 
-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, type GetUserTrustedServersResult, 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, NodePlatformAdapter, 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 RelayerRequestPayload, 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, SchemaController, 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 TrustedServerQueryMode, 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, 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, VanaNodeImpl, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createNodePlatformAdapter, createPlatformAdapter, createPlatformAdapterFor, 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, handleRelayerRequest, 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 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, NodePlatformAdapter, 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 RelayerRequestPayload, 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, SchemaController, 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, 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, VanaNodeImpl, type VanaPlatformAdapter, type WalletConfig, type WalletConfigWithStorage, __contractCache, chains, checkGrantAccess, clearContractCache, type components, convertIpfsUrl, convertIpfsUrlWithFallbacks, createAndStoreGrant, createBrowserPlatformAdapter, createGrantFile, createNodePlatformAdapter, createPlatformAdapter, createPlatformAdapterFor, 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, handleRelayerRequest, 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 };