@elizaos/plugin-debridge

Cross-chain interoperability and liquidity plugin for ElizaOS agents via the deBridge protocol.

Description

The deBridge plugin enables ElizaOS agents to perform seamless cross-chain operations, including asset swaps, liquidity bridging, complex transaction hooks, and agent-to-agent payments. Powered by deBridge's Liquidity Network Protocol (DLN), it allows agents to interact confidently across multiple blockchains with complete transaction lifecycle management.

Installation

pnpm install @elizaos/plugin-debridge

Features

1. Cross-Chain Operations

• CROSS_CHAIN_SWAP: Swap tokens between different blockchains
• LIMIT_ORDER: Create cross-chain swaps with minimum output guarantees
• EXECUTE_DEBRIDGE_HOOK: Attach on-chain actions to cross-chain transactions
• CANCEL_ORDER: Cancel active cross-chain orders
• AGENT_TO_AGENT_PAYMENT: Transfer tokens between agents across chains

2. Blockchain Support

• Ethereum and EVM-compatible chains (Polygon, Arbitrum, BNB Chain, etc.)
• Solana
• All chains supported by deBridge protocol
• Extensible architecture for adding new chains

3. Transaction Management

• Real-time transaction status monitoring
• Persistent transaction history
• Detailed error tracking and recovery
• Comprehensive memory integration

4. Advanced Hook Capabilities

• Asset distribution hooks
• Blockchain abstraction (auto-staking, auto-deposit)
• Cross-chain protocol interactions
• Custom transaction triggers

5. Agent Intelligence

• Natural language extraction of transaction parameters
• Automatic evaluation of transaction intentions
• Context-aware transaction history recall
• Risk assessment and explanation

Architecture

The plugin is built around five core components:

1. Actions: Execute cross-chain operations
2. Evaluators: Extract and process transaction information
3. Providers: Supply contextual blockchain data
4. Services: Manage blockchain connections and monitoring
5. Memory Integration: Store transaction history and status

┌─────────────────────────────────────────┐
│             Eliza Agent                 │
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│           deBridge Plugin               │
├─────────────────────────────────────────┤
│ ┌─────────┐  ┌──────────┐  ┌──────────┐ │
│ │ Actions │  │Evaluators│  │Providers │ │
│ └─────┬───┘  └────┬─────┘  └────┬─────┘ │
│       │           │             │       │
│       └────┬──────┴─────────────┘       │
│            │                            │
│    ┌───────▼────────┐                   │
│    │  Services      │                   │
│    └───────┬────────┘                   │
└────────────┼────────────────────────────┘
             │
┌────────────▼────────────────────────────┐
│         Blockchain Networks              │
└─────────────────────────────────────────┘

Usage Examples

Basic Cross-Chain Swap

// Import the plugin
import { deBridgePlugin } from "@elizaos/plugin-debridge";

// Add to agent runtime
const runtime = new AgentRuntime({
  // ...other config
  plugins: [deBridgePlugin]
});

// Trigger a cross-chain swap
await runtime.processAction("CROSS_CHAIN_SWAP", {
  content: { text: "Swap 100 USDC from Ethereum to Solana" },
  userId: "user123",
  roomId: "room456"
});

Creating a Limit Order

await runtime.processAction("LIMIT_ORDER", {
  content: { text: "Create a limit order to swap 1000 USDC on Polygon and get at least 0.33 ETH on Ethereum" },
  userId: "user123",
  roomId: "room456"
});

Using Hooks for Complex Operations

await runtime.processAction("EXECUTE_DEBRIDGE_HOOK", {
  content: { text: "Swap 500 USDC from Ethereum to Arbitrum and automatically stake it on Aave" },
  userId: "user123",
  roomId: "room456"
});

Agent-to-Agent Payments

await runtime.processAction("AGENT_TO_AGENT_PAYMENT", {
  content: { text: "Pay 50 USDC to TradingAgent on Polygon" },
  userId: "user123",
  roomId: "room456"
});

Configuration

Configuration is managed through the agent's character file:

{
  "name": "CrossChainAgent",
  "plugins": ["debridge-plugin"],
  "settings": {
    "secrets": {
      "ETH_PRIVATE_KEY": "your-private-key",
      "SOLANA_PRIVATE_KEY": "your-solana-private-key",
      "ETH_RPC_URL": "https://mainnet.infura.io/v3/your-api-key",
      "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
      "POLYGON_RPC_URL": "https://polygon-rpc.com"
    }
  }
}

Required Environment Variables

For full functionality, set up the following environment variables or add them to your character's settings:

