Running a full node

How to become a Validator on Allora

This guide provides instructions on how to run a full node for the Allora network. There are two primary methods for running an Allora node: using systemd with cosmosvisor for easier upgrade management (recommended) or using docker compose. It's important to choose the method that best suits your environment and needs.

Prerequisites

Git
Go (version 1.21 or later)
Basic command-line knowledge
Linux/Unix environment with systemd
curl and jq utilities

Method 1: Using systemd with cosmosvisor (Recommended)

Running the Allora node with systemd and cosmosvisor provides production-grade reliability and easier binary upgrade management. This is the recommended approach for validators and production environments.

Step 1: Install cosmosvisor

First, install cosmosvisor, which will manage binary upgrades:

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

Verify the installation:

cosmovisor version

Step 2: Install allorad Binary

Download the latest allorad binary from the releases page:

Navigate to the Allora Chain Releases page (opens in a new tab).
Download the allorad binary appropriate for your operating system (e.g., allorad-linux-amd64, allorad-darwin-amd64).
Rename and move the binary to a standard location:

# Rename the downloaded binary
mv ./allorad-linux-amd64 ./allorad  # Adjust filename as needed
 
# Move to system path
sudo mv ./allorad /usr/local/bin/allorad
 
# Make executable
sudo chmod +x /usr/local/bin/allorad

Step 3: Initialize the Node

Initialize your node (replace <your-moniker> with your desired node name):

allorad init <your-moniker> --chain-id allora-testnet-1

Step 4: Download Network Configuration

Download the testnet configuration files:

# Download genesis.json
curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/genesis.json > $HOME/.allorad/config/genesis.json
 
# Download config.toml
curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/config.toml > $HOME/.allorad/config/config.toml
 
# Download app.toml
curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/app.toml > $HOME/.allorad/config/app.toml

Step 5: Configure Seeds and Peers

Configure seeds and persistent peers for network connectivity:

# Fetch and set seeds
SEEDS=$(curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/seeds.txt)
sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/.allorad/config/config.toml
 
# Optionally set persistent peers
PEERS=$(curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/peers.txt)
sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PEERS\"/" $HOME/.allorad/config/config.toml

Step 6: Configure cosmosvisor

Set up the cosmosvisor directory structure and environment:

# Set environment variables
export DAEMON_NAME=allorad
export DAEMON_HOME=$HOME/.allorad
export DAEMON_RESTART_AFTER_UPGRADE=true
 
# Create cosmosvisor directories
mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
mkdir -p $DAEMON_HOME/cosmovisor/upgrades
 
# Copy the current binary to genesis
cp /usr/local/bin/allorad $DAEMON_HOME/cosmovisor/genesis/bin/

Step 7: Configure State Sync (Optional but Recommended)

State sync allows your node to quickly catch up with the network. Create and run this state sync script:

cat > state_sync.sh << 'EOF'
#!/bin/bash
 
set -e
 
# Choose your preferred RPC endpoint
SNAP_RPC="https://allora-rpc.testnet.allora.network"
CONFIG_TOML_PATH="$HOME/.allorad/config/config.toml"
 
echo "Using RPC Endpoint: $SNAP_RPC"
echo "Fetching latest block height..."
 
LATEST_HEIGHT=$(curl -s $SNAP_RPC/block | jq -r .result.block.header.height)
if [ -z "$LATEST_HEIGHT" ] || [ "$LATEST_HEIGHT" == "null" ]; then
    echo "Error: Could not fetch latest height"
    exit 1
fi
 
BLOCK_HEIGHT_OFFSET=2000
BLOCK_HEIGHT=$((LATEST_HEIGHT - BLOCK_HEIGHT_OFFSET))
 
echo "Fetching trust hash for block $BLOCK_HEIGHT..."
TRUST_HASH=$(curl -s "$SNAP_RPC/block?height=$BLOCK_HEIGHT" | jq -r .result.block_id.hash)
if [ -z "$TRUST_HASH" ] || [ "$TRUST_HASH" == "null" ]; then
    echo "Error: Could not fetch trust hash"
    exit 1
fi
 
echo "Updating config for state sync..."
RPC_SERVERS="$SNAP_RPC,$SNAP_RPC"
 
sed -i.bak -E \
    -e "s|^(enable[[:space:]]*=[[:space:]]*).*$|\\1true|" \
    -e "s|^(rpc_servers[[:space:]]*=[[:space:]]*).*$|\\1\"$RPC_SERVERS\"|" \
    -e "s|^(trust_height[[:space:]]*=[[:space:]]*).*$|\\1$BLOCK_HEIGHT|" \
    -e "s|^(trust_hash[[:space:]]*=[[:space:]]*).*$|\\1\"$TRUST_HASH\"|" \
    "$CONFIG_TOML_PATH"
 
