Policy Commit Function

The commit function updates your Policy’s state after successful Ability execution. This is crucial for maintaining accurate tracking of limits, counters, and other stateful information.

If your Policy is stateful (tracks spending, counts executions, etc.), you MUST implement a commit function. Without it, your Policy will make incorrect decisions in future executions.

Function Parameters

The commit function receives two parameters:

params · object · required

Object adhering to the commitParamsSchema you have defined for your policy. This should include the specific parameters that your policy needs to update the state your policy depends on for its validation checks.

Notice that unlike the precheck and evaluate functions, the commit function does not receive the abilityParams and userParams arguments. If you need access to any of those variables, make sure to include them in the commitParamsSchema you have defined for your policy.

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 was executed

appId · number

The ID of the Vincent App the Vincent Ability was executed for

appVersion · number

The version of the Vincent App the Vincent Ability was 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 commit function

deny · function

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

Response Schemas

Allow Response

commitAllowResultSchema · ZodSchema · required

A Zod schema that defines the structure of successful commit results. Include details about what state was updated, such as new spending totals or execution counts.

Deny Response

commitDenyResultSchema · ZodSchema · required

A Zod schema that defines the structure of failed commit results. Include details about why the commit failed and what data was being updated.

Allow Schema

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

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

  commitAllowResultSchema: z.object({
    updatedDailySpending: z.number(),
    remainingDailyLimit: z.number(),
  }),
});

Deny Schema

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

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

  commitDenyResultSchema: z.object({
    reason: z.string(),
    vincentAppId: z.number(),
    spenderAddress: z.string(),
    spentAmount: z.number(),
    spentTokenAddress: z.string(),
  }),
});

If any unhandled error occurs during commit, the Vincent Ability SDK automatically returns a deny result with the error message.

Example Implementation

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

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

  commitParamsSchema: z.object({
    spentAmount: z.number(),
    tokenAddress: z.string(),
  }),

  commitAllowResultSchema: z.object({
    updatedDailySpending: z.number(),
    remainingDailyLimit: z.number(),
  }),

  commitDenyResultSchema: z.object({
    reason: z.string(),
    vincentAppId: z.number(),
    spenderAddress: z.string(),
    spentAmount: z.number(),
    spentTokenAddress: z.string(),
  }),

  commit: async (params, policyContext) => {
    const { spentAmount, tokenAddress } = params;

    try {
      const { updatedDailySpending, remainingDailyLimit } = await updateSpentAmount({
        vincentAppId: policyContext.appId,
        spenderAddress: policyContext.delegation.delegatorPkpInfo.ethAddress,
        spentAmount,
        spentTokenAddress: tokenAddress,
      });

      return policyContext.allow({
        updatedDailySpending,
        remainingDailyLimit,
      });
    } catch (error) {
      return policyContext.deny({
        reason: 'Failed to update spending limit',
        vincentAppId: policyContext.appId,
        spenderAddress: policyContext.delegation.delegatorPkpInfo.ethAddress,
        spentAmount,
        spentTokenAddress: tokenAddress,
      });
    }
  },
});

Best Practices

1. Always Implement for Stateful Policies - Any Policy that tracks limits, counts, or cumulative data needs a commit function
2. Handle Partial Failures - Design for scenarios where some updates succeed and others fail
3. Use Transactions - Ensure atomicity when updating multiple records or contracts
4. Log State Changes - Maintain audit trails of all policy state modifications

Next Steps

Publishing Policies

Publish your Policy for use in Vincent Apps

Policy Quick Start

Build your first Policy from scratch