Appchain CLI Spec

Install the allorad binary for interacting with Allora via the CLI

Suggest Edits

The Appchain CLI is an easy means of interacting with the Allora Network. It can be used to read and write data to the chain, e.g. to read the distribution of weights across workers or to create new topics. In this page, we'll discuss how to set up allorad, which is the tool synonymous with the Appchain CLI, then enumerate all queries and transactions unique to Allora that can be run with it.

Install

curl -sSL https://raw.githubusercontent.com/allora-network/allora-chain/main/install.sh | bash -s -- v0.0.7

Build Requirements and Setup

The installation process is optimized for Linux distributions, with Ubuntu 20.04.3 LTS as the reference environment. Installation is also supported on Unix systems. Windows users may need to use third-party tools, which are not officially supported. The instructions below guide you through a clean installation.

Update & Install Build Tools

To begin, update your system and install the essential build tools:

Ubuntu:

sudo apt-get update  
sudo apt-get install -y make gcc

Install Go

allorad requires Go version 1.21 or newer to ensure compatibility and performance.

To install Go, follow one of the recommended methods below or consult the official Go documentation for the correct download for your operating system. The command-line instructions are based on standard installation locations, but you may customize them as needed.

Go Binary Downloads

On Ubuntu, you would download and set up Go as follows, adjusting for the latest version available:

curl -OL <https://go.dev/dl/go1.21.linux-amd64.tar.gz>  
sudo tar -C /usr/local -xvf go1.21.linux-amd64.tar.gz

Add Go to your PATH to facilitate command execution:

export PATH=$PATH:$(go env GOPATH)/bin

Install allorad Binaries

Proceed to install the latest allorad version, ensuring you clone the correct version tag from the repository:

git clone -b <latest-release-tag> https://github.com/allora-network/allora-chain.git
cd allora-chain && make all

Verifying Installation

After installation, verify that allorad is correctly installed and ready to interact with the Allora Network by running:

allorad version

allorad supports general Cosmos SDK and Tendermint commands. You can run the tool to see a list of commands with explanations of what they do:

$ allorad
allorad - the allora app chain

Usage:
  allorad [command]

Available Commands:
  comet       CometBFT subcommands
  completion  Generate the autocompletion script for the specified shell
  config      Utilities for managing application configuration
  debug       Tool for helping with debugging your application
  export      Export state to JSON
  genesis     Application's genesis-related subcommands
  help        Help about any command
  init        Initialize private validator, p2p, genesis, and application configuration files
  keys        Manage your application's keys
  prune       Prune app history states by keeping the recent heights and deleting old heights
  query       Querying subcommands
  rollback    rollback Cosmos SDK and CometBFT state by one height
  snapshots   Manage local snapshots
  start       Run the full node
  status      Query remote node for status
  tx          Transactions subcommands
  version     Print the application binary version information

Flags:
  -h, --help                help for allorad
      --home string         directory for config and data (default "/Users/<USER>/.allorad")
      --log_format string   The logging format (json|plain) (default "plain")
      --log_level string    The logging level (trace|debug|info|warn|error|fatal|panic|disabled or '*:<level>,<key>:<level>') (default "info")
      --log_no_color        Disable colored logs
      --trace               print out full stack trace on errors

Use "allorad [command] --help" for more information about a command.

Running Commands

You can then interact with the chain as follows.

In the code below, note that RPC_URL defaults to localhost, which you may not have running. We'll release a list of supported RPC endpoints for public use shortly.

Queries

To query the chain e.g. to get the next topic id, one can run:

allorad q emissions next-topic-id --node <RPC_URL>

Create a wallet

Prior to start with transactions, a wallet must be created by running:

allorad keys add testkey

Learn more about setting up keys here.

Make sure you save your mnemomic and account information safely.

Transactions

Transactions involve some extra steps. Then, for testnet, head over to our faucet or, for mainnet, an exchange (details for both TBA) to grab some coins to pay for gas and other interactions. Then, to run a transaction, e.g. to create a topic, one can run:

allorad --node <RPC_URL> tx emissions push-topic <YOUR_ADDRESS> "ETH" bafybeih6yjjjf2v7qp3wm6hodvjcdljj7galu7dufirvcekzip5gd7bthq eth-price-weights-calc.wasm 150 bafybeie65aglhion2fol4etjotgdpfra44tdxssrid345pjkcmms5g3j7u allora-function-example.wasm 60 true

