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

package/dist/permissions-DNKPu_G0.d.cts

@@ -0,0 +1,1666 @@
+import { TransactionResult, TransactionWaitOptions, Operation, PollingOptions } from './types/operations.cjs';
+import { Hash, Address, WalletClient, PublicClient } from 'viem';
+import { RelayerCallbacks, DownloadRelayerCallbacks } from './types/config.cjs';
+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.cjs';
+import { TransactionOperation } from './config/eventMappings.cjs';
+import { StorageManager } from './storage/manager.cjs';
+import { VanaPlatformAdapter } from './platform/interface.cjs';
+
+/**
+ * Base interface for all transaction results.
+ * Contains the event data plus transaction metadata.
+ */
+interface BaseTransactionResult {
+    transactionHash: Hash;
+    blockNumber: bigint;
+    gasUsed: bigint;
+}
+/**
+ * Generic transaction result parser that extracts event data from transaction receipts.
+ *
+ * This utility provides a consistent way to parse blockchain events from completed
+ * transactions across all SDK controllers. It handles receipt fetching, event parsing,
+ * error handling, and result formatting automatically.
+ *
+ * @param context - Controller context containing blockchain clients
+ * @param hash - Transaction hash to parse
+ * @param operation - SDK operation name (maps to contract/event via EVENT_MAPPINGS)
+ * @returns Promise resolving to event args plus transaction metadata
+ * @throws {NetworkError} When transaction receipt cannot be fetched
+ * @throws {BlockchainError} When expected event is not found in transaction
+ *
+ * @example
+ * ```typescript
+ * // Parse a permission grant transaction
+ * const result = await parseTransactionResult(context, txHash, 'grant');
+ * console.log(`Permission ${result.permissionId} granted to ${result.user}`);
+ *
+ * // Parse a file addition transaction
+ * const result = await parseTransactionResult(context, txHash, 'addFile');
+ * console.log(`File ${result.fileId} added at ${result.url}`);
+ * ```
+ */
+declare function parseTransactionResult<K extends TransactionOperation>(context: ControllerContext, hash: Hash, operation: K): Promise<TransactionResultMap[K]>;
+
+/**
+ * Transaction result types for all SDK operations.
+ * These interfaces define the structure of data returned by enhanced
+ * transaction methods that parse blockchain events automatically.
+ */
+/**
+ * Result of a successful permission grant operation.
+ * Contains data from the PermissionAdded blockchain event.
+ */
+interface PermissionGrantResult extends BaseTransactionResult {
+    /** Unique permission ID for this grant */
+    permissionId: bigint;
+    /** Address of the user who granted the permission */
+    user: Address;
+    /** URL where the grant file is stored (IPFS/CDN) */
+    grant: string;
+    /** Array of file IDs covered by this permission */
+    fileIds: readonly bigint[];
+}
+/**
+ * Result of a successful permission revocation operation.
+ * Contains data from the PermissionRevoked blockchain event.
+ */
+interface PermissionRevokeResult extends BaseTransactionResult {
+    /** ID of the permission that was revoked */
+    permissionId: bigint;
+}
+/**
+ * Result of a successful server trust operation.
+ * Contains data from the ServerTrusted blockchain event.
+ */
+interface ServerTrustResult extends BaseTransactionResult {
+    /** Address of the user who trusted the server */
+    user: Address;
+    /** Address/ID of the trusted server */
+    serverId: Address;
+    /** URL of the trusted server */
+    serverUrl: string;
+}
+/**
+ * Result of a successful server untrust operation.
+ * Contains data from the ServerUntrusted blockchain event.
+ */
+interface ServerUntrustResult extends BaseTransactionResult {
+    /** Address of the user who untrusted the server */
+    user: Address;
+    /** Address/ID of the untrusted server */
+    serverId: Address;
+}
+/**
+ * Result of a successful server registration operation.
+ * Contains data from the ServerRegistered blockchain event.
+ */
+interface ServerRegisterResult extends BaseTransactionResult {
+    /** Unique server ID assigned by the registry */
+    serverId: bigint;
+    /** URL of the registered server */
+    url: string;
+    /** Owner address of the server */
+    owner: Address;
+}
+/**
+ * Result of a successful server update operation.
+ * Contains data from the ServerUpdated blockchain event.
+ */
+interface ServerUpdateResult extends BaseTransactionResult {
+    /** ID of the server that was updated */
+    serverId: bigint;
+    /** New URL of the server */
+    url: string;
+}
+/**
+ * Result of a successful grantee registration operation.
+ * Contains data from the GranteeRegistered blockchain event.
+ */
+interface GranteeRegisterResult extends BaseTransactionResult {
+    /** Unique grantee ID assigned by the registry */
+    granteeId: bigint;
+    /** Address of the registered grantee */
+    granteeAddress: Address;
+    /** Display name of the grantee */
+    name: string;
+}
+/**
+ * Result of a successful file addition operation.
+ * Contains data from the FileAddedV2 blockchain event.
+ */
+interface FileAddedResult extends BaseTransactionResult {
+    /** Unique file ID assigned by the registry */
+    fileId: bigint;
+    /** Address of the file owner */
+    ownerAddress: Address;
+    /** URL where the file is stored */
+    url: string;
+    /** Schema ID associated with the file (0 for no schema) */
+    schemaId: bigint;
+}
+/**
+ * Result of a successful schema addition operation.
+ * Contains data from the SchemaAdded blockchain event.
+ */
+interface SchemaAddedResult extends BaseTransactionResult {
+    /** Unique schema ID assigned by the registry */
+    schemaId: bigint;
+    /** Human-readable name of the schema */
+    name: string;
+    /** Schema dialect (e.g., "jsonschema") */
+    dialect: string;
+    /** URL where the schema definition is stored */
+    definitionUrl: string;
+}
+/**
+ * Result of a successful refiner addition operation.
+ * Contains data from the RefinerAdded blockchain event.
+ */
+interface RefinerAddedResult extends BaseTransactionResult {
+    /** Unique refiner ID assigned by the registry */
+    refinerId: bigint;
+    /** DLP ID this refiner belongs to */
+    dlpId: bigint;
+    /** Human-readable name of the refiner */
+    name: string;
+    /** Schema ID this refiner uses */
+    schemaId: bigint;
+    /** URL where the schema definition is stored */
+    schemaDefinitionUrl: string;
+    /** URL with refiner processing instructions */
+    refinementInstructionUrl: string;
+}
+/**
+ * Result of a successful schema ID update operation.
+ * Contains data from the RefinerSchemaUpdated blockchain event.
+ */
+interface SchemaUpdateResult extends BaseTransactionResult {
+    /** ID of the refiner that was updated */
+    refinerId: bigint;
+    /** New schema ID */
+    schemaId: bigint;
+    /** URL of the new schema definition */
+    schemaDefinitionUrl: string;
+}
+/**
+ * Result of a successful file permission addition operation.
+ * Contains data from the FilePermissionAdded blockchain event.
+ */
+interface FilePermissionResult extends BaseTransactionResult {
+    /** File ID the permission was added to */
+    fileId: bigint;
+    /** Account that was granted permission */
+    account: Address;
+    /** Encrypted key for file access */
+    encryptedKey: string;
+}
+/**
+ * Union type of all possible transaction result types.
+ * Useful for generic functions that handle multiple operation types.
+ */
+type AnyTransactionResult = PermissionGrantResult | PermissionRevokeResult | ServerTrustResult | ServerUntrustResult | ServerRegisterResult | ServerUpdateResult | GranteeRegisterResult | FileAddedResult | SchemaAddedResult | RefinerAddedResult | SchemaUpdateResult | FilePermissionResult;
+/**
+ * Maps transaction operation names to their result types.
+ * Used for type inference in generic transaction parsing functions.
+ */
+interface TransactionResultMap {
+    grant: PermissionGrantResult;
+    revoke: PermissionRevokeResult;
+    revokePermission: PermissionRevokeResult;
+    addServerFilesAndPermissions: PermissionGrantResult;
+    trustServer: ServerTrustResult;
+    untrustServer: ServerUntrustResult;
+    registerServer: ServerRegisterResult;
+    updateServer: ServerUpdateResult;
+    addAndTrustServer: ServerTrustResult;
+    registerGrantee: GranteeRegisterResult;
+    addFile: FileAddedResult;
+    addFileWithPermissionsAndSchema: FileAddedResult;
+    addFileWithSchema: FileAddedResult;
+    addFileWithPermissions: FileAddedResult;
+    addRefinement: RefinerAddedResult;
+    addRefiner: RefinerAddedResult;
+    updateSchemaId: SchemaUpdateResult;
+    addSchema: SchemaAddedResult;
+    updateRefinement: SchemaUpdateResult;
+    addFilePermission: FilePermissionResult;
+}
+
+/**
+ * Provides shared configuration and services for all SDK controllers.
+ *
+ * @remarks
+ * This interface defines the foundational blockchain and storage services that all
+ * controllers require for operation. The main Vana SDK class automatically creates
+ * this context during initialization and passes it to each controller. It includes
+ * wallet clients for transaction signing, storage managers for file operations,
+ * and platform adapters for environment-specific functionality.
+ * @category Configuration
+ */
+interface ControllerContext {
+    /** Signs transactions and messages using the user's private key. */
+    walletClient: WalletClient;
+    /** Queries blockchain state and smart contracts without signing. */
+    publicClient: PublicClient;
+    /** Signs application-specific operations when different from primary wallet. */
+    applicationClient?: WalletClient;
+    /** Handles gasless transaction submission through relayer services. */
+    relayerCallbacks?: RelayerCallbacks;
+    /** Proxies CORS-restricted downloads through application server. */
+    downloadRelayer?: DownloadRelayerCallbacks;
+    /** Manages file upload and download operations across storage providers. */
+    storageManager?: StorageManager;
+    /** Provides subgraph endpoint for querying indexed blockchain data. */
+    subgraphUrl?: string;
+    /** Adapts SDK functionality to the current runtime environment. */
+    platform: VanaPlatformAdapter;
+    /** Validates that storage is available for storage-dependent operations. */
+    validateStorageRequired?: () => void;
+    /** Checks whether storage is configured without throwing an error. */
+    hasStorage?: () => boolean;
+    /** Default IPFS gateways to use for fetching files. */
+    ipfsGateways?: string[];
+    /** Default personal server base URL for server operations. */
+    defaultPersonalServerUrl?: string;
+    /** Waits for transaction confirmation and parses typed events. */
+    waitForTransactionEvents?: <T = unknown>(hashOrObj: Hash | TransactionResult | {
+        hash: Hash;
+    }, options?: TransactionWaitOptions) => Promise<T>;
+    /** Waits for an operation to complete with polling. */
+    waitForOperation?: <T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions) => Promise<Operation<T>>;
+}
+/**
+ * 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<TransactionResult & {
+        eventData?: 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 & {
+        eventData?: PermissionGrantResult;
+    }>;
+    /**
+     * 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<TransactionResult & {
+            eventData?: 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 & {
+        eventData?: PermissionGrantResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerTrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerTrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionRevokeResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerUntrustResult;
+    }>;
+    /**
+     * 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<TransactionResult & {
+        eventData?: 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 & {
+        eventData?: PermissionRevokeResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionRevokeResult;
+    }>;
+    /**
+     * @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<TransactionResult & {
+        eventData?: 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 & {
+        eventData?: ServerTrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerTrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerTrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerUntrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerUntrustResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: GranteeRegisterResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: GranteeRegisterResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: GranteeRegisterResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: ServerUpdateResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionGrantResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionGrantResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionGrantResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionGrantResult;
+    }>;
+    /**
+     * 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 & {
+        eventData?: PermissionRevokeResult;
+    }>;
+    /**
+     * 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 { type AnyTransactionResult as A, type BaseTransactionResult as B, type ControllerContext as C, type FilePermissionResult as F, type GranteeRegisterResult as G, PermissionsController as P, type RefinerAddedResult as R, type SchemaAddedResult as S, type TransactionResultMap as T, type FileAddedResult as a, type PermissionGrantResult as b, type PermissionRevokeResult as c, type ServerTrustResult as d, type ServerUntrustResult as e, type ServerRegisterResult as f, type ServerUpdateResult as g, type SchemaUpdateResult as h, parseTransactionResult as p };