Update documentation and naming for legacy accrual code

This clarifies the usage of legacy tally and accrual code for blocks
version 10 and below. Blocks version 11 and higher follow superblock
snapshot accrual rules.

Author: cyrossignol

src/init.cpp

@@ -1166,7 +1166,7 @@ bool AppInit2(ThreadHandlerPtr threads)
         uiInterface.InitMessage(_("Loading Network Averages..."));
         if (fDebug3) LogPrintf("Loading network averages");
 
-        NN::Tally::LegacyRecount(NN::Tally::FindTrigger(pindexBest));
+        NN::Tally::LegacyRecount(NN::Tally::FindLegacyTrigger(pindexBest));
     }
 
     if (!threads->createThread(StartNode, NULL, "Start Thread"))

src/main.cpp

@@ -2956,7 +2956,7 @@ bool DisconnectBlocksBatch(CTxDB& txdb, list<CTransaction>& vResurrect, unsigned
 
         // Tally research averages.
         if(IsV9Enabled_Tally(nBestHeight) && !IsV11Enabled(nBestHeight)) {
-            assert(NN::Tally::IsTrigger(nBestHeight));
+            assert(NN::Tally::IsLegacyTrigger(nBestHeight));
             NN::Tally::LegacyRecount(pindexBest);
         }
     }
@@ -2998,7 +2998,7 @@ bool ReorganizeChain(CTxDB& txdb, unsigned &cnt_dis, unsigned &cnt_con, CBlock &
         //
         if (!IsV11Enabled(pcommon->nHeight) && pcommon != pindexBest)
         {
-            pcommon = NN::Tally::FindTrigger(pcommon);
+            pcommon = NN::Tally::FindLegacyTrigger(pcommon);
             if(!pcommon)
                 return error("ReorganizeChain: unable to find fork root with tally point");
         }
@@ -3128,7 +3128,7 @@ bool ReorganizeChain(CTxDB& txdb, unsigned &cnt_dis, unsigned &cnt_con, CBlock &
 
         if (IsV9Enabled_Tally(nBestHeight)
             && !IsV11Enabled(nBestHeight)
-            && NN::Tally::IsTrigger(nBestHeight))
+            && NN::Tally::IsLegacyTrigger(nBestHeight))
         {
             NN::Tally::LegacyRecount(pindexBest);
         }

src/neuralnet/accrual/newbie.h

@@ -8,7 +8,7 @@ using namespace NN;
 
 //!
 //! \brief An accrual calculator for a CPID that never earned a research reward
-//! before.
+//! before. Used for legacy accrual calculations in block version 10 and below.
 //!
 class NewbieAccrualComputer : public IAccrualComputer
 {

src/neuralnet/accrual/research_age.h

@@ -37,7 +37,8 @@ int64_t GetMaxResearchSubsidy(const int64_t nTime)
 
 //!
 //! \brief A calculator that computes the accrued research rewards for a
-//! research account using research age rules.
+//! research account using legacy research age rules in block version 10
+//! and below.
 //!
 class ResearchAgeComputer : public IAccrualComputer
 {

src/neuralnet/tally.cpp

@@ -14,12 +14,6 @@ using namespace NN;
 using LogFlags = BCLog::LogFlags;
 
 namespace {
-//!
-//! \brief Number of days that the tally scans backward from to calculate
-//! the average network payment.
-//!
-constexpr size_t TALLY_DAYS = 14;
-
 //!
 //! \brief Set the correct CPID from the block claim when the block index
 //! contains a zero CPID.
@@ -55,25 +49,27 @@ void RepairZeroCpidIndex(CBlockIndex* const pindex)
     }
 }
 
-//!
-//! \brief Round a value to intervals of 0.025.
-//!
-//! Used to calculate the network magnitude unit.
-//!
-double SnapToGrid(double d)
-{
-    double dDither = .04;
-    double dOut = RoundFromString(RoundToString(d * dDither, 3), 3) / dDither;
-    return dOut;
-}
-
 //!
 //! \brief Contains the two-week network average tally used to produce the
-//! magnitude unit for research age reward calculations.
+//! magnitude unit for legacy research age reward calculations (version 10
+//! blocks and below).
+//!
+//! Before block version 11, the network used a feedback filter to limit the
+//! total research reward generated over a rolling two week window. To scale
+//! rewards accordingly, the magnitude unit acts as a multiplier and changes
+//! in response to the amount of research rewards minted over the two weeks.
+//! This class holds state for the parameters that produce a magnitude units
+//! at a point in time.
 //!
 class NetworkTally
 {
 public:
+    //!
+    //! \brief Number of days that the tally scans backward from to calculate
+    //! the average network payment.
+    //!
+    static constexpr size_t TALLY_DAYS = 14;
+
     //!
     //! \brief Get the maximum network-wide research reward amount per day.
     //!
@@ -137,6 +133,16 @@ class NetworkTally
 private:
     uint32_t m_total_magnitude = 0;         //!< Sum of the magnitude of all CPIDs.
     double m_two_week_research_subsidy = 0; //!< Sum of research subsidy payments.
+
+    //!
+    //! \brief Round a magnitude unit value to intervals of 0.025.
+    //!
+    static double SnapToGrid(double d)
+    {
+        double dDither = .04;
+        double dOut = RoundFromString(RoundToString(d * dDither, 3), 3) / dDither;
+        return dOut;
+    }
 }; // NetworkTally
 
 //!
@@ -380,7 +386,7 @@ class ResearcherTally
 }; // ResearcherTally
 
 ResearcherTally g_researcher_tally; //!< Tracks lifetime research rewards.
-NetworkTally g_network_tally;       //!< Tracks two-week network averages.
+NetworkTally g_network_tally;       //!< Tracks legacy two-week network averages.
 
 } // Anonymous namespace
 
