feat: add CLI support for state pruning configuration

This commit adds command-line interface support for configuring state
pruning in full nodes, allowing users to control historical state retention
directly through CLI arguments.

## Changes

### CLI Options (crates/cli/src/options.rs)
- Added `PruningOptions` struct with two configuration parameters:
  - `--pruning.mode`: Specifies pruning strategy
    - `full`: Keep all state (default)
    - `latest`: Keep only latest state
    - `archive:N`: Keep last N blocks
  - `--pruning.interval`: Blocks between pruning runs

- Added `PruningMode` enum (CLI representation)
- Implemented `parse_pruning_mode` parser for flexible mode specification

### Full Node Integration (crates/cli/src/full.rs)
- Added `pruning` field to `FullNodeArgs`
- Implemented `pruning_config()` to convert CLI options to pipeline config
- Maps CLI `PruningMode` to `katana_stage::PruningMode`

### Node Configuration (crates/node/src/full/mod.rs)
- Added `pruning` field to full node `Config`
- Exported `PruningConfig` from `katana_pipeline` for reuse
- Wired pruning config to pipeline during node build

## Usage Examples

Keep only last 1000 blocks, prune every 100 blocks:
```
katana node full --pruning.mode archive:1000 --pruning.interval 100
```

Keep only latest state, prune every 50 blocks:
```
katana node full --pruning.mode latest --pruning.interval 50
```

No pruning (default):
```
katana node full
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kariy

crates/cli/src/full.rs

@@ -54,6 +54,9 @@ pub struct FullNodeArgs {
     #[cfg(feature = "explorer")]
     #[command(flatten)]
     pub explorer: ExplorerOptions,
+
+    #[command(flatten)]
+    pub pruning: PruningOptions,
 }
 
 impl FullNodeArgs {
@@ -95,16 +98,30 @@ impl FullNodeArgs {
         let db = self.db_config();
         let rpc = self.rpc_config()?;
         let metrics = self.metrics_config();
+        let pruning = self.pruning_config();
 
         Ok(full::Config {
             db,
             rpc,
             metrics,
+            pruning,
             network: self.network,
             gateway_api_key: self.gateway_api_key.clone(),
         })
     }
 
+    fn pruning_config(&self) -> Option<full::PruningConfig> {
+        use crate::options::PruningMode as CliPruningMode;
+
+        let mode = match self.pruning.mode.as_ref()? {
+            CliPruningMode::Full => katana_stage::PruningMode::Full,
+            CliPruningMode::Latest => katana_stage::PruningMode::LatestOnly,
+            CliPruningMode::Archive(n) => katana_stage::PruningMode::HistoricalBlocks(*n),
+        };
+
+        Some(full::PruningConfig { mode, interval: self.pruning.interval })
+    }
+
     fn db_config(&self) -> DbConfig {
         DbConfig { dir: Some(self.db_dir.clone()) }
     }

crates/cli/src/options.rs

@@ -719,3 +719,60 @@ impl TracerOptions {
         self
     }
 }
+
+#[derive(Debug, Args, Clone, Serialize, Deserialize, PartialEq)]
+#[command(next_help_heading = "Pruning options")]
+pub struct PruningOptions {
+    /// State pruning mode.
+    ///
+    /// Determines how much historical state to retain:
+    /// - 'full': Keep all historical state (no pruning, default)
+    /// - 'archive:N': Keep last N blocks of historical state
+    /// - 'latest': Keep only the latest state
+    #[arg(long = "pruning.mode", value_name = "MODE")]
+    #[arg(value_parser = parse_pruning_mode)]
+    #[serde(default)]
+    pub mode: Option<PruningMode>,
+
+    /// Number of blocks to process between pruning runs.
+    ///
+    /// Pruning will be triggered after every N blocks are synced.
+    /// If not specified, pruning is disabled even if a pruning mode is set.
+    #[arg(long = "pruning.interval", value_name = "BLOCKS")]
+    #[serde(default)]
+    pub interval: Option<u64>,
+}
+
+impl Default for PruningOptions {
+    fn default() -> Self {
+        Self { mode: None, interval: None }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "lowercase")]
+pub enum PruningMode {
+    Full,
+    Archive(u64),
+    Latest,
+}
+
+fn parse_pruning_mode(s: &str) -> Result<PruningMode, String> {
+    match s.to_lowercase().as_str() {
+        "full" => Ok(PruningMode::Full),
+        "latest" => Ok(PruningMode::Latest),
+        s if s.starts_with("archive:") => {
+            let n = s
+                .strip_prefix("archive:")
+                .and_then(|n| n.parse::<u64>().ok())
+                .ok_or_else(|| {
+                    format!("Invalid archive format. Use 'archive:N' where N is a number")
+                })?;
+            Ok(PruningMode::Archive(n))
+        }
+        _ => Err(format!(
+            "Invalid pruning mode '{}'. Valid modes are: 'full', 'latest', 'archive:N'",
+            s
+        )),
+    }
+}

crates/node/src/full/mod.rs

@@ -58,11 +58,14 @@ pub enum Network {
     Sepolia,
 }
 
+pub use katana_pipeline::PruningConfig;
+
 #[derive(Debug)]
 pub struct Config {
     pub db: DbConfig,
     pub rpc: RpcConfig,
     pub metrics: Option<MetricsConfig>,
+    pub pruning: Option<PruningConfig>,
     pub gateway_api_key: Option<String>,
     pub network: Network,
 }
@@ -122,6 +125,12 @@ impl Node {
         // --- build pipeline
 
         let (mut pipeline, pipeline_handle) = Pipeline::new(provider.clone(), 50);
+
+        // Configure pruning if specified
+        if let Some(pruning_config) = config.pruning {
+            pipeline.set_pruning_config(pruning_config);
+        }
+
         let block_downloader = BatchBlockDownloader::new_gateway(gateway_client.clone(), 8);
         pipeline.add_stage(Blocks::new(provider.clone(), block_downloader));
         pipeline.add_stage(Classes::new(provider.clone(), gateway_client.clone(), 8));