Confidential AVS Example

---

Table of Contents

1. Overview
2. Project Structure
3. Architecture
4. Prerequisites
5. Installation
6. Usage
7. Service Start-up Order

---

Overview

The Simple Price Oracle AVS Example demonstrates how to deploy a minimal AVS using Othentic Stack.

Project Structure

📂 simple-price-oracle-avs-example
├── 📂 Execution_Service         # Implements Task execution logic - Express JS Backend
│   ├── 📂 config/
│   │   └── app.config.js        # An Express.js app setup with dotenv, and a task controller route for handling `/task` endpoints.
│   ├── 📂 src/
│   │   └── dal.service.js       # A module that interacts with Pinata for IPFS uploads
│   │   ├── oracle.service.js    # A utility module to fetch the current price of a cryptocurrency pair from the Binance API
│   │   ├── task.controller.js   # An Express.js router handling a `/execute` POST endpoint
│   │   ├── 📂 utils             # Defines two custom classes, CustomResponse and CustomError, for standardizing API responses
│   ├── Dockerfile               # A Dockerfile that sets up a Node.js (22.6) environment, exposes port 8080, and runs the application via index.js
|   ├── index.js                 # A Node.js server entry point that initializes the DAL service, loads the app configuration, and starts the server on the specified port
│   └── package.json             # Node.js dependencies and scripts
│
├── 📂 Validation_Service         # Implements task validation logic - Express JS Backend
│   ├── 📂 config/
│   │   └── app.config.js         # An Express.js app setup with a task controller route for handling `/task` endpoints.
│   ├── 📂 src/
│   │   └── dal.service.js        # A module that interacts with Pinata for IPFS uploads
│   │   ├── oracle.service.js     # A utility module to fetch the current price of a cryptocurrency pair from the Binance API
│   │   ├── task.controller.js    # An Express.js router handling a `/validate` POST endpoint
│   │   ├── validator.service.js  # A validation module that checks if a task result from IPFS matches the ETH/USDT price within a 5% margin.
│   │   ├── 📂 utils              # Defines two custom classes, CustomResponse and CustomError, for standardizing API responses.
│   ├── Dockerfile                # A Dockerfile that sets up a Node.js (22.6) environment, exposes port 8080, and runs the application via index.js.
|   ├── index.js                  # A Node.js server entry point that initializes the DAL service, loads the app configuration, and starts the server on the specified port.
│   └── package.json              # Node.js dependencies and scripts
│
├── 📂 grafana                    # Grafana monitoring configuration
├── docker-compose.yml            # Docker setup for Operator Nodes (Performer, Attesters, Aggregator), Execution Service, Validation Service, and monitoring tools
├── .env.example                  # An example .env file containing configuration details and contract addresses
├── README.md                     # Project documentation
└── prometheus.yaml               # Prometheus configuration for logs

Architecture

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:

Task Execution logic:

Validation Service logic:

---

Prerequisites

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

Usage

1. Clone the repository:

   git clone https://github.com/Othentic-Labs/simple-price-oracle-avs-example.git
   cd simple-price-oracle-avs-example
   git checkout kyc-avs

2. Install Othentic CLI:

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

3. Set up the TEE server by following the instructions below. Build the Docker image and start the server. Make sure to populate the .env file with TEE_KYC_SERVER_URL and any other required environment variables.

   cd ..
   git clone https://github.com/scrtlabs/kyc-avs-demo
   cd kyc-avs-demo
   docker build -t kyc-avs .

4. Follow the steps in the official documentation's Quickstart Guide for setup and deployment.

   cd simple-price-oracle-avs-example
   docker compose build --no-cache
   docker compose up
   curl -X POST http://localhost:4003/task/execute
   

Service Start-up Order

To ensure proper initialization and communication between services, start them in the following order:

1. Start Aggregator

docker compose -f docker-compose-aggregator.yml up -d

2. Start Attesters

for i in 1 2 3; do
  docker compose -f docker-compose-attester-$i.yml up -d
done

3. Start Validation Service

docker compose -f docker-compose-validation-service.yml up -d

4. Start Execution Service

docker compose -f docker-compose-execution-service.yml up -d

Troubleshooting

If you encounter issues with service startup or communication:

1. Check container logs for detailed error messages:

   docker compose -f docker-compose-aggregator.yml logs
   docker compose -f docker-compose-attester-1.yml logs
   docker compose -f docker-compose-validation-service.yml logs
   docker compose -f docker-compose-execution-service.yml logs

2. Verify network connectivity between services:

   # Test connectivity to aggregator
   ping 10.8.0.1
   
   # Test connectivity to attesters
   ping 10.8.0.2
   ping 10.8.0.3
   ping 10.8.0.4
   
   # Test connectivity to validation service
   ping 10.8.0.5
   
   # Test connectivity to execution service
   ping 10.8.0.6

3. Check service health by monitoring container status:

   docker ps

4. Restart services if needed (in the same order as startup):

   docker compose -f docker-compose-aggregator.yml restart
   docker compose -f docker-compose-attester-1.yml restart
   docker compose -f docker-compose-attester-2.yml restart
   docker compose -f docker-compose-attester-3.yml restart
   docker compose -f docker-compose-validation-service.yml restart
   docker compose -f docker-compose-execution-service.yml restart

Happy Building! 🚀