Skip to main content

@elizaos/plugin-multichain

Cross-chain integration plugin for Eliza OS that enables seamless token transfers and swaps across multiple blockchain networks using Chain Signatures and NEAR Intents technologies.

Overview​

This plugin serves as a unified interface for cross-chain interactions, allowing seamless token transfers and swaps across major blockchain networks. It leverages Chain Signatures and NEAR Intents for secure multi-chain transactions and cross-chain token swap.

Features​

  • Cross-chain token transfers
  • Multi-chain token swaps
  • Support for major blockchain networks:
    • Bitcoin
    • Ethereum and EVM chains:
      • Polygon
      • BNB Chain
      • Avalanche
      • Arbitrum
      • Optimism
    • Cosmos ecosystem (coming soon)
  • Chain Signatures integration
  • NEAR Intents for optimized execution
  • Portfolio tracking across chains (coming soon)
  • Comprehensive error handling

Installation​

bun install @elizaos/plugin-multichain

Configuration​

The plugin requires environment variables for each supported chain:

# NEAR Configuration (for Chain Signatures and Intents)
NEAR_WALLET_SECRET_KEY=your-near-private-key
NEAR_ADDRESS=your-account.near
NEAR_NETWORK=mainnet
NEAR_RPC_URL=https://rpc.mainnet.near.org

# Ethereum Configuration
ETH_RPC_URL=your-eth-rpc-url

# EVM Chain Configurations
POLYGON_RPC_URL=your-polygon-rpc-url
BSC_RPC_URL=your-bsc-rpc-url
AVAX_RPC_URL=your-avax-rpc-url
ARBITRUM_RPC_URL=your-arbitrum-rpc-url
OPTIMISM_RPC_URL=your-optimism-rpc-url

# Global Settings
DEFAULT_SLIPPAGE=0.01  # 1% slippage tolerance

Usage​

Multi-Chain Transfer​

import { multichainPlugin } from '@elizaos/plugin-multichain';

// Transfer tokens across chains
const result = await eliza.execute({
  action: 'MULTI_CHAIN_TRANSFER',
  content: {
    chain: 'BTC',
    networkId: 'testnet',
    token: null, // Native BTC
    amount: '0.1',
    recipient: 'tb1qmw3xw3y8jtm4054w02kfz58tmf6pcse02twrh8',
  },
});

Cross-Chain Swap​

const result = await eliza.execute({
  action: 'CROSS_CHAIN_SWAP',
  content: {
    sourceChain: 'ETH',
    targetChain: 'COSMOS',
    inputToken: 'ETH',
    outputToken: 'ATOM',
    amount: '1.0',
    recipient: 'cosmos1...',
  },
});

API Reference​

Actions​

MULTI_CHAIN_TRANSFER​

Transfers tokens on multiple chains with a single account

{
  action: 'MULTI_CHAIN_TRANSFER',
  content: {
    chain: string,           // The blockchain (e.g., "BTC", "ETH", "COSMOS")
    networkId: string,       // The network of the blockchain (e.g. "mainnet", "testnet")
    token: string,           // Token to transfer
    amount: string,          // Amount to transfer
    recipient: string        // Recipient address on target chain
  }
}

CROSS_CHAIN_SWAP​

Executes a token swap across different chains.

{
  action: 'CROSS_CHAIN_SWAP',
  content: {
    sourceChain: string,     // Source blockchain
    targetChain: string,     // Target blockchain
    inputToken: string,      // Input token symbol
    outputToken: string,     // Output token symbol
    amount: string,          // Amount to swap
    recipient: string,       // Recipient address
    slippage?: number        // Optional: slippage tolerance
  }
}

Providers​

MultiChain Provider​

Provides cross-chain portfolio tracking and network status.

const portfolioInfo = await eliza.getProvider('multichain');
// Returns consolidated portfolio including:
// - Balances across all chains
// - USD values
// - Network status

Troubleshooting​

Common Issues​

  1. Cross-Chain Transaction Failures

    • Verify sufficient gas/fees on source chain
    • Check Bitcoin UTXO availability
    • Confirm bridge/protocol liquidity
    • Monitor transaction status on both chains

  2. Network Issues

    • Verify RPC endpoints
    • Check network congestion
    • Monitor bridge status
    • Ensure chain signatures are valid

  3. Swap Issues

    • Verify token pair liquidity
    • Check price impact
    • Monitor slippage
    • Confirm route availability

Security Best Practices​

  1. Key Management

    • Secure storage of private keys
    • Regular key rotation
    • Multi-signature support
    • Activity monitoring

  2. Transaction Safety

    • Input validation
    • Amount limits
    • Address verification
    • Transaction simulation

  3. Network Security

    • Secure RPC endpoints
    • Fallback providers
    • Rate limiting
    • Chain signature verification

Testing​

bun test

Development mode:

bun test:watch

Dependencies​

  • multichain-tools: ^4.0.0
  • near-api-js: ^5.0.1
  • bignumber.js: ^9.1.2
  • node-cache: ^5.1.2

Contributing​

See CONTRIBUTING.md for contribution guidelines.

Credits​

This plugin integrates with multiple blockchain networks and their respective technologies:

  • Bitcoin Network
  • Ethereum and EVM-compatible chains
  • NEAR Protocol (Chain Signatures and NEAR Intents)

Special thanks to:

  • The NEAR Protocol team for developing the NEAR blockchain and Chain Signatures
  • The Aurora team for developing the NEAR Intents
  • The Eliza community for their contributions and feedback.

License​

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