feat: move default data dir (#499)

* feat: move default data dir

* docs: update changelogs

* docs: update path references

---------

Co-authored-by: brock 🤖⚡ <2791467+zeroXbrock@users.noreply.github.com>

Author: 0xl3on

CHANGELOG.md

@@ -5,6 +5,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > Note: this file did not exist until after `v0.5.6`.
 
+## [Unreleased]
+
+- move default data dir to `$XDG_STATE_HOME/contender` (`~/.local/state/contender`), with automatic migration from legacy `~/.contender` ([#460](https://github.com/flashbots/contender/issues/460))
+
 ## [0.9.0](https://github.com/flashbots/contender/releases/tag/v0.9.0) - 2026-03-17
 
 - added `--send-raw-tx-sync` flag to `spam` and `campaign` for `eth_sendRawTransactionSync` support ([#459](https://github.com/flashbots/contender/pull/459))

README.md

@@ -45,11 +45,11 @@ export RPC="http://host.docker.internal:8545"
 Run contender in a container with persistent state:
 
 ```bash
-docker run -it -v /tmp/.contender:/root/.contender \
+docker run -it -v /tmp/.contender:/root/.local/state/contender \
 contender spam --tps 20 -r $RPC transfers
 ```
 
-> `-v` maps `/tmp/.contender` on the host machine to `/root/.contender` in the container, which contains the DB; used for generating reports and saving contract deployments.
+> `-v` maps `/tmp/.contender` on the host machine to `/root/.local/state/contender` in the container, which contains the DB; used for generating reports and saving contract deployments.
 
 ## ⚙️ Prerequisites
 

crates/cli/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+- move default data dir from `~/.contender` to `$XDG_STATE_HOME/contender` (defaults to `~/.local/state/contender`), with automatic migration of existing data ([#460](https://github.com/flashbots/contender/issues/460))
+
 ## [0.9.0](https://github.com/flashbots/contender/releases/tag/v0.9.0) - 2026-03-17
 
 - added `--send-raw-tx-sync` flag to `spam` and `campaign` commands ([#459](https://github.com/flashbots/contender/pull/459))

crates/cli/src/commands/mod.rs

@@ -40,7 +40,7 @@ pub enum ReportFormat {
     about = "A flexible JSON-RPC spammer for EVM chains."
 )]
 pub struct ContenderCli {
-    /// Override the default data directory (~/.contender).
+    /// Override the default data directory (~/.local/state/contender).
     /// This directory stores the database and reports.
     #[arg(long, global = true, env = "CONTENDER_DATA_DIR", value_name = "PATH")]
     pub data_dir: Option<PathBuf>,

crates/cli/src/main.rs

@@ -47,7 +47,7 @@ async fn run() -> Result<(), CliError> {
     let db_path = db_file_in(&data_dir);
     init_reports_dir(&data_dir);
 
-    debug!("data directory: {data_dir:?}");
+    info!("data directory: {}", data_dir.display());
     debug!("opening DB at {db_path:?}");
 
     let db = SqliteDb::from_file(&db_path)?;

crates/cli/src/util/utils.rs

@@ -380,15 +380,43 @@ pub async fn find_insufficient_balances(
 
 /// Returns the path to the default data directory.
 /// The directory is created if it does not exist.
+///
+/// Uses `$XDG_STATE_HOME/contender` (defaulting to `~/.local/state/contender`).
+/// If the legacy `~/.contender` directory exists, it is migrated to the new location.
 pub fn default_data_dir() -> Result<PathBuf, UtilError> {
-    let home_dir = if cfg!(windows) {
-        std::env::var("USERPROFILE")?
-    } else {
-        std::env::var("HOME")?
+    let home_dir = PathBuf::from(std::env::var("HOME")?);
+    let xdg_state_home = std::env::var("XDG_STATE_HOME").ok();
+    resolve_default_data_dir(&home_dir, xdg_state_home.as_deref())
+}
+
+/// Core logic for resolving the default data directory. Extracted for testability.
+fn resolve_default_data_dir(
+    home_dir: &Path,
+    xdg_state_home: Option<&str>,
+) -> Result<PathBuf, UtilError> {
+    let state_home = match xdg_state_home {
+        Some(val) if !val.is_empty() => PathBuf::from(val),
+        _ => home_dir.join(".local").join("state"),
     };
-    let home_dir = PathBuf::from(&home_dir);
 
-    let dir = home_dir.join(".contender");
+    let dir = state_home.join("contender");
+
+    // migrate legacy ~/.contender to the new location
+    let legacy_dir = home_dir.join(".contender");
+    if legacy_dir.exists() && !dir.exists() {
+        if let Some(parent) = dir.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        if std::fs::rename(&legacy_dir, &dir).is_err() {
+            // rename can fail across filesystem boundaries; warn and continue
+            eprintln!(
+                "warning: failed to migrate legacy data dir '{}' to '{}'. \
+                 You can move it manually or set CONTENDER_DATA_DIR.",
+                legacy_dir.display(),
+                dir.display()
+            );
+        }
+    }
 
     // ensure directory exists
     std::fs::create_dir_all(&dir)?;
@@ -398,7 +426,7 @@ pub fn default_data_dir() -> Result<PathBuf, UtilError> {
 /// Resolves the data directory with the following priority:
 /// 1. CLI argument (if provided)
 /// 2. CONTENDER_DATA_DIR environment variable (if set)
-/// 3. Default: $HOME/.contender
+/// 3. Default: $XDG_STATE_HOME/contender (or ~/.local/state/contender)
 ///
 /// Creates the directory if it does not exist.
 pub fn resolve_data_dir(cli_arg: Option<std::path::PathBuf>) -> Result<PathBuf, UtilError> {
@@ -852,6 +880,77 @@ mod test {
         );
     }
 
+    #[test]
+    fn default_data_dir_uses_xdg_state_home() {
+        let tmp = tempfile::tempdir().unwrap();
+        let home = tmp.path().join("home");
+        let xdg = tmp.path().join("custom_state");
+        std::fs::create_dir_all(&home).unwrap();
+
+        let result = super::resolve_default_data_dir(&home, Some(xdg.to_str().unwrap())).unwrap();
+        assert_eq!(result, xdg.join("contender"));
+        assert!(result.exists());
+    }
+
+    #[test]
+    fn default_data_dir_falls_back_to_local_state() {
+        let tmp = tempfile::tempdir().unwrap();
+        let home = tmp.path().join("home");
+        std::fs::create_dir_all(&home).unwrap();
+
+        let result = super::resolve_default_data_dir(&home, None).unwrap();
+        assert_eq!(result, home.join(".local").join("state").join("contender"));
+        assert!(result.exists());
+    }
+
+    #[test]
+    fn default_data_dir_ignores_empty_xdg() {
+        let tmp = tempfile::tempdir().unwrap();
+        let home = tmp.path().join("home");
+        std::fs::create_dir_all(&home).unwrap();
+
+        let result = super::resolve_default_data_dir(&home, Some("")).unwrap();
+        assert_eq!(result, home.join(".local").join("state").join("contender"));
+    }
+
+    #[test]
+    fn default_data_dir_migrates_legacy_dir() {
+        let tmp = tempfile::tempdir().unwrap();
+        let home = tmp.path().join("home");
+        let legacy = home.join(".contender");
+        std::fs::create_dir_all(&legacy).unwrap();
+        std::fs::write(legacy.join("contender.db"), b"test data").unwrap();
+
+        let result = super::resolve_default_data_dir(&home, None).unwrap();
+        assert_eq!(result, home.join(".local").join("state").join("contender"));
+        // legacy dir should be gone, data should be at new location
+        assert!(!legacy.exists());
+        assert_eq!(
+            std::fs::read_to_string(result.join("contender.db")).unwrap(),
+            "test data"
+        );
+    }
+
+    #[test]
+    fn default_data_dir_skips_migration_if_new_dir_exists() {
+        let tmp = tempfile::tempdir().unwrap();
+        let home = tmp.path().join("home");
+        let legacy = home.join(".contender");
+        let new_dir = home.join(".local").join("state").join("contender");
+        std::fs::create_dir_all(&legacy).unwrap();
+        std::fs::create_dir_all(&new_dir).unwrap();
+        std::fs::write(legacy.join("old.db"), b"old").unwrap();
+        std::fs::write(new_dir.join("new.db"), b"new").unwrap();
+
+        let result = super::resolve_default_data_dir(&home, None).unwrap();
+        // both dirs should still exist, no overwrite
+        assert!(legacy.exists());
+        assert_eq!(
+            std::fs::read_to_string(result.join("new.db")).unwrap(),
+            "new"
+        );
+    }
+
     #[test]
     fn human_readable_gas_works() {
         assert_eq!(human_readable_gas(500), "500 gas");

docs/campaigns.md

@@ -97,7 +97,7 @@ Flags mirror `spam` where they make sense:
 - Campaign summary: `contender report --campaign [<campaign_id>]` (alias: `--campaign-id`)
   - If `<campaign_id>` is omitted, the latest campaign is used.
   - Generates per-run HTML for all runs in the campaign.
-  - Writes `campaign-<campaign_id>.html` and `campaign-<campaign_id>.json` under `~/.contender/reports/` with links, aggregate metrics, and per-stage/per-scenario rollups.
+  - Writes `campaign-<campaign_id>.html` and `campaign-<campaign_id>.json` under `~/.local/state/contender/reports/` with links, aggregate metrics, and per-stage/per-scenario rollups.
   - If you pass `--report` to `contender campaign ...`, contender will also generate a report for the run-id range at the end of the campaign.
   - If transaction logs are incomplete for any run (e.g., tracing/storage gaps), the campaign report will use stored run metadata for totals/durations and will display a notice; error counts may be under-reported in that case.
 - When a stage has multiple `[[spam.stage.mix]]` entries, do not combine it with `--override-senders`; using a single sender across mixes is rejected because it would cause nonce conflicts.