Validator Guide

VERSION=$(curl -fsSL https://api.github.com/repos/lobstercove/lichen/releases/latest | jq -r .tag_name)
curl -LO "https://github.com/lobstercove/lichen/releases/download/${VERSION}/lichen-validator-linux-x86_64.tar.gz"
curl -LO "https://github.com/lobstercove/lichen/releases/download/${VERSION}/SHA256SUMS"
grep 'lichen-validator-linux-x86_64.tar.gz' SHA256SUMS | sha256sum -c -
tar xzf lichen-validator-linux-x86_64.tar.gz --strip-components=1
chmod +x lichen-validator lichen-genesis lichen zk-prove
mkdir -p "$HOME/.lichen/state-mainnet"
cp seeds.json "$HOME/.lichen/state-mainnet/seeds.json"
export LICHEN_KEYPAIR_PASSWORD='set-a-long-random-secret-before-first-start'
./lichen-validator \
    --network mainnet \
    --rpc-port 9899 \
    --ws-port 9900 \
    --p2p-port 8001 \
    --db-path "$HOME/.lichen/state-mainnet" \
    --auto-update=apply

VERSION=$(curl -fsSL https://api.github.com/repos/lobstercove/lichen/releases/latest | jq -r .tag_name)
curl -LO "https://github.com/lobstercove/lichen/releases/download/${VERSION}/lichen-validator-darwin-aarch64.tar.gz"
curl -LO "https://github.com/lobstercove/lichen/releases/download/${VERSION}/SHA256SUMS"
grep 'lichen-validator-darwin-aarch64.tar.gz' SHA256SUMS | shasum -a 256 -c -
tar xzf lichen-validator-darwin-aarch64.tar.gz --strip-components=1
chmod +x lichen-validator lichen-genesis lichen zk-prove
mkdir -p "$HOME/.lichen/state-mainnet"
cp seeds.json "$HOME/.lichen/state-mainnet/seeds.json"
export LICHEN_KEYPAIR_PASSWORD='set-a-long-random-secret-before-first-start'
./lichen-validator \
    --network mainnet \
    --rpc-port 9899 \
    --ws-port 9900 \
    --p2p-port 8001 \
    --db-path "$HOME/.lichen/state-mainnet" \
    --auto-update=apply

$version = (Invoke-RestMethod https://api.github.com/repos/lobstercove/lichen/releases/latest).tag_name
Invoke-WebRequest -Uri "https://github.com/lobstercove/lichen/releases/download/$version/lichen-validator-windows-x86_64.tar.gz" -OutFile "lichen-validator-windows-x86_64.tar.gz"
tar -xzf .\lichen-validator-windows-x86_64.tar.gz --strip-components=1
New-Item -ItemType Directory -Force -Path "$HOME\.lichen\state-mainnet" | Out-Null
Copy-Item .\seeds.json "$HOME\.lichen\state-mainnet\seeds.json" -Force
$env:LICHEN_KEYPAIR_PASSWORD = 'set-a-long-random-secret-before-first-start'
.\lichen-validator.exe `
    --network mainnet `
    --rpc-port 9899 `
    --ws-port 9900 `
    --p2p-port 8001 `
    --db-path "$HOME\.lichen\state-mainnet" `
    --auto-update=apply

mkdir -p "$HOME/.lichen/state-mainnet/home"
cp seeds.json "$HOME/.lichen/state-mainnet/seeds.json"
export LICHEN_KEYPAIR_PASSWORD='set-a-long-random-secret-before-first-start'

env HOME="$HOME/.lichen/state-mainnet/home" \
lichen-validator \
    --network mainnet \
    --rpc-port 9899 \
    --ws-port 9900 \
    --p2p-port 8001 \
    --db-path "$HOME/.lichen/state-mainnet" \
    --auto-update=apply

git clone https://github.com/lobstercove/lichen.git
cd lichen
cargo build --release
export LICHEN_KEYPAIR_PASSWORD='local-e2e-secret'
bash scripts/start-local-3validators.sh start-reset

export LICHEN_KEYPAIR_PASSWORD='local-e2e-secret'
./scripts/start-local-stack.sh testnet
./scripts/status-local-stack.sh testnet

# Validator-only cluster
bash scripts/start-local-3validators.sh status
bash scripts/start-local-3validators.sh stop
bash scripts/start-local-3validators.sh start-reset

# Full local stack
./scripts/status-local-stack.sh testnet
./scripts/stop-local-stack.sh testnet
./scripts/start-local-stack.sh testnet

# Clean local reset
bash scripts/start-local-3validators.sh stop
bash scripts/start-local-3validators.sh start-reset

git clone https://github.com/lobstercove/lichen.git
cd lichen
cargo build --release
export LICHEN_KEYPAIR_PASSWORD='set-a-long-random-secret-before-first-start'

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

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

docker-compose up validator

lichen init --output ~/.lichen/validator-keypair.json

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

$ lichen stake add 75000000000 --rpc-url https://testnet-rpc.lichen.network

 Staking 75 LICN for validator Mo1tVa1idAtoR...xYz789

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

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

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

$ lichen stake status --rpc-url https://testnet-rpc.lichen.network

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

# Fetch metrics
curl -s http://127.0.0.1:9100/metrics | grep lichen_

# Example output
lichen_block_height 1205247
lichen_tps 842
lichen_peer_count 18
lichen_mempool_size 127

curl -s https://testnet-rpc.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

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

# Per-module granularity via RUST_LOG
RUST_LOG=info,lichen_p2p=debug,lichen_rpc=warn lichen-validator

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

version: "3.8"

services:
  validator:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: lichen-validator
    restart: unless-stopped
    ports:
      - "7001:7001"   # P2P (testnet)
      - "8899:8899"   # RPC (testnet)
      - "8900:8900"   # WebSocket (testnet)
      - "9100:9100"   # Metrics
    volumes:
      - lichen-data:/var/lib/lichen
    environment:
      - RUST_LOG=info
      - LICHEN_NETWORK=testnet
      - LICHEN_RPC_PORT=8899
      - LICHEN_WS_PORT=8900
      - LICHEN_P2P_PORT=7001
            - LICHEN_SIGNER_BIND=127.0.0.1:9201
      - LICHEN_ADMIN_TOKEN=${LICHEN_ADMIN_TOKEN:-}
    networks:
      - lichen
    healthcheck:
            test: ["CMD-SHELL", "curl -sf http://127.0.0.1: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:
  lichen-data:
    driver: local

networks:
  lichen:
    driver: bridge

# 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

# Example: install the release binary, then install a systemd unit
sudo install -m 755 lichen-validator /usr/local/bin/lichen-validator
sudo install -m 644 deploy/lichen-validator.service /etc/systemd/system/lichen-validator.service
sudo systemctl daemon-reload
sudo systemctl enable --now lichen-validator

[Unit]
Description=Lichen Validator Node
Documentation=https://developers.lichen.network/validator.html
After=network-online.target
Wants=network-online.target

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

Restart=on-failure
RestartSec=10
LimitNOFILE=65536

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

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

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

[Install]
WantedBy=multi-user.target

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

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

# Check status
sudo systemctl status lichen-validator-testnet

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

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

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

mkdir -p ~/.lichen/bin ~/.lichen/state-mainnet ~/.lichen/logs

cat > ~/.lichen/bin/lichen-service.sh << 'WRAPPER'
#!/bin/bash
set -euo pipefail

INSTALL_DIR="$HOME/.lichen/bin"
BINARY="$INSTALL_DIR/lichen-validator"
STATE_DIR="$HOME/.lichen/state-mainnet"
LOG_DIR="$HOME/.lichen/logs"
REPO="lobstercove/lichen"

# Set ASSET based on architecture
ARCH=$(uname -m)
case "$ARCH" in
    arm64|aarch64) ASSET="lichen-validator-darwin-aarch64.tar.gz" ;;
    x86_64)        ASSET="lichen-validator-darwin-x86_64.tar.gz" ;;
    *)             echo "Unsupported arch: $ARCH"; exit 1 ;;
esac

mkdir -p "$INSTALL_DIR" "$STATE_DIR" "$LOG_DIR"

# Download binary if not present
if [ ! -x "$BINARY" ]; then
    echo "$(date): Downloading latest release..."
    TMPDIR=$(mktemp -d)
    trap 'rm -rf "$TMPDIR"' EXIT

    # Fetch highest semver tag (not GitHub "latest" which sorts by publish date)
    VERSION=$(/usr/bin/curl -fsSL "https://api.github.com/repos/$REPO/releases" \
        | /usr/bin/python3 -c "
import sys, json
releases = [r for r in json.load(sys.stdin) if not r['draft'] and not r['prerelease']]
releases.sort(key=lambda r: [int(x) for x in r['tag_name'].lstrip('v').split('.')], reverse=True)
print(releases[0]['tag_name'])
")
    echo "$(date): Latest version: $VERSION"

    /usr/bin/curl -fSL -o "$TMPDIR/$ASSET" \
        "https://github.com/$REPO/releases/download/${VERSION}/${ASSET}"
    /usr/bin/curl -fSL -o "$TMPDIR/SHA256SUMS" \
        "https://github.com/$REPO/releases/download/${VERSION}/SHA256SUMS"

    cd "$TMPDIR"
    grep "$ASSET" SHA256SUMS | shasum -a 256 -c -
    tar xzf "$ASSET" --strip-components=1
    mv lichen-validator "$BINARY"
    mv zk-prove "$INSTALL_DIR/zk-prove"
    mv lichen-genesis "$INSTALL_DIR/lichen-genesis"
    mv lichen "$INSTALL_DIR/lichen"
    cp -R contracts "$INSTALL_DIR/contracts"
    chmod +x "$BINARY" "$INSTALL_DIR/zk-prove" "$INSTALL_DIR/lichen-genesis" "$INSTALL_DIR/lichen"
    cp seeds.json "$STATE_DIR/seeds.json"

    cd /

    echo "$(date): Installed lichen-validator $VERSION"
    trap - EXIT
    rm -rf "$TMPDIR"
fi

# Start the validator
echo "$(date): Starting lichen-validator..."
exec "$BINARY" \
    --network mainnet \
    --p2p-port 8001 \
    --rpc-port 9899 \
    --ws-port 9900 \
    --db-path "$STATE_DIR" \
    --auto-update=apply
WRAPPER

chmod +x ~/.lichen/bin/lichen-service.sh

cat > ~/Library/LaunchAgents/network.lichen.validator.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>network.lichen.validator</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>$HOME/.lichen/bin/lichen-service.sh</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>ThrottleInterval</key>
    <integer>15</integer>

    <key>StandardOutPath</key>
    <string>$HOME/.lichen/logs/validator.log</string>

    <key>StandardErrorPath</key>
    <string>$HOME/.lichen/logs/validator.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>RUST_LOG</key>
        <string>info</string>
    </dict>
</dict>
</plist>
EOF

# Load and start (runs immediately and on every login)
launchctl load ~/Library/LaunchAgents/network.lichen.validator.plist

# Stop the validator
launchctl unload ~/Library/LaunchAgents/network.lichen.validator.plist

# Restart (stop then start)
launchctl unload ~/Library/LaunchAgents/network.lichen.validator.plist
sleep 2
launchctl load ~/Library/LaunchAgents/network.lichen.validator.plist

# Follow logs
tail -f ~/.lichen/logs/validator.log

# Check if running
launchctl list | grep lichen

# Force re-download of the binary (e.g. after a new release)
launchctl unload ~/Library/LaunchAgents/network.lichen.validator.plist
rm ~/.lichen/bin/lichen-validator
launchctl load ~/Library/LaunchAgents/network.lichen.validator.plist

# 1. Download and extract the release
$Version = (Invoke-RestMethod https://api.github.com/repos/lobstercove/lichen/releases/latest).tag_name
$Url = "https://github.com/lobstercove/lichen/releases/download/$Version/lichen-validator-windows-x86_64.tar.gz"
$InstallDir = "$env:LOCALAPPDATA\Lichen"
New-Item -ItemType Directory -Force -Path "$InstallDir\bin", "$InstallDir\state-mainnet", "$InstallDir\logs"

Invoke-WebRequest -Uri $Url -OutFile "$env:TEMP\lichen.tar.gz"
tar -xzf "$env:TEMP\lichen.tar.gz" -C "$InstallDir\bin" --strip-components=1

# 2. Install NSSM (https://nssm.cc/download)
# Extract nssm.exe to a directory in your PATH

# 3. Create the service
nssm install LichenValidator "$InstallDir\bin\lichen-validator.exe"
Copy-Item "$InstallDir\bin\seeds.json" "$InstallDir\state-mainnet\seeds.json" -Force
nssm set LichenValidator AppParameters "--network mainnet --p2p-port 8001 --rpc-port 9899 --ws-port 9900 --db-path $InstallDir\state-mainnet --auto-update=apply"
nssm set LichenValidator AppDirectory "$InstallDir"
nssm set LichenValidator AppStdout "$InstallDir\logs\validator.log"
nssm set LichenValidator AppStderr "$InstallDir\logs\validator.log"
nssm set LichenValidator AppEnvironmentExtra "RUST_LOG=info" "USERPROFILE=$InstallDir"
nssm set LichenValidator Start SERVICE_AUTO_START
nssm set LichenValidator AppRestartDelay 10000

# 4. Start
nssm start LichenValidator

$InstallDir = "$env:LOCALAPPDATA\Lichen"
$Action = New-ScheduledTaskAction `
    -Execute "$InstallDir\bin\lichen-validator.exe" `
                    -Argument "--network mainnet --p2p-port 8001 --rpc-port 9899 --ws-port 9900 --db-path $InstallDir\state-mainnet --auto-update=apply" `
    -WorkingDirectory "$InstallDir"
$Trigger = New-ScheduledTaskTrigger -AtStartup
$Settings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Seconds 15)

Register-ScheduledTask -TaskName "LichenValidator" `
    -Action $Action -Trigger $Trigger -Settings $Settings `
    -RunLevel Highest -User "SYSTEM"

# Start immediately
Start-ScheduledTask -TaskName "LichenValidator"

# NSSM commands
nssm status LichenValidator
nssm start LichenValidator
nssm stop LichenValidator
nssm restart LichenValidator

# View logs
Get-Content "$env:LOCALAPPDATA\Lichen\logs\validator.log" -Tail 50 -Wait

# Remove service
nssm stop LichenValidator
nssm remove LichenValidator confirm

# 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

lichen balance --rpc-url https://testnet-rpc.lichen.network
lichen stake status --rpc-url https://testnet-rpc.lichen.network

# Test connectivity to seed nodes
nc -zv seed-01.lichen.network 7001

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

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

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

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

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

# Peer list
curl -s https://testnet-rpc.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getClusterNodes"}' | jq

# Validator set
curl -s https://testnet-rpc.lichen.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getValidators"}' | jq

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

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