Secure your secrets, empower your agent. A production-ready Eliza plugin that brings Lit Protocol's programmable cryptography and wallet-based encryption to your AI agents.

What makes this special:

• 🎁 Zero-Config Encryption: Encrypt .env files with just your wallet - no complex setup
• 🔄 Auto-Decrypt Magic: Clone repo, run agent, secrets auto-decrypt. That's it.
• 🏗️ Service Architecture: Built properly with LitService, not scattered utilities
• 📦 Latest & Greatest: Ethers v6, Lit Protocol v7.3.1, Eliza 1.x standards

• 🔐 Environment Encryption: Wallet-based .env file encryption with auto-decrypt
• 🎯 Service Layer: Centralized LitService managing all Lit Protocol operations
• 🔑 PKP Integration: Programmable Key Pairs for distributed key management
• ✍️ ECDSA Signing: Message signing with policy-based access control
• 💸 ERC-20 Transfers: Secure token transfers via Lit Actions
• 💱 Uniswap Integration: Automated token swaps on Uniswap v3
• 🚀 Production Ready: Latest packages (ethers v6, Lit Protocol v7.3.1)

• Quick Start
• Configuration
• Encryption Features
• Available Actions
• Architecture
• Use Cases
• Service API Reference
• Troubleshooting
• Contributing

npm install @elizaos/plugin-lit

1. Add to your character file:

{
  "name": "MyAgent",
  "plugins": ["@elizaos/plugin-lit"],
  "settings": {
    "secrets": {
      "EVM_PRIVATE_KEY": "0xYourPrivateKey"
    }
  }
}

2. Start your agent:

npm run dev

3. Try encryption:

You: "Encrypt my .env file"
Agent: ✅ Successfully encrypted .env to .env.encrypted
       🔐 Access Control: Only your wallet can decrypt this file

# 1. Create your .env with secrets
echo "OPENAI_API_KEY=sk-..." > .env
echo "ANTHROPIC_API_KEY=..." >> .env

# 2. Start agent and encrypt
npm run dev
# In chat: "Encrypt my .env file"

# 3. Commit the encrypted file
git add .env.encrypted
git commit -m "Add encrypted environment config"

# 4. On new machine, just clone and run
git clone your-repo
npm run dev
# Auto-decrypts on startup! ✨

Add these to your .eliza/.env file:

Add the plugin to your character configuration file:

{
  "name": "YourCharacter",
  "plugins": ["@elizaos/plugin-lit"],
  "settings": {
    "secrets": {
      "EVM_PRIVATE_KEY": "your-private-key-here"
    }
  }
}

Or programmatically in your agent:

import litPlugin from "@elizaos/plugin-lit";

const character = {
  name: "YourCharacter",
  plugins: [litPlugin],
};

NEW! Secure your environment variables using Lit Protocol's wallet-based encryption. Your .env file is encrypted so only your wallet can decrypt it - perfect for sharing configurations safely or storing secrets in version control.

Natural Language Triggers:

• "Encrypt my .env file"
• "Secure my environment variables"
• "Lock my secrets"

How it works:

1. Your .env file is encrypted using Lit Protocol
2. Access control is set to your wallet address only
3. The encrypted .env.encrypted file is created
4. The encrypted file can be safely committed to git
5. Only you (with your wallet) can decrypt it

Environment Variables:

• EVM_PRIVATE_KEY: Your wallet private key (required)
• ENV_FILE_PATH: Path to .env file (default: .env)
• ENCRYPTED_ENV_PATH: Path for encrypted output (default: .env.encrypted)
• AUTHORIZED_WALLET: Wallet address that can decrypt (default: your wallet)

Example:

# Encrypt your .env file
> "Encrypt my .env file"

# Creates .env.encrypted with wallet-based access control
# Add .env.encrypted to git, keep .env in .gitignore

Decrypt your encrypted environment variables using your wallet signature. The agent can even auto-decrypt on startup!

Natural Language Triggers:

• "Decrypt my .env file"
• "Unlock my environment variables"
• "Decrypt my secrets"

How it works:

