@opendatalabs/vana-sdk 0.1.0-alpha.eebb656 → 0.1.0-alpha.ef15099

package/dist/controllers/permissions.d.ts

@@ -1,7 +1,7 @@
 import type { Address, Hash } from "viem";
-import type { GrantPermissionParams, RevokePermissionParams, PermissionGrantTypedData, GenericTypedData, OnChainPermissionGrant, GetUserPermissionsOptions, AddAndTrustServerParams, TrustServerParams, UntrustServerParams, AddAndTrustServerTypedData, TrustServerTypedData, TrustedServerInfo, PaginatedTrustedServers, TrustedServerQueryOptions, BatchServerInfoResult, ServerTrustStatus, GrantFile, Grantee, GranteeInfo, RegisterGranteeParams, RegisterGranteeTypedData, GranteeQueryOptions, PaginatedGrantees, ServerInfo, ServerFilesAndPermissionParams, ServerFilesAndPermissionTypedData } from "../types/index";
+import type { TransactionOptions, TransactionResult } from "../types/operations";
+import type { GrantPermissionParams, RevokePermissionParams, PermissionGrantTypedData, GenericTypedData, OnChainPermissionGrant, GetUserPermissionsOptions, AddAndTrustServerParams, TrustServerParams, UntrustServerParams, AddAndTrustServerTypedData, TrustServerTypedData, TrustedServerInfo, PaginatedTrustedServers, TrustedServerQueryOptions, BatchServerInfoResult, ServerTrustStatus, GrantFile, Grantee, GranteeInfo, RegisterGranteeParams, GranteeQueryOptions, PaginatedGrantees, ServerInfo, ServerFilesAndPermissionParams, ServerFilesAndPermissionTypedData } from "../types/index";
 import type { PermissionGrantResult, PermissionRevokeResult, ServerTrustResult } from "../types/transactionResults";
-import type { TransactionResult } from "../types/operations";
 import type { PermissionInfo } from "../types/permissions";
 /**
  * Provides shared configuration and services for all SDK controllers.
@@ -15,55 +15,57 @@ import type { PermissionInfo } from "../types/permissions";
  * @category Configuration
  */
 import type { ControllerContext } from "../types/controller-context";
+import { BaseController } from "./base";
 export type { ControllerContext };
 /**
- * Manages gasless data access permissions and trusted server registry operations.
+ * Manages data access permissions and trusted server operations with gasless transaction support.
  *
  * @remarks
- * This controller enables users to grant applications access to their data without
- * paying gas fees. It handles the complete EIP-712 permission flow including signature
- * creation, IPFS storage of permission details, and gasless transaction submission.
- * The controller also manages trusted servers that can process user data and provides
- * methods for revoking permissions when access is no longer needed.
+ * Enables applications to access user data through EIP-712 signatures, eliminating gas fees
+ * for users. Handles permission lifecycle from creation through revocation, plus trusted
+ * server management for data processing operations.
  *
- * **Permission Architecture:**
- * Permissions use dual storage: detailed parameters stored on IPFS, references stored on blockchain.
- * This enables complex permissions while maintaining minimal on-chain data.
+ * **Architecture:**
+ * Permissions use dual storage: complex parameters on IPFS, references on blockchain.
+ * This minimizes on-chain data while maintaining decentralization and auditability.
  *
  * **Method Selection:**
- * - `grant()` creates new permissions with automatic IPFS upload and blockchain registration
- * - `prepareGrant()` allows preview before signing for interactive applications
- * - `revoke()` removes permissions by ID, supporting both gasless and direct transactions
- * - `getUserPermissionGrantsOnChain()` queries existing permissions efficiently
- * - `trustServer()` and `untrustServer()` manage server access for data processing
+ * - `grant()` - Create permissions with automatic IPFS upload and blockchain registration
+ * - `prepareGrant()` - Preview permission structure before signing
+ * - `revoke()` - Remove permissions by ID (gasless or direct)
+ * - `getUserPermissionGrantsOnChain()` - Query active permissions
+ * - `trustServer()`/`untrustServer()` - Manage server access
+ *
+ * **Gasless Support:**
+ * All permission methods support both gasless (via relayer) and direct transactions.
+ * Configure relayer callbacks in Vana initialization for gasless operations.
  *
- * **Transaction Types:**
- * Methods with gasless support: `grant()`, `revoke()`, `trustServer()`, `untrustServer()`
- * Methods requiring direct transactions: none (all support both gasless and direct)
  * @example
  * ```typescript
- * // Grant permission for an app to access your data
- * const txHash = await vana.permissions.grant({
+ * // Grant data access permission
+ * const result = await vana.permissions.grant({
  *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
  *   operation: "llm_inference",
- *   files: [1, 2, 3],
- *   parameters: { model: "gpt-4", maxTokens: 1000 },
+ *   fileIds: [1, 2, 3],
+ *   parameters: { model: "gpt-4", maxTokens: 1000 }
  * });
+ * console.log(`Permission ${result.permissionId} granted`);
  *
- * // Trust a server for data processing
+ * // Trust server for processing
  * await vana.permissions.trustServer({
- *   serverId: "0x123...",
- *   serverUrl: "https://personal-server.vana.org",
+ *   serverAddress: "0x123...",
+ *   serverUrl: "https://personal-server.vana.org"
  * });
  *
- * // Query current permissions
+ * // Query active permissions
  * const permissions = await vana.permissions.getUserPermissionGrantsOnChain();
+ * permissions.forEach(p => console.log(`Permission ${p.id}: ${p.grantee}`));
  * ```
+ *
  * @category Permissions
- * @see {@link https://docs.vana.com/developer/permissions | Vana Permissions System} for conceptual overview
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/permissions}
  */
