@opendatalabs/vana-sdk 0.1.0-alpha.276ea01 → 0.1.0-alpha.2b6935d

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,20 +160,34 @@ 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) {
+        const canStoreViaRelayer = this.context.relayer !== void 0;
+        if (!canStoreViaRelayer && !this.context.storageManager) {
           if (this.context.validateStorageRequired) {
             this.context.validateStorageRequired();
           } else {
             throw new Error(
-              "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
+              "No storage available. Provide a grantUrl, configure relayer, or storageManager."
             );
           }
         }
-        if (this.context.relayerCallbacks?.storeGrantFile) {
-          grantUrl = await this.context.relayerCallbacks.storeGrantFile(grantFile);
+        if (canStoreViaRelayer && this.context.relayer) {
+          const request = {
+            type: "direct",
+            operation: "storeGrantFile",
+            params: grantFile
+          };
+          const response = await this.context.relayer(request);
+          if (response.type === "error") {
+            throw new Error(response.error);
+          }
+          if (response.type === "direct" && typeof response.result === "object" && "url" in response.result) {
+            grantUrl = response.result.url;
+          } else {
+            throw new Error("Invalid response from relayer for grant storage");
+          }
         } else if (this.context.storageManager) {
           const blob = new Blob([JSON.stringify(grantFile)], {
             type: "application/json"
@@ -244,23 +264,38 @@ 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) {
+        const canStoreViaRelayer = this.context.relayer !== void 0;
+        if (!canStoreViaRelayer && !this.context.storageManager) {
           if (this.context.validateStorageRequired) {
             this.context.validateStorageRequired();
           } else {
             throw new Error(
-              "No storage available. Provide a grantUrl, configure relayerCallbacks.storeGrantFile, or storageManager."
+              "No storage available. Provide a grantUrl, configure relayer, or storageManager."
             );
           }
         }
-        if (this.context.relayerCallbacks?.storeGrantFile) {
-          grantUrl = await this.context.relayerCallbacks.storeGrantFile(grantFile);
+        if (canStoreViaRelayer && this.context.relayer) {
+          const request = {
+            type: "direct",
+            operation: "storeGrantFile",
+            params: grantFile
+          };
+          const response = await this.context.relayer(request);
+          if (response.type === "error") {
+            throw new Error(response.error);
+          }
+          if (response.type === "direct" && typeof response.result === "object" && "url" in response.result) {
+            grantUrl = response.result.url;
+          } else {
+            throw new Error("Invalid response from relayer for grant storage");
+          }
         } else if (this.context.storageManager) {
           const blob = new Blob([JSON.stringify(grantFile)], {
             type: "application/json"
@@ -335,23 +370,39 @@ 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(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitAddPermission",
           typedData,
-          signature
-        );
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        let hash;
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else if (response.type === "error") {
+          throw new Error(`Relayer error: ${response.error}`);
+        } else {
+          throw new Error(
+            "Invalid response from relayer: expected signed transaction"
+          );
+        }
+        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 +444,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 +509,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 +527,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.
    *
@@ -492,18 +617,37 @@ class PermissionsController {
   async submitSignedRevoke(typedData, signature) {
     try {
       let hash;
-      if (this.context.relayerCallbacks?.submitPermissionRevoke) {
-        hash = await this.context.relayerCallbacks.submitPermissionRevoke(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitPermissionRevoke",
+          typedData,
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else if (response.type === "error") {
+          throw new Error(`Relayer error: ${response.error}`);
+        } else {
+          throw new Error(
+            "Invalid response from relayer: expected signed transaction"
+          );
+        }
+      } else {
+        hash = await this.submitDirectRevokeTransaction(
           typedData,
           signature
         );
-      } else {
-        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;
@@ -538,18 +682,37 @@ class PermissionsController {
   async submitSignedUntrustServer(typedData, signature) {
     try {
       let hash;
-      if (this.context.relayerCallbacks?.submitUntrustServer) {
-        hash = await this.context.relayerCallbacks.submitUntrustServer(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitUntrustServer",
+          typedData,
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else if (response.type === "error") {
+          throw new Error(`Relayer error: ${response.error}`);
+        } else {
+          throw new Error(
+            "Invalid response from relayer: expected signed transaction"
+          );
+        }
+      } else {
+        hash = await this.submitSignedUntrustTransaction(
           typedData,
           signature
         );
-      } 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 RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -573,7 +736,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 +757,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 +802,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.
@@ -653,11 +844,12 @@ class PermissionsController {
    * ```
    */
   async submitPermissionRevoke(params) {
+    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 +857,22 @@ 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
       });
-      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 +912,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();
@@ -738,18 +935,37 @@ class PermissionsController {
       };
       const signature = await this.signTypedData(typedData);
       let hash;
-      if (this.context.relayerCallbacks?.submitPermissionRevoke) {
-        hash = await this.context.relayerCallbacks.submitPermissionRevoke(
+      if (this.context.relayer) {
+        const response = await this.context.relayer({
+          type: "signed",
+          operation: "submitPermissionRevoke",
+          typedData,
+          signature,
+          expectedUserAddress: this.context.userAddress
+        });
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else if (response.type === "error") {
+          throw new Error(`Relayer error: ${response.error}`);
+        } else {
+          throw new Error(
+            "Invalid response from relayer: expected signed transaction"
+          );
+        }
+      } else {
+        hash = await this.submitDirectRevokeTransaction(
           typedData,
           signature
         );
-      } else {
-        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 +973,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 +999,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 +1045,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 +1085,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 +1194,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 +1213,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 +1224,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 +1241,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 +1283,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 +1336,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 +1347,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 +1369,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 +1377,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 +1403,7 @@ class PermissionsController {
    * ```
    */
   async addAndTrustServer(params) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1279,7 +1411,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 +1427,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 +1480,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 +1488,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 +1521,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);
@@ -1378,21 +1545,36 @@ class PermissionsController {
       const signature = await this.signTypedData(typedData);
       console.debug("\u{1F50D} Generated signature:", signature);
       let hash;
-      if (this.context.relayerCallbacks?.submitAddAndTrustServer) {
-        hash = await this.context.relayerCallbacks.submitAddAndTrustServer(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitAddAndTrustServer",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitAddAndTrustServerTransaction(
           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 Error) {
         if (error instanceof RelayerError || error instanceof UserRejectedRequestError || error instanceof SerializationError || error instanceof SignatureError || error instanceof NetworkError || error instanceof NonceError) {
@@ -1422,6 +1604,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 = {
@@ -1431,21 +1614,36 @@ class PermissionsController {
       const typedData = await this.composeTrustServerMessage(trustServerInput);
       const signature = await this.signTypedData(typedData);
       let hash;
-      if (this.context.relayerCallbacks?.submitTrustServer) {
-        hash = await this.context.relayerCallbacks.submitTrustServer(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitTrustServer",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitTrustServerTransaction(
           trustServerInput,
           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) {
@@ -1477,6 +1675,7 @@ class PermissionsController {
    * @throws {BlockchainError} When contract submission fails
    */
   async submitDirectUntrustTransaction(params) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -1484,18 +1683,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: "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
       });
-      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();
@@ -1535,6 +1738,7 @@ class PermissionsController {
    * ```
    */
   async submitUntrustServer(params) {
+    this.assertWallet();
     const nonce = await this.getServersUserNonce();
     const untrustServerInput = {
       nonce,
@@ -1555,6 +1759,7 @@ class PermissionsController {
    * @throws {BlockchainError} When untrust transaction fails
    */
   async submitUntrustServerWithSignature(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getServersUserNonce();
       const untrustServerInput = {
@@ -1564,18 +1769,33 @@ class PermissionsController {
       const typedData = await this.composeUntrustServerMessage(untrustServerInput);
       const signature = await this.signTypedData(typedData);
       let hash;
-      if (this.context.relayerCallbacks?.submitUntrustServer) {
-        hash = await this.context.relayerCallbacks.submitUntrustServer(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitUntrustServer",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } 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 +1833,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 +1863,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 +1893,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 +2042,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 +2117,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 +2207,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 +2227,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 +2259,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 +2272,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 +2291,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 +2304,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 +2316,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 +2330,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 +2338,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;
   }
@@ -2155,6 +2381,7 @@ class PermissionsController {
    * ```
    */
   async submitRegisterGrantee(params) {
+    this.assertWallet();
     const chainId = await this.context.walletClient.getChainId();
     const DataPortabilityGranteesAddress = getContractAddress(
       chainId,
@@ -2163,77 +2390,26 @@ 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
     });
-    return {
+    const { tx } = await import("../utils/transactionHelpers");
+    return tx({
       hash: txHash,
-      from: this.context.walletClient.account?.address
-    };
-  }
-  /**
-   * Registers a grantee with a signature (gasless transaction)
-   *
-   * @param params - Parameters for registering the grantee
-   * @returns Promise resolving to the transaction hash
-   *
-   * @example
-   * ```typescript
-   * const txHash = await vana.permissions.registerGranteeWithSignature({
-   *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
-   *   granteeAddress: "0xApp1234567890123456789012345678901234567890",
-   *   publicKey: "0x1234567890abcdef..."
-   * });
-   * ```
-   */
-  async submitRegisterGranteeWithSignature(params) {
-    const nonce = await this.getServersUserNonce();
-    const owner = getAddress(params.owner);
-    const granteeAddress = getAddress(params.granteeAddress);
-    const registerGranteeInput = {
-      nonce,
-      owner,
-      granteeAddress,
-      publicKey: params.publicKey
-    };
-    const typedData = await this.buildRegisterGranteeTypedData(registerGranteeInput);
-    const signature = await this.signTypedData(typedData);
-    const hash = await this.submitSignedRegisterGranteeTransaction(
-      typedData,
-      signature
-    );
-    return {
-      hash,
-      from: this.context.walletClient.account?.address
-    };
-  }
-  /**
-   * Submits a signed register grantee transaction via relayer
-   *
-   * @param typedData - The EIP-712 typed data for register grantee
-   * @param signature - The cryptographic signature
-   * @returns Promise resolving to the transaction hash
-   *
-   * @example
-   * ```typescript
-   * const result = await vana.permissions.submitSignedRegisterGrantee(typedData, signature);
-   * ```
-   */
-  async submitSignedRegisterGrantee(typedData, signature) {
-    const hash = await this.submitSignedRegisterGranteeTransaction(
-      typedData,
-      signature
-    );
-    return {
-      hash,
-      from: this.context.walletClient.account?.address
-    };
+      from: typeof account === "string" ? account : account.address,
+      contract: "DataPortabilityGrantees",
+      fn: "registerGrantee"
+    });
   }
+  // TODO: When DataPortabilityGrantees contract adds registerGranteeWithSignature function,
+  // implement submitRegisterGranteeWithSignature and submitSignedRegisterGrantee methods
+  // to support gasless transactions via relayer
   /**
    * Retrieves all registered grantees from the DataPortabilityGrantees contract.
    *
@@ -2279,8 +2455,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++) {
@@ -2420,67 +2596,6 @@ class PermissionsController {
       return null;
     }
   }
-  /**
-   * Builds EIP-712 typed data for grantee registration
-   *
-   * @param input - The register grantee input
-   * @returns Promise resolving to the typed data structure
-   * @private
-   */
-  async buildRegisterGranteeTypedData(input) {
-    const chainId = await this.context.walletClient.getChainId();
-    const verifyingContract = getContractAddress(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    return {
-      domain: {
-        name: "DataPortabilityGrantees",
-        version: "1",
-        chainId,
-        verifyingContract
-      },
-      types: {
-        RegisterGrantee: [
-          { name: "nonce", type: "uint256" },
-          { name: "owner", type: "address" },
-          { name: "granteeAddress", type: "address" },
-          { name: "publicKey", type: "string" }
-        ]
-      },
-      primaryType: "RegisterGrantee",
-      message: input
-    };
-  }
-  /**
-   * Submits a register grantee transaction with signature.
-   *
-   * @param typedData - The EIP-712 typed data structure for the registration
-   * @param _signature - The cryptographic signature authorizing the registration (currently unused)
-   * @returns Promise resolving to the transaction hash
-   * @private
-   */
-  async submitSignedRegisterGranteeTransaction(typedData, _signature) {
-    const chainId = await this.context.walletClient.getChainId();
-    const DataPortabilityGranteesAddress = getContractAddress(
-      chainId,
-      "DataPortabilityGrantees"
-    );
-    const DataPortabilityGranteesAbi = getAbi("DataPortabilityGrantees");
-    const txHash = await this.context.walletClient.writeContract({
-      address: DataPortabilityGranteesAddress,
-      abi: DataPortabilityGranteesAbi,
-      functionName: "registerGrantee",
-      args: [
-        typedData.message.owner,
-        typedData.message.granteeAddress,
-        typedData.message.publicKey
-      ],
-      account: this.context.walletClient.account || await this.getUserAddress(),
-      chain: this.context.walletClient.chain || null
-    });
-    return txHash;
-  }
   // ===========================
   // DATA PORTABILITY SERVERS HELPER METHODS
   // ===========================
@@ -2492,7 +2607,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 +2665,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 +2694,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 +2811,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 +2873,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,
@@ -3203,6 +3318,7 @@ class PermissionsController {
    * @returns Promise resolving to transaction hash
    */
   async submitUpdateServer(serverId, url) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityServersAddress = getContractAddress(
@@ -3210,18 +3326,22 @@ 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
       });
-      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 +3491,7 @@ class PermissionsController {
    * @throws {NetworkError} When network communication fails
    */
   async submitAddPermission(params) {
+    this.assertWallet();
     try {
       const nonce = await this.getPermissionsUserNonce();
       const addPermissionInput = {
@@ -3409,23 +3530,39 @@ class PermissionsController {
    * @throws {NetworkError} When network communication fails
    */
   async submitSignedAddPermission(typedData, signature) {
+    this.assertWallet();
     try {
       let hash;
-      if (this.context.relayerCallbacks?.submitAddPermission) {
-        hash = await this.context.relayerCallbacks.submitAddPermission(
+      if (this.context.relayer) {
+        const request = {
+          type: "signed",
+          operation: "submitAddPermission",
           typedData,
           signature
-        );
+        };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         hash = await this.submitDirectAddPermissionTransaction(
           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: "addPermission"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -3454,7 +3591,7 @@ 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
    * @returns TransactionResult with immediate hash access and optional event data
    * @throws {Error} When schemaIds array length doesn't match fileUrls array length
@@ -3476,7 +3613,7 @@ 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
@@ -3487,6 +3624,7 @@ class PermissionsController {
    * ```
    */
   async submitAddServerFilesAndPermissions(params) {
+    this.assertWallet();
     try {
       if (params.schemaIds.length !== params.fileUrls.length) {
         throw new Error(
@@ -3551,37 +3689,45 @@ class PermissionsController {
    * ```
    */
   async submitSignedAddServerFilesAndPermissions(typedData, signature) {
+    this.assertWallet();
     try {
-      console.debug("\u{1F50D} submitSignedAddServerFilesAndPermissions Debug Info:", {
-        hasRelayerCallbacks: !!this.context.relayerCallbacks,
-        hasSubmitMethod: !!this.context.relayerCallbacks?.submitAddServerFilesAndPermissions,
-        availableRelayerMethods: this.context.relayerCallbacks ? Object.keys(this.context.relayerCallbacks) : []
-      });
-      if (this.context.relayerCallbacks?.submitAddServerFilesAndPermissions) {
+      let hash;
+      if (this.context.relayer) {
         console.debug(
           "\u{1F680} Using relayer for submitAddServerFilesAndPermissions"
         );
-        const hash = await this.context.relayerCallbacks.submitAddServerFilesAndPermissions(
+        const request = {
+          type: "signed",
+          operation: "submitAddServerFilesAndPermissions",
           typedData,
           signature
-        );
-        return {
-          hash,
-          from: this.context.walletClient.account?.address
         };
+        const response = await this.context.relayer(request);
+        if (response.type === "error") {
+          throw new RelayerError(response.error);
+        }
+        if (response.type === "signed") {
+          hash = response.hash;
+        } else {
+          throw new Error("Unexpected response type from relayer");
+        }
       } else {
         console.debug(
           "\u{1F4DD} Using direct transaction for submitAddServerFilesAndPermissions"
         );
-        const hash = await this.submitDirectAddServerFilesAndPermissionsTransaction(
+        hash = await this.submitDirectAddServerFilesAndPermissionsTransaction(
           typedData,
           signature
         );
-        return {
-          hash,
-          from: this.context.walletClient.account?.address
-        };
       }
+      const account = this.context.walletClient?.account ?? this.context.userAddress;
+      const { tx } = await import("../utils/transactionHelpers");
+      return tx({
+        hash,
+        from: typeof account === "string" ? account : account.address,
+        contract: "DataPortabilityPermissions",
+        fn: "addServerFilesAndPermissions"
+      });
     } catch (error) {
       if (error instanceof RelayerError || error instanceof NetworkError || error instanceof UserRejectedRequestError || error instanceof SignatureError || error instanceof NonceError) {
         throw error;
@@ -3599,6 +3745,7 @@ class PermissionsController {
    * @returns Promise resolving to transaction hash
    */
   async submitRevokePermission(permissionId) {
+    this.assertWallet();
     try {
       const chainId = await this.context.walletClient.getChainId();
       const DataPortabilityPermissionsAddress = getContractAddress(
@@ -3608,18 +3755,25 @@ 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
       });
-      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 +3789,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 +3800,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 +3808,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;
   }
@@ -3666,7 +3821,8 @@ class PermissionsController {
    * @returns Promise resolving to the transaction hash
    */
   async submitDirectAddServerFilesAndPermissionsTransaction(typedData, signature) {
-    const chainId = await this.context.walletClient.getChainId();
+    this.assertWallet();
+    const chainId = await this.context.publicClient.getChainId();
     const DataPortabilityPermissionsAddress = getContractAddress(
       chainId,
       "DataPortabilityPermissions"
@@ -3690,8 +3846,8 @@ 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.userAddress,
+      chain: this.context.walletClient?.chain ?? null
     });
     return hash;
   }