@opendatalabs/vana-sdk 0.1.0-alpha.a6b60fc → 0.1.0-alpha.a78ce5c

package/dist/controllers/permissions.d.ts

@@ -1,7 +1,7 @@
 import type { Address, Hash } from "viem";
-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, TransactionOptions } from "../types/index";
+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.
@@ -101,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.
      *
@@ -127,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.
      *
@@ -153,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>;
     }>;
@@ -225,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.
      *
@@ -247,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.
      *
@@ -269,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.
      *
@@ -288,6 +288,17 @@ 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
+     * @param options - Polling configuration including status updates and cancellation
+     * @returns Promise resolving to the confirmed hash and receipt
+     * @throws {TransactionPendingError} When the operation times out
+     * @throws {Error} When the operation fails or is cancelled
+     * @internal
+     */
+    private pollRelayerForConfirmation;
     /**
      * Submits an already-signed permission revoke transaction to the blockchain.
      *
@@ -309,7 +320,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.
      *
@@ -331,7 +342,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.
      *
@@ -416,7 +427,7 @@ export declare class PermissionsController extends BaseController {
      * console.log(`Permission ${result.permissionId} revoked`);
      * ```
      */
-    submitRevokeWithSignature(params: RevokePermissionParams): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
+    submitRevokeWithSignature(params: RevokePermissionParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityPermissions", "revokePermissionWithSignature">>;
     /**
      * Retrieves the user's current nonce from the DataPortabilityServers contract.
      * This nonce is used for server-related operations (AddAndTrustServer, TrustServer, UntrustServer).
@@ -598,7 +609,7 @@ export declare class PermissionsController extends BaseController {
      * @param params - Parameters for adding and trusting the server
      * @returns Promise resolving to TransactionResult with ServerTrustResult event data
      */
-    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
+    submitAddAndTrustServerWithSignature(params: AddAndTrustServerParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "addAndTrustServerWithSignature">>;
     /**
      * Trusts a server using a signature (gasless transaction - legacy method).
      *
@@ -612,7 +623,7 @@ export declare class PermissionsController extends BaseController {
      * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
      * @throws {BlockchainError} When trust operation fails for any other reason
      */
-    submitTrustServerWithSignature(params: TrustServerParams): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
+    submitTrustServerWithSignature(params: TrustServerParams, options?: TransactionOptions): Promise<TransactionResult<"DataPortabilityServers", "trustServerWithSignature">>;
     /**
      * Submits a direct untrust server transaction (without signature).
      *
@@ -840,6 +851,9 @@ export declare class PermissionsController extends BaseController {
      * 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.
      *
+     * This method supports gasless transactions via relayer when configured.
+     * If no relayer is available, it falls back to direct wallet transactions.
+     *
      * @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)
@@ -848,7 +862,7 @@ export declare class PermissionsController extends BaseController {
      * @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
+     * @throws {RelayerError} When gasless transaction submission fails
      *
      * @example
      * ```typescript
@@ -895,15 +909,16 @@ export declare class PermissionsController extends BaseController {
      */
     getGrantees(options?: GranteeQueryOptions): Promise<PaginatedGrantees>;
     /**
-     * Retrieves a specific grantee by their Ethereum address from the DataPortabilityGrantees contract.
+     * Retrieves a specific grantee by their Ethereum wallet address.
      *
+     * @remarks
      * Looks up a registered grantee (application) using their Ethereum address
-     * and returns their complete registration information including permissions.
+     * and returns their complete registration information including all associated 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
+     * Returns `null` if the address is not registered as a grantee or if an error occurs.
+     *
+     * @param granteeAddress - Ethereum wallet address of the grantee to query
+     * @returns Grantee information including ID, addresses, public key, and permission IDs, or `null` if not found
      *
      * @example
      * ```typescript
@@ -922,15 +937,16 @@ export declare class PermissionsController extends BaseController {
      */
     getGranteeByAddress(granteeAddress: Address): Promise<Grantee | null>;
     /**
-     * Retrieves a specific grantee by their unique ID from the DataPortabilityGrantees contract.
+     * Retrieves a specific grantee by their unique ID.
      *
+     * @remarks
      * Looks up a registered grantee (application) using their numeric ID assigned during
-     * registration and returns their complete information including permissions.
+     * registration and returns their complete information including all associated 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
+     * Returns `null` if the grantee is not found or if an error occurs during fetching.
+     *
+     * @param granteeId - Unique numeric ID of the grantee (1-indexed)
+     * @returns Grantee information including ID, addresses, public key, and permission IDs, or `null` if not found
      *
      * @example
      * ```typescript
@@ -938,7 +954,7 @@ export declare class PermissionsController extends BaseController {
      *
      * if (grantee) {
      *   console.log(`Grantee ID: ${grantee.id}`);
-     *   console.log(`Address: ${grantee.granteeAddress}`);
+     *   console.log(`Address: ${grantee.address}`);
      *   console.log(`Owner: ${grantee.owner}`);
      *   console.log(`Total permissions: ${grantee.permissionIds.length}`);
      * } else {
@@ -1041,6 +1057,24 @@ export declare class PermissionsController extends BaseController {
      * @returns Promise resolving to array of file IDs
      */
     getPermissionFileIds(permissionId: bigint): Promise<bigint[]>;
+    /**
+     * Retrieves detailed grant file data from IPFS or HTTP storage.
+     *
+     * @remarks
+     * This method automatically uses the SDK's configured downloadRelayer to bypass CORS restrictions.
+     * Use this instead of importing the standalone `retrieveGrantFile` utility.
+     *
+     * @param grantUrl - The grant file URL (from OnChainPermissionGrant.grantUrl)
+     * @returns Promise resolving to the complete grant file with operation details
+     * @throws {NetworkError} When all retrieval attempts fail
+     * @example
+     * ```typescript
+     * const grants = await vana.permissions.getUserPermissionGrantsOnChain();
+     * const grantFile = await vana.permissions.retrieveGrantFile(grants[0].grantUrl);
+     * console.log(`Operation: ${grantFile.operation}`);
+     * ```
+     */
+    retrieveGrantFile(grantUrl: string): Promise<GrantFile>;
     /**
      * Get all permissions for a specific file (alias for getFilePermissionIds)
      *
@@ -1049,17 +1083,39 @@ export declare class PermissionsController extends BaseController {
      */
     getFilePermissions(fileId: bigint): Promise<bigint[]>;
     /**
-     * Get grantee information by grantee ID
+     * Retrieves detailed grantee information including all associated permissions.
+     *
+     * @remarks
+     * Returns grantee metadata and associated permission IDs. Uses the newer
+     * paginated contract method internally for efficient permission fetching.
      *
-     * @param granteeId - Grantee ID to get info for
-     * @returns Promise resolving to grantee info
+     * @param granteeId - Unique grantee identifier as bigint
+     * @returns Grantee information containing owner address, grantee address, public key, and permission IDs
+     * @throws {BlockchainError} When grantee ID is not found or contract read fails
+     *
+     * @example
+     * ```typescript
+     * const granteeInfo = await vana.permissions.getGranteeInfo(BigInt(1));
+     * console.log(`Grantee ${granteeInfo.granteeAddress} has ${granteeInfo.permissionIds.length} permissions`);
+     * ```
      */
     getGranteeInfo(granteeId: bigint): Promise<GranteeInfo>;
     /**
-     * Get grantee information by grantee address
+     * Retrieves detailed grantee information by wallet address.
+     *
+     * @remarks
+     * Looks up the grantee ID from the provided address, then fetches complete
+     * grantee information including all associated permissions.
+     *
+     * @param granteeAddress - Ethereum wallet address of the grantee to query
+     * @returns Grantee information containing owner address, grantee address, public key, and permission IDs
+     * @throws {BlockchainError} When grantee address is not registered or contract read fails
      *
-     * @param granteeAddress - Grantee address to get info for
-     * @returns Promise resolving to grantee info
+     * @example
+     * ```typescript
+     * const granteeInfo = await vana.permissions.getGranteeInfoByAddress("0x742d35Cc6634c0532925a3b844Bc9e8e1ee3b2De");
+     * console.log(`Found grantee with ${granteeInfo.permissionIds.length} permissions`);
+     * ```
      */
     getGranteeInfoByAddress(granteeAddress: Address): Promise<GranteeInfo>;
     /**
@@ -1076,6 +1132,57 @@ export declare class PermissionsController extends BaseController {
      * @returns Promise resolving to array of permission IDs
      */
     getGranteePermissions(granteeId: bigint): Promise<bigint[]>;
+    /**
+     * Retrieves permission IDs for a specific grantee with flexible pagination.
+     *
+     * @remarks
+     * **Pagination Behavior:**
+     * Returns different types based on parameters:
+     * - Without offset/limit: Returns `bigint[]` of all permissions using batched multicall
+     * - With offset/limit: Returns paginated object with `permissionIds`, `totalCount`, and `hasMore`
+     *
+     * Uses gas-aware multicall for efficient batch fetching when retrieving all permissions.
+     *
+     * @param granteeId - Grantee ID to get permissions for
+     * @param options - Optional pagination parameters
+     * @param options.offset - Zero-based starting index for pagination. Defaults to 0 when fetching all permissions. Required for single-page requests.
+     * @param options.limit - Maximum number of permission IDs to return per page. Defaults to 100 when fetching all permissions. Required for single-page requests.
+     * @returns When called without options: Array of all permission IDs as `bigint[]`.
+     *   When called with offset and limit: Paginated result object containing `permissionIds` array,
+     *   `totalCount`, and `hasMore` boolean.
+     * @throws {BlockchainError} When contract read operation fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch all permissions (no pagination params)
+     * const allPermissions = await vana.permissions.getGranteePermissionsPaginated(BigInt(1));
+     * console.log(`Total permissions: ${allPermissions.length}`);
+     *
+     * // Fetch a specific page (with pagination params)
+     * const page = await vana.permissions.getGranteePermissionsPaginated(BigInt(1), {
+     *   offset: BigInt(0),
+     *   limit: BigInt(100)
+     * });
+     * console.log(`Fetched ${page.permissionIds.length} permissions`);
+     * console.log(`Total: ${page.totalCount}, Has more: ${page.hasMore}`);
+     *
+     * // Fetch next page
+     * if (page.hasMore) {
+     *   const nextPage = await vana.permissions.getGranteePermissionsPaginated(BigInt(1), {
+     *     offset: BigInt(100),
+     *     limit: BigInt(100)
+     *   });
+     * }
+     * ```
+     */
+    getGranteePermissionsPaginated(granteeId: bigint, options?: {
+        offset?: bigint;
+        limit?: bigint;
+    }): Promise<bigint[] | {
+        permissionIds: bigint[];
+        totalCount: bigint;
+        hasMore: boolean;
+    }>;
     /**
      * Get all server IDs for a user
      *
@@ -1183,7 +1290,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.
      *