Allora Network Worker Skill

Build and deploy AI workers on the Allora Network - a decentralized oracle platform that leverages machine learning to provide accurate predictions and earn rewards.

Overview

What is the Allora Network?

Allora is a decentralized network where:

• Workers submit ML predictions to specific Topics (e.g., "BTC 24h price prediction")
• Reputers evaluate and score prediction quality
• Accurate predictions earn ALLO tokens as rewards
• The network aggregates predictions using "context-aware inference synthesis"

Key Concepts

| Concept | Description | |---------|-------------| | Worker | A node that runs your ML model and submits predictions to the network | | Topic | A specific prediction task (e.g., ETH price in 10 minutes) | | Reputer | A node that evaluates prediction quality | | ALLO | The native token used for gas fees and rewards (18 decimals) | | Epoch | Time window when predictions are submitted and evaluated |

Network Environments

| Environment | Use Case | Chain ID | |-------------|----------|----------| | Testnet | Development, testing, no real funds | allora-testnet-1 | | Mainnet | Production, real ALLO tokens | allora-mainnet-1 |

Quick Start: Python SDK (Recommended)

The allora-sdk-py library is the easiest way to build workers.

Installation

pip install allora_sdk

Minimal Worker Example

from allora_sdk import AlloraWorker

def my_model():
    """Your ML model prediction logic."""
    # Return a prediction value (e.g., BTC price)
    return 120000.0

async def main():
    worker = AlloraWorker.testnet(
        run=my_model,
        api_key="<YOUR_API_KEY>",  # Get free key at https://developer.allora.network
    )

    async for result in worker.run():
        if isinstance(result, Exception):
            print(f"Error: {result}")
        else:
            print(f"Prediction submitted: {result.prediction}")

# Run it
import asyncio
asyncio.run(main())

What happens automatically:

1. Generates a wallet identity (saved locally for reuse)
2. Obtains testnet ALLO for gas fees
3. Registers your worker to Topic 69 (sandbox)
4. Submits predictions each epoch

Get an API Key

1. Visit https://developer.allora.network
2. Create an account (free)
3. Generate an API key
4. Use it in your worker configuration

Production Worker Configuration

Using Existing Wallet

from allora_sdk import AlloraWorker, AlloraWalletConfig, AlloraNetworkConfig, FeeTier

worker = AlloraWorker.inferer(
    # Wallet configuration
    wallet=AlloraWalletConfig(
        mnemonic="your 24 word mnemonic phrase here...",
        # OR use private key:
        # private_key="hex_encoded_private_key",
    ),
    
    # Network configuration
    network=AlloraNetworkConfig.mainnet(),  # or .testnet() or .local()
    
    # Target topic
    topic_id=1,  # ETH 10min prediction
    
    # Your inference function
    run=my_prediction_function,
    
    # API key for convenience features
    api_key="UP-...",
    
    # Fee tier: ECO, STANDARD, or PRIORITY
    fee_tier=FeeTier.STANDARD,
    
    # Enable debug logging
    debug=False,
)

Custom Network Configuration

network = AlloraNetworkConfig(
    chain_id="allora-testnet-1",
    url="grpc+https://allora-grpc.testnet.allora.network:443",
    websocket_url="wss://allora-rpc.testnet.allora.network/websocket",
    fee_denom="uallo",
    fee_minimum_gas_price=250_000_000.0,
    congestion_aware_fees=True,
    use_dynamic_gas_price=True,
)

Building Inference Functions

Basic Price Prediction

import numpy as np

def predict_btc_price():
    """Simple prediction function."""
    # Your model logic here
    # Must return a numeric value
    return 95000.0

Using the Forge Builder Kit

For production ML models, use the allora-forge-builder-kit:

pip install git+https://github.com/allora-network/allora-forge-builder-kit.git

from allora_forge_builder_kit import AlloraMLWorkflow
from datetime import datetime, timedelta, timezone
import lightgbm as lgb
import numpy as np

# 1. Create workflow for 24-hour Bitcoin prediction
workflow = AlloraMLWorkflow(
    tickers=["btcusd"],
    number_of_input_bars=48,  # 48 hourly bars for features
    target_bars=24,           # Predict 24 hours ahead
    interval="1h",
    data_source="allora",
    api_key="your-api-key"
)

# 2. Backfill historical data
start = datetime.now(timezone.utc) - timedelta(days=180)
workflow.backfill(start=start)

# 3. Get training data
df = workflow.get_full_feature_target_dataframe(start_date=start).reset_index()
feature_cols = [c for c in df.columns if c.startswith('feature_')]

# 4. Train model
model = lgb.LGBMRegressor(n_estimators=100)
model.fit(df[feature_cols], df["target"])

# 5. Create inference function
def predict():
    features = workflow.get_live_features("btcusd")
    log_return = model.predict(features)[0]
    
    # Get current price for conversion
    raw = workflow.load_raw(start=datetime.now(timezone.utc) - timedelta(hours=2))
    current_price = raw["close"].iloc[-1]
    
    # Convert log return to price
    predicted_price = current_price * np.exp(log_return)
    return float(predicted_price)

Model Evaluation

The Forge Builder Kit includes official metrics:

# Evaluate your model
test_preds = model.predict(X_test[feature_cols])
metrics = workflow.evaluate_test_data(test_preds)

# Grading: A+ to F based on 8 metrics
# - Directional Accuracy ≥ 55%
# - DA Confidence Interval Lower Bound ≥ 52%
# - Statistical Significance (p < 0.05)
# - And more...

Docker Deployment

For production workers, use the Docker-based approach:

Project Structure

my-allora-worker/
├── config.json           # Worker configuration
├── docker-compose.yml    # Container orchestration
├── model.py             # Your ML model
├── main.py              # Flask inference server
├── requirements.txt     # Python dependencies
└── Dockerfile           # Container build

