@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dc68f39

package/dist/controllers/permissions.js

@@ -18,9 +18,10 @@ 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.
@@ -57,7 +58,10 @@ class PermissionsController {
    * ```
    */
   async grant(params) {
-    return await this.submitPermissionGrant(params);
+    this.assertWallet();
+    const { typedData, signature } = await this.createAndSign(params);
+    const result = await this.submitSignedGrantWithEvents(typedData, signature);
+    return result;
   }
   /**
    * Submits a permission grant transaction and returns a handle for flexible result access.
@@ -85,6 +89,7 @@ class PermissionsController {
    * ```
    */
   async submitPermissionGrant(params) {
+    this.assertWallet();
     const { typedData, signature } = await this.createAndSign(params);
     return await this.submitSignedGrant(typedData, signature);
   }
@@ -114,13 +119,14 @@ class PermissionsController {
    * ```
    */
   async prepareGrant(params) {
+    this.assertWallet();
     try {
       const grantFile = createGrantFile(params);
       validateGrant(grantFile);
       return {
         preview: grantFile,
         confirm: async () => {
-          return await this.confirmGrantInternal(params, grantFile);
+          return await this.confirmGrantInternalWithEvents(params, grantFile);
         }
       };
     } catch (error) {
@@ -154,7 +160,7 @@ class PermissionsController {
    */
   async confirmGrantInternal(params, grantFile) {
     try {
-      let grantUrl = params.grantUrl;
+      let { grantUrl } = params;
       console.debug("\u{1F50D} Debug - Grant URL from params:", grantUrl);
       if (!grantUrl) {
         if (!this.context.relayerCallbacks?.storeGrantFile && !this.context.storageManager) {
@@ -244,10 +250,11 @@ class PermissionsController {
    * ```
    */
   async createAndSign(params) {
+    this.assertWallet();
     try {
       const grantFile = createGrantFile(params);
       validateGrant(grantFile);
-      let grantUrl = params.grantUrl;
+      let { grantUrl } = params;
       console.debug("\u{1F50D} Debug - Grant URL from params:", grantUrl);
       if (!grantUrl) {
         if (!this.context.relayerCallbacks?.storeGrantFile && !this.context.storageManager) {
@@ -335,23 +342,26 @@ class PermissionsController {
         "\u{1F50D} Debug - submitSignedGrant called with typed data:",
         JSON.stringify(
           typedData,
-          (key, value) => typeof value === "bigint" ? value.toString() : value,
+          (_key, value) => typeof value === "bigint" ? value.toString() : value,
           2
         )
       );
-      let hash;
       if (this.context.relayerCallbacks?.submitPermissionGrant) {
-        hash = await this.context.relayerCallbacks.submitPermissionGrant(
+        const hash = await this.context.relayerCallbacks.submitPermissionGrant(
           typedData,
           signature
         );
+        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: "addPermission"
+        });
       } else {
-        hash = await this.submitDirectTransaction(typedData, signature);
+        return await this.submitDirectTransaction(typedData, signature);
       }
-      return {
-        hash,
-        from: this.context.walletClient.account?.address
-      };
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -393,10 +403,14 @@ class PermissionsController {
         trustServerInput,
         signature
       );
-      return {
+      const account = this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: account,
+        contract: "DataPortabilityServers",
+        fn: "trustServerWithSignature"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -454,10 +468,14 @@ class PermissionsController {
         addAndTrustServerInput,
         signature
       );
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "addAndTrustServerWithSignature"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -468,6 +486,72 @@ class PermissionsController {
       );
     }
   }
+  /**
+   * Internal method to submit a signed grant and wait for events.
+   *
+   * @internal
+   * @param typedData - The EIP-712 typed data for the permission grant
+   * @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);
+    if (!this.context.waitForTransactionEvents) {
+      throw new BlockchainError("waitForTransactionEvents not configured");
+    }
+    const result = await this.context.waitForTransactionEvents(txResult);
+    const event = result.expectedEvents.PermissionAdded;
+    if (!event) {
+      throw new BlockchainError(
+        "PermissionAdded event not found in transaction"
+      );
+    }
+    const receipt = await this.context.publicClient.getTransactionReceipt({
+      hash: result.hash
+    });
+    return {
+      transactionHash: result.hash,
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+      permissionId: event.permissionId,
+      user: event.user,
+      grant: event.grant,
+      fileIds: event.fileIds
+    };
+  }
+  /**
+   * Internal method for confirm grant with events.
+   *
+   * @internal
+   * @param params - The permission grant parameters
+   * @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);
+    if (!this.context.waitForTransactionEvents) {
+      throw new BlockchainError("waitForTransactionEvents not configured");
+    }
+    const result = await this.context.waitForTransactionEvents(txResult);
+    const event = result.expectedEvents.PermissionAdded;
+    if (!event) {
+      throw new BlockchainError(
+        "PermissionAdded event not found in transaction"
+      );
+    }
+    const receipt = await this.context.publicClient.getTransactionReceipt({
+      hash: result.hash
+    });
+    return {
+      transactionHash: result.hash,
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+      permissionId: event.permissionId,
+      user: event.user,
+      grant: event.grant,
+      fileIds: event.fileIds
+    };
+  }
   /**
    * Submits an already-signed permission revoke transaction to the blockchain.
    *
@@ -498,12 +582,19 @@ class PermissionsController {
           signature
         );
       } else {
-        hash = await this.submitDirectRevokeTransaction(typedData, signature);
+        hash = await this.submitDirectRevokeTransaction(
+          typedData,
+          signature
+        );
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityPermissions",
+        fn: "revokePermissionWithSignature"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -544,12 +635,19 @@ class PermissionsController {
           signature
         );
       } else {
-        hash = await this.submitSignedUntrustTransaction(typedData, signature);
+        hash = await this.submitSignedUntrustTransaction(
+          typedData,
+          signature
+        );
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "untrustServerWithSignature"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -573,7 +671,8 @@ class PermissionsController {
    * @throws {BlockchainError} When contract submission fails
    */
   async submitDirectTransaction(typedData, signature) {
-    const chainId = await this.context.walletClient.getChainId();
+    this.assertWallet();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
       "DataPortabilityPermissions"
@@ -593,18 +692,25 @@ class PermissionsController {
     console.debug("\u{1F50D} Debug - Grant field value:", typedData.message.grant);
     console.debug(
       "\u{1F50D} Debug - Grant field length:",
-      typedData.message.grant?.length || 0
+      typedData.message.grant?.length ?? 0
     );
     const formattedSignature = formatSignatureForContract(signature);
+    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: this.context.walletClient.account || await this.getUserAddress(),
-      chain: this.context.walletClient.chain || null
+      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: "DataPortabilityPermissions",
+      fn: "addPermission"
     });
-    return txHash;
   }
   /**
    * Revokes a previously granted permission.
@@ -631,7 +737,27 @@ class PermissionsController {
    * ```
    */
   async revoke(params) {
-    return await this.submitPermissionRevoke(params);
+    this.assertWallet();
+    const txResult = await this.submitPermissionRevoke(params);
+    if (!this.context.waitForTransactionEvents) {
+      throw new BlockchainError("waitForTransactionEvents not configured");
+    }
+    const result = await this.context.waitForTransactionEvents(txResult);
+    const event = result.expectedEvents.PermissionRevoked;
+    if (!event) {
+      throw new BlockchainError(
+        "PermissionRevoked event not found in transaction"
+      );
+    }
+    const receipt = await this.context.publicClient.getTransactionReceipt({
+      hash: result.hash
+    });
+    return {
+      transactionHash: result.hash,
+      blockNumber: receipt.blockNumber,
+      gasUsed: receipt.gasUsed,
+      permissionId: event.permissionId
+    };
   }
   /**
    * Submits a permission revocation transaction and returns the transaction hash immediately.
@@ -640,6 +766,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
@@ -652,12 +779,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"
@@ -665,18 +793,33 @@ class PermissionsController {
       const DataPortabilityPermissionsAbi = getAbi(
         "DataPortabilityPermissions"
       );
+      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: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient?.chain ?? null,
+        ...options?.gasLimit && { gas: options.gasLimit },
+        ...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 }
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash: txHash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityPermissions",
+        fn: "revokePermission"
+      });
     } 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) {
@@ -716,8 +859,9 @@ class PermissionsController {
    * ```
    */
   async submitRevokeWithSignature(params) {
+    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();
@@ -744,12 +888,19 @@ class PermissionsController {
           signature
         );
       } else {
-        hash = await this.submitDirectRevokeTransaction(typedData, signature);
+        hash = await this.submitDirectRevokeTransaction(
+          typedData,
+          signature
+        );
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityPermissions",
+        fn: "revokePermissionWithSignature"
+      });
     } catch (error) {
       throw new PermissionError(
         `Failed to revoke permission with signature: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -757,64 +908,6 @@ class PermissionsController {
       );
     }
   }
-  /**
-   * @deprecated Use getPermissionsUserNonce() for permission operations or getServersUserNonce() for server operations
-   *
-   * Retrieves the user's current nonce from the DataPortabilityServers contract.
-   * This method is deprecated in favor of more specific nonce methods.
-   *
-   * The nonce is used to prevent replay attacks in signed transactions and must
-   * be incremented with each transaction to maintain security.
-   *
-   * @returns Promise resolving to the user's current nonce value as a bigint
-   * @throws {Error} When wallet account is not available
-   * @throws {Error} When chain ID is not available
-   * @throws {NonceError} When reading nonce from contract fails
-   * @private
-   * @example
-   * ```typescript
-   * // Deprecated - use specific methods instead
-   * const nonce = await this.getUserNonce();
-   *
-   * // Use these instead:
-   * const permissionsNonce = await this.getPermissionsUserNonce();
-   * const serversNonce = await this.getServersUserNonce();
-   * ```
-   */
-  /**
-   * @deprecated Use getPermissionsUserNonce() for permission operations or getServersUserNonce() for server operations
-   *
-   * Retrieves the user's current nonce from the DataPortabilityServers contract.
-   *
-   * @remarks
-   * This method is deprecated in favor of more specific nonce methods that target
-   * the appropriate contract for the operation being performed.
-   *
-   * @returns Promise resolving to the user's current nonce as a bigint
-   * @throws {NonceError} When retrieving the nonce fails
-   */
-  async getUserNonce() {
-    try {
-      const userAddress = await this.getUserAddress();
-      const chainId = await this.context.walletClient.getChainId();
-      const DataPortabilityServersAddress = getContractAddress(
-        chainId,
-        "DataPortabilityServers"
-      );
-      const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
-      const nonce = await this.context.publicClient.readContract({
-        address: DataPortabilityServersAddress,
-        abi: DataPortabilityServersAbi,
-        functionName: "userNonce",
-        args: [userAddress]
-      });
-      return nonce;
-    } catch (error) {
-      throw new NonceError(
-        `Failed to retrieve user nonce: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
   /**
    * Retrieves the user's current nonce from the DataPortabilityServers contract.
    * This nonce is used for server-related operations (AddAndTrustServer, TrustServer, UntrustServer).
@@ -841,8 +934,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"
@@ -887,8 +980,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"
@@ -927,7 +1020,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"
@@ -1036,7 +1129,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"
@@ -1055,8 +1148,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,
@@ -1065,9 +1159,9 @@ class PermissionsController {
           const viemCompatibleTypedData = toViemTypedDataDefinition(typedData);
           return await this.context.walletClient.signTypedData({
             ...viemCompatibleTypedData,
-            // Non-null assertion is safe here because getUserAddress() above ensures account exists
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            account: this.context.walletClient.account
+            // Use the account if available, otherwise use the wallet address
+            // This follows the same pattern used throughout this file
+            account: this.context.walletClient.account ?? walletAddress
           });
         }
       );
@@ -1082,17 +1176,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.
    *
@@ -1131,8 +1218,8 @@ class PermissionsController {
   async getUserPermissionGrantsOnChain(options = {}) {
     const { limit = 50, subgraphUrl } = options;
     try {
-      const userAddress = await this.getUserAddress();
-      const graphqlEndpoint = subgraphUrl || this.context.subgraphUrl;
+      const userAddress = this.context.userAddress;
+      const graphqlEndpoint = subgraphUrl ?? this.context.subgraphUrl;
       if (!graphqlEndpoint) {
         throw new BlockchainError(
           "subgraphUrl is required. Please provide a valid subgraph endpoint or configure it in Vana constructor."
@@ -1184,7 +1271,7 @@ class PermissionsController {
         );
       }
       const userData = result.data?.user;
-      if (!userData || !userData.permissions?.length) {
+      if (!userData?.permissions?.length) {
         return [];
       }
       const onChainGrants = userData.permissions.slice(0, limit).map(
@@ -1195,8 +1282,8 @@ class PermissionsController {
           nonce: BigInt(permission.nonce),
           startBlock: BigInt(permission.startBlock),
           addedAtBlock: BigInt(permission.addedAtBlock),
-          addedAtTimestamp: BigInt(permission.addedAtTimestamp || "0"),
-          transactionHash: permission.transactionHash || "",
+          addedAtTimestamp: BigInt(permission.addedAtTimestamp ?? "0"),
+          transactionHash: permission.transactionHash ?? "",
           grantor: userAddress,
           grantee: permission.grantee,
           active: !permission.endBlock || BigInt(permission.endBlock) === 0n
@@ -1217,26 +1304,6 @@ class PermissionsController {
       );
     }
   }
-  /**
-   * Normalizes grant ID to hex format.
-   * Handles conversion from permission ID (bigint/number/string) to proper hex hash format.
-   *
-   * @param grantId - Permission ID or grant hash in various formats
-   * @returns Normalized hex hash
-   */
-  normalizeGrantId(grantId) {
-    if (typeof grantId === "string" && grantId.startsWith("0x") && grantId.length === 66) {
-      return grantId;
-    }
-    try {
-      const bigIntId = BigInt(grantId);
-      return `0x${bigIntId.toString(16).padStart(64, "0")}`;
-    } catch {
-      throw new Error(
-        `Invalid grant ID format: ${grantId}. Must be a permission ID (number/bigint/string) or a 32-byte hex hash.`
-      );
-    }
-  }
   /**
    * Registers a new server and immediately trusts it in the DataPortabilityServers contract.
    *
@@ -1245,7 +1312,6 @@ class PermissionsController {
    * Trusted servers can handle data export and portability requests from the user.
    *
    * @param params - Parameters for adding and trusting the server
-   * @param params.owner - Ethereum address that will own this server registration
    * @param params.serverAddress - Ethereum address of the server
    * @param params.serverUrl - HTTPS URL where the server can be reached
    * @param params.publicKey - Server's public key for encryption (hex string)
@@ -1272,6 +1338,7 @@ class PermissionsController {
    * ```
    */
   async addAndTrustServer(params) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1279,7 +1346,8 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
-      const userAddress = this.context.walletClient.account?.address || 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);
       const txHash = await this.context.walletClient.writeContract({
@@ -1294,12 +1362,40 @@ class PermissionsController {
             publicKey: params.publicKey
           }
         ],
-        account: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient?.chain ?? null
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      const txResult = tx({
         hash: txHash,
-        from: this.context.walletClient.account?.address
+        from: userAddress,
+        contract: "DataPortabilityServers",
+        fn: "addAndTrustServerByManager"
+      });
+      if (!this.context.waitForTransactionEvents) {
+        throw new BlockchainError("waitForTransactionEvents not configured");
+      }
+      const result = await this.context.waitForTransactionEvents(txResult);
+      const event = result.expectedEvents.ServerTrusted;
+      if (!event) {
+        throw new BlockchainError(
+          "ServerTrusted event not found in transaction"
+        );
+      }
+      const receipt = await this.context.publicClient.getTransactionReceipt({
+        hash: txHash
+      });
+      return {
+        transactionHash: txHash,
+        blockNumber: receipt.blockNumber,
+        gasUsed: receipt.gasUsed,
+        user: event.user,
+        serverId: event.serverId,
+        // bigint from event
+        serverAddress: normalizedServerAddress,
+        // derived from params
+        serverUrl: params.serverUrl
+        // provided in params
       };
     } catch (error) {
       if (error instanceof Error && error.message.includes("rejected")) {
@@ -1319,6 +1415,7 @@ class PermissionsController {
    * @deprecated Use addAndTrustServer instead
    */
   async submitTrustServer(params) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1326,18 +1423,22 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
+      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: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient?.chain ?? null
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash: txHash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "trustServer"
+      });
     } catch (error) {
       if (error instanceof Error && error.message.includes("rejected")) {
         throw new UserRejectedRequestError();
@@ -1355,6 +1456,7 @@ class PermissionsController {
    * @returns Promise resolving to TransactionResult with ServerTrustResult event data
    */
   async submitAddAndTrustServerWithSignature(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
       const serverAddress = getAddress(params.serverAddress);
@@ -1389,10 +1491,14 @@ class PermissionsController {
           signature
         );
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "addAndTrustServerWithSignature"
+      });
     } 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) {
@@ -1422,6 +1528,7 @@ class PermissionsController {
    * @throws {BlockchainError} When trust operation fails for any other reason
    */
   async submitTrustServerWithSignature(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
       const trustServerInput = {
@@ -1442,10 +1549,14 @@ class PermissionsController {
           signature
         );
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "trustServerWithSignature"
+      });
     } 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) {
@@ -1476,7 +1587,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(
@@ -1484,18 +1596,33 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
+      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: this.context.walletClient.account || await this.getUserAddress(),
-        chain: this.context.walletClient.chain || null
+        account,
+        chain: this.context.walletClient?.chain ?? null,
+        ...options?.gasLimit && { gas: options.gasLimit },
+        ...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 }
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash: txHash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "untrustServer"
+      });
     } catch (error) {
       if (error instanceof Error && error.message.includes("rejected")) {
         throw new UserRejectedRequestError();
@@ -1514,6 +1641,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
@@ -1534,13 +1662,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).
@@ -1555,6 +1687,7 @@ class PermissionsController {
    * @throws {BlockchainError} When untrust transaction fails
    */
   async submitUntrustServerWithSignature(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
       const untrustServerInput = {
@@ -1572,10 +1705,14 @@ class PermissionsController {
       } else {
         hash = await this.submitSignedUntrustTransaction(typedData, signature);
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "untrustServerWithSignature"
+      });
     } 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) {
@@ -1613,8 +1750,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"
@@ -1643,8 +1780,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"
@@ -1673,10 +1810,10 @@ class PermissionsController {
    */
   async getTrustedServersPaginated(options = {}) {
     try {
-      const user = options.userAddress || await this.getUserAddress();
-      const limit = options.limit || 50;
-      const offset = options.offset || 0;
-      const chainId = await this.context.walletClient.getChainId();
+      const user = options.userAddress ?? this.context.userAddress;
+      const limit = options.limit ?? 50;
+      const offset = options.offset ?? 0;
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -1822,7 +1959,7 @@ class PermissionsController {
       };
     }
     try {
-      const chainId = await this.context.walletClient.getChainId();
+      const chainId = await this.context.publicClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
         chainId,
         "DataPortabilityServers"
@@ -1897,7 +2034,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
@@ -1987,7 +2124,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"
@@ -2007,6 +2144,7 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    */
   async submitAddAndTrustServerTransaction(addAndTrustServerInput, signature) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = getContractAddress(
       chainId,
@@ -2038,8 +2176,8 @@ 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
     });
     return txHash;
   }
@@ -2051,6 +2189,7 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    */
   async submitTrustServerTransaction(trustServerInput, signature) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = getContractAddress(
       chainId,
@@ -2069,8 +2208,8 @@ 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
     });
     return txHash;
   }
@@ -2082,6 +2221,7 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    */
   async submitDirectRevokeTransaction(typedData, signature) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
@@ -2093,10 +2233,9 @@ class PermissionsController {
       address: DataPortabilityPermissionsAddress,
       abi: DataPortabilityPermissionsAbi,
       functionName: "revokePermissionWithSignature",
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       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
     });
     return txHash;
   }
