Reputers

Reputers do the following actions on Allora:

Source ground truth as specified by the topic metadata
- e.g. the actual price of ETH as of a moment in time
Calculate loss of workers inferences and forecast-implied inferences relative to that ground truth
- e.g. A topic's loss function is an L1-norm (opens in a new tab) applied to each worker's inference and the revealed price of ETH in 10 days per CoinGecko API. Reputers apply this loss function to every inference received in a request and respond with a ValueBundle of losses
Secure topics with their stake
- the more a reputer stakes in a topic, the more they influence the consensus of losses
- reputers can be delegated to as well, increasing the extent to which they secure the topic
Receive rewards based on how close to consensus their reported losses are
- a stake-weighted average of each reported loss is taken among reputers per topic per epoch
- the closer a reputer's values are to the average, the more they are rewarded

Setup a Reputer Node with `docker-compose`

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

docker compose up

⚠️

Our containers are not yet compatible with Apple Silicon hardware!

Components of the Example Reputer Node

This example contains a service for sourcing truth -- called the "truth service" -- a Blockless worker node for responding to Blockless requests and calculating topic-specific los functions, and a Blockless head node for initiating requests.

In practice, you would only run a head node as a side car to a validator node. This way, chain validators can initiate requests to collect inferences and forecasts from workers, and ground-truth-informed loss calculations from reputers.

You can read more about the lifecycle of Blockless requests on the Blockless docs (opens in a new tab).

If you were just acting as a reputer, you would only be responding to requests from another peer's head node, not your own head node.

Setup a Reputer Node Manually

Here, we'll recreate the steps contained within the docker-compose.yml file. We'll setup a reputer that sources ground truth and calculates losses for ETH price prediction topics, plus a head node for development and testing purposes.

First, be sure to clone and cd into our example reputer repo (opens in a new tab).

Generate keys

Create a set of keys for your head and worker nodes. These keys will be used in the configuration of the head and worker nodes.

Create head keys

docker run -it --entrypoint=bash -v ./head-data:/data alloranetwork/allora-inference-base:latest -c "mkdir -p /data/keys && (cd /data/keys && allora-keys)"

Create worker keys

docker run -it --entrypoint=bash -v ./worker-data:/data alloranetwork/allora-inference-base:latest -c "mkdir -p /data/keys && (cd /data/keys && allora-keys)"

Important note: If no keys are specified in the volumes, new keys will be automatically created inside head-data/keys and worker-data/keys when first running step 4.

Connect the worker node to the head node

At this step, both worker and head nodes identities are generated inside head-data/keys and worker-data/keys.

Now, we must register the worker with the head. When the head initiates a request, it will ping all the Blockless workers that have registered to it.

To instruct the worker node to connect to the head node:

run cat head-data/keys/identity to extract the head node's peer_id
copy this printed peer_id to replace the head-id placeholder value specified inside the docker-compose.yml file (or docker-compose.arm64.yml based on your configuration) when running the worker service: --boot-nodes=/ip4/172.22.0.100/tcp/9010/p2p/head-id

Run setup

Once all the above is set up, run docker compose up This will bring up the head, the worker and the truth nodes (which will run an initial update).

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.

Testing docker-compose setup

The head node has the only open port, and responds to requests in port 6000.

Example request:

curl --location 'http://localhost:6000/api/v1/functions/execute' --header 'Accept: application/json, text/plain, */*' --header 'Content-Type: application/json;charset=UTF-8' --data '{
    "function_id": "bafybeigpiwl3o73zvvl6dxdqu7zqcub5mhg65jiky2xqb4rdhfmikswzqm",
    "method": "allora-inference-function.wasm",
    "parameters": null,
    "topic": "1",
    "config": {
        "env_vars": [
            {                              
                "name": "BLS_REQUEST_PATH",
                "value": "/api"
            },
            {                              
                "name": "ALLORA_ARG_PARAMS",
                "value": "1711064725"
            }
        ],
        "number_of_nodes": -1,
        "timeout" : 2
    }
}'

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/get/ETHUSD/1711105645
  {"value":"3227.311942291347"}

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

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

Connecting to the Allora network

In order to connect to the Allora network, both the head and the worker need to register against it. More details on allora-inference-base (opens in a new tab) repo.

The following optional flags are used in the command: section of the docker-compose.yml file to define the connectivity with the Allora network.

--allora-chain-key-name=index-provider  # your local key name in your keyring
--allora-chain-restore-mnemonic='pet sock excess ...'  # your node's Allora address mnemonic
--allora-node-rpc-address=  # RPC address of a node in the chain
--allora-chain-topic-id=  # The topic id from the chain that you want to provide predictions for

In order for the nodes to register with the chain, a funded address is needed first. If these flags are not provided, the nodes will not register to the appchain and will not attempt to connect to the appchain.

Learn More

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

Validator Operations Data Providers