Validator Guide

Run a MoltChain validator node to participate in consensus, produce blocks, and earn staking rewards. This guide covers hardware requirements, installation, configuration, staking, monitoring, and production deployment.

Requirements

Hardware

Operating System

• Production: Linux — Ubuntu 22.04 LTS or newer (Debian, RHEL 9+ also supported)
• Development: macOS (Apple Silicon or Intel)

Network Ports

Installation

Option A: Quick Start (Recommended)

Clone the repository, build, and start a validator in one go:

git clone https://github.com/moltchain/moltchain.git
cd moltchain
./moltchain-start.sh testnet

The start script will automatically build the binary, create genesis (if this is the first validator), deploy all 27 smart contracts, seed AMM pools, and fund the insurance reserve. Everything is idempotent — run it again and it picks up where it left off.

Port Assignments

You can run both testnet and mainnet on the same machine — they use different ports and separate data directories.

Joining an Existing Network

To join a network with existing validators, pass a bootstrap peer:

./moltchain-start.sh testnet --bootstrap seed1.moltchain.io:7001

Stop / Restart

# Stop
./moltchain-stop.sh testnet

# Full reset (wipe all state and start fresh)
./reset-blockchain.sh testnet
./moltchain-start.sh testnet

Option B: Build from Source (Manual)

If you prefer manual control, build the binary and run it directly. Requires Rust 1.75+ stable toolchain.

git clone https://github.com/moltchain/moltchain.git
cd moltchain
cargo build --release

# Start — the built-in supervisor auto-restarts on stalls/crashes
./target/release/moltchain-validator \
    --network testnet \
    --rpc-port 8899 \
    --ws-port 8900 \
    --p2p-port 7001 \
    --db-path ./data/state-testnet-7001

# Disable the supervisor (e.g. when using systemd Restart=on-failure)
./target/release/moltchain-validator --no-watchdog \
    --network testnet --rpc-port 8899 --p2p-port 7001

Option C: Docker

docker-compose up validator

See the Docker Deployment section below for full details.

Initialize Validator Identity

Generate a validator keypair. This Ed25519 key is your node's on-chain identity. The start script does this automatically, but you can also do it manually:

molt init --output ~/.moltchain/validator-keypair.json

 New validator keypair generated
  Identity: Mo1tVa1idAtoR...xYz789
  Saved to: ~/.moltchain/validator-keypair.json

Configuration

MoltChain validators are currently configured via CLI flags when starting the binary. The section labels below (for example [network] and [rpc]) are conceptual groupings for readability, not literal TOML sections consumed by the validator today. A real config.toml input format is planned for a future release.

[validator]

Core validator identity and data paths.

[network]

Peer-to-peer networking and gossip settings.

[consensus]

BFT consensus and staking parameters.

[graduation]

Validator graduation and anti-fraud settings (CLI flags).

[rpc]

JSON-RPC server configuration.

[logging]

Logging verbosity and output targets.

[monitoring]

Prometheus metrics and health checks.

[genesis]

Genesis block and chain identity.

[performance]

Tuning options for throughput and resource usage.

[security]

Security hardening and access control.

[watchdog]

Built-in self-healing supervisor. The validator automatically monitors itself for stalls (deadlocks, resource exhaustion) and restarts when needed. No external scripts or cron jobs required — just run the binary.

Staking

Validators must stake MOLT tokens to participate in consensus. Stake weight determines your share of block production slots and rewards.

Stake via CLI

