Skip to main content

@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​

bun 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​

  1. Clone the repository
  2. Install dependencies:
bun install
  1. Build the plugin:
bun run build
  1. Run tests:
bun test

API Reference​

Core Components​

  1. WalletProvider

    • Manages wallet connections
    • Handles chain switching
    • Manages RPC endpoints
    • Tracks balances

  2. Actions

    • TransferAction: Native token transfers
    • BridgeAction: Cross-chain transfers
    • SwapAction: Same-chain token swaps

Future Enhancements​

  1. Cross-Chain Operations

    • Enhanced bridge aggregation
    • Multi-chain transaction batching
    • Cross-chain liquidity management
    • Bridge fee optimization
    • Chain-specific gas strategies
    • Cross-chain messaging

  2. DeFi Integration

    • Advanced swap routing
    • Yield farming automation
    • Liquidity pool management
    • Position management tools
    • MEV protection features
    • Flash loan integration

  3. Smart Contract Management

    • Contract deployment templates
    • Verification automation
    • Upgrade management
    • Security analysis tools
    • Gas optimization
    • ABI management system

  4. Token Operations

    • Batch transfer tools
    • Token approval management
    • Token metadata handling
    • Custom token standards
    • Token bridging optimization
    • NFT support enhancement

  5. Wallet Features

    • Multi-signature support
    • Account abstraction
    • Hardware wallet integration
    • Social recovery options
    • Transaction simulation
    • Batch transaction processing

  6. Network Management

    • Dynamic RPC management
    • Network health monitoring
    • Fallback provider system
    • Custom network addition
    • Gas price optimization
    • Network analytics

  7. Security Enhancements

    • Transaction validation
    • Risk assessment tools
    • Fraud detection
    • Rate limiting
    • Emergency shutdown
    • Audit integration

  8. 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:

bun 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:

For more information about EVM capabilities:

License​

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