feat: add estimate-size subcommand for network size estimation

src/bin/ant-node/cli.rs

@@ -4,7 +4,7 @@ use ant_node::config::{
     BootstrapCacheConfig, BootstrapPeersConfig, BootstrapSource, EvmNetworkConfig, NetworkMode,
     NodeConfig, PaymentConfig, UpgradeChannel,
 };
-use clap::{Parser, ValueEnum};
+use clap::{Parser, Subcommand, ValueEnum};
 use std::net::SocketAddr;
 use std::path::PathBuf;
 
@@ -145,6 +145,49 @@ pub struct Cli {
     /// Maximum peers to cache in the bootstrap cache.
     #[arg(long, default_value = "10000", env = "ANT_BOOTSTRAP_CACHE_CAPACITY")]
     pub bootstrap_cache_capacity: usize,
+
+    /// Optional subcommand. When omitted, `ant-node` runs as a network node
+    /// using the top-level flags above (the default and pre-existing behavior).
+    #[command(subcommand)]
+    pub command: Option<Command>,
+}
+
+/// Subcommands that change `ant-node` from "run as a network node" to a
+/// different one-shot operation. Adding subcommands here is non-breaking:
+/// invocations without a subcommand still launch the node.
+#[derive(Subcommand, Debug)]
+pub enum Command {
+    /// Estimate the size of the live network.
+    ///
+    /// Bootstraps into the network in client mode (does not participate
+    /// in DHT routing), performs many random-key iterative `FIND_NODE`
+    /// lookups to sample keyspace density, prints an averaged estimate
+    /// with a confidence interval, then exits.
+    EstimateSize {
+        /// Number of random-key samples to take. More samples → tighter
+        /// confidence interval; the standard error scales as 1/sqrt(n).
+        #[arg(long, default_value = "32")]
+        samples: usize,
+
+        /// Number of closest peers to retrieve per lookup (Kademlia `k`).
+        /// When `0`, the saorsa-core default is used.
+        #[arg(long, default_value = "0")]
+        k: usize,
+
+        /// Per-lookup timeout, in seconds. Defaults to 90s — saorsa-core's
+        /// iterative lookup can take this long when a dead peer's dial
+        /// cascade drags out an early iteration.
+        #[arg(long, default_value = "90")]
+        lookup_timeout_secs: u64,
+
+        /// Bootstrap-completion timeout, in seconds.
+        #[arg(long, default_value = "60")]
+        bootstrap_timeout_secs: u64,
+
+        /// Print per-sample peer counts alongside each density estimate as we go.
+        #[arg(long)]
+        verbose: bool,
+    },
 }
 
 /// Upgrade channel CLI enum.

src/bin/ant-node/main.rs

@@ -6,11 +6,13 @@ mod cli;
 mod platform;
 
 use ant_node::config::BootstrapSource;
+use ant_node::estimator::{estimate_network_size, EstimatorParams};
 use ant_node::NodeBuilder;
 use clap::Parser;
-use cli::Cli;
 #[cfg(feature = "logging")]
 use cli::CliLogFormat;
+use cli::{Cli, Command};
+use std::time::Duration;
 #[cfg(feature = "logging")]
 use tracing_subscriber::prelude::*;
 #[cfg(feature = "logging")]
@@ -96,7 +98,7 @@ fn init_logging(
 async fn main() -> color_eyre::Result<()> {
     color_eyre::install()?;
 
-    let cli = Cli::parse();
+    let mut cli = Cli::parse();
 
     // _guard must live for the duration of main() to ensure log flushing.
     #[cfg(feature = "logging")]
@@ -122,6 +124,9 @@ async fn main() -> color_eyre::Result<()> {
         }
     };
 
+    // Extract subcommand (if any) before consuming `cli` via `into_config()`.
+    let command = cli.command.take();
+
     // Build configuration
     let (config, bootstrap_source) = cli.into_config()?;
 
@@ -152,9 +157,45 @@ async fn main() -> color_eyre::Result<()> {
         }
     }
 
-    let mut node = NodeBuilder::new(config).build().await?;
-    node.run().await?;
+    match command {
+        None => {
+            let mut node = NodeBuilder::new(config).build().await?;
+            node.run().await?;
+            ant_node::logging::info!("Goodbye!");
+        }
+        Some(Command::EstimateSize {
+            samples,
+            k,
+            lookup_timeout_secs,
+            bootstrap_timeout_secs,
+            verbose,
+        }) => {
+            let params = EstimatorParams {
+                samples,
+                k,
+                lookup_timeout: Duration::from_secs(lookup_timeout_secs),
+                bootstrap_timeout: Duration::from_secs(bootstrap_timeout_secs),
+                verbose,
+            };
+            let estimate = estimate_network_size(&config, params).await?;
+            print_estimate(&estimate);
+        }
+    }
 
-    ant_node::logging::info!("Goodbye!");
     Ok(())
 }
+
+fn print_estimate(est: &ant_node::estimator::SizeEstimate) {
+    println!("Network size estimate:");
+    println!("  mean       : {:>12.0}", est.mean);
+    println!("  median     : {:>12.0}", est.median);
+    println!(
+        "  95% confidence interval : [{:.0}, {:.0}]",
+        est.ci_low, est.ci_high
+    );
+    println!(
+        "  samples    : {} successful / {} attempted",
+        est.samples_successful, est.samples_attempted
+    );
+    println!("  k (per-lookup): {}", est.k_used);
+}