Vana SDK - v0.1.0
    Preparing search index...

    Class PermissionsController

    Manages gasless data access permissions and trusted server registry operations.

    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.

    All permission operations support both gasless transactions via relayers and direct blockchain transactions. Grant files containing detailed permission parameters are stored on IPFS while permission references are recorded on the blockchain.

    // Grant permission for an app to access your data
    const txHash = await vana.permissions.grant({
      grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
      operation: "llm_inference",
      parameters: { model: "gpt-4", maxTokens: 1000 },
    });

    // Trust a server for data processing
    await vana.permissions.trustServer({
      serverId: "0x123...",
      serverUrl: "https://trusted-server.example.com",
    });

    // Query current permissions
    const permissions = await vana.permissions.getUserPermissions();

    [URL_PLACEHOLDER] | Vana Permissions System for conceptual overview

    Index

    Methods

    grant prepareGrant createAndSign submitSignedGrant submitSignedTrustServer submitSignedRevoke submitSignedUntrustServer revoke revokeWithSignature getUserPermissionGrantsOnChain getFilePermissionIds getPermissionFileIds isActivePermission getPermissionInfo trustServer trustServerWithSignature untrustServer untrustServerWithSignature getTrustedServers getServerInfo getTrustedServersCount getTrustedServersPaginated getTrustedServersWithInfo getServerInfoBatch checkServerTrustStatus

    Methods

    • Grants permission for an application to access user data with gasless transactions.

      Parameters

      Returns Promise<`0x${string}`>

      A Promise that resolves to the transaction hash when successfully submitted

      This method combines signature creation and gasless submission for a complete end-to-end permission grant flow. It creates the grant file, stores it on IPFS, generates an EIP-712 signature, and submits via relayer. The grant file contains detailed parameters while the blockchain stores only a reference to enable efficient permission queries.

      When gasless transaction submission fails

      When user rejects the signature request

      When grant data cannot be serialized

      When permission grant preparation fails

      const txHash = await vana.permissions.grant({
        grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
        operation: "llm_inference",
        parameters: {
          model: "gpt-4",
          maxTokens: 1000,
          temperature: 0.7,
        },
      });

      console.log(`Permission granted: ${txHash}`);

    • Prepares a permission grant with preview before signing.

      Parameters

      Returns Promise<{ preview: GrantFile; confirm: () => Promise<`0x${string}`> }>

      A promise resolving to a preview object and confirm function

      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.

      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();

    • Creates typed data and signature for a permission grant without submitting.

      Parameters

      Returns Promise<{ typedData: PermissionGrantTypedData; signature: `0x${string}` }>

      A promise resolving to the typed data structure and signature for gasless submission

      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.

      When the user rejects the signature request

      When grant data cannot be properly formatted

      When permission grant preparation fails

      When storage operations fail

      const { typedData, signature } = await vana.permissions.createAndSign({
        grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
        operation: "data_analysis",
        parameters: { analysisType: "sentiment" },
      });

      const transactionHash = await vana.permissions.submitSignedGrant(typedData, signature);

    • Submits an already-signed permission grant to the blockchain.

      Parameters

      • typedData: PermissionGrantTypedData

        The EIP-712 typed data structure for the permission grant

      • signature: `0x${string}`

        The user's signature as a hex string

      Returns Promise<`0x${string}`>

      A Promise that resolves to the transaction hash

      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.

      When gasless transaction submission fails

      When permission submission fails

      When network communication fails

      const txHash = await vana.permissions.submitSignedGrant(
        typedData,
        "0x1234..."
      );

    • Submits an already-signed trust server transaction to the blockchain. This method extracts the trust server input from typed data and submits it directly.

      Parameters

      • typedData: TrustServerTypedData

        The EIP-712 typed data for TrustServer

      • signature: `0x${string}`

        The user's signature

      Returns Promise<`0x${string}`>

      Promise resolving to the transaction hash

    • Submits an already-signed permission revoke transaction to the blockchain. This method handles the revocation of previously granted permissions.

      Parameters

      • typedData: GenericTypedData

        The EIP-712 typed data for PermissionRevoke

      • signature: `0x${string}`

        The user's signature

      Returns Promise<`0x${string}`>

      Promise resolving to the transaction hash

    • Submits an already-signed untrust server transaction to the blockchain. This method handles the removal of trusted servers.

      Parameters

      • typedData: GenericTypedData

        The EIP-712 typed data for UntrustServer

      • signature: `0x${string}`

        The user's signature

      Returns Promise<`0x${string}`>

      Promise resolving to the transaction hash

    • Revokes a previously granted permission.

      Parameters

      Returns Promise<`0x${string}`>

      Promise resolving to transaction hash

      // Revoke a permission by its ID
      const txHash = await vana.permissions.revoke({
        permissionId: 123n
      });
      console.log('Permission revoked in transaction:', txHash);

      // Wait for confirmation if needed
      const receipt = await vana.core.waitForTransaction(txHash);
      console.log('Revocation confirmed in block:', receipt.blockNumber);

    • Gets on-chain permission grant data without expensive off-chain resolution.

      Parameters

      Returns Promise<OnChainPermissionGrant[]>

      A Promise that resolves to an array of OnChainPermissionGrant objects

      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.

      When subgraph query fails

      When network requests fail

      // 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);

    • Gets all permission IDs for a specific file.

      Parameters

      • fileId: bigint

        The file ID to query permissions for

      Returns Promise<bigint[]>

      Promise resolving to array of permission IDs

    • Gets all file IDs associated with a permission.

      Parameters

      • permissionId: bigint

        The permission ID to query files for

      Returns Promise<bigint[]>

      Promise resolving to array of file IDs

    • Checks if a permission is active.

      Parameters

      • permissionId: bigint

        The permission ID to check

      Returns Promise<boolean>

      Promise resolving to boolean indicating if permission is active

    • Trusts a server for data processing.

      Parameters

      Returns Promise<`0x${string}`>

      Promise resolving to transaction hash

      // Trust a server by providing its ID and URL
      const txHash = await vana.permissions.trustServer({
        serverId: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
        serverUrl: 'https://myserver.example.com'
      });
      console.log('Server trusted in transaction:', txHash);

      // Verify the server was added to trusted list
      const trustedServers = await vana.permissions.getTrustedServers();
      console.log('Trusted servers:', trustedServers.length);

    • Gets all servers trusted by a user.

      Parameters

      • OptionaluserAddress: `0x${string}`

        Optional user address (defaults to current user)

      Returns Promise<`0x${string}`[]>

      Promise resolving to array of trusted server addresses

    • Gets the total count of trusted servers for a user.

      Parameters

      • OptionaluserAddress: `0x${string}`

        Optional user address (defaults to current user)

      Returns Promise<number>

      Promise resolving to the number of trusted servers

    • Checks whether a specific server is trusted by a user.

      Parameters

      • serverId: `0x${string}`

        Server ID to check

      • OptionaluserAddress: `0x${string}`

        Optional user address (defaults to current user)

      Returns Promise<ServerTrustStatus>

      Promise resolving to server trust status

    Settings

    Member Visibility

    On This Page

    Methods