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:

• aggregator/aggregator.go71-104
• aggregator/rpc_server.go29-44

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:

• aggregator/aggregator.go201-293

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:

• aggregator/rpc_server.go29-44
• protobuf/avs_grpc.pb.go246-290

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:

• protobuf/avs_grpc.pb.go22-65

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:

• aggregator/rpc_server.go353-375

Authentication System#

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

Sources:

• aggregator/auth.go20-187

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:

• core/taskengine/doc.go1-36
• core/taskengine/schema.go12-180

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 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:

• core/taskengine/schema.go97-110

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:

• aggregator/rpc_server.go353-367

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:

• aggregator/aggregator.go295-334

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