Merge #19857: net: improve nLastBlockTime and nLastTXTime documentation

d780293e1ee0f9e66bd2d88914694c17f9aaa0ca net: improve nLastBlockTime and nLastTXTime documentation (Jon Atack)

Pull request description:

  Follow-up to #19731 to help alleviate confusion around `nLastBlockTime` and `nLastTXTime`, now also provided by the JSON-RPC API as `last_block` and `last_transaction` in `getpeerinfo` output.

  Thanks to John Newbery, credited in the commit, and to Dave Harding and Adam Jonas during discussions on how to best explain these in this week's Optech newsletter.

ACKs for top commit:
  practicalswift:
    ACK d780293e1ee0f9e66bd2d88914694c17f9aaa0ca
  MarcoFalke:
    ACK d780293e1ee0f9e66bd2d88914694c17f9aaa0ca
  harding:
    ACK d780293e1ee0f9e66bd2d88914694c17f9aaa0ca .  The added documentation matches my reading of the code and answers a question I had after seeing #19731
  0xB10C:
    ACK d780293e1ee0f9e66bd2d88914694c17f9aaa0ca

Tree-SHA512: 72d47cf50a099913c7e4753cb80e11785b26fb66fa3a8b6c382fde4ea725116f3d215f93d32a567246d269768e66159f8dcf017a1bbc6d5f2489a35f81c316fa

2 files changed, 12 insertions, 3 deletions

diff --git a/src/net.cpp b/src/net.cpp
index 883e57bdf0..dc34743c5b 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -904,10 +904,10 @@ bool CConnman::AttemptToEvictConnection()
     // Protect the 8 nodes with the lowest minimum ping time.
     // An attacker cannot manipulate this metric without physically moving nodes closer to the target.
     EraseLastKElements(vEvictionCandidates, ReverseCompareNodeMinPingTime, 8);
-    // Protect 4 nodes that most recently sent us transactions.
+    // Protect 4 nodes that most recently sent us novel transactions accepted into our mempool.
     // An attacker cannot manipulate this metric without performing useful work.
     EraseLastKElements(vEvictionCandidates, CompareNodeTXTime, 4);
-    // Protect 4 nodes that most recently sent us blocks.
+    // Protect 4 nodes that most recently sent us novel blocks.
     // An attacker cannot manipulate this metric without performing useful work.
     EraseLastKElements(vEvictionCandidates, CompareNodeBlockTime, 4);
     // Protect the half of the remaining nodes which have been connected the longest.
diff --git a/src/net.h b/src/net.h
index c72eada3ff..0b5ab2390e 100644
--- a/src/net.h
+++ b/src/net.h
@@ -932,8 +932,17 @@ public:
     // Used for headers announcements - unfiltered blocks to relay
     std::vector<uint256> vBlockHashesToAnnounce GUARDED_BY(cs_inventory);
 
-    // Block and TXN accept times
+    /** UNIX epoch time of the last block received from this peer that we had
+     * not yet seen (e.g. not already received from another peer), that passed
+     * preliminary validity checks and was saved to disk, even if we don't
+     * connect the block or it eventually fails connection. Used as an inbound
+     * peer eviction criterium in CConnman::AttemptToEvictConnection. */
     std::atomic<int64_t> nLastBlockTime{0};
+
+    /** UNIX epoch time of the last transaction received from this peer that we
+     * had not yet seen (e.g. not already received from another peer) and that
+     * was accepted into our mempool. Used as an inbound peer eviction criterium
+     * in CConnman::AttemptToEvictConnection. */
     std::atomic<int64_t> nLastTXTime{0};
 
     // Ping time measurement: