@opendatalabs/vana-sdk 0.1.0-alpha.7e71046 → 0.1.0-alpha.7ee7635

package/dist/controllers/permissions.d.ts

@@ -0,0 +1,1383 @@
+import { Hash, Address } from 'viem';
+import { GrantPermissionParams, GrantFile, PermissionGrantTypedData, TrustServerTypedData, AddAndTrustServerTypedData, GenericTypedData, RevokePermissionParams, GetUserPermissionsOptions, OnChainPermissionGrant, AddAndTrustServerParams, TrustServerParams, UntrustServerParams, TrustedServerQueryOptions, PaginatedTrustedServers, TrustedServerInfo, BatchServerInfoResult, ServerTrustStatus, RegisterGranteeParams, RegisterGranteeTypedData, GranteeQueryOptions, PaginatedGrantees, Grantee, ServerInfo, PermissionInfo, GranteeInfo, ServerFilesAndPermissionParams, ServerFilesAndPermissionTypedData } from '../types/permissions.js';
+import { PermissionGrantResult, PermissionRevokeResult, ServerTrustResult } from '../types/transactionResults.js';
+import { TransactionResult } from '../types/operations.js';
+import { ControllerContext } from '../types/controller-context.js';
+import '../generated/event-types.js';
+import '../generated/server/server-exports.js';
+import '../generated/server/server.js';
+import '../platform/interface.js';
+import '../types/config.js';
+import '../types/chains.js';
+import '../types/storage.js';
+import '../storage/manager.js';
+
+/**
+ * Manages gasless data access permissions and trusted server registry operations.
+ *
+ * @remarks
+ * This controller enables users to grant applications access to their data without
+ * paying gas fees. It handles the complete EIP-712 permission flow including signature
+ * creation, IPFS storage of permission details, and gasless transaction submission.
+ * The controller also manages trusted servers that can process user data and provides
+ * methods for revoking permissions when access is no longer needed.
+ *
+ * **Permission Architecture:**
+ * Permissions use dual storage: detailed parameters stored on IPFS, references stored on blockchain.
+ * This enables complex permissions while maintaining minimal on-chain data.
+ *
+ * **Method Selection:**
+ * - `grant()` creates new permissions with automatic IPFS upload and blockchain registration
+ * - `prepareGrant()` allows preview before signing for interactive applications
+ * - `revoke()` removes permissions by ID, supporting both gasless and direct transactions
+ * - `getUserPermissionGrantsOnChain()` queries existing permissions efficiently
+ * - `trustServer()` and `untrustServer()` manage server access for data processing
+ *
+ * **Transaction Types:**
+ * Methods with gasless support: `grant()`, `revoke()`, `trustServer()`, `untrustServer()`
+ * Methods requiring direct transactions: none (all support both gasless and direct)
+ * @example
+ * ```typescript
+ * // Grant permission for an app to access your data
+ * const txHash = await vana.permissions.grant({
+ *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+ *   operation: "llm_inference",
+ *   files: [1, 2, 3],
+ *   parameters: { model: "gpt-4", maxTokens: 1000 },
+ * });
+ *
+ * // Trust a server for data processing
+ * await vana.permissions.trustServer({
+ *   serverId: "0x123...",
+ *   serverUrl: "https://personal-server.vana.org",
+ * });
+ *
+ * // Query current permissions
+ * const permissions = await vana.permissions.getUserPermissionGrantsOnChain();
+ * ```
+ * @category Permissions
+ * @see {@link https://docs.vana.com/developer/permissions | Vana Permissions System} for conceptual overview
+ */
+declare class PermissionsController {
+    private readonly context;
+    constructor(context: ControllerContext);
+    /**
+     * Grants permission for an application to access user data with gasless transactions.
+     *
+     * This method provides a complete end-to-end permission grant flow that returns
+     * the permission ID and other relevant data immediately after successful submission.
+     * For advanced users who need more control over the transaction lifecycle, use
+     * `submitPermissionGrant()` instead.
+     *
+     * @param params - The permission grant configuration object
+     * @returns Promise resolving to permission data from the PermissionAdded event
+     * @throws {RelayerError} When gasless transaction submission fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {SerializationError} When grant data cannot be serialized
+     * @throws {BlockchainError} When permission grant fails or event parsing fails
+     * @throws {NetworkError} When transaction confirmation times out
+     * @example
+     * ```typescript
+     * const result = await vana.permissions.grant({
+     *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   operation: "llm_inference",
+     *   parameters: {
+     *     model: "gpt-4",
+     *     maxTokens: 1000,
+     *     temperature: 0.7,
+     *   },
+     * });
+     *
+     * console.log(`Permission ${result.permissionId} granted to ${result.user}`);
+     * console.log(`Transaction: ${result.transactionHash}`);
+     *
+     * // Can immediately use the permission ID for other operations
+     * await vana.permissions.revoke({ permissionId: result.permissionId });
+     * ```
+     */
+    grant(params: GrantPermissionParams): Promise<PermissionGrantResult>;
+    /**
+     * Submits a permission grant transaction and returns a handle for flexible result access.
+     *
+     * @remarks
+     * This lower-level method provides maximum control over transaction timing.
+     * Returns a TransactionResult that can be serialized and passed across API boundaries.
+     * Use this when handling multiple transactions or when you need granular control.
+     *
+     * @param params - The permission grant configuration object
+     * @returns Promise resolving to TransactionResult with hash and event parsing capabilities
+     * @throws {RelayerError} When gasless transaction submission fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {SerializationError} When grant data cannot be serialized
+     * @throws {BlockchainError} When permission grant preparation fails
+     * @example
+     * ```typescript
+     * // Submit transaction and get immediate hash access
+     * const tx = await vana.permissions.submitPermissionGrant(params);
+     * console.log(`Transaction submitted: ${tx.hash}`);
+     *
+     * // To wait for events, use SDK's waitForTransactionEvents
+     * const eventData = await vana.waitForTransactionEvents(tx.hash);
+     * console.log(`Permission ID: ${eventData.permissionId}`);
+     * ```
+     */
+    submitPermissionGrant(params: GrantPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    /**
+     * Prepares a permission grant with preview before signing.
+     *
+     * @remarks
+     * This method implements a two-phase commit workflow that allows applications
+     * to show users a preview of what they're authorizing before requesting a signature.
+     * Unlike `createAndSign()`, this method does NOT upload to IPFS or prompt for signatures
+     * until the returned `confirm()` function is called.
+     * @param params - The permission grant parameters
+     * @returns A promise resolving to a preview object and confirm function
+     * @throws {SerializationError} When grant parameters are invalid or cannot be serialized
+     * @throws {BlockchainError} When grant validation fails or preparation encounters an error
+     * @example
+     * ```typescript
+     * const { preview, confirm } = await vana.permissions.prepareGrant({
+     *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   operation: "llm_inference",
+     *   files: [1, 2, 3],
+     *   parameters: { model: "gpt-4", prompt: "Analyze my social media data" }
+     * });
+     *
+     * console.log(`Granting ${preview.operation} access to ${preview.files?.length} files`);
+     * const transactionHash = await confirm();
+     * ```
+     */
+    prepareGrant(params: GrantPermissionParams): Promise<{
+        preview: GrantFile;
+        confirm: () => Promise<PermissionGrantResult>;
+    }>;
+    /**
+     * Completes the grant process after user confirmation.
+     *
+     * @remarks
+     * This internal method is called by the confirm() function returned from prepareGrant().
+     * It handles IPFS upload, signature creation, and transaction submission.
+     *
+     * @param params - The permission grant parameters containing user and operation details
+     * @param grantFile - The prepared grant file with permissions and metadata
+     * @returns Promise resolving to TransactionResult for flexible result access
+     * @throws {BlockchainError} When permission grant confirmation fails
+     * @throws {NetworkError} When IPFS upload fails
+     * @throws {SignatureError} When user rejects the signature
+     */
+    private confirmGrantInternal;
+    /**
+     * Creates typed data and signature for a permission grant without submitting.
+     *
+     * @remarks
+     * This method handles the first phase of permission granting: creating the grant file,
+     * storing it on IPFS, and generating the user's EIP-712 signature. Use this when you
+     * want to handle submission separately or batch multiple operations. The method validates
+     * the grant file against the JSON schema before creating the signature.
+     *
+     * For interactive user flows, consider using `prepareGrant()` instead,
+     * which allows showing a preview before signing.
+     * @param params - The permission grant configuration object
+     * @returns A promise resolving to the typed data structure and signature for gasless submission
+     * @throws {SignatureError} When the user rejects the signature request
+     * @throws {SerializationError} When grant data cannot be properly formatted
+     * @throws {BlockchainError} When permission grant preparation fails
+     * @throws {NetworkError} When storage operations fail
+     * @example
+     * ```typescript
+     * const { typedData, signature } = await vana.permissions.createAndSign({
+     *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   operation: "data_analysis",
+     *   parameters: { analysisType: "sentiment" },
+     * });
+     *
+     * const transactionHash = await vana.permissions.submitSignedGrant(typedData, signature);
+     * ```
+     */
+    createAndSign(params: GrantPermissionParams): Promise<{
+        typedData: PermissionGrantTypedData;
+        signature: Hash;
+    }>;
+    /**
+     * Submits an already-signed permission grant to the blockchain.
+     *
+     * @remarks
+     * This method supports both relayer-based gasless transactions and direct transactions.
+     * It automatically converts `bigint` values to JSON-safe strings when using relayer
+     * callbacks and handles transaction submission with proper error handling and retry logic.
+     * @param typedData - The EIP-712 typed data structure for the permission grant
+     * @param signature - The user's signature as a hex string
+     * @returns A Promise that resolves to the transaction hash
+     * @throws {RelayerError} When gasless transaction submission fails
+     * @throws {BlockchainError} When permission submission fails
+     * @throws {NetworkError} When network communication fails
+     * @example
+     * ```typescript
+     * const txHash = await vana.permissions.submitSignedGrant(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * ```
+     */
+    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    /**
+     * Submits an already-signed trust server transaction to the blockchain.
+     *
+     * @remarks
+     * This method extracts the trust server input from typed data and submits it directly.
+     * Used internally by trust server methods after signature collection.
+     *
+     * @param typedData - The EIP-712 typed data for TrustServer
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionResult for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedTrustServer(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
+     */
+    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
+    /**
+     * Submits an already-signed add and trust server transaction to the blockchain.
+     *
+     * @remarks
+     * This method extracts the add and trust server input from typed data and submits it directly.
+     * Combines server registration and trust operations in a single transaction.
+     *
+     * @param typedData - The EIP-712 typed data for AddAndTrustServer
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionResult for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedAddAndTrustServer(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
+     */
+    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
+    /**
+     * 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
+     */
+    private submitSignedGrantWithEvents;
+    /**
+     * 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
+     */
+    private confirmGrantInternalWithEvents;
+    /**
+     * Internal method to submit a signed revoke and wait for events.
+     *
+     * @internal
+     * @param typedData - The EIP-712 typed data for the permission revoke
+     * @param signature - The user's signature authorizing the transaction
+     * @returns Promise resolving to PermissionRevokeResult with parsed events
+     */
+    private submitSignedRevokeWithEvents;
+    /**
+     * Submits an already-signed permission revoke transaction to the blockchain.
+     *
+     * @remarks
+     * This method handles the revocation of previously granted permissions.
+     * Used internally by revocation methods after signature collection.
+     *
+     * @param typedData - The EIP-712 typed data for PermissionRevoke
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionResult for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedRevoke(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
+     */
+    submitSignedRevoke(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
+    /**
+     * Submits an already-signed untrust server transaction to the blockchain.
+     *
+     * @remarks
+     * This method handles the removal of trusted servers.
+     * Used internally by untrust server methods after signature collection.
+     *
+     * @param typedData - The EIP-712 typed data for UntrustServer
+     * @param signature - The user's signature obtained via `signTypedData()`
+     * @returns Promise resolving to TransactionResult for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     * @throws {NetworkError} When blockchain communication fails
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitSignedUntrustServer(
+     *   typedData,
+     *   "0x1234..."
+     * );
+     * const result = await txHandle.waitForEvents();
+     * ```
+     */
+    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "untrustServerWithSignature">>;
+    /**
+     * Submits a signed transaction directly to the blockchain.
+     *
+     * @remarks
+     * Internal method used when relayer callbacks are not available. Formats the signature
+     * and submits the permission grant directly to the smart contract.
+     *
+     * @param typedData - The typed data structure for the permission grant
+     * @param signature - The cryptographic signature authorizing the transaction
+     * @returns Promise resolving to the transaction hash
+     * @throws {BlockchainError} When contract submission fails
+     */
+    private submitDirectTransaction;
+    /**
+     * Revokes a previously granted permission.
+     *
+     * This method provides complete revocation with automatic event parsing to confirm
+     * the permission was successfully revoked. For advanced users who need more control,
+     * use `submitPermissionRevoke()` instead.
+     *
+     * @param params - Parameters for revoking the permission
+     * @param params.permissionId - Permission identifier (accepts bigint, number, or string).
+     *   Obtain from permission grants via `getUserPermissionGrantsOnChain()`.
+     * @returns Promise resolving to revocation data from PermissionRevoked event
+     * @throws {BlockchainError} When revocation fails or event parsing fails
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @throws {NetworkError} When transaction confirmation times out
+     * @example
+     * ```typescript
+     * // Revoke a permission and get confirmation
+     * const result = await vana.permissions.revoke({
+     *   permissionId: 123n
+     * });
+     * console.log(`Permission ${result.permissionId} revoked in transaction ${result.transactionHash}`);
+     * console.log(`Revoked in block ${result.blockNumber}`);
+     * ```
+     */
+    revoke(params: RevokePermissionParams): Promise<PermissionRevokeResult>;
+    /**
+     * Submits a permission revocation transaction and returns the transaction hash immediately.
+     *
+     * This is the lower-level method that provides maximum control over transaction timing.
+     * Use this when you want to handle transaction confirmation and event parsing separately.
+     *
+     * @param params - Parameters for revoking the permission
+     * @returns Promise resolving to the transaction hash when successfully submitted
+     * @throws {BlockchainError} When revocation transaction fails
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @example
+     * ```typescript
+     * // Submit revocation and handle confirmation later
+     * const txHash = await vana.permissions.submitPermissionRevoke({
+     *   permissionId: 123n
+     * });
+     * console.log(`Revocation submitted: ${txHash}`);
+     * ```
+     */
+    submitPermissionRevoke(params: RevokePermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
+    /**
+     * Revokes a permission with a signature for gasless transactions.
+     *
+     * @remarks
+     * This method creates an EIP-712 signature for permission revocation and submits
+     * it either through relayer callbacks or directly to the blockchain. Provides
+     * gasless revocation when relayer is configured.
+     *
+     * @param params - Parameters for revoking the permission
+     * @param params.permissionId - Permission identifier to revoke (accepts bigint, number, or string)
+     * @returns Promise resolving to TransactionResult for transaction tracking
+     * @throws {BlockchainError} When chain ID is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {RelayerError} When gasless submission fails
+     * @throws {PermissionError} When revocation fails for any other reason
+     * @example
+     * ```typescript
+     * const txHandle = await vana.permissions.submitRevokeWithSignature({
+     *   permissionId: 123n
+     * });
+     * const result = await txHandle.waitForEvents();
+     * console.log(`Permission ${result.permissionId} revoked`);
+     * ```
+     */
+    submitRevokeWithSignature(params: RevokePermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
+    /**
+     * @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
+     */
+    private getUserNonce;
+    /**
+     * Retrieves the user's current nonce from the DataPortabilityServers contract.
+     * This nonce is used for server-related operations (AddAndTrustServer, TrustServer, UntrustServer).
+     *
+     * @returns Promise resolving to the current servers nonce
+     * @throws {NonceError} When reading nonce from contract fails
+     * @private
+     *
+     * @example
+     * ```typescript
+     * const nonce = await this.getServersUserNonce();
+     * console.log(`Current servers nonce: ${nonce}`);
+     * ```
+     */
+    /**
+     * Retrieves the user's current nonce from the DataPortabilityServers contract.
+     *
+     * @remarks
+     * Used for server-related operations (trust/untrust) to prevent replay attacks.
+     * The nonce must be incremented with each server operation.
+     *
+     * @returns Promise resolving to the user's current nonce as a bigint
+     * @throws {NonceError} When retrieving the nonce fails
+     */
+    private getServersUserNonce;
+    /**
+     * Retrieves the user's current nonce from the DataPortabilityPermissions contract.
+     * This nonce is used for permission-related operations (addPermission, addServerFilesAndPermissions).
+     *
+     * @returns Promise resolving to the current permissions nonce
+     * @throws {NonceError} When reading nonce from contract fails
+     * @private
+     *
+     * @example
+     * ```typescript
+     * const nonce = await this.getPermissionsUserNonce();
+     * console.log(`Current permissions nonce: ${nonce}`);
+     * ```
+     */
+    /**
+     * Retrieves the user's current nonce from the DataPortabilityPermissions contract.
+     *
+     * @remarks
+     * Used for permission-related operations (grant/revoke) to prevent replay attacks.
+     * The nonce must be incremented with each permission operation.
+     *
+     * @returns Promise resolving to the user's current nonce as a bigint
+     * @throws {NonceError} When retrieving the nonce fails
+     */
+    private getPermissionsUserNonce;
+    /**
+     * Composes the EIP-712 typed data for PermissionGrant (new simplified format).
+     *
+     * @param params - The parameters for composing the permission grant message
+     * @param params.grantee - The recipient address for the permission grant
+     * @param params.operation - The type of operation being granted permission for
+     * @param params.files - Array of file IDs that the permission applies to
+     * @param params.grantUrl - URL where the grant details are stored
+     * @param params.serializedParameters - Serialized parameters for the operation
+     * @param params.nonce - Unique number to prevent replay attacks
+     * @returns Promise resolving to the typed data structure
+     */
+    private composePermissionGrantMessage;
+    /**
+     * Creates EIP-712 typed data structure for server files and permissions.
+     *
+     * @param params - Parameters for the server files and permissions message
+     * @param params.granteeId - Grantee ID
+     * @param params.grant - Grant URL or grant data
+     * @param params.fileUrls - Array of file URLs
+     * @param params.schemaIds - Schema IDs for each file
+     * @param params.serverAddress - Server address
+     * @param params.serverUrl - Server URL
+     * @param params.serverPublicKey - Server public key
+     * @param params.filePermissions - File permissions array
+     * @param params.nonce - Unique number to prevent replay attacks
+     * @returns Promise resolving to the typed data structure
+     */
+    private composeServerFilesAndPermissionMessage;
+    /**
+     * Gets the EIP-712 domain for PermissionGrant signatures.
+     *
+     * @returns Promise resolving to the EIP-712 domain configuration
+     */
+    private getPermissionDomain;
+    /**
+     * Signs typed data using the wallet client with signature caching.
+     *
+     * @param typedData - The EIP-712 typed data structure to sign
+     * @returns Promise resolving to the cryptographic signature
+     */
+    private signTypedData;
+    /**
+     * Gets the user's address from the wallet client.
+     *
+     * @returns Promise resolving to the user's wallet address
+     */
+    private getUserAddress;
+    /**
+     * Gets on-chain permission grant data without expensive off-chain resolution.
+     *
+     * @remarks
+     * This method provides a fast, performance-focused way to retrieve permission grants
+     * by querying only the subgraph without making expensive IPFS or individual contract calls.
+     * It eliminates the N+1 query problem of the legacy `getUserPermissions()` method.
+     *
+     * The returned data contains all on-chain information but does NOT include resolved
+     * operation details, parameters, or file IDs. Use `retrieveGrantFile()` separately
+     * for specific grants when detailed data is needed.
+     *
+     * **Performance**: Completes in ~100-500ms regardless of permission count.
+     * **Reliability**: Single point of failure (subgraph) with clear RPC fallback path.
+     *
+     * @param options - Options for retrieving permissions (limit, subgraph URL)
+     * @returns A Promise that resolves to an array of `OnChainPermissionGrant` objects
+     * @throws {BlockchainError} When subgraph query fails
+     * @throws {NetworkError} When network requests fail
+     * @example
+     * ```typescript
+     * // Fast: Get all on-chain permission data
+     * const grants = await vana.permissions.getUserPermissionGrantsOnChain({ limit: 20 });
+     *
+     * // Display in UI immediately
+     * grants.forEach(grant => {
+     *   console.log(`Permission ${grant.id}: ${grant.grantUrl}`);
+     * });
+     *
+     * // Lazy load detailed data for specific permission when user clicks
+     * const grantFile = await retrieveGrantFile(grants[0].grantUrl);
+     * console.log(`Operation: ${grantFile.operation}`);
+     * console.log(`Parameters:`, grantFile.parameters);
+     * ```
+     */
+    getUserPermissionGrantsOnChain(options?: GetUserPermissionsOptions): Promise<OnChainPermissionGrant[]>;
+    /**
+     * 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
+     */
+    private normalizeGrantId;
+    /**
+     * Registers a new server and immediately trusts it in the DataPortabilityServers contract.
+     *
+     * This is a combined operation that both registers a new data portability server
+     * and adds it to the user's trusted servers list in a single transaction.
+     * 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)
+     * @returns Promise resolving to transaction hash
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @throws {BlockchainError} When chain ID is unavailable or transaction fails
+     * @throws {ServerAlreadyRegisteredError} When server address is already registered
+     * @throws {Error} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Add and trust a server by providing all required details
+     * const txHash = await vana.permissions.addAndTrustServer({
+     *   owner: '0x1234567890abcdef1234567890abcdef12345678',
+     *   serverAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+     *   serverUrl: 'https://myserver.example.com',
+     *   publicKey: '0x456789abcdef456789abcdef456789abcdef456789abcdef'
+     * });
+     * console.log('Server added and trusted in transaction:', txHash);
+     *
+     * // Verify the server is now trusted
+     * const trustedServers = await vana.permissions.getTrustedServers();
+     * console.log('Now trusting servers:', trustedServers);
+     * ```
+     */
+    addAndTrustServer(params: AddAndTrustServerParams): Promise<ServerTrustResult>;
+    /**
+     * Trusts a server for data processing (legacy method).
+     *
+     * @param params - Parameters for trusting the server
+     * @returns Promise resolving to transaction hash
+     * @deprecated Use addAndTrustServer instead
+     */
+    submitTrustServer(params: TrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "trustServer">>;
+    /**
+     * Adds and trusts a server using a signature (gasless transaction).
+     *
+     * @param params - Parameters for adding and trusting the server
+     * @returns Promise resolving to TransactionResult with ServerTrustResult event data
+     */
+    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
+    /**
+     * Trusts a server using a signature (gasless transaction - legacy method).
+     *
+     * @param params - Parameters for trusting the server
+     * @returns Promise resolving to transaction hash
+     * @deprecated Use addAndTrustServerWithSignature instead
+     * @throws {BlockchainError} When chain ID is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {RelayerError} When gasless submission fails
+     * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
+     * @throws {BlockchainError} When trust operation fails for any other reason
+     */
+    submitTrustServerWithSignature(params: TrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
+    /**
+     * Submits a direct untrust server transaction (without signature).
+     *
+     * @param params - The untrust server parameters containing server details
+     * @returns Promise resolving to the transaction hash
+     */
+    /**
+     * Submits an untrust server transaction directly to the blockchain.
+     *
+     * @remarks
+     * Internal method used for direct blockchain submission of untrust server operations
+     * when relayer callbacks are not available.
+     *
+     * @param params - The untrust server parameters
+     * @returns Promise resolving to TransactionResult for transaction tracking
+     * @throws {BlockchainError} When contract submission fails
+     */
+    private submitDirectUntrustTransaction;
+    /**
+     * Removes a server from the user's trusted servers list in the DataPortabilityServers contract.
+     *
+     * This revokes the server's authorization to handle data portability requests for the user.
+     * The server remains registered in the system but will no longer be trusted by this user.
+     *
+     * @param params - Parameters for untrusting the server
+     * @param params.serverId - The numeric ID of the server to untrust
+     * @returns Promise resolving to transaction hash
+     * @throws {Error} When wallet account is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @throws {ServerNotTrustedError} When the server is not currently trusted
+     * @throws {BlockchainError} When untrust transaction fails
+     *
+     * @example
+     * ```typescript
+     * // Untrust a specific server
+     * const txHash = await vana.permissions.untrustServer({
+     *   serverId: 1
+     * });
+     * console.log('Server untrusted in transaction:', txHash);
+     *
+     * // Verify the server is no longer trusted
+     * const trustedServers = await vana.permissions.getTrustedServers();
+     * console.log('Still trusting servers:', trustedServers);
+     * ```
+     */
+    submitUntrustServer(params: UntrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "untrustServer">>;
+    /**
+     * Untrusts a server using a signature (gasless transaction).
+     *
+     * @param params - Parameters for untrusting the server
+     * @param params.serverId - The server's Ethereum address to untrust
+     * @returns Promise resolving to transaction hash
+     * @throws {Error} When wallet account is not available
+     * @throws {NonceError} When retrieving user nonce fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {RelayerError} When gasless submission fails
+     * @throws {BlockchainError} When untrust transaction fails
+     */
+    submitUntrustServerWithSignature(params: UntrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "untrustServerWithSignature">>;
+    /**
+     * Retrieves all servers trusted by a user from the DataPortabilityServers contract.
+     *
+     * Returns an array of server IDs that the specified user has explicitly trusted.
+     * Trusted servers are those that users have authorized to handle their data portability requests.
+     *
+     * @param userAddress - Optional user address to query (defaults to current wallet user)
+     * @returns Promise resolving to array of trusted server IDs (numeric)
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
+     * @throws {NetworkError} When unable to connect to the blockchain network
+     *
+     * @example
+     * ```typescript
+     * // Get trusted servers for current user
+     * const myServers = await vana.permissions.getTrustedServers();
+     * console.log(`I trust ${myServers.length} servers: ${myServers.join(', ')}`);
+     *
+     * // Get trusted servers for another user
+     * const userServers = await vana.permissions.getTrustedServers("0x1234...");
+     * console.log(`User trusts servers: ${userServers.join(', ')}`);
+     * ```
+     */
+    getTrustedServers(userAddress?: Address): Promise<number[]>;
+    /**
+     * Gets the total count of trusted servers for a user.
+     *
+     * @param userAddress - Optional user address (defaults to current user)
+     * @returns Promise resolving to the number of trusted servers
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
+     */
+    getTrustedServersCount(userAddress?: Address): Promise<number>;
+    /**
+     * Gets trusted servers with pagination support.
+     *
+     * @param options - Query options including pagination parameters
+     * @returns Promise resolving to paginated trusted servers
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
+     */
+    getTrustedServersPaginated(options?: TrustedServerQueryOptions): Promise<PaginatedTrustedServers>;
+    /**
+     * Gets trusted servers with their complete information.
+     *
+     * @param options - Query options
+     * @returns Promise resolving to array of trusted server info
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
+     */
+    getTrustedServersWithInfo(options?: TrustedServerQueryOptions): Promise<TrustedServerInfo[]>;
+    /**
+     * Gets server information for multiple servers efficiently.
+     *
+     * @remarks
+     * This method uses multicall to fetch information for multiple servers in a single
+     * blockchain call, improving performance when querying many servers. Failed lookups
+     * are returned separately for error handling.
+     *
+     * @param serverIds - Array of numeric server IDs to query
+     * @returns Promise resolving to batch result containing successful lookups and failed IDs
+     * @throws {BlockchainError} When reading from contract fails or chain is unavailable
+     * @example
+     * ```typescript
+     * const result = await vana.permissions.getServerInfoBatch([1, 2, 3, 999]);
+     *
+     * // Process successful lookups
+     * result.servers.forEach((server, id) => {
+     *   console.log(`Server ${id}: ${server.url}`);
+     * });
+     *
+     * // Handle failed lookups
+     * if (result.failed.length > 0) {
+     *   console.log(`Failed to fetch: ${result.failed.join(', ')}`);
+     * }
+     * ```
+     */
+    getServerInfoBatch(serverIds: number[]): Promise<BatchServerInfoResult>;
+    /**
+     * Checks whether a specific server is trusted by a user.
+     *
+     * @remarks
+     * This method queries the user's trusted server list and checks if the specified
+     * server is present. Returns both the trust status and the index in the trust list
+     * if trusted.
+     *
+     * @param serverId - Numeric server ID to check
+     * @param userAddress - Optional user address (defaults to current user)
+     * @returns Promise resolving to server trust status with trust index if applicable
+     * @throws {BlockchainError} When reading from contract fails
+     * @example
+     * ```typescript
+     * const status = await vana.permissions.checkServerTrustStatus(1);
+     * if (status.isTrusted) {
+     *   console.log(`Server is trusted at index ${status.trustIndex}`);
+     * } else {
+     *   console.log('Server is not trusted');
+     * }
+     * ```
+     */
+    checkServerTrustStatus(serverId: number, userAddress?: Address): Promise<ServerTrustStatus>;
+    /**
+     * Composes EIP-712 typed data for AddAndTrustServer.
+     *
+     * @remarks
+     * Creates the complete typed data structure required for EIP-712 signature generation
+     * when adding and trusting a new server in a single transaction.
+     *
+     * @param input - The add and trust server input data containing server details
+     * @returns Promise resolving to the typed data structure for server add and trust
+     */
+    private composeAddAndTrustServerMessage;
+    /**
+     * Composes EIP-712 typed data for TrustServer.
+     *
+     * @param input - The trust server input data containing server details
+     * @returns Promise resolving to the typed data structure for server trust
+     */
+    private composeTrustServerMessage;
+    /**
+     * Composes EIP-712 typed data for UntrustServer.
+     *
+     * @param input - The untrust server input data containing server details
+     * @returns Promise resolving to the typed data structure for server untrust
+     */
+    private composeUntrustServerMessage;
+    /**
+     * Gets the EIP-712 domain for DataPortabilityServers signatures.
+     *
+     * @returns Promise resolving to the EIP-712 domain configuration
+     */
+    private getServersDomain;
+    /**
+     * Submits an add and trust server transaction directly to the blockchain.
+     *
+     * @param addAndTrustServerInput - The add and trust server input data containing server details
+     * @param signature - The cryptographic signature for the transaction
+     * @returns Promise resolving to the transaction hash
+     */
+    private submitAddAndTrustServerTransaction;
+    /**
+     * Submits a trust server transaction directly to the blockchain.
+     *
+     * @param trustServerInput - The trust server input data containing server details
+     * @param signature - The cryptographic signature for the transaction
+     * @returns Promise resolving to the transaction hash
+     */
+    private submitTrustServerTransaction;
+    /**
+     * Submits a revoke transaction directly to the blockchain with signature.
+     *
+     * @param typedData - The EIP-712 typed data structure for the revoke operation
+     * @param signature - The cryptographic signature authorizing the revoke
+     * @returns Promise resolving to the transaction hash
+     */
+    private submitDirectRevokeTransaction;
+    /**
+     * Submits an untrust server transaction with signature.
+     *
+     * @param typedData - The EIP-712 typed data structure for the untrust operation
+     * @param signature - The cryptographic signature authorizing the untrust
+     * @returns Promise resolving to the transaction hash
+     */
+    private submitSignedUntrustTransaction;
+    /**
+     * Registers a new grantee in the DataPortabilityGrantees contract.
+     *
+     * A grantee is an entity (like an application) that can receive data permissions
+     * from users. Once registered, users can grant the grantee access to their data.
+     *
+     * @param params - Parameters for registering the grantee
+     * @param params.owner - The Ethereum address that will own this grantee registration
+     * @param params.granteeAddress - The Ethereum address of the grantee (application)
+     * @param params.publicKey - The public key used for data encryption/decryption (hex string)
+     * @returns Promise resolving to the transaction hash
+     * @throws {BlockchainError} When the grantee registration transaction fails
+     * @throws {UserRejectedRequestError} When user rejects the transaction
+     * @throws {ContractError} When grantee is already registered
+     *
+     * @example
+     * ```typescript
+     * const txHash = await vana.permissions.registerGrantee({
+     *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   granteeAddress: "0xApp1234567890123456789012345678901234567890",
+     *   publicKey: "0x1234567890abcdef..."
+     * });
+     * console.log(`Grantee registered in transaction: ${txHash}`);
+     * ```
+     */
+    submitRegisterGrantee(params: RegisterGranteeParams): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
+    /**
+     * Registers a grantee with a signature (gasless transaction)
+     *
+     * @param params - Parameters for registering the grantee
+     * @returns Promise resolving to the transaction hash
+     *
+     * @example
+     * ```typescript
+     * const txHash = await vana.permissions.registerGranteeWithSignature({
+     *   owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+     *   granteeAddress: "0xApp1234567890123456789012345678901234567890",
+     *   publicKey: "0x1234567890abcdef..."
+     * });
+     * ```
+     */
+    submitRegisterGranteeWithSignature(params: RegisterGranteeParams): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
+    /**
+     * Submits a signed register grantee transaction via relayer
+     *
+     * @param typedData - The EIP-712 typed data for register grantee
+     * @param signature - The cryptographic signature
+     * @returns Promise resolving to the transaction hash
+     *
+     * @example
+     * ```typescript
+     * const result = await vana.permissions.submitSignedRegisterGrantee(typedData, signature);
+     * ```
+     */
+    submitSignedRegisterGrantee(typedData: RegisterGranteeTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
+    /**
+     * Retrieves all registered grantees from the DataPortabilityGrantees contract.
+     *
+     * Returns a paginated list of all grantees (applications) that have been registered
+     * in the system and can receive data permissions from users.
+     *
+     * @param options - Query options for pagination and filtering
+     * @param options.limit - Maximum number of grantees to return (default: 50)
+     * @param options.offset - Number of grantees to skip for pagination (default: 0)
+     * @returns Promise resolving to paginated grantees with metadata
+     * @throws {BlockchainError} When contract read operation fails
+     * @throws {NetworkError} When unable to connect to the blockchain network
+     *
+     * @example
+     * ```typescript
+     * // Get first 10 grantees
+     * const result = await vana.permissions.getGrantees({
+     *   limit: 10,
+     *   offset: 0
+     * });
+     *
+     * console.log(`Found ${result.total} total grantees`);
+     * result.grantees.forEach(grantee => {
+     *   console.log(`Grantee ${grantee.id}: ${grantee.granteeAddress}`);
+     * });
+     *
+     * // Check if there are more results
+     * if (result.hasMore) {
+     *   console.log('More grantees available');
+     * }
+     * ```
+     */
+    getGrantees(options?: GranteeQueryOptions): Promise<PaginatedGrantees>;
+    /**
+     * Retrieves a specific grantee by their Ethereum address from the DataPortabilityGrantees contract.
+     *
+     * Looks up a registered grantee (application) using their Ethereum address
+     * and returns their complete registration information including permissions.
+     *
+     * @param granteeAddress - The Ethereum address of the grantee to look up
+     * @returns Promise resolving to the grantee information, or null if not found
+     * @throws {BlockchainError} When contract read operation fails
+     * @throws {NetworkError} When unable to connect to the blockchain network
+     *
+     * @example
+     * ```typescript
+     * const granteeAddress = "0xApp1234567890123456789012345678901234567890";
+     * const grantee = await vana.permissions.getGranteeByAddress(granteeAddress);
+     *
+     * if (grantee) {
+     *   console.log(`Found grantee ${grantee.id}`);
+     *   console.log(`Owner: ${grantee.owner}`);
+     *   console.log(`Public Key: ${grantee.publicKey}`);
+     *   console.log(`Permissions: ${grantee.permissionIds.join(', ')}`);
+     * } else {
+     *   console.log('Grantee not found');
+     * }
+     * ```
+     */
+    getGranteeByAddress(granteeAddress: Address): Promise<Grantee | null>;
+    /**
+     * Retrieves a specific grantee by their unique ID from the DataPortabilityGrantees contract.
+     *
+     * Looks up a registered grantee (application) using their numeric ID assigned during
+     * registration and returns their complete information including permissions.
+     *
+     * @param granteeId - The unique numeric ID of the grantee (1-indexed)
+     * @returns Promise resolving to the grantee information, or null if not found
+     * @throws {BlockchainError} When contract read operation fails
+     * @throws {NetworkError} When unable to connect to the blockchain network
+     *
+     * @example
+     * ```typescript
+     * const grantee = await vana.permissions.getGranteeById(1);
+     *
+     * if (grantee) {
+     *   console.log(`Grantee ID: ${grantee.id}`);
+     *   console.log(`Address: ${grantee.granteeAddress}`);
+     *   console.log(`Owner: ${grantee.owner}`);
+     *   console.log(`Total permissions: ${grantee.permissionIds.length}`);
+     * } else {
+     *   console.log('Grantee with ID 1 not found');
+     * }
+     * ```
+     */
+    getGranteeById(granteeId: number): Promise<Grantee | null>;
+    /**
+     * Builds EIP-712 typed data for grantee registration
+     *
+     * @param input - The register grantee input
+     * @returns Promise resolving to the typed data structure
+     * @private
+     */
+    private buildRegisterGranteeTypedData;
+    /**
+     * 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
+     */
+    private submitSignedRegisterGranteeTransaction;
+    /**
+     * Get all trusted server IDs for a user
+     *
+     * @param userAddress - User address to query (defaults to current user)
+     * @returns Promise resolving to array of server IDs
+     */
+    getUserServerIds(userAddress?: Address): Promise<bigint[]>;
+    /**
+     * Get server ID at specific index for a user
+     *
+     * @param userAddress - User address to query
+     * @param serverIndex - Index in the user's server list
+     * @returns Promise resolving to server ID
+     */
+    getUserServerIdAt(userAddress: Address, serverIndex: bigint): Promise<bigint>;
+    /**
+     * Get the number of trusted servers for a user
+     *
+     * @param userAddress - User address to query (defaults to current user)
+     * @returns Promise resolving to number of trusted servers
+     */
+    getUserServerCount(userAddress?: Address): Promise<bigint>;
+    /**
+     * Get detailed information about trusted servers for a user
+     *
+     * @param userAddress - User address to query (defaults to current user)
+     * @returns Promise resolving to array of trusted server info
+     */
+    getUserTrustedServers(userAddress?: Address): Promise<TrustedServerInfo[]>;
+    /**
+     * Get trusted server info for a specific server ID and user
+     *
+     * @param userAddress - User address to query
+     * @param serverId - Server ID to get info for
+     * @returns Promise resolving to trusted server info
+     */
+    getUserTrustedServer(userAddress: Address, serverId: bigint): Promise<TrustedServerInfo>;
+    /**
+     * Get server information by server ID
+     *
+     * @param serverId - Server ID to get info for
+     * @returns Promise resolving to server info
+     */
+    getServerInfo(serverId: bigint): Promise<ServerInfo>;
+    /**
+     * Get server information by server address
+     *
+     * @param serverAddress - Server address to get info for
+     * @returns Promise resolving to server info
+     */
+    getServerInfoByAddress(serverAddress: Address): Promise<ServerInfo>;
+    /**
+     * Get all permission IDs for a user
+     *
+     * @param userAddress - User address to query (defaults to current user)
+     * @returns Promise resolving to array of permission IDs
+     */
+    getUserPermissionIds(userAddress?: Address): Promise<bigint[]>;
+    /**
+     * Get permission ID at specific index for a user
+     *
+     * @param userAddress - User address to query
+     * @param permissionIndex - Index in the user's permission list
+     * @returns Promise resolving to permission ID
+     */
+    getUserPermissionIdAt(userAddress: Address, permissionIndex: bigint): Promise<bigint>;
+    /**
+     * Get the number of permissions for a user
+     *
+     * @param userAddress - User address to query (defaults to current user)
+     * @returns Promise resolving to number of permissions
+     */
+    getUserPermissionCount(userAddress?: Address): Promise<bigint>;
+    /**
+     * Get detailed permission information by permission ID
+     *
+     * @param permissionId - Permission ID to get info for
+     * @returns Promise resolving to permission info
+     */
+    getPermissionInfo(permissionId: bigint): Promise<PermissionInfo>;
+    /**
+     * Get all permission IDs for a specific file
+     *
+     * @param fileId - File ID to get permissions for
+     * @returns Promise resolving to array of permission IDs
+     */
+    getFilePermissionIds(fileId: bigint): Promise<bigint[]>;
+    /**
+     * Get all file IDs for a specific permission
+     *
+     * @param permissionId - Permission ID to get files for
+     * @returns Promise resolving to array of file IDs
+     */
+    getPermissionFileIds(permissionId: bigint): Promise<bigint[]>;
+    /**
+     * Get all permissions for a specific file (alias for getFilePermissionIds)
+     *
+     * @param fileId - File ID to get permissions for
+     * @returns Promise resolving to array of permission IDs
+     */
+    getFilePermissions(fileId: bigint): Promise<bigint[]>;
+    /**
+     * Get grantee information by grantee ID
+     *
+     * @param granteeId - Grantee ID to get info for
+     * @returns Promise resolving to grantee info
+     */
+    getGranteeInfo(granteeId: bigint): Promise<GranteeInfo>;
+    /**
+     * Get grantee information by grantee address
+     *
+     * @param granteeAddress - Grantee address to get info for
+     * @returns Promise resolving to grantee info
+     */
+    getGranteeInfoByAddress(granteeAddress: Address): Promise<GranteeInfo>;
+    /**
+     * Get all permission IDs for a specific grantee
+     *
+     * @param granteeId - Grantee ID to get permissions for
+     * @returns Promise resolving to array of permission IDs
+     */
+    getGranteePermissionIds(granteeId: bigint): Promise<bigint[]>;
+    /**
+     * Get all permissions for a specific grantee (alias for getGranteePermissionIds)
+     *
+     * @param granteeId - Grantee ID to get permissions for
+     * @returns Promise resolving to array of permission IDs
+     */
+    getGranteePermissions(granteeId: bigint): Promise<bigint[]>;
+    /**
+     * Get all server IDs for a user
+     *
+     * @param userAddress - User address to get server IDs for
+     * @returns Promise resolving to array of server IDs
+     */
+    getUserServerIdsValues(userAddress: Address): Promise<bigint[]>;
+    /**
+     * Get server ID at specific index for a user
+     *
+     * @param userAddress - User address
+     * @param serverIndex - Index of the server ID
+     * @returns Promise resolving to server ID
+     */
+    getUserServerIdsAt(userAddress: Address, serverIndex: bigint): Promise<bigint>;
+    /**
+     * Get the number of servers a user has
+     *
+     * @param userAddress - User address
+     * @returns Promise resolving to number of servers
+     */
+    getUserServerIdsLength(userAddress: Address): Promise<bigint>;
+    /**
+     * Get trusted server info for a specific user and server ID
+     *
+     * @param userAddress - User address
+     * @param serverId - Server ID
+     * @returns Promise resolving to trusted server info
+     */
+    getUserServers(userAddress: Address, serverId: bigint): Promise<TrustedServerInfo>;
+    /**
+     * Get server info by server ID
+     *
+     * @param serverId - Server ID
+     * @returns Promise resolving to server info
+     */
+    getServers(serverId: bigint): Promise<ServerInfo>;
+    /**
+     * Get user info including nonce and trusted server IDs
+     *
+     * @param userAddress - User address
+     * @returns Promise resolving to user info
+     */
+    getUsers(userAddress: Address): Promise<{
+        nonce: bigint;
+        trustedServerIds: bigint[];
+    }>;
+    /**
+     * Update server URL
+     *
+     * @param serverId - Server ID to update
+     * @param url - New URL for the server
+     * @returns Promise resolving to transaction hash
+     */
+    submitUpdateServer(serverId: bigint, url: string): Promise<TransactionResult<"DataPortabilityServers", "updateServer">>;
+    /**
+     * Get all permission IDs for a user
+     *
+     * @param userAddress - User address to get permission IDs for
+     * @returns Promise resolving to array of permission IDs
+     */
+    getUserPermissionIdsValues(userAddress: Address): Promise<bigint[]>;
+    /**
+     * Get permission ID at specific index for a user
+     *
+     * @param userAddress - User address
+     * @param permissionIndex - Index of the permission ID
+     * @returns Promise resolving to permission ID
+     */
+    getUserPermissionIdsAt(userAddress: Address, permissionIndex: bigint): Promise<bigint>;
+    /**
+     * Get the number of permissions a user has
+     *
+     * @param userAddress - User address
+     * @returns Promise resolving to number of permissions
+     */
+    getUserPermissionIdsLength(userAddress: Address): Promise<bigint>;
+    /**
+     * Get permission info by permission ID
+     *
+     * @param permissionId - Permission ID
+     * @returns Promise resolving to permission info
+     */
+    getPermissions(permissionId: bigint): Promise<PermissionInfo>;
+    /**
+     * Submit permission with signature to the blockchain (supports gasless transactions)
+     *
+     * @param params - Parameters for adding permission
+     * @returns Promise resolving to transaction hash
+     * @throws {RelayerError} When gasless transaction submission fails
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {BlockchainError} When permission addition fails
+     * @throws {NetworkError} When network communication fails
+     */
+    submitAddPermission(params: ServerFilesAndPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    /**
+     * Submits an already-signed add permission transaction to the blockchain.
+     * This method supports both relayer-based gasless transactions and direct transactions.
+     *
+     * @param typedData - The EIP-712 typed data for AddPermission
+     * @param signature - The user's signature
+     * @returns Promise resolving to TransactionResult with PermissionGrantResult event data
+     * @throws {RelayerError} When gasless transaction submission fails
+     * @throws {BlockchainError} When permission addition fails
+     * @throws {NetworkError} When network communication fails
+     */
+    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    /**
+     * Submits server files and permissions with signature to the blockchain, supporting schema validation and gasless transactions.
+     *
+     * @remarks
+     * This method validates files against their specified schemas before submission.
+     * Schema validation ensures data conforms to expected formats before on-chain registration.
+     * Files with schemaId = 0 bypass validation. The method supports atomic batch operations
+     * where all files and permissions are registered in a single transaction.
+     *
+     * @param params - Parameters for adding server files and permissions
+     * @param params.granteeId - The ID of the permission grantee
+     * @param params.grant - Grant URL containing permission parameters (typically IPFS)
+     * @param params.fileUrls - Array of file URLs to register
+     * @param params.schemaIds - Schema IDs for each file. Use 0 for files without schema validation.
+     *   Array length must match fileUrls length.
+     * @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`.
+     * @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
+     * @throws {SchemaValidationError} When file data doesn't match the specified schema.
+     *   Verify data structure matches schema definition from `vana.schemas.get(schemaId)`.
+     * @throws {RelayerError} When gasless transaction submission fails.
+     *   Retry without relayer configuration to submit direct transaction.
+     * @throws {SignatureError} When user rejects the signature request
+     * @throws {BlockchainError} When server files and permissions addition fails
+     * @throws {NetworkError} When network communication fails.
+     *   Check network connection or configure alternative gateways.
+     *
+     * @example
+     * ```typescript
+     * const result = await vana.permissions.submitAddServerFilesAndPermissions({
+     *   granteeId: BigInt(1),
+     *   grant: "ipfs://QmXxx...",
+     *   fileUrls: ["https://storage.example.com/data.json"],
+     *   schemaIds: [123], // LinkedIn profile schema ID
+     *   serverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
+     *   serverUrl: "https://server.example.com",
+     *   serverPublicKey: serverInfo.public_key,
+     *   filePermissions: [[{
+     *     account: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
+     *     key: encryptedKey
+     *   }]]
+     * });
+     * const events = await result.waitForEvents();
+     * console.log(`Permission ID: ${events.permissionId}`);
+     * ```
+     */
+    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
+    /**
+     * Submits an already-signed add server files and permissions transaction to the blockchain.
+     *
+     * @remarks
+     * This method returns a TransactionResult that provides immediate access to the transaction hash.
+     * The eventData field may contain parsed event details after transaction confirmation.
+     *
+     * @param typedData - The EIP-712 typed data for AddServerFilesAndPermissions
+     * @param signature - The user's signature
+     * @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
+     * @throws {NetworkError} When network communication fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await vana.permissions.submitSignedAddServerFilesAndPermissions(
+     *   typedData,
+     *   signature
+     * );
+     * console.log(`Transaction submitted: ${tx.hash}`);
+     *
+     * // Wait for confirmation and get the permission ID
+     * const { permissionId } = await tx.waitForEvents();
+     * console.log(`Permission created with ID: ${permissionId}`);
+     * ```
+     */
+    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
+    /**
+     * Submit permission revocation with signature to the blockchain
+     *
+     * @param permissionId - Permission ID to revoke
+     * @returns Promise resolving to transaction hash
+     */
+    submitRevokePermission(permissionId: bigint): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
+    /**
+     * Submits a signed add permission transaction directly to the blockchain.
+     *
+     * @param typedData - The typed data structure for the permission addition
+     * @param signature - The cryptographic signature authorizing the transaction
+     * @returns Promise resolving to the transaction hash
+     */
+    private submitDirectAddPermissionTransaction;
+    /**
+     * Submits a signed add server files and permissions transaction directly to the blockchain.
+     *
+     * @param typedData - The typed data structure for the server files and permissions addition
+     * @param signature - The cryptographic signature authorizing the transaction
+     * @returns Promise resolving to the transaction hash
+     */
+    private submitDirectAddServerFilesAndPermissionsTransaction;
+}
+
+export { ControllerContext, PermissionsController };