Running a Node - Paxeer Network Documentation

Overview

Running a Paxeer Network node allows you to interact with the network independently, verify transactions, and contribute to network decentralization.

Running a node requires technical knowledge and dedicated hardware resources. For most developers, using public RPC endpoints is sufficient.

Node Types

Full Node

Stores complete blockchain dataRequirements:

500GB+ SSD storage
16GB+ RAM
4+ CPU cores
Stable internet connection

Archive Node

Stores all historical statesRequirements:

2TB+ SSD storage
32GB+ RAM
8+ CPU cores
High-bandwidth connection

Prerequisites

Hardware Requirements

Minimum Specifications:

CPU: 4 cores
RAM: 16 GB
Storage: 500 GB SSD
Network: 100 Mbps

Recommended Specifications:

CPU: 8+ cores
RAM: 32 GB
Storage: 1 TB NVMe SSD
Network: 1 Gbps

Software Requirements

Docker and Docker Compose (recommended)
Or: Go 1.21+, Node.js 18+, Build tools
Linux/macOS/Windows with WSL2

Quick Start with Docker

The easiest way to run a node is using Docker:

Install Docker

# Linux
curl -fsSL https://get.docker.com | sh

# macOS
brew install --cask docker

Clone Node Repository

git clone https://github.com/paxeer/node
cd node

Configure Environment

.env

# Network Configuration
CHAIN_ID=229
NETWORK_NAME=paxeer

# RPC Endpoints
L1_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
L2_RPC_URL=https://public-rpc.paxeer.app/rpc

# Optional: Monitoring
METRICS_ENABLED=true
METRICS_PORT=7300

Start Node

docker-compose up -d

Verify Node is Running

# Check logs
docker-compose logs -f

# Check sync status
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

Running from Source

For advanced users who want to build from source:

Linux
macOS

# Install dependencies
sudo apt-get update
sudo apt-get install -y build-essential git

# Install Go
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Clone and build
git clone https://github.com/paxeer/pax-geth
cd pax-geth
make geth

# Run node
./build/bin/geth \
  --paxeer \
  --datadir ./datadir \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546

# Install dependencies
brew install go git

# Clone and build
git clone https://github.com/paxeer/pax-geth
cd pax-geth
make geth

# Run node
./build/bin/geth \
  --paxeer \
  --datadir ./datadir \
  --http \
  --http.addr localhost \
  --http.port 8545 \
  --http.api eth,net,web3

Node Configuration

Essential Flags

--paxeer                    # Run as Paxeer Network node
--datadir ./datadir         # Data directory location
--http                      # Enable HTTP-RPC server
--http.addr 0.0.0.0        # HTTP-RPC server listening interface
--http.port 8545           # HTTP-RPC server listening port
--http.api eth,net,web3    # API's offered over HTTP-RPC
--ws                        # Enable WebSocket-RPC server
--ws.addr 0.0.0.0          # WS-RPC server listening interface
--ws.port 8546             # WS-RPC server listening port

Optional Flags

--syncmode full            # Sync mode (full, snap)
--cache 4096              # Memory for internal caching (MB)
--maxpeers 50             # Maximum number of peers
--metrics                 # Enable metrics collection
--metrics.addr 0.0.0.0   # Metrics listening interface
--metrics.port 6060       # Metrics listening port

Monitoring Your Node

Health Checks

# Check if node is responding
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Check sync status
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

# Check peer count
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

Prometheus Metrics

If you enabled metrics, access them at:

http://localhost:6060/debug/metrics/prometheus

Key Metrics to Monitor:

chain_head_block - Current block height
p2p_peers - Number of connected peers
txpool_pending - Pending transactions
system_cpu_usage - CPU utilization
system_memory_usage - Memory usage

Grafana Dashboard

docker-compose.yml

services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

Maintenance

Updating Your Node

# With Docker
docker-compose pull
docker-compose up -d

# From source
cd pax-geth
git pull
make geth
# Restart node

Backing Up Data