@@ -433,17 +439,17 @@ bool Tally::ActivateSnapshotAccrual(const CBlockIndex* const pindex)
         Quorum::CurrentSuperblock());
 }
 
-bool Tally::IsTrigger(const uint64_t height)
+bool Tally::IsLegacyTrigger(const uint64_t height)
 {
     return height % TALLY_GRANULARITY == 0;
 }
 
-CBlockIndex* Tally::FindTrigger(CBlockIndex* pindex)
+CBlockIndex* Tally::FindLegacyTrigger(CBlockIndex* pindex)
 {
     // Scan backwards until we find one where accepting it would
     // trigger a tally.
     for (;
-        pindex && pindex->pprev && !IsTrigger(pindex->nHeight);
+        pindex && pindex->pprev && !IsLegacyTrigger(pindex->nHeight);
         pindex = pindex->pprev);
 
     return pindex;
@@ -582,7 +588,7 @@ void Tally::LegacyRecount(const CBlockIndex* pindex)
     LogPrint(LogFlags::TALLY, "Tally::LegacyRecount(%" PRId64 ")", pindex->nHeight);
 
     const int64_t consensus_depth = pindex->nHeight - CONSENSUS_LOOKBACK;
-    const int64_t lookback_depth = BLOCKS_PER_DAY * TALLY_DAYS;
+    const int64_t lookback_depth = BLOCKS_PER_DAY * NetworkTally::TALLY_DAYS;
 
     int64_t max_depth = consensus_depth - (consensus_depth % TALLY_GRANULARITY);
     int64_t min_depth = max_depth - lookback_depth;

src/neuralnet/tally.h

@@ -56,7 +56,7 @@ class Tally
     //!
     //! \return \c true if the block height should trigger a recount.
     //!
-    static bool IsTrigger(const uint64_t height);
+    static bool IsLegacyTrigger(const uint64_t height);
 
     //!
     //! \brief Find the previous tally trigger below the specified block.
@@ -65,7 +65,7 @@ class Tally
     //!
     //! \return Index of the first tally trigger block.
     //!
-    static CBlockIndex* FindTrigger(CBlockIndex* pindex);
+    static CBlockIndex* FindLegacyTrigger(CBlockIndex* pindex);
 
     //!
     //! \brief Get the maximum network-wide research reward amount per day.