Setting Up a Provider

This guide walks you through setting up your Arkeo Provider—from bonding your service on-chain, to configuring metadata, running your backend (sentinel), and automating settlement. You do not need to be a validator or run a full node to be a provider, though running your own node is strongly recommended for reliability.

Before You Begin

What You Need

• Arkeo Accounts:

  • Hot Wallet (automated settlement key created with keyring-backend test).

  • (Optional) Secure cold storage account for larger funds.

• Arkeo CLI Tools installed (from GitHub).

• Server or reliable machine for running your backend (sentinel).

• Recommended: A full node for complete control over blockchain events and reliable settlements.

Install Arkeo Tools

git clone https://github.com/arkeonetwork/arkeo.git  
cd arkeo  
make install  
make tools

This installs the arkeod CLI and related tools.

Best Practice: Although no full chain sync is required for basic operations, running your own node is highly recommended. Doing so ensures full control over blockchain events critical for timely settlements, avoiding reliance on third-party RPC services.

Create a Hot Wallet (Automated Key)

Providers automate claim settlements using a dedicated "hot wallet":

arkeod keys add <provider-hot-wallet> --keyring-backend test

• Fund this wallet only with minimal amounts required for bonding and fees.

Security Notice:

• The test backend stores your keys unencrypted; use it only for automated scripts.

• Never use this wallet for significant funds.

Arkeo Supported Services

Use either of these services for a comprehensive reference mapping between service names and their numeric identifiers, as used within Arkeo.

arkeod query arkeo all-services

http://localhost:1317/arkeo/services

Bond Your Provider Service On-Chain

Bonding stakes collateral and registers your service.

No Validator privileges are required to be a Provider.

Each time you run the BOND script, you will add in more tokens- so be aware that the bond will keep increasing.

Just add a negative bond amount to UNBOND tokens, and UNBOND all tokens to remove your provider.

The Bond is implemented so that providers have skin in the game and can be docked for bad behavior or performance. This functionality will be worked into the system soon.

Usage:

./provider_bond_4.sh arkeo-mainnet-fullnode

#!/bin/bash

if [ -z "$1" ]; then
  echo "Usage: $0 <SERVICE>"
  exit 1
fi
SERVICE="$1"

USER="Arkeo-Main-Validator-1"
BOND=100000000
KEYRING_BACKEND="test"
FEES="200uarkeo"

# Get raw public key
RAWPUBKEY=$(arkeod keys show "$USER" -p --keyring-backend="$KEYRING_BACKEND" | jq -r .key)

# Convert to Bech32 pubkey
PUBKEY=$(arkeod debug pubkey-raw $RAWPUBKEY | grep 'Bech32 Acc:' | sed "s|Bech32 Acc: ||g")

#echo "Using USER: $USER"
#echo "RAW PUBKEY: $RAWPUBKEY"
#echo "PUBKEY: $PUBKEY"
#echo "SERVICE: $SERVICE"
#echo "KEYRING_BACKEND: $KEYRING_BACKEND"
#echo "FEES: $FEES"
#echo "BOND: $BOND"

echo "Bonding provider service '$SERVICE'..."

# Bond the provider
arkeod tx arkeo bond-provider \
  --from="$USER" --fees="$FEES" --keyring-backend="$KEYRING_BACKEND" -b sync -y \
  "$PUBKEY" "$SERVICE" -- "$BOND"

if [ $? -ne 0 ]; then
  echo "Error: Provider bonding transaction failed."
  exit 1
else
  echo "Provider bonding transaction submitted successfully."
fi

Configure Provider Metadata

Make your service discoverable and configure contract terms:

The Nonce is cosmetic, and not required to be incremented like in Contracts.

Usage:

./provider_mod_4.sh arkeo-mainnet-fullnode 1 1 200uarkeo 200uarkeo

#!/bin/bash

# Usage check for required arguments
if [ "$#" -lt 5 ]; then
  echo "Usage: $0 <SERVICE> <METADATA_NONCE> <STATUS> <SUBSCRIPTION_RATES> <PAY_AS_YOU_GO_RATES>"
  exit 1