@@ -2108,6 +2247,7 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    */
   async submitSignedUntrustTransaction(typedData, signature) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityServersAddress = getContractAddress(
       chainId,
@@ -2115,14 +2255,17 @@ class PermissionsController {
     );
     const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
     const formattedSignature = formatSignatureForContract(signature);
+    const contractMessage = {
+      nonce: typedData.message.nonce,
+      serverId: BigInt(typedData.message.serverId)
+    };
     const txHash = await this.context.walletClient.writeContract({
       address: DataPortabilityServersAddress,
       abi: DataPortabilityServersAbi,
       functionName: "untrustServerWithSignature",
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      args: [typedData.message, formattedSignature],
-      account: this.context.walletClient.account || await this.getUserAddress(),
-      chain: this.context.walletClient.chain || null
+      args: [contractMessage, formattedSignature],
+      account: this.context.walletClient?.account ?? this.context.userAddress,
+      chain: this.context.walletClient?.chain ?? null
     });
     return txHash;
   }
@@ -2139,6 +2282,7 @@ class PermissionsController {
    * @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
@@ -2154,7 +2298,8 @@ class PermissionsController {
    * console.log(`Grantee registered in transaction: ${txHash}`);
    * ```
    */
-  async submitRegisterGrantee(params) {
+  async submitRegisterGrantee(params, options) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityGranteesAddress = getContractAddress(
       chainId,
@@ -2163,18 +2308,31 @@ class PermissionsController {
     const DataPortabilityGranteesAbi = getAbi("DataPortabilityGrantees");
     const ownerAddress = getAddress(params.owner);
     const granteeAddress = 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: this.context.walletClient.account || await this.getUserAddress(),
-      chain: this.context.walletClient.chain || null
+      account,
+      chain: this.context.walletClient?.chain ?? null,
+      ...options?.gasLimit && { gas: options.gasLimit },
+      ...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 }
     });
-    return {
+    const { tx } = await import("../utils/transactionHelpers");
+    return tx({
       hash: txHash,
-      from: this.context.walletClient.account?.address
-    };
+      from: typeof account === "string" ? account : account.address,
+      contract: "DataPortabilityGrantees",
+      fn: "registerGrantee"
+    });
   }
   /**
    * Registers a grantee with a signature (gasless transaction)
@@ -2192,6 +2350,7 @@ class PermissionsController {
    * ```
    */
   async submitRegisterGranteeWithSignature(params) {
+    this.assertWallet();
     const nonce = await this.getServersUserNonce();
     const owner = getAddress(params.owner);
     const granteeAddress = getAddress(params.granteeAddress);
@@ -2207,10 +2366,14 @@ class PermissionsController {
       typedData,
       signature
     );
-    return {
+    const account = this.context.walletClient?.account ?? this.context.userAddress;
+    const { tx } = await import("../utils/transactionHelpers");
+    return tx({
       hash,
-      from: this.context.walletClient.account?.address
-    };
+      from: typeof account === "string" ? account : account.address,
+      contract: "DataPortabilityGrantees",
+      fn: "registerGrantee"
+    });
   }
   /**
    * Submits a signed register grantee transaction via relayer
@@ -2229,10 +2392,14 @@ class PermissionsController {
       typedData,
       signature
     );
-    return {
+    const account = this.context.walletClient?.account ?? this.context.userAddress;
+    const { tx } = await import("../utils/transactionHelpers");
+    return tx({
       hash,
-      from: this.context.walletClient.account?.address
-    };
+      from: typeof account === "string" ? account : account.address,
+      contract: "DataPortabilityGrantees",
+      fn: "registerGrantee"
+    });
   }
   /**
    * Retrieves all registered grantees from the DataPortabilityGrantees contract.
@@ -2279,8 +2446,8 @@ class PermissionsController {
       functionName: "granteesCount"
     });
     const total = Number(totalCount);
-    const limit = options.limit || 50;
-    const offset = options.offset || 0;
+    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++) {
@@ -2428,7 +2595,7 @@ class PermissionsController {
    * @private
    */
   async buildRegisterGranteeTypedData(input) {
-    const chainId = await this.context.walletClient.getChainId();
+    const chainId = await this.context.publicClient.getChainId();
     const verifyingContract = getContractAddress(
       chainId,
       "DataPortabilityGrantees"
@@ -2461,6 +2628,7 @@ class PermissionsController {
    * @private
    */
   async submitSignedRegisterGranteeTransaction(typedData, _signature) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityGranteesAddress = getContractAddress(
       chainId,
@@ -2476,8 +2644,8 @@ class PermissionsController {
         typedData.message.granteeAddress,
         typedData.message.publicKey
       ],
-      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
     });
     return txHash;
   }
@@ -2492,7 +2660,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,
@@ -2550,7 +2718,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,
@@ -2579,7 +2747,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,
@@ -2696,7 +2864,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,
@@ -2758,7 +2926,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,
@@ -3200,9 +3368,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(
@@ -3210,18 +3380,33 @@ class PermissionsController {
         "DataPortabilityServers"
       );
       const DataPortabilityServersAbi = getAbi("DataPortabilityServers");
+      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: this.context.walletClient.account || null
+        chain: this.context.walletClient?.chain,
+        account,
+        ...options?.gasLimit && { gas: options.gasLimit },
+        ...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 }
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityServers",
+        fn: "updateServer"
+      });
     } catch (error) {
       throw new BlockchainError(
         `Failed to update server: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3371,6 +3556,7 @@ class PermissionsController {
    * @throws {NetworkError} When network communication fails
    */
   async submitAddPermission(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getPermissionsUserNonce();
       const addPermissionInput = {
@@ -3409,6 +3595,7 @@ class PermissionsController {
    * @throws {NetworkError} When network communication fails
    */
   async submitSignedAddPermission(typedData, signature) {
+    this.assertWallet();
     try {
       let hash;
       if (this.context.relayerCallbacks?.submitAddPermission) {
@@ -3422,10 +3609,14 @@ class PermissionsController {
           signature
         );
       }
-      return {
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityPermissions",
+        fn: "addPermission"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -3454,8 +3645,11 @@ class PermissionsController {
    * @param params.serverAddress - Server wallet address for decryption permissions
    * @param params.serverUrl - Server endpoint URL
    * @param params.serverPublicKey - Server's public key for encryption.
-   *   Obtain via `vana.server.getIdentity(userAddress).public_key`.
+   *   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.
@@ -3469,6 +3663,7 @@ class PermissionsController {
    *
    * @example
    * ```typescript
+   * // Submit with custom gas parameters and timeout
    * const result = await vana.permissions.submitAddServerFilesAndPermissions({
    *   granteeId: BigInt(1),
    *   grant: "ipfs://QmXxx...",
@@ -3476,17 +3671,25 @@ class PermissionsController {
    *   schemaIds: [123], // LinkedIn profile schema ID
    *   serverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
    *   serverUrl: "https://server.example.com",
-   *   serverPublicKey: serverInfo.public_key,
+   *   serverPublicKey: serverInfo.publicKey,
    *   filePermissions: [[{
    *     account: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
    *     key: encryptedKey
    *   }]]
+   * }, {
+   *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei
+   *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip
    * });
-   * const events = await result.waitForEvents();
-   * console.log(`Permission ID: ${events.permissionId}`);
+   *
+   * // Wait for confirmation with custom timeout
+   * const receipt = await vana.waitForTransactionReceipt(result, {
+   *   timeout: 180000 // 3 minutes
+   * });
+   * 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(
@@ -3511,7 +3714,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) {
@@ -3532,6 +3736,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
@@ -3550,7 +3757,8 @@ 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,
@@ -3565,22 +3773,31 @@ class PermissionsController {
           typedData,
           signature
         );
-        return {
+        const account = this.context.walletClient?.account ?? this.context.userAddress;
+        const { tx } = await import("../utils/transactionHelpers");
+        return tx({
           hash,
-          from: this.context.walletClient.account?.address
-        };
+          from: typeof account === "string" ? account : account.address,
+          contract: "DataPortabilityPermissions",
+          fn: "addServerFilesAndPermissions"
+        });
       } else {
         console.debug(
           "\u{1F4DD} Using direct transaction for submitAddServerFilesAndPermissions"
         );
         const hash = await this.submitDirectAddServerFilesAndPermissionsTransaction(
           typedData,
-          signature
+          signature,
+          options
         );
-        return {
+        const account = this.context.userAddress;
+        const { tx } = await import("../utils/transactionHelpers");
+        return tx({
           hash,
-          from: this.context.walletClient.account?.address
-        };
+          from: account,
+          contract: "DataPortabilityPermissions",
+          fn: "addServerFilesAndPermissions"
+        });
       }
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
@@ -3596,9 +3813,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(
@@ -3608,18 +3827,36 @@ class PermissionsController {
       const DataPortabilityPermissionsAbi = getAbi(
         "DataPortabilityPermissions"
       );
+      const { account } = this.context.walletClient;
+      if (!account) {
+        throw new Error("No wallet account connected");
+      }
       const hash = await this.context.walletClient.writeContract({
         address: DataPortabilityPermissionsAddress,
         abi: DataPortabilityPermissionsAbi,
         functionName: "revokePermission",
         args: [permissionId],
-        chain: this.context.walletClient.chain,
-        account: this.context.walletClient.account || null
+        chain: this.context.walletClient?.chain,
+        account,
+        ...options?.gasLimit && { gas: options.gasLimit },
+        ...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 }
       });
-      return {
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
         hash,
-        from: this.context.walletClient.account?.address
-      };
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityPermissions",
+        fn: "revokePermission"
+      });
     } catch (error) {
       throw new BlockchainError(
         `Failed to revoke permission: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -3635,6 +3872,7 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    */
   async submitDirectAddPermissionTransaction(typedData, signature) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
@@ -3645,7 +3883,7 @@ class PermissionsController {
       nonce: typedData.message.nonce,
       granteeId: typedData.message.granteeId,
       grant: typedData.message.grant,
-      fileIds: typedData.message.fileIds || []
+      fileIds: typedData.message.fileIds ?? []
     };
     const formattedSignature = formatSignatureForContract(signature);
     const hash = await this.context.walletClient.writeContract({
@@ -3653,8 +3891,8 @@ 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
     });
     return hash;
   }
@@ -3665,8 +3903,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"
@@ -3690,8 +3929,20 @@ class PermissionsController {
       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?.gasLimit && { gas: options.gasLimit },
+      ...options?.nonce && { nonce: options.nonce },
+      ...options?.value && { value: options.value },
+      // 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 }
     });
     return hash;
   }