🏗️ Validator Setup

Complete guide to setting up a full Arch Network validator node with Bitcoin Core and Titan indexer

Welcome to the validator setup guide! This guide will walk you through setting up a full Arch Network validator node. You can choose between an automated setup or manual configuration depending on your needs.

🎯 What You'll Build

🎯 Component Architecture

💡 Understanding Your Role

As a validator, you will:

Execute smart contracts and validate transactions
Participate in network consensus
Help secure the Bitcoin integration
Earn rewards for your contribution

📋 System Requirements

CPU: 4+ cores recommended
RAM: 16GB+ recommended
Storage: 100GB+ SSD for regtest, 500GB+ for testnet/mainnet
Network: Stable internet connection (10+ Mbps)
OS: Linux (Ubuntu 20.04+) or macOS (12.0+)

🚀 Setup Options

Choose your preferred setup method:

Option A: Automated Setup (Recommended)

The easiest way to get started using the CLI orchestrate command.

Prerequisites:

Docker: Required on all platforms - Install Docker
Docker Management (optional but recommended):
- macOS: OrbStack (recommended) or Docker Desktop
- Linux: Docker Desktop (optional GUI)
Arch Network CLI - Install using the System Requirements guide

Setup:

# 1. Download and install the Arch CLI
# (Download the appropriate binary for your platform from the releases page)

# 2. Start the complete validator stack
arch-cli orchestrate start

This automatically starts:

Bitcoin Core (regtest mode)
Titan indexer
Local validator
All necessary networking and configuration

The published local validator container is a Linux amd64 image. On Apple Silicon Macs, Docker must run it through linux/amd64 emulation; the arch-cli orchestrate start compose configuration pins this platform automatically.

Service URLs:

Bitcoin Core RPC: http://127.0.0.1:18443
Titan HTTP API: http://127.0.0.1:8080
Titan TCP/subscription endpoint: 127.0.0.1:3030
Validator RPC: http://127.0.0.1:9002

Management Commands:

# Stop all services
arch-cli orchestrate stop

# Restart only the local validator service
arch-cli orchestrate validator-restart

# Check local validator service status
arch-cli orchestrate validator-status

# Reset everything (clears all data)
arch-cli orchestrate reset

If the published local validator image is stale or fails at startup, run the local stack from a source checkout:

arch-cli orchestrate start --local /path/to/arch-network

Option B: Manual Setup

For advanced users who want full control over each component.

Step 1: Bitcoin Core Setup

Install Bitcoin Core:

# Download and install Bitcoin Core
# Visit https://bitcoincore.org/en/download/ for your platform

