@opendatalabs/vana-sdk 0.1.0-alpha.fd33fc9 → 2.0.0

package/dist/controllers/permissions.cjs

@@ -33,6 +33,7 @@ __export(permissions_exports, {
 module.exports = __toCommonJS(permissions_exports);
 var import_viem = require("viem");
 var import_multicall = require("../utils/multicall");
+var import_pollingManager = require("../core/pollingManager");
 var import_errors = require("../errors");
 var import_addresses = require("../config/addresses");
 var import_abi = require("../generated/abi");
@@ -80,10 +81,14 @@ class PermissionsController extends import_base.BaseController {
    * await vana.permissions.revoke({ permissionId: result.permissionId });
    * ```
    */
-  async grant(params) {
+  async grant(params, options) {
     this.assertWallet();
     const { typedData, signature } = await this.createAndSign(params);
-    const result = await this.submitSignedGrantWithEvents(typedData, signature);
+    const result = await this.submitSignedGrantWithEvents(
+      typedData,
+      signature,
+      options
+    );
     return result;
   }
   /**
@@ -111,10 +116,10 @@ class PermissionsController extends import_base.BaseController {
    * console.log(`Permission ID: ${eventData.permissionId}`);
    * ```
    */
-  async submitPermissionGrant(params) {
+  async submitPermissionGrant(params, options) {
     this.assertWallet();
     const { typedData, signature } = await this.createAndSign(params);
-    return await this.submitSignedGrant(typedData, signature);
+    return await this.submitSignedGrant(typedData, signature, options);
   }
   /**
    * Prepares a permission grant with preview before signing.
@@ -141,7 +146,7 @@ class PermissionsController extends import_base.BaseController {
    * const transactionHash = await confirm();
    * ```
    */
-  async prepareGrant(params) {
+  async prepareGrant(params, options) {
     this.assertWallet();
     try {
       const grantFile = (0, import_grantFiles.createGrantFile)(params);
@@ -149,7 +154,11 @@ class PermissionsController extends import_base.BaseController {
       return {
         preview: grantFile,
         confirm: async () => {
-          return await this.confirmGrantInternalWithEvents(params, grantFile);
+          return await this.confirmGrantInternalWithEvents(
+            params,
+            grantFile,
+            options
+          );
         }
       };
     } catch (error) {
@@ -181,7 +190,7 @@ class PermissionsController extends import_base.BaseController {
    * @throws {NetworkError} When IPFS upload fails
    * @throws {SignatureError} When user rejects the signature
    */
-  async confirmGrantInternal(params, grantFile) {
+  async confirmGrantInternal(params, grantFile, options) {
     try {
       let { grantUrl } = params;
       console.debug("\u{1F50D} Debug - Grant URL from params:", grantUrl);
@@ -206,7 +215,7 @@ class PermissionsController extends import_base.BaseController {
           if (response.type === "error") {
             throw new Error(response.error);
           }
-          if (response.type === "direct" && typeof response.result === "object" && "url" in response.result) {
+          if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "url" in response.result) {
             grantUrl = response.result.url;
           } else {
             throw new Error("Invalid response from relayer for grant storage");
@@ -242,7 +251,7 @@ class PermissionsController extends import_base.BaseController {
         nonce
       });
       const signature = await this.signTypedData(typedData);
-      return await this.submitSignedGrant(typedData, signature);
+      return await this.submitSignedGrant(typedData, signature, options);
     } catch (error) {
       if (error instanceof Error) {
         if (error instanceof import_errors.RelayerError || error instanceof import_errors.UserRejectedRequestError || error instanceof import_errors.SerializationError || error instanceof import_errors.SignatureError || error instanceof import_errors.NetworkError || error instanceof import_errors.NonceError) {
@@ -314,7 +323,7 @@ class PermissionsController extends import_base.BaseController {
           if (response.type === "error") {
             throw new Error(response.error);
           }
-          if (response.type === "direct" && typeof response.result === "object" && "url" in response.result) {
+          if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "url" in response.result) {
             grantUrl = response.result.url;
           } else {
             throw new Error("Invalid response from relayer for grant storage");
@@ -387,7 +396,7 @@ class PermissionsController extends import_base.BaseController {
    * );
    * ```
    */
-  async submitSignedGrant(typedData, signature) {
+  async submitSignedGrant(typedData, signature, options) {
     try {
       console.debug(
         "\u{1F50D} Debug - submitSignedGrant called with typed data:",
@@ -405,26 +414,41 @@ class PermissionsController extends import_base.BaseController {
           signature,
           expectedUserAddress: this.context.userAddress
         });
-        let hash;
-        if (response.type === "signed") {
-          hash = response.hash;
-        } else if (response.type === "error") {
+        if (response.type === "error") {
           throw new Error(`Relayer error: ${response.error}`);
+        }
+        let finalHash;
+        if (response.type === "submitted") {
+          finalHash = response.hash;
+        } else if (response.type === "pending") {
+          const pollResult = await this.pollRelayerForConfirmation(
+            response.operationId,
+            options
+          );
+          finalHash = pollResult.hash;
+        } else if (response.type === "confirmed") {
+          finalHash = response.hash;
+        } else if (response.type === "signed") {
+          finalHash = response.hash;
         } else {
           throw new Error(
-            "Invalid response from relayer: expected signed transaction"
+            "Invalid response from relayer: unexpected response type"
           );
         }
         const account = this.context.walletClient?.account ?? this.context.userAddress;
         const { tx } = await import("../utils/transactionHelpers");
         return tx({
-          hash,
+          hash: finalHash,
           from: typeof account === "string" ? account : account.address,
           contract: "DataPortabilityPermissions",
           fn: "addPermission"
         });
       } else {
-        return await this.submitDirectTransaction(typedData, signature);
+        return await this.submitDirectTransaction(
+          typedData,
+          signature,
+          options
+        );
       }
     } catch (error) {
       if (error instanceof import_errors.RelayerError || error instanceof import_errors.NetworkError || error instanceof import_errors.UserRejectedRequestError || error instanceof import_errors.SignatureError || error instanceof import_errors.NonceError) {
@@ -457,7 +481,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedTrustServer(typedData, signature) {
+  async submitSignedTrustServer(typedData, signature, options) {
     try {
       const trustServerInput = {
         nonce: BigInt(typedData.message.nonce),
@@ -465,7 +489,8 @@ class PermissionsController extends import_base.BaseController {
       };
       const hash = await this.submitTrustServerTransaction(
         trustServerInput,
-        signature
+        signature,
+        options
       );
       const account = this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
@@ -520,7 +545,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedAddAndTrustServer(typedData, signature) {
+  async submitSignedAddAndTrustServer(typedData, signature, options) {
     try {
       const addAndTrustServerInput = {
         nonce: BigInt(typedData.message.nonce),
@@ -530,7 +555,8 @@ class PermissionsController extends import_base.BaseController {
       };
       const hash = await this.submitAddAndTrustServerTransaction(
         addAndTrustServerInput,
-        signature
+        signature,
+        options
       );
       const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
@@ -558,8 +584,12 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The user's signature authorizing the transaction
    * @returns Promise resolving to PermissionGrantResult with parsed events
    */
-  async submitSignedGrantWithEvents(typedData, signature) {
-    const txResult = await this.submitSignedGrant(typedData, signature);
+  async submitSignedGrantWithEvents(typedData, signature, options) {
+    const txResult = await this.submitSignedGrant(
+      typedData,
+      signature,
+      options
+    );
     if (!this.context.waitForTransactionEvents) {
       throw new import_errors.BlockchainError("waitForTransactionEvents not configured");
     }
@@ -591,8 +621,12 @@ class PermissionsController extends import_base.BaseController {
    * @param grantFile - The pre-created grant file object
    * @returns Promise resolving to PermissionGrantResult with parsed events
    */
-  async confirmGrantInternalWithEvents(params, grantFile) {
-    const txResult = await this.confirmGrantInternal(params, grantFile);
+  async confirmGrantInternalWithEvents(params, grantFile, options) {
+    const txResult = await this.confirmGrantInternal(
+      params,
+      grantFile,
+      options
+    );
     if (!this.context.waitForTransactionEvents) {
       throw new import_errors.BlockchainError("waitForTransactionEvents not configured");
     }
@@ -616,6 +650,27 @@ class PermissionsController extends import_base.BaseController {
       fileIds: event.fileIds
     };
   }
+  /**
+   * 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
+   */
+  async pollRelayerForConfirmation(operationId, options) {
+    if (!this.context.relayer) {
+      throw new Error("Relayer not configured for polling");
+    }
+    const pollingManager = new import_pollingManager.PollingManager(this.context.relayer);
+    return await pollingManager.startPolling(operationId, {
+      signal: options?.signal,
+      onStatusUpdate: options?.onStatusUpdate,
+      ...options?.pollingOptions
+    });
+  }
   /**
    * Submits an already-signed permission revoke transaction to the blockchain.
    *
@@ -637,7 +692,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedRevoke(typedData, signature) {
+  async submitSignedRevoke(typedData, signature, options) {
     try {
       let hash;
       if (this.context.relayer) {
@@ -648,19 +703,31 @@ class PermissionsController extends import_base.BaseController {
           signature,
           expectedUserAddress: this.context.userAddress
         });
-        if (response.type === "signed") {
-          hash = response.hash;
-        } else if (response.type === "error") {
+        if (response.type === "error") {
           throw new Error(`Relayer error: ${response.error}`);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "pending") {
+          const pollResult = await this.pollRelayerForConfirmation(
+            response.operationId,
+            options
+          );
+          hash = pollResult.hash;
+        } else if (response.type === "confirmed") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
+          hash = response.hash;
         } else {
           throw new Error(
-            "Invalid response from relayer: expected signed transaction"
+            "Invalid response from relayer: unexpected response type"
           );
         }
       } else {
         hash = await this.submitDirectRevokeTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -702,7 +769,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedUntrustServer(typedData, signature) {
+  async submitSignedUntrustServer(typedData, signature, options) {
     try {
       let hash;
       if (this.context.relayer) {
@@ -713,7 +780,9 @@ class PermissionsController extends import_base.BaseController {
           signature,
           expectedUserAddress: this.context.userAddress
         });
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else if (response.type === "error") {
           throw new Error(`Relayer error: ${response.error}`);
@@ -725,7 +794,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitSignedUntrustTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -758,7 +828,7 @@ class PermissionsController extends import_base.BaseController {
    * @returns Promise resolving to the transaction hash
    * @throws {BlockchainError} When contract submission fails
    */
-  async submitDirectTransaction(typedData, signature) {
+  async submitDirectTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = (0, import_addresses.getContractAddress)(
@@ -790,7 +860,8 @@ class PermissionsController extends import_base.BaseController {
       functionName: "addPermission",
       args: [permissionInput, formattedSignature],
       account,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...this.spreadTransactionOptions(options)
     });
     const { tx } = await import("../utils/transactionHelpers");
     return tx({
@@ -854,6 +925,7 @@ class PermissionsController extends import_base.BaseController {
    * 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
@@ -866,7 +938,7 @@ class PermissionsController extends import_base.BaseController {
    * console.log(`Revocation submitted: ${txHash}`);
    * ```
    */
-  async submitPermissionRevoke(params) {
+  async submitPermissionRevoke(params, options) {
     this.assertWallet();
     try {
       if (!this.context.walletClient?.chain?.id) {
@@ -887,7 +959,18 @@ class PermissionsController extends import_base.BaseController {
         functionName: "revokePermission",
         args: [params.permissionId],
         account,
-        chain: this.context.walletClient?.chain ?? null
+        chain: this.context.walletClient?.chain ?? null,
+        ...options?.gas && { gas: options.gas },
+        ...options?.nonce && { nonce: options.nonce },
+        // Use EIP-1559 if available, otherwise fall back to legacy gasPrice
+        ...options?.maxFeePerGas || options?.maxPriorityFeePerGas ? {
+          ...options.maxFeePerGas && {
+            maxFeePerGas: options.maxFeePerGas
+          },
+          ...options.maxPriorityFeePerGas && {
+            maxPriorityFeePerGas: options.maxPriorityFeePerGas
+          }
+        } : options?.gasPrice && { gasPrice: options.gasPrice }
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -934,7 +1017,7 @@ class PermissionsController extends import_base.BaseController {
    * console.log(`Permission ${result.permissionId} revoked`);
    * ```
    */
-  async submitRevokeWithSignature(params) {
+  async submitRevokeWithSignature(params, options) {
     this.assertWallet();
     try {
       if (!this.context.walletClient?.chain?.id) {
@@ -966,7 +1049,9 @@ class PermissionsController extends import_base.BaseController {
           signature,
           expectedUserAddress: this.context.userAddress
         });
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else if (response.type === "error") {
           throw new Error(`Relayer error: ${response.error}`);
@@ -978,7 +1063,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitDirectRevokeTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1304,7 +1390,9 @@ class PermissionsController extends import_base.BaseController {
    * ```
    */
   async getUserPermissionGrantsOnChain(options = {}) {
-    const { limit = 50, subgraphUrl } = options;
+    const { limit = 50, fetchAll = false, subgraphUrl } = options;
+    const pageSize = fetchAll ? 100 : limit;
+    const maxResults = fetchAll ? 1e4 : limit;
     try {
       const userAddress = this.context.userAddress;
       const graphqlEndpoint = subgraphUrl ?? this.context.subgraphUrl;
@@ -1314,10 +1402,10 @@ class PermissionsController extends import_base.BaseController {
         );
       }
       const query = `
-        query GetUserPermissions($userId: ID!) {
+        query GetUserPermissions($userId: ID!, $first: Int!, $skip: Int!) {
           user(id: $userId) {
             id
-            permissions {
+            permissions(first: $first, skip: $skip, orderBy: addedAtBlock, orderDirection: desc) {
               id
               grant
               nonce
@@ -1335,34 +1423,82 @@ class PermissionsController extends import_base.BaseController {
           }
         }
       `;
-      const response = await fetch(graphqlEndpoint, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          query,
-          variables: {
-            userId: userAddress.toLowerCase()
+      const allPermissions = [];
+      let currentOffset = 0;
+      if (!fetchAll) {
+        const response = await fetch(graphqlEndpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            query,
+            variables: {
+              userId: userAddress.toLowerCase(),
+              first: limit,
+              skip: 0
+            }
+          })
+        });
+        if (!response.ok) {
+          throw new import_errors.BlockchainError(
+            `Subgraph request failed: ${response.status} ${response.statusText}`
+          );
+        }
+        const result = await response.json();
+        if (result.errors) {
+          throw new import_errors.BlockchainError(
+            `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+          );
+        }
+        const userData = result.data?.user;
+        if (!userData?.permissions?.length) {
+          return [];
+        }
+        allPermissions.push(...userData.permissions);
+      } else {
+        while (allPermissions.length < maxResults) {
+          const currentLimit = Math.min(
+            pageSize,
+            maxResults - allPermissions.length
+          );
+          const response = await fetch(graphqlEndpoint, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              query,
+              variables: {
+                userId: userAddress.toLowerCase(),
+                first: currentLimit,
+                skip: currentOffset
+              }
+            })
+          });
+          if (!response.ok) {
+            throw new import_errors.BlockchainError(
+              `Subgraph request failed: ${response.status} ${response.statusText}`
+            );
           }
-        })
-      });
-      if (!response.ok) {
-        throw new import_errors.BlockchainError(
-          `Subgraph request failed: ${response.status} ${response.statusText}`
-        );
-      }
-      const result = await response.json();
-      if (result.errors) {
-        throw new import_errors.BlockchainError(
-          `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
-        );
-      }
-      const userData = result.data?.user;
-      if (!userData?.permissions?.length) {
-        return [];
+          const result = await response.json();
+          if (result.errors) {
+            throw new import_errors.BlockchainError(
+              `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+            );
+          }
+          const userData = result.data?.user;
+          if (!userData?.permissions?.length) {
+            break;
+          }
+          allPermissions.push(...userData.permissions);
+          if (userData.permissions.length < currentLimit) {
+            break;
+          }
+          currentOffset += userData.permissions.length;
+        }
       }
-      const onChainGrants = userData.permissions.slice(0, limit).map(
+      const onChainGrants = allPermissions.map(
         (permission) => ({
           id: BigInt(permission.id),
           grantUrl: permission.grant,
@@ -1543,7 +1679,7 @@ class PermissionsController extends import_base.BaseController {
    * @param params - Parameters for adding and trusting the server
    * @returns Promise resolving to TransactionResult with ServerTrustResult event data
    */
-  async submitAddAndTrustServerWithSignature(params) {
+  async submitAddAndTrustServerWithSignature(params, options) {
     this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
@@ -1579,7 +1715,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -1587,7 +1725,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitAddAndTrustServerTransaction(
           addAndTrustServerInput,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1626,7 +1765,7 @@ class PermissionsController extends import_base.BaseController {
    * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
    * @throws {BlockchainError} When trust operation fails for any other reason
    */
-  async submitTrustServerWithSignature(params) {
+  async submitTrustServerWithSignature(params, options) {
     this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
@@ -1648,7 +1787,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -1656,7 +1797,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitTrustServerTransaction(
           trustServerInput,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1697,7 +1839,7 @@ class PermissionsController extends import_base.BaseController {
    * @returns Promise resolving to TransactionResult for transaction tracking
    * @throws {BlockchainError} When contract submission fails
    */
-  async submitDirectUntrustTransaction(params) {
+  async submitDirectUntrustTransaction(params, options) {
     this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
@@ -1713,7 +1855,18 @@ class PermissionsController extends import_base.BaseController {
         functionName: "untrustServer",
         args: [BigInt(params.serverId)],
         account,
-        chain: this.context.walletClient?.chain ?? null
+        chain: this.context.walletClient?.chain ?? null,
+        ...options?.gas && { gas: options.gas },
+        ...options?.nonce && { nonce: options.nonce },
+        // Use EIP-1559 if available, otherwise fall back to legacy gasPrice
+        ...options?.maxFeePerGas || options?.maxPriorityFeePerGas ? {
+          ...options.maxFeePerGas && {
+            maxFeePerGas: options.maxFeePerGas
+          },
+          ...options.maxPriorityFeePerGas && {
+            maxPriorityFeePerGas: options.maxPriorityFeePerGas
+          }
+        } : options?.gasPrice && { gasPrice: options.gasPrice }
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -1740,6 +1893,7 @@ class PermissionsController extends import_base.BaseController {
    *
    * @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
@@ -1760,14 +1914,17 @@ class PermissionsController extends import_base.BaseController {
    * console.log('Still trusting servers:', trustedServers);
    * ```
    */
-  async submitUntrustServer(params) {
+  async submitUntrustServer(params, options) {
     this.assertWallet();
     const nonce = await this.getServersUserNonce();
     const untrustServerInput = {
       nonce,
       serverId: params.serverId
     };
-    return await this.submitDirectUntrustTransaction(untrustServerInput);
+    return await this.submitDirectUntrustTransaction(
+      untrustServerInput,
+      options
+    );
   }
   /**
    * Untrusts a server using a signature (gasless transaction).
@@ -1803,7 +1960,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -2249,7 +2408,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature for the transaction
    * @returns Promise resolving to the transaction hash
    */
-  async submitAddAndTrustServerTransaction(addAndTrustServerInput, signature) {
+  async submitAddAndTrustServerTransaction(addAndTrustServerInput, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = (0, import_addresses.getContractAddress)(
@@ -2283,7 +2442,16 @@ class PermissionsController extends import_base.BaseController {
         formattedSignature
       ],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options && {
+        gas: options.gas,
+        nonce: options.nonce,
+        // Use EIP-1559 gas pricing if available, otherwise legacy
+        ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+          maxFeePerGas: options.maxFeePerGas,
+          maxPriorityFeePerGas: options.maxPriorityFeePerGas
+        } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+      }
     });
     return txHash;
   }
@@ -2294,7 +2462,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature for the transaction
    * @returns Promise resolving to the transaction hash
    */
-  async submitTrustServerTransaction(trustServerInput, signature) {
+  async submitTrustServerTransaction(trustServerInput, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = (0, import_addresses.getContractAddress)(
@@ -2315,7 +2483,8 @@ class PermissionsController extends import_base.BaseController {
         formattedSignature
       ],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...this.spreadTransactionOptions(options)
     });
     return txHash;
   }
@@ -2326,7 +2495,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature authorizing the revoke
    * @returns Promise resolving to the transaction hash
    */
-  async submitDirectRevokeTransaction(typedData, signature) {
+  async submitDirectRevokeTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityPermissionsAddress = (0, import_addresses.getContractAddress)(
@@ -2341,7 +2510,16 @@ class PermissionsController extends import_base.BaseController {
       functionName: "revokePermissionWithSignature",
       args: [typedData.message, formattedSignature],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options && {
+        gas: options.gas,
+        nonce: options.nonce,
+        // Use EIP-1559 gas pricing if available, otherwise legacy
+        ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+          maxFeePerGas: options.maxFeePerGas,
+          maxPriorityFeePerGas: options.maxPriorityFeePerGas
+        } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+      }
     });
     return txHash;
   }
@@ -2352,7 +2530,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature authorizing the untrust
    * @returns Promise resolving to the transaction hash
    */
-  async submitSignedUntrustTransaction(typedData, signature) {
+  async submitSignedUntrustTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = (0, import_addresses.getContractAddress)(
@@ -2371,7 +2549,16 @@ class PermissionsController extends import_base.BaseController {
       functionName: "untrustServerWithSignature",
       args: [contractMessage, formattedSignature],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options && {
+        gas: options.gas,
+        nonce: options.nonce,
+        // Use EIP-1559 gas pricing if available, otherwise legacy
+        ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+          maxFeePerGas: options.maxFeePerGas,
+          maxPriorityFeePerGas: options.maxPriorityFeePerGas
+        } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+      }
     });
     return txHash;
   }
@@ -2384,14 +2571,18 @@ class PermissionsController extends import_base.BaseController {
    * 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
@@ -2403,36 +2594,88 @@ class PermissionsController extends import_base.BaseController {
    * console.log(`Grantee registered in transaction: ${txHash}`);
    * ```
    */
-  async submitRegisterGrantee(params) {
-    this.assertWallet();
-    const chainId = await this.context.walletClient.getChainId();
-    const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
-    const ownerAddress = (0, import_viem.getAddress)(params.owner);
-    const granteeAddress = (0, import_viem.getAddress)(params.granteeAddress);
-    const account = this.context.walletClient?.account ?? this.context.userAddress;
-    const txHash = await this.context.walletClient.writeContract({
-      address: DataPortabilityGranteesAddress,
-      abi: DataPortabilityGranteesAbi,
-      functionName: "registerGrantee",
-      args: [ownerAddress, granteeAddress, params.publicKey],
-      account,
-      chain: this.context.walletClient?.chain ?? null
-    });
-    const { tx } = await import("../utils/transactionHelpers");
-    return tx({
-      hash: txHash,
-      from: typeof account === "string" ? account : account.address,
-      contract: "DataPortabilityGrantees",
-      fn: "registerGrantee"
-    });
+  async submitRegisterGrantee(params, options) {
+    try {
+      let hash;
+      if (this.context.relayer) {
+        const request = {
+          type: "direct",
+          operation: "submitRegisterGrantee",
+          params: {
+            owner: params.owner,
+            granteeAddress: params.granteeAddress,
+            publicKey: params.publicKey
+          }
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new import_errors.RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "direct") {
+          const result = response.result;
+          hash = result.transactionHash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
+      } else {
+        this.assertWallet();
+        const chainId = await this.context.walletClient.getChainId();
+        const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
+          chainId,
+          "DataPortabilityGrantees"
+        );
+        const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
+        const ownerAddress = (0, import_viem.getAddress)(params.owner);
+        const granteeAddress = (0, import_viem.getAddress)(params.granteeAddress);
+        const account2 = this.context.walletClient?.account ?? this.context.userAddress;
+        hash = await this.context.walletClient.writeContract({
+          address: DataPortabilityGranteesAddress,
+          abi: DataPortabilityGranteesAbi,
+          functionName: "registerGrantee",
+          args: [ownerAddress, granteeAddress, params.publicKey],
+          account: account2,
+          chain: this.context.walletClient?.chain ?? null,
+          ...this.spreadTransactionOptions(options)
+        });
+      }
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityGrantees",
+        fn: "registerGrantee"
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error instanceof import_errors.RelayerError || error instanceof import_errors.UserRejectedRequestError || error instanceof import_errors.SerializationError || error instanceof import_errors.SignatureError || error instanceof import_errors.BlockchainError) {
+          throw error;
+        }
+        if (error.name === "ContractFunctionExecutionError") {
+          throw new import_errors.BlockchainError(
+            `Grantee registration failed: ${error.message}`,
+            error
+          );
+        }
+        if (error.name === "UserRejectedRequestError") {
+          throw new import_errors.UserRejectedRequestError(
+            "User rejected the grantee registration transaction"
+          );
+        }
+        throw new import_errors.BlockchainError(
+          `Failed to register grantee: ${error.message}`,
+          error
+        );
+      }
+      throw new import_errors.BlockchainError(`Failed to register grantee: ${String(error)}`);
+    }
   }
   // TODO: When DataPortabilityGrantees contract adds registerGranteeWithSignature function,
   // implement submitRegisterGranteeWithSignature and submitSignedRegisterGrantee methods
-  // to support gasless transactions via relayer
+  // to support EIP-712 signed gasless transactions via relayer.
+  // Current implementation above supports direct gasless transactions (relayer pays gas directly).
   /**
    * Retrieves all registered grantees from the DataPortabilityGrantees contract.
    *
@@ -2480,27 +2723,52 @@ class PermissionsController extends import_base.BaseController {
     const total = Number(totalCount);
     const limit = options.limit ?? 50;
     const offset = options.offset ?? 0;
-    const grantees = [];
-    const endIndex = Math.min(offset + limit, total);
-    for (let i = offset; i < endIndex; i++) {
-      try {
-        const granteeInfo = await this.context.publicClient.readContract({
-          address: DataPortabilityGranteesAddress,
-          abi: DataPortabilityGranteesAbi,
-          functionName: "grantees",
-          args: [BigInt(i + 1)]
-          // Grantee IDs are 1-indexed
-        });
-        grantees.push({
-          id: i + 1,
-          owner: granteeInfo.owner,
-          address: granteeInfo.granteeAddress,
-          publicKey: granteeInfo.publicKey,
-          permissionIds: granteeInfo.permissionIds.map((id) => Number(id))
-        });
-      } catch (error) {
-        console.warn(`Failed to fetch grantee ${i + 1}:`, error);
-      }
+    const includePermissions = options.includePermissions ?? true;
+    const startId = total - offset;
+    const endId = Math.max(startId - limit + 1, 1);
+    const granteeIds = Array.from(
+      { length: startId - endId + 1 },
+      (_, i) => startId - i
+      // Generate IDs in descending order
+    );
+    let grantees;
+    if (includePermissions) {
+      const granteePromises = granteeIds.map(
+        (granteeId) => this.getGranteeById(granteeId)
+      );
+      const granteeResults = await Promise.all(granteePromises);
+      grantees = granteeResults.filter(
+        (grantee) => grantee !== null
+      );
+    } else {
+      const granteeInfoPromises = granteeIds.map(
+        async (granteeId) => {
+          try {
+            const granteeInfo = await this.context.publicClient.readContract({
+              address: DataPortabilityGranteesAddress,
+              abi: DataPortabilityGranteesAbi,
+              functionName: "granteesV2",
+              args: [BigInt(granteeId)]
+            });
+            const grantee = {
+              id: granteeId,
+              owner: granteeInfo.owner,
+              address: granteeInfo.granteeAddress,
+              publicKey: granteeInfo.publicKey,
+              permissionIds: []
+              // TypeScript infers number[] from Grantee type
+            };
+            return grantee;
+          } catch (error) {
+            console.warn(`Failed to fetch grantee ${granteeId}:`, error);
+            return null;
+          }
+        }
+      );
+      const granteeInfoResults = await Promise.all(granteeInfoPromises);
+      grantees = granteeInfoResults.filter(
+        (grantee) => grantee !== null
+      );
     }
     return {
       grantees,
@@ -2511,15 +2779,16 @@ class PermissionsController extends import_base.BaseController {
     };
   }
   /**
-   * 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
@@ -2544,40 +2813,32 @@ class PermissionsController extends import_base.BaseController {
     );
     const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
     try {
-      const granteeInfo = await this.context.publicClient.readContract({
-        address: DataPortabilityGranteesAddress,
-        abi: DataPortabilityGranteesAbi,
-        functionName: "granteeByAddress",
-        args: [granteeAddress]
-      });
       const granteeId = await this.context.publicClient.readContract({
         address: DataPortabilityGranteesAddress,
         abi: DataPortabilityGranteesAbi,
         functionName: "granteeAddressToId",
         args: [granteeAddress]
       });
-      return {
-        id: Number(granteeId),
-        owner: granteeInfo.owner,
-        address: granteeInfo.granteeAddress,
-        publicKey: granteeInfo.publicKey,
-        permissionIds: granteeInfo.permissionIds.map((id) => Number(id))
-      };
+      if (granteeId === 0n) {
+        return null;
+      }
+      return await this.getGranteeById(Number(granteeId));
     } catch (error) {
       console.warn(`Failed to fetch grantee ${granteeAddress}:`, error);
       return 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
@@ -2585,7 +2846,7 @@ class PermissionsController extends import_base.BaseController {
    *
    * 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 {
@@ -2601,18 +2862,23 @@ class PermissionsController extends import_base.BaseController {
     );
     const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
     try {
-      const granteeInfo = await this.context.publicClient.readContract({
+      const granteeInfoResult = await this.context.publicClient.readContract({
         address: DataPortabilityGranteesAddress,
         abi: DataPortabilityGranteesAbi,
-        functionName: "grantees",
+        functionName: "granteesV2",
         args: [BigInt(granteeId)]
       });
+      const granteeInfo = granteeInfoResult;
+      const allPermissionIdsResult = await this.getGranteePermissionsPaginated(
+        BigInt(granteeId)
+      );
+      const allPermissionIds = allPermissionIdsResult;
       return {
         id: granteeId,
         owner: granteeInfo.owner,
         address: granteeInfo.granteeAddress,
         publicKey: granteeInfo.publicKey,
-        permissionIds: granteeInfo.permissionIds.map((id) => Number(id))
+        permissionIds: allPermissionIds.map((id) => Number(id))
       };
     } catch (error) {
       console.warn(`Failed to fetch grantee ${granteeId}:`, error);
@@ -3009,6 +3275,31 @@ class PermissionsController extends import_base.BaseController {
       );
     }
   }
+  /**
+   * 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}`);
+   * ```
+   */
+  async retrieveGrantFile(grantUrl) {
+    const { retrieveGrantFile: retrieveGrantFileUtil } = await import("../utils/grantFiles");
+    return retrieveGrantFileUtil(
+      grantUrl,
+      void 0,
+      this.context.downloadRelayer
+    );
+  }
   /**
    * Get all permissions for a specific file (alias for getFilePermissionIds)
    *
@@ -3034,26 +3325,34 @@ class PermissionsController extends import_base.BaseController {
   // DATA PORTABILITY GRANTEES HELPER METHODS
   // ===========================
   /**
-   * 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 - Grantee ID to get info for
-   * @returns Promise resolving to grantee info
+   * @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
+   *
+   * @example
+   * ```typescript
+   * const granteeInfo = await vana.permissions.getGranteeInfo(BigInt(1));
+   * console.log(`Grantee ${granteeInfo.granteeAddress} has ${granteeInfo.permissionIds.length} permissions`);
+   * ```
    */
   async getGranteeInfo(granteeId) {
     try {
-      const chainId = await this.context.publicClient.getChainId();
-      const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
-        chainId,
-        "DataPortabilityGrantees"
-      );
-      const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
-      const granteeInfo = await this.context.publicClient.readContract({
-        address: DataPortabilityGranteesAddress,
-        abi: DataPortabilityGranteesAbi,
-        functionName: "granteeInfo",
-        args: [granteeId]
-      });
-      return granteeInfo;
+      const grantee = await this.getGranteeById(Number(granteeId));
+      if (!grantee) {
+        throw new Error("Grantee not found");
+      }
+      return {
+        owner: grantee.owner,
+        granteeAddress: grantee.address,
+        publicKey: grantee.publicKey,
+        permissionIds: grantee.permissionIds.map((id) => BigInt(id))
+      };
     } catch (error) {
       throw new import_errors.BlockchainError(
         `Failed to get grantee info: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3062,10 +3361,21 @@ class PermissionsController extends import_base.BaseController {
     }
   }
   /**
-   * Get grantee information by grantee address
+   * Retrieves detailed grantee information by wallet address.
    *
-   * @param granteeAddress - Grantee address to get info for
-   * @returns Promise resolving to grantee info
+   * @remarks
+   * Looks up the grantee ID from the provided address, then fetches complete
+   * grantee information including all associated permissions.
+   *
+   * @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`);
+   * ```
    */
   async getGranteeInfoByAddress(granteeAddress) {
     try {
@@ -3075,13 +3385,26 @@ class PermissionsController extends import_base.BaseController {
         "DataPortabilityGrantees"
       );
       const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
-      const granteeInfo = await this.context.publicClient.readContract({
+      const granteeIdResult = await this.context.publicClient.readContract({
         address: DataPortabilityGranteesAddress,
         abi: DataPortabilityGranteesAbi,
-        functionName: "granteeByAddress",
+        functionName: "granteeAddressToId",
         args: [granteeAddress]
       });
-      return granteeInfo;
+      const granteeId = granteeIdResult;
+      if (granteeId === 0n) {
+        throw new Error("Grantee not found");
+      }
+      const grantee = await this.getGranteeById(Number(granteeId));
+      if (!grantee) {
+        throw new Error("Grantee not found");
+      }
+      return {
+        owner: grantee.owner,
+        granteeAddress: grantee.address,
+        publicKey: grantee.publicKey,
+        permissionIds: grantee.permissionIds.map((id) => BigInt(id))
+      };
     } catch (error) {
       throw new import_errors.BlockchainError(
         `Failed to get grantee info by address: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3145,6 +3468,117 @@ class PermissionsController extends import_base.BaseController {
       );
     }
   }
+  /**
+   * 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)
+   *   });
+   * }
+   * ```
+   */
+  async getGranteePermissionsPaginated(granteeId, options) {
+    try {
+      const chainId = await this.context.publicClient.getChainId();
+      const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
+        chainId,
+        "DataPortabilityGrantees"
+      );
+      const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
+      const fetchOnlyOnePage = options?.offset !== void 0 && options?.limit !== void 0;
+      if (fetchOnlyOnePage) {
+        const result = await this.context.publicClient.readContract({
+          address: DataPortabilityGranteesAddress,
+          abi: DataPortabilityGranteesAbi,
+          functionName: "granteePermissionsPaginated",
+          args: [granteeId, options.offset, options.limit]
+        });
+        const [permissionIds, totalCount2, hasMore] = result;
+        return {
+          permissionIds: [...permissionIds],
+          totalCount: totalCount2,
+          hasMore
+        };
+      }
+      const countResult = await this.context.publicClient.readContract({
+        address: DataPortabilityGranteesAddress,
+        abi: DataPortabilityGranteesAbi,
+        functionName: "granteePermissionsPaginated",
+        args: [granteeId, BigInt(0), BigInt(1)]
+      });
+      const [, totalCount] = countResult;
+      if (totalCount === BigInt(0)) {
+        return [];
+      }
+      const batchSize = options?.limit ?? BigInt(100);
+      const startOffset = options?.offset ?? BigInt(0);
+      const endOffset = totalCount;
+      const numBatches = Math.ceil(
+        Number(endOffset - startOffset) / Number(batchSize)
+      );
+      const paginationCalls = Array.from({ length: numBatches }, (_, i) => ({
+        address: DataPortabilityGranteesAddress,
+        abi: DataPortabilityGranteesAbi,
+        functionName: "granteePermissionsPaginated",
+        args: [
+          granteeId,
+          startOffset + BigInt(i) * batchSize,
+          batchSize
+        ]
+      }));
+      const results = await (0, import_multicall.gasAwareMulticall)(
+        this.context.publicClient,
+        {
+          contracts: paginationCalls
+        }
+      );
+      const allPermissionIds = [];
+      for (const result of results) {
+        const [permissionIds] = result;
+        allPermissionIds.push(...permissionIds);
+      }
+      return allPermissionIds;
+    } catch (error) {
+      throw new import_errors.BlockchainError(
+        `Failed to get grantee permissions: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
   // ===== DataPortabilityServersImplementation Methods =====
   /**
    * Get all server IDs for a user
@@ -3338,9 +3772,10 @@ class PermissionsController extends import_base.BaseController {
    *
    * @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
    */
-  async submitUpdateServer(serverId, url) {
+  async submitUpdateServer(serverId, url, options) {
     this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
@@ -3356,7 +3791,18 @@ class PermissionsController extends import_base.BaseController {
         functionName: "updateServer",
         args: [serverId, url],
         chain: this.context.walletClient?.chain,
-        account
+        account,
+        ...options?.gas && { gas: options.gas },
+        ...options?.nonce && { nonce: options.nonce },
+        // Use EIP-1559 if available, otherwise fall back to legacy gasPrice
+        ...options?.maxFeePerGas || options?.maxPriorityFeePerGas ? {
+          ...options.maxFeePerGas && {
+            maxFeePerGas: options.maxFeePerGas
+          },
+          ...options.maxPriorityFeePerGas && {
+            maxPriorityFeePerGas: options.maxPriorityFeePerGas
+          }
+        } : options?.gasPrice && { gasPrice: options.gasPrice }
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -3552,7 +3998,7 @@ class PermissionsController extends import_base.BaseController {
    * @throws {BlockchainError} When permission addition fails
    * @throws {NetworkError} When network communication fails
    */
-  async submitSignedAddPermission(typedData, signature) {
+  async submitSignedAddPermission(typedData, signature, options) {
     this.assertWallet();
     try {
       let hash;
@@ -3567,7 +4013,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -3575,7 +4023,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitDirectAddPermissionTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -3616,6 +4065,9 @@ class PermissionsController extends import_base.BaseController {
    * @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.
@@ -3629,6 +4081,7 @@ class PermissionsController extends import_base.BaseController {
    *
    * @example
    * ```typescript
+   * // Submit with custom gas parameters and timeout
    * const result = await vana.permissions.submitAddServerFilesAndPermissions({
    *   granteeId: BigInt(1),
    *   grant: "ipfs://QmXxx...",
@@ -3641,12 +4094,19 @@ class PermissionsController extends import_base.BaseController {
    *     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}`);
    * ```
    */
-  async submitAddServerFilesAndPermissions(params) {
+  async submitAddServerFilesAndPermissions(params, options) {
     this.assertWallet();
     try {
       if (params.schemaIds.length !== params.fileUrls.length) {
@@ -3672,7 +4132,8 @@ class PermissionsController extends import_base.BaseController {
       const signature = await this.signTypedData(typedData);
       return await this.submitSignedAddServerFilesAndPermissions(
         typedData,
-        signature
+        signature,
+        options
       );
     } catch (error) {
       if (error instanceof import_errors.RelayerError || error instanceof import_errors.UserRejectedRequestError || error instanceof import_errors.SerializationError || error instanceof import_errors.SignatureError || error instanceof import_errors.NetworkError || error instanceof import_errors.NonceError) {
@@ -3693,6 +4154,9 @@ class PermissionsController extends import_base.BaseController {
    *
    * @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
@@ -3711,7 +4175,7 @@ class PermissionsController extends import_base.BaseController {
    * console.log(`Permission created with ID: ${permissionId}`);
    * ```
    */
-  async submitSignedAddServerFilesAndPermissions(typedData, signature) {
+  async submitSignedAddServerFilesAndPermissions(typedData, signature, options) {
     this.assertWallet();
     try {
       let hash;
@@ -3729,7 +4193,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -3740,7 +4206,8 @@ class PermissionsController extends import_base.BaseController {
         );
         hash = await this.submitDirectAddServerFilesAndPermissionsTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -3765,9 +4232,10 @@ class PermissionsController extends import_base.BaseController {
    * 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
    */
-  async submitRevokePermission(permissionId) {
+  async submitRevokePermission(permissionId, options) {
     this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
@@ -3788,7 +4256,18 @@ class PermissionsController extends import_base.BaseController {
         functionName: "revokePermission",
         args: [permissionId],
         chain: this.context.walletClient?.chain,
-        account
+        account,
+        ...options?.gas && { gas: options.gas },
+        ...options?.nonce && { nonce: options.nonce },
+        // Use EIP-1559 if available, otherwise fall back to legacy gasPrice
+        ...options?.maxFeePerGas || options?.maxPriorityFeePerGas ? {
+          ...options.maxFeePerGas && {
+            maxFeePerGas: options.maxFeePerGas
+          },
+          ...options.maxPriorityFeePerGas && {
+            maxPriorityFeePerGas: options.maxPriorityFeePerGas
+          }
+        } : options?.gasPrice && { gasPrice: options.gasPrice }
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -3811,7 +4290,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature authorizing the transaction
    * @returns Promise resolving to the transaction hash
    */
-  async submitDirectAddPermissionTransaction(typedData, signature) {
+  async submitDirectAddPermissionTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityPermissionsAddress = (0, import_addresses.getContractAddress)(
@@ -3832,7 +4311,8 @@ class PermissionsController extends import_base.BaseController {
       functionName: "addPermission",
       args: [permissionInput, formattedSignature],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...this.spreadTransactionOptions(options)
     });
     return hash;
   }
@@ -3843,7 +4323,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature authorizing the transaction
    * @returns Promise resolving to the transaction hash
    */
-  async submitDirectAddServerFilesAndPermissionsTransaction(typedData, signature) {
+  async submitDirectAddServerFilesAndPermissionsTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = (0, import_addresses.getContractAddress)(
@@ -3867,10 +4347,11 @@ class PermissionsController extends import_base.BaseController {
       address: DataPortabilityPermissionsAddress,
       abi: DataPortabilityPermissionsAbi,
       functionName: "addServerFilesAndPermissions",
-      // @ts-expect-error - Viem's type inference for nested Permission[][] arrays is incompatible with our Permission type
       args: [serverFilesAndPermissionInput, formattedSignature],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options?.value && { value: options.value },
+      ...this.spreadTransactionOptions(options)
     });
     return hash;
   }