PRNG AVS Example

This repository demonstrates the advanced features of the othentic-cli. It's recommended to set up the simple-price-oracle-avs first before diving into more advanced features.

Table of Contents

1. Overview
2. Project Structure
3. Architecture
4. Prerequisites
5. Installation
6. Usage

Overview

This repository contains:

• Leader Election Algorithm: Implements a leader election algorithm to allocate task among multiple Performer nodes. Learn more about different task allocation mechanisms in the official documentation.

• AVS Logic Hook: Hooks enable developers to integrate custom logic seamlessly. The pseudo-random number generator (PRNG) smart contract utilizes this feature to generate a pseudo-random number after task execution. Learn more about AVS Logic Hook.

• Custom Task triggers: The Othentic framework provides flexibility to define custom logic for triggering tasks. In this example, Performer nodes monitor new blocks and execute a task every 20 blocks. Learn more about Triggering a task

Project Structure

📂 PRNG-avs-example
├── 📂 Execution_Service  # Implements task execution and leader election logic
├── 📂 Validation_Service # Implements task validation logic
├── 📂 grafana            # Grafana alerting and monitoring configuration
├── 📂 contracts # PRNG contract implementation using Hooks and deployment scripts
├── docker-compose.yml # # Docker setup for Operator Nodes (Performer, Attesters, Aggregator), Execution Service, Validation Service, and monitoring tools
└── README.md          # Project documentation

Architecture

Task Triggers:

This repository contains two methods to trigger a Task:

1. New Block Production Trigger: A task is automatically triggered every time a new block is produced on the blockchain.

2. Custom Event-Based Trigger: A task is triggered when a specific custom event is emitted by a smart contract. When the event occurs, the log details (such as transaction hash, block number, and event data) are captured. A corresponding task is executed based on the event data.

The Performer node executes tasks using the Task Execution Service and sends the results to the p2p network.

Attester Nodes validate task execution through the Validation Service. Based on the Validation Service's response, attesters sign the tasks. In this AVS:

Leader election logic:

In this repository we have implemented 3 different leader election algorithms.

1. Round Robin: The task performer is selected in a round-robin manner by computing blockNumber % numOfOperators, ensuring each operator performs tasks in a fair and predictable order.
2. Random selection: A random operator is chosen from the list of active operators for each block.
3. Stake weighted random selection: This algorithm selects a leader based on the voting power of each operator. The idea is to give operators with higher stakes a greater chance of being selected. The probability of selection is proportional to the operator's stake, meaning operators with larger stakes are more likely to be chosen, but all operators still have a chance.

The Operators details are retrieved using the getActiveOperatorsDetails method in the attestation center contract.

Task Execution logic:

Once an operator is selected to perform a task, they generate a proof (a combination of block number and timestamp) and sign it with their private key. This proof is sent to the attester node to confirm that the task was performed.

Validation Service logic:

The server exposes an endpoint /task/validate for validating the task performance. This endpoint checks if the provided task proof corresponds to the correct performer for the specified block number.

Task Flow

1. The Performer nodes listens for new blocks.
2. Every 20th block selects a task performer.
3. If the current block is the performer's turn, the task is executed, and a proof is generated.
4. The proof is sent to the attester node.
5. The /task/validate endpoint is called internally, to check if the task was performed by the correct operator.

Prerequisites

• Node.js (v 22.6.0 )
• Foundry
• Yarn
• Docker

Usage

1. Create a .env file and include the deployed contract addresses and private keys for the operators. If you are unfamiliar with AVS, Checkout the Quickstart guide.

2. Install Othentic CLI:

npm i -g @othentic/cli
npm i -g @othentic/node

3. Deploy the PRNG Contract: To use hooks, deploy an instance of the PRNG contract by navigating to the contracts directory. Note that deploying this contract is optional; the AVS can run without it. This step is primarily for showcasing the use of hooks.

cd contracts/
forge install
forge script PRNGDeploy --fork-url $L2_RPC --private-key $PRIVATE_KEY --broadcast -vvvv --verify --etherscan-api-key $L2_ETHERSCAN_API_KEY --chain $L2_CHAIN --sig="run(address)" $ATTESTATION_CENTER_ADDRESS

4. Once the contract is deployed, return to the root of the repository and start the Docker Compose configuration:

docker-compose up --build

Note

Building the images might take a few minutes

Updating the Othentic node version

To update the othentic-cli inside the docker images to the latest version, rebuild the images using the following command:

docker-compose build --no-cache

Next

Modify the different configurations, write your own leader election algorithm, and run the AVS.

Happy Building! 🚀