@lit-protocol/vincent-ability-erc20-transfer 0.0.10-mma

package/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to Vincent Ability ERC20 Transfer
+
+This document provides guidelines for contributing to the Vincent Ability ERC20 Transfer project.
+
+## Overview
+
+The Vincent Ability ERC20 Transfer is an ability to send ERC20 transfer transactions from a Vincent app on behalf of the delegator. It's part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK.
+
+## Setup
+
+1. Follow the global setup instructions in the repository root [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+## Development Workflow
+
+### Testing
+
+Run tests:
+
+```bash
+nx test ability-erc20-transfer
+```
+
+### Building the Lit Action
+
+Build the ability:
+
+```bash
+nx action:build ability-erc20-transfer
+```
+
+### Deploying the Lit Action to IPFS
+
+Building will be done automatically. Deploy the ability:
+
+```bash
+nx action:deploy ability-erc20-transfer
+```
+
+## Ability Development Guidelines
+
+1. Use the Vincent Ability SDK to create abilities
+2. Define clear schemas for ability parameters
+3. Implement the ability lifecycle methods (precheck, execute)
+4. Handle errors gracefully
+5. Write comprehensive tests for all functionality
+6. Document the ability's purpose and usage
+
+## Integration with Policies
+
+This ability can be integrated with various Vincent Policies to enforce constraints. When developing or modifying the ability, consider how it will be used with policies such as:
+
+- Vincent Policy Send Counter
+
+## Testing
+
+Write unit tests for all functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document the ability's purpose and usage
+- Update README.md when adding new features
+- Document the ability's parameters and behavior
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new functionality
+4. Link any related issues in your pull request description
+5. Request a review from a maintainer
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [Vincent Ability SDK Documentation](../../libs/ability-sdk/README.md)
+- [ERC20 Standard](https://eips.ethereum.org/EIPS/eip-20)

package/README.md

@@ -0,0 +1,271 @@
+# Vincent Ability ERC20 Transfer
+
+A Vincent Ability for secure ERC-20 token transfers with integrated policy-based governance, balance
+validation, and multi-network support.
+
+## Overview
+
+The `erc20-transfer` ability enables secure ERC-20 token transfers through the Vincent Framework,
+providing:
+
+- Secure transfers using PKP (Programmable Key Pair) wallets
+- Automatic token decimals detection
+- Policy-based governance with integrated rate limiting
+- Balance validation for both native gas fees and token amounts
+- Multi-network support (precheck uses rpcUrl; execute resolves RPC via the `chain` parameter)
+- Real-time transaction execution with detailed logging and error handling
+
+## Key Features
+
+### 🪙 ERC-20 Token Support
+
+- Works with any ERC-20 token
+- Automatically fetches token decimals from the contract
+- Token balance validation before transfer execution
+- Standard ERC-20 transfer function integration
+
+### 🔐 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
+
+- Precheck uses the provided RPC URL (rpcUrl)
+- Execute resolves RPC via the `chain` parameter using Lit Actions
+- Works with any EVM-compatible network
+
+### ✅ Comprehensive Validation
+
+- Ethereum address format validation for recipient and token contract
+- Amount validation (must be a positive decimal string)
+- RPC URL required for precheck
+- Native balance check for gas fees
+- Token balance check before transfer
+
+## Parameters
+
+All functions accept the following parameters:
+
+| Parameter                   | Type      | Description                                                                   |
+| --------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `rpcUrl`                    | `string`  | RPC URL used during precheck validations                                      |
+| `chain`                     | `string`  | Chain name used during execute (e.g., 'base', 'ethereum')                     |
+| `to`                        | `string`  | Recipient address (0x...)                                                     |
+| `tokenAddress`              | `string`  | ERC-20 token contract address (0x...)                                         |
+| `amount`                    | `string`  | Amount in human-readable string (e.g., "1.23")                                |
+| `alchemyGasSponsor`         | `boolean` | Whether to use Alchemy's gas sponsorship (EIP-7702)                           |
+| `alchemyGasSponsorApiKey`   | `string`  | Alchemy API key for gas sponsorship (required if alchemyGasSponsor is true)   |
+| `alchemyGasSponsorPolicyId` | `string`  | Alchemy gas policy ID for sponsorship (required if alchemyGasSponsor is true) |
+
+## Usage Examples
+
+### USDC Transfer on Base Network
+
+```typescript
+const transferParams = {
+  rpcUrl: 'https://base.llamarpc.com',
+  chain: 'base',
+  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // Base USDC
+  amount: '10.50',
+};
+```
+
+### Custom Token Transfer
+
+```typescript
+const transferParams = {
+  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_PROJECT_ID',
+  chain: 'ethereum',
+  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  tokenAddress: '0xYourTokenContractAddress',
+  amount: '100.0',
+};
+```
+
+### Small Amount Transfer (for testing)
+
+```typescript
+const transferParams = {
+  rpcUrl: 'https://base.llamarpc.com',
+  chain: 'base',
+  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  amount: '0.000001',
+};
+```
+
+## Execution Flow
+
+### 1. Precheck Phase
+
+- Validates recipient address format
+- Validates token contract address format
+- Validates transfer amount (positive, reasonable limits)
+- Validates token decimals (0-18 range)
+- Validates RPC URL format (if provided)
+- Validates chain ID (if provided)
+- Returns validation status
+
+### 2. Execute Phase
+
+- Connects to specified RPC endpoint
+- Retrieves PKP public key from delegation context
+- Converts PKP public key to Ethereum address
+- Parses token amount using specified decimals
+- Validates native balance for gas fees
+- Validates token balance for transfer amount
+- Executes ERC-20 transfer using `laUtils.transaction.handler.contractCall`
+- Triggers policy commit phase for rate limiting
+- Returns transaction hash and metadata
+
+## Policy Integration
+
+The ability automatically integrates with the `send-counter-limit` policy:
+
+- **Precheck**: Validates ability parameters
+- **Execute**: Performs the actual ERC-20 transfer
+- **Policy Commit**: Records the transaction for rate limiting
+
+### Policy Configuration
+
+```typescript
+// Example: Allow 2 ERC-20 transfers per 10 seconds
+const policyConfig = {
+  maxSends: 2n,
+  timeWindowSeconds: 10n,
+};
+```
+
+## Error Handling
+
+The ability provides detailed error messages for various failure scenarios:
+
+### Address Validation Errors
+
+```
+"Invalid recipient address format"
+"Invalid token contract address format"
+```
+
+### 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"
+"Insufficient token balance. Need 100.0 tokens, but only have 50.0 tokens"
+```
+
+### Network Errors
+
+```
+"Invalid RPC URL format"
+"Unable to obtain blockchain provider for transfer operations"
+"PKP public key not available from delegation context"
+```
+
+### Transaction Errors
+
+```
+"Unknown error occurred"
+```
+
+## Response Format
+
+### Success Response
+
+```typescript
+{
+  txHash: "0x...",
+    to
+:
+  "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
+    amount
+:
+  "10.50",
+    tokenAddress
+:
+  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    timestamp
+:
+  1703123456789
+}
+```
+
+### Error Response
+
+```typescript
+{
+  error: 'Detailed error message';
+}
+```
+
+## Development
+
+### Building
+
+```bash
+npm install
+npm run build
+```
+
+### Testing
+
+This ability is tested through the Vincent E2E testing framework:
+
+- `npm run vincent:e2e:erc20` - Tests ERC-20 transfers with rate limiting
+
+### Architecture
+
+The ability follows the Vincent two-phase execution model:
+
+1. **Precheck** - Parameter validation outside Lit Actions
+2. **Execute** - Transaction execution within Lit Actions
+
+## Security Considerations
+
+- **Balance validation**: Comprehensive checks for both native gas fees and token balances
+- **PKP security**: Uses Lit Protocol's secure PKP system
+- **Policy enforcement**: Integrated rate limiting prevents abuse
+- **Network validation**: RPC URL and chain validation prevents malicious endpoints
+
+## Supported Networks
+
+- **Base Mainnet** (Chain ID: 8453)
+- **Ethereum Mainnet** (Chain ID: 1)
+- **Polygon** (Chain ID: 137)
+- **Arbitrum** (Chain ID: 42161)
+- **Any EVM-compatible network supported by Lit**
+
+### Popular Token Addresses
+
+#### Base Network
+
+- **USDC**: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+- **WETH**: `0x4200000000000000000000000000000000000006`
+
+#### Ethereum Mainnet
+
+- **USDC**: `0xA0b86a33E6441b8C4C8C8C8C8C8C8C8C8C8C8C8`
+- **USDT**: `0xdAC17F958D2ee523a2206206994597C13D831ec7`
+
+## Dependencies
+
+- `@lit-protocol/vincent-scaffold-sdk` - Core Vincent framework
+- `@lit-protocol/vincent-ability-sdk` - Ability development framework
+- `ethers.js` - Blockchain interaction
+- `zod` - Schema validation and type safety

package/dist/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to Vincent Ability ERC20 Transfer
+
+This document provides guidelines for contributing to the Vincent Ability ERC20 Transfer project.
+
+## Overview
+
+The Vincent Ability ERC20 Transfer is an ability to send ERC20 transfer transactions from a Vincent app on behalf of the delegator. It's part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK.
+
+## Setup
+
+1. Follow the global setup instructions in the repository root [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+## Development Workflow
+
+### Testing
+
+Run tests:
+
+```bash
+nx test ability-erc20-transfer
+```
+
+### Building the Lit Action
+
+Build the ability:
+
+```bash
+nx action:build ability-erc20-transfer
+```
+
+### Deploying the Lit Action to IPFS
+
+Building will be done automatically. Deploy the ability:
+
+```bash
+nx action:deploy ability-erc20-transfer
+```
+
+## Ability Development Guidelines
+
+1. Use the Vincent Ability SDK to create abilities
+2. Define clear schemas for ability parameters
+3. Implement the ability lifecycle methods (precheck, execute)
+4. Handle errors gracefully
+5. Write comprehensive tests for all functionality
+6. Document the ability's purpose and usage
+
+## Integration with Policies
+
+This ability can be integrated with various Vincent Policies to enforce constraints. When developing or modifying the ability, consider how it will be used with policies such as:
+
+- Vincent Policy Send Counter
+
+## Testing
+
+Write unit tests for all functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document the ability's purpose and usage
+- Update README.md when adding new features
+- Document the ability's parameters and behavior
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new functionality
+4. Link any related issues in your pull request description
+5. Request a review from a maintainer
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [Vincent Ability SDK Documentation](../../libs/ability-sdk/README.md)
+- [ERC20 Standard](https://eips.ethereum.org/EIPS/eip-20)

package/dist/README.md

@@ -0,0 +1,271 @@
+# Vincent Ability ERC20 Transfer
+
+A Vincent Ability for secure ERC-20 token transfers with integrated policy-based governance, balance
+validation, and multi-network support.
+
+## Overview
+
+The `erc20-transfer` ability enables secure ERC-20 token transfers through the Vincent Framework,
+providing:
+
+- Secure transfers using PKP (Programmable Key Pair) wallets
+- Automatic token decimals detection
+- Policy-based governance with integrated rate limiting
+- Balance validation for both native gas fees and token amounts
+- Multi-network support (precheck uses rpcUrl; execute resolves RPC via the `chain` parameter)
+- Real-time transaction execution with detailed logging and error handling
+
+## Key Features
+
+### 🪙 ERC-20 Token Support
+
+- Works with any ERC-20 token
+- Automatically fetches token decimals from the contract
+- Token balance validation before transfer execution
+- Standard ERC-20 transfer function integration
+
+### 🔐 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
+
+- Precheck uses the provided RPC URL (rpcUrl)
+- Execute resolves RPC via the `chain` parameter using Lit Actions
+- Works with any EVM-compatible network
+
+### ✅ Comprehensive Validation
+
+- Ethereum address format validation for recipient and token contract
+- Amount validation (must be a positive decimal string)
+- RPC URL required for precheck
+- Native balance check for gas fees
+- Token balance check before transfer
+
+## Parameters
+
+All functions accept the following parameters:
+
+| Parameter                   | Type      | Description                                                                   |
+| --------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `rpcUrl`                    | `string`  | RPC URL used during precheck validations                                      |
+| `chain`                     | `string`  | Chain name used during execute (e.g., 'base', 'ethereum')                     |
+| `to`                        | `string`  | Recipient address (0x...)                                                     |
+| `tokenAddress`              | `string`  | ERC-20 token contract address (0x...)                                         |
+| `amount`                    | `string`  | Amount in human-readable string (e.g., "1.23")                                |
+| `alchemyGasSponsor`         | `boolean` | Whether to use Alchemy's gas sponsorship (EIP-7702)                           |
+| `alchemyGasSponsorApiKey`   | `string`  | Alchemy API key for gas sponsorship (required if alchemyGasSponsor is true)   |
+| `alchemyGasSponsorPolicyId` | `string`  | Alchemy gas policy ID for sponsorship (required if alchemyGasSponsor is true) |
+
+## Usage Examples
+
+### USDC Transfer on Base Network
+
+```typescript
+const transferParams = {
+  rpcUrl: 'https://base.llamarpc.com',
+  chain: 'base',
+  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // Base USDC
+  amount: '10.50',
+};
+```
+
+### Custom Token Transfer
+
+```typescript
+const transferParams = {
+  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_PROJECT_ID',
+  chain: 'ethereum',
+  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  tokenAddress: '0xYourTokenContractAddress',
+  amount: '100.0',
+};
+```
+
+### Small Amount Transfer (for testing)
+
+```typescript
+const transferParams = {
+  rpcUrl: 'https://base.llamarpc.com',
+  chain: 'base',
+  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
+  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  amount: '0.000001',
+};
+```
+
+## Execution Flow
+
+### 1. Precheck Phase
+
+- Validates recipient address format
+- Validates token contract address format
+- Validates transfer amount (positive, reasonable limits)
+- Validates token decimals (0-18 range)
+- Validates RPC URL format (if provided)
+- Validates chain ID (if provided)
+- Returns validation status
+
+### 2. Execute Phase
+
+- Connects to specified RPC endpoint
+- Retrieves PKP public key from delegation context
+- Converts PKP public key to Ethereum address
+- Parses token amount using specified decimals
+- Validates native balance for gas fees
+- Validates token balance for transfer amount
+- Executes ERC-20 transfer using `laUtils.transaction.handler.contractCall`
+- Triggers policy commit phase for rate limiting
+- Returns transaction hash and metadata
+
+## Policy Integration
+
+The ability automatically integrates with the `send-counter-limit` policy:
+
+- **Precheck**: Validates ability parameters
+- **Execute**: Performs the actual ERC-20 transfer
+- **Policy Commit**: Records the transaction for rate limiting
+
+### Policy Configuration
+
+```typescript
+// Example: Allow 2 ERC-20 transfers per 10 seconds
+const policyConfig = {
+  maxSends: 2n,
+  timeWindowSeconds: 10n,
+};
+```
+
+## Error Handling
+
+The ability provides detailed error messages for various failure scenarios:
+
+### Address Validation Errors
+
+```
+"Invalid recipient address format"
+"Invalid token contract address format"
+```
+
+### 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"
+"Insufficient token balance. Need 100.0 tokens, but only have 50.0 tokens"
+```
+
+### Network Errors
+
+```
+"Invalid RPC URL format"
+"Unable to obtain blockchain provider for transfer operations"
+"PKP public key not available from delegation context"
+```
+
+### Transaction Errors
+
+```
+"Unknown error occurred"
+```
+
+## Response Format
+
+### Success Response
+
+```typescript
+{
+  txHash: "0x...",
+    to
+:
+  "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
+    amount
+:
+  "10.50",
+    tokenAddress
+:
+  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    timestamp
+:
+  1703123456789
+}
+```
+
+### Error Response
+
+```typescript
+{
+  error: 'Detailed error message';
+}
+```
+
+## Development
+
+### Building
+
+```bash
+npm install
+npm run build
+```
+
+### Testing
+
+This ability is tested through the Vincent E2E testing framework:
+
+- `npm run vincent:e2e:erc20` - Tests ERC-20 transfers with rate limiting
+
+### Architecture
+
+The ability follows the Vincent two-phase execution model:
+
+1. **Precheck** - Parameter validation outside Lit Actions
+2. **Execute** - Transaction execution within Lit Actions
+
+## Security Considerations
+
+- **Balance validation**: Comprehensive checks for both native gas fees and token balances
+- **PKP security**: Uses Lit Protocol's secure PKP system
+- **Policy enforcement**: Integrated rate limiting prevents abuse
+- **Network validation**: RPC URL and chain validation prevents malicious endpoints
+
+## Supported Networks
+
+- **Base Mainnet** (Chain ID: 8453)
+- **Ethereum Mainnet** (Chain ID: 1)
+- **Polygon** (Chain ID: 137)
+- **Arbitrum** (Chain ID: 42161)
+- **Any EVM-compatible network supported by Lit**
+
+### Popular Token Addresses
+
+#### Base Network
+
+- **USDC**: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+- **WETH**: `0x4200000000000000000000000000000000000006`
+
+#### Ethereum Mainnet
+
+- **USDC**: `0xA0b86a33E6441b8C4C8C8C8C8C8C8C8C8C8C8C8`
+- **USDT**: `0xdAC17F958D2ee523a2206206994597C13D831ec7`
+
+## Dependencies
+
+- `@lit-protocol/vincent-scaffold-sdk` - Core Vincent framework
+- `@lit-protocol/vincent-ability-sdk` - Ability development framework
+- `ethers.js` - Blockchain interaction
+- `zod` - Schema validation and type safety