Trigger Engines

Documentation for Trigger Engines in the EigenLayer-AVS system.

Overview#

Trigger Engines are a critical component of the EigenLayer-AVS platform's automation capabilities. They enable operators to monitor various sources (blockchain events, blocks, and time intervals) to determine when tasks should be executed. When a trigger condition is met, the operator notifies the Aggregator, which then initiates task execution.

This page documents the different trigger mechanisms implemented in the system, their internal architecture, and how they integrate with the Operator subsystem. For information about how triggers are defined in the Task Model, see Task Model.

Sources:

Trigger Engine Architecture#

The Trigger Engine system consists of a base CommonTrigger structure that provides shared functionality for all trigger types, with specialized implementations for different trigger sources (events, blocks, and time intervals).

Sources:

Trigger Integration in System Flow#

This diagram illustrates how triggers initiate task execution in the EigenLayer-AVS system. When a trigger condition is met, the corresponding trigger engine notifies the operator, which then reports to the aggregator to execute the task.

Sources:

Common Trigger Structure#

All trigger types extend a common base structure that provides shared functionality:

The CommonTrigger structure provides:

  • Ethereum client connections for both HTTP and WebSocket RPC
  • Error handling and reconnection logic
  • Logging capabilities
  • Shutdown signaling
  • Progress tracking

Each specific trigger type embeds this common structure and implements its own monitoring and evaluation logic.

Sources:

Trigger Types#

The EigenLayer-AVS system supports three main trigger types:

Trigger TypeDescriptionMonitoring SourceMarker Type
Event TriggerExecutes tasks when specific blockchain events occurEthereum event logsEventMark (BlockNumber, LogIndex, TxHash)
Block TriggerExecutes tasks on specific block intervalsEthereum block headersBlock Number (int64)
Time TriggerExecutes tasks at specific time intervalsSystem clockTimestamp (time.Time)

Each trigger type monitors different sources using specialized logic but follows a similar pattern of subscribing to data sources, evaluating conditions, and notifying when triggers occur.

Sources:

Event Trigger Engine#

The Event Trigger Engine monitors blockchain event logs and executes tasks when specified conditions are met.

Structure and Components#

The Event Trigger Engine consists of:

  1. A collection of checks (task triggers) stored in a thread-safe map
  2. A WebSocket connection to an Ethereum node
  3. A subscription to filtered event logs
  4. Evaluation logic for both simple matchers and JavaScript expressions
  5. A channel to send trigger notifications when conditions are met

Sources:

Event Trigger Conditions#

Event triggers can be defined using two methods:

  1. Matcher-based conditions: Simple conditions that match specific event properties:

    • topics: Match event topics (e.g., event signatures and indexed parameters)
    • address: Match the contract address that emitted the event

  2. JavaScript expressions: Advanced conditions using a JavaScript expression to evaluate event data:

    • Access to event data (address, topics, data, tx_hash)
    • Support for string operations (substring, toLowerCase, includes)
    • Access to external data through built-in macros (e.g., chainlinkPrice)

When a blockchain event occurs, the Event Trigger Engine evaluates all registered checks against the event and notifies when conditions are met.

Sources:

Event Evaluation Process#

When evaluating an event against a trigger condition, the following process occurs:

  1. If the check has Matcher conditions:

    • Evaluate each matcher against the event properties
    • For topic matchers, compare specified topics with event topics
    • For address matchers, compare the contract address

  2. If the check has a JavaScript expression:

    • Initialize a JavaScript VM with the event data
    • Run the expression and ensure it returns a boolean
    • Use the result to determine if the trigger condition is met

  3. If the condition is met, send a notification with the task ID and event details

Sources:

Block Trigger Engine#

The Block Trigger Engine monitors blockchain blocks and executes tasks at specified block intervals.

Structure and Components#

The Block Trigger Engine consists of:

  1. A schedule mapping block intervals to tasks
  2. A WebSocket connection to an Ethereum node
  3. A subscription to new block headers
  4. Logic to check if a block number is divisible by the specified interval
  5. A channel to send trigger notifications when intervals are reached

Sources:

Block Trigger Process#

Block triggers are simpler than event triggers and operate based on block number intervals:

  1. When a task with a block trigger is registered, it's added to a schedule map with its block interval

  2. The system subscribes to new block headers from the Ethereum network

  3. For each new block:

    • Check each registered interval to see if the block number is divisible by the interval
    • If divisible, trigger all tasks registered for that interval
    • Send notifications with the task ID and block number

This enables tasks to run periodically based on blockchain progression rather than wall-clock time.

Sources:

Error Handling and Reconnection#

All trigger engines include error handling and reconnection logic for RPC connections:

  1. Monitor subscription error channel
  2. If an error occurs, log the error and unsubscribe
  3. Close the WebSocket connection
  4. Attempt to reconnect using exponential backoff
  5. Re-establish subscriptions once reconnected

This ensures resilience against temporary RPC failures and network issues.

Sources:

Performance Considerations#

The trigger engines include several optimizations to ensure efficient operation:

  1. Topic filtering: Event triggers use whitelisted topics to reduce the number of events processed
  2. Thread safety: Concurrent access to check collections is managed using sync.Map and mutexes
  3. Efficient evaluation: Block triggers use modulo arithmetic to quickly determine if a block matches an interval
  4. Performance metrics: Logging includes duration metrics for check evaluations

Additionally, the system logs metrics about the number of checks processed and their processing rate, which helps identify performance bottlenecks.

Sources:

Integration with Operator System#

Trigger engines are initialized and managed by the Operator component:

  1. The Operator creates and initializes each trigger engine during startup
  2. When the Operator receives task definitions from the Aggregator, it registers them with the appropriate trigger engine
  3. Each trigger engine runs in its own goroutine, monitoring its respective sources
  4. When triggers occur, notifications are sent to the Operator via trigger channels
  5. The Operator then notifies the Aggregator to execute the triggered task

This separation of concerns allows each trigger engine to focus on its specific monitoring logic while the Operator handles coordination with the broader system.

Sources:

Summary#

The Trigger Engines in EigenLayer-AVS provide a flexible and extensible system for task automation based on blockchain events, blocks, and time intervals. Key features include:

  • Support for multiple trigger types (event, block, time)
  • Simple matcher-based conditions for common use cases
  • Advanced JavaScript expressions for complex conditions
  • Resilient error handling and reconnection logic
  • Performance optimizations for efficient operation

These engines enable sophisticated automation workflows that respond to on-chain events and conditions, forming a core part of the EigenLayer-AVS automation platform.

Feature this wiki to auto refresh weekly

Try DeepWiki on your private codebase with Devin