fi
SERVICE="$1"
METADATA_NONCE="$2"
STATUS="$3"
SUBSCRIPTION_RATES="$4"
PAY_AS_YOU_GO_RATES="$5"

KEY="Arkeo-Main-Validator-1"
SENTINEL_URI="http://127.0.0.1:3636/metadata.json"
MIN_CONTRACT_DUR=5
MAX_CONTRACT_DUR=432000
SETTLEMENT_DUR=100
KEYRING_BACKEND="test"
FEES="200uarkeo"

# Get raw public key
RAWPUBKEY=$(arkeod keys show "$KEY" -p --keyring-backend="$KEYRING_BACKEND" | jq -r .key)

# Convert to Bech32 pubkey
PUBKEY=$(arkeod debug pubkey-raw $RAWPUBKEY | grep 'Bech32 Acc:' | sed "s|Bech32 Acc: ||g")

echo "Modifying provider for service '$SERVICE'..."

# Mod the provider
arkeod tx arkeo mod-provider \
"$PUBKEY" \
"$SERVICE" \
"$SENTINEL_URI" \
"$METADATA_NONCE" \
"$STATUS" \
"$MIN_CONTRACT_DUR" \
"$MAX_CONTRACT_DUR" \
"$SUBSCRIPTION_RATES" \
"$PAY_AS_YOU_GO_RATES" \
"$SETTLEMENT_DUR" \
--from="$KEY" \
--fees="$FEES" \
--keyring-backend="$KEYRING_BACKEND" \
-y

if [ $? -ne 0 ]; then
  echo "Error: Provider modification transaction failed."
  exit 1
else
  echo "Provider modification transaction submitted successfully."
fi

Provider Bond + Mod Looping Add/Update Script

This is a fast onboarding script to setup multiple providers at once, quickly.

#!/bin/bash

# Paths to your scripts (edit if needed)
BOND_SCRIPT="./provider_bond_4.sh"
MOD_SCRIPT="./provider_mod_4.sh"
SERVICES_API_URL="http://localhost:1317/arkeo/services"

# SERVICE_TYPES contains lines of: SERVICE METADATA_NONCE STATUS SUBSCRIPTION_RATES PAY_AS_YOU_GO_RATES
# Example:
#   "akash-mainnet-fullnode 1 1 200uarkeo 200uarkeo"
# Where:
#   SERVICE            = the service type string
#   METADATA_NONCE     = integer metadata nonce for this service
#   STATUS             = 1 (ONLINE) or 0 (OFFLINE)
#   SUBSCRIPTION_RATES = e.g., 200uarkeo
#   PAY_AS_YOU_GO_RATES= e.g., 200uarkeo

SERVICE_TYPES=(
  "btc-mainnet-fullnode 1 1 200uarkeo 200uarkeo"
)

for SERVICE_ENTRY in "${SERVICE_TYPES[@]}"; do
  set -- $SERVICE_ENTRY
  SERVICE="$1"
  METADATA_NONCE="$2"
  STATUS="$3"
  SUBSCRIPTION_RATES="$4"
  PAY_AS_YOU_GO_RATES="$5"

  echo ""

  BOND_OUTPUT=$($BOND_SCRIPT "$SERVICE")
  echo "$BOND_OUTPUT"
  echo ""
  BOND_TXHASH=$(echo "$BOND_OUTPUT" | grep "txhash:" | awk '{print $2}')
  if [ -n "$BOND_TXHASH" ]; then
    sleep 6
    echo "Querying bond transaction $BOND_TXHASH ..."
    arkeod query tx $BOND_TXHASH
  else
    echo "No transaction hash found for bond."
  fi
  if [ $? -ne 0 ]; then
    echo "Bonding failed for $SERVICE. Skipping modification."
    continue
  fi

  echo ""

  MOD_OUTPUT=$($MOD_SCRIPT "$SERVICE" $METADATA_NONCE $STATUS "$SUBSCRIPTION_RATES" "$PAY_AS_YOU_GO_RATES")
  echo "$MOD_OUTPUT"
  echo ""
  MOD_TXHASH=$(echo "$MOD_OUTPUT" | grep "txhash:" | awk '{print $2}')
  if [ -n "$MOD_TXHASH" ]; then
    sleep 6
    echo "Querying mod transaction $MOD_TXHASH ..."
    arkeod query tx $MOD_TXHASH
  else
    echo "No transaction hash found for mod."
  fi
  if [ $? -ne 0 ]; then
    echo "Modification failed for $SERVICE."
  fi

