feat(p2p): add external address configuration for NAT/Docker

Validators can now announce their public IP instead of Docker internal IPs.
Use --external-addr CLI flag or EXTERNAL_ADDR env variable.

Example: --external-addr /ip4/1.2.3.4/tcp/8090

Author: echobt

bins/validator-node/src/main.rs

@@ -157,6 +157,11 @@ struct Args {
     #[arg(long, default_value = "/ip4/0.0.0.0/tcp/8090")]
     listen_addr: String,
 
+    /// External address to announce to peers (multiaddr format, e.g. /ip4/1.2.3.4/tcp/8090)
+    /// Use this when running behind NAT or in Docker to announce your public IP
+    #[arg(long, env = "EXTERNAL_ADDR")]
+    external_addr: Option<String>,
+
     /// Bootstrap peers (multiaddr format)
     #[arg(long)]
     bootstrap: Vec<String>,
@@ -269,6 +274,12 @@ async fn main() -> Result<()> {
         .with_netuid(args.netuid)
         .with_min_stake(10_000_000_000_000); // 10000 TAO
 
+    // Set external address if provided (for NAT/Docker environments)
+    if let Some(ref external_addr) = args.external_addr {
+        p2p_config = p2p_config.with_external_addrs(vec![external_addr.clone()]);
+        info!("External address configured: {}", external_addr);
+    }
+
     // Add CLI bootstrap peers to defaults (don't replace)
     for peer in &args.bootstrap {
         if !p2p_config.bootstrap_peers.contains(peer) {

crates/p2p-consensus/src/config.rs

@@ -21,6 +21,9 @@ pub const DEFAULT_BOOTSTRAP_NODES: &[&str] = &[
 pub struct P2PConfig {
     /// Listen addresses (multiaddr format)
     pub listen_addrs: Vec<String>,
+    /// External addresses to announce to peers (multiaddr format)
+    /// If empty, the node will try to detect its public IP automatically
+    pub external_addrs: Vec<String>,
     /// Bootstrap peers (multiaddr format)
     pub bootstrap_peers: Vec<String>,
     /// Gossipsub topic for consensus messages
@@ -50,6 +53,7 @@ impl Default for P2PConfig {
     fn default() -> Self {
         Self {
             listen_addrs: vec![format!("/ip4/0.0.0.0/tcp/{}", DEFAULT_P2P_PORT)],
+            external_addrs: vec![],
             bootstrap_peers: DEFAULT_BOOTSTRAP_NODES
                 .iter()
                 .map(|s| s.to_string())
@@ -98,10 +102,17 @@ impl P2PConfig {
         self
     }
 
+    /// Add external addresses to announce
+    pub fn with_external_addrs(mut self, addrs: Vec<String>) -> Self {
+        self.external_addrs = addrs;
+        self
+    }
+
     /// Create a development config with relaxed settings
     pub fn development() -> Self {
         Self {
             listen_addrs: vec!["/ip4/127.0.0.1/tcp/0".to_string()],
+            external_addrs: vec![],
             bootstrap_peers: vec![],
             consensus_topic: "platform/consensus/dev".to_string(),
             challenge_topic: "platform/challenge/dev".to_string(),
@@ -122,6 +133,7 @@ impl P2PConfig {
                 format!("/ip4/0.0.0.0/tcp/{}", DEFAULT_P2P_PORT),
                 format!("/ip6/::/tcp/{}", DEFAULT_P2P_PORT),
             ],
+            external_addrs: vec![],
             bootstrap_peers: DEFAULT_BOOTSTRAP_NODES
                 .iter()
                 .map(|s| s.to_string())

crates/p2p-consensus/src/network.rs

@@ -744,6 +744,20 @@ impl P2PNetwork {
             }
         }
 
+        // Add external addresses for announcement to other peers
+        // This is crucial for NAT traversal - we announce our public IP instead of internal Docker IPs
+        for addr_str in &self.config.external_addrs {
+            match addr_str.parse::<Multiaddr>() {
+                Ok(addr) => {
+                    swarm.add_external_address(addr.clone());
+                    info!(addr = %addr, "Added external address for announcement");
+                }
+                Err(e) => {
+                    error!(addr = %addr_str, error = %e, "Invalid external address");
+                }
+            }
+        }
+
         // Connect to bootstrap peers
         for addr_str in &self.config.bootstrap_peers {
             match addr_str.parse::<Multiaddr>() {

docker/entrypoint.sh

@@ -67,6 +67,10 @@ if [ -n "$BOOTSTRAP_PEERS" ]; then
     done
 fi
 
+if [ -n "$EXTERNAL_ADDR" ]; then
+    ARGS+=("--external-addr" "$EXTERNAL_ADDR")
+fi
+
 # Cleanup crash file on successful start
 cleanup() {
     rm -f "$CRASH_FILE"