System Architecture
This document provides a detailed explanation of the EigenLayer-AVS system architecture and the relationships between components.
This document provides a detailed explanation of the EigenLayer-AVS system architecture, including the relationships between major components, data flow patterns, and execution models. For information about smart contract integration specifically, see Smart Contract Integration.
Overview#
EigenLayer-AVS is a decentralized task automation platform built on Ethereum and integrated with EigenLayer for security. The system enables the creation and execution of automated tasks triggered by blockchain events, time schedules, or block intervals.
Sources:
Core Components#
The system consists of three main components:
| Component | Description | Key Responsibilities |
|---|---|---|
| Aggregator | Central service that coordinates operators, manages tasks, and communicates with clients via gRPC and HTTP | Task management, operator coordination, data storage, authentication |
| Operators | Distributed nodes that monitor blockchain events, blocks, and time triggers, then report to aggregator when tasks should run | Event monitoring, trigger detection, task execution |
| Task Engine | Processing system that executes task graphs with various node types including contract interactions, API calls, and more | Task compilation, VM execution, external system integration |
Sources:
Aggregator Architecture#
The Aggregator acts as the central hub for the entire system, providing interfaces for clients and coordinating the operator network.
Sources:
RPC Server#
The RPC Server implements the gRPC interface defined in protobuf/avs.proto providing methods for task management, execution tracking, and operator coordination. Key services include:
- Task Management: CreateTask, ListTasks, GetTask, DeleteTask
- Task Execution: TriggerTask, GetExecution, GetExecutionStatus
- Smart Account Operations: GetNonce, GetWallet, ListWallets
- Secret Management: CreateSecret, UpdateSecret, ListSecrets, DeleteSecret
- Authentication: GetKey for API key generation
Sources:
Operator Pool#
The Operator Pool maintains connections with registered operators, tracks their status, and distributes tasks and trigger monitoring duties. It also verifies that operators are properly registered with the EigenLayer AVS contracts.
Task Engine System#
The Task Engine compiles and executes task graphs, managing the Virtual Machine that processes individual task nodes.
Sources:
Task Model#
Tasks in the system are represented as directed graphs of nodes (operations) connected by edges (flow control). Each node performs a specific operation, and edges define the execution flow between nodes.
Sources:
Node Types#
The system supports multiple node types for different operations:
| Node Type | Description | Use Cases |
|---|---|---|
| ETHTransferNode | Transfers native ETH to a destination address | Sending payments, distributing funds |
| ContractWriteNode | Executes a state-changing contract call | Contract interactions, token transfers |
| ContractReadNode | Reads data from a contract without changing state | Balance checks, contract state queries |
| GraphQLQueryNode | Makes a GraphQL API query | Fetching data from indexers, subgraphs |
| RestAPINode | Makes HTTP requests to REST APIs | Interacting with external web services |
| BranchNode | Conditional branching based on expressions | Workflow control, decision making |
| FilterNode | Filters arrays based on expressions | Data processing, selection |
| CustomCodeNode | Executes custom JavaScript code | Complex transformations, custom logic |
Sources:
Trigger Types#
Tasks can be triggered through various mechanisms:
| Trigger Type | Description | Configuration |
|---|---|---|
| Manual | User-initiated execution | No additional configuration |
| FixedTime | Execution at specific timestamps | List of epoch timestamps |
| Cron | Scheduled execution using cron syntax | Cron expression (e.g., "0 */12 * * *") |
| Block | Execution at specific block intervals | Block interval (e.g., every 100 blocks) |
| Event | Execution when matching contract events occur | Topic filters, address filters |
Sources:
Task Execution Flow#
The following sequence diagram illustrates how tasks flow through the system from creation to execution:
Sources:
Operator System#
Operators are distributed nodes that monitor for trigger conditions and report to the aggregator when tasks should be executed.
Sources:
Operator Registration#
Operators must register with the EigenLayer AVS contracts before connecting to the aggregator. This involves:
- Generating BLS keys for authentication
- Registering with the Registry Coordinator contract
- Staking tokens (directly or delegated) with EigenLayer
- Declaring aliases in the AP Config contract
- Connecting to the aggregator with proper authentication
Sources:
Storage System#
The system uses BadgerDB, an embedded key-value database, for persistent storage.
The storage system maintains several key data collections:
- Tasks: Stores task definitions, including nodes, edges, and triggers
- Executions: Records task execution history, including step-by-step results
- Wallets: Manages smart wallet addresses for task execution
- Secrets: Securely stores secrets used in task definitions
Deployment Options#
The system can be deployed in several configurations:
-
Aggregator Service: Typically managed by the Ava Protocol team, accessible at:
- Holesky Testnet:
aggregator-holesky.avaprotocol.org:2206 - Mainnet:
aggregator.avaprotocol.org:2206
- Holesky Testnet:
-
Operators: Can be run by the community or by the Ava Protocol team:
- Testnet Operator:
0x997e5d40a32c44a3d93e59fc55c4fd20b7d2d49d - Mainnet Operator:
0xc6B87cc9e85b07365b6aBEfff061F237F7cf7Dc3
- Testnet Operator:
Sources:
Security Model#
The security of the system is based on several mechanisms:
- EigenLayer Staking: Operators stake tokens with EigenLayer, creating economic security through slashing
- BLS Signatures: Operators authenticate using BLS signatures
- API Key Authentication: Clients authenticate using API keys generated from cryptographic signatures
- Quorum-based Consensus: Multiple operators must agree on trigger conditions
Sources:
Conclusion#
The EigenLayer-AVS architecture provides a robust platform for decentralized task automation with strong security guarantees through EigenLayer integration. By separating the system into distinct components (Aggregator, Operators, Task Engine), it achieves scalability and resilience while maintaining coordination through the centralized aggregator service.
For more information about the smart contract integration aspects of the system, see the Smart Contract Integration page.
Feature this wiki to auto refresh weekly
Try DeepWiki on your private codebase with Devin