1. Agent reads .env.encrypted
2. You sign with your wallet to prove ownership
3. Lit Protocol verifies access and provides decryption keys
4. .env file is created with decrypted content

Auto-Decrypt on Startup: The plugin automatically checks for .env.encrypted on startup. If found and .env doesn't exist, it will auto-decrypt using your EVM_PRIVATE_KEY. Disable with LIT_AUTO_DECRYPT_ENV=false.

Environment Variables:

• EVM_PRIVATE_KEY: Your wallet private key (required)
• ENCRYPTED_ENV_PATH: Path to encrypted file (default: .env.encrypted)
• ENV_FILE_PATH: Path for decrypted output (default: .env)
• LIT_AUTO_DECRYPT_ENV: Enable/disable auto-decrypt on startup (default: true)

Example Workflow:

# Team member A encrypts their .env
> "Encrypt my .env file"
# Commits .env.encrypted to repo

# Team member B clones repo
# On agent startup, auto-decrypt runs:
✅ Successfully auto-decrypted .env.encrypted to .env
🔓 Decrypted with wallet: 0x...

# Or manually:
> "Decrypt my .env file"

Securely encrypt your environment files with wallet-based access control.

Natural Language:

"Encrypt my .env file"
"Secure my environment variables"
"Lock my secrets"

What it does:

• Reads your .env file
• Encrypts with Lit Protocol using your wallet
• Creates .env.encrypted (safe to commit!)
• Sets access control to your wallet only

Required: EVM_PRIVATE_KEY

Decrypt encrypted environment files using wallet signature.

Natural Language:

"Decrypt my .env file"
"Unlock my environment variables"
"Decrypt my secrets"

What it does:

• Reads .env.encrypted
• Verifies your wallet signature
• Decrypts and creates .env
• Auto-runs on startup if .env missing!

Required: EVM_PRIVATE_KEY

Sign messages using Lit Protocol's programmable key pairs.

Natural Language:

"Sign this message: Hello World"
"Create a signature for [message]"

What it does:

• Executes ECDSA signing Lit Action
• Applies policy controls (allowed prefixes)
• Returns cryptographic signature

Required:

• EVM_PRIVATE_KEY
• PKP_ETH_ADDRESS

Transfer ERC-20 tokens via secure Lit Actions.

Natural Language:

"Send 100 USDC to 0x..."
"Transfer tokens to [address]"

What it does:

• Validates transfer policy
• Creates blockchain transaction
• Signs with PKP
• Broadcasts to network

Required:

• EVM_PRIVATE_KEY
• PKP_ETH_ADDRESS
• TOKEN_ADDRESS
• RECIPIENT_ADDRESS
• CHAIN_ID
• RPC_URL

Execute token swaps on Uniswap v3.

Natural Language:

"Swap 1 ETH for USDC"
"Exchange tokens on Uniswap"

What it does:

• Finds best swap route/price
• Validates swap policy
• Approves token spending
• Executes swap transaction

Required:

• EVM_PRIVATE_KEY
• PKP_ETH_ADDRESS
• TOKEN_IN_ADDRESS
• TOKEN_OUT_ADDRESS
• CHAIN_ID
• RPC_URL

Test action to verify Lit Protocol connectivity.

Natural Language:

"Test Lit Protocol"
"Hello Lit"
"Verify Lit connection"

What it does:

• Connects to Lit Network
• Executes simple test action
• Confirms integration working

Required: EVM_PRIVATE_KEY

npm run build

npm run lint

npm run format

This plugin follows Eliza 1.x best practices with a dedicated LitService that manages all Lit Protocol operations:

┌─────────────────────────────────────────────────┐
│                  Eliza Runtime                   │
├─────────────────────────────────────────────────┤
│                                                  │
│  ┌────────────────────────────────────────┐    │
│  │          LitService (Singleton)         │    │
│  │                                          │    │
│  │  • Lit Client Management                │    │
│  │  • Session Signature Caching            │    │
│  │  • Wallet Lifecycle                     │    │
│  │  • Auto-decrypt on Startup              │    │
│  └────────────────────────────────────────┘    │
│                     ▲                            │
│                     │                            │
│  ┌──────────────────┴─────────────────────┐    │
│  │            Actions Layer                │    │
│  │                                          │    │
│  │  • encryptEnv    • ecdsaSign            │    │
│  │  • decryptEnv    • erc20Transfer        │    │
│  │  • helloLit      • uniswapSwap          │    │
│  └──────────────────────────────────────────┘  │
│                                                  │
└─────────────────────────────────────────────────┘

