fix(network): avoid disconnecting peers that return empty find responses at the chain tip (#10732)

* Add `chain_tip` getter to `MinimumPeerVersion`

In some places the `MinimumPeerVersion` becomes the way to access the
`ChainTip`, so we should make that explicit instead of adding unrelated
methods to `MinimumPeerVersion`.

* Remove `MinimumPeerVersion::chain_tip_height`

Refactor to keep `MinimumPeerVersion` more focused.

* Add `ChainTip::is_at_or_near_network_tip`

A helper method to check if the node can be considered to be synced.

* Only count stalls while syncing

Empty find block or find headers responses are expected once nodes are
synced.

* Test if stalls aren't tracked when close to tip

Ensure that the stall tracker only disconnects peers while the node is
syncing.

* Test disconnection after empty find responses

Empty find blocks or find headers responses can slow down
synchronization, so the peers should be penalized with a disconnection.

* Also test if the chain tip state is empty

Ensure that the initial behavior is to disconnect from peers that return
empty find blocks or headers responses.

* Test stall counts are preserved after sync

Ensure that if the node falls behind, it will still track stalls from
peers.

* Add a regression test for the disconnection issue

Simulate the scenario described in the issue, where an internal Zebra
node disconnects from its upstream (and sole peer) because it has
finished syncing.

* Update changelog

List the fix to not disconnect from peers missing blocks when synced.

Author: jvff

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to Zebra are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org).
 
+## [Unreleased]
+
+### Fixed
+
+- Don't disconnect from peers that return empty `FindBlocks` or `FindHeaders`
+  responses when the local node is at or near the chain tip
+  ([#10732](https://github.com/ZcashFoundation/zebra/pull/10732))
+
 ## [Zebra 6.0.0-rc.0](https://github.com/ZcashFoundation/zebra/releases/tag/v6.0.0-rc.0) - 2026-07-02
 
 ### Added

zebra-chain/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- `AT_OR_NEAR_TIP_THRESHOLD` constant and `ChainTip::is_at_or_near_network_tip()`
+  method for determining whether the node is within 5 blocks of the estimated network tip
+  ([#10732](https://github.com/ZcashFoundation/zebra/pull/10732))
+
 ## [11.0.0] - 2026-07-02
 
 ### Added

zebra-chain/src/chain_tip.rs

@@ -15,6 +15,13 @@ mod tests;
 
 pub use network_chain_tip_height_estimator::NetworkChainTipHeightEstimator;
 
+/// The maximum estimated distance to the network chain tip that is considered "at or near tip".
+///
+/// Allows for normal block-time variance and propagation delay. Considering the 75 second target
+/// for the time between blocks on mainnet, this equals approximately 6 minutes of time the node
+/// can stay without receiving a new block before being considered far from the tip.
+pub const AT_OR_NEAR_TIP_THRESHOLD: block::HeightDiff = 5;
+
 /// An interface for querying the chain tip.
 ///
 /// This trait helps avoid dependencies between:
@@ -118,6 +125,18 @@ pub trait ChainTip {
 
         Some((distance_to_tip, current_height))
     }
+
+    /// Returns `true` if the node is at or near the network chain tip.
+    ///
+    /// Returns `false` if the chain is empty or the node is more than
+    /// [`AT_OR_NEAR_TIP_THRESHOLD`] blocks behind the estimated network tip,
+    /// meaning stall detection should remain active.
+    fn is_at_or_near_network_tip(&self, network: &Network) -> bool {
+        match self.estimate_distance_to_network_chain_tip(network) {
+            None => false,
+            Some((distance, _height)) => distance <= AT_OR_NEAR_TIP_THRESHOLD,
+        }
+    }
 }
 
 /// A chain tip that is always empty and never changes.

zebra-network/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Breaking Changes
+
+- `MinimumPeerVersion::chain_tip_height()` is replaced by `chain_tip()`, which returns a
+  reference to the underlying chain tip instead of a `Height`
+  ([#10732](https://github.com/ZcashFoundation/zebra/pull/10732))
+
 ## [10.0.0] - 2026-07-02
 
 ### Breaking Changes

zebra-network/src/peer/handshake.rs

@@ -28,6 +28,7 @@ use tracing::{span, Level, Span};
 use tracing_futures::Instrument;
 
 use zebra_chain::{
+    block,
     chain_tip::{ChainTip, NoChainTip},
     parameters::Network,
     serialization::{DateTime32, SerializationError},
@@ -674,6 +675,11 @@ where
         }
     };
 
+    let start_height = minimum_peer_version
+        .chain_tip()
+        .best_tip_height()
+        .unwrap_or(block::Height(0));
+
     let our_version = VersionMessage {
         version: constants::CURRENT_NETWORK_PROTOCOL_VERSION,
         services: our_services,
@@ -683,7 +689,7 @@ where
         address_from: AddrInVersion::new(our_listen_addr, our_services),
         nonce: local_nonce,
         user_agent: user_agent.clone(),
-        start_height: minimum_peer_version.chain_tip_height(),
+        start_height,
         relay,
     }
     .into();

zebra-network/src/peer/minimum_peer_version.rs

@@ -2,7 +2,7 @@
 
 use std::fmt;
 
-use zebra_chain::{block::Height, chain_tip::ChainTip, parameters::Network};
+use zebra_chain::{chain_tip::ChainTip, parameters::Network};
 
 use crate::protocol::external::types::Version;
 
@@ -80,14 +80,9 @@ where
         }
     }
 
-    /// Return the current chain tip height.
-    ///
-    /// If it is not available return height zero.
-    pub fn chain_tip_height(&self) -> Height {
-        match self.chain_tip.best_tip_height() {
-            Some(height) => height,
-            None => Height(0),
-        }
+    /// Returns a reference to the underlying chain tip.
+    pub fn chain_tip(&self) -> &C {
+        &self.chain_tip
     }
 }
 

zebra-network/src/peer_set/set.rs

@@ -943,10 +943,17 @@ where
                 .take_ready_service(&p2c_key)
                 .expect("selected peer must be ready");
 
-            let track_stalls = matches!(
+            let is_find_request = matches!(
                 &req,
                 Request::FindBlocks { .. } | Request::FindHeaders { .. }
             );
+            let is_syncing = || {
+                !self
+                    .minimum_peer_version
+                    .chain_tip()
+                    .is_at_or_near_network_tip(&self.network)
+            };
+            let track_stalls = is_find_request && is_syncing();
 
             let fut = svc.call(req);
             self.push_unready(p2c_key, svc);