refactor: align pruning mode naming with Erigon conventions

This commit updates the pruning mode naming to match Erigon Ethereum
client conventions, making the API more familiar to users who have
experience with Erigon.

## Changes

### Core PruningMode Enum (crates/sync/stage/src/lib.rs)
Renamed modes to match Erigon:
- `Full` → `Archive` (keep all historical state)
- `HistoricalBlocks(N)` → `Full(N)` (keep last N blocks)
- `LatestOnly` → `Minimal` (keep only latest state)

Updated documentation to explicitly reference Erigon equivalents
and explain the mapping between the two systems.

### CLI Options (crates/cli/src/options.rs)
Updated argument names and documentation:
- `--pruning.mode` → `--prune.mode` (matches Erigon exactly)
- Mode values: `archive`, `full:N`, `minimal`
- Updated parser to handle new format

### Pipeline (crates/sync/pipeline/src/lib.rs)
- Updated default mode from `Full` to `Archive`
- Updated `is_enabled()` to check for `Archive` mode

### Tests
Updated all test functions to use new naming conventions
while maintaining the same test logic.

## Erigon Mapping

The naming now directly corresponds to Erigon's modes:
- `--prune.mode=archive` - Keep complete historical state
- `--prune.mode=full:1000` - Keep last 1000 blocks
- `--prune.mode=minimal` - Keep only latest state

## Usage Examples

Archive mode (no pruning):
```
katana node full --prune.mode archive
```

Full mode with 1000 block history, prune every 100 blocks:
```
katana node full --prune.mode full:1000 --prune.interval 100
```

Minimal mode for validators, prune every 50 blocks:
```
katana node full --prune.mode minimal --prune.interval 50
```

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

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

Author: kariy

crates/cli/src/full.rs

@@ -114,9 +114,9 @@ impl FullNodeArgs {
         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),
+            CliPruningMode::Archive => katana_stage::PruningMode::Archive,
+            CliPruningMode::Minimal => katana_stage::PruningMode::Minimal,
+            CliPruningMode::Full(n) => katana_stage::PruningMode::Full(*n),
         };
 
         Some(full::PruningConfig { mode, interval: self.pruning.interval })

crates/cli/src/options.rs

@@ -723,13 +723,13 @@ impl TracerOptions {
 #[derive(Debug, Args, Clone, Serialize, Deserialize, PartialEq)]
 #[command(next_help_heading = "Pruning options")]
 pub struct PruningOptions {
-    /// State pruning mode.
+    /// State pruning mode (follows Erigon conventions).
     ///
     /// 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")]
+    /// - 'archive': Keep all historical state (no pruning, default)
+    /// - 'full:N': Keep last N blocks of historical state
+    /// - 'minimal': Keep only the latest state
+    #[arg(long = "prune.mode", value_name = "MODE")]
     #[arg(value_parser = parse_pruning_mode)]
     #[serde(default)]
     pub mode: Option<PruningMode>,
@@ -738,7 +738,7 @@ pub struct PruningOptions {
     ///
     /// 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")]
+    #[arg(long = "prune.interval", value_name = "BLOCKS")]
     #[serde(default)]
     pub interval: Option<u64>,
 }
@@ -752,26 +752,26 @@ impl Default for PruningOptions {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "lowercase")]
 pub enum PruningMode {
-    Full,
-    Archive(u64),
-    Latest,
+    Archive,
+    Full(u64),
+    Minimal,
 }
 
 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:") => {
+        "archive" => Ok(PruningMode::Archive),
+        "minimal" => Ok(PruningMode::Minimal),
+        s if s.starts_with("full:") => {
             let n = s
-                .strip_prefix("archive:")
+                .strip_prefix("full:")
                 .and_then(|n| n.parse::<u64>().ok())
                 .ok_or_else(|| {
-                    format!("Invalid archive format. Use 'archive:N' where N is a number")
+                    format!("Invalid full format. Use 'full:N' where N is the number of blocks to keep")
                 })?;
-            Ok(PruningMode::Archive(n))
+            Ok(PruningMode::Full(n))
         }
         _ => Err(format!(
-            "Invalid pruning mode '{}'. Valid modes are: 'full', 'latest', 'archive:N'",
+            "Invalid pruning mode '{}'. Valid modes are: 'archive', 'minimal', 'full:N'",
             s
         )),
     }

crates/sync/pipeline/src/lib.rs

