AVS Operator

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. Install EigenLayer CLI: Follow EigenLayer’s Installation Guide to set up the EigenLayer CLI on your machine.

2. 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. Upload metadata.json to a Public URL: You can use services like GitHub Gist to host the metadata file. Once hosted, update the operator.yaml file with this public metadata_url.

2. 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.

3. 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.

2. Run Operator Registration Script: Follow alt-research’s guide to register using register_operator.sh.

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

Link to the code: https://github.com/HemeraProtocol/hemera-indexer/pull/212/files#diff-3527683c538c929e553ef048358b8de50f5cecd7144a62d38e890de0f7573d4d

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:

• Discord: Join Hemera’s Community

• Email: [e-mail]