fix(crawl): bound activation observation sweeps

Author: gustavovalverde

docs/adr/0007-observed-network-upgrade-activation.md

@@ -14,7 +14,7 @@ Peers already report their start height and protocol version during the Zcash ha
 
 Each crawler starts its `SeederChainTip` immediately below the newest compiled activation height. It raises the tip to that activation height only after an independent observer confirms all of these conditions:
 
-- The observer samples 1 recently live, outbound, full node from each available IPv4 `/16` or IPv6 `/32` network group.
+- The observer uniformly samples at most 64 available IPv4 `/16` or IPv6 `/32` network groups, then chooses 1 recently live, outbound, full node from each selected group.
 - At least 12 network groups participate in a completed sweep.
 - At least 75% of the sampled groups report a start height at or above the activation height plus Zebra's maximum reorganization depth, negotiate the new protocol version, and advertise `NODE_NETWORK`.
 - The threshold holds for 3 consecutive sweeps, separated by the target block spacing. A timeout, failed handshake, or nonqualifying response remains in the denominator and counts as not ready.
@@ -25,14 +25,15 @@ Before raising the floor, Zeeder atomically persists an exact record of the acti
 
 ## Rationale
 
-Network-group voting limits the weight of many addresses from one prefix, while the minimum group count prevents a small, internally consistent view from deciding activation. A fixed 75% threshold requires a supermajority without allowing a stalled minority to block the transition indefinitely. Requiring 3 spaced sweeps rejects brief height spikes and transient partitions, and waiting through the maximum reorganization depth avoids reacting at the activation boundary.
+Network-group voting limits the weight of many addresses from one prefix, while uniform selection prevents prefixes containing more addresses from gaining extra sampling weight. The 64-group cap bounds concurrent handshakes and prevents an attacker-influenced address book from expanding the quorum denominator. The minimum group count prevents a small, internally consistent view from deciding activation, and a fixed 75% threshold requires a supermajority without allowing a stalled minority to block the transition indefinitely. Requiring 3 spaced sweeps rejects brief height spikes and transient partitions, while waiting through the maximum reorganization depth avoids reacting at the activation boundary.
 
 The algorithm treats missing evidence conservatively. Failed and timed-out probes do not disappear from the denominator, and any nonqualifying sweep resets the consecutive-sweep counter. Persistence makes the transition monotonic across ordinary restarts and fleet rolls.
 
 ## Consequences
 
 - Zeeder can be deployed before activation without removing nodes that satisfy the previous protocol floor.
 - Each Zeeder instance decides independently from the peers it has discovered, so the design adds no node or endpoint dependency.
+- Each observation sweep opens at most 64 concurrent isolated handshakes.
 - The protocol floor can rise later than the chain reaches the confirmation height when the address book lacks 12 groups or fewer than 75% of groups qualify.
 - After confirmation, the servable-peer cache rechecks each peer's negotiated version against the new floor, which removes handshakes admitted under the previous floor from DNS responses immediately.
 - Peer start heights remain self-reported. An attacker that controls at least 75% of the sampled network groups, or fully eclipses a seeder, can still cause a false confirmation; this design raises the cost of false evidence but cannot authenticate chain work.

docs/architecture.md

@@ -119,7 +119,7 @@ sequenceDiagram
 
 ### Observed Activation
 
-The activation observer separates a compiled upgrade target from proof that the network has reached it. Each sweep chooses 1 recently live peer per IPv4 `/16` or IPv6 `/32` group from the crawler's own address book, then performs an isolated handshake that accepts the previous protocol floor. At least 75% of 12 or more groups must report the target version and a height beyond the activation plus maximum reorganization depth for 3 consecutive sweeps.
+The activation observer separates a compiled upgrade target from proof that the network has reached it. Each sweep uniformly selects at most 64 IPv4 `/16` or IPv6 `/32` groups from the crawler's own address book, chooses 1 recently live peer per selected group, and performs isolated handshakes that accept the previous protocol floor. At least 75% of 12 or more sampled groups must report the target version and a height beyond the activation plus maximum reorganization depth for 3 consecutive sweeps.
 
 After the final qualifying sweep, the observer persists the exact decision and advances `SeederChainTip`. zebra-network receives the height change through its `ChainTip` monitor, while the 5-second servable-peer refresh applies the same new minimum to cached handshakes. [ADR 0007](adr/0007-observed-network-upgrade-activation.md) defines the trust model, thresholds, and failure behavior.
 

docs/network-upgrades.md

@@ -8,7 +8,7 @@ Each network crawler starts immediately below the newest activation height compi
 
 The floor advances only after all of these conditions hold:
 
-- 1 peer is sampled from each available IPv4 `/16` or IPv6 `/32` network group.
+- At most 64 available IPv4 `/16` or IPv6 `/32` network groups are selected uniformly, with 1 peer sampled from each selected group.
 - At least 12 groups participate.
 - At least 75% of those groups report the activation height plus Zebra's maximum reorganization depth, negotiate the target protocol version, and advertise `NODE_NETWORK`.
 - The same threshold holds for 3 consecutive sweeps, separated by the target block spacing.