# Stop node
docker-compose down

# Backup data directory
tar -czf paxeer-backup-$(date +%Y%m%d).tar.gz datadir/

# Restart node
docker-compose up -d

Pruning Old Data

# Stop node
docker-compose down

# Prune data (reduces size)
geth --datadir ./datadir snapshot prune-state

# Restart node
docker-compose up -d

Troubleshooting

Node Won't Sync

Symptoms: Sync stays at 0% or stuckSolutions:

Check internet connection
Verify L1 RPC endpoint is working
Check firewall isn’t blocking P2P ports (30303)
Try different L1 RPC provider
Check logs for errors: docker-compose logs -f

Out of Disk Space

Symptoms: Node stops, disk full errorsSolutions:

Add more storage
Prune old state data
Run a full node instead of archive node
Use external SSD for data directory

High Memory Usage

Symptoms: OOM errors, system slowdownSolutions:

Increase system RAM
Reduce cache size: --cache 2048
Limit max peers: --maxpeers 25
Check for memory leaks in logs

Peer Connection Issues

Symptoms: No peers, isolated nodeSolutions:

Check firewall settings
Open P2P port (30303 TCP/UDP)
Verify bootnodes are configured
Check NAT configuration

Using Your Node

Configure Applications

Point your applications to your local node:

import { ethers } from 'ethers';

// Use your local node
const provider = new ethers.JsonRpcProvider('http://localhost:8545');

// Verify connection
const blockNumber = await provider.getBlockNumber();
console.log('Connected! Current block:', blockNumber);

RPC Methods Available

Your node exposes these RPC methods:

eth_* - Ethereum JSON-RPC methods
net_* - Network information
web3_* - Web3 methods
debug_* - Debugging methods (if enabled)
txpool_* - Transaction pool inspection

Performance Optimization

SSD Optimization
Network Optimization
Cache Optimization

# Use NVMe SSD for best performance
# Mount with noatime for faster writes

# /etc/fstab
/dev/nvme0n1 /mnt/paxeer-data ext4 noatime 0 0

# Increase ulimit for network connections
ulimit -n 65536

# Optimize TCP settings
sysctl -w net.core.rmem_max=134217728
sysctl -w net.core.wmem_max=134217728

# Increase cache for better performance
geth --cache 8192  # 8GB cache

Security Best Practices

Security Checklist:

Use firewall to restrict RPC access
Don’t expose admin APIs publicly
Use HTTPS/WSS for remote access
Keep node software updated
Monitor for suspicious activity
Backup private keys separately
Use strong passwords
Enable fail2ban for SSH

Firewall Configuration

# Allow only specific IPs to access RPC
sudo ufw allow from YOUR_IP to any port 8545

# Allow P2P connections
sudo ufw allow 30303

# Enable firewall
sudo ufw enable

Resources

Node Repository

Official node implementation

Discord Support

Get help from the community

Status Page

Check network health

Explorer

Compare with network data

Guides

​Overview

​Node Types

Full Node

Archive Node

​Prerequisites

​Quick Start with Docker

​Running from Source

​Node Configuration

​Essential Flags

​Optional Flags

​Monitoring Your Node

​Health Checks

​Prometheus Metrics

​Grafana Dashboard

​Maintenance

​Updating Your Node

​Backing Up Data

​Pruning Old Data

​Troubleshooting

​Using Your Node

​Configure Applications

​RPC Methods Available

​Performance Optimization

​Security Best Practices

​Firewall Configuration

​Resources

Node Repository

Discord Support

Status Page

Explorer

Overview

Node Types

Prerequisites

Quick Start with Docker

Running from Source

Node Configuration

Essential Flags

Optional Flags

Monitoring Your Node

Health Checks

Prometheus Metrics

Grafana Dashboard

Maintenance

Updating Your Node

Backing Up Data

Pruning Old Data

Troubleshooting

Using Your Node

Configure Applications

RPC Methods Available

Performance Optimization

Security Best Practices

Firewall Configuration

Resources