network: clarify local_height/server_height

electrum/interface.py

@@ -306,8 +306,13 @@ class Interface(Logger):
         self.session = None  # type: Optional[NotificationSession]
         self._ipaddr_bucket = None
 
+        # Latest block header and corresponding height, as claimed by the server.
+        # Note that these values are updated before they are verified.
+        # Especially during initial header sync, verification can take a long time.
+        # Failing verification will get the interface closed.
         self.tip_header = None
         self.tip = 0
+
         self.fee_estimates_eta = {}
 
         # Dump network messages (only for this interface).  Set at runtime from the console.
@@ -621,6 +626,8 @@ class Interface(Logger):
                 raise GracefulDisconnect('server tip below max checkpoint')
             self._mark_ready()
             await self._process_header_at_tip()
+            # header processing done
+            util.trigger_callback('blockchain_updated')
             util.trigger_callback('network_updated')
             await self.network.switch_unwanted_fork_interface()
             await self.network.switch_lagging_interface()
@@ -636,7 +643,6 @@ class Interface(Logger):
             # in the simple case, height == self.tip+1
             if height <= self.tip:
                 await self.sync_until(height)
-        util.trigger_callback('blockchain_updated')
 
     async def sync_until(self, height, next_height=None):
         if next_height is None:

electrum/network.py

@@ -389,11 +389,7 @@ class Network(Logger, NetworkRetryManager[ServerAddr]):
         except:
             pass
 
-    def get_server_height(self):
-        interface = self.interface
-        return interface.tip if interface else 0
-
-    async def _server_is_lagging(self):
+    async def _server_is_lagging(self) -> bool:
         sh = self.get_server_height()
         if not sh:
             self.logger.info('no height for main interface')
@@ -631,7 +627,7 @@ class Network(Logger, NetworkRetryManager[ServerAddr]):
         '''If auto_connect and lagging, switch interface'''
         if self.auto_connect and await self._server_is_lagging():
             # switch to one that has the correct header (not height)
-            best_header = self.blockchain().read_header(self.get_local_height())
+            best_header = self.blockchain().header_at_tip()
             with self.interfaces_lock: interfaces = list(self.interfaces.values())
             filtered = list(filter(lambda iface: iface.tip_header == best_header, interfaces))
             if filtered:
@@ -1122,7 +1118,16 @@ class Network(Logger, NetworkRetryManager[ServerAddr]):
         net_params = net_params._replace(server=server)
         await self.set_parameters(net_params)
 
+    def get_server_height(self) -> int:
+        """Length of header chain, as claimed by main interface."""
+        interface = self.interface
+        return interface.tip if interface else 0
+
     def get_local_height(self):
+        """Length of header chain, POW-verified.
+        In case of a chain split, this is for the branch the main interface is on,
+        but it is the tip of that branch (even if main interface is behind).
+        """
         return self.blockchain().height()
 
     def export_checkpoints(self, path):