@maxosllc/vincent-ability-erc7540-admin-actions

v0.0.7

Published

4 months ago

A Vincent ability for ERC-7540 vault administrative actions created with @lit-protocol/vincent-scaffold-sdk

0High
0Medium
0Low

celapablo

maxiperezc

erc7540-admin-actions

A Vincent tool for secure ERC-7540 vault administrative actions with integrated policy-based governance, balance validation, and multi-network support.

Overview

The erc7540-admin-actions tool enables secure ERC-7540 vault administrative operations through the Vincent Framework, providing:

Secure ERC-7540 vault administration using PKP (Programmable Key Pair) wallets
Multi-action support for deposit fulfillment, redemption, asset management, and vault queries
Policy-based governance with integrated rate limiting
Comprehensive balance validation for both native gas fees and vault operations
Multi-network support with configurable RPC endpoints and chain IDs
Real-time transaction execution with detailed logging and error handling

Key Features

🏛️ ERC-7540 Vault Support

Support for all standard ERC-7540 vault administrative actions
Automatic asset decimals detection and amount parsing
Vault state validation before operation execution
Read-only operations for vault data retrieval

🔐 PKP-Based Security

Uses Lit Protocol's PKP wallets for secure transaction signing
Delegated execution with proper permission validation
No private key exposure during transaction execution

🚦 Policy Integration

Integrated with send-counter-limit policy for rate limiting
Configurable transaction limits per time window
Automatic policy enforcement during execution

🌐 Multi-Network Support

Configurable RPC endpoints for different networks
Chain ID specification for network compatibility
Default support for Base network
Support for any EVM-compatible network

✅ Comprehensive Validation

Ethereum address format validation for controller and vault addresses
Amount validation with reasonable limits (max 1,000,000 tokens)
Action type validation for supported ERC-7540 operations
Native balance validation for gas fees
Vault state validation before operations

Parameters

Required Parameters

| Parameter | Type | Validation | Description | |-----------|------|------------|-------------| | controller | string | Ethereum address format (0x...) | Controller address for deposit/redeem operations | | amount | string | Positive number, max 1,000,000 | Operation amount in asset units (not required for getValues) | | action | string | One of supported actions | ERC-7540 action to perform | | vault | string | Ethereum address format (0x...) | ERC-7540 vault contract address |

Optional Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | rpcUrl | string | "https://yellowstone-rpc.litprotocol.com/" | Custom RPC endpoint | | chainId | number | 8453 (Base) | Network chain ID |

Supported Actions

Administrative Actions

| Action | Description | Parameters Required | Transaction Type | |--------|-------------|-------------------|------------------| | fulfillDeposit | Fulfill pending deposit requests | controller, amount | Write | | fulfillRedeem | Fulfill pending redemption requests | controller, amount | Write | | takeAssets | Take assets from vault for investment | amount | Write | | returnAssets | Return assets to vault from investment | amount | Write | | updateInvested | Update invested amount tracking | amount | Write | | getValues | Get vault state information | none | Read-only |

Usage Examples

Fulfill Deposit Request

const fulfillDepositParams = {
  controller: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: "1000.0",
  action: "fulfillDeposit",
  vault: "0x1234567890123456789012345678901234567890",
  rpcUrl: "https://base.llamarpc.com",
  chainId: 8453
};

Take Assets for Investment

const takeAssetsParams = {
  controller: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6", // Required but not used for this action
  amount: "50000.0",
  action: "takeAssets",
  vault: "0x1234567890123456789012345678901234567890",
  rpcUrl: "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
  chainId: 1 // Ethereum mainnet
};

Get Vault Information (Read-only)

const getValuesParams = {
  controller: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6", // Required but not used for this action
  amount: "0", // Not used for read-only operations
  action: "getValues",
  vault: "0x1234567890123456789012345678901234567890"
};

Fulfill Redemption Request

const fulfillRedeemParams = {
  controller: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: "500.0",
  action: "fulfillRedeem",
  vault: "0x1234567890123456789012345678901234567890",
  chainId: 137 // Polygon
};

Execution Flow

1. Precheck Phase

Validates controller address format
Validates vault contract address format
Validates action type (must be one of supported actions)
Validates operation amount (positive, reasonable limits) - skipped for getValues
Validates RPC URL format (if provided)
Validates chain ID (if provided)
Returns validation status

2. Execute Phase

For Read-only Operations (getValues)

Connects to specified RPC endpoint
Retrieves vault contract information
Queries vault state (pending deposits, redeems, asset balance)
Returns vault data without transaction

For Write Operations

