Document how fork choice actually works

Author: teor2345

crates/sc-consensus-subspace/src/block_import.rs

@@ -638,6 +638,7 @@ where
         }
 
         let parent_weight = if block_number.is_one() {
+            // The genesis block is given a zero weight.
             0
         } else {
             // Parent block weight might be missing in special sync modes where block is imported in
@@ -646,6 +647,10 @@ where
                 .unwrap_or_default()
         };
 
+        // We prioritise smaller solution ranges numerically, using a solution weight of
+        // ~`2^64 - range` per block. Solution ranges can be up to ~`2^64`, so it is unlikely
+        // (but not impossible) that the total extrinsic weight exceeds the total solution weight
+        // (the maximum block extrinsic weight is ~2^41).
         let added_weight = calculate_block_weight(subspace_digest_items.solution_range);
         let total_weight = parent_weight.saturating_add(added_weight);
 
@@ -672,8 +677,27 @@ where
             }
         }
 
-        // The fork choice rule is that we pick the heaviest chain (i.e. smallest solution range),
-        // if there's a tie we go with the longest chain
+        // The fork choice rule is that we pick the largest total "chain weight".
+        // This almost always prioritises:
+        // - the longest chain (the largest number of solutions), and if there is a tie
+        // - the strictest solutions (the numerically smallest solution ranges),
+        //   and if there is a tie
+        // - the highest total extrinsic weight.
+        //
+        // If the totals are equal:
+        // - each node keeps the block it already chose (the one that it processed first).
+        //
+        // This check is performed using a single integer for the chain weight, so these priorities
+        // are not perfectly enforced. Unusually large solution ranges, large weights, or long forks
+        // can temporarily change the priority order above. But this is very unlikely to persist
+        // beyond a single block, particularly in networks with lots of storage, because the
+        // solution "weight" per block is much larger than any other factor.
+        //
+        // Solution ranges only change at the end of each epoch, but different block times can make
+        // the range in each fork different. This can lead to an edge case where one fork accepts a
+        // solution, but another does not. But this would also be resolved with very high
+        // probability after a few blocks. (And farmers are not incentivised to vote on multiple
+        // forks, because they have very limited time to vote and audit.)
         let fork_choice = {
             let info = self.client.info();