done

SERVICES_JSON=$(curl -s $SERVICES_API_URL)

# Now output YAML config block for all service types
echo ""
echo "services:"
for SERVICE_ENTRY in "${SERVICE_TYPES[@]}"; do
  set -- $SERVICE_ENTRY
  SERVICE="$1"
  CHAIN_TYPE=$(echo "$SERVICE" | cut -d'-' -f1)
  SERVICE_ID=$(echo "$SERVICES_JSON" | jq ".services[] | select(.name==\"$SERVICE\") | .service_id")
  echo "  - name: $SERVICE"
  echo "    id: $SERVICE_ID"
  echo "    type: $CHAIN_TYPE"
  echo "    rpc_url: http://127.0.0.1:26657"
  echo "    rpc_user:"
  echo "    rpc_pass:"
done

Provider and Sentinel Configuration

Example sentinel_config.yaml:

provider:
pubkey: "<your-bech32-pubkey>"
name: "My Arkeo Provider"

services:
- name: btc-mainnet-fullnode
  id: 10
  type: bitcoin
  rpc_url: http://localhost:8332
  rpc_user: "<rpc-username>"
  rpc_pass: "<rpc-password>"

api:
listen_addr: "0.0.0.0:3636"

Run Sentinel

Create and enable sentinel.service with systemd:

[Unit]
Description=Arkeo Sentinel (Provider)
After=network-online.target

[Service]
User=<your-os-user>
WorkingDirectory=/home/<your-os-user>
ExecStart=/home/<your-os-user>/go/bin/sentinel --config /home/<your-os-user>/sentinel_config.yaml
Restart=on-failure
RestartSec=5
LimitNOFILE=65535
Environment="CLAIM_STORE_LOCATION=/home/<your-os-user>/.arkeo/claims"
Environment="CONTRACT_CONFIG_STORE_LOCATION=/home/<your-os-user>/.arkeo/contract_configs"
Environment="DESCRIPTION=Arkeo Core Multi-Provider: Core Provider of Blockchain Nodes and Indexers."
Environment="EVENT_STREAM_HOST=127.0.0.1:26657"
Environment="FREE_RATE_LIMIT=10"
Environment="LOCATION=USA, West Coast"
Environment="LOG_LEVEL=debug"
Environment="MONIKER=arkeo-core-multi-provider"
Environment="PORT=3636"
Environment="PROVIDER_CONFIG_STORE_LOCATION=/home/<your-os-user>/.arkeo/provider_configs"
Environment="PROVIDER_HUB_URI=http://127.0.0.1:1317"
Environment="PROVIDER_PUBKEY=<your-bech32-pubkey>"
Environment="SOURCE_CHAIN=arkeo-main-v2"
Environment="WEBSITE=https://arkeo.network"

[Install]
WantedBy=multi-user.target

Activate the service:

sudo systemctl daemon-reload
sudo systemctl enable --now sentinel

Automate Settlements

Set up your settlement script to use the "hot wallet" (keyring-backend test) for automated signing:

• Do not store hot wallet mnemonics in plain text or public repositories.

• Regularly monitor hot wallet transactions and balances.

Monitoring and Verification

Check provider status:

arkeod query arkeo show-provider <your-bech32-pubkey>

Metadata API:

curl http://localhost:3636/metadata.json

Logs:

journalctl -u sentinel -f

Additional Recommendations

• Run your own full node for reliable and timely event processing.

• Limit reliance on third-party RPC providers to maintain control over settlements.

• Rotate and audit hot wallet keys regularly.