Deploy a Reputer Node using Docker

What You'll Learn

How to deploy and configure a reputer node for the Allora Network
Understanding reputer configuration including wallet and endpoint setup
Creating a truth server to provide accurate ground truth data
Complete deployment workflow from setup to network registration

Overview

Deploying a reputer in the Allora network involves configuring the config.example.json file to ensure your reputer can interact with the network and provide accurate truth data.

What is a Reputer?

Reputers serve critical functions in the Allora Network:

Quality assurance: Evaluate the accuracy of worker submissions
Ground truth provision: Supply reliable truth data for comparison
Network integrity: Maintain the quality and reliability of network inferences
Reward determination: Help calculate appropriate rewards for workers

Why Deploy a Reputer?

Running a reputer provides:

Network contribution: Help maintain network quality and accuracy
Reward opportunities: Earn rewards for providing valuable evaluation services
Data validation: Contribute to the verification of network predictions
Ecosystem participation: Play a key role in network governance and quality

To build this setup, please follow these steps:

Prerequisites

Ensure you have the following installed on your machine:

Git: Version control system for repository management
Go (version 1.16 or later): Programming language runtime
Docker: Container platform for application deployment

Installation and Setup

Step 1: Clone the Repository

Download the allora-offchain-node git repo:

git clone https://github.com/allora-network/allora-offchain-node
cd allora-offchain-node

Repository Contents:

Pre-configured reputer node implementation
Example configuration files for easy setup
Sample truth server code and Docker configurations

Configuration

Step 2: Configure Your Environment

Copy config.example.json and name the copy config.json.
Open config.json and update the necessary fields inside the wallet sub-object and worker config with your specific values:

Wallet Configuration

wallet Sub-object:

nodeRpc: The RPC URL for the corresponding network the node will be deployed on
addressKeyName: The name you gave your wallet key when setting up your wallet
addressRestoreMnemonic: The mnemonic that was outputted when setting up a new key

Reputer Configuration

reputer Config:

topicId: The specific topic ID you created the reputer for.
SourceOfTruthEndpoint: The endpoint exposed by your source of truth server to provide the truth data to the network.
Token: The token for the specific topic you are verifying truth data for. This token should be included in the source of truth endpoint for retrieval.
- The Token variable is specific to the endpoint you expose in your main.py file. It is not related to any blockchain parameter and is only locally specific.
minStake: The minimum stake required to participate as a reputer. This stake will be deducted from the reputer's wallet balance.

💡

When placing your minimum stake, the system will verify the amount of funds you have already staked in the topic. If your staked amount is insufficient, it will automatically pull the necessary funds from your wallet to meet the required minimum.

Multi-Topic Support

⚠️

The reputer config is an array of sub-objects, each representing a different topic ID. This structure allows you to manage multiple topic IDs, each within its own sub-object.

To deploy a reputer that provides inferences for multiple topics, you can duplicate the existing sub-object and add it to the reputer array. Update the topicId, SourceOfTruthEndpoint, minStake and Token fields with the appropriate values for each new topic:

"worker": [
      {
          "topicId": 1,
          "reputerEntrypointName": "api-worker-reputer",
          "loopSeconds": 30,
          "minStake": 100000,
          "parameters": {
              "SourceOfTruthEndpoint": "http://source:8888/truth/{Token}/{BlockHeight}",
              "Token": "ethereum"
          }
      },
      // reputer providing ground truth for topic ID 2
      {
          "topicId": 2,
          "reputerEntrypointName": "api-worker-reputer",
          "loopSeconds": 30,
          "minStake": 100000,
          "parameters": {
              "SourceOfTruthEndpoint": "http://source:8888/truth/{Token}/{BlockHeight}",
              "Token": "ethereum"
          }
      }
    ],

Worker Configuration (Optional)

Worker Config: The config.example.json file that was copied and edited in the previous steps also contains a JSON object for configuring and deploying a worker. To ignore the worker and only deploy a reputer, delete the reputer sub-object from the config.json file.

