Merge pull request #6 from disassembler/sl/queue-solution-submission

Feature: Asynchronous Solution Submission Queue

Author: disassembler

Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "shadow-harvester" # 🚨 NEW: The project and library name
+name = "shadow-harvester"
 version = "0.1.0"
 edition = "2024"
 license = "MIT Or Apache-2.0"

src/api.rs

@@ -22,7 +22,6 @@ pub fn fetch_tandc(client: &blocking::Client, api_url: &str) -> Result<TandCResp
     response.json()
 }
 
-// NEW FUNCTION: Parses the comma-separated CLI challenge string
 pub fn parse_cli_challenge_string(challenge_str: &str) -> Result<CliChallengeData, String> {
     let parts: Vec<&str> = challenge_str.split(',').collect();
 
@@ -44,7 +43,6 @@ pub fn parse_cli_challenge_string(challenge_str: &str) -> Result<CliChallengeDat
 
 
 /// Performs the POST /register call using key/signature arguments.
-// RENAMED from register_address_mock
 pub fn register_address(
     client: &blocking::Client,
     api_url: &str,
@@ -139,7 +137,6 @@ pub fn submit_solution(
 }
 
 /// Performs the POST /donate_to call.
-// RENAMED from donate_to_mock
 pub fn donate_to(
     client: &blocking::Client,
     api_url: &str,
@@ -187,7 +184,6 @@ pub fn donate_to(
 }
 
 /// Fetches the raw Challenge Response object from the API.
-// NEW FUNCTION
 pub fn fetch_challenge_status(client: &blocking::Client, api_url: &str) -> Result<ChallengeResponse, String> {
     let url = format!("{}/challenge", api_url);
 
@@ -202,7 +198,6 @@ pub fn fetch_challenge_status(client: &blocking::Client, api_url: &str) -> Resul
 }
 
 /// Fetches and validates the active challenge parameters, returning data only if active.
-// RENAMED from fetch_challenge
 pub fn get_active_challenge_data(client: &blocking::Client, api_url: &str) -> Result<ChallengeData, String> {
     let challenge_response = fetch_challenge_status(client, api_url)?;
 

src/cli.rs

@@ -28,7 +28,7 @@ pub struct Cli {
     #[arg(long)]
     pub payment_key: Option<String>,
 
-    /// NEW: Automatically generate a new ephemeral key pair for every mining cycle.
+    /// Automatically generate a new ephemeral key pair for every mining cycle.
     #[arg(long)]
     pub ephemeral_key: bool,
 

src/data_types.rs

@@ -128,7 +128,7 @@ pub struct CliChallengeData {
 // CORE APPLICATION STRUCTS
 // ===============================================
 
-// NEW STRUCT: Holds the common, validated state for the mining loops.
+// Holds the common, validated state for the mining loops.
 #[derive(Debug)]
 pub struct MiningContext<'a> {
     pub client: blocking::Client,
@@ -142,10 +142,20 @@ pub struct MiningContext<'a> {
 }
 
 
-// NEW: Define a result type for the mining cycle
+// Holds the data needed to submit a solution later.
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct PendingSolution {
+    pub address: String,
+    pub challenge_id: String,
+    pub nonce: String,
+    pub donation_address: Option<String>, // RE-ADDED this field
+}
+
+// Define a result type for the mining cycle
 #[derive(Debug, PartialEq)]
 pub enum MiningResult {
-    FoundAndSubmitted((serde_json::Value, Option<String>)),
+    FoundAndQueued, // Solution found and saved to local queue
+    #[allow(dead_code)] // The submitter thread produces this result conceptually when processing a queue item, but the miner never constructs it.
     AlreadySolved, // The solution was successfully submitted by someone else
     MiningFailed,  // General mining or submission error (e.g., hash not found, transient API error)
 }
@@ -154,6 +164,8 @@ pub enum MiningResult {
 pub const FILE_NAME_CHALLENGE: &str = "challenge.json";
 pub const FILE_NAME_RECEIPT: &str = "receipt.json";
 pub const FILE_NAME_DONATION: &str = "donation.txt";
+// Removed: FILE_NAME_PENDING_SOLUTION is unused, path is derived from QUEUE_BASE_DIR
+pub const FILE_NAME_FOUND_SOLUTION: &str = "found.json"; // (Crash recovery file)
 
 
 #[derive(Debug, Clone, Copy)]
@@ -224,31 +236,98 @@ impl<'a> DataDir<'a> {
         Ok(())
     }
 
-    pub fn save_receipt(&self, base_dir: &str, challenge_id: &str, receipt: &serde_json::Value, donation: &Option<String>) -> Result<(), String> {
+    // Only saves the receipt, donation logic removed
+    pub fn save_receipt(&self, base_dir: &str, challenge_id: &str, receipt: &serde_json::Value) -> Result<(), String> {
         let mut path = self.receipt_dir(base_dir, challenge_id)?;
         path.push(FILE_NAME_RECEIPT);
 
         let receipt_json = receipt.to_string();
 
-        // FIX: Use explicit file handling and sync to guarantee persistence.
         let mut file = std::fs::File::create(&path)
             .map_err(|e| format!("Could not create {}: {}", FILE_NAME_RECEIPT, e))?;
 
         file.write_all(receipt_json.as_bytes())
             .map_err(|e| format!("Could not write to {}: {}", FILE_NAME_RECEIPT, e))?;
 
-        // CRITICAL: Force the OS to write the data to disk now.
         file.sync_all()
             .map_err(|e| format!("Could not sync {}: {}", FILE_NAME_RECEIPT, e))?;
 
-        if let Some(donation_id) = donation {
-            path.pop();
-            path.push(FILE_NAME_DONATION);
+        // Donation file logic is intentionally removed here.
 
-            std::fs::write(&path, donation_id.as_bytes())
-                .map_err(|e| format!("Could not write {}: {}", FILE_NAME_DONATION, e))?;
-        }
+        Ok(())
+    }
+
+    // Saves a PendingSolution to the queue directory
+    pub fn save_pending_solution(&self, base_dir: &str, solution: &PendingSolution) -> Result<(), String> {
+        let mut path = PathBuf::from(base_dir);
+        path.push("pending_submissions"); // Dedicated directory for the queue
+        std::fs::create_dir_all(&path)
+            .map_err(|e| format!("Could not create pending_submissions directory: {}", e))?;
+
+        // Use a unique file name based on challenge, address, and nonce
+        path.push(format!("{}_{}_{}.json", solution.address, solution.challenge_id, solution.nonce));
+
+        let solution_json = serde_json::to_string(solution)
+            .map_err(|e| format!("Could not serialize pending solution: {}", e))?;
+
+        std::fs::write(&path, solution_json)
+            .map_err(|e| format!("Could not write pending solution file: {}", e))?;
 
         Ok(())
     }
+
+    // Saves the temporary file indicating a solution was found but not queued/submitted
+    pub fn save_found_solution(&self, base_dir: &str, challenge_id: &str, solution: &PendingSolution) -> Result<(), String> {
+        let mut path = self.receipt_dir(base_dir, challenge_id)?; // Use receipt dir for local persistence
+        path.push(FILE_NAME_FOUND_SOLUTION);
+
+        let solution_json = serde_json::to_string(solution)
+            .map_err(|e| format!("Could not serialize found solution: {}", e))?;
+
+        // Use explicit file handling to guarantee persistence before returning success
+        let mut file = std::fs::File::create(&path)
+            .map_err(|e| format!("Could not create {}: {}", FILE_NAME_FOUND_SOLUTION, e))?;
+
+        file.write_all(solution_json.as_bytes())
+            .map_err(|e| format!("Could not write to {}: {}", FILE_NAME_FOUND_SOLUTION, e))?;
+
+        file.sync_all()
+            .map_err(|e| format!("Could not sync {}: {}", FILE_NAME_FOUND_SOLUTION, e))?;
+
+        Ok(())
+    }
+
+    // Removes the temporary file
+    pub fn delete_found_solution(&self, base_dir: &str, challenge_id: &str) -> Result<(), String> {
+        let mut path = self.receipt_dir(base_dir, challenge_id)?;
+        path.push(FILE_NAME_FOUND_SOLUTION);
+        if path.exists() {
+            std::fs::remove_file(&path)
+                .map_err(|e| format!("Failed to delete {}: {}", FILE_NAME_FOUND_SOLUTION, e))?;
+        }
+        Ok(())
+    }
+}
+
+// Checks if an address/challenge has a pending submission file in the queue dir
+pub fn is_solution_pending_in_queue(base_dir: &str, address: &str, challenge_id: &str) -> Result<bool, String> {
+    use std::path::PathBuf;
+
+    let mut path = PathBuf::from(base_dir);
+    path.push("pending_submissions");
+
+    // Scan for any file that matches the address and challenge ID prefix
+    if let Ok(entries) = std::fs::read_dir(&path) {
+        for entry in entries.filter_map(|e| e.ok()) {
+            if let Some(filename) = entry.file_name().to_str() {
+                // Check if the filename starts with the required prefix and is a JSON file
+                // The filename format is: address_challenge_id_nonce.json
+                if filename.starts_with(&format!("{}_{}_", address, challenge_id)) && filename.ends_with(".json") {
+                    return Ok(true);
+                }
+            }
+        }
+    }
+    // If the directory doesn't exist or no matching file is found
+    Ok(false)
 }

src/lib.rs

@@ -587,8 +587,6 @@ pub fn scavenge(
             // Set start_nonce = thread_id
             let start_nonce = thread_id;
 
-            println!("Starting thread {} with initial nonce: {:016x} and step size: {}", thread_id, start_nonce, step_size);
-
             s.spawn(move || {
                 spin(params, sender, stop_signal, start_nonce, step_size)
             });

src/main.rs

@@ -1,6 +1,7 @@
 // src/main.rs - Final Minimal Version
 
 use clap::Parser;
+use std::thread; // ADDED
 
 // Declare modules
 mod api;
@@ -11,6 +12,7 @@ mod cardano;
 mod data_types;
 mod utils; // The helpers module
 mod mining;
+mod submitter;
 
 use mining::{run_persistent_key_mining, run_mnemonic_sequential_mining, run_ephemeral_key_mining};
 use utils::{setup_app, print_mining_setup}; // Importing refactored helpers
@@ -27,6 +29,27 @@ fn run_app(cli: Cli) -> Result<(), String> {
         Err(e) => return Err(e),
     };
 
+    // --- Start Background Submitter Thread ---
+    // Clone client, API URL, and data_dir for the background thread
+    let submitter_handle = if let Some(base_dir) = context.data_dir {
+        let client_clone = context.client.clone();
+        let api_url_clone = context.api_url.clone();
+        let data_dir_clone = base_dir.to_string();
+
+        println!("📦 Starting background submitter thread...");
+        let handle = thread::spawn(move || {
+            match submitter::run_submitter_thread(client_clone, api_url_clone, data_dir_clone) {
+                Ok(_) => {},
+                Err(e) => eprintln!("FATAL SUBMITTER ERROR: {}", e),
+            }
+        });
+        Some(handle)
+    } else {
+        println!("⚠️ No --data-dir specified. Submissions will be synchronous (blocking) and lost on API error.");
+        None
+    };
+    // ---------------------------------------------
+
     // --- Pre-extract mnemonic logic ---
     let mnemonic: Option<String> = if let Some(mnemonic) = cli.mnemonic.clone() {
         Some(mnemonic)
@@ -56,7 +79,7 @@ fn run_app(cli: Cli) -> Result<(), String> {
     }
 
     // 2. Determine Operation Mode and Start Mining
-    if let Some(skey_hex) = cli.payment_key.as_ref() {
+    let result = if let Some(skey_hex) = cli.payment_key.as_ref() {
         // Mode A: Persistent Key Mining
         run_persistent_key_mining(context, skey_hex)
     }
@@ -70,7 +93,12 @@ fn run_app(cli: Cli) -> Result<(), String> {
     } else {
         // This should be unreachable due to the validation in utils::setup_app
         Ok(())
-    }
+    };
+
+    // NOTE: In a production app, you would join the submitter thread here.
+    // if let Some(handle) = submitter_handle { handle.join().unwrap(); }
+
+    result
 }
 
 fn main() {