Connects to specified RPC endpoint
Retrieves PKP public key from delegation context
Converts PKP public key to Ethereum address
Detects asset token and decimals from vault
Parses operation amount using asset decimals
Validates native balance for gas fees
Executes ERC-7540 vault operation using laUtils.transaction.handler.contractCall
Triggers policy commit phase for rate limiting
Returns transaction hash and metadata

Policy Integration

The tool automatically integrates with the send-counter-limit policy:

Precheck: Validates tool parameters
Execute: Performs the actual ERC-7540 vault operation
Policy Commit: Records the transaction for rate limiting

Policy Configuration

// Example: Allow 2 vault operations per 10 seconds
const policyConfig = {
  maxSends: 2n,
  timeWindowSeconds: 10n
};

Error Handling

The tool provides detailed error messages for various failure scenarios:

Address Validation Errors

"Invalid controller address format"
"Invalid vault address format"

Action Validation Errors

"Invalid action. Must be one of: fulfillDeposit, fulfillRedeem, takeAssets, returnAssets, updateInvested, getValues"

Amount Validation Errors

"Invalid amount format or amount must be greater than 0"
"Amount too large (maximum 1,000,000 tokens per transaction)"

Balance Validation Errors

"Insufficient native balance for gas. Need 0.0001 ETH, but only have 0.00005 ETH"

Network Errors

"Invalid RPC URL format"
"Invalid chain ID - must be a positive integer"
"PKP public key not available from delegation context"

Vault Operation Errors

"Failed to read vault data: [specific error]"
"Unknown error occurred"

Response Format

Success Response (Write Operations)

{
  txHash: "0x...",
  controller: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: "1000.0",
  action: "fulfillDeposit",
  vault: "0x1234567890123456789012345678901234567890",
  timestamp: 1703123456789
}

Success Response (Read Operations)

{
  controller: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  amount: "0",
  action: "getValues",
  vault: "0x1234567890123456789012345678901234567890",
  timestamp: 1703123456789,
  data: {
    pendingDeposits: "5000.0",
    pendingRedeems: "2500.0",
    vaultAssetBalance: "100000.0",
    pendingRedeemAssets: "2500.0"
  }
}

Error Response

{
  error: "Detailed error message"
}

Development

Building

npm install
npm run build

Testing

This tool is tested through the Vincent E2E testing framework:

npm run vincent:e2e:erc7540 - Tests ERC-7540 vault operations with rate limiting

Architecture

The tool follows the Vincent two-phase execution model:

Precheck - Parameter validation outside Lit Actions
Execute - Vault operation execution within Lit Actions

Security Considerations

Amount limits: Maximum 1,000,000 tokens per transaction prevents large accidental operations
Address validation: Strict Ethereum address format validation for controller and vault addresses
Action validation: Only allows predefined ERC-7540 administrative actions
Balance validation: Comprehensive checks for native gas fees
PKP security: Uses Lit Protocol's secure PKP system
Policy enforcement: Integrated rate limiting prevents abuse
Network validation: RPC URL and chain ID validation prevents malicious endpoints

Network Support

Default Network

Base Mainnet via Yellowstone RPC
Chain ID: 8453
RPC URL: https://yellowstone-rpc.litprotocol.com/

Supported Networks

Base Mainnet (Chain ID: 8453)
Ethereum Mainnet (Chain ID: 1)
Polygon (Chain ID: 137)
Arbitrum (Chain ID: 42161)
Any EVM-compatible network

ERC-7540 Standard

ERC-7540 is an extension of ERC-4626 that adds asynchronous deposit and redemption capabilities to vaults. This tool provides administrative functions for:

Asynchronous Operations: Managing pending deposits and redemptions
Asset Management: Taking assets for investment and returning them
Investment Tracking: Updating invested amounts for proper accounting
Vault Monitoring: Querying vault state and pending operations

Key Concepts

Pending Deposits: User deposit requests waiting to be fulfilled
Pending Redemptions: User redemption requests waiting to be fulfilled
Asset Management: Moving assets between vault and investment strategies
Controller: Address authorized to fulfill user requests

Dependencies

@lit-protocol/vincent-scaffold-sdk - Core Vincent framework
@lit-protocol/vincent-tool-sdk - Tool development framework
ethers.js - Blockchain interaction
zod - Schema validation and type safety

Use Cases

Vault Operators

Fulfill user deposit and redemption requests
Manage vault liquidity by taking/returning assets
Monitor vault state and pending operations
Update investment tracking for compliance

DeFi Protocols

Automate vault operations based on market conditions
Implement sophisticated investment strategies
Maintain proper liquidity ratios
Ensure timely fulfillment of user requests

Asset Managers

Execute investment strategies with vault assets
Track invested amounts for reporting
Manage multiple vaults across different networks
Implement risk management through rate limiting