Truth Server Implementation

Step 3: Create the Truth Server

Prepare the API Gateway

Ensure you have an API gateway or server that can accept API requests to call your model.

Server Responsibilities:

Accept API requests from main.go.
Respond with the corresponding inference obtained from the model.

Truth Relay Architecture

Below is a sample structure of what your main.go, main.py and Dockerfile will look like. You can also find a working example here (opens in a new tab).

`main.go` Component

allora-offchain-node comes preconfigured with a main.go file inside the adapter/api-worker-reputer folder (opens in a new tab).

Function: The main.go file fetches the responses outputted from the Source of Truth Endpoint based on the SourceOfTruthEndpoint and Token provided in the section above.

`main.py` Implementation

allora-offchain-node comes preconfigured with a Flask application that uses a main.py file to expose the Source of Truth Endpoint.

The Flask application serves the request from main.go, which is routed to the get_truth function using the required arguments (Token, blockHeight). Before proceeding, ensure that all necessary packages are listed in the requirements.txt file.

from flask import Flask
from model import get_inference  # Importing the hypothetical model
 
app = Flask(__name__)
 
@app.route('/truth/<token>/<blockheight>', methods=['GET'])
def get_truth(token, blockheight):
    random_float = str(random.uniform(0.0, 100.0))
    return random_float
 
if __name__ == '__main__':
    app.run(host='0.0.0.0')

⚠️

The source of truth in allora-offchain-node is barebones and outputs a random integer. Follow the source of truth built in coin-prediction-reputer as an example for a reputer that uses CoinGecko to fetch price data.

Docker Configuration

A sample Dockerfile has been created in allora-offchain-node that can be used to deploy your model on port 8000.

FROM python:3.9-slim
 
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
 
WORKDIR /app
 
COPY requirements.txt .
 
RUN pip install --no-cache-dir -r requirements.txt
 
COPY . .
 
EXPOSE 8000
 
CMD ["python", "main.py"]

Deployment Process

Step 4: Running the Node

Now that the node is configured, let's deploy and register it to the network. To run the node, follow these steps:

Export Variables

Execute the following command from the root directory:

chmod +x init.config
./init.config

This command will automatically export the necessary variables from the account created. These variables are used by the offchain node and are bundled with your provided config.json, then passed to the node as environment variables.

💡

If you need to make changes to your config.json file after you ran the init.config command, rerun:

chmod +x init.config
./init.config

before proceeding.

Request from Faucet

Copy your Allora address and request some tokens from the Allora Testnet Faucet (opens in a new tab) to register your worker in the next step successfully.

Funding Requirements:

Sufficient tokens for transaction fees
Minimum stake amount as configured in your reputer settings
Additional buffer for ongoing operations

Deploy the Node

docker compose up --build

Both the offchain node and the source services will be started. They will communicate through endpoints attached to the internal DNS.

Deployment Components:

Offchain reputer node for network communication
Truth server for providing ground truth data
Internal service discovery and communication

Verification

Successful Deployment

A successful response from your Reputer should display:

{"level":"debug","msg":"Send Reputer Data to chain","txHash":"<tx-hash>","time":"<timestamp>","message":"Success"}

Success Indicators:

Transaction hash appears in logs
No persistent error messages
Truth server responds to requests
Stake properly allocated to chosen topics

Congratulations! You've successfully deployed and registered your node on Allora.

Advanced Configuration

Performance Optimization

Resource Management:

Monitor container resource usage
Adjust stake amounts based on performance
Optimize truth data retrieval for faster responses

Multi-Topic Strategy

Scaling Considerations:

Balance stake across multiple topics
Monitor relative performance and adjust allocations
Consider computational requirements for multiple truth sources

Learn More

Learn more by directly checking out the code and README for the example ETH price reputer (opens in a new tab).

Next Steps

Explore advanced reputer configurations with real market data
Learn about stake management for optimal participation
Understand reputer data querying for performance monitoring

Reputers Deploy a Pre-configured Reputer