Deploy a Coin Prediction Reputer

What You'll Learn

Complete setup process for a coin prediction reputer node using Docker
Understanding the three-component architecture: Reputer, Truth, and Updater containers
Configuration management for wallet settings and reputer parameters
Real-world implementation for ETH price prediction topics

Overview

This is an example of a setup for running an Allora Network reputer node for providing ground truth and reputation, where the Allora Network node defers the requests to another container which is responsible for providing the ground truth, which is run in a separate container. It also provides a means of updating the internal database of the ground truth provider.

Architecture Benefits

Why This Design Works:

Separation of concerns: Each component handles specific responsibilities
Scalability: Individual containers can be scaled independently
Maintainability: Components can be updated without affecting others
Reliability: Isolated failures don't compromise the entire system

System Components

Component Architecture

Reputer: The node that responds to reputer requests from the Allora Network.

Primary function: Interface between Allora Network and ground truth system
Network communication: Handles all blockchain interactions and consensus
Request routing: Forwards evaluation requests to the Truth container

Truth: A container that performs reputation tasks, maintains the state of the model, and responds to reputation requests via a simple Flask application. It fetches data from CoinGecko.

Data source: CoinGecko API integration for reliable price data
Ground truth provision: Supplies authoritative data for loss calculations
State management: Maintains historical data and current market information

Updater: A cron-like container designed to periodically trigger the Truth node's data updates.

Automation: Scheduled updates to maintain data freshness
Data integrity: Ensures continuous availability of ground truth
System reliability: Reduces manual intervention requirements

Example Implementation

A full working example for a reputer node for ETH price prediction topics is provided in the docker-compose.yml file (opens in a new tab) of our example repo. Simply run:

Repository Benefits:

Complete implementation: Ready-to-deploy configuration
Best practices: Proven architecture and setup patterns
Documentation: Comprehensive examples and explanations
Community support: Maintained by the Allora Network team

Educational Resources

Video Walkthrough

Please see the video below to get a full deep-dive on how to deploy a reputer:

Video Learning Benefits:

Visual guidance: Step-by-step demonstration of the entire process
Troubleshooting: Common issues and their solutions
Best practices: Expert recommendations for optimal setup
Real-time examples: Live deployment walkthrough

Setup Process

Step 1: Download the Repository

git clone https://github.com/allora-network/coin-prediction-reputer.git
cd coin-prediction-reputer

Repository Structure:

Complete codebase: All necessary files for reputer deployment
Configuration templates: Pre-built examples for quick setup
Documentation: Detailed instructions and troubleshooting guides
Docker integration: Containerized deployment for easy management

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

Configuration Security:

Secure storage: Keep your mnemonic phrase in a safe location
Access control: Limit file permissions for configuration files
Backup strategy: Maintain secure backups of wallet information

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.
loopSeconds: The amount of seconds to wait between attempts to get the next reputer nonce

💡

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"
          }
      }
    ],

Multi-Topic Strategy:

Resource allocation: Distribute stakes strategically across topics
Performance monitoring: Track individual topic performance
Risk management: Diversify across different prediction categories
Scaling considerations: Plan for increased computational requirements

Deployment Process

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

Variable Export Benefits:

Environment isolation: Secure separation of configuration data
Docker integration: Seamless container environment setup
Security enhancement: Prevents credential exposure in command line
Configuration validation: Ensures all required parameters are present

Request from Faucet

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

Funding Requirements:

Minimum stake: Sufficient tokens for your configured minimum stake
Transaction fees: Additional tokens for network operations
Operational buffer: Extra funds for ongoing network participation

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 Process:

Container orchestration: All components start in coordinated fashion
Internal networking: Secure communication between containers
Service discovery: Automatic endpoint resolution and connection
Health monitoring: Built-in checks for service availability

Verification and Monitoring

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"}

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

Success Indicators:

Transaction confirmation: Valid transaction hash in logs
Network registration: Node appears in network participant lists
Data flow: Truth service responding to requests properly
Consensus participation: Active involvement in reputation calculations

Data Maintenance

Keep it updated

You can keep the state updated by hitting the url:

http://localhost:8000/update/<token-name>/<token-from>/<token-to>

where:

token-name: the name of the token on internal database, e.g. ETHUSD
token-from: the name of the token on Coingecko naming, e.g. ethereum
token-to: the name of the token on Coingecko naming, e.g. usd

It is expected that this endpoint is hit periodically, as this is crucial for maintaining the accuracy of the provided ground truth.

Update Strategy:

Scheduled updates: Implement regular data refresh cycles
Real-time monitoring: Track data freshness and accuracy
Error handling: Manage API failures and network issues
Performance optimization: Balance update frequency with resource usage

Testing and Validation

Testing the Truth Service

Here we'll setup a reputer with only the "truth service", which fetches the ground truth.

To only test the truth service, you can simply follow these steps:

Run docker compose up --build truth and wait for the initial data load.

Requests can now be sent, e.g. ETH price ground truths can be fetched with:

  $ curl http://localhost:8000/gt/ETHUSD/1719565747
  {"value":"3431.440268842158"}

or you can trigger an update to the current ETH price:

  $ curl http://localhost:8000/update/ETHUSD/ethereum/usd

Testing Benefits:

Component isolation: Test truth service independently
Data validation: Verify ground truth accuracy before full deployment
Performance assessment: Measure response times and reliability
Debugging facilitation: Identify issues before network integration

Best Practices

Operational Considerations

Reliability Strategies:

Regular monitoring: Track all component health and performance
Data backup: Maintain copies of critical configuration and state data
Update procedures: Establish processes for software and configuration updates
Error recovery: Implement robust error handling and recovery mechanisms

Security Guidelines

Protection Measures:

Access control: Limit network access to reputer endpoints
Credential management: Secure storage of wallet keys and API credentials
Network security: Use firewalls and secure communication protocols
Regular updates: Keep all software components current with security patches

Prerequisites

Docker and Docker Compose: Container orchestration platform
Network connectivity: Stable internet connection for API access and blockchain communication
Wallet setup: Configured Allora wallet with sufficient funds
Technical understanding: Basic knowledge of containerized applications and blockchain operations

Next Steps

Learn about reputer data querying for performance monitoring
Understand stake management for optimal network participation
Explore general reputer deployment for broader implementation options
Study the reputer role for comprehensive understanding of network functions

Deploy a Simple Reputer using Docker Set and Adjust Stake