From 97c48cd3f5a718d0738b541b66180df8bfeab320 Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Fri, 20 Nov 2026 10:26:12 +0100 Subject: [PATCH 1/4] csnode: PEERS status line and official-nodes alerts (log and status only) 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 --- csnode/CMakeLists.txt | 2 + csnode/include/csnode/forkguardstate.hpp | 9 +- csnode/include/csnode/node.hpp | 14 + csnode/include/csnode/peerstatus.hpp | 149 ++++++++++ csnode/src/forkguardstate.cpp | 58 ++-- csnode/src/node.cpp | 70 ++++- csnode/src/peerstatus.cpp | 350 +++++++++++++++++++++++ docs/differences.md | 14 + docs/quick-start.md | 20 ++ packaging/docker/healthcheck.sh | 13 + packaging/docker/test/test-entrypoint.sh | 17 +- tests/csnode/peerstatus_tests.cpp | 323 +++++++++++++++++++++ 12 files changed, 1009 insertions(+), 30 deletions(-) create mode 100644 csnode/include/csnode/peerstatus.hpp create mode 100644 csnode/src/peerstatus.cpp create mode 100644 tests/csnode/peerstatus_tests.cpp diff --git a/csnode/CMakeLists.txt b/csnode/CMakeLists.txt index d6d81a1cb..bb27750a2 100644 --- a/csnode/CMakeLists.txt +++ b/csnode/CMakeLists.txt @@ -81,6 +81,7 @@ add_library(csnode include/csnode/snapshot_fetcher.hpp include/csnode/blockverifier.hpp include/csnode/forkguardstate.hpp + include/csnode/peerstatus.hpp include/csnode/backwardsync.hpp include/csnode/sendcachedata.hpp include/csnode/eventreport.hpp @@ -136,6 +137,7 @@ add_library(csnode src/snapshot_fetcher.cpp src/blockverifier.cpp src/forkguardstate.cpp + src/peerstatus.cpp src/backwardsync.cpp src/sendcachedata.cpp src/eventreport.cpp diff --git a/csnode/include/csnode/forkguardstate.hpp b/csnode/include/csnode/forkguardstate.hpp index d3445260d..7f78d4025 100644 --- a/csnode/include/csnode/forkguardstate.hpp +++ b/csnode/include/csnode/forkguardstate.hpp @@ -34,6 +34,11 @@ inline constexpr size_t kMaxBranchHashes = 256; // the folder of these files for a database path: its parent folder ("." for a relative "db") std::string stateDirFor(const std::string& dbPath); +// a small file in dir written whole: to a temporary name first, flushed to the disk, then renamed over +// the old one (the folder entry flushed too on POSIX), so a crash leaves either the old file or the new +// one. False (nothing replaced) on any failure or an empty dir. +bool writeFileAtomic(const std::string& dir, const char* name, const std::string& text); + struct Episode { cs::Sequence highWater = 0; }; @@ -121,7 +126,7 @@ std::string utcTime(int64_t unixSeconds); std::string remedy(const ForkRecord& record); // the periodic FORK HELD detail line: since when, where the chains diverge, the refused peer and the -// remedy -std::string summary(const ForkRecord& record); +// remedy. peerSide (optional): what the refused peer announces, e.g. "official 4.2.532" +std::string summary(const ForkRecord& record, const std::string& peerSide = std::string()); } // namespace cs::forkguard diff --git a/csnode/include/csnode/node.hpp b/csnode/include/csnode/node.hpp index 6fe51844c..12cda9515 100644 --- a/csnode/include/csnode/node.hpp +++ b/csnode/include/csnode/node.hpp @@ -24,6 +24,7 @@ #include #include #include +#include #include @@ -331,6 +332,12 @@ class Node { return nodeIdKey_; } + // no official node among the neighbours for 10 minutes, or among the trusted of the last 200 + // rounds (log and status only; see csnode/peerstatus.hpp) + bool officialNodesGone() const { + return peerStatus_.officialGone(); + } + Level getNodeLevel() const { return myLevel_; } @@ -480,6 +487,13 @@ public slots: // the fork guard's timer (every 5 s, queued to the processor thread): dismiss-fork, pending holds cs::Timer forkGuardTimer_; void onForkGuardTick(); + // who keeps the network going (log and status only): fed by stored blocks, ticked by the fork + // guard's timer; the peers' kinds read again every 30 s + cs::peerstatus::Tracker peerStatus_; + std::chrono::steady_clock::time_point peerStatusRefreshed_{}; + void onPeerStatusBlock(const csdb::Pool& pool); + void onPeerStatusBlockRemoved(const csdb::Pool& pool); + void onPeerStatusTick(); // snapshot.json of a restored folder against the digest of the loaded caches (design 6.8); // false with exit code 4 on a mismatch bool verifyAtStart(); diff --git a/csnode/include/csnode/peerstatus.hpp b/csnode/include/csnode/peerstatus.hpp new file mode 100644 index 000000000..84755552b --- /dev/null +++ b/csnode/include/csnode/peerstatus.hpp @@ -0,0 +1,149 @@ +#pragma once + +#include +#include +#include +#include +#include +#include +#include + +#include + +// Who keeps the network going: the official nodes (4.2.532, minor version 0 in the handshake) or the +// community releases (minor version N > 0). Log and status only: the node reads what peers announce +// (host_data) and the confidants of the blocks it stores; nothing here is sent, signed, hashed or +// validated. +// +// - every 10 minutes (and once at the start) a PEERS line: the neighbours by kind, the trusted seats +// of the last rounds by kind, how often this node was among them; +// - OFFICIAL NODES GONE when no official neighbour was seen for 10 minutes, or no official node was +// among the trusted of the last 200 rounds; OFFICIAL NODES BACK when they return; +// - a warning when the trusted seats of the last 1000 rounds were all community nodes; +// - peer-status.json next to the db folder (like fork-held.json), for the Docker healthcheck and +// operators. +namespace cs::peerstatus { + +inline constexpr const char* kStatusFile = "peer-status.json"; + +enum class Kind : uint8_t { + Unknown, + Official, + Community +}; + +// from the announced host_data: version 0 means nothing announced yet +Kind classify(uint16_t version, uint16_t minorVersion); +const char* kindName(Kind kind); + +struct Settings { + size_t window = 1000; // rounds in the PEERS line + int64_t goneSeconds = 600; // no official neighbour for this long: gone + size_t goneRounds = 200; // no official among the trusted of this many rounds: gone + size_t communityOnlyRounds = 1000; // all trusted seats community for this many rounds: warning + int64_t summaryEvery = 600; // the PEERS line + int64_t repeatEvery = 600; // an alert while its state holds +}; + +struct NeighbourCounts { + size_t total = 0; + size_t official = 0; + size_t community = 0; + size_t unknown = 0; +}; + +struct SeatCounts { + size_t rounds = 0; + size_t seats = 0; + size_t official = 0; + size_t community = 0; + size_t unknown = 0; + size_t selfTrusted = 0; // rounds with this node among the trusted + cs::Sequence first = 0; + cs::Sequence last = 0; +}; + +struct Line { + bool warning = false; + std::string text; +}; + +// integer percent, rounded; 0 for an empty total +unsigned percent(size_t part, size_t total); + +class Tracker { +public: + explicit Tracker(Settings settings = Settings{}); + + // this node: its key and its own kind (a community build) + void setSelf(const cs::PublicKey& key, Kind kind); + // what the node knows of the peers' announced versions (replaces the previous map) + void setKinds(std::map kinds); + Kind kindOf(const cs::PublicKey& key) const; + // by the base58 key (the fork record's peer_key); Unknown when not known + Kind kindOfBase58(const std::string& key) const; + + // a stored block: the confidants and the realTrusted mask (bit i: confidant i signed) + void addBlock(cs::Sequence seq, const std::vector& confidants, uint64_t realTrusted); + // a block removed from the top: forget it and anything above + void removeBlock(cs::Sequence seq); + + // the trusted seats of the last `rounds` stored blocks (all of the window for 0) + SeatCounts seats(size_t rounds = 0) const; + NeighbourCounts countNeighbours(const std::vector& neighbours) const; + + // every few seconds: the neighbours now; returns the lines to log (the PEERS line when due, + // alerts on transitions and at most every repeatEvery while they hold); nowSeconds: a monotonic clock + std::vector tick(int64_t nowSeconds, const NeighbourCounts& neighbours); + + std::string peersLine(const NeighbourCounts& neighbours) const; + + bool officialGone() const; + bool communityOnly() const; + + // the status file's JSON text (as of the last tick) + std::string statusJson(int64_t wallUnix) const; + +private: + struct Block { + cs::Sequence seq = 0; + std::vector trusted; + bool self = false; + }; + + SeatCounts seatsLocked(size_t rounds) const; + std::string peersLineLocked(const NeighbourCounts& n) const; + + Settings settings_; + mutable std::mutex mutex_; + cs::PublicKey self_{}; + Kind selfKind_ = Kind::Community; + std::map kinds_; + std::map kindsBase58_; + std::deque blocks_; + + // "long ago" for the throttles: the first alert or summary is always due + static constexpr int64_t kNever = (std::numeric_limits::min)() / 2; + + bool started_ = false; + int64_t startedAt_ = 0; + int64_t lastSummary_ = kNever; + int64_t lastOfficialNeighbour_ = 0; // last tick with an official neighbour (startedAt_ before) + bool officialNeighbourSeen_ = false; + NeighbourCounts lastNeighbours_{}; + + bool gone_ = false; + std::string goneReason_; + int64_t goneSince_ = 0; + bool goneAlerted_ = false; + int64_t lastGoneAlert_ = kNever; + int64_t lastBackAlert_ = kNever; + + bool communityOnly_ = false; + bool communityOnlyAlerted_ = false; + int64_t lastCommunityOnlyAlert_ = kNever; + + std::string lastAlert_; +}; + +} // namespace cs::peerstatus diff --git a/csnode/src/forkguardstate.cpp b/csnode/src/forkguardstate.cpp index 96398fa1f..8f7db2ba7 100644 --- a/csnode/src/forkguardstate.cpp +++ b/csnode/src/forkguardstate.cpp @@ -48,15 +48,8 @@ void syncDir(const fs::path& dir) { #endif } -// a small file written whole: to a temporary name first, flushed to the disk, then renamed over the -// old one, so a crash leaves either the old file or the new one +// a small file written as JSON with writeFileAtomic bool writeTree(const std::string& dir, const char* name, const ptree& tree) { - if (dir.empty()) { - return false; - } - std::error_code ec; - const fs::path target = fs::path(dir) / name; - const fs::path tmp = fs::path(dir) / (std::string(name) + ".tmp"); std::string text; try { std::ostringstream out; @@ -66,23 +59,7 @@ bool writeTree(const std::string& dir, const char* name, const ptree& tree) { catch (const std::exception&) { return false; } - std::FILE* f = std::fopen(tmp.string().c_str(), "wb"); - if (f == nullptr) { - return false; - } - const bool written = std::fwrite(text.data(), 1, text.size(), f) == text.size() && syncFile(f); - const bool closed = std::fclose(f) == 0; - if (!written || !closed) { - fs::remove(tmp, ec); - return false; - } - fs::rename(tmp, target, ec); - if (ec) { - fs::remove(tmp, ec); - return false; - } - syncDir(fs::path(dir)); - return true; + return writeFileAtomic(dir, name, text); } // the file's tree; nothing when it does not exist. A file that exists but cannot be read sets @@ -129,6 +106,32 @@ void removeFile(const std::string& dir, const char* name) { } // namespace +bool writeFileAtomic(const std::string& dir, const char* name, const std::string& text) { + if (dir.empty()) { + return false; + } + std::error_code ec; + const fs::path target = fs::path(dir) / name; + const fs::path tmp = fs::path(dir) / (std::string(name) + ".tmp"); + std::FILE* f = std::fopen(tmp.string().c_str(), "wb"); + if (f == nullptr) { + return false; + } + const bool written = std::fwrite(text.data(), 1, text.size(), f) == text.size() && syncFile(f); + const bool closed = std::fclose(f) == 0; + if (!written || !closed) { + fs::remove(tmp, ec); + return false; + } + fs::rename(tmp, target, ec); + if (ec) { + fs::remove(tmp, ec); + return false; + } + syncDir(fs::path(dir)); + return true; +} + std::string stateDirFor(const std::string& dbPath) { fs::path p(dbPath); // "db/" and "db" name the same folder @@ -377,7 +380,7 @@ std::string remedy(const ForkRecord& r) { return os.str(); } -std::string summary(const ForkRecord& r) { +std::string summary(const ForkRecord& r, const std::string& peerSide) { std::ostringstream os; os << "FORK HELD since " << utcTime(r.sinceUnix) << ": "; if (r.reason == "authority") { @@ -407,6 +410,9 @@ std::string summary(const ForkRecord& r) { if (r.peerHeight != 0) { os << ", peer height #" << r.peerHeight; } + if (!peerSide.empty()) { + os << "; the other side is " << peerSide; + } os << ". The node keeps its chain. What to do: " << remedy(r); return os.str(); } diff --git a/csnode/src/node.cpp b/csnode/src/node.cpp index 6a11ba977..643ecda3a 100644 --- a/csnode/src/node.cpp +++ b/csnode/src/node.cpp @@ -157,6 +157,8 @@ Node::Node(cs::config::Observer& observer) cs::Connector::connect(&snapshotTickTimer_.timeOut, this, &Node::onSnapshotTick); cs::Connector::connect(&backfillTimer_.timeOut, this, &Node::onBackfillTick); cs::Connector::connect(&forkGuardTimer_.timeOut, this, &Node::onForkGuardTick); + cs::Connector::connect(&blockChain_.storeBlockEvent, this, &Node::onPeerStatusBlock); + cs::Connector::connect(&blockChain_.removeBlockEvent, this, &Node::onPeerStatusBlockRemoved); globalPublicKey_.fill(0); globalPublicKey_.at(31) = 7U; @@ -256,7 +258,21 @@ void Node::logForkHeldDetail(const std::optional& for const auto now = std::chrono::steady_clock::now(); if (lastForkHeldDetail_ == std::chrono::steady_clock::time_point{} || now - lastForkHeldDetail_ >= std::chrono::minutes(1)) { lastForkHeldDetail_ = now; - cswarning() << " " << cs::forkguard::summary(*forkHeld); + // the refused peer's announced version, when known (the PEERS status) + std::string side; + if (!forkHeld->peerKey.empty()) { + switch (peerStatus_.kindOfBase58(forkHeld->peerKey)) { + case cs::peerstatus::Kind::Official: + side = "an official node (4.2.532)"; + break; + case cs::peerstatus::Kind::Community: + side = "a community node"; + break; + default: + break; + } + } + cswarning() << " " << cs::forkguard::summary(*forkHeld, side); } } else { @@ -273,6 +289,58 @@ void Node::onForkGuardTick() { blockChain_.checkDismissTrigger(); blockChain_.promotePendingHold(false); logForkHeldDetail(blockChain_.forkHeldRecord()); + onPeerStatusTick(); +} + +void Node::onPeerStatusBlock(const csdb::Pool& pool) { + peerStatus_.addBlock(pool.sequence(), pool.confidants(), pool.realTrusted()); +} + +void Node::onPeerStatusBlockRemoved(const csdb::Pool& pool) { + peerStatus_.removeBlock(pool.sequence()); +} + +// every 30 s: the peers' announced versions and the neighbours; the PEERS line every 10 minutes and the +// official-gone alerts, peer-status.json next to the db folder. Reads only what the node already has. +void Node::onPeerStatusTick() { + const auto now = std::chrono::steady_clock::now(); + if (peerStatusRefreshed_ != std::chrono::steady_clock::time_point{} && now - peerStatusRefreshed_ < std::chrono::seconds(30)) { + return; + } + peerStatusRefreshed_ = now; + std::vector known; + transport_->getKnownPeers(known); + std::map kinds; + for (const auto& p : known) { + kinds[p.key] = cs::peerstatus::classify(static_cast(p.version), p.minorVersion); + } + peerStatus_.setSelf(nodeIdKey_, Config::getMinorNodeVersion() == 0 ? cs::peerstatus::Kind::Official : cs::peerstatus::Kind::Community); + peerStatus_.setKinds(std::move(kinds)); + std::vector neighbours; + transport_->forEachNeighbour([&neighbours](const cs::PublicKey& key, cs::Sequence, cs::RoundNumber) { + neighbours.push_back(key); + }); + const auto counts = peerStatus_.countNeighbours(neighbours); + const auto seconds = std::chrono::duration_cast(now.time_since_epoch()).count(); + const bool goneBefore = peerStatus_.officialGone(); + const bool onlyBefore = peerStatus_.communityOnly(); + const auto lines = peerStatus_.tick(seconds, counts); + for (const auto& line : lines) { + if (line.warning) { + cswarning() << line.text; + } + else { + cslog() << line.text; + } + } + // the status file with every PEERS line, alert and change of state (a few times an hour) + if (!lines.empty() || goneBefore != peerStatus_.officialGone() || onlyBefore != peerStatus_.communityOnly()) { + const auto dir = cs::forkguard::stateDirFor(cs::ConfigHolder::instance().config()->getPathToDB()); + const auto wall = std::chrono::duration_cast(std::chrono::system_clock::now().time_since_epoch()).count(); + if (!cs::forkguard::writeFileAtomic(dir, cs::peerstatus::kStatusFile, peerStatus_.statusJson(wall))) { + csdebug() << "PEERS: cannot write " << cs::peerstatus::kStatusFile << " in " << dir; + } + } } std::optional Node::resolveForkTop() { diff --git a/csnode/src/peerstatus.cpp b/csnode/src/peerstatus.cpp new file mode 100644 index 000000000..b6d50acae --- /dev/null +++ b/csnode/src/peerstatus.cpp @@ -0,0 +1,350 @@ +#include + +#include + +#include +#include + +#include + +#include + +namespace cs::peerstatus { + +Kind classify(uint16_t version, uint16_t minorVersion) { + if (version == 0) { + return Kind::Unknown; + } + return minorVersion == 0 ? Kind::Official : Kind::Community; +} + +const char* kindName(Kind kind) { + switch (kind) { + case Kind::Official: + return "official"; + case Kind::Community: + return "community"; + default: + return "unknown"; + } +} + +unsigned percent(size_t part, size_t total) { + if (total == 0) { + return 0; + } + return static_cast((part * 200 + total) / (2 * total)); +} + +Tracker::Tracker(Settings settings) +: settings_(settings) { +} + +void Tracker::setSelf(const cs::PublicKey& key, Kind kind) { + std::lock_guard lock(mutex_); + self_ = key; + selfKind_ = kind; +} + +void Tracker::setKinds(std::map kinds) { + std::map byName; + for (const auto& [key, kind] : kinds) { + byName.emplace(EncodeBase58(key.data(), key.data() + key.size()), kind); + } + std::lock_guard lock(mutex_); + kinds_ = std::move(kinds); + kindsBase58_ = std::move(byName); +} + +Kind Tracker::kindOf(const cs::PublicKey& key) const { + std::lock_guard lock(mutex_); + if (key == self_) { + return selfKind_; + } + const auto it = kinds_.find(key); + return it == kinds_.end() ? Kind::Unknown : it->second; +} + +Kind Tracker::kindOfBase58(const std::string& key) const { + std::lock_guard lock(mutex_); + const auto it = kindsBase58_.find(key); + return it == kindsBase58_.end() ? Kind::Unknown : it->second; +} + +void Tracker::addBlock(cs::Sequence seq, const std::vector& confidants, uint64_t realTrusted) { + Block b; + b.seq = seq; + for (size_t i = 0; i < confidants.size() && i < 64; ++i) { + if ((realTrusted >> i) & 1U) { + b.trusted.push_back(confidants[i]); + } + } + std::lock_guard lock(mutex_); + for (const auto& k : b.trusted) { + if (k == self_) { + b.self = true; + break; + } + } + // a block stored again after a rollback replaces the old one and anything above it + while (!blocks_.empty() && blocks_.back().seq >= seq) { + blocks_.pop_back(); + } + blocks_.push_back(std::move(b)); + while (blocks_.size() > settings_.window) { + blocks_.pop_front(); + } +} + +void Tracker::removeBlock(cs::Sequence seq) { + std::lock_guard lock(mutex_); + while (!blocks_.empty() && blocks_.back().seq >= seq) { + blocks_.pop_back(); + } +} + +SeatCounts Tracker::seats(size_t rounds) const { + std::lock_guard lock(mutex_); + return seatsLocked(rounds); +} + +SeatCounts Tracker::seatsLocked(size_t rounds) const { + SeatCounts c; + const size_t n = (rounds == 0 || rounds > blocks_.size()) ? blocks_.size() : rounds; + for (size_t i = blocks_.size() - n; i < blocks_.size(); ++i) { + const auto& b = blocks_[i]; + if (c.rounds == 0) { + c.first = b.seq; + } + c.last = b.seq; + ++c.rounds; + if (b.self) { + ++c.selfTrusted; + } + for (const auto& k : b.trusted) { + ++c.seats; + Kind kind = Kind::Unknown; + if (k == self_) { + kind = selfKind_; + } + else if (const auto it = kinds_.find(k); it != kinds_.end()) { + kind = it->second; + } + switch (kind) { + case Kind::Official: + ++c.official; + break; + case Kind::Community: + ++c.community; + break; + default: + ++c.unknown; + break; + } + } + } + return c; +} + +NeighbourCounts Tracker::countNeighbours(const std::vector& neighbours) const { + NeighbourCounts n; + std::lock_guard lock(mutex_); + for (const auto& k : neighbours) { + ++n.total; + const auto it = kinds_.find(k); + switch (it == kinds_.end() ? Kind::Unknown : it->second) { + case Kind::Official: + ++n.official; + break; + case Kind::Community: + ++n.community; + break; + default: + ++n.unknown; + break; + } + } + return n; +} + +std::string Tracker::peersLine(const NeighbourCounts& neighbours) const { + std::lock_guard lock(mutex_); + return peersLineLocked(neighbours); +} + +std::string Tracker::peersLineLocked(const NeighbourCounts& n) const { + std::ostringstream os; + os << "PEERS: " << n.total << " neighbours (" << n.official << " official, " << n.community << " community"; + if (n.unknown != 0) { + os << ", " << n.unknown << " unknown"; + } + os << "); "; + const auto c = seatsLocked(0); + if (c.rounds == 0 || c.seats == 0) { + os << "no stored blocks yet"; + return os.str(); + } + os << "last " << c.rounds << " rounds: trusted seats " << percent(c.official, c.seats) << "% official, " + << percent(c.community, c.seats) << "% community"; + if (c.unknown != 0) { + os << ", " << percent(c.unknown, c.seats) << "% unknown"; + } + os << "; this node trusted in " << percent(c.selfTrusted, c.rounds) << "%"; + return os.str(); +} + +std::vector Tracker::tick(int64_t now, const NeighbourCounts& neighbours) { + std::vector out; + std::lock_guard lock(mutex_); + if (!started_) { + started_ = true; + startedAt_ = now; + lastOfficialNeighbour_ = now; + } + lastNeighbours_ = neighbours; + if (neighbours.official != 0) { + lastOfficialNeighbour_ = now; + officialNeighbourSeen_ = true; + } + + // gone: by the neighbours (none official for goneSeconds) or by the trusted seats (none official + // in the last goneRounds, with at least half of the seats classified: unknown keys may be official) + const bool byNeighbours = now - lastOfficialNeighbour_ >= settings_.goneSeconds; + const auto recent = seatsLocked(settings_.goneRounds); + const bool bySeats = recent.rounds >= settings_.goneRounds && recent.seats != 0 && recent.official == 0 && + 2 * (recent.official + recent.community) >= recent.seats; + const bool gone = byNeighbours || bySeats; + + const auto minutes = [](int64_t s) { + return std::to_string(s / 60) + " min"; + }; + const auto all = seatsLocked(0); + const auto composition = [&]() { + std::ostringstream os; + os << "community nodes keep the network going: " << neighbours.community << " community of " << neighbours.total + << " neighbours"; + if (all.seats != 0) { + os << ", " << percent(all.community, all.seats) << "% of the trusted seats of the last " << all.rounds << " rounds"; + } + return os.str(); + }; + + if (gone) { + std::string reason; + if (byNeighbours) { + reason = officialNeighbourSeen_ ? "no official neighbour for " + minutes(now - lastOfficialNeighbour_) + : "no official neighbour seen since the start (" + minutes(now - startedAt_) + ")"; + } + if (bySeats) { + if (!reason.empty()) { + reason += " and "; + } + reason += "no official node among the trusted of the last " + std::to_string(recent.rounds) + " rounds"; + } + if (!gone_) { + gone_ = true; + goneSince_ = now; + goneAlerted_ = false; + } + goneReason_ = reason; + // once on the transition, then at most every repeatEvery (also across a quick back and forth) + if (now - lastGoneAlert_ >= settings_.repeatEvery) { + std::string text = "OFFICIAL NODES GONE"; + if (goneAlerted_) { + text += " (still, for " + minutes(now - goneSince_) + ")"; + } + text += ": " + reason + "; " + composition(); + out.push_back(Line{true, text}); + lastAlert_ = text; + goneAlerted_ = true; + lastGoneAlert_ = now; + } + } + else if (gone_) { + gone_ = false; + goneReason_.clear(); + // a quick return after a gone alert is still said, but not more than once per repeatEvery + if (goneAlerted_ && now - lastBackAlert_ >= settings_.repeatEvery) { + std::ostringstream os; + os << "OFFICIAL NODES BACK after " << minutes(now - goneSince_) << ": " << neighbours.official + << " official of " << neighbours.total << " neighbours, " << percent(recent.official, recent.seats) + << "% of the trusted seats of the last " << recent.rounds << " rounds"; + out.push_back(Line{false, os.str()}); + lastAlert_ = os.str(); + lastBackAlert_ = now; + } + goneAlerted_ = false; + } + + const auto longRun = seatsLocked(settings_.communityOnlyRounds); + const bool communityOnly = longRun.rounds >= settings_.communityOnlyRounds && longRun.seats != 0 && + longRun.community == longRun.seats; + if (communityOnly) { + communityOnly_ = true; + if (now - lastCommunityOnlyAlert_ >= settings_.repeatEvery) { + std::ostringstream os; + os << "TRUSTED SEATS COMMUNITY-ONLY: every trusted seat of the last " << longRun.rounds << " rounds (blocks #" + << longRun.first << "-#" << longRun.last << ") was a community node; no official node takes part in consensus"; + out.push_back(Line{true, os.str()}); + lastAlert_ = os.str(); + communityOnlyAlerted_ = true; + lastCommunityOnlyAlert_ = now; + } + } + else if (communityOnly_) { + communityOnly_ = false; + if (communityOnlyAlerted_) { + out.push_back(Line{false, "TRUSTED SEATS MIXED again: official or unknown nodes among the trusted of the last " + + std::to_string(longRun.rounds) + " rounds"}); + } + communityOnlyAlerted_ = false; + } + + // the PEERS line first: at the first tick, then every summaryEvery + if (now - lastSummary_ >= settings_.summaryEvery) { + out.insert(out.begin(), Line{false, peersLineLocked(neighbours)}); + lastSummary_ = now; + } + return out; +} + +bool Tracker::officialGone() const { + std::lock_guard lock(mutex_); + return gone_; +} + +bool Tracker::communityOnly() const { + std::lock_guard lock(mutex_); + return communityOnly_; +} + +std::string Tracker::statusJson(int64_t wallUnix) const { + using boost::property_tree::ptree; + std::lock_guard lock(mutex_); + const auto c = seatsLocked(0); + const auto& n = lastNeighbours_; + ptree tree; + tree.put("updated", cs::forkguard::utcTime(wallUnix)); + tree.put("updated_unix", wallUnix); + tree.put("summary", peersLineLocked(n)); + tree.put("neighbours", n.total); + tree.put("neighbours_official", n.official); + tree.put("neighbours_community", n.community); + tree.put("neighbours_unknown", n.unknown); + tree.put("window_rounds", c.rounds); + tree.put("window_first_block", c.first); + tree.put("window_last_block", c.last); + tree.put("seats_official_pct", percent(c.official, c.seats)); + tree.put("seats_community_pct", percent(c.community, c.seats)); + tree.put("seats_unknown_pct", percent(c.unknown, c.seats)); + tree.put("self_trusted_pct", percent(c.selfTrusted, c.rounds)); + tree.put("official_gone", gone_); + tree.put("official_gone_reason", goneReason_); + tree.put("community_only", communityOnly_); + tree.put("last_alert", lastAlert_); + std::ostringstream os; + boost::property_tree::write_json(os, tree); + return os.str(); +} + +} // namespace cs::peerstatus diff --git a/docs/differences.md b/docs/differences.md index b8e22d884..8bd45daff 100644 --- a/docs/differences.md +++ b/docs/differences.md @@ -222,6 +222,20 @@ rebuilt from the chain when the checkpoint holds none. See [tokens.md](tokens.md even though the network executed the call. The community node marks the blocks as read when it starts running. +- **Who keeps the network going.** Every 10 minutes (and once at the start) the log has a `PEERS` + line: the neighbours by announced version (official 4.2.532 when the handshake's minor version is + 0, community when it is higher, unknown when not announced yet), the share of official and + community nodes among the trusted seats (confidants whose bit is set in the block's realTrusted + mask) of the last 1000 stored blocks, and how often this node was among them. The node warns + `OFFICIAL NODES GONE` when no official node has been a neighbour for 10 minutes or signed any of the + last 200 blocks (with at least half the seats classified), `OFFICIAL NODES BACK` when they return, + and `TRUSTED SEATS COMMUNITY-ONLY` when every seat of the last 1000 blocks was a community node; + each once on the change, then at most every 10 minutes. The state is written to + `peer-status.json` next to the `db` folder (atomically, like `fork-held.json`), printed by the + Docker healthcheck (never unhealthy for this), and the FORK HELD detail line says whether the + refused peer is an official or a community node. Log and status only: nothing is sent, signed, + hashed or validated differently, and there is no new option. + ## Security and correctness fixes These were found by reviewing the official code. None of them changes the blocks or the diff --git a/docs/quick-start.md b/docs/quick-start.md index b77e5931d..2ff76dede 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -269,6 +269,22 @@ Then ask the node with the wallet, in the `csnode` folder: It shows the network, the last block and `synced`. Wait for `synced: yes` before sending anything. +**Who keeps the network going.** Once at the start and then every 10 minutes the log has a line like + +``` +PEERS: 16 neighbours (11 official, 5 community); last 1000 rounds: trusted seats 76% official, 24% community; this node trusted in 41% +``` + +Peers announce their version when they connect: official nodes (4.2.532) count as `official`, +community releases as `community`, peers not heard from yet as `unknown`. The trusted seats are the +confidants that signed the last 1000 blocks this node stored. If no official node has been a +neighbour for 10 minutes, or none signed any of the last 200 blocks, the node warns +`OFFICIAL NODES GONE` (again every 10 minutes while it lasts) and `OFFICIAL NODES BACK` when they +return; `TRUSTED SEATS COMMUNITY-ONLY` means every seat of the last 1000 blocks was a community node. +These lines are information, not faults: the network goes on with community nodes. The latest state +is also in `peer-status.json` next to the `db` folder, and the Docker healthcheck prints it +(`docker inspect --format '{{json .State.Health}}' `) without turning unhealthy. + ## 8. The wallet in two lines Open it with `./credits-wallet --config wallet.toml` in `csnode` (`credits-wallet.exe` on Windows; @@ -437,6 +453,10 @@ line (`| FORK HELD`), as a detail line once a minute, in `fork-held.json` next t (the `csnode` folder; `~/.credits` in Docker), and as an unhealthy container in `docker ps`. It clears by itself if the node's chain grows past the point where the rollback started. +When the node knows the version the refused peer announced, the detail line ends its peer part with +`the other side is an official node (4.2.532)` or `... a community node`: a fork against official +nodes usually means the two releases disagree on a block, which is worth reporting. + A restart changes nothing: the node remembers the fork and the rollback limit across restarts, in `reorg-episode.json`, `fork-held.json` and `resolve-approved.json` next to the `db` folder. They describe that database: if you delete `db/` by hand to start again, delete these three files too diff --git a/packaging/docker/healthcheck.sh b/packaging/docker/healthcheck.sh index 1b3554d91..5f84f711c 100755 --- a/packaging/docker/healthcheck.sh +++ b/packaging/docker/healthcheck.sh @@ -2,6 +2,19 @@ # Healthy while the last written block advances: fails when it has not changed for 10 minutes. # Unhealthy while the node reports FORK HELD (fork-held.json with "held": "true"): it refused a # competing chain and waits for the operator. +# Prints the latest PEERS summary and the official-nodes state from peer-status.json (information only: +# official nodes gone never makes the container unhealthy). +peers=/data/peer-status.json +if [ -f "$peers" ]; then + sed -nE 's/.*"summary": "([^"]*)".*/\1/p' "$peers" | head -1 + if grep -q '"official_gone": "true"' "$peers"; then + why=$(sed -nE 's/.*"official_gone_reason": "([^"]*)".*/\1/p' "$peers" | head -1) + echo "OFFICIAL NODES GONE: $why; community nodes keep the network going (information, not a fault)" + fi + if grep -q '"community_only": "true"' "$peers"; then + echo "TRUSTED SEATS COMMUNITY-ONLY: no official node among the trusted of the last rounds" + fi +fi fork=/data/fork-held.json if [ -f "$fork" ] && grep -q '"held": "true"' "$fork"; then at=$(sed -nE 's/.*"fork_point": "([0-9]+)".*/\1/p' "$fork") diff --git a/packaging/docker/test/test-entrypoint.sh b/packaging/docker/test/test-entrypoint.sh index 94cf7975c..132a9583a 100755 --- a/packaging/docker/test/test-entrypoint.sh +++ b/packaging/docker/test/test-entrypoint.sh @@ -321,6 +321,21 @@ set +e; out=$(health "$d"); rc=$?; set -e && grep -q 'resolve-fork' <<<"$out" && grep -q 'dismiss-fork' <<<"$out" || { echo "$out"; fail "healthcheck with a fork held: exit $rc"; } printf '{\n "held": "false",\n "fork_point": "4899"\n}\n' > "$d/fork-held.json" out=$(health "$d") || { echo "$out"; fail "healthcheck with a dismissed fork"; } -pass "resolve-fork, set-bc-top and dismiss-fork; the healthcheck reports FORK HELD" +# peer-status.json: printed, never unhealthy by itself, FORK HELD still is +cat > "$d/peer-status.json" <<'EOF2' +{ + "summary": "PEERS: 6 neighbours (0 official, 6 community); last 1000 rounds: trusted seats 0% official, 100% community; this node trusted in 41%", + "official_gone": "true", + "official_gone_reason": "no official neighbour for 12 min", + "community_only": "true" +} +EOF2 +out=$(health "$d") || { echo "$out"; fail "healthcheck with official nodes gone must stay healthy"; } +grep -q 'PEERS: 6 neighbours (0 official, 6 community)' <<<"$out" && grep -q 'OFFICIAL NODES GONE: no official neighbour for 12 min' <<<"$out" \ + && grep -q 'TRUSTED SEATS COMMUNITY-ONLY' <<<"$out" || { echo "$out"; fail "healthcheck does not print the peer status"; } +printf '{\n "held": "true",\n "since": "2026-11-19 10:00:00 UTC",\n "fork_point": "4899"\n}\n' > "$d/fork-held.json" +set +e; out=$(health "$d"); rc=$?; set -e +[ "$rc" = 1 ] && grep -q 'FORK HELD since' <<<"$out" && grep -q 'PEERS:' <<<"$out" || { echo "$out"; fail "healthcheck with a fork held and peer status: exit $rc"; } +pass "resolve-fork, set-bc-top and dismiss-fork; the healthcheck reports FORK HELD and the peer status" echo "PASS: entrypoint" diff --git a/tests/csnode/peerstatus_tests.cpp b/tests/csnode/peerstatus_tests.cpp new file mode 100644 index 000000000..54dd9ba6f --- /dev/null +++ b/tests/csnode/peerstatus_tests.cpp @@ -0,0 +1,323 @@ +#include + +#include +#include +#include + +#include + +#include +#include + +using namespace cs::peerstatus; + +namespace { + +cs::PublicKey key(uint8_t n) { + cs::PublicKey k{}; + k.fill(0); + k[0] = n; + return k; +} + +// keys 1-9 official, 11-19 community, 21-29 unknown (not in the map); 100 is this node +void setup(Tracker& t) { + t.setSelf(key(100), Kind::Community); + std::map kinds; + for (uint8_t i = 1; i < 10; ++i) { + kinds[key(i)] = Kind::Official; + kinds[key(10 + i)] = Kind::Community; + } + t.setKinds(kinds); +} + +NeighbourCounts neighbours(size_t official, size_t community, size_t unknown = 0) { + return NeighbourCounts{official + community + unknown, official, community, unknown}; +} + +bool hasLine(const std::vector& lines, const std::string& prefix) { + for (const auto& l : lines) { + if (l.text.rfind(prefix, 0) == 0) { + return true; + } + } + return false; +} + +} // namespace + +TEST(PeerStatus, ClassifiesAnnouncedVersions) { + EXPECT_EQ(classify(0, 0), Kind::Unknown); // nothing announced yet + EXPECT_EQ(classify(532, 0), Kind::Official); // official 4.2.532 + EXPECT_EQ(classify(532, 15), Kind::Community); + EXPECT_STREQ(kindName(Kind::Official), "official"); + EXPECT_STREQ(kindName(Kind::Community), "community"); + EXPECT_STREQ(kindName(Kind::Unknown), "unknown"); +} + +TEST(PeerStatus, Percent) { + EXPECT_EQ(percent(0, 0), 0u); + EXPECT_EQ(percent(1, 3), 33u); + EXPECT_EQ(percent(2, 3), 67u); + EXPECT_EQ(percent(3, 4), 75u); + EXPECT_EQ(percent(5, 5), 100u); +} + +TEST(PeerStatus, SeatsCountOnlyRealTrustedAndClassify) { + Tracker t; + setup(t); + // confidants official 1, community 11, unknown 21, self; only bits 0, 1 and 3 signed + t.addBlock(10, {key(1), key(11), key(21), key(100)}, 0b1011); + const auto c = t.seats(); + EXPECT_EQ(c.rounds, 1u); + EXPECT_EQ(c.seats, 3u); + EXPECT_EQ(c.official, 1u); + EXPECT_EQ(c.community, 2u); // 11 and this node + EXPECT_EQ(c.unknown, 0u); + EXPECT_EQ(c.selfTrusted, 1u); + t.addBlock(11, {key(1), key(21), key(100)}, 0b011); + const auto d = t.seats(); + EXPECT_EQ(d.rounds, 2u); + EXPECT_EQ(d.unknown, 1u); + EXPECT_EQ(d.selfTrusted, 1u); + EXPECT_EQ(d.first, 10u); + EXPECT_EQ(d.last, 11u); + EXPECT_EQ(t.seats(1).rounds, 1u); + EXPECT_EQ(t.seats(1).first, 11u); +} + +TEST(PeerStatus, SlidingWindowAndRollback) { + Settings s; + s.window = 5; + Tracker t(s); + setup(t); + for (cs::Sequence q = 1; q <= 8; ++q) { + t.addBlock(q, {key(1)}, 1); + } + auto c = t.seats(); + EXPECT_EQ(c.rounds, 5u); + EXPECT_EQ(c.first, 4u); + EXPECT_EQ(c.last, 8u); + t.removeBlock(7); // 7 and 8 removed + EXPECT_EQ(t.seats().last, 6u); + t.addBlock(5, {key(11)}, 1); // stored again after a rollback: replaces 5 and 6 + c = t.seats(); + EXPECT_EQ(c.last, 5u); + EXPECT_EQ(c.rounds, 2u); + EXPECT_EQ(c.community, 1u); +} + +TEST(PeerStatus, KindsLearnedLaterReclassifyTheWindow) { + Tracker t; + t.setSelf(key(100), Kind::Community); + t.addBlock(1, {key(1), key(11)}, 0b11); + EXPECT_EQ(t.seats().unknown, 2u); + t.setKinds({{key(1), Kind::Official}, {key(11), Kind::Community}}); + EXPECT_EQ(t.seats().official, 1u); + EXPECT_EQ(t.seats().community, 1u); + EXPECT_EQ(t.kindOf(key(1)), Kind::Official); + EXPECT_EQ(t.kindOf(key(100)), Kind::Community); + EXPECT_EQ(t.kindOf(key(50)), Kind::Unknown); +} + +TEST(PeerStatus, NeighbourCounts) { + Tracker t; + setup(t); + const auto n = t.countNeighbours({key(1), key(2), key(11), key(25)}); + EXPECT_EQ(n.total, 4u); + EXPECT_EQ(n.official, 2u); + EXPECT_EQ(n.community, 1u); + EXPECT_EQ(n.unknown, 1u); +} + +TEST(PeerStatus, PeersLine) { + Tracker t; + setup(t); + EXPECT_EQ(t.peersLine(neighbours(11, 5)), "PEERS: 16 neighbours (11 official, 5 community); no stored blocks yet"); + // 4 rounds, 4 seats each: 3 official + 1 community, this node in 2 of them + for (cs::Sequence q = 1; q <= 4; ++q) { + if (q % 2 == 0) { + t.addBlock(q, {key(1), key(2), key(3), key(100)}, 0xF); + } + else { + t.addBlock(q, {key(1), key(2), key(3), key(11)}, 0xF); + } + } + EXPECT_EQ(t.peersLine(neighbours(11, 5)), + "PEERS: 16 neighbours (11 official, 5 community); last 4 rounds: trusted seats 75% official, 25% community; " + "this node trusted in 50%"); + t.addBlock(5, {key(21), key(22), key(23), key(24)}, 0xF); + EXPECT_EQ(t.peersLine(neighbours(1, 1, 2)), + "PEERS: 4 neighbours (1 official, 1 community, 2 unknown); last 5 rounds: trusted seats 60% official, 20% " + "community, 20% unknown; this node trusted in 40%"); +} + +TEST(PeerStatus, PeersLineAtStartThenEveryTenMinutes) { + Tracker t; + setup(t); + auto lines = t.tick(1000, neighbours(3, 1)); + ASSERT_EQ(lines.size(), 1u); + EXPECT_TRUE(hasLine(lines, "PEERS: 4 neighbours")); + EXPECT_FALSE(lines[0].warning); + EXPECT_TRUE(t.tick(1030, neighbours(3, 1)).empty()); + EXPECT_TRUE(t.tick(1599, neighbours(3, 1)).empty()); + EXPECT_TRUE(hasLine(t.tick(1600, neighbours(3, 1)), "PEERS:")); +} + +TEST(PeerStatus, GoneByNeighboursThrottledAndBack) { + Tracker t; + setup(t); + t.tick(0, neighbours(2, 2)); // the last official neighbour + EXPECT_FALSE(t.officialGone()); + EXPECT_FALSE(hasLine(t.tick(300, neighbours(0, 4)), "OFFICIAL")); // 5 minutes only + EXPECT_FALSE(hasLine(t.tick(599, neighbours(0, 4)), "OFFICIAL")); + EXPECT_FALSE(t.officialGone()); + auto lines = t.tick(600, neighbours(0, 4)); // 10 minutes without an official neighbour + EXPECT_TRUE(t.officialGone()); + ASSERT_TRUE(hasLine(lines, "OFFICIAL NODES GONE: no official neighbour for 10 min")); + for (const auto& l : lines) { + if (l.text.rfind("OFFICIAL", 0) == 0) { + EXPECT_TRUE(l.warning); + EXPECT_NE(l.text.find("community nodes keep the network going: 4 community of 4 neighbours"), std::string::npos); + } + } + // held: nothing for 10 minutes, then a reminder + EXPECT_FALSE(hasLine(t.tick(930, neighbours(0, 4)), "OFFICIAL")); + EXPECT_FALSE(hasLine(t.tick(1199, neighbours(0, 4)), "OFFICIAL")); + EXPECT_TRUE(hasLine(t.tick(1200, neighbours(0, 4)), "OFFICIAL NODES GONE (still, for 10 min)")); + // back + lines = t.tick(1230, neighbours(1, 3)); + EXPECT_FALSE(t.officialGone()); + EXPECT_TRUE(hasLine(lines, "OFFICIAL NODES BACK after 10 min: 1 official of 4 neighbours")); + EXPECT_TRUE(t.tick(1260, neighbours(1, 3)).empty()); +} + +TEST(PeerStatus, NeverSeenSinceTheStart) { + Tracker t; + setup(t); + t.tick(0, neighbours(0, 6)); + const auto lines = t.tick(600, neighbours(0, 6)); + EXPECT_TRUE(hasLine(lines, "OFFICIAL NODES GONE: no official neighbour seen since the start (10 min)")); +} + +TEST(PeerStatus, FlappingIsThrottled) { + Settings s; + s.goneRounds = 2; + Tracker t(s); + setup(t); + t.tick(0, neighbours(2, 2)); // official neighbours all along: only the seats change + t.addBlock(1, {key(11)}, 1); + t.addBlock(2, {key(12)}, 1); + EXPECT_TRUE(hasLine(t.tick(10, neighbours(2, 2)), "OFFICIAL NODES GONE")); + t.addBlock(3, {key(1)}, 1); + EXPECT_TRUE(hasLine(t.tick(20, neighbours(2, 2)), "OFFICIAL NODES BACK")); + // gone again within 10 minutes of the last GONE alert: the state changes, the line waits + t.addBlock(4, {key(11)}, 1); + t.addBlock(5, {key(12)}, 1); + EXPECT_FALSE(hasLine(t.tick(30, neighbours(2, 2)), "OFFICIAL")); + EXPECT_TRUE(t.officialGone()); + // and back: no BACK line for a GONE that was not said + t.addBlock(6, {key(1)}, 1); + EXPECT_FALSE(hasLine(t.tick(40, neighbours(2, 2)), "OFFICIAL")); + EXPECT_FALSE(t.officialGone()); + // gone again 10 minutes after the last alert: said again + t.addBlock(7, {key(11)}, 1); + t.addBlock(8, {key(12)}, 1); + EXPECT_TRUE(hasLine(t.tick(610, neighbours(2, 2)), "OFFICIAL NODES GONE: no official node among the trusted of the last 2 rounds")); +} + +TEST(PeerStatus, GoneBySeats) { + Settings s; + s.goneRounds = 10; + s.communityOnlyRounds = 20; + Tracker t(s); + setup(t); + t.tick(0, neighbours(3, 3)); + for (cs::Sequence q = 1; q <= 9; ++q) { + t.addBlock(q, {key(11), key(12), key(100)}, 0b111); + } + EXPECT_FALSE(hasLine(t.tick(30, neighbours(3, 3)), "OFFICIAL")); // 9 rounds only + t.addBlock(10, {key(11), key(12), key(100)}, 0b111); + const auto lines = t.tick(60, neighbours(3, 3)); + EXPECT_TRUE(t.officialGone()); + EXPECT_TRUE(hasLine(lines, "OFFICIAL NODES GONE: no official node among the trusted of the last 10 rounds")); + // one official seat in the last 10 rounds: back + t.addBlock(11, {key(1), key(12), key(100)}, 0b111); + EXPECT_TRUE(hasLine(t.tick(90, neighbours(3, 3)), "OFFICIAL NODES BACK")); + EXPECT_FALSE(t.officialGone()); +} + +TEST(PeerStatus, UnknownSeatsDoNotRaiseGone) { + Settings s; + s.goneRounds = 4; + Tracker t(s); + setup(t); + t.tick(0, neighbours(1, 1)); + for (cs::Sequence q = 1; q <= 4; ++q) { + t.addBlock(q, {key(21), key(22), key(23), key(11)}, 0xF); // 3 of 4 unknown + } + t.tick(30, neighbours(1, 1)); + EXPECT_FALSE(t.officialGone()); +} + +TEST(PeerStatus, CommunityOnlyWarning) { + Settings s; + s.goneRounds = 1000; // only the community-only state here + s.communityOnlyRounds = 5; + Tracker t(s); + setup(t); + t.tick(0, neighbours(1, 1)); + for (cs::Sequence q = 1; q <= 5; ++q) { + t.addBlock(q, {key(11), key(100)}, 0b11); + } + auto lines = t.tick(30, neighbours(1, 1)); + EXPECT_TRUE(t.communityOnly()); + ASSERT_TRUE(hasLine(lines, "TRUSTED SEATS COMMUNITY-ONLY: every trusted seat of the last 5 rounds (blocks #1-#5)")); + EXPECT_FALSE(hasLine(t.tick(60, neighbours(1, 1)), "TRUSTED SEATS")); + EXPECT_TRUE(hasLine(t.tick(630, neighbours(1, 1)), "TRUSTED SEATS COMMUNITY-ONLY")); + t.addBlock(6, {key(1), key(100)}, 0b11); + EXPECT_TRUE(hasLine(t.tick(660, neighbours(1, 1)), "TRUSTED SEATS MIXED again")); + EXPECT_FALSE(t.communityOnly()); +} + +TEST(PeerStatus, KindByBase58Key) { + Tracker t; + setup(t); + const auto k = key(1); + std::string name = EncodeBase58(k.data(), k.data() + k.size()); + EXPECT_EQ(t.kindOfBase58(name), Kind::Official); + EXPECT_EQ(t.kindOfBase58("nope"), Kind::Unknown); +} + +TEST(PeerStatus, StatusFileIsWrittenAtomically) { + Tracker t; + setup(t); + t.addBlock(1, {key(1), key(11)}, 0b11); + t.tick(0, neighbours(0, 2)); + t.tick(600, neighbours(0, 2)); + const auto dir = std::filesystem::temp_directory_path() / "peerstatus_test"; + std::filesystem::remove_all(dir); + std::filesystem::create_directories(dir); + ASSERT_TRUE(cs::forkguard::writeFileAtomic(dir.string(), kStatusFile, t.statusJson(1795000000))); + EXPECT_FALSE(std::filesystem::exists(dir / (std::string(kStatusFile) + ".tmp"))); + std::ifstream in(dir / kStatusFile); + std::stringstream ss; + ss << in.rdbuf(); + const auto text = ss.str(); + EXPECT_NE(text.find("\"official_gone\": \"true\""), std::string::npos); + EXPECT_NE(text.find("\"summary\": \"PEERS: 2 neighbours (0 official, 2 community)"), std::string::npos); + EXPECT_NE(text.find("\"seats_official_pct\": \"50\""), std::string::npos); + EXPECT_NE(text.find("\"last_alert\": \"OFFICIAL NODES GONE"), std::string::npos); + EXPECT_FALSE(cs::forkguard::writeFileAtomic("", kStatusFile, "x")); + std::filesystem::remove_all(dir); +} + +TEST(PeerStatus, ForkHeldSummaryNamesTheOtherSide) { + cs::forkguard::ForkRecord r; + r.forkPoint = 10; + r.ourHead = 12; + r.peerKey = "abc"; + EXPECT_EQ(cs::forkguard::summary(r).find("the other side is"), std::string::npos); + EXPECT_NE(cs::forkguard::summary(r, "an official node (4.2.532)").find("from abc; the other side is an official node (4.2.532)."), + std::string::npos); +} From c9260d0e5f96b9753e0933b141b4ec6c33eac358 Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Fri, 20 Nov 2026 10:26:38 +0100 Subject: [PATCH 2/4] docs: CHANGES row for #191 Co-Authored-By: Claude Opus 5.5 --- docs/CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/CHANGES.md b/docs/CHANGES.md index a8369230a..5d3bad4bd 100644 --- a/docs/CHANGES.md +++ b/docs/CHANGES.md @@ -44,6 +44,7 @@ lines under the new release. | PR | Change | |---|---| +| #191 | csnode: who keeps the network going, in the log and the status. A `PEERS` line once at the start and every 10 minutes: the neighbours by announced version (official 4.2.532 when the minor version is 0, community above, unknown when not announced), the official/community share of the trusted seats of the last 1000 stored blocks, and how often this node was trusted. `OFFICIAL NODES GONE` (no official neighbour for 10 minutes, or no official confidant among the trusted of the last 200 rounds), `OFFICIAL NODES BACK`, and a `TRUSTED SEATS COMMUNITY-ONLY` warning, each once on the change and then at most every 10 minutes. `peer-status.json` next to the database (atomic, fsynced), printed by the Docker healthcheck without making it unhealthy; the FORK HELD detail line says whether the refused peer is an official or a community node. Log and status only: nothing sent, signed or validated differently, no new option | | #190 | ci: the snapshot workflow's monitor check sends its own User-Agent; the monitor answers 403 to urllib's default one, which failed the snapshot runs | | #189 | csnode: bound automatic chain reorganisations. The node stops unwinding its own confirmed blocks once it would roll back more than `[params] max_auto_rollback` (default 100) below the head it had when the rollback began, on every automatic removal path; the reference is kept in `reorg-episode.json`, so a restart does not reset it. A competing block triggers a rollback only if it is vouched for locally: confirmations by a majority of the node's own last confidants, or, for a bootstrap block, its own signatures plus confidants of a round table the node accepted. When it refuses, the node keeps its chain and reports **FORK HELD** until the operator decides: a marker on every round line, a detail line once a minute, `fork-held.json` next to the database and an unhealthy Docker healthcheck. The operator either keeps this chain (a `dismiss-fork` file, picked up by the running node: that branch stays refused and is not reported again) or follows the other one (`node --resolve-fork` cuts the chain at the recorded fork point if the block there is still the recorded one; `--set-bc-top ` by hand; Docker commands `resolve-fork`, `set-bc-top`, `dismiss-fork`). A block not vouched for is refused at once but reported only if the head then stays put (no flapping); unreadable guard files fail safe; the files go when the database is replaced. `allow_deep_rollback` / `CS_ALLOW_DEEP_ROLLBACK` stays as the last resort and turns itself off after one completed episode. The start-up integrity repair is not bounded. Local only; block content is unchanged (see `docs/differences.md`, "Consensus fixes", and "If your node reports FORK HELD" in `docs/quick-start.md`). Also csdb: the storage read cache forgets a block removed from the top of the chain, so a block saved at the same sequence afterwards is the one read back (before, a node that unwound stored blocks could keep reading the removed block and stop a few blocks above the fork point) | | #187 | docs: `AGENTS.md` and `CLAUDE.md` for coding agents: build, tests, CI, conventions and the mainnet constraints (documentation only) | From 3f3a6a7e5f744d7720c9bb076d6105f41eb3b6b3 Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Fri, 20 Nov 2026 10:53:39 +0100 Subject: [PATCH 3/4] tests: close the status file before removing its folder (Windows) Co-Authored-By: Claude Opus 5.5 --- tests/csnode/peerstatus_tests.cpp | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/tests/csnode/peerstatus_tests.cpp b/tests/csnode/peerstatus_tests.cpp index 54dd9ba6f..162b5c1b1 100644 --- a/tests/csnode/peerstatus_tests.cpp +++ b/tests/csnode/peerstatus_tests.cpp @@ -300,16 +300,21 @@ TEST(PeerStatus, StatusFileIsWrittenAtomically) { std::filesystem::create_directories(dir); ASSERT_TRUE(cs::forkguard::writeFileAtomic(dir.string(), kStatusFile, t.statusJson(1795000000))); EXPECT_FALSE(std::filesystem::exists(dir / (std::string(kStatusFile) + ".tmp"))); - std::ifstream in(dir / kStatusFile); - std::stringstream ss; - ss << in.rdbuf(); - const auto text = ss.str(); + std::string text; + { + // closed before the folder is removed (Windows keeps an open file) + std::ifstream in(dir / kStatusFile); + std::stringstream ss; + ss << in.rdbuf(); + text = ss.str(); + } EXPECT_NE(text.find("\"official_gone\": \"true\""), std::string::npos); EXPECT_NE(text.find("\"summary\": \"PEERS: 2 neighbours (0 official, 2 community)"), std::string::npos); EXPECT_NE(text.find("\"seats_official_pct\": \"50\""), std::string::npos); EXPECT_NE(text.find("\"last_alert\": \"OFFICIAL NODES GONE"), std::string::npos); EXPECT_FALSE(cs::forkguard::writeFileAtomic("", kStatusFile, "x")); - std::filesystem::remove_all(dir); + std::error_code ec; + std::filesystem::remove_all(dir, ec); } TEST(PeerStatus, ForkHeldSummaryNamesTheOtherSide) { From b6dba3359e1788771d6d3faa4f5cc162bc42a8a3 Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Fri, 20 Nov 2026 10:54:42 +0100 Subject: [PATCH 4/4] csnode: PEERS says the window starts at the node's start 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 --- csnode/src/peerstatus.cpp | 2 +- tests/csnode/peerstatus_tests.cpp | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/csnode/src/peerstatus.cpp b/csnode/src/peerstatus.cpp index b6d50acae..f87dffeca 100644 --- a/csnode/src/peerstatus.cpp +++ b/csnode/src/peerstatus.cpp @@ -181,7 +181,7 @@ std::string Tracker::peersLineLocked(const NeighbourCounts& n) const { os << "); "; const auto c = seatsLocked(0); if (c.rounds == 0 || c.seats == 0) { - os << "no stored blocks yet"; + os << "no block stored since the start yet"; return os.str(); } os << "last " << c.rounds << " rounds: trusted seats " << percent(c.official, c.seats) << "% official, " diff --git a/tests/csnode/peerstatus_tests.cpp b/tests/csnode/peerstatus_tests.cpp index 162b5c1b1..a5cdeb11f 100644 --- a/tests/csnode/peerstatus_tests.cpp +++ b/tests/csnode/peerstatus_tests.cpp @@ -133,7 +133,7 @@ TEST(PeerStatus, NeighbourCounts) { TEST(PeerStatus, PeersLine) { Tracker t; setup(t); - EXPECT_EQ(t.peersLine(neighbours(11, 5)), "PEERS: 16 neighbours (11 official, 5 community); no stored blocks yet"); + EXPECT_EQ(t.peersLine(neighbours(11, 5)), "PEERS: 16 neighbours (11 official, 5 community); no block stored since the start yet"); // 4 rounds, 4 seats each: 3 official + 1 community, this node in 2 of them for (cs::Sequence q = 1; q <= 4; ++q) { if (q % 2 == 0) {