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:

  1. Core Aggregator - Initializes and manages all other components, connects to Ethereum nodes, and handles the system lifecycle
  2. RPC Server - Provides gRPC interfaces for clients and operators
  3. Operator Pool - Manages connections to operators and task distribution
  4. Task Engine - Processes task definitions, schedules execution, and manages task state
  5. 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:

  1. Loading configuration from a YAML file
  2. Initializing connections to Ethereum nodes
  3. Setting up the database (BadgerDB)
  4. Running any necessary migrations
  5. Starting the Task Engine
  6. Starting the RPC server for client and operator communication
  7. 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:

  1. AggregatorServer - For client applications to manage tasks and wallets
  2. NodeServer - For operators to report triggers and sync messages

Sources:

Client API Endpoints#

The RPC Server exposes the following endpoints for client applications:

CategoryEndpointsDescription
AuthenticationGetKeyExchange signature for auth token
Smart WalletGetWallet, GetNonce, ListWalletsManage smart wallet accounts
Task ManagementCreateTask, GetTask, ListTasks, TriggerTask, CancelTask, DeleteTaskCRUD operations for tasks
ExecutionListExecutions, GetExecution, GetExecutionStatus, GetExecutionCount, GetWorkflowCountMonitor task execution
SecretsCreateSecret, ListSecrets, UpdateSecret, DeleteSecretManage secrets used in tasks

Sources:

Operator API Endpoints#

For operators, the RPC Server provides endpoints for task trigger notification and synchronization:

EndpointDescription
SyncMessagesStream checks to operator for monitoring
NotifyTriggersReceive trigger notifications from operators
AckAcknowledge received messages

Sources:

Authentication System#

The Aggregator implements a robust authentication system for securing client interactions:

Sources:

The authentication flow provides:

  1. 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
  2. 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:

PrefixDescriptionExample Key
w:Wallet informationw:0xabc...:0xdef...
t:Task definitionst:a:01JG2F... (a=active)
u:User task referencesu:0xabc...:0xdef...:01JG2F...
history:Execution historyhistory:01JG2F...:01JG2G...
trigger:Execution triggerstrigger:01JG2F...:01JG2G...
secret:Secret storagesecret:_:0xabc...:_:api_key

The status code in task keys encodes the task state:

  • a: active - being checked for triggers
  • c: completed - finished execution, no longer checked
  • f: failed - execution failed, no longer checked
  • l: cancelled - cancelled by user, no longer checked
  • x: 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:

  1. Tracking operator connections
  2. Routing task triggers from operators to the Task Engine
  3. Distributing task checks to appropriate operators
  4. 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:

  1. Creation: Client creates a task definition through the RPC API
  2. Storage: Task is stored in BadgerDB with appropriate keys
  3. Distribution: Task triggers are distributed to operators for monitoring
  4. Triggering: Operators notify Aggregator when trigger conditions are met
  5. Queuing: Task Engine queues the task for execution
  6. Execution: Task Engine executes the task, calling external services as needed
  7. Result Storage: Execution results are stored in BadgerDB
  8. 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:

  1. Network settings (RPC bind address, HTTP port)
  2. Ethereum connection details (HTTP and WebSocket RPC URLs)
  3. Smart contract addresses (Registry Coordinator, Operator State Retriever)
  4. Database path and settings
  5. JWT secret for authentication
  6. 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:

  1. BLS signature aggregation for secure task responses
  2. Operator registration and staking verification
  3. Registry Coordinator for managing operators
  4. 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