Policy Precheck Function

The precheck function provides fast, local validation before committing to expensive Lit Action execution. It’s your Policy’s first line of defense against invalid requests.

The precheck function is executed locally by the Vincent Ability executor to provide a best-effort check that the policy shouldn’t fail when the policy’s evaluate function is called.

Function Parameters

The precheck function receives two parameters:

params · object · required

Object containing the ability and user parameters

Show properties

abilityParams · object

Parameters matching your abilityParamsSchema definition

userParams · object

Parameters matching your userParamsSchema definition

policyContext · object · required

Context object provided by the SDK with helpers and metadata

Show properties

abilityIpfsCid · string

The IPFS CID of the Vincent Ability that is being executed

appId · number

The ID of the Vincent App the Vincent Ability is being executed for

appVersion · number

The version of the Vincent App the Vincent Ability is being executed for

delegation · object

Information about the execution delegation

Show properties

delegateeAddress · string

The Ethereum address of the Vincent Ability executor

delegatorPkpInfo · object

User’s Vincent Wallet information

Show properties

tokenId · string

The token ID of the Vincent App User’s Vincent Wallet

ethAddress · string

The Ethereum address of the App User’s Vincent Wallet

publicKey · string

The public key of the App User’s Vincent Wallet

allow · function

Helper method for returning an allow result from your policy’s precheck function

deny · function

Helper method for returning a deny result from your policy’s precheck function

Response Schemas

Allow Response

precheckAllowResultSchema · ZodSchema · required

A Zod schema that defines the structure of successful precheck results. Include details about why the precheck passed, such as current spending limits and remaining quotas.

Deny Response

precheckDenyResultSchema · ZodSchema · required

A Zod schema that defines the structure of failed precheck results. Include details about why the precheck failed, such as exceeded limits or disallowed tokens.

Example Implementation

import { createVincentPolicy } from '@lit-protocol/vincent-ability-sdk';
import { z } from 'zod';

const vincentPolicy = createVincentPolicy({
  // ... other policy definitions

  precheck: async ({ abilityParams, userParams }, policyContext) => {
    const { amount, tokenAddress } = abilityParams;
    const { dailySpendingLimit, allowedTokens } = userParams;

    const isTokenAllowed = allowedTokens.includes(tokenAddress);
    const { isSpendingLimitExceeded, currentDailySpending } = await checkSpendingLimit(
      tokenAddress,
      amount,
      dailySpendingLimit,
    );

    if (!isTokenAllowed) {
      return policyContext.deny({
        reason: 'Token not allowed',
        maxDailySpendingLimit: dailySpendingLimit,
        currentDailySpending,
        allowedTokens: allowedTokens,
      });
    }

    if (isSpendingLimitExceeded) {
      return policyContext.deny({
        reason: 'Spending limit exceeded',
        maxDailySpendingLimit: dailySpendingLimit,
        currentDailySpending,
        allowedTokens: allowedTokens,
      });
    }

    return policyContext.allow({
      maxDailySpendingLimit: dailySpendingLimit,
      currentDailySpending,
      allowedTokens: allowedTokens,
    });
  },
});

Best Practices

1. Validate Early - Check user parameters first before expensive operations
2. Return Helpful Context - Include current state information in responses
3. Handle Errors Gracefully - Provide clear error messages for debugging
4. Keep It Fast - Avoid expensive blockchain calls in precheck

Next Steps

Evaluate Function

Implement final validation with blockchain access

Commit Function

Update state after successful execution