Network Monitoring

Monitor forks, stale nodes, and operator actions

Vorliq node monitoring reads the public node comparison layer, classifies network state, alerts operators, and opens public incidents only for critical network-integrity issues.

ok

ok means the trusted public node is synced, no active fork is visible, and no trusted public node is unreachable.

warning

warning covers stale old community nodes, behind nodes, ahead nodes, unreachable non-critical nodes, and missing snapshot metadata from non-critical nodes.

critical

critical covers trusted public node forked or unreachable, any active forked node, trusted snapshot signature failure, or inability to determine trusted chain state.

Why stale old nodes are warnings only

A stale community node can be an old local install, a stopped laptop, or a node that no longer sends heartbeat. Vorliq does not delete stale registry history and does not open a public incident for one harmless stale record by default. Operators still see the warning and suggested fixes.

Long-inactive non-critical nodes are archival candidates, not automatic deletions. Maintenance suggests archival by default and only auto-archives when VORLIQ_AUTO_ARCHIVE_INACTIVE_NODES=true. Auto-archive skips the trusted public node and requires the node to be inactive longer than 30 days.

Why active forks are critical

An active forked node is currently online and reporting a latest hash that does not match the trusted public chain at the comparable position. That can confuse operators and users, so it is treated as network-integrity critical. Do not sync from it until signed snapshots and audit exports agree.

Ahead nodes are not automatically trusted

Ahead means a node reports a higher height than the trusted public chain. It might be ahead legitimately, but it might also be forked, misconfigured, or unverified. Vorliq treats it as a warning until signed snapshots and audit exports verify the state.

Operator alerts and duplicate suppression

The scheduled maintenance runner calls http://127.0.0.1:5000/api/nodes/monitor. It logs sanitized warnings, calls the configured alert.sh path for repeated warnings or critical alerts, and suppresses duplicates by alert code and node URL. The state file stores only alert code, node URL, first seen, last seen, count, last alerted time, and status.

Public incident rules

Public incidents are created or updated only for critical network-integrity issues: active fork, trusted public node unreachable, trusted public node forked, trusted snapshot signature failure, or trusted state unavailable. Stale community nodes remain operator warnings by default. Incidents are resolved when the same critical condition clears.

Fix stale heartbeat

sudo systemctl restart vorliq-heartbeat.service
curl -I https://node.example.org/api/health
node tools/node_doctor.js --base-url http://127.0.0.1:5000 --public-url https://node.example.org --trusted-node https://vorliq.org

Investigate a fork warning

node tools/node_doctor.js --base-url http://127.0.0.1:5000 --trusted-node https://vorliq.org
node tools/bootstrap_verify_node.js https://vorliq.org
python3.12 tools/bootstrap_chain_from_public_node.py --trusted-node https://vorliq.org --data-dir ./blockchain/data

Do not manually edit chain.json, rewrite historical blocks, or change block hashes. Use verified dry-run bootstrap first, then recover deliberately from backup if needed.

Endpoints

GET /api/nodes/monitor returns public-safe monitor JSON. GET /api/admin/nodes/monitor requires the admin token and adds safe diagnostic context. Use Node Lifecycle for archive, restore, and retire behavior. Neither endpoint returns private keys, admin tokens, raw logs, server paths, raw IPs, raw user agents, or environment dumps.