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

package/dist/controllers/permissions.js

@@ -1,5 +1,6 @@
 import { getAddress } from "viem";
 import { gasAwareMulticall } from "../utils/multicall";
+import { PollingManager } from "../core/pollingManager";
 import {
   RelayerError,
   UserRejectedRequestError,
@@ -11,16 +12,17 @@ import {
   ServerUrlMismatchError,
   PermissionError
 } from "../errors";
-import { getContractAddress } from "../config/addresses";
+import { getContractAddress } from "../generated/addresses";
 import { getAbi } from "../generated/abi";
 import { createGrantFile, getGrantFileHash } from "../utils/grantFiles";
 import { validateGrant } from "../utils/grantValidation";
 import { withSignatureCache } from "../utils/signatureCache";
 import { formatSignatureForContract } from "../utils/signatureFormatter";
 import { toViemTypedDataDefinition } from "../utils/typedDataConverter";
-class PermissionsController {
+import { BaseController } from "./base";
+class PermissionsController extends BaseController {
   constructor(context) {
-    this.context = context;
+    super(context);
   }
   /**
    * Grants permission for an application to access user data with gasless transactions.
@@ -56,9 +58,14 @@ class PermissionsController {
    * 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;
   }
   /**
@@ -86,9 +93,10 @@ class PermissionsController {
    * 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.
@@ -115,14 +123,19 @@ class PermissionsController {
    * const transactionHash = await confirm();
    * ```
    */
-  async prepareGrant(params) {
+  async prepareGrant(params, options) {
+    this.assertWallet();
     try {
       const grantFile = createGrantFile(params);
       validateGrant(grantFile);
       return {
         preview: grantFile,
         confirm: async () => {
-          return await this.confirmGrantInternalWithEvents(params, grantFile);
+          return await this.confirmGrantInternalWithEvents(
+            params,
+            grantFile,
+            options
+          );
         }
       };
     } catch (error) {
@@ -154,22 +167,36 @@ class PermissionsController {
    * @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);
       if (!grantUrl) {
-        if (!this.context.relayerCallbacks?.storeGrantFile && !this.context.storageManager) {
+        const canStoreViaRelayer = this.context.relayer !== void 0;
+        if (!canStoreViaRelayer && !this.context.storageManager) {
           if (this.context.validateStorageRequired) {
             this.context.validateStorageRequired();
           } else {
             throw new Error(
-              "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
+              "No storage available. Provide a grantUrl, configure relayer, or storageManager."
             );
           }
         }
-        if (this.context.relayerCallbacks?.storeGrantFile) {
-          grantUrl = await this.context.relayerCallbacks.storeGrantFile(grantFile);
+        if (canStoreViaRelayer && this.context.relayer) {
+          const request = {
+            type: "direct",
+            operation: "storeGrantFile",
+            params: grantFile
+          };
+          const response = await this.context.relayer(request);
+          if (response.type === "error") {
+            throw new Error(response.error);
+          }
+          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");
+          }
         } else if (this.context.storageManager) {
           const blob = new Blob([JSON.stringify(grantFile)], {
             type: "application/json"
@@ -201,7 +228,7 @@ class PermissionsController {
         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 RelayerError || error instanceof UserRejectedRequestError || error instanceof SerializationError || error instanceof SignatureError || error instanceof NetworkError || error instanceof NonceError) {
@@ -246,23 +273,38 @@ class PermissionsController {
    * ```
    */
   async createAndSign(params) {
+    this.assertWallet();
     try {
       const grantFile = createGrantFile(params);
       validateGrant(grantFile);
       let { grantUrl } = params;
       console.debug("\u{1F50D} Debug - Grant URL from params:", grantUrl);
       if (!grantUrl) {
-        if (!this.context.relayerCallbacks?.storeGrantFile && !this.context.storageManager) {
+        const canStoreViaRelayer = this.context.relayer !== void 0;
+        if (!canStoreViaRelayer && !this.context.storageManager) {
           if (this.context.validateStorageRequired) {
             this.context.validateStorageRequired();
           } else {
             throw new Error(
-              "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
+              "No storage available. Provide a grantUrl, configure relayer, or storageManager."
             );
           }
         }
-        if (this.context.relayerCallbacks?.storeGrantFile) {
-          grantUrl = await this.context.relayerCallbacks.storeGrantFile(grantFile);
+        if (canStoreViaRelayer && this.context.relayer) {
+          const request = {
+            type: "direct",
+            operation: "storeGrantFile",
+            params: grantFile
+          };
+          const response = await this.context.relayer(request);
+          if (response.type === "error") {
+            throw new Error(response.error);
+          }
+          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");
+          }
         } else if (this.context.storageManager) {
           const blob = new Blob([JSON.stringify(grantFile)], {
             type: "application/json"
@@ -331,7 +373,7 @@ class PermissionsController {
    * );
    * ```
    */
-  async submitSignedGrant(typedData, signature) {
+  async submitSignedGrant(typedData, signature, options) {
     try {
       console.debug(
         "\u{1F50D} Debug - submitSignedGrant called with typed data:",
@@ -341,21 +383,49 @@ class PermissionsController {
           2
         )
       );
-      if (this.context.relayerCallbacks?.submitPermissionGrant) {
-        const hash = await this.context.relayerCallbacks.submitPermissionGrant(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitAddPermission",
           typedData,
-          signature
-        );
-        const account = this.context.walletClient.account ?? await this.getUserAddress();
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        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: 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 RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
@@ -388,7 +458,7 @@ class PermissionsController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedTrustServer(typedData, signature) {
+  async submitSignedTrustServer(typedData, signature, options) {
     try {
       const trustServerInput = {
         nonce: BigInt(typedData.message.nonce),
@@ -396,13 +466,14 @@ class PermissionsController {
       };
       const hash = await this.submitTrustServerTransaction(
         trustServerInput,
-        signature
+        signature,
+        options
       );
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
-        from: typeof account === "string" ? account : account.address,
+        from: account,
         contract: "DataPortabilityServers",
         fn: "trustServerWithSignature"
       });
@@ -451,7 +522,7 @@ class PermissionsController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedAddAndTrustServer(typedData, signature) {
+  async submitSignedAddAndTrustServer(typedData, signature, options) {
     try {
       const addAndTrustServerInput = {
         nonce: BigInt(typedData.message.nonce),
@@ -461,9 +532,10 @@ class PermissionsController {
       };
       const hash = await this.submitAddAndTrustServerTransaction(
         addAndTrustServerInput,
-        signature
+        signature,
+        options
       );
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -489,8 +561,12 @@ class PermissionsController {
    * @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 BlockchainError("waitForTransactionEvents not configured");
     }
@@ -522,8 +598,12 @@ class PermissionsController {
    * @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 BlockchainError("waitForTransactionEvents not configured");
     }
@@ -547,6 +627,27 @@ class PermissionsController {
       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 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.
    *
@@ -568,21 +669,45 @@ class PermissionsController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedRevoke(typedData, signature) {
+  async submitSignedRevoke(typedData, signature, options) {
     try {
       let hash;
-      if (this.context.relayerCallbacks?.submitPermissionRevoke) {
-        hash = await this.context.relayerCallbacks.submitPermissionRevoke(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitPermissionRevoke",
           typedData,
-          signature
-        );
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        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: unexpected response type"
+          );
+        }
       } else {
         hash = await this.submitDirectRevokeTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -621,21 +746,36 @@ class PermissionsController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedUntrustServer(typedData, signature) {
+  async submitSignedUntrustServer(typedData, signature, options) {
     try {
       let hash;
-      if (this.context.relayerCallbacks?.submitUntrustServer) {
-        hash = await this.context.relayerCallbacks.submitUntrustServer(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitUntrustServer",
           typedData,
-          signature
-        );
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        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}`);
+        } else {
+          throw new Error(
+            "Invalid response from relayer: expected signed transaction"
+          );
+        }
       } else {
         hash = await this.submitSignedUntrustTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -665,8 +805,9 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    * @throws {BlockchainError} When contract submission fails
    */
-  async submitDirectTransaction(typedData, signature) {
-    const chainId = await this.context.walletClient.getChainId();
+  async submitDirectTransaction(typedData, signature, options) {
+    this.assertWallet();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
       "DataPortabilityPermissions"
@@ -689,14 +830,15 @@ class PermissionsController {
       typedData.message.grant?.length ?? 0
     );
     const formattedSignature = formatSignatureForContract(signature);
-    const account = this.context.walletClient.account ?? await this.getUserAddress();
+    const account = this.context.walletClient?.account ?? this.context.userAddress;
     const txHash = await this.context.walletClient.writeContract({
       address: DataPortabilityPermissionsAddress,
       abi: DataPortabilityPermissionsAbi,
       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({
@@ -731,6 +873,7 @@ class PermissionsController {
    * ```
    */
   async revoke(params) {
+    this.assertWallet();
     const txResult = await this.submitPermissionRevoke(params);
     if (!this.context.waitForTransactionEvents) {
       throw new BlockchainError("waitForTransactionEvents not configured");
@@ -759,6 +902,7 @@ 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
@@ -771,12 +915,13 @@ class PermissionsController {
    * console.log(`Revocation submitted: ${txHash}`);
    * ```
    */
-  async submitPermissionRevoke(params) {
+  async submitPermissionRevoke(params, options) {
+    this.assertWallet();
     try {
-      if (!this.context.walletClient.chain?.id) {
+      if (!this.context.walletClient?.chain?.id) {
         throw new BlockchainError("Chain ID not available");
       }
-      const chainId = await this.context.walletClient.getChainId();
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityPermissionsAddress = getContractAddress(
         chainId,
         "DataPortabilityPermissions"
@@ -784,14 +929,25 @@ class PermissionsController {
       const DataPortabilityPermissionsAbi = getAbi(
         "DataPortabilityPermissions"
       );
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const txHash = await this.context.walletClient.writeContract({
         address: DataPortabilityPermissionsAddress,
         abi: DataPortabilityPermissionsAbi,
         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({
@@ -838,9 +994,10 @@ class PermissionsController {
    * console.log(`Permission ${result.permissionId} revoked`);
    * ```
    */
-  async submitRevokeWithSignature(params) {
+  async submitRevokeWithSignature(params, options) {
+    this.assertWallet();
     try {
-      if (!this.context.walletClient.chain?.id) {
+      if (!this.context.walletClient?.chain?.id) {
         throw new BlockchainError("Chain ID not available");
       }
       const nonce = await this.getPermissionsUserNonce();
@@ -861,18 +1018,33 @@ class PermissionsController {
       };
       const signature = await this.signTypedData(typedData);
       let hash;
-      if (this.context.relayerCallbacks?.submitPermissionRevoke) {
-        hash = await this.context.relayerCallbacks.submitPermissionRevoke(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitPermissionRevoke",
           typedData,
-          signature
-        );
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        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}`);
+        } else {
+          throw new Error(
+            "Invalid response from relayer: expected signed transaction"
+          );
+        }
       } else {
         hash = await this.submitDirectRevokeTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -913,8 +1085,8 @@ class PermissionsController {
    */
   async getServersUserNonce() {
     try {
-      const userAddress = await this.getUserAddress();
-      const chainId = await this.context.walletClient.getChainId();
+      const userAddress = this.context.userAddress;
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -959,8 +1131,8 @@ class PermissionsController {
    */
   async getPermissionsUserNonce() {
     try {
-      const userAddress = await this.getUserAddress();
-      const chainId = await this.context.walletClient.getChainId();
+      const userAddress = this.context.userAddress;
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityPermissionsAddress = getContractAddress(
         chainId,
         "DataPortabilityPermissions"
@@ -999,7 +1171,7 @@ class PermissionsController {
       "\u{1F50D} Debug - Composing permission message with grantUrl:",
       params.grantUrl
     );
-    const chainId = await this.context.walletClient.getChainId();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityGranteesAddress = getContractAddress(
       chainId,
       "DataPortabilityGrantees"
@@ -1108,7 +1280,7 @@ class PermissionsController {
    * @returns Promise resolving to the EIP-712 domain configuration
    */
   async getPermissionDomain() {
-    const chainId = await this.context.walletClient.getChainId();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
       "DataPortabilityPermissions"
@@ -1127,8 +1299,9 @@ class PermissionsController {
    * @returns Promise resolving to the cryptographic signature
    */
   async signTypedData(typedData) {
+    this.assertWallet();
     try {
-      const walletAddress = this.context.walletClient.account?.address ?? await this.getUserAddress();
+      const walletAddress = this.context.walletClient.account?.address ?? this.context.userAddress;
       return await withSignatureCache(
         this.context.platform.cache,
         walletAddress,
@@ -1154,17 +1327,10 @@ class PermissionsController {
     }
   }
   /**
-   * 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
    */
-  async getUserAddress() {
-    const addresses = await this.context.walletClient.getAddresses();
-    if (addresses.length === 0) {
-      throw new BlockchainError("No addresses available in wallet client");
-    }
-    return addresses[0];
-  }
   /**
    * Gets on-chain permission grant data without expensive off-chain resolution.
    *
@@ -1201,9 +1367,11 @@ class PermissionsController {
    * ```
    */
   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 = await this.getUserAddress();
+      const userAddress = this.context.userAddress;
       const graphqlEndpoint = subgraphUrl ?? this.context.subgraphUrl;
       if (!graphqlEndpoint) {
         throw new BlockchainError(
@@ -1211,10 +1379,10 @@ class PermissionsController {
         );
       }
       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
@@ -1232,34 +1400,82 @@ class PermissionsController {
           }
         }
       `;
-      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 BlockchainError(
+            `Subgraph request failed: ${response.status} ${response.statusText}`
+          );
+        }
+        const result = await response.json();
+        if (result.errors) {
+          throw new 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 BlockchainError(
+              `Subgraph request failed: ${response.status} ${response.statusText}`
+            );
           }
-        })
-      });
-      if (!response.ok) {
-        throw new BlockchainError(
-          `Subgraph request failed: ${response.status} ${response.statusText}`
-        );
-      }
-      const result = await response.json();
-      if (result.errors) {
-        throw new 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 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,
@@ -1323,6 +1539,7 @@ class PermissionsController {
    * ```
    */
   async addAndTrustServer(params) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1330,7 +1547,7 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const userAddress = typeof account === "string" ? account : account.address;
       const normalizedUserAddress = getAddress(userAddress);
       const normalizedServerAddress = getAddress(params.serverAddress);
@@ -1347,7 +1564,7 @@ class PermissionsController {
           }
         ],
         account,
-        chain: this.context.walletClient.chain ?? null
+        chain: this.context.walletClient?.chain ?? null
       });
       const { tx } = await import("../utils/transactionHelpers");
       const txResult = tx({
@@ -1399,6 +1616,7 @@ class PermissionsController {
    * @deprecated Use addAndTrustServer instead
    */
   async submitTrustServer(params) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1406,14 +1624,14 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const txHash = await this.context.walletClient.writeContract({
         address: DataPortabilityServersAddress,
         abi: DataPortabilityServersAbi,
         functionName: "trustServer",
         args: [BigInt(params.serverId)],
         account,
-        chain: this.context.walletClient.chain ?? null
+        chain: this.context.walletClient?.chain ?? null
       });
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
@@ -1438,7 +1656,8 @@ class PermissionsController {
    * @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();
       const serverAddress = getAddress(params.serverAddress);
@@ -1462,18 +1681,32 @@ class PermissionsController {
       const signature = await this.signTypedData(typedData);
       console.debug("\u{1F50D} Generated signature:", signature);
       let hash;
-      if (this.context.relayerCallbacks?.submitAddAndTrustServer) {
-        hash = await this.context.relayerCallbacks.submitAddAndTrustServer(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitAddAndTrustServer",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitAddAndTrustServerTransaction(
           addAndTrustServerInput,
-          signature
+          signature,
+          options
         );
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -1509,7 +1742,8 @@ class PermissionsController {
    * @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();
       const trustServerInput = {
@@ -1519,18 +1753,32 @@ class PermissionsController {
       const typedData = await this.composeTrustServerMessage(trustServerInput);
       const signature = await this.signTypedData(typedData);
       let hash;
-      if (this.context.relayerCallbacks?.submitTrustServer) {
-        hash = await this.context.relayerCallbacks.submitTrustServer(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitTrustServer",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitTrustServerTransaction(
           trustServerInput,
-          signature
+          signature,
+          options
         );
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -1568,7 +1816,8 @@ class PermissionsController {
    * @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();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1576,14 +1825,25 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const txHash = await this.context.walletClient.writeContract({
         address: DataPortabilityServersAddress,
         abi: DataPortabilityServersAbi,
         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({
@@ -1610,6 +1870,7 @@ 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
@@ -1630,13 +1891,17 @@ class PermissionsController {
    * 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).
@@ -1651,6 +1916,7 @@ class PermissionsController {
    * @throws {BlockchainError} When untrust transaction fails
    */
   async submitUntrustServerWithSignature(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
       const untrustServerInput = {
@@ -1660,15 +1926,28 @@ class PermissionsController {
       const typedData = await this.composeUntrustServerMessage(untrustServerInput);
       const signature = await this.signTypedData(typedData);
       let hash;
-      if (this.context.relayerCallbacks?.submitUntrustServer) {
-        hash = await this.context.relayerCallbacks.submitUntrustServer(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitUntrustServer",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitSignedUntrustTransaction(typedData, signature);
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -1713,8 +1992,8 @@ class PermissionsController {
    */
   async getTrustedServers(userAddress) {
     try {
-      const user = userAddress ?? await this.getUserAddress();
-      const chainId = await this.context.walletClient.getChainId();
+      const user = userAddress ?? this.context.userAddress;
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -1743,8 +2022,8 @@ class PermissionsController {
    */
   async getTrustedServersCount(userAddress) {
     try {
-      const user = userAddress ?? await this.getUserAddress();
-      const chainId = await this.context.walletClient.getChainId();
+      const user = userAddress ?? this.context.userAddress;
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -1773,10 +2052,10 @@ class PermissionsController {
    */
   async getTrustedServersPaginated(options = {}) {
     try {
-      const user = options.userAddress ?? await this.getUserAddress();
+      const user = options.userAddress ?? this.context.userAddress;
       const limit = options.limit ?? 50;
       const offset = options.offset ?? 0;
-      const chainId = await this.context.walletClient.getChainId();
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -1922,7 +2201,7 @@ class PermissionsController {
       };
     }
     try {
-      const chainId = await this.context.walletClient.getChainId();
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -1997,7 +2276,7 @@ class PermissionsController {
    */
   async checkServerTrustStatus(serverId, userAddress) {
     try {
-      const user = userAddress ?? await this.getUserAddress();
+      const user = userAddress ?? this.context.userAddress;
       const trustedServers = await this.getTrustedServers(user);
       const trustIndex = trustedServers.findIndex(
         (server) => server === serverId
@@ -2087,7 +2366,7 @@ class PermissionsController {
    * @returns Promise resolving to the EIP-712 domain configuration
    */
   async getServersDomain() {
-    const chainId = await this.context.walletClient.getChainId();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityServersAddress = getContractAddress(
       chainId,
       "DataPortabilityServers"
@@ -2106,7 +2385,8 @@ class PermissionsController {
    * @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 = getContractAddress(
       chainId,
@@ -2138,8 +2418,17 @@ class PermissionsController {
         },
         formattedSignature
       ],
-      account: this.context.walletClient.account ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      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;
   }
@@ -2150,7 +2439,8 @@ class PermissionsController {
    * @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 = getContractAddress(
       chainId,
@@ -2169,8 +2459,9 @@ class PermissionsController {
         },
         formattedSignature
       ],
-      account: this.context.walletClient.account ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      chain: this.context.walletClient?.chain ?? null,
+      ...this.spreadTransactionOptions(options)
     });
     return txHash;
   }
@@ -2181,7 +2472,8 @@ class PermissionsController {
    * @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 = getContractAddress(
       chainId,
@@ -2194,8 +2486,17 @@ class PermissionsController {
       abi: DataPortabilityPermissionsAbi,
       functionName: "revokePermissionWithSignature",
       args: [typedData.message, formattedSignature],
-      account: this.context.walletClient.account ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      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;
   }
@@ -2206,7 +2507,8 @@ class PermissionsController {
    * @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 = getContractAddress(
       chainId,
@@ -2223,8 +2525,17 @@ class PermissionsController {
       abi: DataPortabilityServersAbi,
       functionName: "untrustServerWithSignature",
       args: [contractMessage, formattedSignature],
-      account: this.context.walletClient.account ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      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;
   }
@@ -2237,14 +2548,18 @@ 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
@@ -2256,98 +2571,88 @@ class PermissionsController {
    * console.log(`Grantee registered in transaction: ${txHash}`);
    * ```
    */
-  async submitRegisterGrantee(params) {
-    const chainId = await this.context.walletClient.getChainId();
-    const DataPortabilityGranteesAddress = getContractAddress(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    const DataPortabilityGranteesAbi = getAbi("DataPortabilityGrantees");
-    const ownerAddress = getAddress(params.owner);
-    const granteeAddress = getAddress(params.granteeAddress);
-    const account = this.context.walletClient.account ?? await this.getUserAddress();
-    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"
-    });
-  }
-  /**
-   * 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..."
-   * });
-   * ```
-   */
-  async submitRegisterGranteeWithSignature(params) {
-    const nonce = await this.getServersUserNonce();
-    const owner = getAddress(params.owner);
-    const granteeAddress = getAddress(params.granteeAddress);
-    const registerGranteeInput = {
-      nonce,
-      owner,
-      granteeAddress,
-      publicKey: params.publicKey
-    };
-    const typedData = await this.buildRegisterGranteeTypedData(registerGranteeInput);
-    const signature = await this.signTypedData(typedData);
-    const hash = await this.submitSignedRegisterGranteeTransaction(
-      typedData,
-      signature
-    );
-    const account = this.context.walletClient.account ?? await this.getUserAddress();
-    const { tx } = await import("../utils/transactionHelpers");
-    return tx({
-      hash,
-      from: typeof account === "string" ? account : account.address,
-      contract: "DataPortabilityGrantees",
-      fn: "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);
-   * ```
-   */
-  async submitSignedRegisterGrantee(typedData, signature) {
-    const hash = await this.submitSignedRegisterGranteeTransaction(
-      typedData,
-      signature
-    );
-    const account = this.context.walletClient.account ?? await this.getUserAddress();
-    const { tx } = await import("../utils/transactionHelpers");
-    return tx({
-      hash,
-      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 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 = getContractAddress(
+          chainId,
+          "DataPortabilityGrantees"
+        );
+        const DataPortabilityGranteesAbi = getAbi("DataPortabilityGrantees");
+        const ownerAddress = getAddress(params.owner);
+        const granteeAddress = 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 RelayerError || error instanceof UserRejectedRequestError || error instanceof SerializationError || error instanceof SignatureError || error instanceof BlockchainError) {
+          throw error;
+        }
+        if (error.name === "ContractFunctionExecutionError") {
+          throw new BlockchainError(
+            `Grantee registration failed: ${error.message}`,
+            error
+          );
+        }
+        if (error.name === "UserRejectedRequestError") {
+          throw new UserRejectedRequestError(
+            "User rejected the grantee registration transaction"
+          );
+        }
+        throw new BlockchainError(
+          `Failed to register grantee: ${error.message}`,
+          error
+        );
+      }
+      throw new BlockchainError(`Failed to register grantee: ${String(error)}`);
+    }
   }
+  // TODO: When DataPortabilityGrantees contract adds registerGranteeWithSignature function,
+  // implement submitRegisterGranteeWithSignature and submitSignedRegisterGrantee methods
+  // 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.
    *
@@ -2395,27 +2700,52 @@ class PermissionsController {
     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,
@@ -2426,15 +2756,16 @@ class PermissionsController {
     };
   }
   /**
-   * 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
@@ -2459,40 +2790,32 @@ class PermissionsController {
     );
     const DataPortabilityGranteesAbi = 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
@@ -2500,7 +2823,7 @@ 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 {
@@ -2516,85 +2839,29 @@ class PermissionsController {
     );
     const DataPortabilityGranteesAbi = 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);
       return null;
     }
   }
-  /**
-   * Builds EIP-712 typed data for grantee registration
-   *
-   * @param input - The register grantee input
-   * @returns Promise resolving to the typed data structure
-   * @private
-   */
-  async buildRegisterGranteeTypedData(input) {
-    const chainId = await this.context.walletClient.getChainId();
-    const verifyingContract = getContractAddress(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    return {
-      domain: {
-        name: "DataPortabilityGrantees",
-        version: "1",
-        chainId,
-        verifyingContract
-      },
-      types: {
-        RegisterGrantee: [
-          { name: "nonce", type: "uint256" },
-          { name: "owner", type: "address" },
-          { name: "granteeAddress", type: "address" },
-          { name: "publicKey", type: "string" }
-        ]
-      },
-      primaryType: "RegisterGrantee",
-      message: input
-    };
-  }
-  /**
-   * 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
-   */
-  async submitSignedRegisterGranteeTransaction(typedData, _signature) {
-    const chainId = await this.context.walletClient.getChainId();
-    const DataPortabilityGranteesAddress = getContractAddress(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    const DataPortabilityGranteesAbi = getAbi("DataPortabilityGrantees");
-    const txHash = await this.context.walletClient.writeContract({
-      address: DataPortabilityGranteesAddress,
-      abi: DataPortabilityGranteesAbi,
-      functionName: "registerGrantee",
-      args: [
-        typedData.message.owner,
-        typedData.message.granteeAddress,
-        typedData.message.publicKey
-      ],
-      account: this.context.walletClient.account ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
-    });
-    return txHash;
-  }
   // ===========================
   // DATA PORTABILITY SERVERS HELPER METHODS
   // ===========================
@@ -2606,7 +2873,7 @@ class PermissionsController {
    */
   async getUserServerIds(userAddress) {
     try {
-      const targetAddress = userAddress ?? await this.getUserAddress();
+      const targetAddress = userAddress ?? this.context.userAddress;
       const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
@@ -2664,7 +2931,7 @@ class PermissionsController {
    */
   async getUserServerCount(userAddress) {
     try {
-      const targetAddress = userAddress ?? await this.getUserAddress();
+      const targetAddress = userAddress ?? this.context.userAddress;
       const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
@@ -2693,7 +2960,7 @@ class PermissionsController {
    */
   async getUserTrustedServers(userAddress) {
     try {
-      const targetAddress = userAddress ?? await this.getUserAddress();
+      const targetAddress = userAddress ?? this.context.userAddress;
       const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
@@ -2810,7 +3077,7 @@ class PermissionsController {
    */
   async getUserPermissionIds(userAddress) {
     try {
-      const targetAddress = userAddress ?? await this.getUserAddress();
+      const targetAddress = userAddress ?? this.context.userAddress;
       const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityPermissionsAddress = getContractAddress(
         chainId,
@@ -2872,7 +3139,7 @@ class PermissionsController {
    */
   async getUserPermissionCount(userAddress) {
     try {
-      const targetAddress = userAddress ?? await this.getUserAddress();
+      const targetAddress = userAddress ?? this.context.userAddress;
       const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityPermissionsAddress = getContractAddress(
         chainId,
@@ -2985,6 +3252,31 @@ class PermissionsController {
       );
     }
   }
+  /**
+   * 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)
    *
@@ -3010,26 +3302,34 @@ class PermissionsController {
   // DATA PORTABILITY GRANTEES HELPER METHODS
   // ===========================
   /**
-   * Get grantee information by grantee ID
+   * Retrieves detailed grantee information including all associated permissions.
    *
-   * @param granteeId - Grantee ID to get info for
-   * @returns Promise resolving to grantee info
+   * @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
+   *
+   * @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 = getContractAddress(
-        chainId,
-        "DataPortabilityGrantees"
-      );
-      const DataPortabilityGranteesAbi = 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 BlockchainError(
         `Failed to get grantee info: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3038,10 +3338,21 @@ class PermissionsController {
     }
   }
   /**
-   * 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 {
@@ -3051,13 +3362,26 @@ class PermissionsController {
         "DataPortabilityGrantees"
       );
       const DataPortabilityGranteesAbi = 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 BlockchainError(
         `Failed to get grantee info by address: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3121,6 +3445,117 @@ class PermissionsController {
       );
     }
   }
+  /**
+   * 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 = getContractAddress(
+        chainId,
+        "DataPortabilityGrantees"
+      );
+      const DataPortabilityGranteesAbi = 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 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 BlockchainError(
+        `Failed to get grantee permissions: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
   // ===== DataPortabilityServersImplementation Methods =====
   /**
    * Get all server IDs for a user
@@ -3314,9 +3749,11 @@ 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
    */
-  async submitUpdateServer(serverId, url) {
+  async submitUpdateServer(serverId, url, options) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -3324,14 +3761,25 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const hash = await this.context.walletClient.writeContract({
         address: DataPortabilityServersAddress,
         abi: DataPortabilityServersAbi,
         functionName: "updateServer",
         args: [serverId, url],
-        chain: this.context.walletClient.chain,
-        account
+        chain: this.context.walletClient?.chain,
+        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({
@@ -3489,6 +3937,7 @@ class PermissionsController {
    * @throws {NetworkError} When network communication fails
    */
   async submitAddPermission(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getPermissionsUserNonce();
       const addPermissionInput = {
@@ -3526,21 +3975,36 @@ class PermissionsController {
    * @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;
-      if (this.context.relayerCallbacks?.submitAddPermission) {
-        hash = await this.context.relayerCallbacks.submitAddPermission(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitAddPermission",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitDirectAddPermissionTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
-      const account = this.context.walletClient.account ?? await this.getUserAddress();
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
       return tx({
         hash,
@@ -3578,6 +4042,9 @@ 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.
@@ -3591,6 +4058,7 @@ class PermissionsController {
    *
    * @example
    * ```typescript
+   * // Submit with custom gas parameters and timeout
    * const result = await vana.permissions.submitAddServerFilesAndPermissions({
    *   granteeId: BigInt(1),
    *   grant: "ipfs://QmXxx...",
@@ -3603,12 +4071,20 @@ 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}`);
    * ```
    */
-  async submitAddServerFilesAndPermissions(params) {
+  async submitAddServerFilesAndPermissions(params, options) {
+    this.assertWallet();
     try {
       if (params.schemaIds.length !== params.fileUrls.length) {
         throw new Error(
@@ -3633,7 +4109,8 @@ class PermissionsController {
       const signature = await this.signTypedData(typedData);
       return await this.submitSignedAddServerFilesAndPermissions(
         typedData,
-        signature
+        signature,
+        options
       );
     } catch (error) {
       if (error instanceof RelayerError || error instanceof UserRejectedRequestError || error instanceof SerializationError || error instanceof SignatureError || error instanceof NetworkError || error instanceof NonceError) {
@@ -3654,6 +4131,9 @@ 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
@@ -3672,46 +4152,49 @@ class PermissionsController {
    * console.log(`Permission created with ID: ${permissionId}`);
    * ```
    */
-  async submitSignedAddServerFilesAndPermissions(typedData, signature) {
+  async submitSignedAddServerFilesAndPermissions(typedData, signature, options) {
+    this.assertWallet();
     try {
-      console.debug("\u{1F50D} submitSignedAddServerFilesAndPermissions Debug Info:", {
-        hasRelayerCallbacks: !!this.context.relayerCallbacks,
-        hasSubmitMethod: !!this.context.relayerCallbacks?.submitAddServerFilesAndPermissions,
-        availableRelayerMethods: this.context.relayerCallbacks ? Object.keys(this.context.relayerCallbacks) : []
-      });
-      if (this.context.relayerCallbacks?.submitAddServerFilesAndPermissions) {
+      let hash;
+      if (this.context.relayer) {
         console.debug(
           "\u{1F680} Using relayer for submitAddServerFilesAndPermissions"
         );
-        const hash = await this.context.relayerCallbacks.submitAddServerFilesAndPermissions(
+        const request = {
+          type: "signed",
+          operation: "submitAddServerFilesAndPermissions",
           typedData,
           signature
-        );
-        const account = this.context.walletClient.account ?? await this.getUserAddress();
-        const { tx } = await import("../utils/transactionHelpers");
-        return tx({
-          hash,
-          from: typeof account === "string" ? account : account.address,
-          contract: "DataPortabilityPermissions",
-          fn: "addServerFilesAndPermissions"
-        });
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         console.debug(
           "\u{1F4DD} Using direct transaction for submitAddServerFilesAndPermissions"
         );
-        const hash = await this.submitDirectAddServerFilesAndPermissionsTransaction(
+        hash = await this.submitDirectAddServerFilesAndPermissionsTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
-        const account = this.context.walletClient.account ?? await this.getUserAddress();
-        const { tx } = await import("../utils/transactionHelpers");
-        return tx({
-          hash,
-          from: typeof account === "string" ? account : account.address,
-          contract: "DataPortabilityPermissions",
-          fn: "addServerFilesAndPermissions"
-        });
       }
+      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: "DataPortabilityPermissions",
+        fn: "addServerFilesAndPermissions"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -3726,9 +4209,11 @@ class PermissionsController {
    * 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();
       const DataPortabilityPermissionsAddress = getContractAddress(
@@ -3747,8 +4232,19 @@ class PermissionsController {
         abi: DataPortabilityPermissionsAbi,
         functionName: "revokePermission",
         args: [permissionId],
-        chain: this.context.walletClient.chain,
-        account
+        chain: this.context.walletClient?.chain,
+        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({
@@ -3771,7 +4267,8 @@ class PermissionsController {
    * @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 = getContractAddress(
       chainId,
@@ -3790,8 +4287,9 @@ class PermissionsController {
       abi: DataPortabilityPermissionsAbi,
       functionName: "addPermission",
       args: [permissionInput, formattedSignature],
-      account: this.context.walletClient.account ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      chain: this.context.walletClient?.chain ?? null,
+      ...this.spreadTransactionOptions(options)
     });
     return hash;
   }
@@ -3802,8 +4300,9 @@ class PermissionsController {
    * @param signature - The cryptographic signature authorizing the transaction
    * @returns Promise resolving to the transaction hash
    */
-  async submitDirectAddServerFilesAndPermissionsTransaction(typedData, signature) {
-    const chainId = await this.context.walletClient.getChainId();
+  async submitDirectAddServerFilesAndPermissionsTransaction(typedData, signature, options) {
+    this.assertWallet();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
       "DataPortabilityPermissions"
@@ -3825,10 +4324,11 @@ class PermissionsController {
       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 ?? await this.getUserAddress(),
-      chain: this.context.walletClient.chain ?? null
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      chain: this.context.walletClient?.chain ?? null,
+      ...options?.value && { value: options.value },
+      ...this.spreadTransactionOptions(options)
     });
     return hash;
   }