Skip to content

csnode: PEERS status line and official-nodes alerts (log and status only) - #191

Draft
EnzinoBB wants to merge 4 commits into
masterfrom
feat/peer-status
Draft

EnzinoBB wants to merge 4 commits into
masterfrom
feat/peer-status

Conversation

@EnzinoBB

Copy link
Copy Markdown
Collaborator

Operators can now see in the log and in the status whether official nodes are still around or whether community nodes are carrying the network.

What it adds

  • PEERS line, once at the start and then every 10 minutes:
    PEERS: 16 neighbours (11 official, 5 community); last 1000 rounds: trusted seats 76% official, 24% community; this node trusted in 41%
    • Each peer is classified from the version it announces (host_data, the same source as known_peers.json): minor 0 is official 4.2.532, minor > 0 is community, and nothing announced yet is unknown.
    • The trusted seats are the confidants whose realTrusted bit is set, over a sliding window of the last 1000 stored blocks. Rollbacks are handled. Keys are classified when the line is computed, so a peer the node learns about later is counted correctly.
  • Alerts, each logged once when the state changes, then at most every 10 minutes while it holds:
    • OFFICIAL NODES GONE: no official neighbour for 10 minutes, or no official confidant among the trusted of the last 200 rounds. The second test needs at least half of the seats classified, so a window of unknown keys does not raise it.
    • OFFICIAL NODES BACK when they return.
    • TRUSTED SEATS COMMUNITY-ONLY (a warning) when every seat of the last 1000 rounds was a community node, and TRUSTED SEATS MIXED again when that ends.
  • peer-status.json next to the db folder, like fork-held.json: written atomically and fsynced, using the writer from csnode: bound automatic chain reorganisations #189, which is now shared (cs::forkguard::writeFileAtomic). It is rewritten with each PEERS line, each alert and each state change.
  • Docker healthcheck prints the latest PEERS summary and the alert state. It stays healthy when official nodes are gone; FORK HELD remains the only unhealthy state. A new case in test-entrypoint.sh covers this.
  • FORK HELD detail line: when the refused peer's announced version is known, the line adds ; the other side is an official node (4.2.532) or ... a community node.
  • Accessor Node::officialNodesGone(), for the community bootstrap (csnode: community bootstrap fallback (opt-in) and official-stop CI scenarios #188) or other later users.

Constraints

  • Log and status only. Nothing is sent, signed, hashed or validated differently.
  • No new network message, no Thrift IDL change and no new configuration key, so no set-up changes.
  • Gitlinks are unchanged.

Tests

  • New tests/csnode/peerstatus_tests.cpp with 17 tests covering:
    • classification;
    • the seat window and rollback;
    • reclassification when kinds are learned later;
    • the PEERS line format;
    • GONE and BACK by neighbours and by seats, with the throttling and flapping cases;
    • unknown seats not raising GONE;
    • the community-only warning;
    • the status file;
    • the FORK HELD side note.
  • Docs: docs/quick-start.md (reading the PEERS line), docs/differences.md ("Running"). The docs/CHANGES.md row follows once the PR number is known.

🤖 Generated with Claude Code

EnzinoBB and others added 4 commits November 20, 2026 10:26
…nly)

Every 10 minutes and once at the start the node logs who keeps the network
going: its neighbours by announced version (official 4.2.532 when the
handshake's minor version is 0, community when higher, unknown when not yet
announced), the share of official and community nodes among the trusted
seats (confidants with their realTrusted bit) of the last 1000 stored blocks,
and how often this node was trusted.

OFFICIAL NODES GONE when no official neighbour for 10 minutes or no official
confidant among the trusted of the last 200 rounds (with at least half of the
seats classified); OFFICIAL NODES BACK when they return; TRUSTED SEATS
COMMUNITY-ONLY when every seat of the last 1000 rounds was a community node.
Each alert once on the change, then at most every 10 minutes.

peer-status.json next to the db folder (atomic and fsynced, the writer of the
fork guard files is now shared), printed by the Docker healthcheck, which
stays healthy for it. The FORK HELD detail line says whether the refused peer
is an official or a community node. Node::officialNodesGone() for later use.

Consensus-neutral: nothing is sent, signed, hashed or validated differently;
no new configuration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The window holds blocks stored since the start (blocks read from the
database at start-up are not counted), so the first line of a restarted
node said "no stored blocks yet" next to a full database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant