feat: add lit plugin (elizaOS#2703)

* init: lit plugin

* remove files from cache

* update Lit actions

* add minor updates

* add example env + initilisation

* Update pnpm-lock.yaml

---------

Co-authored-by: Sayo <[email protected]>

.env.example

@@ -820,4 +820,8 @@ HYPERBOLIC_SPASH=true
 HYPERBOLIC_LOG_LEVEL=debug
 
 # Football Plugin Configuration
-FOOTBALL_API_KEY=                   # API key from Football-Data.org (https://www.football-data.org/)
+FOOTBALL_API_KEY=                   # API key from Football-Data.org (https://www.football-data.org/)
+
+# Lit Protocol
+FUNDING_PRIVATE_KEY=    # Private key for funding transactions in Lit Protocol
+EVM_RPC_URL=                # RPC endpoint URL for blockchain interactions

.gitignore

@@ -68,3 +68,5 @@ eliza.sig
 packages/plugin-nvidia-nim/extra
 packages/plugin-nvidia-nim/old_code
 packages/plugin-nvidia-nim/docs
+
+lit-config.json

agent/package.json

@@ -62,6 +62,7 @@
         "@elizaos/plugin-icp": "workspace:*",
         "@elizaos/plugin-initia": "workspace:*",
         "@elizaos/plugin-image-generation": "workspace:*",
+        "@elizaos/plugin-lit": "workspace:*",
         "@elizaos/plugin-movement": "workspace:*",
         "@elizaos/plugin-massa": "workspace:*",
         "@elizaos/plugin-nft-generation": "workspace:*",

agent/src/index.ts

@@ -115,7 +115,6 @@ import { hyperliquidPlugin } from "@elizaos/plugin-hyperliquid";
 import { echoChambersPlugin } from "@elizaos/plugin-echochambers";
 import { dexScreenerPlugin } from "@elizaos/plugin-dexscreener";
 import { pythDataPlugin } from "@elizaos/plugin-pyth-data";
-
 import { openaiPlugin } from "@elizaos/plugin-openai";
 import nitroPlugin from "@elizaos/plugin-router-nitro";
 import { devinPlugin } from "@elizaos/plugin-devin";
@@ -124,6 +123,7 @@ import { chainbasePlugin } from "@elizaos/plugin-chainbase";
 import { nvidiaNimPlugin } from "@elizaos/plugin-nvidia-nim";
 import { zxPlugin } from "@elizaos/plugin-0x";
 import { hyperbolicPlugin } from "@elizaos/plugin-hyperbolic";
+import { litPlugin } from "@elizaos/plugin-lit";
 import Database from "better-sqlite3";
 import fs from "fs";
 import net from "net";
@@ -1164,7 +1164,8 @@ export async function createAgent(
                 ? hyperbolicPlugin
                 : null,
             getSecret(character, "SUNO_API_KEY") ? sunoPlugin : null,
-            getSecret(character, "UDIO_AUTH_TOKEN") ? udioPlugin : null
+            getSecret(character, "UDIO_AUTH_TOKEN") ? udioPlugin : null,
+            getSecret(character, "FUNDING_PRIVATE_KEY") && getSecret(character, "EVM_RPC_URL") ? litPlugin : null            ,
         ].filter(Boolean),
         providers: [],
         managers: [],

packages/plugin-lit/.npmignore

@@ -0,0 +1,6 @@
+*
+
+!dist/**
+!package.json
+!readme.md
+!tsup.config.ts

packages/plugin-lit/README.md

@@ -0,0 +1,129 @@
+# @elizaos/plugin-lit
+
+A comprehensive blockchain interaction plugin for the Eliza Agent Stack, powered by Lit Protocol's Programmable Key Pairs (PKPs). This plugin enables autonomous agents to perform secure cross-chain transactions through decentralized key management and threshold cryptography.
+
+## Overview
+
+The Lit Protocol plugin provides:
+- Dual-chain wallet management (EVM + Solana)
+- Secure transaction signing and execution
+- Capacity credit management
+- Automated PKP lifecycle management
+- Security evaluations for transactions
+
+## Features
+
+- **Wallet Management**
+  - Automated PKP creation and management
+  - Dual-chain support (EVM + Solana)
+  - Secure key storage and rotation
+  - Capacity credit allocation
+
+- **Transaction Support**
+  - ETH transfers
+  - USDC transfers
+  - SOL transfers
+  - Transaction security validation
+
+- **Security Features**
+  - Transaction amount limits
+  - Security evaluations
+  - PKP validation
+  - Session management
+  - Capacity credit monitoring
+
+## Installation
+```bash
+npm install @elizaos/plugin-lit
+```
+
+## Configuration
+
+Required environment variables:
+```env
+FUNDING_PRIVATE_KEY=   # Private key for funding operations
+EVM_RPC_URL=           # RPC endpoint for blockchain interactions
+LIT_PKP_PUBLIC_KEY=    # (Optional) Existing PKP public key
+```
+
+## Important: Wallet Funding
+
+Before executing any transactions, you must fund the generated Lit wallet address with the necessary assets (ETH, SOL, or USDC). The plugin will create a new PKP wallet address if one isn't provided, and this address will need to hold sufficient funds to:
+1. Cover the amount being transferred
+2. Pay for transaction fees (gas fees on EVM chains, transaction fees on Solana)
+
+You can view your PKP wallet address after initializing the plugin using the configuration file (`lit-config.json`).
+
+## Usage
+
+### Basic Setup
+```typescript
+import { litPlugin } from '@elizaos/plugin-lit';
+
+// Register the plugin
+runtime.registerPlugin(litPlugin);
+```
+
+### Sending ETH
+```typescript
+// Send ETH transaction
+await runtime.executeAction('SEND_ETH', {
+  text: "Send 0.01 ETH to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
+});
+```
+
+### Sending SOL
+```typescript
+// Send SOL transaction
+await runtime.executeAction('SEND_SOL', {
+  text: "Send 0.1 SOL to 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
+});
+```
+
+### Sending USDC
+```typescript
+// Send USDC transaction
+await runtime.executeAction('SEND_USDC', {
+  text: "Send 10 USDC to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
+});
+```
+
+## Security
+
+The plugin implements multiple security layers:
+- Transaction amount limits
+- Automated security evaluations
+- PKP validation checks
+- Session-based authentication
+- Capacity credit management
+- Automatic key rotation
+
+## Architecture
+
+The plugin consists of several key components:
+
+- **Providers**
+  - `litProvider`: Manages PKP creation and Lit Protocol integration
+  - `pkpPermissionsProvider`: Handles PKP permissions and auth methods
+
+- **Actions**
+  - `sendEth`: ETH transfer functionality
+  - `sendSol`: SOL transfer functionality
+  - `sendUSDC`: USDC transfer functionality
+
+## Configuration Management
+
+The plugin uses a local configuration file (`lit-config.json`) to store:
+- PKP details
+- Network configuration
+- Wallet information
+- Capacity credits
+- Session data
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
+
+## License
+
+MIT

packages/plugin-lit/eslint.config.mjs

@@ -0,0 +1,3 @@
+import eslintGlobalConfig from "../../eslint.config.mjs";
+
+export default [...eslintGlobalConfig];

packages/plugin-lit/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@elizaos/plugin-lit",
+    "version": "0.1.7",
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "import": {
+                "@elizaos/source": "./src/index.ts",
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@elizaos/core": "workspace:*",
+        "@ethersproject/abstract-provider": "^5.0.0",
+        "@lit-protocol/auth-helpers": "^7.0.2",
+        "@lit-protocol/constants": "^7.0.2",
+        "@lit-protocol/contracts-sdk": "^7.0.2",
+        "@lit-protocol/lit-auth-client": "^7.0.2",
+        "@lit-protocol/lit-node-client": "^7.0.2",
+        "@lit-protocol/pkp-client": "6.11.3",
+        "@lit-protocol/pkp-ethers": "^7.0.2",
+        "@lit-protocol/types": "^6.11.3",
+        "@lit-protocol/wrapped-keys": "^7.0.2",
+        "@solana/web3.js": "^1.95.8",
+        "ethers": "^5.7.2",
+        "siwe": "^2.0.0",
+        "tsup": "8.3.5",
+        "zod": "3.22.4"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "typescript": "^5.0.0"
+    },
+    "scripts": {
+        "build": "tsup --format esm --dts",
+        "dev": "tsup --format esm --dts --watch",
+        "lint": "eslint . --fix",
+        "clean": "rm -rf dist",
+        "typecheck": "tsc --noEmit"
+    }
+}

packages/plugin-lit/pkp-setup.md

@@ -0,0 +1,109 @@
+# PKP Setup Guide for @plugin-lit
+
+## Overview
+This guide explains the Programmable Key Pair (PKP) setup process for @plugin-lit and the configuration file structure.
+
+## Automatic PKP Creation
+
+The PKP creation in @plugin-lit is automatic. The process is handled by the `litProvider` during initialization, which:
+
+1. Checks for existing configuration
+2. If no PKP exists, automatically:
+   - Creates a new EVM wallet
+   - Generates a Solana wallet
+   - Mints a new PKP
+   - Mints a capacity credit NFT
+   - Saves all configurations to `lit-config.json`
+
+## Configuration File Structure
+
+The `lit-config.json` file is automatically created with the following structure:
+
+```json
+{
+"pkp": {
+"tokenId": "0xca60...", // The PKP token ID
+"publicKey": "04b756...", // The PKP public key
+"ethAddress": "0xB2D4...", // The Ethereum address
+"solanaAddress": "HzunQ..." // The Solana address
+},
+"network": "Chain ID 175188", // The network identifier
+"timestamp": 1735839217558, // Creation timestamp
+"evmWalletPrivateKey": "0x710...", // EVM wallet private key
+"solanaWalletPrivateKey": "Wz0...", // Solana wallet private key (base64)
+"capacityCredit": {
+"tokenId": "87622" // Capacity credit NFT token ID
+},
+"wrappedKeyId": "0b410..." // Wrapped key identifier
+}
+```
+
+
+### Configuration Fields Explained
+
+#### PKP Section
+- `tokenId`: Unique identifier for the PKP NFT
+- `publicKey`: PKP's public key
+- `ethAddress`: Generated Ethereum address
+- `solanaAddress`: Generated Solana address
+
+#### Other Fields
+- `network`: Identifies the blockchain network
+- `timestamp`: Creation timestamp
+- `evmWalletPrivateKey`: Private key for EVM transactions
+- `solanaWalletPrivateKey`: Private key for Solana transactions (base64 encoded)
+- `capacityCredit.tokenId`: Used for rate limiting and usage tracking
+- `wrappedKeyId`: Used for secure key management with Lit Protocol
+
+## Security Considerations
+
+The `lit-config.json` file contains sensitive information. Important security measures:
+
+1. Add to `.gitignore`
+2. Never share or expose the file
+3. Maintain secure backups
+4. Store in a safe location
+
+## Required Environment Variables
+
+Set these environment variables for proper PKP creation:
+
+```env
+FUNDING_PRIVATE_KEY= # Private key for funding operations
+RPC_URL= # RPC endpoint for blockchain interactions
+```
+
+
+## Optional Manual Configuration
+
+There are two ways to use an existing PKP instead of automatic creation:
+
+1. Set the environment variable:
+```env
+LIT_PKP_PUBLIC_KEY=   # Your existing PKP public key
+```
+
+2. Copy an existing `lit-config.json` file:
+   - Simply copy your existing `lit-config.json` file into your project's root directory
+   - The plugin will detect and use this configuration instead of creating a new one
+   - Ensure the copied configuration file contains all required fields
+   - This is useful for maintaining the same PKP across multiple environments or projects
+
+> Note: When copying an existing configuration, make sure to maintain proper security practices and never commit the file to version control.
+
+
+## Verification Steps
+
+Verify your setup by checking:
+
+1. `lit-config.json` exists in your project
+2. PKP configuration is valid
+3. Capacity credit NFT is allocated
+
+The plugin handles ongoing PKP rotation and management automatically based on the configuration.
+
+## Support
+
+For additional support or questions:
+- Visit the [Lit Protocol Documentation](https://developer.litprotocol.com/)
+- Join the [Lit Protocol Discord](https://discord.com/invite/lit)

packages/plugin-lit/src/actions/index.ts

@@ -0,0 +1,4 @@
+// export { swapTokens } from "./swapTokens";
+export { sendEth } from "./sendEth";
+export { sendUSDC } from "./sendUSDC";
+export { sendSol } from "./sendSol";