Skip to main content

Full Node - Binary (~30 min)

Full Node Walkthrough via Binary ​

🧑‍🔬 Detailed step-by-step instructions to get you up and running with a Full Node on Pocket Network ✅

recommended for advanced linux users only

See the Full Node Cheat Sheet if you want to just copy-pasta a few commands.

These instructions are intended for Debian-based systems.

Table of Contents ​

Why run a Full Node?​

This guide will walk you through, step-by-step, running a Full Node for Pocket Network.

Running a Full Node is the first step toward becoming a Validator, Supplier, or Gateway.

The instructions outlined here use Cosmovisor to enable automatic binary upgrades.

Pre-Requisites & Requirements​

  1. Linux-based System: Preferably Debian-based distributions (Ubuntu, Debian).
  2. Hardware Requirements: See the hardware requirements doc
  3. Architecture Support: Both x86_64 (amd64) and ARM64 architectures are supported.
  4. Root or Sudo Access: Administrative privileges are required.
  5. Dedicated Server or Virtual Machine: Any provider is acceptable.
Vultr Playbook

If you are using Vultr for your deployment, you can following the CLI Playbook we put together here to speed things up.

Instructions​

1. Install Dependencies​

Install all the necessary CLI tools:

sudo apt-get update
sudo apt-get install -y curl tar wget jq zstd aria2
Snapshot specific tooling

zstd is required for snapshot compression/decompression.

aria2 is needed for efficient torrent downloads if you choose to sync from a snapshot.

2. Create a New User​

Create a dedicated user to run pocketd:

sudo adduser pocket

Set a password when prompted, and add the user to the sudo group:

sudo usermod -aG sudo pocket

And switch to the pocket user:

sudo su - pocket

3. Set Up Environment Variables for Cosmovisor​

Create a .pocketrc file and set the following environment variables:

cat > ~/.pocketrc << 'EOF'
export DAEMON_NAME=pocketd
export DAEMON_HOME=$HOME/.pocket
export DAEMON_RESTART_AFTER_UPGRADE=true
export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
export UNSAFE_SKIP_BACKUP=false
export PATH=$HOME/.local/bin:$HOME/.pocket/cosmovisor/current/bin:$PATH
EOF

echo "source ~/.pocketrc" >> ~/.profile
source ~/.profile

4. Install Cosmovisor​

Alternative Instructions to install Cosmovisor

You can follow the official Cosmovisor installation instructions here.

Cosmovisor manages the binary upgrades for your node. Use the commands below to download and install Cosmovisor.

Determine your architecture:

mkdir -p $HOME/.local/bin
COSMOVISOR_VERSION="v1.7.1"
ARCH=$(uname -m)
if [ "$ARCH" = "x86_64" ]; then
    ARCH="amd64"
elif [ "$ARCH" = "aarch64" ]; then
    ARCH="arm64"
fi

Download and install Cosmovisor:

curl -L "https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2F${COSMOVISOR_VERSION}/cosmovisor-${COSMOVISOR_VERSION}-linux-${ARCH}.tar.gz" | tar -zxvf - -C $HOME/.local/bin

Verify the installation:

cosmovisor help

5. Retrieve the Genesis File​

Genesis files and network configuration are stored in the pokt-network/pocket-network-genesis repository. This repository contains the official chain information for all Pocket Network chains.

Choose a network to join from the tabs below:

# Set network to testnet-beta (stable testing network)
NETWORK="testnet-beta"

# Create config directory if it doesn't exist
mkdir -p $HOME/.pocket/config

# Download genesis file from URL
GENESIS_FILE_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/${NETWORK}/genesis.json"
curl -s -o $HOME/.pocket/config/genesis.json "$GENESIS_FILE_URL"

# Extract initial version of pocketd to start synching from genesis
POCKETD_GENESIS_VERSION=$(jq -r '.app_version' < $HOME/.pocket/config/genesis.json)

6. Choose Sync Method: Genesis vs Snapshot​

Before installing pocketd, you need to decide whether to sync from genesis or use a snapshot. This decision will determine which version of pocketd to install.

As the sync progresses from genesis (i.e. block zero) to the latest (i.e. current) height, Cosmosvisor automatically updates the pocketd binary to the latest/necessary version at each particular height as a function of the network’s upgrade plan