echo "State sync configuration updated successfully"
EOF
 
chmod +x state_sync.sh
./state_sync.sh

Step 8: Reset Node Data

Reset existing data while keeping the address book:

allorad tendermint unsafe-reset-all --home $HOME/.allorad --keep-addr-book

⚠️

Warning: This command deletes blockchain data. Only run this on a fresh node or when you intend to resync from scratch.

Step 9: Create systemd Service

Create a systemd service file for cosmosvisor:

sudo tee /etc/systemd/system/allorad.service > /dev/null <<EOF
[Unit]
Description=Allora Node (allorad via Cosmovisor)
After=network-online.target
 
[Service]
User=$USER
ExecStart=$(which cosmovisor) run start
Restart=always
RestartSec=3
LimitNOFILE=65535
Environment="DAEMON_HOME=$HOME/.allorad"
Environment="DAEMON_NAME=allorad"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_POLL_INTERVAL=300ms"
Environment="UNSAFE_SKIP_BACKUP=true"
 
[Install]
WantedBy=multi-user.target
EOF

Security Note: DAEMON_ALLOW_DOWNLOAD_BINARIES is set to false for security. Validators should manually place upgrade binaries in the appropriate directories.

Step 10: Start the Service

Enable and start the systemd service:

sudo systemctl daemon-reload
sudo systemctl enable allorad
sudo systemctl start allorad

Monitoring and Management

Monitor your node logs:

sudo journalctl -u allorad -f

Check service status:

sudo systemctl status allorad

Check sync status:

curl -s http://localhost:26657/status | jq .result.sync_info.catching_up

Once this returns false, your node is fully synced.

Managing Upgrades with cosmosvisor

When a governance upgrade is approved, prepare for it by placing the new binary:

# For an upgrade named "v1.0.0", create the upgrade directory
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v1.0.0/bin
 
# Download and place the new binary (replace with actual URL)
# wget NEW_BINARY_URL -O $DAEMON_HOME/cosmovisor/upgrades/v1.0.0/bin/allorad
# chmod +x $DAEMON_HOME/cosmovisor/upgrades/v1.0.0/bin/allorad

Info: cosmosvisor will automatically switch to the new binary at the upgrade height specified in the governance proposal. Monitor governance proposals and prepare upgrade binaries in advance.

Method 2: Using `docker compose`

Running the Allora node with docker compose simplifies the setup and ensures consistency across different environments, but requires manual upgrade management.

Step 1: Clone the Allora Chain Repository

If you haven't already, clone the latest release of the allora-chain repository (opens in a new tab):

git clone https://github.com/allora-network/allora-chain.git

Step 2: Run the Node with Docker Compose

Navigate to the root directory of the cloned repository and start the node using docker compose:

cd allora-chain
docker compose pull
docker compose up

run docker compose up -d to run the container in detached mode, allowing it to run in the background.

Info: Don't forget to pull the images first, to ensure that you're using the latest images.

⚠️

Make sure that any previous containers you launched are killed, before launching a new container that uses the same port.

You can run the following command to kill any containers running on the same port:

docker container ls
docker rm -f <container-name>

Run Only a Node with Docker Compose

In this case, you will use Allora's heads.

Run

docker compose pull
docker compose up node

To run only a head: docker compose up head

NOTE: You also can comment the head service in the Dockerfile.

Monitoring Logs

To view the node's logs, use the following command:

docker compose logs -f

Executing RPC Calls

You can interact with the running node through RPC calls. For example, to check the node's status:

curl -s http://localhost:26657/status | jq .

This command uses curl to send a request to the node's RPC interface and jq to format the JSON response.

Once your node has finished syncing and is caught up with the network, this command will return false:

curl -so- http\://localhost:26657/status | jq .result.sync_info.catching_up

Info: The time required to sync depends on the chain's size and height.

For newly launched chains, syncing will take minutes.
Established chains like Ethereum can take around a day to sync using Nethermind or similar clients.
Some chains may take several days to sync.
Syncing an archival node will take significantly more time.

⚠️

Warning: Network participants will not be able to connect to your node until it is finished syncing and the command above returns false.

Syncing from Snapshot

Users can also opt to sync their nodes from our latest snapshot script (opens in a new tab) following the instructions below:

Install rclone (opens in a new tab), a command-line program to manage files on cloud storage

brew install rclone

Follow the instructions to configure rclone after running rclone config in the command line
Uncomment the following lines (opens in a new tab) from your Allora Chain repository:

# uncomment this block if you want to restore from a snapshot
# SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# "${SCRIPT_DIR}/restore_snapshot.sh"

Run the node using Docker:

docker compose pull
docker compose up -d

Deploy Allora Chain Stake a Validator