Key Benefits:

• Single Client Instance: Shared Lit client across all actions
• Session Reuse: Session signatures cached and reused
• Automatic Initialization: Service starts with plugin, handles setup
• Clean Separation: Actions focus on logic, service handles complexity
• 90% Code Reduction: Actions went from 150+ lines to ~30 lines each

• Programmable Key Pairs (PKPs): Distributed key pairs controlled by Lit Actions
• Lit Actions: JavaScript executed across the Lit network for authorization
• Policy Controls: Fine-grained access control for cryptographic operations
• Encryption SDK: Client-side encryption with decentralized access control
• Capacity Credits: Pay-per-use model for network operations

1. Safe Secret Sharing in Teams

• Encrypt .env files for team members' wallets
• Each team member can only decrypt with their own wallet
• No more sharing secrets in Slack or email

2. Version Control Security

• Commit .env.encrypted to your repository safely
• Keep sensitive credentials encrypted at rest
• New team members can decrypt with their wallet

3. Multi-Environment Management

• Encrypt different .env files for dev/staging/prod
• Control access per environment with different wallets
• Audit who decrypted what and when

4. Zero-Knowledge Secret Storage

• Your secrets are encrypted client-side
• Lit nodes can't read your data
• Only your wallet signature grants access

5. Portable Credential Management

• Take your encrypted .env anywhere
• Decrypt on any machine with your wallet
• No need for password managers or key vaults

6. Decentralized Transaction Signing

• Execute blockchain transactions without exposing private keys
• Policy-based authorization for token transfers
• Multi-signature workflows with programmable conditions

7. Automated DeFi Operations

• Schedule token swaps with price limits
• Automated portfolio rebalancing
• Conditional execution based on on-chain data

8. Secure Message Signing

• Sign messages with distributed key shares
• Enforce signing policies (message prefixes, rate limits)
• Audit trail of all signing operations

The LitService provides a comprehensive API for Lit Protocol operations:

const litService = runtime.getService<LitService>("lit");

// Get Lit node client
const client = await litService.getLitClient();

// Get session signatures
const sessionSigs = await litService.getSessionSigs();

// Get wallet instance
const wallet = litService.getWallet();

// Encrypt a string
const encrypted = await litService.encryptString(
  "sensitive data",
  "0xAuthorizedWalletAddress" // optional, defaults to your wallet
);

// Decrypt a string
const decrypted = await litService.decryptString(encryptedData);

// Encrypt .env file
await litService.encryptEnvFile(
  ".env",              // source
  ".env.encrypted",    // output
  "0xWalletAddress"    // who can decrypt (optional)
);

// Decrypt .env file
await litService.decryptEnvFile(
  ".env.encrypted",    // source
  ".env"               // output
);

// Execute by IPFS CID
const response = await litService.executeJs({
  ipfsId: "QmYourIPFSCid...",
  jsParams: {
    params: { /* your parameters */ }
  }
});

// Execute code directly
const response = await litService.executeJsCode({
  code: "(async () => { /* your code */ })()",
  jsParams: { magicNumber: 42 }
});

1. Never Commit .env Files

   • Always keep .env in .gitignore
   • Only commit .env.encrypted to version control
   • Encrypted files are safe but still contain sensitive structure info

2. Wallet Key Management

   • Store EVM_PRIVATE_KEY securely
   • Use hardware wallets for production
   • Consider key rotation policies

3. Access Control

   • Review who has access to encrypted files
   • Use AUTHORIZED_WALLET to grant access to specific addresses
   • Audit encryption/decryption events in logs

4. Network Selection

   • Use datil-dev for development only
   • Use datil for production deployments
   • Understand Lit network limitations and costs