The following diagram illustrates the two sync path with arbitrary version and height numbers:

6.1 [Slow & Not Recommended] Sync from Genesis​

The (static) genesis file contains the required initial version of pocketd to start syncing from genesis.

POCKETD_VERSION=$POCKETD_GENESIS_VERSION
echo "Sync from genesis will use the following version of pocketd as a starting point: $POCKETD_VERSION"

6.2 [Fast & Recommended] Sync from Snapshot​

Snapshot Explorer

You can visit snapshots.us-nj.poktroll.com directly in your browser to explore available snapshots.

If you prefer to use a snapshot (recommended for faster setup), you need to check the snapshot version first:

echo "############################################"

# Base URL for snapshots
SNAPSHOT_BASE_URL="https://snapshots.us-nj.poktroll.com"

# Get latest snapshot information for testnet-beta
LATEST_SNAPSHOT_HEIGHT=$(curl -s "$SNAPSHOT_BASE_URL/testnet-beta-latest-archival.txt")
echo "Latest snapshot height: $LATEST_SNAPSHOT_HEIGHT"

# Get snapshot version (important for compatibility)
SNAPSHOT_VERSION=$(curl -s "$SNAPSHOT_BASE_URL/testnet-beta-${LATEST_SNAPSHOT_HEIGHT}-version.txt")
echo "Snapshot version: $SNAPSHOT_VERSION"

# Store the torrent URL for later use
TORRENT_URL="${SNAPSHOT_BASE_URL}/testnet-beta-latest-archival.torrent"

# Set the version to use for installation
POCKETD_VERSION=$SNAPSHOT_VERSION
echo "Sync from snapshot will use the following version of pocketd as a starting point: $POCKETD_VERSION"

echo "############################################"

Then download the snapshot via torrent and apply it to your node:

Snapshot Download

This can take 10-20 minutes depending on your network speed.

Make sure you review the disk space requirements at the top of this guide before proceeding.

# Create a directory for the snapshot download
SNAPSHOT_DIR="$HOME/pocket_snapshot"
mkdir -p "$SNAPSHOT_DIR" "$HOME/.pocket/data"
cd "$SNAPSHOT_DIR"

# Download via torrent
aria2c --seed-time=0 --file-allocation=none --continue=true \
       --max-connection-per-server=4 --max-concurrent-downloads=16 --split=16 \
       --bt-enable-lpd=true --bt-max-peers=100 --bt-prioritize-piece=head,tail \
       --bt-seed-unverified \
       "$TORRENT_URL"

# Find the downloaded file
DOWNLOADED_FILE=$(find . -type f -name "*.tar.*" | head -n 1)

# Extract the snapshot
if [[ "$DOWNLOADED_FILE" == *.tar.zst ]]; then
    echo "Extracting .tar.zst snapshot..."
    zstd -d "$DOWNLOADED_FILE" --stdout | tar -xf - -C $HOME/.pocket/data
elif [[ "$DOWNLOADED_FILE" == *.tar.gz ]]; then
    echo "Extracting .tar.gz snapshot..."
    tar -zxf "$DOWNLOADED_FILE" -C $HOME/.pocket/data
else
    echo "Unknown snapshot format: $DOWNLOADED_FILE"
    exit 1
fi

# Clean up
cd $HOME
rm -rf "$SNAPSHOT_DIR"

echo "###"
echo "Snapshot applied successfully"
echo "###"

7. Install pocketd​

Now that we've determined the correct version to use, we can install pocketd:

# Determine your OS type and architecture
OS_TYPE=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
if [ "$ARCH" = "x86_64" ]; then
    ARCH="amd64"
elif [ "$ARCH" = "aarch64" ]; then
    ARCH="arm64"
fi

# Download and install pocketd with the version determined in the previous step
RELEASE_URL="https://github.com/pokt-network/poktroll/releases/download/v${POCKETD_VERSION}/pocket_${OS_TYPE}_${ARCH}.tar.gz"
mkdir -p $HOME/.pocket/cosmovisor/genesis/bin
curl -L "$RELEASE_URL" | tar -zxvf - -C $HOME/.pocket/cosmovisor/genesis/bin
chmod +x $HOME/.pocket/cosmovisor/genesis/bin/pocketd