@@ -71,7 +71,7 @@ To force fresh observation after investigating a suspected false confirmation, s
 |----------|--------|
 | Does an upgrade require Zeeder configuration changes? | No |
 | Can the new image be deployed before activation? | Yes; deployment keeps the previous floor |
-| What causes the floor to rise? | 75% of at least 12 network groups qualifying across 3 consecutive sweeps after the confirmation height |
+| What causes the floor to rise? | 75% of a uniform sample of 12 to 64 network groups qualifying across 3 consecutive sweeps after the confirmation height |
 | Does Zeeder depend on a node or endpoint? | No; each instance observes peers from its own address book |
 | Must the peer cache be cleared? | No; preserve it for observation and restart continuity |
 | What is the recovery control? | Delete only the affected `.activation` record, then restart |

src/crawl/activation.rs

@@ -8,7 +8,7 @@
 //! make one impossible under a group-supermajority Sybil or full eclipse.
 
 use std::{
-    collections::HashSet,
+    collections::HashMap,
     io,
     net::IpAddr,
     path::{Path, PathBuf},
@@ -39,6 +39,9 @@ use crate::{
 /// Minimum independent network groups required for an activation decision.
 const MIN_NETWORK_GROUPS: usize = 12;
 
+/// Maximum independent network groups probed concurrently in one sweep.
+const MAX_NETWORK_GROUPS_PER_SWEEP: usize = 64;
+
 /// Fixed supermajority required in each sweep.
 const QUORUM_NUMERATOR: usize = 3;
 const QUORUM_DENOMINATOR: usize = 4;
@@ -181,6 +184,7 @@ pub(crate) fn spawn(
                 ready_groups = evidence.ready_groups,
                 qualifying_sweeps = gate.qualifying_sweeps(),
                 required_groups = MIN_NETWORK_GROUPS,
+                maximum_groups = MAX_NETWORK_GROUPS_PER_SWEEP,
                 required_sweeps = REQUIRED_QUALIFYING_SWEEPS,
                 quorum_numerator = QUORUM_NUMERATOR,
                 quorum_denominator = QUORUM_DENOMINATOR,
@@ -277,7 +281,7 @@ fn sample_network_groups(
     network: &Network,
     minimum_version: Version,
 ) -> Vec<PeerSocketAddr> {
-    let mut candidates = {
+    let candidates = {
         let book = match address_book.lock() {
             Ok(book) => book,
             Err(poisoned) => {
@@ -293,10 +297,24 @@ fn sample_network_groups(
             .collect::<Vec<_>>()
     };
 
+    sample_network_group_candidates(candidates)
+}
+
+/// Choose one random peer per group, then uniformly bound the group sample.
+fn sample_network_group_candidates(mut candidates: Vec<PeerSocketAddr>) -> Vec<PeerSocketAddr> {
     candidates.shuffle(&mut rng());
-    let mut sampled_groups = HashSet::new();
-    candidates.retain(|addr| sampled_groups.insert(network_group(addr.ip())));
-    candidates
+
+    let mut representative_by_group = HashMap::new();
+    for addr in candidates {
+        representative_by_group
+            .entry(network_group(addr.ip()))
+            .or_insert(addr);
+    }
+
+    let mut sampled_peers = representative_by_group.into_values().collect::<Vec<_>>();
+    sampled_peers.shuffle(&mut rng());
+    sampled_peers.truncate(MAX_NETWORK_GROUPS_PER_SWEEP);
+    sampled_peers
 }
 
 async fn observe_sweep(
@@ -362,8 +380,9 @@ async fn persist_confirmation(path: Option<PathBuf>, target: ActivationTarget) -
 #[cfg(test)]
 mod tests {
     use std::{
+        collections::HashSet,
         error::Error,
-        net::{IpAddr, Ipv4Addr, Ipv6Addr},
+        net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr},
     };
 
     use super::*;
@@ -447,6 +466,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn sampling_caps_unique_network_groups() {
+        let candidates = (1..=80)
+            .flat_map(|group| {
+                [1, 2].map(|host| {
+                    PeerSocketAddr::from(SocketAddr::new(
+                        IpAddr::V4(Ipv4Addr::new(group, 1, host, 1)),
+                        8233,
+                    ))
+                })
+            })
+            .collect();
+
+        let sampled = sample_network_group_candidates(candidates);
+        let sampled_groups = sampled
+            .iter()
+            .map(|addr| network_group(addr.ip()))
+            .collect::<HashSet<_>>();
+
+        assert_eq!(sampled.len(), MAX_NETWORK_GROUPS_PER_SWEEP);
+        assert_eq!(sampled_groups.len(), sampled.len());
+    }
+
     #[test]
     fn latest_mainnet_target_requires_reorg_safe_nu6_3_depth() {
         let target = ActivationTarget::latest(&Network::Mainnet);