Aggregator
The Aggregator is a central component in the EigenLayer-AVS system that orchestrates task execution across a network of operators.
The Aggregator is a central component in the EigenLayer-AVS system that orchestrates task execution across a network of operators. It serves as the coordination layer between client applications and the distributed operator network, managing task creation, storage, distribution, triggering, and execution. This document provides a detailed technical overview of the Aggregator's architecture, components, and operation.
For information about the Operator component that executes tasks under the Aggregator's coordination, see Operator.
Architecture Overview#
The Aggregator consists of several interconnected components working together to provide task automation services through the EigenLayer AVS ecosystem.
Sources:
The Aggregator consists of the following key components:
- Core Aggregator - Initializes and manages all other components, connects to Ethereum nodes, and handles the system lifecycle
- RPC Server - Provides gRPC interfaces for clients and operators
- Operator Pool - Manages connections to operators and task distribution
- Task Engine - Processes task definitions, schedules execution, and manages task state
- BadgerDB Storage - Persists all system data including tasks, executions, and configuration
Component Initialization and Lifecycle#
The Aggregator lifecycle follows a defined sequence of initialization and startup steps:
Sources:
The startup process includes:
- Loading configuration from a YAML file
- Initializing connections to Ethereum nodes
- Setting up the database (BadgerDB)
- Running any necessary migrations
- Starting the Task Engine
- Starting the RPC server for client and operator communication
- Starting HTTP services for telemetry and monitoring
RPC Server#
The RPC Server is the primary interface for both clients and operators to interact with the Aggregator. It implements two main service interfaces defined in Protocol Buffers:
AggregatorServer
- For client applications to manage tasks and walletsNodeServer
- For operators to report triggers and sync messages
Sources:
Client API Endpoints#
The RPC Server exposes the following endpoints for client applications:
Category | Endpoints | Description |
---|---|---|
Authentication | GetKey | Exchange signature for auth token |
Smart Wallet | GetWallet , GetNonce , ListWallets | Manage smart wallet accounts |
Task Management | CreateTask , GetTask , ListTasks , TriggerTask , CancelTask , DeleteTask | CRUD operations for tasks |
Execution | ListExecutions , GetExecution , GetExecutionStatus , GetExecutionCount , GetWorkflowCount | Monitor task execution |
Secrets | CreateSecret , ListSecrets , UpdateSecret , DeleteSecret | Manage secrets used in tasks |
Sources:
Operator API Endpoints#
For operators, the RPC Server provides endpoints for task trigger notification and synchronization:
Endpoint | Description |
---|---|
SyncMessages | Stream checks to operator for monitoring |
NotifyTriggers | Receive trigger notifications from operators |
Ack | Acknowledge received messages |
Sources:
Authentication System#
The Aggregator implements a robust authentication system for securing client interactions:
Sources:
The authentication flow provides:
-
Initial Authentication:
- Client signs a message containing its address, timestamps, and chain ID
- Server verifies the signature matches the claimed owner address
- Server issues a JWT token for subsequent requests
-
Request Authentication:
- Client includes JWT token in the "authkey" header
- Server verifies token validity and extracts user information
- Server authorizes operations based on user identity
Storage System#
The Aggregator uses BadgerDB, a high-performance key-value store, for persistent storage. The storage system follows a well-defined schema for organizing different types of data.
Sources:
The storage system uses key prefixes to organize different types of data:
Prefix | Description | Example Key |
---|---|---|
w: | Wallet information | w:0xabc...:0xdef... |
t: | Task definitions | t:a:01JG2F... (a=active) |
u: | User task references | u:0xabc...:0xdef...:01JG2F... |
history: | Execution history | history:01JG2F...:01JG2G... |
trigger: | Execution triggers | trigger:01JG2F...:01JG2G... |
secret: | Secret storage | secret:_:0xabc...:_:api_key |
The status code in task keys encodes the task state:
a
: active - being checked for triggersc
: completed - finished execution, no longer checkedf
: failed - execution failed, no longer checkedl
: cancelled - cancelled by user, no longer checkedx
: executing - currently being executed
Sources:
Operator Pool Management#
The Aggregator maintains an Operator Pool to track and manage the operators connected to the system. This component is responsible for:
- Tracking operator connections
- Routing task triggers from operators to the Task Engine
- Distributing task checks to appropriate operators
- Monitoring operator health and status
When an operator connects, it registers with the Aggregator and begins receiving task assignments. The operator then monitors for trigger conditions (events, blocks, time) and reports back to the Aggregator when conditions are met.
Sources:
Task Execution Process#
The full lifecycle of a task in the Aggregator system follows this general pattern:
- Creation: Client creates a task definition through the RPC API
- Storage: Task is stored in BadgerDB with appropriate keys
- Distribution: Task triggers are distributed to operators for monitoring
- Triggering: Operators notify Aggregator when trigger conditions are met
- Queuing: Task Engine queues the task for execution
- Execution: Task Engine executes the task, calling external services as needed
- Result Storage: Execution results are stored in BadgerDB
- Status Update: Task status is updated based on execution results
During execution, the Task Engine processes each node in the task graph, which may involve REST API calls, smart contract interactions, GraphQL queries, or JavaScript execution.
Configuration and Deployment#
The Aggregator requires configuration for:
- Network settings (RPC bind address, HTTP port)
- Ethereum connection details (HTTP and WebSocket RPC URLs)
- Smart contract addresses (Registry Coordinator, Operator State Retriever)
- Database path and settings
- JWT secret for authentication
- Logging configuration
The Aggregator is typically deployed as a standalone service that connects to Ethereum nodes and is accessible to both client applications and operators through gRPC interfaces.
Integration with EigenLayer#
The Aggregator integrates with EigenLayer through:
- BLS signature aggregation for secure task responses
- Operator registration and staking verification
- Registry Coordinator for managing operators
- AVS (Actively Validated Service) contracts
This integration ensures that operators are properly staked and registered with EigenLayer, providing security guarantees for the task execution system.
Sources:
Conclusion#
The Aggregator is the central coordination component of the EigenLayer-AVS system, managing tasks, operators, storage, and execution. It provides robust APIs for client interaction, secure authentication, and efficient task distribution. By leveraging EigenLayer's security model, it ensures reliable and trustworthy task execution across the operator network.
Feature this wiki to auto refresh weekly
Try DeepWiki on your private codebase with Devin