Package Exports

@elizaos/plugin-evm
@elizaos/plugin-evm/package.json

Readme

@elizaos/plugin-evm

This plugin provides actions and providers for interacting with EVM-compatible chains.

Description

The EVM plugin provides comprehensive functionality for interacting with EVM-compatible chains, including token transfers, cross-chain bridging, and token swaps using LiFi integration.

Features

Multi-chain support with dynamic chain configuration
Native token transfers
Cross-chain token bridging via LiFi
Token swapping on supported DEXs
Wallet balance tracking
Custom RPC endpoint configuration
Automatic retry mechanisms
Comprehensive transaction management

Installation

pnpm install @elizaos/plugin-evm

Configuration

Required Environment Variables

# Required
EVM_PRIVATE_KEY=your-private-key-here

# Optional - Custom RPC URLs
EVM_PROVIDER_URL=https://your-custom-mainnet-rpc-url
ETHEREUM_PROVIDER_<CHAIN_NAME>=https://your-custom-rpc-url

Chain Configuration

By default, Ethereum mainnet is enabled. To enable additional chains, add them to your character config:

"settings": {
    "chains": {
        "evm": [
            "base", "arbitrum", "iotex"
        ]
    }
}

Note: The chain names must match those in the viem/chains.

Custom RPC URLs

By default, the RPC URL is inferred from the viem/chains config. To use a custom RPC URL for a specific chain, add the following to your .env file:

ETHEREUM_PROVIDER_<CHAIN_NAME>=https://your-custom-rpc-url

Example usage:

ETHEREUM_PROVIDER_IOTEX=https://iotex-network.rpc.thirdweb.com

Custom RPC for Ethereum Mainnet

To set a custom RPC URL for Ethereum mainnet, use:

EVM_PROVIDER_URL=https://your-custom-mainnet-rpc-url

Provider

The Wallet Provider initializes with the first chain in the list as the default (or Ethereum mainnet if none are added). It:

Provides the context of the currently connected address and its balance.
Creates Public and Wallet clients to interact with the supported chains.
Allows adding chains dynamically at runtime.

Actions

1. Transfer

Transfer native tokens on the same chain:

// Example: Transfer 1 ETH
Transfer 1 ETH to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

2. Bridge

Bridge tokens between different chains using LiFi:

// Example: Bridge ETH from Ethereum to Base
Bridge 1 ETH from Ethereum to Base

3. Swap

Swap tokens on the same chain using LiFi:

// Example: Swap ETH for USDC
Swap 1 ETH for USDC on Base

4. Propose

Propose a proposal to a governor on a specific chain.

Proposal
- Targets
- Values
- Calldatas
- Description
Chain
Governor

Example usage:

Propose a proposal to the 0xdeadbeef00000000000000000000000000000000 governor on Ethereum to transfer 1 ETH to 0xRecipient.

5. Vote

Vote on a proposal to a governor on a specific chain.

Proposal ID
Support
Chain
Governor

Example usage:

Vote on the proposal with ID 1 to support the proposal on the 0xdeadbeef00000000000000000000000000000000 governor on Ethereum.

6. Queue

Queue a proposal to a governor on a specific chain.

Proposal
- Targets
- Values
- Calldatas
- Description
Chain
Governor

Example usage:

Queue the proposal to the 0xdeadbeef00000000000000000000000000000000 governor on Ethereum.

7. Execute

Execute a proposal to a governor on a specific chain.

Proposal ID
Chain
Governor

Example usage:

Execute the proposal with ID 1 on the 0xdeadbeef00000000000000000000000000000000 governor on Ethereum.

Development

Clone the repository
Install dependencies:

pnpm install

Build the plugin:

pnpm run build

Run tests:

pnpm test

API Reference

Core Components

WalletProvider
- Manages wallet connections
- Handles chain switching
- Manages RPC endpoints
- Tracks balances
Actions
- TransferAction: Native token transfers
- BridgeAction: Cross-chain transfers
- SwapAction: Same-chain token swaps

Future Enhancements

Cross-Chain Operations
- Enhanced bridge aggregation
- Multi-chain transaction batching
- Cross-chain liquidity management
- Bridge fee optimization
- Chain-specific gas strategies
- Cross-chain messaging
DeFi Integration
- Advanced swap routing
- Yield farming automation
- Liquidity pool management
- Position management tools
- MEV protection features
- Flash loan integration
Smart Contract Management
- Contract deployment templates
- Verification automation
- Upgrade management
- Security analysis tools
- Gas optimization
- ABI management system
Token Operations
- Batch transfer tools
- Token approval management
- Token metadata handling
- Custom token standards
- Token bridging optimization
- NFT support enhancement
Wallet Features
- Multi-signature support
- Account abstraction
- Hardware wallet integration
- Social recovery options
- Transaction simulation
- Batch transaction processing
Network Management
- Dynamic RPC management
- Network health monitoring
- Fallback provider system
- Custom network addition
- Gas price optimization
- Network analytics
Security Enhancements
- Transaction validation
- Risk assessment tools
- Fraud detection
- Rate limiting
- Emergency shutdown
- Audit integration
Developer Tools
- Enhanced debugging
- Testing framework
- Documentation generator
- CLI improvements
- Performance profiling
- Integration templates

We welcome community feedback and contributions to help prioritize these enhancements.

Contributing

The plugin contains tests. Whether you're using TDD or not, please make sure to run the tests before submitting a PR:

pnpm test

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Credits

This plugin integrates with and builds upon several key technologies:

Ethereum: Decentralized blockchain
LiFi: Cross-chain bridge and swap service
viem: Ethereum client library
wagmi: Ethereum client library

Special thanks to:

Ethereum Developer community
The Eliza community for their contributions and feedback

For more information about EVM capabilities:

License

This plugin is part of the Eliza project. See the main project repository for license information.