Vincent Stage Settlement Ability

A Vincent/Lit Protocol ability for staging settlements with payment legs for escrow contracts.

Overview

This package provides a Vincent ability that allows third-party agents to stage settlements with multiple payment legs for escrow contracts. The staged settlements can later be executed by any authorized party within the specified validity window.

Features

• Stage Settlements: Create staged settlements with multiple payment legs
• Payment Legs: Support for native ETH and ERC-20 token payments
• Validity Window: Configurable validity period (1 second to 30 days)
• Validation: Comprehensive parameter validation
• Policy Support: Integrates with Vincent policies for access control

Installation

npm install @lit-protocol/vincent-example-ability-stage-settlement

Usage

Basic Usage

import { vincentAbility } from '@lit-protocol/vincent-example-ability-stage-settlement';

// The ability is ready to be used with Vincent

Ability Parameters

The ability accepts the following parameters:

interface AbilityParams {
  escrow: string;           // Escrow contract address
  paymentLegs: PaymentLeg[]; // Array of payment legs
  validForSeconds: number;   // Validity period in seconds
  rpcUrl?: string;          // Optional RPC URL
}

interface PaymentLeg {
  to: string;              // Recipient address
  amount: string;         // Amount (in ETH for native, or token units)
  token?: string;          // Token address (optional, defaults to native ETH)
}

Example Payment Legs

const paymentLegs = [
  {
    to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    amount: "1.5", // 1.5 ETH
    // token is optional for native ETH
  },
  {
    to: "0x8ba1f109551bD432803012645Hac136c",
    amount: "1000", // 1000 tokens
    token: "0xA0b86a33E6441b8C4C8C0C8C0C8C0C8C0C8C0C8C" // ERC-20 token address
  }
];

Contract Integration

This ability calls the stageSettlement function on your escrow contract:

function stageSettlement(
    address escrow,
    PaymentLeg[] calldata paymentLegs,
    uint256 validForSeconds
) external;

PaymentLeg Structure

struct PaymentLeg {
    address to;      // Recipient address
    uint256 amount; // Amount in wei
    address token;   // Token address (zero address for native ETH)
}

Vincent Integration

This ability integrates with the Vincent ecosystem:

• Policies: Supports Vincent policies for access control
• Delegation: Works with PKP (Programmable Key Pairs) delegation
• Validation: Comprehensive pre-execution validation
• Events: Emits SettlementStaged events

Development

Building

npm run build

Testing

npm test

License

MIT

Support

For issues and questions, please open an issue on the GitHub repository.