Variable	Description	Required
ETH_PRIVATE_KEY	Ethereum private key	Yes, for ETH chains
SOLANA_PRIVATE_KEY	Solana private key	Yes, for Solana
ETH_RPC_URL	Ethereum RPC endpoint	Yes, for Ethereum
SOLANA_RPC_URL	Solana RPC endpoint	Yes, for Solana
POLYGON_RPC_URL	Polygon RPC endpoint	For Polygon
ARBITRUM_RPC_URL	Arbitrum RPC endpoint	For Arbitrum
BNBCHAIN_RPC_URL	BNB Chain RPC endpoint	For BNB Chain

API Reference

Actions

Action	Description	Parameters
CROSS_CHAIN_SWAP	Execute a basic cross-chain swap	sourceChain, destChain, tokenIn, tokenOut, amount, recipient
LIMIT_ORDER	Create a limit order with minimum output	sourceChain, destChain, tokenIn, tokenOut, amountIn, minAmountOut, recipient
EXECUTE_DEBRIDGE_HOOK	Execute a transaction with a hook	sourceChain, destChain, tokenIn, tokenOut, amount, recipient, hookType, hookParams
AGENT_TO_AGENT_PAYMENT	Transfer tokens between agents	sourceChain, destChain, tokenSymbol, amount, recipientAgent
CANCEL_ORDER	Cancel an active order	orderId

Evaluators

Evaluator	Description
TRANSACTION_EVALUATOR	Extracts cross-chain transaction intent from messages
ORDER_STATUS_EVALUATOR	Tracks and updates order status information

Providers

Provider	Description
deBridgeStatusProvider	Provides information about active cross-chain transactions

Services

Service	Description
BlockchainService	Manages blockchain connections and interactions
DeBridgeMonitorService	Monitors transaction status and updates

Memory Integration

The plugin integrates with Eliza's memory system for complete transaction lifecycle management:

1. Transaction Records: Stored under the "transactions" type
2. Error Tracking: Stored under the "errors" type
3. Transaction Intent: Extracted and stored via evaluators
4. Status Updates: Tracked through memory updates

Troubleshooting

Common Issues

1. Transaction Stuck Pending

   • Verify blockchain RPC endpoints are operational
   • Check if transaction meets minimum requirements (e.g., gas, fees)
   • Confirm blockchain networks are not congested

2. Order Creation Fails

   • Verify private keys are correctly configured
   • Check token approval settings
   • Ensure sufficient balance for fees

3. Hook Execution Errors

   • Validate hook data format is correct
   • Verify hook parameters match destination chain requirements
   • Check for compatibility with target contracts

Diagnostic Tools

The plugin provides several diagnostic capabilities:

// Check service initialization
const blockchainService = runtime.getService<BlockchainService>(ServiceType.BLOCKCHAIN);
console.log(blockchainService.isInitialized());

// View active transactions
const transactions = await runtime.messageManager.getMemories({
  roomId: "room456",
  unique: true,
  tableName: "transactions"
});
console.log(transactions);

// Check order status
const orderId = "0x1234abcd";
const status = await blockchainService.checkOrderStatus("ethereum", orderId);
console.log(status);

Security Considerations

1. Private Key Management

   • Store private keys securely in environment variables or encrypted storage
   • Never expose keys in logs or client-side code
   • Consider using key management services for production

2. Transaction Validation

   • Always validate transaction parameters before execution
   • Set appropriate limits for transaction amounts
   • Verify recipient addresses carefully

3. Chain Selection

   • Validate that chains are supported before initiating transactions
   • Check for chain-specific requirements or limitations
   • Be aware of finality differences between chains

Integration with dePort

The plugin can be extended to work with dePort for enhanced cross-chain liquidity:

import { dePortPlugin } from "@elizaos/plugin-deport";

const runtime = new AgentRuntime({
  // ...other config
  plugins: [deBridgePlugin, dePortPlugin]
});

Future Enhancements

1. Enhanced Chain Support

   • Adding support for additional chains as deBridge expands
   • Optimized chain-specific transaction handling
   • Improved cross-chain rate calculation

2. Advanced Hook Templates

   • Pre-built hooks for common DeFi operations
   • User-defined hook templates
   • Multi-step transaction hooks

3. Risk Management

   • Transaction simulation before execution
   • Gas estimation improvements
   • Slippage protection mechanisms

4. Integration Enhancements

   • Direct integration with dePort API
   • Support for cross-chain NFT operations
   • Integration with additional protocols

5. Advanced UX

   • Transaction visualization components
   • Cross-chain portfolio tracking
   • Enhanced transaction history management

Contributing

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

Credits

Special thanks to:

• The Story Protocol to (open a Hackthon)[https://x.com/StoryProtocol/status/1894054655325319484]
• The deBridge team for their protocol and documentation
• The Eliza Core development team
• The Eliza community for their contributions and feedback

License

MIT