Hemera Doc
  • 👋Welcome
    • Introduction
    • Quick Start
    • Account Centric Indexing Protocol
      • What is Account-Centric Indexing?
      • Why "account-centric" indexing?
      • The advantages of Account-Centric Indexing
      • What's next for account-centric indexing?
      • Why create a new protocol here?
      • The Hemera Network
        • Network Roles
        • Indexers
        • Validators
        • Proprietary models & knowledge
        • Proprietary data and labels
        • Smart Contracts
        • Key roadmap items
        • Supported blockchains
      • Example Hemera use cases
        • SocialScan Explorers
        • Anti-sybil UML algorithm
        • Ethereum long term DA
        • EVM chain history preservation
        • Ecosystem AI Agents
        • User-defined AI Agents
  • 👩‍💻Developer Resources
    • Smart Contract Developers
    • EVM-compatible chains
      • Blockchain explorers
      • SocialScan explorer API doc
      • Ecosystem AI Agents
    • Dapp developers
    • User-defined Agent creators
    • AVS Operator
  • 🖥️Hemera Indexer
    • Introduction
    • Installation
      • Prerequisites
      • Install & Run
      • Export Result
    • Configurations
    • Benchmark
    • Data Class
      • Raw Data Tables
        • Blocks
        • Transactions
        • Logs
        • Traces
      • Generated Tables
        • Contract Internal Transactions
        • ERC20 Token Transfers
        • Tokens
        • ERC20 Token Holders
        • ERC721 Token Transfers
        • ERC721 Token Holders
        • ERC1155 Token Transfers
        • ERC1155 Token Holders
        • Address Coin Balances
        • Address Token Balances
        • Address Current Token Balances
        • Daily Wallet Address Stats
        • Contracts
      • Other Tables
        • Inscriptions
        • Bridges
          • L1 to L2 Transactions
          • L2 to L1 Transactions
          • Optimistic Rollup Data Availability Batches
          • Optimistic Rollup State Batches
    • Use Cases
      • UniSwap V3
        • Data Class
        • Trigger and Function
        • Run & Query
      • ENS
        • Data Class
        • Trigger and Function
        • Run & Query
      • OpenSea
        • Data Class
        • Trigger and Function
        • Run & Query
      • Deposit to L2
        • Data Class
        • Trigger and Function
        • Run & Query
      • User Profile
  • UDFs - User Defined Functions
    • Introduction
    • Components of UDFs
    • Building User Defined Functions(UDF)
    • Testing and Running UDF
    • Troubleshooting and Support
    • Supported UDFs
    • FAQs
  • 😄About us
    • The story behind building Hemera
    • Partners & Backers
    • Partnership inquiries
    • Hemera Powered Explorers
    • Active Developer Hackathons
    • Developer Contribution
  • Documentation feedback
Powered by GitBook
On this page
  • Step-by-Step Guide to Setting Up an AVS Operator
  • 1. Key Generation and Wallet Funding
  • 2. Registering as an Operator on EigenLayer
  • 3. Joining Hemera AVS
  • 4. Configuring the Operator for Hemera AVS
  • 5. Running the AVS Operator
  • Frequently Asked Questions (FAQs)
  • Contact and Support
  1. Developer Resources

AVS Operator

PreviousUser-defined Agent creatorsNextIntroduction

Last updated 6 months ago

This documentation gives an in-depth guide for setting up, registering, configuring, and running an AVS (Actively Validating Services) Operator in the Hemera ecosystem. As an AVS Operator, your role is central to maintaining data transparency and accuracy across the Hemera Protocol. By validating and aggregating on-chain data, the AVS Operator ensures that all Hemera network participants have access to reliable, verifiable information. This essentially involves validating blocks and transactions, comparing data across multiple sources, and contributing to Hemera’s unique history transparency.

AVS Operators are critical for Hemera’s decentralized data verification structure which brings enhanced trust and security to the platform’s users and data-driven applications.