# Verify the installation
$HOME/.pocket/cosmovisor/genesis/bin/pocketd version

# Initialize Cosmovisor with the pocketd binary
cosmovisor init $HOME/.pocket/cosmovisor/genesis/bin/pocketd
Cosmosvisor pocketd symlinks

The cosmovisor init command creates the necessary directory structure and symlinks and you can now use the pocketd command directly.

8. Network Configuration​

Initialize your node and configure it to connect to the network:

# Extract chain-id from existing genesis
CHAIN_ID=$(jq -r '.chain_id' < $HOME/.pocket/config/genesis.json)

# Initialize the node with your chosen moniker (node name)
pocketd init "YourNodeMoniker" --chain-id="$CHAIN_ID" --home=$HOME/.pocket

# Get seeds from the official repository
SEEDS_URL="https://raw.githubusercontent.com/pokt-network/pocket-network-genesis/master/shannon/testnet-beta/seeds"
SEEDS=$(curl -s "$SEEDS_URL")
sed -i -e "s|^seeds *=.*|seeds = \"$SEEDS\"|" $HOME/.pocket/config/config.toml

# Configure external address for P2P communication
EXTERNAL_IP=$(curl -s https://api.ipify.org)
sed -i -e "s|^external_address *=.*|external_address = \"${EXTERNAL_IP}:26656\"|" $HOME/.pocket/config/config.toml

9. Set Up systemd Service​

Create a systemd service to manage your node. You can customize the service name if you plan to run multiple nodes:

# Set a service name (change if running multiple nodes)
SERVICE_NAME="cosmovisor-pocket"  # or another name like "cosmovisor-testnet"

# Store the current username for use in the service file
USERNAME=$(whoami)

sudo tee /etc/systemd/system/${SERVICE_NAME}.service > /dev/null <<EOF
[Unit]
Description=Cosmovisor daemon for pocketd
After=network-online.target

[Service]
User=${USERNAME}
ExecStart=/home/${USERNAME}/.local/bin/cosmovisor run start --home=/home/${USERNAME}/.pocket
Restart=always
RestartSec=3
LimitNOFILE=infinity
LimitNPROC=infinity
Environment="DAEMON_NAME=pocketd"
Environment="DAEMON_HOME=/home/${USERNAME}/.pocket"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true"
Environment="UNSAFE_SKIP_BACKUP=true"

[Install]
WantedBy=multi-user.target
EOF

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable ${SERVICE_NAME}.service
sudo systemctl start ${SERVICE_NAME}.service

10. Configure your Firewall​

To ensure your node can properly participate in the P2P network, you need to make port 26656 accessible from the internet. This is essential for communication with other nodes.

Choose the appropriate method for your system:

  1. [Required] Using UFW:

    # [REQUIRED] Expose P2P
    sudo ufw allow 26656/tcp

  2. Using iptables:

    sudo iptables -A INPUT -p tcp --dport 26656 -j ACCEPT
    sudo iptables-save > /etc/iptables/rules.v4  # Save rules (may require iptables-persistent package)

  3. Cloud Provider Settings: If running on a cloud provider (AWS, GCP, Azure, etc.), configure security groups or firewall rules to allow inbound traffic on port 26656.

  4. Verify your port is accessible:

  • Install netcat if not already installed

    sudo apt install -y netcat
    # OR
    sudo apt install netcat-openbsd

  • Use an external service to check port accessibility

    nc -zv portquiz.net 26656

  • Alternatively, have someone from outside check your port:

    nc -zv YOUR_EXTERNAL_IP 26656

11. Check & Monitor the Status of your Node​

View service status (e.g. SERVICE_NAME=cosmovisor-pocket):

sudo systemctl status ${SERVICE_NAME}

View logs in real-time (e.g. SERVICE_NAME=cosmovisor-pocket):

sudo journalctl -u ${SERVICE_NAME} -f

Check sync status using pocketd:

pocketd status | jq '.sync_info.catching_up'

Your node is fully synced when catching_up is false.

tip

Consider visiting one of our explores to compare their block height against yours, which you can query via:

pocketd status | jq '.sync_info.latest_block_height'

Next Steps​

You have now successfully set up a Full Node on the Pocket Network! This node can be used as a foundation to set up a validator, supplier, or gateway in the future.