Contract Interaction Processors

Documentation for Contract Interaction Processors in the EigenLayer-AVS system.

Purpose and Scope#

Contract Interaction Processors enable EigenLayer-AVS tasks to interact with Ethereum smart contracts. They provide the capability to both read state from contracts and execute state-changing transactions. These processors are critical components of the Task Engine's Virtual Machine (VM) that allow automated workflows to integrate with on-chain systems.

This page documents two specific processors:

  • Contract Read Processor - For querying contract state without modifying the blockchain
  • Contract Write Processor - For executing transactions that modify contract state

For information about the Task Engine's Virtual Machine architecture, see Virtual Machine. For information about other processors such as REST API or JavaScript, see their respective pages (REST API Processor and JavaScript Processor).

Architecture Overview#

Contract Interaction Processors are specialized components within the Task Engine's Virtual Machine that handle blockchain-specific operations. They translate task node definitions into Ethereum contract interactions and process the results.

Sources:

Contract Read Processor#

The Contract Read Processor allows tasks to query data from smart contracts without modifying state. It processes read-only calls to Ethereum contracts and converts the responses to a format usable within task execution flows.

Implementation Details#

Sources:

Configuration and Data Format#

Contract Read Processor requires the following information in the task node definition:

ParameterDescription
ContractAddressEthereum address of the contract to call
CallDataABI-encoded function call data in hex format
ContractABIJSON ABI definition for the function being called

The processor returns the decoded data in a structured format that maintains the original Solidity types but converted to strings for large numbers to preserve precision.

Example Node Structure#

ContractReadNode {
    ContractAddress: "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
    CallData: "0x70a08231000000000000000000000000ce289bb9fb0a9591317981223cbe33d5dc42268d",
    ContractAbi: "[{\"inputs\":[{\"internalType\":\"address\",\"name\":\"account\",\"type\":\"address\"}],\"name\":\"balanceOf\",\"outputs\":[{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"}]"
}

Sources:

Contract Write Processor#

The Contract Write Processor executes state-changing transactions on Ethereum contracts. It uses Account Abstraction (ERC-4337) to manage transactions through smart contract wallets, enabling features like batched transactions and sponsored transactions.

Implementation Details#

The ContractWriteProcessor is defined in core/taskengine/vm_runner_contract_write.go21-39 and includes dependencies on the Ethereum client and smart wallet configuration.

Sources:

Execution Flow#

  1. The processor receives a contract address and calldata
  2. It preprocesses any template variables (e.g., {{variable}})
  3. It packages the data into an ERC-4337 UserOperation
  4. The UserOperation is sent to a bundler
  5. The processor monitors for transaction confirmation
  6. Transaction receipt and logs are returned to the task engine

Sources:

Account Abstraction Integration#

The Contract Write Processor uses ERC-4337 Account Abstraction to execute transactions, which offers several advantages:

  • Smart contract wallets instead of EOAs (Externally Owned Accounts)
  • Meta-transactions for improved UX
  • Transaction sponsorship through paymasters
  • Batched transactions for efficiency

The processor handles UserOperation creation, bundling, submission, and receipt tracking. It uses the preset package from pkg/erc4337/preset to simplify UserOp management.

Sources:

Transaction Output Data#

The processor provides detailed transaction information in its output:

CategoryFields
UserOperationSender, Nonce, InitCode, CallData, GasLimits, Fees, PaymasterData, Signature
Transaction ReceiptHash, BlockInfo, Addresses, Gas Used, Status, Logs, etc.

This data is stored in the task variables and can be used by subsequent nodes in the task flow.

Sources:

Templating and Variable Processing#

Both contract processors support templating within their input parameters. This allows dynamic values to be inserted at execution time:

ContractAddress: "0x{{contractAddress}}"
CallData: "0x70a08231000000000000000000000000{{userAddress}}"

The processors use the VM's preprocessing capabilities to substitute these variables with actual values from the task's execution context.

Sources:

Error Handling#

Contract interactions can fail for various reasons (insufficient gas, reverted transactions, network issues). The processors handle these errors and provide detailed information in the execution step:

  • Success flag indicates if the operation completed without errors
  • Error field contains detailed error information
  • Log field contains execution details useful for debugging
  • Transaction receipts include status codes and gas information

Sources:

Integration with Task Flow#

Contract processors store their results in the VM's variable system, making the data available to subsequent nodes in the task graph:

r.SetOutputVarForStep(stepID, map[string]any{
    "userOp":    outputData.ContractWrite.UserOp,
    "txReceipt": outputData.ContractWrite.TxReceipt,
})

This allows complex workflows that combine contract interactions with other processors like JavaScript, REST API calls, or branching logic.

Sources:

Feature this wiki to auto refresh weekly

Try DeepWiki on your private codebase with Devin