The Virtual Machine (VM) is a core component of the EigenLayer-AVS task engine responsible for loading, compiling, and executing user-defined task workflows. It serves as the execution environment for all task nodes, managing state between steps and orchestrating the flow of data through the task graph.

This document explains the design, architecture, and functionality of the VM, including how it compiles task graphs, executes different node types, and manages execution state. For information about the specific node processors the VM uses, refer to REST API Processor, Contract Interaction Processors, JavaScript Processor, and Branch and Flow Control.

Architecture#

The VM is designed as a stateful executor that processes a directed acyclic graph (DAG) of task nodes. It maintains an internal state during execution, manages variables that can be used between nodes, and applies a compilation step to create an execution plan before running.

Sources:

• core/taskengine/vm.go27-156

VM Lifecycle#

The VM follows a well-defined lifecycle as it processes a task:

Sources:

• core/taskengine/vm.go29-35
• core/taskengine/vm.go143-170
• core/taskengine/vm.go410-423

Task Compilation#

Before executing a task, the VM compiles it into an execution plan. This process:

1. Analyzes all task edges (connections between nodes)
2. Creates a map of execution steps
3. Identifies the entrypoint node (connected to the trigger)
4. Sets up the execution flow based on edge connections

Sources:

• core/taskengine/vm.go367-407

The compilation process handles special cases such as branch conditions (e.g., branch1.a1) and ensures that the execution flow is properly established before running. If compilation fails (for example, if no valid entrypoint is found), the VM will not proceed to execution.

Task Execution#

Once compiled, the VM executes the task by following these steps:

1. Start from the entrypoint
2. Execute each node using the appropriate processor
3. Follow the execution plan to determine the next node
4. Collect execution logs and manage variables between steps
5. Handle any errors that occur during execution

Sources:

• core/taskengine/vm.go410-450
• core/taskengine/vm.go453-485

Node Processors#

The VM uses specialized processors to handle different types of task nodes:

Processor Type	Function	Purpose
REST API	runRestApi	Executes HTTP requests to external APIs
GraphQL	runGraphQL	Performs GraphQL queries to external services
Contract Read	runContractRead	Reads data from Ethereum smart contracts
Contract Write	runContractWrite	Writes data to Ethereum smart contracts
Custom Code	runCustomCode	Executes custom JavaScript code
Branch	runBranch	Evaluates conditions and directs flow

Each processor:

1. Takes the node configuration as input
2. Performs its specific operation
3. Collects input variables used
4. Generates an execution log
5. Sets output variables for use by subsequent nodes

Sources:

• core/taskengine/vm.go487-611

Variable Management#

The VM manages a variables context that enables data to flow between nodes. There are three primary sources of variables:

1. Trigger data (event information that triggered the task)
2. Node output variables (results from executed nodes)
3. Configuration variables (secrets and user-defined constants)

A key feature is the preprocessText method, which allows dynamic text substitution using JavaScript expressions within {{ }} delimiters.

Sources:

• core/taskengine/vm.go612-695
• core/taskengine/vm.go696-722
• core/taskengine/vm.go178-204

The preprocessor allows for powerful templating capabilities, enabling tasks to dynamically reference data from previous steps, trigger information, or configuration variables.

Integration with Task Executor#

The VM is used by the TaskExecutor component, which:

1. Retrieves task definitions from storage
2. Creates a VM instance for the task
3. Initializes the VM with trigger data
4. Compiles and runs the task
5. Stores execution results

Sources:

• core/taskengine/executor.go72-175

Example Virtual Machine Execution#

To illustrate the VM in action, let's examine a simplified task execution:

The VM plays a critical role in this execution by:

1. Parsing the trigger data (contract event)
2. Making it available to the branch node for condition evaluation
3. Determining the correct execution path
4. Executing each node in sequence
5. Managing data between nodes (e.g., passing REST API response to contract write)
6. Recording the execution for auditing purposes

Sources:

• core/taskengine/vm_test.go236-369
• core/taskengine/vm_test.go393-476

Preprocessing and Template Functions#

The VM includes a powerful text preprocessing system that allows dynamic content generation in node configurations. This system:

1. Parses templates with {{ expression }} syntax
2. Evaluates JavaScript expressions within templates
3. Substitutes the results into the text
4. Provides access to variables, mathematical operations, and string manipulation

This preprocessor is used extensively throughout the task system to allow dynamic configuration, such as:

• Including authentication keys in API requests
• Adding dynamic data to notification messages
• Building parameterized contract calls

Sources:

• core/taskengine/vm.go612-695
• core/taskengine/vm_test.go701-885

Error Handling#

The VM includes robust error handling that:

1. Captures errors during node execution
2. Records them in execution logs
3. Terminates execution when necessary
4. Returns detailed error information to callers
5. Handles compilation errors separately from runtime errors

This error handling ensures that issues are properly reported and that task execution is reliable, even with external dependencies.

Sources:

• core/taskengine/vm.go432-436
• core/taskengine/executor.go108-114
• core/taskengine/executor.go142-144

Conclusion#

The Virtual Machine is a central component of the EigenLayer-AVS task execution system, providing a flexible and powerful framework for running complex task workflows. By managing state, handling different node types, and providing variable context between steps, the VM enables the creation of sophisticated automation workflows that can interact with both on-chain and off-chain systems.

Feature this wiki to auto refresh weekly