Step-by-Step Guide to Setting Up an AVS Operator

1. Key Generation and Wallet Funding

Before you can register as an AVS Operator, you need to set up your keys and wallet.

  1. Generate Keys: Create both ECDSA and BLS keypairs using the following commands:

    shellCopy codeeigenlayer operator keys create --key-type ecdsa [keyname]
    eigenlayer operator keys create --key-type bls [keyname]

    This will create an ECDSA and BLS keypair for secure, verifiable operations on EigenLayer and Hemera. Remember to back up your private keys securely. The encrypted keys are stored by default at ~/.eigenlayer/operator_keys/.

2. Registering as an Operator on EigenLayer

Note: Skip this section if you are already a registered operator on the EigenLayer testnet and mainnet. Registration is required separately for testnet and mainnet.

  1. Create Configuration Files: Use the command below to generate the necessary operator registration files (operator.yaml and metadata.json).

    shellCopy codeeigenlayer operator config create

    Follow the prompts to complete the configuration setup.

  2. Edit metadata.json: Fill in your operator’s details. This metadata will be publicly accessible and includes your operator name, website, description, and social links.

jsonCopy code{
  "name": "Example Operator",
  "website": "https://example.com/",
  "description": "Example description",
  "logo": "https://example.com/logo.png",
  "twitter": "https://twitter.com/example"
}
  1. Register Operator: To finalize registration, run:

    shellCopy codeeigenlayer operator register operator.yaml

    A success message will confirm the operator registration: ✅ Operator is registered successfully to EigenLayer.

  2. Check Registration Status: Verify the registration by checking the EigenLayer operator page or using the CLI command below:

    shellCopy codeeigenlayer operator status operator.yaml

3. Joining Hemera AVS

After registering on EigenLayer, the next step is to integrate your operator with Hemera AVS:

  1. Whitelist Registration: Contact Hemera support to add your operator address to the AVS whitelist.

4. Configuring the Operator for Hemera AVS

Edit the indexer-config-avs-holesky.yaml file, located in the configuration directory, to include the necessary details for running as an AVS operator:

  • Update the following items in the configuration file:

    • operator_ecdsa_key_file: Path to your ECDSA key file.

    • operator_bls_key_file: Path to your BLS key file.

These keys are required to sign and validate data with the Hemera AVS protocol.

5. Running the AVS Operator

You can run the AVS Operator either directly from the source code or by using Docker.

Running from Source Code

  1. Navigate to the Hemera indexer directory. Checkout this guide on how to setup hemera indexer: Installation

  2. Run the following command to start the AVS Operator, specifying the configuration file and database output details:

    shellCopy codecd hemera_indexer
    python3 hemera.py stream --provider-uri https://holesky.drpc.org --debug-provider-uri https://holesky.drpc.org -O hemera_history_transparency --output postgres --postgres-url postgresql://postgres:123456@localhost:5432/hemera_indexer --config-file ./config/indexer-config-avs-holesky.yaml

This command initializes the operator, establishing connections to RPC and data validation sources.

Running with Docker

  1. Navigate to the Docker Compose directory and update environment variables in avs.env to suit your setup.

  2. Start the AVS Operator in Docker by running:

    shellCopy codecd hemera_indexer
    cd docker-compose
    sudo docker compose -f avs-operator.yaml up

Docker is ideal for streamlined deployments and scalable operation setups.


Operator Code Walkthrough

The operator.py script facilitates data validation, transaction filtering, and event aggregation. Below is an outline of its primary components:

Key Functionalities

  1. Data Collection and Validation (_verify_logs):

    • The operator collects transaction logs from specified blocks, verifies data using both API and RPC sources, and checks block hashes and transaction counts for consistency.

    • This process ensures that transaction data aligns with Hemera’s transparency requirements, which is critical for maintaining accurate history records.

  2. Operator Registration Verification (_check_operator_is_registered):

    • Before starting, the operator checks if it is registered on EigenLayer by querying the registry coordinator contract.

    • The function returns True if the operator is registered, preventing unregistered operators from interacting with the network.

  3. Aggregation and Alert Creation (_confirm_task):

    • Upon log verification, the operator aggregates the data and creates an alert task through the aggregator client, which assists in real-time monitoring and alerting.

  4. Configuration Handling:

    • Configuration details for the RPC and API endpoints are managed through the YAML file, allowing flexible setup adjustments.


Troubleshooting

This section addresses common issues you may encounter when setting up or running the AVS Operator, with solutions and debugging tips to help you resolve them quickly.

  1. Operator Registration Failed

    • Issue: Registration attempts result in an error.

    • Solution: Double-check the configuration files (operator.yaml and metadata.json). Ensure all required fields are filled in, especially the metadata_url field pointing to a publicly accessible location.

    • Tip: Use the eigenlayer operator status operator.yaml command to verify registration status.

  2. Key File Access Error

    • Issue: The operator is unable to access the ECDSA or BLS key files.

    • Solution: Confirm that the key files are located at the paths specified in indexer-config-avs-holesky.yaml (operator_ecdsa_key_file and operator_bls_key_file). Check file permissions to ensure they are readable by the operator service.

  3. Block/Transaction Count Mismatch

    • Issue: Block or transaction counts differ between the API and RPC sources.

    • Solution: Verify the synchronization of your RPC provider. If issues persist, consult the RPC provider or consider using an alternative to ensure data consistency.

  4. Docker Container Not Starting

    • Issue: The AVS Operator Docker container fails to start.

    • Solution: Check the Docker Compose file avs-operator.yaml for any misconfiguration. Review avs.env to confirm that all environment variables are correctly set. Run docker logs <container_id> to get more details on startup errors.

  5. Aggregated Data Not Appearing in Database

    • Issue: Data does not populate in the PostgreSQL database.

    • Solution: Ensure that the postgres-url provided in the run command is accurate and that the database service is running. Double-check network connectivity and the PostgreSQL configuration.


Frequently Asked Questions (FAQs)

  1. What is the role of an AVS Operator in Hemera? An AVS Operator in Hemera is responsible for validating and aggregating on-chain data, ensuring transparency and accuracy. This helps maintain a reliable data layer that Hemera and its users can trust for decentralized applications.

  2. How do I update the operator metadata after registration? Update the metadata.json file with the new information, host it publicly, and edit the operator.yaml file to reflect the updated metadata_url. Run the following command to apply the update:

    eigenlayer operator update operator.yaml
  3. Can I run the AVS Operator on multiple machines? Yes, you can deploy the AVS Operator on multiple instances to improve redundancy and handle higher data volumes. Make sure each instance is configured with unique credentials and environment variables.

  4. How can I verify that my AVS Operator is running correctly? Use the eigenlayer operator status operator.yaml command to check the operator's registration status. Additionally, monitor logs for any errors and confirm that data is being populated in the configured database.

  5. What happens if my keys are compromised? In case of a security breach, generate new keys immediately using the EigenLayer CLI, update your configurations, and re-register if necessary. Secure backups of all private keys are strongly recommended.


Contact and Support

For additional support, join our Discord community or contact us via email:

Install EigenLayer CLI: Follow to set up the EigenLayer CLI on your machine.

Upload metadata.json to a Public URL: You can use services like to host the metadata file. Once hosted, update the operator.yaml file with this public metadata_url.

Run Operator Registration Script: Follow to register using register_operator.sh.

Link to the code:

Discord:

Email:

👩‍💻
EigenLayer’s Installation Guide
GitHub Gist
alt-research’s guide
https://github.com/HemeraProtocol/hemera-indexer/pull/212/files#diff-3527683c538c929e553ef048358b8de50f5cecd7144a62d38e890de0f7573d4d
Join Hemera’s Community
contact@thehemera.com