fix(libp2p): make AutoNAT log messages actionable for operators

.typos.toml

@@ -33,3 +33,5 @@ Forgetten = "Forgetten"
 typ = "typ"
 # Token Generation Event
 tge = "tge"
+# Rust crate name
+bimap = "bimap"

crates/hotshot/libp2p-networking/src/network/node.rs

@@ -84,6 +84,11 @@ pub const ESTABLISHED_LIMIT: NonZeroU32 = NonZeroU32::new(ESTABLISHED_LIMIT_UNWR
 /// Number of connections to a single peer before logging an error
 pub const ESTABLISHED_LIMIT_UNWR: u32 = 10;
 
+/// AutoNAT confidence at which we treat a Private status as definitive enough
+/// to escalate from a transient warning to a loud operator-facing error.
+/// Matches libp2p-autonat's default `confidence_max`.
+const AUTONAT_CONFIDENCE_MAX: usize = 3;
+
 /// Network definition
 #[derive(derive_more::Debug)]
 pub struct NetworkNode<T: NodeType, D: DhtPersistentStorage> {
@@ -104,6 +109,9 @@ pub struct NetworkNode<T: NodeType, D: DhtPersistentStorage> {
     dht_handler: DHTBehaviour<T::SignatureKey, D>,
     /// Channel to resend requests, set to Some when we call `spawn_listeners`
     resend_tx: Option<UnboundedSender<ClientRequest>>,
+    /// Whether we've already emitted the loud "not publicly reachable" error for the
+    /// current Private episode. Reset whenever AutoNAT leaves Private status.
+    autonat_private_logged: bool,
 }
 
 impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
@@ -267,7 +275,7 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
                 .set_publication_interval(Some(kademlia_record_republication_interval))
                 .set_record_ttl(Some(kademlia_ttl));
 
-            // allowing panic here because something is very wrong if this fales
+            // allowing panic here because something is very wrong if this fails
             #[allow(clippy::panic)]
             if let Some(factor) = config.replication_factor {
                 kconfig.set_replication_factor(factor);
@@ -355,6 +363,7 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
                     .unwrap_or(NonZeroUsize::new(4).unwrap()),
             ),
             resend_tx: None,
+            autonat_private_logged: false,
         })
     }
 
@@ -687,16 +696,46 @@ impl<T: NodeType, D: DhtPersistentStorage> NetworkNode<T, D> {
                                     peer,
                                     error,
                                 } => {
+                                    debug!("AutoNAT outbound probe to {peer:?} failed: {error:?}");
+                                },
+                            },
+                            autonat::Event::StatusChanged { old, new } => match &new {
+                                autonat::NatStatus::Public(addr) => {
+                                    info!(
+                                        "AutoNAT: this node is publicly reachable at {addr} (was \
+                                         {old:?})"
+                                    );
+                                    self.autonat_private_logged = false;
+                                },
+                                autonat::NatStatus::Private => {
                                     warn!(
-                                        "AutoNAT Probe failed to peer {peer:?} with error: \
-                                         {error:?}"
+                                        "AutoNAT: probe reports this node may not be publicly \
+                                         reachable (was {old:?}). Treating as transient until \
+                                         confirmed by repeated probes."
                                     );
                                 },
-                            },
-                            autonat::Event::StatusChanged { old, new } => {
-                                debug!("AutoNAT Status changed. Old: {old:?}, New: {new:?}");
+                                autonat::NatStatus::Unknown => {
+                                    debug!("AutoNAT status: {old:?} -> Unknown");
+                                    self.autonat_private_logged = false;
+                                },
                             },
                         };
+                        let autonat = &self.swarm.behaviour().autonat;
+                        if matches!(autonat.nat_status(), autonat::NatStatus::Private)
+                            && autonat.confidence() >= AUTONAT_CONFIDENCE_MAX
+                            && !self.autonat_private_logged
+                        {
+                            error!(
+                                "AutoNAT: this node is NOT publicly reachable (confirmed by \
+                                 repeated probes). Peers cannot direct-message us, so leader \
+                                 views may fail and we may accumulate missed slots. Verify \
+                                 --libp2p-advertise-address (env \
+                                 ESPRESSO_NODE_LIBP2P_ADVERTISE_ADDRESS) is set a publicly \
+                                 reachable host:port, and ensure inbound UDP at that port is open \
+                                 from the public internet (firewall/NAT/security group)."
+                            );
+                            self.autonat_private_logged = true;
+                        }
                         None
                     },
                 };