• Client-Side Encryption: All encryption happens in your browser/node, never on servers
• Zero-Knowledge: Lit nodes can't read your encrypted data
• Threshold Cryptography: Decryption requires majority of Lit nodes to cooperate
• Wallet Signatures: Every decrypt operation requires fresh wallet signature

Q: Can I encrypt files other than .env? A: Yes! Use the LitService API directly to encrypt any string or file data.

Q: What happens if I lose my private key? A: Encrypted data becomes unrecoverable. Always backup your keys securely.

Q: Can I give multiple wallets access? A: Currently single-wallet access. For multi-wallet, encrypt separately for each wallet or use NFT/token-based access control conditions.

Q: Does this work offline? A: No, requires connection to Lit Protocol network for encryption/decryption operations.

Q: What's the cost? A: Lit Protocol uses capacity credits. Development networks are typically free/low-cost.

Q: Can I use this in production? A: Yes! Set LIT_NETWORK=datil and ensure you have capacity credits.

• Lit Protocol Documentation
• Lit Protocol Agent Wallet
• Lit Protocol Encryption Guide
• Eliza Documentation

• Eliza Discord
• Lit Protocol Discord
• Plugin Source Code
• Report Issues

Contributions are welcome! This plugin is built with:

• TypeScript 5.8+
• Ethers.js v6 (v5 in Lit Action runtime)
• Lit Protocol SDK v7.3.1
• Eliza Core v1.6+

# Install dependencies
npm install

# Build the plugin
npm run build

# Format code
npm run format

# Clean build artifacts
npm run clean

Service Layer:

• All Lit Protocol operations MUST go through LitService
• Actions should be <50 lines, just call service methods
• No direct LitJsSdk.LitNodeClient initialization in actions

Logging:

• Use logger from @elizaos/core, never console.log
• Use structured logging: logger.info("Action", { metadata })

Ethers API:

• Main code uses ethers v6 API
• lit-actions runtime uses ethers v5 API (global ethers in Lit runtime)

TypeScript:

• Strict mode enabled
• No any types without good reason
• Cast runtime.getSetting() results: as string

Testing:

• Test actions through service interface
• Mock LitService for unit tests
• Integration tests should use datil-dev network

1. Update README if adding features
2. Run npm run format before committing
3. Ensure npm run build passes
4. Add examples for new actions
5. Update CHANGELOG in README

"Lit Protocol service not initialized"

# Ensure EVM_PRIVATE_KEY is set
echo "EVM_PRIVATE_KEY=0x..." >> .env

"Failed to auto-decrypt .env.encrypted"

# Check wallet has access (must match encrypted wallet)
# Or disable auto-decrypt:
echo "LIT_AUTO_DECRYPT_ENV=false" >> .env

"Connection to Lit Network failed"

# Check network connectivity
# Try different Lit network:
echo "LIT_NETWORK=datil-test" >> .env

Build errors after updating

# Clean install
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build

Current Version: v1.6.3

Dependencies:

• @elizaos/core: ^1.6.0
• ethers: ^6.15.0 (v5 in Lit Action runtime)
• @lit-protocol/lit-node-client: ^7.3.1
• @lit-protocol/encryption: ^7.3.1
• @lit-protocol/auth-helpers: ^7.3.1
• Node.js 18+ or Bun

Peer Dependencies:

• whatwg-url: ^15.1.0

• 📖 Check Lit Protocol Docs
• 💬 Join Eliza Discord
• 🐛 Report issues on GitHub

• ✅ Added LitService for centralized Lit Protocol management
• ✅ Refactored all actions to use service layer
• ✅ Reduced action code by ~90%
• ✅ Better error handling and logging

• ✅ Added .env encryption/decryption actions
• ✅ Auto-decrypt on startup feature
• ✅ Wallet-based access control for files

• ✅ Updated to ethers v6
• ✅ Updated to Lit Protocol v7.3.1
• ✅ Modernized plugin architecture for Eliza 1.x
• ✅ Comprehensive agentConfig documentation

MIT License

Copyright (c) 2025 elizaOS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.