# For Ubuntu/Debian:
wget https://bitcoincore.org/bin/bitcoin-core-25.0/bitcoin-25.0-x86_64-linux-gnu.tar.gz
tar -xzf bitcoin-25.0-x86_64-linux-gnu.tar.gz
sudo cp bitcoin-25.0/bin/* /usr/local/bin/

Configure Bitcoin Core:

# Create Bitcoin data directory
mkdir -p ~/.bitcoin

# Create bitcoin.conf
cat > ~/.bitcoin/bitcoin.conf << EOF
# Network configuration
regtest=1
server=1
rpcuser=bitcoin
rpcpassword=bitcoinpass
rpcport=18443
rpcbind=127.0.0.1
rpcallowip=127.0.0.1

# Performance settings
dbcache=1000
maxmempool=2000
maxconnections=25

# Logging
debug=1
logtimestamps=1
logips=1
EOF

Start Bitcoin Core:

# Start Bitcoin Core in regtest mode
bitcoind -regtest -daemon

# Verify it's running
bitcoin-cli -regtest getblockchaininfo

Step 2: Titan Indexer Setup

Install Titan:

# Clone Titan repository
git clone https://github.com/saturnbtc/Titan.git
cd Titan

# Build Titan
cargo build --release

# Create Titan configuration
mkdir -p ~/.titan
cat > ~/.titan/config.toml << EOF
[network]
network = "regtest"

[bitcoin]
rpc_url = "http://bitcoin:bitcoinpass@127.0.0.1:18443"

[server]
http_addr = "127.0.0.1:8080"
tcp_addr = "127.0.0.1:3030"
EOF

Start Titan:

# Start Titan indexer
./target/release/titan --config ~/.titan/config.toml

Step 3: Arch Validator Setup

Install Arch Validator:

# From a checkout of the private Arch Network source repository:
cargo build --release -p validator

Configure Validator:

# Create validator data directory
mkdir -p ~/.arch_data

Start Validator:

# Start Arch validator from source with explicit local endpoints
cargo run --release -p validator -- \
  --network-mode devnet \
  --data-dir ~/.arch_data \
  --rpc-bind-port 9001 \
  --p2p-bind-port 29001 \
  --titan-endpoint http://127.0.0.1:8080 \
  --titan-socket-endpoint 127.0.0.1:3030

# Bitcoin Core regtest configuration
regtest=1
server=1
rpcuser=bitcoin
rpcpassword=bitcoinpass
rpcport=18443

# Generate blocks instantly for testing
bitcoin-cli -regtest generatetoaddress 100 $(bitcoin-cli -regtest getnewaddress)

Testnet Configuration

For testing with real Bitcoin testnet:

# Bitcoin Core testnet configuration
testnet=1
server=1
rpcuser=bitcoin
rpcpassword=bitcoinpass
rpcport=18332

# Connect to testnet
bitcoin-cli -testnet getblockchaininfo

🧪 Testing Your Setup

Verify Bitcoin Core

# Check Bitcoin Core status
bitcoin-cli -regtest getblockchaininfo

# Generate some test blocks
bitcoin-cli -regtest generatetoaddress 10 $(bitcoin-cli -regtest getnewaddress)

# Check balance
bitcoin-cli -regtest getbalance

Verify Titan Indexer

# Check Titan HTTP API
curl http://127.0.0.1:8080

# Get block information
curl http://127.0.0.1:8080/api/v1/blocks/latest

Verify Arch Validator

# Check validator readiness
curl -X POST http://127.0.0.1:9002 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "is_node_ready", "params": []}'

# Get validator version
curl -X POST http://127.0.0.1:9002 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "get_version", "params": []}'

🚨 Troubleshooting

Common Issues

Bitcoin Core won't start:

# Check if port is already in use
netstat -tulpn | grep 18443

# Kill existing process
pkill bitcoind

# Check Bitcoin Core logs
tail -f ~/.bitcoin/regtest/debug.log

Titan connection issues:

# Verify Bitcoin RPC connection
curl -u bitcoin:bitcoinpass http://127.0.0.1:18443

# Check Titan logs
tail -f ~/.titan/logs/titan.log

Validator startup problems:

# Verify all dependencies are running
arch-cli orchestrate validator-status

Performance Optimization

For better performance:

# Increase Bitcoin Core cache
echo "dbcache=2000" >> ~/.bitcoin/bitcoin.conf

# Optimize Titan settings
echo "max_connections=100" >> ~/.titan/config.toml

# Restart local validator service
arch-cli orchestrate validator-restart

Check the logs for error messages
Verify all services are running correctly
Join our Discord for community support
Review the troubleshooting guide for common solutions
Submit an issue on GitHub if you find a bug

Welcome to the Arch Network validator community! 🎉

🏗️ Validator Setup

🎯 What You'll Build

🎯 Component Architecture

💡 Understanding Your Role

📋 System Requirements

🚀 Setup Options

Option A: Automated Setup (Recommended)

Option B: Manual Setup

Step 1: Bitcoin Core Setup

Step 2: Titan Indexer Setup

Step 3: Arch Validator Setup

🔧 Configuration Options

Network Modes

Regtest (Development)

Testnet (Testing)

Mainnet (Production)

Regtest Configuration

Testnet Configuration

🧪 Testing Your Setup

Verify Bitcoin Core

Verify Titan Indexer

Verify Arch Validator

🚨 Troubleshooting

Common Issues

Performance Optimization

📚 Next Steps

Deploy Your First Program

Understanding Architecture

Bitcoin Integration

Join the Community

🆘 Getting Help

On this page