@opendatalabs/vana-sdk 0.1.0-alpha.2e77fcc → 0.1.0-alpha.3041a59

package/dist/controllers/permissions.cjs

@@ -33,6 +33,7 @@ __export(permissions_exports, {
 module.exports = __toCommonJS(permissions_exports);
 var import_viem = require("viem");
 var import_multicall = require("../utils/multicall");
+var import_pollingManager = require("../core/pollingManager");
 var import_errors = require("../errors");
 var import_addresses = require("../config/addresses");
 var import_abi = require("../generated/abi");
@@ -214,7 +215,7 @@ class PermissionsController extends import_base.BaseController {
           if (response.type === "error") {
             throw new Error(response.error);
           }
-          if (response.type === "direct" && typeof response.result === "object" && "url" in response.result) {
+          if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "url" in response.result) {
             grantUrl = response.result.url;
           } else {
             throw new Error("Invalid response from relayer for grant storage");
@@ -322,7 +323,7 @@ class PermissionsController extends import_base.BaseController {
           if (response.type === "error") {
             throw new Error(response.error);
           }
-          if (response.type === "direct" && typeof response.result === "object" && "url" in response.result) {
+          if (response.type === "direct" && typeof response.result === "object" && response.result !== null && "url" in response.result) {
             grantUrl = response.result.url;
           } else {
             throw new Error("Invalid response from relayer for grant storage");
@@ -421,7 +422,8 @@ class PermissionsController extends import_base.BaseController {
           finalHash = response.hash;
         } else if (response.type === "pending") {
           const pollResult = await this.pollRelayerForConfirmation(
-            response.operationId
+            response.operationId,
+            options
           );
           finalHash = pollResult.hash;
         } else if (response.type === "confirmed") {
@@ -543,7 +545,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedAddAndTrustServer(typedData, signature, _options) {
+  async submitSignedAddAndTrustServer(typedData, signature, options) {
     try {
       const addAndTrustServerInput = {
         nonce: BigInt(typedData.message.nonce),
@@ -553,7 +555,8 @@ class PermissionsController extends import_base.BaseController {
       };
       const hash = await this.submitAddAndTrustServerTransaction(
         addAndTrustServerInput,
-        signature
+        signature,
+        options
       );
       const account = this.context.walletClient?.account ?? this.context.userAddress;
       const { tx } = await import("../utils/transactionHelpers");
@@ -651,34 +654,22 @@ class PermissionsController extends import_base.BaseController {
    * Polls the relayer for confirmation of a pending operation.
    *
    * @param operationId - The operation ID to poll
-   * @returns Promise resolving to the confirmed hash
-   * @throws {Error} When the operation fails or times out
+   * @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 = {}) {
-    const timeout = options.timeout ?? 3e4;
-    let interval = options.pollingInterval ?? 1e3;
-    const startTime = Date.now();
-    while (Date.now() - startTime < timeout) {
-      if (!this.context.relayer) {
-        throw new Error("Relayer not configured for polling");
-      }
-      const statusResponse = await this.context.relayer({
-        type: "status_check",
-        operationId
-      });
-      if (statusResponse.type === "confirmed") {
-        return { hash: statusResponse.hash };
-      }
-      if (statusResponse.type === "error") {
-        throw new Error(
-          `Operation ${operationId} failed: ${statusResponse.error}`
-        );
-      }
-      await new Promise((resolve) => setTimeout(resolve, interval));
-      interval = Math.min(interval * 1.5, 5e3);
+  async pollRelayerForConfirmation(operationId, options) {
+    if (!this.context.relayer) {
+      throw new Error("Relayer not configured for polling");
     }
-    throw new Error(`Operation ${operationId} timed out after ${timeout}ms`);
+    const pollingManager = new import_pollingManager.PollingManager(this.context.relayer);
+    return await pollingManager.startPolling(operationId, {
+      signal: options?.signal,
+      onStatusUpdate: options?.onStatusUpdate,
+      ...options?.pollingOptions
+    });
   }
   /**
    * Submits an already-signed permission revoke transaction to the blockchain.
@@ -701,7 +692,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedRevoke(typedData, signature, _options) {
+  async submitSignedRevoke(typedData, signature, options) {
     try {
       let hash;
       if (this.context.relayer) {
@@ -719,7 +710,8 @@ class PermissionsController extends import_base.BaseController {
           hash = response.hash;
         } else if (response.type === "pending") {
           const pollResult = await this.pollRelayerForConfirmation(
-            response.operationId
+            response.operationId,
+            options
           );
           hash = pollResult.hash;
         } else if (response.type === "confirmed") {
@@ -734,7 +726,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitDirectRevokeTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -776,7 +769,7 @@ class PermissionsController extends import_base.BaseController {
    * const result = await txHandle.waitForEvents();
    * ```
    */
-  async submitSignedUntrustServer(typedData, signature, _options) {
+  async submitSignedUntrustServer(typedData, signature, options) {
     try {
       let hash;
       if (this.context.relayer) {
@@ -787,7 +780,9 @@ class PermissionsController extends import_base.BaseController {
           signature,
           expectedUserAddress: this.context.userAddress
         });
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else if (response.type === "error") {
           throw new Error(`Relayer error: ${response.error}`);
@@ -799,7 +794,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitSignedUntrustTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1021,7 +1017,7 @@ class PermissionsController extends import_base.BaseController {
    * console.log(`Permission ${result.permissionId} revoked`);
    * ```
    */
-  async submitRevokeWithSignature(params) {
+  async submitRevokeWithSignature(params, options) {
     this.assertWallet();
     try {
       if (!this.context.walletClient?.chain?.id) {
@@ -1053,7 +1049,9 @@ class PermissionsController extends import_base.BaseController {
           signature,
           expectedUserAddress: this.context.userAddress
         });
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else if (response.type === "error") {
           throw new Error(`Relayer error: ${response.error}`);
@@ -1065,7 +1063,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitDirectRevokeTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1391,7 +1390,9 @@ class PermissionsController extends import_base.BaseController {
    * ```
    */
   async getUserPermissionGrantsOnChain(options = {}) {
-    const { limit = 50, subgraphUrl } = options;
+    const { limit = 50, fetchAll = false, subgraphUrl } = options;
+    const pageSize = fetchAll ? 100 : limit;
+    const maxResults = fetchAll ? 1e4 : limit;
     try {
       const userAddress = this.context.userAddress;
       const graphqlEndpoint = subgraphUrl ?? this.context.subgraphUrl;
@@ -1401,10 +1402,10 @@ class PermissionsController extends import_base.BaseController {
         );
       }
       const query = `
-        query GetUserPermissions($userId: ID!) {
+        query GetUserPermissions($userId: ID!, $first: Int!, $skip: Int!) {
           user(id: $userId) {
             id
-            permissions {
+            permissions(first: $first, skip: $skip, orderBy: addedAtBlock, orderDirection: desc) {
               id
               grant
               nonce
@@ -1422,34 +1423,82 @@ class PermissionsController extends import_base.BaseController {
           }
         }
       `;
-      const response = await fetch(graphqlEndpoint, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          query,
-          variables: {
-            userId: userAddress.toLowerCase()
+      const allPermissions = [];
+      let currentOffset = 0;
+      if (!fetchAll) {
+        const response = await fetch(graphqlEndpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            query,
+            variables: {
+              userId: userAddress.toLowerCase(),
+              first: limit,
+              skip: 0
+            }
+          })
+        });
+        if (!response.ok) {
+          throw new import_errors.BlockchainError(
+            `Subgraph request failed: ${response.status} ${response.statusText}`
+          );
+        }
+        const result = await response.json();
+        if (result.errors) {
+          throw new import_errors.BlockchainError(
+            `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+          );
+        }
+        const userData = result.data?.user;
+        if (!userData?.permissions?.length) {
+          return [];
+        }
+        allPermissions.push(...userData.permissions);
+      } else {
+        while (allPermissions.length < maxResults) {
+          const currentLimit = Math.min(
+            pageSize,
+            maxResults - allPermissions.length
+          );
+          const response = await fetch(graphqlEndpoint, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              query,
+              variables: {
+                userId: userAddress.toLowerCase(),
+                first: currentLimit,
+                skip: currentOffset
+              }
+            })
+          });
+          if (!response.ok) {
+            throw new import_errors.BlockchainError(
+              `Subgraph request failed: ${response.status} ${response.statusText}`
+            );
           }
-        })
-      });
-      if (!response.ok) {
-        throw new import_errors.BlockchainError(
-          `Subgraph request failed: ${response.status} ${response.statusText}`
-        );
-      }
-      const result = await response.json();
-      if (result.errors) {
-        throw new import_errors.BlockchainError(
-          `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
-        );
-      }
-      const userData = result.data?.user;
-      if (!userData?.permissions?.length) {
-        return [];
+          const result = await response.json();
+          if (result.errors) {
+            throw new import_errors.BlockchainError(
+              `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+            );
+          }
+          const userData = result.data?.user;
+          if (!userData?.permissions?.length) {
+            break;
+          }
+          allPermissions.push(...userData.permissions);
+          if (userData.permissions.length < currentLimit) {
+            break;
+          }
+          currentOffset += userData.permissions.length;
+        }
       }
-      const onChainGrants = userData.permissions.slice(0, limit).map(
+      const onChainGrants = allPermissions.map(
         (permission) => ({
           id: BigInt(permission.id),
           grantUrl: permission.grant,
@@ -1630,7 +1679,7 @@ class PermissionsController extends import_base.BaseController {
    * @param params - Parameters for adding and trusting the server
    * @returns Promise resolving to TransactionResult with ServerTrustResult event data
    */
-  async submitAddAndTrustServerWithSignature(params) {
+  async submitAddAndTrustServerWithSignature(params, options) {
     this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
@@ -1666,7 +1715,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -1674,7 +1725,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitAddAndTrustServerTransaction(
           addAndTrustServerInput,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1713,7 +1765,7 @@ class PermissionsController extends import_base.BaseController {
    * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
    * @throws {BlockchainError} When trust operation fails for any other reason
    */
-  async submitTrustServerWithSignature(params) {
+  async submitTrustServerWithSignature(params, options) {
     this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
@@ -1735,7 +1787,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -1743,7 +1797,8 @@ class PermissionsController extends import_base.BaseController {
       } else {
         hash = await this.submitTrustServerTransaction(
           trustServerInput,
-          signature
+          signature,
+          options
         );
       }
       const account = this.context.walletClient?.account ?? this.context.userAddress;
@@ -1905,7 +1960,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -2351,7 +2408,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature for the transaction
    * @returns Promise resolving to the transaction hash
    */
-  async submitAddAndTrustServerTransaction(addAndTrustServerInput, signature) {
+  async submitAddAndTrustServerTransaction(addAndTrustServerInput, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = (0, import_addresses.getContractAddress)(
@@ -2385,7 +2442,16 @@ class PermissionsController extends import_base.BaseController {
         formattedSignature
       ],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options && {
+        gas: options.gas,
+        nonce: options.nonce,
+        // Use EIP-1559 gas pricing if available, otherwise legacy
+        ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+          maxFeePerGas: options.maxFeePerGas,
+          maxPriorityFeePerGas: options.maxPriorityFeePerGas
+        } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+      }
     });
     return txHash;
   }
@@ -2429,7 +2495,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature authorizing the revoke
    * @returns Promise resolving to the transaction hash
    */
-  async submitDirectRevokeTransaction(typedData, signature) {
+  async submitDirectRevokeTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityPermissionsAddress = (0, import_addresses.getContractAddress)(
@@ -2444,7 +2510,16 @@ class PermissionsController extends import_base.BaseController {
       functionName: "revokePermissionWithSignature",
       args: [typedData.message, formattedSignature],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options && {
+        gas: options.gas,
+        nonce: options.nonce,
+        // Use EIP-1559 gas pricing if available, otherwise legacy
+        ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+          maxFeePerGas: options.maxFeePerGas,
+          maxPriorityFeePerGas: options.maxPriorityFeePerGas
+        } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+      }
     });
     return txHash;
   }
@@ -2455,7 +2530,7 @@ class PermissionsController extends import_base.BaseController {
    * @param signature - The cryptographic signature authorizing the untrust
    * @returns Promise resolving to the transaction hash
    */
-  async submitSignedUntrustTransaction(typedData, signature, _options) {
+  async submitSignedUntrustTransaction(typedData, signature, options) {
     this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = (0, import_addresses.getContractAddress)(
@@ -2474,7 +2549,16 @@ class PermissionsController extends import_base.BaseController {
       functionName: "untrustServerWithSignature",
       args: [contractMessage, formattedSignature],
       account: this.context.walletClient?.account ?? this.context.userAddress,
-      chain: this.context.walletClient?.chain ?? null
+      chain: this.context.walletClient?.chain ?? null,
+      ...options && {
+        gas: options.gas,
+        nonce: options.nonce,
+        // Use EIP-1559 gas pricing if available, otherwise legacy
+        ...options.maxFeePerGas || options.maxPriorityFeePerGas ? {
+          maxFeePerGas: options.maxFeePerGas,
+          maxPriorityFeePerGas: options.maxPriorityFeePerGas
+        } : options.gasPrice ? { gasPrice: options.gasPrice } : {}
+      }
     });
     return txHash;
   }
@@ -2487,6 +2571,9 @@ class PermissionsController extends import_base.BaseController {
    * A grantee is an entity (like an application) that can receive data permissions
    * from users. Once registered, users can grant the grantee access to their data.
    *
+   * This method supports gasless transactions via relayer when configured.
+   * If no relayer is available, it falls back to direct wallet transactions.
+   *
    * @param params - Parameters for registering the grantee
    * @param params.owner - The Ethereum address that will own this grantee registration
    * @param params.granteeAddress - The Ethereum address of the grantee (application)
@@ -2495,7 +2582,7 @@ class PermissionsController extends import_base.BaseController {
    * @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
@@ -2508,36 +2595,87 @@ class PermissionsController extends import_base.BaseController {
    * ```
    */
   async submitRegisterGrantee(params, options) {
-    this.assertWallet();
-    const chainId = await this.context.walletClient.getChainId();
-    const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
-    const ownerAddress = (0, import_viem.getAddress)(params.owner);
-    const granteeAddress = (0, import_viem.getAddress)(params.granteeAddress);
-    const account = this.context.walletClient?.account ?? this.context.userAddress;
-    const txHash = await this.context.walletClient.writeContract({
-      address: DataPortabilityGranteesAddress,
-      abi: DataPortabilityGranteesAbi,
-      functionName: "registerGrantee",
-      args: [ownerAddress, granteeAddress, params.publicKey],
-      account,
-      chain: this.context.walletClient?.chain ?? null,
-      ...this.spreadTransactionOptions(options)
-    });
-    const { tx } = await import("../utils/transactionHelpers");
-    return tx({
-      hash: txHash,
-      from: typeof account === "string" ? account : account.address,
-      contract: "DataPortabilityGrantees",
-      fn: "registerGrantee"
-    });
+    try {
+      let hash;
+      if (this.context.relayer) {
+        const request = {
+          type: "direct",
+          operation: "submitRegisterGrantee",
+          params: {
+            owner: params.owner,
+            granteeAddress: params.granteeAddress,
+            publicKey: params.publicKey
+          }
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new import_errors.RelayerError(response.error);
+        }
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "direct") {
+          const result = response.result;
+          hash = result.transactionHash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
+      } else {
+        this.assertWallet();
+        const chainId = await this.context.walletClient.getChainId();
+        const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
+          chainId,
+          "DataPortabilityGrantees"
+        );
+        const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
+        const ownerAddress = (0, import_viem.getAddress)(params.owner);
+        const granteeAddress = (0, import_viem.getAddress)(params.granteeAddress);
+        const account2 = this.context.walletClient?.account ?? this.context.userAddress;
+        hash = await this.context.walletClient.writeContract({
+          address: DataPortabilityGranteesAddress,
+          abi: DataPortabilityGranteesAbi,
+          functionName: "registerGrantee",
+          args: [ownerAddress, granteeAddress, params.publicKey],
+          account: account2,
+          chain: this.context.walletClient?.chain ?? null,
+          ...this.spreadTransactionOptions(options)
+        });
+      }
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityGrantees",
+        fn: "registerGrantee"
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error instanceof import_errors.RelayerError || error instanceof import_errors.UserRejectedRequestError || error instanceof import_errors.SerializationError || error instanceof import_errors.SignatureError || error instanceof import_errors.BlockchainError) {
+          throw error;
+        }
+        if (error.name === "ContractFunctionExecutionError") {
+          throw new import_errors.BlockchainError(
+            `Grantee registration failed: ${error.message}`,
+            error
+          );
+        }
+        if (error.name === "UserRejectedRequestError") {
+          throw new import_errors.UserRejectedRequestError(
+            "User rejected the grantee registration transaction"
+          );
+        }
+        throw new import_errors.BlockchainError(
+          `Failed to register grantee: ${error.message}`,
+          error
+        );
+      }
+      throw new import_errors.BlockchainError(`Failed to register grantee: ${String(error)}`);
+    }
   }
   // TODO: When DataPortabilityGrantees contract adds registerGranteeWithSignature function,
   // implement submitRegisterGranteeWithSignature and submitSignedRegisterGrantee methods
-  // to support gasless transactions via relayer
+  // to support EIP-712 signed gasless transactions via relayer.
+  // Current implementation above supports direct gasless transactions (relayer pays gas directly).
   /**
    * Retrieves all registered grantees from the DataPortabilityGrantees contract.
    *
@@ -2585,27 +2723,52 @@ class PermissionsController extends import_base.BaseController {
     const total = Number(totalCount);
     const limit = options.limit ?? 50;
     const offset = options.offset ?? 0;
-    const grantees = [];
-    const endIndex = Math.min(offset + limit, total);
-    for (let i = offset; i < endIndex; i++) {
-      try {
-        const granteeInfo = await this.context.publicClient.readContract({
-          address: DataPortabilityGranteesAddress,
-          abi: DataPortabilityGranteesAbi,
-          functionName: "grantees",
-          args: [BigInt(i + 1)]
-          // Grantee IDs are 1-indexed
-        });
-        grantees.push({
-          id: i + 1,
-          owner: granteeInfo.owner,
-          address: granteeInfo.granteeAddress,
-          publicKey: granteeInfo.publicKey,
-          permissionIds: granteeInfo.permissionIds.map((id) => Number(id))
-        });
-      } catch (error) {
-        console.warn(`Failed to fetch grantee ${i + 1}:`, error);
-      }
+    const includePermissions = options.includePermissions ?? true;
+    const startId = total - offset;
+    const endId = Math.max(startId - limit + 1, 1);
+    const granteeIds = Array.from(
+      { length: startId - endId + 1 },
+      (_, i) => startId - i
+      // Generate IDs in descending order
+    );
+    let grantees;
+    if (includePermissions) {
+      const granteePromises = granteeIds.map(
+        (granteeId) => this.getGranteeById(granteeId)
+      );
+      const granteeResults = await Promise.all(granteePromises);
+      grantees = granteeResults.filter(
+        (grantee) => grantee !== null
+      );
+    } else {
+      const granteeInfoPromises = granteeIds.map(
+        async (granteeId) => {
+          try {
+            const granteeInfo = await this.context.publicClient.readContract({
+              address: DataPortabilityGranteesAddress,
+              abi: DataPortabilityGranteesAbi,
+              functionName: "granteesV2",
+              args: [BigInt(granteeId)]
+            });
+            const grantee = {
+              id: granteeId,
+              owner: granteeInfo.owner,
+              address: granteeInfo.granteeAddress,
+              publicKey: granteeInfo.publicKey,
+              permissionIds: []
+              // TypeScript infers number[] from Grantee type
+            };
+            return grantee;
+          } catch (error) {
+            console.warn(`Failed to fetch grantee ${granteeId}:`, error);
+            return null;
+          }
+        }
+      );
+      const granteeInfoResults = await Promise.all(granteeInfoPromises);
+      grantees = granteeInfoResults.filter(
+        (grantee) => grantee !== null
+      );
     }
     return {
       grantees,
@@ -2616,15 +2779,16 @@ class PermissionsController extends import_base.BaseController {
     };
   }
   /**
-   * Retrieves a specific grantee by their Ethereum address from the DataPortabilityGrantees contract.
+   * Retrieves a specific grantee by their Ethereum wallet address.
    *
+   * @remarks
    * Looks up a registered grantee (application) using their Ethereum address
-   * and returns their complete registration information including permissions.
+   * and returns their complete registration information including all associated permissions.
    *
-   * @param granteeAddress - The Ethereum address of the grantee to look up
-   * @returns Promise resolving to the grantee information, or null if not found
-   * @throws {BlockchainError} When contract read operation fails
-   * @throws {NetworkError} When unable to connect to the blockchain network
+   * Returns `null` if the address is not registered as a grantee or if an error occurs.
+   *
+   * @param granteeAddress - Ethereum wallet address of the grantee to query
+   * @returns Grantee information including ID, addresses, public key, and permission IDs, or `null` if not found
    *
    * @example
    * ```typescript
@@ -2649,40 +2813,32 @@ class PermissionsController extends import_base.BaseController {
     );
     const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
     try {
-      const granteeInfo = await this.context.publicClient.readContract({
-        address: DataPortabilityGranteesAddress,
-        abi: DataPortabilityGranteesAbi,
-        functionName: "granteeByAddress",
-        args: [granteeAddress]
-      });
       const granteeId = await this.context.publicClient.readContract({
         address: DataPortabilityGranteesAddress,
         abi: DataPortabilityGranteesAbi,
         functionName: "granteeAddressToId",
         args: [granteeAddress]
       });
-      return {
-        id: Number(granteeId),
-        owner: granteeInfo.owner,
-        address: granteeInfo.granteeAddress,
-        publicKey: granteeInfo.publicKey,
-        permissionIds: granteeInfo.permissionIds.map((id) => Number(id))
-      };
+      if (granteeId === 0n) {
+        return null;
+      }
+      return await this.getGranteeById(Number(granteeId));
     } catch (error) {
       console.warn(`Failed to fetch grantee ${granteeAddress}:`, error);
       return null;
     }
   }
   /**
-   * Retrieves a specific grantee by their unique ID from the DataPortabilityGrantees contract.
+   * Retrieves a specific grantee by their unique ID.
    *
+   * @remarks
    * Looks up a registered grantee (application) using their numeric ID assigned during
-   * registration and returns their complete information including permissions.
+   * registration and returns their complete information including all associated permissions.
    *
-   * @param granteeId - The unique numeric ID of the grantee (1-indexed)
-   * @returns Promise resolving to the grantee information, or null if not found
-   * @throws {BlockchainError} When contract read operation fails
-   * @throws {NetworkError} When unable to connect to the blockchain network
+   * Returns `null` if the grantee is not found or if an error occurs during fetching.
+   *
+   * @param granteeId - Unique numeric ID of the grantee (1-indexed)
+   * @returns Grantee information including ID, addresses, public key, and permission IDs, or `null` if not found
    *
    * @example
    * ```typescript
@@ -2690,7 +2846,7 @@ class PermissionsController extends import_base.BaseController {
    *
    * if (grantee) {
    *   console.log(`Grantee ID: ${grantee.id}`);
-   *   console.log(`Address: ${grantee.granteeAddress}`);
+   *   console.log(`Address: ${grantee.address}`);
    *   console.log(`Owner: ${grantee.owner}`);
    *   console.log(`Total permissions: ${grantee.permissionIds.length}`);
    * } else {
@@ -2706,18 +2862,23 @@ class PermissionsController extends import_base.BaseController {
     );
     const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
     try {
-      const granteeInfo = await this.context.publicClient.readContract({
+      const granteeInfoResult = await this.context.publicClient.readContract({
         address: DataPortabilityGranteesAddress,
         abi: DataPortabilityGranteesAbi,
-        functionName: "grantees",
+        functionName: "granteesV2",
         args: [BigInt(granteeId)]
       });
+      const granteeInfo = granteeInfoResult;
+      const allPermissionIdsResult = await this.getGranteePermissionsPaginated(
+        BigInt(granteeId)
+      );
+      const allPermissionIds = allPermissionIdsResult;
       return {
         id: granteeId,
         owner: granteeInfo.owner,
         address: granteeInfo.granteeAddress,
         publicKey: granteeInfo.publicKey,
-        permissionIds: granteeInfo.permissionIds.map((id) => Number(id))
+        permissionIds: allPermissionIds.map((id) => Number(id))
       };
     } catch (error) {
       console.warn(`Failed to fetch grantee ${granteeId}:`, error);
@@ -3114,6 +3275,31 @@ class PermissionsController extends import_base.BaseController {
       );
     }
   }
+  /**
+   * Retrieves detailed grant file data from IPFS or HTTP storage.
+   *
+   * @remarks
+   * This method automatically uses the SDK's configured downloadRelayer to bypass CORS restrictions.
+   * Use this instead of importing the standalone `retrieveGrantFile` utility.
+   *
+   * @param grantUrl - The grant file URL (from OnChainPermissionGrant.grantUrl)
+   * @returns Promise resolving to the complete grant file with operation details
+   * @throws {NetworkError} When all retrieval attempts fail
+   * @example
+   * ```typescript
+   * const grants = await vana.permissions.getUserPermissionGrantsOnChain();
+   * const grantFile = await vana.permissions.retrieveGrantFile(grants[0].grantUrl);
+   * console.log(`Operation: ${grantFile.operation}`);
+   * ```
+   */
+  async retrieveGrantFile(grantUrl) {
+    const { retrieveGrantFile: retrieveGrantFileUtil } = await import("../utils/grantFiles");
+    return retrieveGrantFileUtil(
+      grantUrl,
+      void 0,
+      this.context.downloadRelayer
+    );
+  }
   /**
    * Get all permissions for a specific file (alias for getFilePermissionIds)
    *
@@ -3139,26 +3325,34 @@ class PermissionsController extends import_base.BaseController {
   // DATA PORTABILITY GRANTEES HELPER METHODS
   // ===========================
   /**
-   * Get grantee information by grantee ID
+   * Retrieves detailed grantee information including all associated permissions.
+   *
+   * @remarks
+   * Returns grantee metadata and associated permission IDs. Uses the newer
+   * paginated contract method internally for efficient permission fetching.
+   *
+   * @param granteeId - Unique grantee identifier as bigint
+   * @returns Grantee information containing owner address, grantee address, public key, and permission IDs
+   * @throws {BlockchainError} When grantee ID is not found or contract read fails
    *
-   * @param granteeId - Grantee ID to get info for
-   * @returns Promise resolving to grantee info
+   * @example
+   * ```typescript
+   * const granteeInfo = await vana.permissions.getGranteeInfo(BigInt(1));
+   * console.log(`Grantee ${granteeInfo.granteeAddress} has ${granteeInfo.permissionIds.length} permissions`);
+   * ```
    */
   async getGranteeInfo(granteeId) {
     try {
-      const chainId = await this.context.publicClient.getChainId();
-      const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
-        chainId,
-        "DataPortabilityGrantees"
-      );
-      const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
-      const granteeInfo = await this.context.publicClient.readContract({
-        address: DataPortabilityGranteesAddress,
-        abi: DataPortabilityGranteesAbi,
-        functionName: "granteeInfo",
-        args: [granteeId]
-      });
-      return granteeInfo;
+      const grantee = await this.getGranteeById(Number(granteeId));
+      if (!grantee) {
+        throw new Error("Grantee not found");
+      }
+      return {
+        owner: grantee.owner,
+        granteeAddress: grantee.address,
+        publicKey: grantee.publicKey,
+        permissionIds: grantee.permissionIds.map((id) => BigInt(id))
+      };
     } catch (error) {
       throw new import_errors.BlockchainError(
         `Failed to get grantee info: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3167,10 +3361,21 @@ class PermissionsController extends import_base.BaseController {
     }
   }
   /**
-   * Get grantee information by grantee address
+   * Retrieves detailed grantee information by wallet address.
    *
-   * @param granteeAddress - Grantee address to get info for
-   * @returns Promise resolving to grantee info
+   * @remarks
+   * Looks up the grantee ID from the provided address, then fetches complete
+   * grantee information including all associated permissions.
+   *
+   * @param granteeAddress - Ethereum wallet address of the grantee to query
+   * @returns Grantee information containing owner address, grantee address, public key, and permission IDs
+   * @throws {BlockchainError} When grantee address is not registered or contract read fails
+   *
+   * @example
+   * ```typescript
+   * const granteeInfo = await vana.permissions.getGranteeInfoByAddress("0x742d35Cc6634c0532925a3b844Bc9e8e1ee3b2De");
+   * console.log(`Found grantee with ${granteeInfo.permissionIds.length} permissions`);
+   * ```
    */
   async getGranteeInfoByAddress(granteeAddress) {
     try {
@@ -3180,13 +3385,26 @@ class PermissionsController extends import_base.BaseController {
         "DataPortabilityGrantees"
       );
       const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
-      const granteeInfo = await this.context.publicClient.readContract({
+      const granteeIdResult = await this.context.publicClient.readContract({
         address: DataPortabilityGranteesAddress,
         abi: DataPortabilityGranteesAbi,
-        functionName: "granteeByAddress",
+        functionName: "granteeAddressToId",
         args: [granteeAddress]
       });
-      return granteeInfo;
+      const granteeId = granteeIdResult;
+      if (granteeId === 0n) {
+        throw new Error("Grantee not found");
+      }
+      const grantee = await this.getGranteeById(Number(granteeId));
+      if (!grantee) {
+        throw new Error("Grantee not found");
+      }
+      return {
+        owner: grantee.owner,
+        granteeAddress: grantee.address,
+        publicKey: grantee.publicKey,
+        permissionIds: grantee.permissionIds.map((id) => BigInt(id))
+      };
     } catch (error) {
       throw new import_errors.BlockchainError(
         `Failed to get grantee info by address: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3250,6 +3468,117 @@ class PermissionsController extends import_base.BaseController {
       );
     }
   }
+  /**
+   * Retrieves permission IDs for a specific grantee with flexible pagination.
+   *
+   * @remarks
+   * **Pagination Behavior:**
+   * Returns different types based on parameters:
+   * - Without offset/limit: Returns `bigint[]` of all permissions using batched multicall
+   * - With offset/limit: Returns paginated object with `permissionIds`, `totalCount`, and `hasMore`
+   *
+   * Uses gas-aware multicall for efficient batch fetching when retrieving all permissions.
+   *
+   * @param granteeId - Grantee ID to get permissions for
+   * @param options - Optional pagination parameters
+   * @param options.offset - Zero-based starting index for pagination. Defaults to 0 when fetching all permissions. Required for single-page requests.
+   * @param options.limit - Maximum number of permission IDs to return per page. Defaults to 100 when fetching all permissions. Required for single-page requests.
+   * @returns When called without options: Array of all permission IDs as `bigint[]`.
+   *   When called with offset and limit: Paginated result object containing `permissionIds` array,
+   *   `totalCount`, and `hasMore` boolean.
+   * @throws {BlockchainError} When contract read operation fails
+   *
+   * @example
+   * ```typescript
+   * // Fetch all permissions (no pagination params)
+   * const allPermissions = await vana.permissions.getGranteePermissionsPaginated(BigInt(1));
+   * console.log(`Total permissions: ${allPermissions.length}`);
+   *
+   * // Fetch a specific page (with pagination params)
+   * const page = await vana.permissions.getGranteePermissionsPaginated(BigInt(1), {
+   *   offset: BigInt(0),
+   *   limit: BigInt(100)
+   * });
+   * console.log(`Fetched ${page.permissionIds.length} permissions`);
+   * console.log(`Total: ${page.totalCount}, Has more: ${page.hasMore}`);
+   *
+   * // Fetch next page
+   * if (page.hasMore) {
+   *   const nextPage = await vana.permissions.getGranteePermissionsPaginated(BigInt(1), {
+   *     offset: BigInt(100),
+   *     limit: BigInt(100)
+   *   });
+   * }
+   * ```
+   */
+  async getGranteePermissionsPaginated(granteeId, options) {
+    try {
+      const chainId = await this.context.publicClient.getChainId();
+      const DataPortabilityGranteesAddress = (0, import_addresses.getContractAddress)(
+        chainId,
+        "DataPortabilityGrantees"
+      );
+      const DataPortabilityGranteesAbi = (0, import_abi.getAbi)("DataPortabilityGrantees");
+      const fetchOnlyOnePage = options?.offset !== void 0 && options?.limit !== void 0;
+      if (fetchOnlyOnePage) {
+        const result = await this.context.publicClient.readContract({
+          address: DataPortabilityGranteesAddress,
+          abi: DataPortabilityGranteesAbi,
+          functionName: "granteePermissionsPaginated",
+          args: [granteeId, options.offset, options.limit]
+        });
+        const [permissionIds, totalCount2, hasMore] = result;
+        return {
+          permissionIds: [...permissionIds],
+          totalCount: totalCount2,
+          hasMore
+        };
+      }
+      const countResult = await this.context.publicClient.readContract({
+        address: DataPortabilityGranteesAddress,
+        abi: DataPortabilityGranteesAbi,
+        functionName: "granteePermissionsPaginated",
+        args: [granteeId, BigInt(0), BigInt(1)]
+      });
+      const [, totalCount] = countResult;
+      if (totalCount === BigInt(0)) {
+        return [];
+      }
+      const batchSize = options?.limit ?? BigInt(100);
+      const startOffset = options?.offset ?? BigInt(0);
+      const endOffset = totalCount;
+      const numBatches = Math.ceil(
+        Number(endOffset - startOffset) / Number(batchSize)
+      );
+      const paginationCalls = Array.from({ length: numBatches }, (_, i) => ({
+        address: DataPortabilityGranteesAddress,
+        abi: DataPortabilityGranteesAbi,
+        functionName: "granteePermissionsPaginated",
+        args: [
+          granteeId,
+          startOffset + BigInt(i) * batchSize,
+          batchSize
+        ]
+      }));
+      const results = await (0, import_multicall.gasAwareMulticall)(
+        this.context.publicClient,
+        {
+          contracts: paginationCalls
+        }
+      );
+      const allPermissionIds = [];
+      for (const result of results) {
+        const [permissionIds] = result;
+        allPermissionIds.push(...permissionIds);
+      }
+      return allPermissionIds;
+    } catch (error) {
+      throw new import_errors.BlockchainError(
+        `Failed to get grantee permissions: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
   // ===== DataPortabilityServersImplementation Methods =====
   /**
    * Get all server IDs for a user
@@ -3684,7 +4013,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");
@@ -3862,7 +4193,9 @@ class PermissionsController extends import_base.BaseController {
         if (response.type === "error") {
           throw new import_errors.RelayerError(response.error);
         }
-        if (response.type === "signed") {
+        if (response.type === "submitted") {
+          hash = response.hash;
+        } else if (response.type === "signed") {
           hash = response.hash;
         } else {
           throw new Error("Unexpected response type from relayer");