@@ -217,7 +217,7 @@ pub struct PruningConfig {
 
 impl Default for PruningConfig {
     fn default() -> Self {
-        Self { mode: PruningMode::Full, interval: None }
+        Self { mode: PruningMode::Archive, interval: None }
     }
 }
 
@@ -229,7 +229,7 @@ impl PruningConfig {
 
     /// Returns whether pruning is enabled.
     pub fn is_enabled(&self) -> bool {
-        !matches!(self.mode, PruningMode::Full) && self.interval.is_some()
+        !matches!(self.mode, PruningMode::Archive) && self.interval.is_some()
     }
 }
 

crates/sync/stage/src/lib.rs

@@ -66,19 +66,27 @@ pub struct StageExecutionOutput {
 }
 
 /// Pruning mode configuration that determines how much historical state to retain.
+///
+/// Naming follows the Erigon Ethereum client conventions:
+/// - `Archive`: Keep complete historical state (like Erigon's archive mode)
+/// - `Full`: Keep last N blocks of state (like Erigon's full mode with configurable distance)
+/// - `Minimal`: Keep only latest state (like Erigon's minimal mode for validators)
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PruningMode {
     /// Keep all historical state since genesis (no pruning).
-    Full,
+    /// Equivalent to Erigon's `--prune.mode=archive`.
+    Archive,
     /// Keep only the last N blocks of historical state.
-    HistoricalBlocks(u64),
+    /// Similar to Erigon's `--prune.mode=full` with `--prune.distance=N`.
+    Full(u64),
     /// Keep only the latest state, pruning all historical data.
-    LatestOnly,
+    /// Equivalent to Erigon's `--prune.mode=minimal`.
+    Minimal,
 }
 
 impl Default for PruningMode {
     fn default() -> Self {
-        Self::Full
+        Self::Archive
     }
 }
 
@@ -111,13 +119,13 @@ impl PruneInput {
 
     /// Calculates the block number before which all state should be pruned.
     ///
-    /// Returns `None` if no pruning should occur (e.g., in `Full` mode).
+    /// Returns `None` if no pruning should occur (e.g., in `Archive` mode).
     /// Returns `Some(block_number)` indicating that all state before this block can be pruned.
     pub fn prune_before(&self) -> Option<BlockNumber> {
         match self.mode {
-            PruningMode::Full => None,
-            PruningMode::LatestOnly => Some(self.tip.saturating_sub(1)),
-            PruningMode::HistoricalBlocks(n) => {
+            PruningMode::Archive => None,
+            PruningMode::Minimal => Some(self.tip.saturating_sub(1)),
+            PruningMode::Full(n) => {
                 if self.tip > n {
                     Some(self.tip - n)
                 } else {
@@ -239,33 +247,33 @@ mod tests {
     }
 
     #[test]
-    fn prune_before_full_mode() {
-        let input = PruneInput::new(1000, PruningMode::Full);
+    fn prune_before_archive_mode() {
+        let input = PruneInput::new(1000, PruningMode::Archive);
         assert_eq!(input.prune_before(), None);
     }
 
     #[test]
-    fn prune_before_latest_only() {
-        let input = PruneInput::new(1000, PruningMode::LatestOnly);
+    fn prune_before_minimal_mode() {
+        let input = PruneInput::new(1000, PruningMode::Minimal);
         assert_eq!(input.prune_before(), Some(999));
 
         // Edge case: tip at block 0
-        let input = PruneInput::new(0, PruningMode::LatestOnly);
+        let input = PruneInput::new(0, PruningMode::Minimal);
         assert_eq!(input.prune_before(), Some(0));
     }
 
     #[test]
-    fn prune_before_historical_blocks() {
+    fn prune_before_full_mode() {
         // Keep last 100 blocks, tip at 1000
-        let input = PruneInput::new(1000, PruningMode::HistoricalBlocks(100));
+        let input = PruneInput::new(1000, PruningMode::Full(100));
         assert_eq!(input.prune_before(), Some(900));
 
         // Keep last 100 blocks, tip at 50 (not enough blocks yet)
-        let input = PruneInput::new(50, PruningMode::HistoricalBlocks(100));
+        let input = PruneInput::new(50, PruningMode::Full(100));
         assert_eq!(input.prune_before(), None);
 
         // Keep last 100 blocks, tip at exactly 100
-        let input = PruneInput::new(100, PruningMode::HistoricalBlocks(100));
+        let input = PruneInput::new(100, PruningMode::Full(100));
         assert_eq!(input.prune_before(), Some(0));
     }
 }