-export declare class PermissionsController {
-    private readonly context;
+export declare class PermissionsController extends BaseController {
     constructor(context: ControllerContext);
     /**
      * Grants permission for an application to access user data with gasless transactions.
@@ -99,7 +101,7 @@ export declare class PermissionsController {
      * await vana.permissions.revoke({ permissionId: result.permissionId });
      * ```
      */
-    grant(params: GrantPermissionParams): Promise<PermissionGrantResult>;
+    grant(params: GrantPermissionParams, options?: TransactionOptions): Promise<PermissionGrantResult>;
     /**
      * Submits a permission grant transaction and returns a handle for flexible result access.
      *
@@ -125,7 +127,7 @@ export declare class PermissionsController {
      * console.log(`Permission ID: ${eventData.permissionId}`);
      * ```
      */
-    submitPermissionGrant(params: GrantPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    submitPermissionGrant(params: GrantPermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
     /**
      * Prepares a permission grant with preview before signing.
      *
@@ -151,7 +153,7 @@ export declare class PermissionsController {
      * const transactionHash = await confirm();
      * ```
      */
-    prepareGrant(params: GrantPermissionParams): Promise<{
+    prepareGrant(params: GrantPermissionParams, options?: TransactionOptions): Promise<{
         preview: GrantFile;
         confirm: () => Promise<PermissionGrantResult>;
     }>;
@@ -223,7 +225,7 @@ export declare class PermissionsController {
      * );
      * ```
      */
-    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
     /**
      * Submits an already-signed trust server transaction to the blockchain.
      *
@@ -245,7 +247,7 @@ export declare class PermissionsController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
+    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
     /**
      * Submits an already-signed add and trust server transaction to the blockchain.
      *
@@ -267,7 +269,7 @@ export declare class PermissionsController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
+    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
     /**
      * Internal method to submit a signed grant and wait for events.
      *
@@ -286,6 +288,17 @@ export declare class PermissionsController {
      * @returns Promise resolving to PermissionGrantResult with parsed events
      */
     private confirmGrantInternalWithEvents;
+    /**
+     * Polls the relayer for confirmation of a pending operation.
+     *
+     * @param operationId - The operation ID to poll
+     * @param options - Polling configuration including status updates and cancellation
+     * @returns Promise resolving to the confirmed hash and receipt
+     * @throws {TransactionPendingError} When the operation times out
+     * @throws {Error} When the operation fails or is cancelled
+     * @internal
+     */
+    private pollRelayerForConfirmation;
     /**
      * Submits an already-signed permission revoke transaction to the blockchain.
      *
@@ -307,7 +320,7 @@ export declare class PermissionsController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedRevoke(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
+    submitSignedRevoke(typedData: GenericTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
     /**
      * Submits an already-signed untrust server transaction to the blockchain.
      *
@@ -329,7 +342,7 @@ export declare class PermissionsController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "untrustServerWithSignature">>;
+    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "untrustServerWithSignature">>;
     /**
      * Submits a signed transaction directly to the blockchain.
      *
@@ -375,6 +388,7 @@ export declare class PermissionsController {
      * Use this when you want to handle transaction confirmation and event parsing separately.
      *
      * @param params - Parameters for revoking the permission
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to the transaction hash when successfully submitted
      * @throws {BlockchainError} When revocation transaction fails
      * @throws {UserRejectedRequestError} When user rejects the transaction
@@ -387,7 +401,7 @@ export declare class PermissionsController {
      * console.log(`Revocation submitted: ${txHash}`);
      * ```
      */
-    submitPermissionRevoke(params: RevokePermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
+    submitPermissionRevoke(params: RevokePermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
     /**
      * Revokes a permission with a signature for gasless transactions.
      *
@@ -413,7 +427,7 @@ export declare class PermissionsController {
      * console.log(`Permission ${result.permissionId} revoked`);
      * ```
      */
-    submitRevokeWithSignature(params: RevokePermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
+    submitRevokeWithSignature(params: RevokePermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
     /**
      * Retrieves the user's current nonce from the DataPortabilityServers contract.
      * This nonce is used for server-related operations (AddAndTrustServer, TrustServer, UntrustServer).
@@ -507,11 +521,10 @@ export declare class PermissionsController {
      */
     private signTypedData;
     /**
-     * Gets the user's address from the wallet client.
+     * Gets the user's address from the context.
      *
-     * @returns Promise resolving to the user's wallet address
+     * @returns The user's address
      */
-    private getUserAddress;
     /**
      * Gets on-chain permission grant data without expensive off-chain resolution.
      *
@@ -596,7 +609,7 @@ export declare class PermissionsController {
      * @param params - Parameters for adding and trusting the server
      * @returns Promise resolving to TransactionResult with ServerTrustResult event data
      */
-    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
+    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
     /**
      * Trusts a server using a signature (gasless transaction - legacy method).
      *
@@ -610,7 +623,7 @@ export 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<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
+    submitTrustServerWithSignature(params: TrustServerParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
     /**
      * Submits a direct untrust server transaction (without signature).
      *
@@ -637,6 +650,7 @@ export declare class PermissionsController {
      *
      * @param params - Parameters for untrusting the server
      * @param params.serverId - The numeric ID of the server to untrust
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to transaction hash
      * @throws {Error} When wallet account is not available
      * @throws {NonceError} When retrieving user nonce fails
@@ -657,7 +671,7 @@ export declare class PermissionsController {
      * console.log('Still trusting servers:', trustedServers);
      * ```
      */
-    submitUntrustServer(params: UntrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "untrustServer">>;
+    submitUntrustServer(params: UntrustServerParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "untrustServer">>;
     /**
      * Untrusts a server using a signature (gasless transaction).
      *
@@ -837,14 +851,18 @@ export declare class PermissionsController {
      * A grantee is an entity (like an application) that can receive data permissions
      * from users. Once registered, users can grant the grantee access to their data.
      *
+     * This method supports gasless transactions via relayer when configured.
+     * If no relayer is available, it falls back to direct wallet transactions.
+     *
      * @param params - Parameters for registering the grantee
      * @param params.owner - The Ethereum address that will own this grantee registration
      * @param params.granteeAddress - The Ethereum address of the grantee (application)
      * @param params.publicKey - The public key used for data encryption/decryption (hex string)
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to the transaction hash
      * @throws {BlockchainError} When the grantee registration transaction fails
      * @throws {UserRejectedRequestError} When user rejects the transaction
-     * @throws {ContractError} When grantee is already registered
+     * @throws {RelayerError} When gasless transaction submission fails
      *
      * @example
      * ```typescript
@@ -856,36 +874,7 @@ export declare class PermissionsController {
      * console.log(`Grantee registered in transaction: ${txHash}`);
      * ```
      */
-    submitRegisterGrantee(params: RegisterGranteeParams): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
-    /**
-     * Registers a grantee with a signature (gasless transaction)
-     *
-     * @param params - Parameters for registering the grantee
-     * @returns Promise resolving to the transaction hash
-     *
-     * @example
-     * ```typescript
-     * const txHash = await vana.permissions.registerGranteeWithSignature({
-     *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
-     *   granteeAddress: "0xApp1234567890123456789012345678901234567890",
-     *   publicKey: "0x1234567890abcdef..."
-     * });
-     * ```
-     */
-    submitRegisterGranteeWithSignature(params: RegisterGranteeParams): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
-    /**
-     * Submits a signed register grantee transaction via relayer
-     *
-     * @param typedData - The EIP-712 typed data for register grantee
-     * @param signature - The cryptographic signature
-     * @returns Promise resolving to the transaction hash
-     *
-     * @example
-     * ```typescript
-     * const result = await vana.permissions.submitSignedRegisterGrantee(typedData, signature);
-     * ```
-     */
-    submitSignedRegisterGrantee(typedData: RegisterGranteeTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
+    submitRegisterGrantee(params: RegisterGranteeParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
     /**
      * Retrieves all registered grantees from the DataPortabilityGrantees contract.
      *
@@ -920,15 +909,16 @@ export declare class PermissionsController {
      */
     getGrantees(options?: GranteeQueryOptions): Promise<PaginatedGrantees>;
     /**
-     * Retrieves a specific grantee by their Ethereum address from the DataPortabilityGrantees contract.
+     * Retrieves a specific grantee by their Ethereum wallet address.
      *
+     * @remarks
      * Looks up a registered grantee (application) using their Ethereum address
-     * and returns their complete registration information including permissions.
+     * and returns their complete registration information including all associated permissions.
      *
-     * @param granteeAddress - The Ethereum address of the grantee to look up
-     * @returns Promise resolving to the grantee information, or null if not found
-     * @throws {BlockchainError} When contract read operation fails
-     * @throws {NetworkError} When unable to connect to the blockchain network
+     * Returns `null` if the address is not registered as a grantee or if an error occurs.
+     *
+     * @param granteeAddress - Ethereum wallet address of the grantee to query
+     * @returns Grantee information including ID, addresses, public key, and permission IDs, or `null` if not found
      *
      * @example
      * ```typescript
@@ -947,15 +937,16 @@ export declare class PermissionsController {
      */
     getGranteeByAddress(granteeAddress: Address): Promise<Grantee | null>;
     /**
-     * Retrieves a specific grantee by their unique ID from the DataPortabilityGrantees contract.
+     * Retrieves a specific grantee by their unique ID.
      *
+     * @remarks
      * Looks up a registered grantee (application) using their numeric ID assigned during
-     * registration and returns their complete information including permissions.
+     * registration and returns their complete information including all associated permissions.
      *
-     * @param granteeId - The unique numeric ID of the grantee (1-indexed)
-     * @returns Promise resolving to the grantee information, or null if not found
-     * @throws {BlockchainError} When contract read operation fails
-     * @throws {NetworkError} When unable to connect to the blockchain network
+     * Returns `null` if the grantee is not found or if an error occurs during fetching.
+     *
+     * @param granteeId - Unique numeric ID of the grantee (1-indexed)
+     * @returns Grantee information including ID, addresses, public key, and permission IDs, or `null` if not found
      *
      * @example
      * ```typescript
@@ -963,7 +954,7 @@ export declare class PermissionsController {
      *
      * if (grantee) {
      *   console.log(`Grantee ID: ${grantee.id}`);
-     *   console.log(`Address: ${grantee.granteeAddress}`);
+     *   console.log(`Address: ${grantee.address}`);
      *   console.log(`Owner: ${grantee.owner}`);
      *   console.log(`Total permissions: ${grantee.permissionIds.length}`);
      * } else {
@@ -972,23 +963,6 @@ export declare class PermissionsController {
      * ```
      */
     getGranteeById(granteeId: number): Promise<Grantee | null>;
-    /**
-     * Builds EIP-712 typed data for grantee registration
-     *
-     * @param input - The register grantee input
-     * @returns Promise resolving to the typed data structure
-     * @private
-     */
-    private buildRegisterGranteeTypedData;
-    /**
-     * Submits a register grantee transaction with signature.
-     *
-     * @param typedData - The EIP-712 typed data structure for the registration
-     * @param _signature - The cryptographic signature authorizing the registration (currently unused)
-     * @returns Promise resolving to the transaction hash
-     * @private
-     */
-    private submitSignedRegisterGranteeTransaction;
     /**
      * Get all trusted server IDs for a user
      *
@@ -1083,6 +1057,24 @@ export declare class PermissionsController {
      * @returns Promise resolving to array of file IDs
      */
     getPermissionFileIds(permissionId: bigint): Promise<bigint[]>;
+    /**
+     * Retrieves detailed grant file data from IPFS or HTTP storage.
+     *
+     * @remarks
+     * This method automatically uses the SDK's configured downloadRelayer to bypass CORS restrictions.
+     * Use this instead of importing the standalone `retrieveGrantFile` utility.
+     *
+     * @param grantUrl - The grant file URL (from OnChainPermissionGrant.grantUrl)
+     * @returns Promise resolving to the complete grant file with operation details
+     * @throws {NetworkError} When all retrieval attempts fail
+     * @example
+     * ```typescript
+     * const grants = await vana.permissions.getUserPermissionGrantsOnChain();
+     * const grantFile = await vana.permissions.retrieveGrantFile(grants[0].grantUrl);
+     * console.log(`Operation: ${grantFile.operation}`);
+     * ```
+     */
+    retrieveGrantFile(grantUrl: string): Promise<GrantFile>;
     /**
      * Get all permissions for a specific file (alias for getFilePermissionIds)
      *
@@ -1091,17 +1083,39 @@ export declare class PermissionsController {
      */
     getFilePermissions(fileId: bigint): Promise<bigint[]>;
     /**
-     * Get grantee information by grantee ID
+     * Retrieves detailed grantee information including all associated permissions.
+     *
+     * @remarks
+     * Returns grantee metadata and associated permission IDs. Uses the newer
+     * paginated contract method internally for efficient permission fetching.
+     *
+     * @param granteeId - Unique grantee identifier as bigint
+     * @returns Grantee information containing owner address, grantee address, public key, and permission IDs
+     * @throws {BlockchainError} When grantee ID is not found or contract read fails
      *
-     * @param granteeId - Grantee ID to get info for
-     * @returns Promise resolving to grantee info
+     * @example
+     * ```typescript
+     * const granteeInfo = await vana.permissions.getGranteeInfo(BigInt(1));
+     * console.log(`Grantee ${granteeInfo.granteeAddress} has ${granteeInfo.permissionIds.length} permissions`);
+     * ```
      */
     getGranteeInfo(granteeId: bigint): Promise<GranteeInfo>;
     /**
-     * Get grantee information by grantee address
+     * Retrieves detailed grantee information by wallet address.
+     *
+     * @remarks
+     * Looks up the grantee ID from the provided address, then fetches complete
+     * grantee information including all associated permissions.
      *
-     * @param granteeAddress - Grantee address to get info for
-     * @returns Promise resolving to grantee info
+     * @param granteeAddress - Ethereum wallet address of the grantee to query
+     * @returns Grantee information containing owner address, grantee address, public key, and permission IDs
+     * @throws {BlockchainError} When grantee address is not registered or contract read fails
+     *
+     * @example
+     * ```typescript
+     * const granteeInfo = await vana.permissions.getGranteeInfoByAddress("0x742d35Cc6634c0532925a3b844Bc9e8e1ee3b2De");
+     * console.log(`Found grantee with ${granteeInfo.permissionIds.length} permissions`);
+     * ```
      */
     getGranteeInfoByAddress(granteeAddress: Address): Promise<GranteeInfo>;
     /**
@@ -1118,6 +1132,57 @@ export declare class PermissionsController {
      * @returns Promise resolving to array of permission IDs
      */
     getGranteePermissions(granteeId: bigint): Promise<bigint[]>;
+    /**
+     * Retrieves permission IDs for a specific grantee with flexible pagination.
+     *
+     * @remarks
+     * **Pagination Behavior:**
+     * Returns different types based on parameters:
+     * - Without offset/limit: Returns `bigint[]` of all permissions using batched multicall
+     * - With offset/limit: Returns paginated object with `permissionIds`, `totalCount`, and `hasMore`
+     *
+     * Uses gas-aware multicall for efficient batch fetching when retrieving all permissions.
+     *
+     * @param granteeId - Grantee ID to get permissions for
+     * @param options - Optional pagination parameters
+     * @param options.offset - Zero-based starting index for pagination. Defaults to 0 when fetching all permissions. Required for single-page requests.
+     * @param options.limit - Maximum number of permission IDs to return per page. Defaults to 100 when fetching all permissions. Required for single-page requests.
+     * @returns When called without options: Array of all permission IDs as `bigint[]`.
+     *   When called with offset and limit: Paginated result object containing `permissionIds` array,
+     *   `totalCount`, and `hasMore` boolean.
+     * @throws {BlockchainError} When contract read operation fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch all permissions (no pagination params)
+     * const allPermissions = await vana.permissions.getGranteePermissionsPaginated(BigInt(1));
+     * console.log(`Total permissions: ${allPermissions.length}`);
+     *
+     * // Fetch a specific page (with pagination params)
+     * const page = await vana.permissions.getGranteePermissionsPaginated(BigInt(1), {
+     *   offset: BigInt(0),
+     *   limit: BigInt(100)
+     * });
+     * console.log(`Fetched ${page.permissionIds.length} permissions`);
+     * console.log(`Total: ${page.totalCount}, Has more: ${page.hasMore}`);
+     *
+     * // Fetch next page
+     * if (page.hasMore) {
+     *   const nextPage = await vana.permissions.getGranteePermissionsPaginated(BigInt(1), {
+     *     offset: BigInt(100),
+     *     limit: BigInt(100)
+     *   });
+     * }
+     * ```
+     */
+    getGranteePermissionsPaginated(granteeId: bigint, options?: {
+        offset?: bigint;
+        limit?: bigint;
+    }): Promise<bigint[] | {
+        permissionIds: bigint[];
+        totalCount: bigint;
+        hasMore: boolean;
+    }>;
     /**
      * Get all server IDs for a user
      *
@@ -1170,9 +1235,10 @@ export declare class PermissionsController {
      *
      * @param serverId - Server ID to update
      * @param url - New URL for the server
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to transaction hash
      */
-    submitUpdateServer(serverId: bigint, url: string): Promise<TransactionResult<"DataPortabilityServers", "updateServer">>;
+    submitUpdateServer(serverId: bigint, url: string, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "updateServer">>;
     /**
      * Get all permission IDs for a user
      *
@@ -1224,7 +1290,7 @@ export declare class PermissionsController {
      * @throws {BlockchainError} When permission addition fails
      * @throws {NetworkError} When network communication fails
      */
-    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
     /**
      * Submits server files and permissions with signature to the blockchain, supporting schema validation and gasless transactions.
      *
@@ -1245,6 +1311,9 @@ export declare class PermissionsController {
      * @param params.serverPublicKey - Server's public key for encryption.
      *   Obtain via `vana.server.getIdentity(userAddress).publicKey`.
      * @param params.filePermissions - Nested array of permissions for each file
+     * @param options - Optional transaction options for gas parameters and timeout.
+     *   Note: These options are only applied for direct blockchain transactions.
+     *   When using relayer callbacks (gasless transactions), these options are ignored.
      * @returns TransactionResult with immediate hash access and optional event data
      * @throws {Error} When schemaIds array length doesn't match fileUrls array length
      * @throws {SchemaValidationError} When file data doesn't match the specified schema.
@@ -1258,6 +1327,7 @@ export declare class PermissionsController {
      *
      * @example
      * ```typescript
+     * // Submit with custom gas parameters and timeout
      * const result = await vana.permissions.submitAddServerFilesAndPermissions({
      *   granteeId: BigInt(1),
      *   grant: "ipfs://QmXxx...",
@@ -1270,12 +1340,19 @@ export declare class PermissionsController {
      *     account: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
      *     key: encryptedKey
      *   }]]
+     * }, {
+     *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei
+     *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip
+     * });
+     *
+     * // Wait for confirmation with custom timeout
+     * const receipt = await vana.waitForTransactionReceipt(result, {
+     *   timeout: 180000 // 3 minutes
      * });
-     * const events = await result.waitForEvents();
-     * console.log(`Permission ID: ${events.permissionId}`);
+     * console.log(`Transaction confirmed: ${receipt.transactionHash}`);
      * ```
      */
-    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
+    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
     /**
      * Submits an already-signed add server files and permissions transaction to the blockchain.
      *
@@ -1285,6 +1362,9 @@ export declare class PermissionsController {
      *
      * @param typedData - The EIP-712 typed data for AddServerFilesAndPermissions
      * @param signature - The user's signature
+     * @param options - Optional transaction options for gas parameters and timeout.
+     *   Note: These options are only applied for direct blockchain transactions.
+     *   When using relayer callbacks (gasless transactions), these options are ignored.
      * @returns TransactionResult with immediate hash access and optional event data
      * @throws {RelayerError} When gasless transaction submission fails
      * @throws {BlockchainError} When server files and permissions addition fails
@@ -1303,14 +1383,15 @@ export declare class PermissionsController {
      * console.log(`Permission created with ID: ${permissionId}`);
      * ```
      */
-    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
+    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
     /**
      * Submit permission revocation with signature to the blockchain
      *
      * @param permissionId - Permission ID to revoke
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to transaction hash
      */
-    submitRevokePermission(permissionId: bigint): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
+    submitRevokePermission(permissionId: bigint, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
     /**
      * Submits a signed add permission transaction directly to the blockchain.
      *