Be sure to swap out RPC_URL, YOUR_ADDRESS, and all other arguments as appropriate with the desired values.

Query Functions

These functions read from the appchain only and do not write.

Params

  • RPC Method: Params
  • Usage: params
  • Description: Get the current module parameters.

Get Next Topic ID

  • RPC Method: GetNextTopicId
  • Usage: next-topic-id
  • Description: Get next topic id. Topic ids are incremented with each newly added topic.

Get Topic

  • RPC Method: GetTopic
  • Usage: topic topic_id
  • Description: Get topic by topic_id.
  • Positional Arguments:
    • topic_id Identifier of the topic whose information will be returned.

Get Weight

  • RPC Method: GetWeight
  • Usage: weight [topic_id] [reputer] [worker]
  • Description: Get Weight From a Reputer to a Worker for a Topic.
  • Positional Arguments:
    • topic_id Identifier of the topic in which the given reputer and worker nodes participate.
    • reputer Identifier of the reputer who placed stake in the worker. The reputer's trust in the worker is roughly quantified by the returned weight.
    • worker Identifier of the worker node. The trust in this node is roughly quantified by the returned weight.

Get Inference

  • RPC Method: GetInference
  • Usage: inference [topic_id] [worker]
  • Description: Get Latest Inference From Worker for a Topic.
  • Positional Arguments:
    • topic_id Identifier of the topic in which the given worker node participates.
    • worker Identifier of the worker node whose latest inference in this topic will be returned.

Get InferenceToScore

  • RPC Method: GetInferenceToScore
  • Usage: inferences-to-score [topic_id]
  • Description: Get Latest Inference From Worker for a Topic to be score in the topic's weight-adjustment epoch.
  • Positional Arguments:
    • topic_id Identifier of the topic in which the given worker node participates.

Tx Functions

These functions write to the appchain.

Create New Topic

  • RPC Method: CreateNewTopic
  • Usage: push-topic [creator] [metadata] [weight_logic] [weight_method] [weight_cadence] [inference_logic] [inference_method] [inference_cadence] [default_arg]
  • Description: Add a new topic to the network.
  • Positional Arguments:
    • creator The creator is the owner of the topic that is able to update the topic in the future
    • metadata
    • weight_logic
    • weight_method
    • weight_cadence
    • inference_logic
    • inference_method
    • inference_cadence
    • default_arg

Register Network Actor

  • RPC Method: Register
  • Usage: register [creator] [lib_p2p_key] [multi_address] [topic_ids] [initial_stake] [owner] [is_reputer]
  • Description: Register a new reputer or worker for a topic.
  • Positional Arguments:
    • creator
    • lib_p2p_key
    • multi_address
    • topic_ids
    • initial_stake
    • owner
    • is_reputer

Add Stake

  • RPC Method: AddStake
  • Usage: add-stake [sender] [target] [amount]
  • Description: Add stake [amount] from a sender [reputer or worker] to a target [reputer or worker]. If the target is not the sender, then this is equivalent to "delegating stake."
  • Positional Arguments:
    • sender The staker. This is the address of the transaction sender.
    • target The stakee
    • amount The amount staked

Remove Stake

  • RPC Method: RemoveStake
  • Usage: remove-stake sender target amount
  • Description: Remove stake [amount] from a target [reputer or worker] back to a sender [reputer or worker]. If the target is not the sender, then this is equivalent to removing "delegate stake."
  • Positional Arguments:
    • sender The staker. This is the address of the transaction sender.
    • target The stakee
    • amount The amount staked

Remove All Stake

  • RPC Method: RemoveAllStake
  • Usage: remove-all-stake sender
  • Description: Remove all stake from a sender [reputer or worker]. This function will automatically figure out which topic the sender belongs to and remove all of their stake from that topic.
  • Positional Arguments:
    • sender The staker to remove all stakes from. This is the address of the transaction sender.

Set Inferences

  • RPC Method: SetInferences
  • Description: Submit new inference results for a worker on a topic.
  • Positional Arguments:
    • sender the address of the transaction sender who is submitting the inferences.
    • topic_id Identifier of the topic for which the inference is being submitted.
    • worker Identifier of the worker node that produced the inference.
    • value The result of the inference.
    • extra_data Additional data related to the inference.
    • proof A zkProof verifying the validity of the inference as sourced e.g. from Modulus. Topics may require proofs by assigning a large loss to inferences with missing or invalid proofs within their weight-adjustment logic.

Updated about 2 months ago