Address review

chain/store/store.go

@@ -428,8 +428,12 @@ func (cs *ChainStore) RefreshHeaviestTipSet(ctx context.Context, newTsHeight abi
 	// Equivocation has occurred! We need a new head NOW!
 	if newHeaviest == nil || newHeaviestWeight.LessThan(heaviestWeight) {
 		log.Warnf("chainstore heaviest tipset's weight SHRANK from %d (%s) to %d (%s) due to equivocation", heaviestWeight, cs.heaviest, newHeaviestWeight, newHeaviest)
-		// refresh heaviestWeight 10 times moving up and down
-
+		// Unfortunately, we don't know what the right height to form a new heaviest tipset is.
+		// It is _probably_, but not _necessarily_, heaviestHeight.
+		// So, we need to explore a range of epochs, finding the heaviest tipset in that range.
+		// We thus try to form the heaviest tipset for 5 epochs above heaviestHeight (most of which will likely not exist),
+		// as well as for 5 below.
+		// This is slow, but we expect to almost-never be here (only if miners are equivocating, which carries a hefty penalty).
 		for i := heaviestHeight + 5; i > heaviestHeight-5; i-- {
 			possibleHeaviestTs, possibleHeaviestWeight, err := cs.FormHeaviestTipSetForHeight(ctx, i)
 			if err != nil {

chain/sync.go

@@ -247,7 +247,6 @@ func (syncer *Syncer) InformNewHead(from peer.ID, fts *store.FullTipSet) bool {
 		return false
 	}
 
-	// TODO: this method name is a lie
 	syncer.syncmgr.SetPeerHead(ctx, from, fts.TipSet())
 	return true
 }

chain/sync_manager.go

@@ -92,6 +92,7 @@ type syncManager struct {
 var _ SyncManager = (*syncManager)(nil)
 
 type peerHead struct {
+	// Note: this doesn't _necessarily_ mean that p's head is ts, just that ts is a tipset that p sent to us
 	p  peer.ID
 	ts *types.TipSet
 }