Quick Start

Create your first Vincent Policy in under 20 minutes using the Vincent Starter Kit.

Ability Starter Kit

Clone the Vincent Starter Kit repository for quick setup

Prerequisites

Node.js

Version 20.19.4 or higher

Corepack

Version 20.19.4 or higher

Pinata Account

For IPFS storage of your Policy code

Setup

1. Clone the Starter Kit

   git clone [e-mail]:LIT-Protocol/vincent-ability-starter-kit.git
   cd vincent-ability-starter-kit
   
2. Ensure Corepack is Updated

   # Verify your corepack version (should be > 0.31.0)
   corepack -v
   
   # If needed, update corepack to the latest version
   npm install -g corepack@latest
   
   # Enable Corepack globally
   corepack enable
   
3. Run Bootstrap

   corepack enable pnpm
   pnpm bootstrap
   

   The bootstrap will prompt you for:

   • Pinata JWT: Get from Pinata after creating an account
   • Test wallet private key: Fund with test tokens from the Lit Faucet
4. Verify Setup

   pnpm test-e2e
   

   If successful, you’ll see all tests passing and your environment is ready.

Create Your Policy

1. Copy the Template

   # Replace 'my-policy' with your desired package name
   mkdir -p packages/my-policy
   rsync -a --exclude='node_modules/' --exclude='dist/' \
     packages/policy-counter/ packages/my-policy/
   
2. Update Package Configuration

   1. Edit packages/my-policy/package.json:

   {
     "name": "@your-org/my-policy",
     "version": "0.0.1",
     "description": "Your policy description here"
   }
   

   2. Edit packages/my-policy/project.json:

   Replace all occurrences of policy-counter with my-policy:

   • "name": "my-policy"
   • "sourceRoot": "packages/my-policy/src"
   • "cwd": "packages/my-policy" (all instances)
   • "input": "packages/my-policy/src/generated"
   • "outputPath": "packages/my-policy/dist"
   • "main": "packages/my-policy/src/index.ts"
   • "tsConfig": "packages/my-policy/tsconfig.lib.json"
   • All asset paths

   3. Edit packages/my-policy/jest.config.js:

   module.exports = {
     displayName: '@your-org/my-policy', // Update this
     // ... rest of config
   };
   

   4. Update nx.json in repository root:

   Add your package to the release projects:

   {
     "release": {
       "projects": ["ability-native-send", "policy-counter", "test-e2e", "my-policy"]
     }
   }
   
3. Define Your Policy Logic

   Edit packages/my-policy/src/lib/vincent-policy.ts:

   export const vincentPolicy = createVincentPolicy({
     packageName: '@your-org/my-policy',
   
     // There are other configurations here, not covered in the Quick Start.
     // Please read the other guides for more details.
   
     // Schemas for parameters and results
     abilityParamsSchema,
     userParamsSchema,
     commitParamsSchema,
   
     // Local validation - runs before execution
     precheck: async ({ abilityParams, userParams }, { allow, deny }) => {
       // Validate parameters and current state
       if (/* validation passes */) {
         return allow({ /* validation data */ });
       }
       return deny({ reason: 'Validation failed' });
     },
   
     // Evaluation - runs in Lit Action environment
     evaluate: async ({ abilityParams, userParams }, { allow, deny }) => {
       // Check policy state and determine if execution allowed
       if (/* policy allows execution */) {
         return allow({ /* evaluation data */ });
       }
       return deny({ reason: 'Policy denied execution' });
     },
   
     // State update - runs after successful execution
     commit: async (commitParams, { allow, deny }) => {
       // Update policy state
       return allow({ /* commit success data */ });
     },
   });
   
4. Configure User Interface

   Edit packages/my-policy/src/inputUiSchema.json to define how users configure your Policy:

   {
     "jsonSchema": {
       "type": "object",
       "properties": {
         "maxAmount": {
           "type": "number",
           "title": "Maximum Amount",
           "description": "Maximum amount allowed per transaction"
         }
       }
     },
     "uiSchema": {
       "maxAmount": {
         "ui:placeholder": "Enter maximum amount"
       }
     }
   }
   
5. Build and Test

   pnpm install
   pnpm nx build my-policy
   pnpm test-e2e
   
6. Deploy to IPFS

   pnpm nx action:deploy my-policy
   

   Your Policy is now deployed and ready to be used by Vincent Abilities!

7. Publish Your Policy

   When you’re prepared, you can publish the Policy to npm. This will make it publishable in the Vincent Registry.

   cd packages/my-policy
   pnpm publish
   
8. Register in Vincent Registry

   See the Publishing Guide for details on registering your Policy in the Vincent Registry.

Quick Commands

build · command

pnpm nx build my-policy - Build your Policy package

test · command

pnpm test-e2e - Run end-to-end tests with the Vincent system

deploy · command

pnpm nx action:deploy my-policy - Deploy to IPFS via Pinata

clean · command

pnpm clean - Remove build artifacts

What’s Next?

Policy Structure

Learn how Policies work under the hood

Example Policies

Study the included examples

Integration Guide

Connect Policies with Abilities