$ molt validator register --rpc-url https://testnet-rpc.moltchain.io

 Registering validator Mo1tVa1idAtoR...xYz789

  Transaction: 5bN2...kQrT
  Bootstrap:   100,000.000000000 MOLT (granted, #47 of 200)
  Debt:        100,000.000000000 MOLT (repay via 50% of rewards, or 75% at ≥95% uptime)
  Uptime:      98.5% (≥ 95% → 75/25 debt/liquid split)
  Status:      Finalized (slot 1,204,817)

 Validator registered! Your node will enter the active set next epoch.

Minimum Stake

• Bootstrap Grant (first 200 validators): 100,000 MOLT (100,000,000,000,000 shells) — new validators receive this at $0 cost from the treasury
• Self-funded (validator 201+): Must provide your own 75,000 MOLT minimum — immediately fully vested, no debt
• Vesting (standard): 50% of earned rewards go to debt repayment, 50% liquid — this is the default split for all bootstrap validators
• Performance bonus (≥95% uptime): 75% of earned rewards go to debt repayment, 25% liquid — accelerates graduation by ~1.5× (via PERFORMANCE_BONUS_BPS = 15000)
• Time cap: All remaining debt is forgiven after 547 days (~18 months) regardless of repayment progress

Graduation System

Bootstrap validators go through a graduation process from Bootstrapping to FullyVested:

Uptime Calculation

Uptime is calculated in basis points (0–10,000 = 0%–100%) based on actual block production vs. expected share:

expected_blocks = (current_slot - start_slot) / num_active_validators
uptime_bps      = min(10000, blocks_produced × 10000 / expected_blocks)

• Fair share: With N active validators, each one is expected to produce 1/N of total blocks. A validator that produces its full share has 100% uptime (10,000 bps).
• Threshold: ≥ 9,500 bps (95%) triggers the performance bonus (75/25 split).
• Edge cases: New validators with no slot history default to 0 bps. If fewer slots have elapsed than validators exist, validators with at least 1 block get benefit of the doubt (10,000 bps).

Anti-Sybil Protection

Each validator collects a machine fingerprint (SHA-256 hash of platform UUID + MAC address) at startup. This fingerprint is:

• Included in & signed with validator announcements
• Registered in the stake pool — one fingerprint per bootstrap validator
• Prevents running 50 validators on one machine to steal 50 bootstrap grants

Rule: One machine = one bootstrap grant. Self-funded validators (201+) are not restricted by fingerprint.

ReefStake Mechanism

MoltChain uses ReefStake, a delegated proof-of-stake variant inspired by coral reef ecosystems:

• Validator Coral: Each validator is a "coral head." Delegators attach stake to a validator, growing the reef.
• Epoch Rotation: The active validator set is recalculated every epoch (~4 hours). The top validators by total stake are selected.
• Reward Distribution: Block rewards (heartbeat + transaction fees) are split proportionally between the validator (commission) and delegators.
• Slashing: Double-signing or extended downtime results in a percentage of staked MOLT being burned. With enable_slashing = true, evidence is gossiped via P2P and processed by the SlashingTracker.

Check Stake Status

$ molt stake status --rpc-url https://testnet-rpc.moltchain.io

  Identity:    Mo1tVa1idAtoR...xYz789
  Stake:       100,000.000000000 MOLT (bootstrap)
  Delegated:   450.000000000 MOLT
  Total:       100,450.000000000 MOLT
  Active:      Yes (rank #7 of 21)
  Commission:  10%
  Last Vote:   slot 1,205,142

Monitoring

Prometheus Metrics

When [monitoring] enable_metrics = true, the validator exposes a Prometheus-compatible endpoint at http://<host>:9100/metrics.

Key Metrics

# Fetch metrics
curl -s http://localhost:9100/metrics | grep moltchain_

# Example output
moltchain_block_height 1205247
moltchain_tps 842
moltchain_peer_count 18
moltchain_mempool_size 127

Health Check

The RPC server provides a health check via the getHealth JSON-RPC method:

curl -s http://localhost:8899 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

# Response: {"jsonrpc":"2.0","result":"ok","id":1}

Log Levels

Control verbosity with the RUST_LOG environment variable or the [logging] level config key:

# Per-module granularity via RUST_LOG
RUST_LOG=info,moltchain_p2p=debug,moltchain_rpc=warn moltchain-validator

# Or set in config.toml
# [logging]
# level = "debug"
# log_format = "json"

Docker Deployment

The recommended production deployment uses Docker Compose. The provided docker-compose.yml runs the validator, faucet, and optional explorer.

version: "3.8"

services:
  validator:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: moltchain-validator
    restart: unless-stopped
    ports:
      - "7001:7001"   # P2P (testnet)
      - "8899:8899"   # RPC (testnet)
      - "8900:8900"   # WebSocket (testnet)
      - "9100:9100"   # Metrics
    volumes:
      - moltchain-data:/var/lib/moltchain
    environment:
      - RUST_LOG=info
      - MOLTCHAIN_NETWORK=testnet
      - MOLTCHAIN_RPC_PORT=8899
      - MOLTCHAIN_WS_PORT=8900
      - MOLTCHAIN_P2P_PORT=7001
      - MOLTCHAIN_SIGNER_BIND=0.0.0.0:9201
      - MOLTCHAIN_ADMIN_TOKEN=${MOLTCHAIN_ADMIN_TOKEN:-}
    networks:
      - moltchain
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8899/ -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getHealth\"}' -H 'Content-Type: application/json' || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  moltchain-data:
    driver: local

networks:
  moltchain:
    driver: bridge

Volume Mounts

Running

# Start in foreground (see logs)
docker-compose up validator

# Start in background
docker-compose up -d validator

# View logs
docker-compose logs -f validator

# Stop
docker-compose down

Health Check

Docker will automatically restart the validator if the getHealth RPC call fails 3 consecutive times. The start_period: 15s gives the node time to initialize before checks begin.

Systemd Deployment

For bare-metal Linux servers, use the provided setup script to install a systemd service per network.

Setup Script

Run the setup script as root. It accepts one or both network names:

# Build first
cargo build --release

# Setup for testnet only
sudo bash deploy/setup.sh testnet

# Setup for both networks on the same machine
sudo bash deploy/setup.sh testnet mainnet

The script performs:

• Creates a dedicated moltchain system user/group (no login shell)
• Creates directories: /etc/moltchain, /var/lib/moltchain, /var/log/moltchain
• Copies binaries to /usr/local/bin/
• Generates /etc/moltchain/env-testnet and/or /etc/moltchain/env-mainnet with correct port assignments
• Installs per-network systemd services: moltchain-validator-testnet and moltchain-validator-mainnet

Systemd Unit File

The service reads its port configuration from the environment file. Key flags match moltchain-start.sh:

[Unit]
Description=MoltChain Validator Node
Documentation=https://docs.moltchain.io
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=moltchain
Group=moltchain
# --no-watchdog: systemd handles restarts via Restart=on-failure
ExecStart=/usr/local/bin/moltchain-validator --no-watchdog \
    --network ${MOLTCHAIN_NETWORK} \
    --rpc-port ${MOLTCHAIN_RPC_PORT} \
    --ws-port ${MOLTCHAIN_WS_PORT} \
    --p2p-port ${MOLTCHAIN_P2P_PORT} \
    --db-path /var/lib/moltchain/state-${MOLTCHAIN_NETWORK}

Restart=on-failure
RestartSec=10
LimitNOFILE=65536

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/moltchain /var/log/moltchain
PrivateTmp=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true

# Environment
Environment=RUST_LOG=info
EnvironmentFile=/etc/moltchain/env

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=moltchain-validator

[Install]
WantedBy=multi-user.target

Service Management

# Start the testnet validator
sudo systemctl start moltchain-validator-testnet

# Enable on boot
sudo systemctl enable moltchain-validator-testnet

# Check status
sudo systemctl status moltchain-validator-testnet

# Follow logs
journalctl -u moltchain-validator-testnet -f

# Restart after config change
sudo systemctl restart moltchain-validator-testnet

# Mainnet uses the same commands with -mainnet suffix
sudo systemctl start moltchain-validator-mainnet

Troubleshooting

Port Conflicts

If the validator fails to start with "address already in use":

# Find what's using the port (testnet example)
sudo lsof -i :7001   # P2P
sudo lsof -i :8899   # RPC

# The port scheme is fixed per network — see the Installation section above

Insufficient Stake

Your node won't produce blocks without meeting the minimum stake. Check your balance and stake:

molt balance --rpc-url https://testnet-rpc.moltchain.io
molt stake status --rpc-url https://testnet-rpc.moltchain.io

Sync Failures

If your node can't sync with the network:

• Verify seed_nodes are correct and reachable
• Check that the P2P port is open in your firewall (sudo ufw allow 7001/tcp for testnet)
• Ensure chain_id matches the network you're connecting to
• Try increasing log level: RUST_LOG=debug,moltchain_p2p=trace

# Test connectivity to seed nodes
nc -zv seed1.moltchain.io 7001

# Check current block height via RPC (testnet port 8899)
curl -s http://localhost:8899 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getBlockHeight"}' | jq .result

Disk Full

The ledger grows over time. Monitor disk usage and plan for growth:

# Check data directory size
du -sh /var/lib/moltchain/

# Check available disk
df -h /var/lib/moltchain/

# Set up monitoring alert (example with Prometheus Alertmanager)
# Alert when disk usage > 80%

Debug Commands

# Full node status dump (testnet RPC port)
curl -s http://localhost:8899 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' | jq

# Peer list
curl -s http://localhost:8899 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getClusterNodes"}' | jq

# Validator set
curl -s http://localhost:8899 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getValidators"}' | jq

# Check systemd logs for crash details
journalctl -u moltchain-validator-testnet --since "1 hour ago" --no-pager

# Run validator with maximum verbosity (testnet)
RUST_LOG=trace moltchain-validator --network testnet --rpc-port 8899 --ws-port 8900 --p2p-port 7001 --db-path /var/lib/moltchain/state-testnet 2>&1 | head -200