GH-1523 add additional comments

libraries/chain/block_header_state.cpp

@@ -17,9 +17,9 @@ namespace eosio { namespace chain {
       }
 
       uint32_t get_next_next_round_block_num( block_timestamp_type t, uint32_t block_num ) {
-         auto index = t.slot % config::producer_repetitions;
-         //                 remainder of current                 + next round
-         return block_num + config::producer_repetitions - index + config::producer_repetitions;
+         auto index = t.slot % config::producer_repetitions; // current index in current round
+         //                 (increment to the end of this round  ) + next round
+         return block_num + (config::producer_repetitions - index) + config::producer_repetitions;
       }
    }
 
@@ -43,6 +43,9 @@ namespace eosio { namespace chain {
       return blocknums[ index ];
    }
 
+   // create pending_block_header_state from this for `when`
+   // If hotstuff_activated then use new consensus values and simpler active schedule update.
+   // If notstuff is not activated then use previous pre-hotstuff consensus logic.
    pending_block_header_state  block_header_state::next( block_timestamp_type when,
                                                          bool hotstuff_activated,
                                                          uint16_t num_prev_blocks_to_confirm )const
@@ -55,14 +58,14 @@ namespace eosio { namespace chain {
         (when = header.timestamp).slot++;
       }
 
-      auto proauth = get_scheduled_producer(when);
-
       result.block_num                                       = block_num + 1;
       result.previous                                        = id;
       result.timestamp                                       = when;
       result.active_schedule_version                         = active_schedule.version;
       result.prev_activated_protocol_features                = activated_protocol_features;
 
+      auto proauth = get_scheduled_producer(when);
+
       result.valid_block_signing_authority                   = proauth.authority;
       result.producer                                        = proauth.producer_name;
       result.last_proposed_finalizer_set_generation          = last_proposed_finalizer_set_generation;

libraries/chain/controller.cpp

@@ -3185,6 +3185,7 @@ std::optional<block_id_type> controller::pending_producer_block_id()const {
 
 void controller::set_hs_irreversible_block_num(uint32_t block_num) {
    // needs to be set by qc_chain at startup and as irreversible changes
+   assert(block_num > 0);
    my->hs_irreversible_block_num = block_num;
 }
 

libraries/hotstuff/chain_pacemaker.cpp

@@ -234,6 +234,7 @@ namespace eosio { namespace hotstuff {
             std::scoped_lock g( _chain_state_mutex );
             if (_active_finalizer_set.generation == 0) {
                // switching from dpos to hotstuff, all nodes will switch at same block height
+               // block header extension is set in finalize_block to value set by host function set_finalizers
                _chain->set_hs_irreversible_block_num(blk->block_num); // can be any value <= dpos lib
             }
             _active_finalizer_set = std::move(std::get<hs_finalizer_set_extension>(*ext));

plugins/producer_plugin/producer_plugin.cpp

@@ -1862,7 +1862,7 @@ producer_plugin_impl::start_block_result producer_plugin_impl::start_block() {
    try {
       uint16_t blocks_to_confirm = 0;
 
-      if (in_producing_mode() && hbs->dpos_irreversible_blocknum != hs_dpos_irreversible_blocknum) {
+      if (in_producing_mode() && hbs->dpos_irreversible_blocknum != hs_dpos_irreversible_blocknum) { // only if hotstuff not enabled
          // determine how many blocks this producer can confirm
          // 1) if it is not a producer from this node, assume no confirmations (we will discard this block anyway)
          // 2) if it is a producer on this node that has never produced, the conservative approach is to assume no