This page provides detailed documentation of the task data model in the EigenLayer-AVS system, including the structure of tasks, nodes, edges, and triggers. For information about task execution, see Virtual Machine.

Overview#

The Task Model defines the core data structures that represent automated workflows in the EigenLayer-AVS system. Tasks are structured as directed graphs of operations (nodes) connected by execution paths (edges), with trigger conditions that determine when tasks should execute.

Sources:

• protobuf/avs.proto405-431
• model/task.go17-19

Task Structure#

A Task represents a complete workflow definition with the following key components:

Field	Type	Description
id	string	Unique identifier (ULID format)
owner	string	Ethereum address of the task owner
smart_wallet_address	string	Smart wallet address used to execute the task
start_at	int64	Task won't be checked before this timestamp (milliseconds)
expired_at	int64	Task won't run after this timestamp (milliseconds)
name	string	Human-readable task name (limited to 255 characters)
max_execution	int64	Maximum number of times this task can run (0 = unlimited)
total_execution	int64	Number of times this task has executed
last_ran_at	int64	Timestamp of last execution (milliseconds)
status	TaskStatus	Current state of the task
trigger	TaskTrigger	Defines when the task should run
nodes	[]TaskNode	Collection of operations in the task
edges	[]TaskEdge	Connections between nodes that define execution flow

Tasks are created through the CreateTask method in the Task Engine, which validates the task structure before storing it.

Sources:

• protobuf/avs.proto405-431
• core/taskengine/engine.go288-320
• model/task.go40-90

Task Lifecycle#

Tasks transition through different states during their lifetime:

The defined task states are:

Status	Description
Active	Task is eligible to be triggered and executed
Executing	Task is currently running
Completed	Task has reached its max_execution or expiration time
Failed	Task encountered an unrecoverable error
Canceled	Task was explicitly canceled by its owner

A task is considered "runable" if it hasn't reached its maximum execution count and hasn't expired.

Sources:

• protobuf/avs.proto105-111
• model/task.go118-152

Task Nodes#

Nodes represent individual operations within a task. Each node has a specific type that determines its behavior. The TaskNode structure includes a common id and name, plus a type-specific payload.

Sources:

• protobuf/avs.proto276-299

The system supports the following node types:

External Integration Nodes#

These nodes interact with external systems:

1. ETHTransferNode: Transfers ETH to a specified destination

   • Parameters: destination address, amount

2. ContractWriteNode: Executes a write operation on a smart contract

   • Parameters: contract_address, call_data, contract_abi (optional)
   • Output: transaction hash and receipt

3. ContractReadNode: Reads data from a smart contract

   • Parameters: contract_address, call_data, contract_abi
   • Output: contract method return values

4. GraphQLQueryNode: Executes a GraphQL query

   • Parameters: url, query, variables
   • Output: GraphQL response data

5. RestAPINode: Makes HTTP requests to REST APIs

   • Parameters: url, method, headers, body
   • Output: API response data

Sources:

• protobuf/avs.proto121-192

Logic and Control Flow Nodes#

These nodes handle data processing and flow control:

1. CustomCodeNode: Executes custom JavaScript code

   • Parameters: source code
   • Output: code execution result

2. BranchNode: Implements conditional branching

   • Parameters: array of conditions with expressions
   • Output: ID of the matching condition

3. FilterNode: Filters arrays based on expressions

   • Parameters: expression, input node ID
   • Output: filtered array

4. LoopNode: Iterates over collections

   • Note: Currently not fully implemented
   • Parameters: input, iter_val, iter_key, and a runner node

Sources:

• protobuf/avs.proto194-267

Task Edges#

Edges connect nodes together to form a directed graph that defines the execution flow. Each edge has three components:

Field	Description
id	Unique identifier for the edge
source	ID of the node where the edge begins
target	ID of the node where the edge ends

The set of edges determines how data and control flow through the task. After executing a node, the system follows the edges to determine which nodes to execute next.

Sources:

• protobuf/avs.proto269-274

Task Triggers#

Triggers determine when a task should be executed. The system supports various trigger mechanisms to accommodate different use cases.

Sources:

• protobuf/avs.proto61-79

The system supports the following trigger types:

Manual Trigger#

Tasks with manual triggers are executed explicitly by calling the TriggerTask method.

Time-Based Triggers#

1. FixedTimeCondition: Triggers at specific timestamps (epochs)

2. CronCondition: Triggers based on cron-like schedules

Blockchain-Based Triggers#

1. BlockCondition: Triggers at specific block intervals

2. EventCondition: Triggers in response to on-chain events

Event triggers are particularly powerful, allowing tasks to react to blockchain events like token transfers by matching on event topics and other parameters.

Sources:

• protobuf/avs.proto15-58

Execution Model#

When a task is triggered, an execution is created to track the progress and results of the run.

Sources:

• protobuf/avs.proto302-402

The execution model includes:

• Execution: Records the overall result of a task run

  • Contains start/end timestamps, success state, and error messages
  • Includes the trigger reason and a sequence of execution steps
  • Stores output data specific to the trigger type

• Steps: Track the execution of individual nodes

  • Each step corresponds to a node in the task graph
  • Records the start/end time, success state, and any errors
  • Stores type-specific output data from the node execution
  • Tracks inputs used by the node

• TriggerReason: Provides detailed information about what triggered the task

  • For block triggers: records the block number
  • For event triggers: includes transaction hash, log index
  • For time triggers: includes the epoch timestamp

This detailed execution history enables precise tracking and debugging of task runs.

Sources:

• protobuf/avs.proto302-402
• core/taskengine/engine.go751-786

Implementation Architecture#

The Task Model is implemented through several components in the EigenLayer-AVS system:

The primary components involved in the Task Model are:

1. Task Engine - Central component that manages task creation, storage, and execution coordination

   • Implemented in core/taskengine/engine.go
   • Handles creating, triggering, listing, and managing tasks

2. Storage System - Persists tasks and executions using BadgerDB

   • Tasks are stored with various prefixes based on their status
   • Executions are linked to their parent tasks

3. Operator Network - Distributed system for monitoring triggers

   • Operators watch for time, block, and event triggers
   • When triggers are detected, operators notify the Aggregator

4. Virtual Machine - Executes task nodes based on the task graph

   • Processes each node according to its type
   • Follows edges to determine execution flow
   • Records detailed execution steps

Sources:

• core/taskengine/engine.go112-156
• core/taskengine/engine.go288-320

Task Model API#

The system provides a comprehensive API for working with tasks:

Operation	Description
CreateTask	Creates a new task with specified nodes, edges, and trigger
GetTask	Retrieves a task by its ID
ListTasks	Lists tasks based on filtering criteria
TriggerTask	Manually triggers a task execution
CancelTask	Cancels an active task
DeleteTask	Permanently removes a task
GetExecution	Retrieves execution details by task ID and execution ID
ListExecutions	Lists executions for a given task
GetExecutionStatus	Checks the status of a specific execution

These API methods are exposed through the gRPC interface provided by the Aggregator service.

Sources:

• protobuf/avs.proto662-712
• core/taskengine/engine.go571-626

Constraints and Validation#

The Task Model enforces several constraints to ensure valid task definitions:

1. Tasks must have at least one node

2. Tasks must have at least one edge

3. Tasks must include a trigger definition

4. Smart wallet addresses must be valid and owned by the task creator

5. Task IDs are generated as ULIDs (Universally Unique Lexicographically Sortable Identifiers)

Sources:

• model/task.go40-90
• core/taskengine/engine.go288-320

Feature this wiki to auto refresh weekly