Merge pull request #2266 from plebhash/2026-08-03-fix-unbounded-future-jobs

`channels_sv2`: bound future-job storage on client channels

Author: plebhash

sv2/channels-sv2/src/client/extended.rs

@@ -4,7 +4,7 @@
 //! **Extended Channel** within a mining client.
 
 extern crate alloc;
-use super::HashMap;
+use super::{HashMap, MAX_FUTURE_JOBS};
 use crate::{
     bip141::try_strip_bip141,
     chain_tip::ChainTip,
@@ -17,7 +17,7 @@ use crate::{
     target::{bytes_to_hex, u256_to_block_hash},
     MAX_EXTRANONCE_LEN, VERSION_ROLLING_MASK,
 };
-use alloc::{format, string::String, vec, vec::Vec};
+use alloc::{collections::VecDeque, format, string::String, vec, vec::Vec};
 use binary_sv2::Sv2OptionOwned;
 use bitcoin::{
     absolute::LockTime,
@@ -57,8 +57,8 @@ pub type ExtendedJob = (NewExtendedMiningJobOwned, Vec<u8>, Target);
 /// - The channel's current target.
 /// - The channel's nominal hashrate.
 /// - Whether version rolling is supported (see [BIP 323](https://github.com/bitcoin/bips/blob/master/bip-0323.mediawiki)).
-/// - Future jobs (indexed by `job_id`) to be activated by a [`SetNewPrevHash`](SetNewPrevHashMp)
-///   message.
+/// - Future jobs (indexed by `job_id`, capped at [`MAX_FUTURE_JOBS`]) to be activated by a
+///   [`SetNewPrevHash`](SetNewPrevHashMp) message.
 /// - The currently active job.
 /// - Past jobs (previously active under the current chain tip, indexed by `job_id`).
 /// - Stale jobs (previously active and past jobs under the previous chain tip, indexed by
@@ -76,6 +76,9 @@ pub struct ExtendedChannel {
     version_rolling: bool,
     // future jobs are indexed with job_id (u32)
     future_jobs: HashMap<u32, ExtendedJob>,
+    // Future job IDs ordered by receipt, oldest at the front and newest at the back.
+    // Replaced IDs move to the back; overflow evicts from the front.
+    future_job_order: VecDeque<u32>,
     active_job: Option<ExtendedJob>,
     // past jobs are indexed with job_id (u32)
     past_jobs: HashMap<u32, ExtendedJob>,
@@ -105,6 +108,7 @@ impl ExtendedChannel {
             nominal_hashrate,
             version_rolling,
             future_jobs: HashMap::new(),
+            future_job_order: VecDeque::new(),
             active_job: None,
             past_jobs: HashMap::new(),
             stale_jobs: HashMap::new(),
@@ -221,6 +225,8 @@ impl ExtendedChannel {
     }
 
     /// Returns an iterator over all future jobs for this channel.
+    ///
+    /// At most [`MAX_FUTURE_JOBS`] jobs are kept (oldest evicted first).
     pub fn get_future_jobs(&self) -> impl Iterator<Item = (&u32, &ExtendedJob)> + '_ {
         self.future_jobs.iter()
     }
@@ -293,6 +299,8 @@ impl ExtendedChannel {
     ///
     /// - If [`NewExtendedMiningJob::min_ntime`](mining_sv2::NewExtendedMiningJob::min_ntime) is empty, the job is considered a future job and
     ///   added to the future jobs list (see [`get_future_jobs`](ExtendedChannel::get_future_jobs)).
+    ///   At most [`MAX_FUTURE_JOBS`] future jobs are kept: storing a new one beyond that limit
+    ///   evicts the oldest.
     /// - Otherwise, the job is activated and previous active job moves to the past jobs list.
     pub fn on_new_extended_mining_job(
         &mut self,
@@ -331,14 +339,25 @@ impl ExtendedChannel {
                 ));
             }
             None => {
+                let job_id = new_extended_mining_job.job_id;
                 self.future_jobs.insert(
-                    new_extended_mining_job.job_id,
+                    job_id,
                     (
                         new_extended_mining_job,
                         self.extranonce_prefix.as_bytes().to_vec(),
                         self.target,
                     ),
                 );
+
+                // a replaced job_id moves to the back of the eviction order
+                self.future_job_order.retain(|id| *id != job_id);
+                self.future_job_order.push_back(job_id);
+
+                if self.future_jobs.len() > MAX_FUTURE_JOBS {
+                    if let Some(evicted_job_id) = self.future_job_order.pop_front() {
+                        self.future_jobs.remove(&evicted_job_id);
+                    }
+                }
             }
         }
 
@@ -467,6 +486,7 @@ impl ExtendedChannel {
 
         // all other future jobs are now useless
         self.future_jobs.clear();
+        self.future_job_order.clear();
 
         // mark all past jobs as stale, so that shares are not propagated
         self.stale_jobs = self.past_jobs.clone();
@@ -505,6 +525,7 @@ impl ExtendedChannel {
 
         // all other future jobs are now useless
         self.future_jobs.clear();
+        self.future_job_order.clear();
 
         // mark all past jobs as stale, so that shares are not propagated
         self.stale_jobs = self.past_jobs.clone();
@@ -709,6 +730,7 @@ mod tests {
         client::{
             extended::ExtendedChannel,
             share_accounting::{ShareValidationError, ShareValidationResult},
+            MAX_FUTURE_JOBS,
         },
         extranonce_manager::ExtranoncePrefix,
     };
@@ -807,6 +829,145 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_future_jobs_are_bounded() {
+        let channel_id = 1;
+        let extranonce_prefix = [
+            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
+            0, 0, 0, 0, 0, 0, 1,
+        ]
+        .to_vec();
+
+        let mut channel = ExtendedChannel::new(
+            channel_id,
+            "user_identity".to_string(),
+            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
+            Target::from_le_bytes([0xff; 32]),
+            1.0,
+            true,
+            4u16,
+        );
+
+        let future_job = NewExtendedMiningJob {
+            channel_id,
+            job_id: 0,
+            min_ntime: Sv2Option::new(None),
+            version: 536870912,
+            version_rolling_allowed: true,
+            coinbase_tx_prefix: vec![
+                2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+                0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255, 34, 82, 0,
+            ]
+            .try_into()
+            .unwrap(),
+            coinbase_tx_suffix: vec![
+                255, 255, 255, 255, 2, 0, 242, 5, 42, 1, 0, 0, 0, 22, 0, 20, 235, 225, 183, 220,
+                194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194, 8, 252, 0, 0, 0,
+                0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209, 222,
+                253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180, 139,
+                235, 216, 54, 151, 78, 140, 249, 0, 0, 0, 0,
+            ]
+            .try_into()
+            .unwrap(),
+            merkle_path: vec![].try_into().unwrap(),
+        };
+
+        let flood_size = 10_000u32;
+        for job_id in 0..flood_size {
+            let mut job = future_job.clone();
+            job.job_id = job_id;
+            channel.on_new_extended_mining_job(job).unwrap();
+        }
+
+        assert_eq!(channel.get_future_jobs_count(), MAX_FUTURE_JOBS);
+
+        for job_id in 0..flood_size - MAX_FUTURE_JOBS as u32 {
+            assert!(channel.get_future_job(job_id).is_none());
+        }
+        for job_id in flood_size - MAX_FUTURE_JOBS as u32..flood_size {
+            assert!(channel.get_future_job(job_id).is_some());
+        }
+    }
+
+    #[test]
+    fn test_replaced_future_job_moves_to_back_of_eviction_order() {
+        let channel_id = 1;
+        let extranonce_prefix = [
+            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
+            0, 0, 0, 0, 0, 0, 1,
+        ]
+        .to_vec();
+
+        let mut channel = ExtendedChannel::new(
+            channel_id,
+            "user_identity".to_string(),
+            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
+            Target::from_le_bytes([0xff; 32]),
+            1.0,
+            true,
+            4u16,
+        );
+
+        let future_job = NewExtendedMiningJob {
+            channel_id,
+            job_id: 0,
+            min_ntime: Sv2Option::new(None),
+            version: 536870912,
+            version_rolling_allowed: true,
+            coinbase_tx_prefix: vec![
+                2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+                0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255, 34, 82, 0,
+            ]
+            .try_into()
+            .unwrap(),
+            coinbase_tx_suffix: vec![
+                255, 255, 255, 255, 2, 0, 242, 5, 42, 1, 0, 0, 0, 22, 0, 20, 235, 225, 183, 220,
+                194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194, 8, 252, 0, 0, 0,
+                0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209, 222,
+                253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180, 139,
+                235, 216, 54, 151, 78, 140, 249, 0, 0, 0, 0,
+            ]
+            .try_into()
+            .unwrap(),
+            merkle_path: vec![].try_into().unwrap(),
+        };
+
+        // fill the store with MAX_FUTURE_JOBS distinct job_ids
+        for job_id in 0..MAX_FUTURE_JOBS as u32 {
+            let mut job = future_job.clone();
+            job.job_id = job_id;
+            channel.on_new_extended_mining_job(job).unwrap();
+        }
+
+        // re-send job_id 0: it should move to the back of the eviction order
+        channel
+            .on_new_extended_mining_job(future_job.clone())
+            .unwrap();
+
+        // one more distinct job_id: job_id 1 is now the oldest and gets evicted
+        let mut job = future_job.clone();
+        job.job_id = MAX_FUTURE_JOBS as u32;
+        channel.on_new_extended_mining_job(job).unwrap();
+
+        assert_eq!(channel.get_future_jobs_count(), MAX_FUTURE_JOBS);
+        assert!(channel.get_future_job(1).is_none());
+        assert!(channel.get_future_job(0).is_some());
+
+        // the replaced job_id can still be activated
+        let set_new_prev_hash = SetNewPrevHashMp {
+            channel_id,
+            job_id: 0,
+            prev_hash: [
+                200, 53, 253, 129, 214, 31, 43, 84, 179, 58, 58, 76, 128, 213, 24, 53, 38, 144,
+                205, 88, 172, 20, 251, 22, 217, 141, 21, 221, 21, 0, 0, 0,
+            ]
+            .into(),
+            nbits: 503543726,
+            min_ntime: 1746839905,
+        };
+        channel.on_set_new_prev_hash(set_new_prev_hash).unwrap();
+    }
+
     #[test]
     fn test_past_jobs_flow() {
         let channel_id = 1;