Quick Start

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

Ability Starter Kit

Clone the Vincent Ability 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 Ability 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 Ability

1. Copy the Template

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

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

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

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

   Replace all occurrences of ability-native-send with my-ability:

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

   3. Edit packages/my-ability/tsconfig.lib.json:

   Remove the policy-counter reference if not using it:

   {
     "references": []  // Remove policy-counter reference
   }
   

   4. Update nx.json in repository root:

   Add your package to the release projects:

   {
     "release": {
       "projects": ["ability-native-send", "policy-counter", "test-e2e", "my-ability"]
     }
   }
   
3. Update the Main Index File

   Edit packages/my-ability/src/index.ts:

   Update the comment to reflect your ability name.

4. Update Jest Configuration

   Edit packages/my-ability/jest.config.js:

   module.exports = {
     displayName: '@your-org/my-ability', // Update this
     // ... rest of config
   };
   
5. Define Your Ability Logic

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

   export const vincentAbility = createVincentAbility({
     packageName: '@your-org/my-ability',
     abilityDescription: 'What your ability does',
   
     // There are other configurations here, not covered in the Quick Start.
     // Please read the other guides for more details.
   
     // Validation - runs locally
     precheck: async ({ abilityParams }, { fail, succeed }) => {
       // Validate inputs, check balances, etc.
       return succeed({ /* validation passed */ });
     },
   
     // Execution - runs in Lit Action environment
     execute: async ({ abilityParams }, { fail, succeed }) => {
       // Your ability's main logic
       // Has access to sign with user's PKP wallet
       return succeed({ /* result data */ });
     }
   });
   
6. Build and Test

   pnpm install
   pnpm nx build my-ability
   pnpm test-e2e
   
7. Deploy to IPFS

   pnpm nx action:deploy my-ability
   

   Your Ability is now deployed and ready to be used by Vincent Apps!

8. Publish Your Ability

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

   cd packages/my-ability
   pnpm publish
   
9. Register in Vincent Registry

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

Quick Commands

build · command

pnpm nx build my-ability - Build your Ability package

test · command

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

deploy · command

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

clean · command

pnpm clean - Remove build artifacts

What’s Next?

Ability Structure

Learn how Abilities work under the hood

Example Abilities

Study the included examples

Integration Guide

Connect Abilites with Policies