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

package/dist/controllers/permissions.d.ts

@@ -1,7 +1,7 @@
 import type { Address, Hash } from "viem";
+import type { TransactionOptions, TransactionResult } from "../types/operations";
 import type { GrantPermissionParams, RevokePermissionParams, PermissionGrantTypedData, GenericTypedData, OnChainPermissionGrant, GetUserPermissionsOptions, AddAndTrustServerParams, TrustServerParams, UntrustServerParams, AddAndTrustServerTypedData, TrustServerTypedData, TrustedServerInfo, PaginatedTrustedServers, TrustedServerQueryOptions, BatchServerInfoResult, ServerTrustStatus, GrantFile, Grantee, GranteeInfo, RegisterGranteeParams, GranteeQueryOptions, PaginatedGrantees, ServerInfo, ServerFilesAndPermissionParams, ServerFilesAndPermissionTypedData } from "../types/index";
 import type { PermissionGrantResult, PermissionRevokeResult, ServerTrustResult } from "../types/transactionResults";
-import type { TransactionResult } from "../types/operations";
 import type { PermissionInfo } from "../types/permissions";
 /**
  * Provides shared configuration and services for all SDK controllers.
@@ -18,50 +18,52 @@ import type { ControllerContext } from "../types/controller-context";
 import { BaseController } from "./base";
 export type { ControllerContext };
 /**
- * Manages gasless data access permissions and trusted server registry operations.
+ * Manages data access permissions and trusted server operations with gasless transaction support.
  *
  * @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.
+ * Enables applications to access user data through EIP-712 signatures, eliminating gas fees
+ * for users. Handles permission lifecycle from creation through revocation, plus trusted
+ * server management for data processing operations.
  *
- * **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.
+ * **Architecture:**
+ * Permissions use dual storage: complex parameters on IPFS, references on blockchain.
+ * This minimizes on-chain data while maintaining decentralization and auditability.
  *
  * **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
+ * - `grant()` - Create permissions with automatic IPFS upload and blockchain registration
+ * - `prepareGrant()` - Preview permission structure before signing
+ * - `revoke()` - Remove permissions by ID (gasless or direct)
+ * - `getUserPermissionGrantsOnChain()` - Query active permissions
+ * - `trustServer()`/`untrustServer()` - Manage server access
+ *
+ * **Gasless Support:**
+ * All permission methods support both gasless (via relayer) and direct transactions.
+ * Configure relayer callbacks in Vana initialization for gasless operations.
  *
- * **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({
+ * // Grant data access permission
+ * const result = await vana.permissions.grant({
  *   grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
  *   operation: "llm_inference",
- *   files: [1, 2, 3],
- *   parameters: { model: "gpt-4", maxTokens: 1000 },
+ *   fileIds: [1, 2, 3],
+ *   parameters: { model: "gpt-4", maxTokens: 1000 }
  * });
+ * console.log(`Permission ${result.permissionId} granted`);
  *
- * // Trust a server for data processing
+ * // Trust server for processing
  * await vana.permissions.trustServer({
- *   serverId: "0x123...",
- *   serverUrl: "https://personal-server.vana.org",
+ *   serverAddress: "0x123...",
+ *   serverUrl: "https://personal-server.vana.org"
  * });
  *
- * // Query current permissions
+ * // Query active permissions
  * const permissions = await vana.permissions.getUserPermissionGrantsOnChain();
+ * permissions.forEach(p => console.log(`Permission ${p.id}: ${p.grantee}`));
  * ```
+ *
  * @category Permissions
- * @see {@link https://docs.vana.com/developer/permissions | Vana Permissions System} for conceptual overview
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/permissions}
  */
 export declare class PermissionsController extends BaseController {
     constructor(context: ControllerContext);
@@ -99,7 +101,7 @@ export declare class PermissionsController extends BaseController {
      * await vana.permissions.revoke({ permissionId: result.permissionId });
      * ```
      */
-    grant(params: GrantPermissionParams): Promise<PermissionGrantResult>;
+    grant(params: GrantPermissionParams, options?: TransactionOptions): Promise<PermissionGrantResult>;
     /**
      * Submits a permission grant transaction and returns a handle for flexible result access.
      *
@@ -125,7 +127,7 @@ export declare class PermissionsController extends BaseController {
      * console.log(`Permission ID: ${eventData.permissionId}`);
      * ```
      */
-    submitPermissionGrant(params: GrantPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    submitPermissionGrant(params: GrantPermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
     /**
      * Prepares a permission grant with preview before signing.
      *
@@ -151,7 +153,7 @@ export declare class PermissionsController extends BaseController {
      * const transactionHash = await confirm();
      * ```
      */
-    prepareGrant(params: GrantPermissionParams): Promise<{
+    prepareGrant(params: GrantPermissionParams, options?: TransactionOptions): Promise<{
         preview: GrantFile;
         confirm: () => Promise<PermissionGrantResult>;
     }>;
@@ -223,7 +225,7 @@ export declare class PermissionsController extends BaseController {
      * );
      * ```
      */
-    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    submitSignedGrant(typedData: PermissionGrantTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
     /**
      * Submits an already-signed trust server transaction to the blockchain.
      *
@@ -245,7 +247,7 @@ export declare class PermissionsController extends BaseController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
+    submitSignedTrustServer(typedData: TrustServerTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
     /**
      * Submits an already-signed add and trust server transaction to the blockchain.
      *
@@ -267,7 +269,7 @@ export declare class PermissionsController extends BaseController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
+    submitSignedAddAndTrustServer(typedData: AddAndTrustServerTypedData, signature: Hash, _options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
     /**
      * Internal method to submit a signed grant and wait for events.
      *
@@ -286,6 +288,15 @@ export declare class PermissionsController extends BaseController {
      * @returns Promise resolving to PermissionGrantResult with parsed events
      */
     private confirmGrantInternalWithEvents;
+    /**
+     * Polls the relayer for confirmation of a pending operation.
+     *
+     * @param operationId - The operation ID to poll
+     * @returns Promise resolving to the confirmed hash
+     * @throws {Error} When the operation fails or times out
+     * @internal
+     */
+    private pollRelayerForConfirmation;
     /**
      * Submits an already-signed permission revoke transaction to the blockchain.
      *
@@ -307,7 +318,7 @@ export declare class PermissionsController extends BaseController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedRevoke(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
+    submitSignedRevoke(typedData: GenericTypedData, signature: Hash, _options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
     /**
      * Submits an already-signed untrust server transaction to the blockchain.
      *
@@ -329,7 +340,7 @@ export declare class PermissionsController extends BaseController {
      * const result = await txHandle.waitForEvents();
      * ```
      */
-    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityServers", "untrustServerWithSignature">>;
+    submitSignedUntrustServer(typedData: GenericTypedData, signature: Hash, _options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "untrustServerWithSignature">>;
     /**
      * Submits a signed transaction directly to the blockchain.
      *
@@ -375,6 +386,7 @@ export declare class PermissionsController extends BaseController {
      * Use this when you want to handle transaction confirmation and event parsing separately.
      *
      * @param params - Parameters for revoking the permission
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to the transaction hash when successfully submitted
      * @throws {BlockchainError} When revocation transaction fails
      * @throws {UserRejectedRequestError} When user rejects the transaction
@@ -387,7 +399,7 @@ export declare class PermissionsController extends BaseController {
      * console.log(`Revocation submitted: ${txHash}`);
      * ```
      */
-    submitPermissionRevoke(params: RevokePermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
+    submitPermissionRevoke(params: RevokePermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
     /**
      * Revokes a permission with a signature for gasless transactions.
      *
@@ -636,6 +648,7 @@ export declare class PermissionsController extends BaseController {
      *
      * @param params - Parameters for untrusting the server
      * @param params.serverId - The numeric ID of the server to untrust
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to transaction hash
      * @throws {Error} When wallet account is not available
      * @throws {NonceError} When retrieving user nonce fails
@@ -656,7 +669,7 @@ export declare class PermissionsController extends BaseController {
      * console.log('Still trusting servers:', trustedServers);
      * ```
      */
-    submitUntrustServer(params: UntrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "untrustServer">>;
+    submitUntrustServer(params: UntrustServerParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "untrustServer">>;
     /**
      * Untrusts a server using a signature (gasless transaction).
      *
@@ -840,6 +853,7 @@ export declare class PermissionsController extends BaseController {
      * @param params.owner - The Ethereum address that will own this grantee registration
      * @param params.granteeAddress - The Ethereum address of the grantee (application)
      * @param params.publicKey - The public key used for data encryption/decryption (hex string)
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to the transaction hash
      * @throws {BlockchainError} When the grantee registration transaction fails
      * @throws {UserRejectedRequestError} When user rejects the transaction
@@ -855,7 +869,7 @@ export declare class PermissionsController extends BaseController {
      * console.log(`Grantee registered in transaction: ${txHash}`);
      * ```
      */
-    submitRegisterGrantee(params: RegisterGranteeParams): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
+    submitRegisterGrantee(params: RegisterGranteeParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityGrantees", "registerGrantee">>;
     /**
      * Retrieves all registered grantees from the DataPortabilityGrantees contract.
      *
@@ -1123,9 +1137,10 @@ export declare class PermissionsController extends BaseController {
      *
      * @param serverId - Server ID to update
      * @param url - New URL for the server
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to transaction hash
      */
-    submitUpdateServer(serverId: bigint, url: string): Promise<TransactionResult<"DataPortabilityServers", "updateServer">>;
+    submitUpdateServer(serverId: bigint, url: string, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "updateServer">>;
     /**
      * Get all permission IDs for a user
      *
@@ -1177,7 +1192,7 @@ export declare class PermissionsController extends BaseController {
      * @throws {BlockchainError} When permission addition fails
      * @throws {NetworkError} When network communication fails
      */
-    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
+    submitSignedAddPermission(typedData: GenericTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addPermission">>;
     /**
      * Submits server files and permissions with signature to the blockchain, supporting schema validation and gasless transactions.
      *
@@ -1198,6 +1213,9 @@ export declare class PermissionsController extends BaseController {
      * @param params.serverPublicKey - Server's public key for encryption.
      *   Obtain via `vana.server.getIdentity(userAddress).publicKey`.
      * @param params.filePermissions - Nested array of permissions for each file
+     * @param options - Optional transaction options for gas parameters and timeout.
+     *   Note: These options are only applied for direct blockchain transactions.
+     *   When using relayer callbacks (gasless transactions), these options are ignored.
      * @returns TransactionResult with immediate hash access and optional event data
      * @throws {Error} When schemaIds array length doesn't match fileUrls array length
      * @throws {SchemaValidationError} When file data doesn't match the specified schema.
@@ -1211,6 +1229,7 @@ export declare class PermissionsController extends BaseController {
      *
      * @example
      * ```typescript
+     * // Submit with custom gas parameters and timeout
      * const result = await vana.permissions.submitAddServerFilesAndPermissions({
      *   granteeId: BigInt(1),
      *   grant: "ipfs://QmXxx...",
@@ -1223,12 +1242,19 @@ export declare class PermissionsController extends BaseController {
      *     account: "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb",
      *     key: encryptedKey
      *   }]]
+     * }, {
+     *   maxFeePerGas: 100n * 10n ** 9n, // 100 gwei
+     *   maxPriorityFeePerGas: 2n * 10n ** 9n, // 2 gwei tip
+     * });
+     *
+     * // Wait for confirmation with custom timeout
+     * const receipt = await vana.waitForTransactionReceipt(result, {
+     *   timeout: 180000 // 3 minutes
      * });
-     * const events = await result.waitForEvents();
-     * console.log(`Permission ID: ${events.permissionId}`);
+     * console.log(`Transaction confirmed: ${receipt.transactionHash}`);
      * ```
      */
-    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
+    submitAddServerFilesAndPermissions(params: ServerFilesAndPermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
     /**
      * Submits an already-signed add server files and permissions transaction to the blockchain.
      *
@@ -1238,6 +1264,9 @@ export declare class PermissionsController extends BaseController {
      *
      * @param typedData - The EIP-712 typed data for AddServerFilesAndPermissions
      * @param signature - The user's signature
+     * @param options - Optional transaction options for gas parameters and timeout.
+     *   Note: These options are only applied for direct blockchain transactions.
+     *   When using relayer callbacks (gasless transactions), these options are ignored.
      * @returns TransactionResult with immediate hash access and optional event data
      * @throws {RelayerError} When gasless transaction submission fails
      * @throws {BlockchainError} When server files and permissions addition fails
@@ -1256,14 +1285,15 @@ export declare class PermissionsController extends BaseController {
      * console.log(`Permission created with ID: ${permissionId}`);
      * ```
      */
-    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
+    submitSignedAddServerFilesAndPermissions(typedData: ServerFilesAndPermissionTypedData, signature: Hash, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "addServerFilesAndPermissions">>;
     /**
      * Submit permission revocation with signature to the blockchain
      *
      * @param permissionId - Permission ID to revoke
+     * @param options - Optional transaction options for gas parameters and timeout
      * @returns Promise resolving to transaction hash
      */
-    submitRevokePermission(permissionId: bigint): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
+    submitRevokePermission(permissionId: bigint, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermission">>;
     /**
      * Submits a signed add permission transaction directly to the blockchain.
      *