config.json

{
  "wallet": {
    "nodeRpc": "https://allora-rpc.testnet.allora.network",
    "addressKeyName": "my-worker-key",
    "addressRestoreMnemonic": "your 24 word mnemonic..."
  },
  "worker": [
    {
      "topicId": 1,
      "inferenceEndpoint": "http://inference:8000/inference",
      "token": "ETH"
    }
  ]
}

Flask Inference Server (main.py)

from flask import Flask, Response
import json

app = Flask(__name__)

@app.route("/inference/<token>")
def get_inference(token):
    """Return prediction for the given token."""
    # Your model prediction logic
    prediction = your_model.predict(token)
    return Response(
        json.dumps({"value": str(prediction)}),
        mimetype='application/json'
    )

@app.route("/update")
def update_model():
    """Trigger model update (data refresh, retrain)."""
    # Update logic
    return "0"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

docker-compose.yml

version: '3.8'

services:
  inference:
    build: .
    ports:
      - "8000:8000"
    environment:
      - TOKEN=ETH
    volumes:
      - ./data:/app/data
    
  worker:
    image: alloranetwork/allora-offchain-node:latest
    depends_on:
      - inference
    environment:
      - ALLORA_OFFCHAIN_ACCOUNT_ADDRESS=${ALLORA_OFFCHAIN_ACCOUNT_ADDRESS}
    volumes:
      - ./config.json:/app/config.json

Running

# Initialize (creates keys, exports variables)
./init.config

# Fund your worker wallet
# Get address from ./worker-data/env_file (ALLORA_OFFCHAIN_ACCOUNT_ADDRESS)
# Request tokens from https://faucet.testnet.allora.network/

# Start services
docker compose up --build

Existing Topics (Testnet)

| Topic ID | Description | Default Token | |----------|-------------|---------------| | 1 | ETH 10min Prediction | ETH | | 2 | ETH 24h Prediction | ETH | | 3 | BTC 10min Prediction | BTC | | 4 | BTC 24h Prediction | BTC | | 5 | SOL 10min Prediction | SOL | | 6 | SOL 24h Prediction | SOL | | 13 | ETH 5min Prediction | ETH | | 14 | BTC 5min Prediction | BTC | | 69 | Sandbox (testing) | Any |

Use the Allora Explorer to browse all topics.

Using the RPC Client

For advanced operations:

from allora_sdk import AlloraRPCClient

# Initialize
client = AlloraRPCClient.testnet()

# Query network data
from allora_sdk.rpc_client.protos.emissions.v9 import GetLatestRegretStdNormRequest
request = GetLatestRegretStdNormRequest(topic_id=1)
response = client.emissions.query.get_latest_regret_std_norm(request)

# Submit transactions
response = await client.emissions.tx.insert_worker_payload(
    topic_id=1,
    inference_value="95000.0",
    nonce=12345
)

# Subscribe to events
from allora_sdk.rpc_client.protos.emissions.v9 import EventWorkerSubmissionWindowOpened

async def handle_event(event, block_height):
    print(f"New epoch: {event.topic_id} at block {block_height}")

subscription_id = await client.events.subscribe_new_block_events_typed(
    EventWorkerSubmissionWindowOpened,
    [EventAttributeCondition("topic_id", "=", "1")],
    handle_event
)

Using the API Client

For querying network inferences:

from allora_sdk.api_client import AlloraAPIClient

client = AlloraAPIClient()

async def main():
    # Get all active topics
    topics = await client.get_all_topics()
    print(f"Found {len(topics)} topics")

    # Get latest inference for a topic
    inference = await client.get_inference_by_topic_id(13)
    print(f"ETH price in 5 minutes: ${inference.inference_data.network_inference_normalized}")

import asyncio
asyncio.run(main())

Best Practices

Model Development

1. Start with the sandbox (Topic 69) - no penalties for inaccurate predictions
2. Use historical data from the Forge Builder Kit for training
3. Evaluate thoroughly before deploying to production topics
4. Monitor performance using the explorer and metrics

Security

1. Never commit mnemonics - use environment variables
2. Use separate wallets for testnet and mainnet
3. Secure your API keys - rotate if exposed
4. Run workers in isolated environments

Performance

1. Optimize inference latency - predictions must complete within epoch windows
2. Use efficient models - balance accuracy vs. speed
3. Cache data locally - reduce API calls with the Forge Builder Kit
4. Monitor gas fees - use appropriate fee tiers

Reliability

1. Implement retries - network issues happen
2. Handle errors gracefully - log and continue
3. Monitor worker health - set up alerts
4. Keep models updated - retrain regularly with new data

Resources

Official Documentation

• Allora Docs
• Developer Portal

GitHub Repositories

• allora-sdk-py - Python SDK
• allora-forge-builder-kit - ML workflow toolkit
• basic-coin-prediction-node - Example worker
• allora-offchain-node - Docker-based worker

Community

• Discord
• Allora Explorer
• Testnet Faucet

Troubleshooting

Common Issues

Worker not submitting predictions:

• Check wallet has sufficient ALLO for gas
• Verify topic ID exists and is active
• Check network connectivity to RPC endpoints

Low prediction scores:

• Evaluate model with Forge Builder Kit metrics
• Ensure predictions are in expected format (price, not log return)
• Check data freshness in your inference function

Transaction failures:

• Increase fee tier to PRIORITY during congestion
• Check nonce/sequence issues
• Verify wallet balance

Logging

Enable debug mode for detailed logs:

worker = AlloraWorker.testnet(
    run=my_model,
    api_key="...",
    debug=True,  # Enable verbose logging
)