From 01bf0ce53af66f7a1a5829827699148df52dd0cd Mon Sep 17 00:00:00 2001 From: Amartya Singh Date: Thu, 5 Nov 2026 17:06:42 +0530 Subject: [PATCH 1/4] feat(sv1_api): add VersionRollingParams::negotiated_mask BIP 310 only lets a miner roll the version bits it asked for and the server granted, and neither side may roll bits outside VERSION_ROLLING_MASK. negotiated_mask computes that mask from a grant and the requested mask, so the server and client paths can share it. --- sv1/src/methods/server_to_client.rs | 38 +++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/sv1/src/methods/server_to_client.rs b/sv1/src/methods/server_to_client.rs index 0f0f04b284..b2f0fcbaf4 100644 --- a/sv1/src/methods/server_to_client.rs +++ b/sv1/src/methods/server_to_client.rs @@ -800,6 +800,20 @@ impl VersionRollingParams { version_rolling_min_bit_count, } } + + /// Returns the mask both peers act on once this grant answers a request for `requested`. + /// + /// BIP 310 only lets the miner roll bits it asked for and the server granted, and neither + /// side may roll bits outside [`VERSION_ROLLING_MASK`]. Returns `None` when version rolling + /// was not requested or was refused. + pub fn negotiated_mask(&self, requested: Option<&HexU32Be>) -> Option { + match requested { + Some(requested) if self.version_rolling => Some(HexU32Be( + requested.0 & self.version_rolling_mask.0 & VERSION_ROLLING_MASK, + )), + _ => None, + } + } } impl From for serde_json::Map { @@ -817,3 +831,27 @@ impl From for serde_json::Map { params } } + +#[test] +fn negotiated_mask_keeps_only_requested_and_general_purpose_bits() { + let granted = VersionRollingParams { + version_rolling: true, + version_rolling_mask: HexU32Be(0xffffffff), + version_rolling_min_bit_count: HexU32Be(0), + }; + assert_eq!( + granted.negotiated_mask(Some(&HexU32Be(0xffffffff))), + Some(HexU32Be(VERSION_ROLLING_MASK)) + ); + assert_eq!( + granted.negotiated_mask(Some(&HexU32Be(0x00ff0000))), + Some(HexU32Be(0x00ff0000)) + ); + assert_eq!(granted.negotiated_mask(None), None); + + let refused = VersionRollingParams { + version_rolling: false, + ..granted + }; + assert_eq!(refused.negotiated_mask(Some(&HexU32Be(0xffffffff))), None); +} From 7ccd6da8dd0c6551be4aadc82419a0e05b0bba73 Mon Sep 17 00:00:00 2001 From: Amartya Singh Date: Thu, 5 Nov 2026 17:06:42 +0530 Subject: [PATCH 2/4] fix(sv1_api): check submits against the negotiated version-rolling mask IsServer stored the mask from the mining.configure request before handle_configure decided what to grant, and mining.submit version bits were then checked against it, so a miner asking for ffffffff could roll reserved bits. Store only the negotiated mask once handle_configure returns, and narrow the grant in the response to that same mask. A session that did not request version rolling, or had it refused, keeps no mask, so submits without version bits stay valid. The example server now reads the requested mask from the request instead of the session state. --- sv1/examples/client_and_server.rs | 15 ++- sv1/src/lib.rs | 154 ++++++++++++++++++++++++++++-- 2 files changed, 152 insertions(+), 17 deletions(-) diff --git a/sv1/examples/client_and_server.rs b/sv1/examples/client_and_server.rs index 0cff7df98d..dcf0172b9a 100644 --- a/sv1/examples/client_and_server.rs +++ b/sv1/examples/client_and_server.rs @@ -200,15 +200,14 @@ impl IsServer for Server { fn handle_configure( &mut self, _client_id: Option, - _request: &client_to_server::Configure, + request: &client_to_server::Configure, ) -> Result<(Option, Option), Error> { - self.version_rolling_mask - .get_or_insert_with(new_version_rolling_mask); - self.version_rolling_min_bit - .get_or_insert_with(new_version_rolling_min); - - let mask = self.version_rolling_mask.as_ref().unwrap().clone(); - let min_bit = self.version_rolling_min_bit.as_ref().unwrap().clone(); + let mask = request + .version_rolling_mask() + .unwrap_or_else(new_version_rolling_mask); + let min_bit = request + .version_rolling_min_bit_count() + .unwrap_or_else(new_version_rolling_min); Ok(( Some(server_to_client::VersionRollingParams::new(mask, min_bit)), diff --git a/sv1/src/lib.rs b/sv1/src/lib.rs index 26dcac8a05..4985569ec3 100644 --- a/sv1/src/lib.rs +++ b/sv1/src/lib.rs @@ -52,7 +52,7 @@ use tracing::debug; use error::Error; pub use json_rpc::Message; pub use methods::{client_to_server, server_to_client, Method, MethodError, ParsingMethodError}; -use utils::{Extranonce, HexU32Be}; +use utils::{Extranonce, HexU32Be, VERSION_ROLLING_MASK}; /// json_rpc Response are not handled because stratum v1 does not have any request from a server to /// a client @@ -132,12 +132,22 @@ pub trait IsServer { } methods::Client2Server::Configure(configure) => { debug!("{:?}", configure); - self.set_version_rolling_mask(client_id, configure.version_rolling_mask())?; - self.set_version_rolling_min_bit( - client_id, - configure.version_rolling_min_bit_count(), - )?; - let (version_rolling, min_diff) = self.handle_configure(client_id, &configure)?; + let requested_mask = configure.version_rolling_mask(); + let (mut version_rolling, min_diff) = + self.handle_configure(client_id, &configure)?; + let negotiated_mask = version_rolling.as_mut().and_then(|params| { + let mask = params.negotiated_mask(requested_mask.as_ref()); + if params.version_rolling { + // Grant exactly the bits that submits are checked against below. + params.version_rolling_mask = mask.clone().unwrap_or(HexU32Be(0)); + } + mask + }); + let min_bit = negotiated_mask + .as_ref() + .and(configure.version_rolling_min_bit_count()); + self.set_version_rolling_mask(client_id, negotiated_mask)?; + self.set_version_rolling_min_bit(client_id, min_bit)?; Ok(Some(configure.respond(version_rolling, min_diff))) } methods::Client2Server::ExtranonceSubscribe(subscribe) => { @@ -189,6 +199,13 @@ pub trait IsServer { /// This message (JSON RPC Request) SHOULD be the first message sent by the miner after the /// connection with the server is established. + /// + /// The requested mask is available through `request`; the session mask is only set once this + /// returns. A version-rolling grant is narrowed to the bits the miner requested and to + /// [`utils::VERSION_ROLLING_MASK`] (see + /// [`server_to_client::VersionRollingParams::negotiated_mask`]); that narrowed mask is sent + /// in the response, stored with [`Self::set_version_rolling_mask`], and used to check the + /// version bits of every later `mining.submit`. fn handle_configure( &mut self, client_id: Option, @@ -736,6 +753,7 @@ mod tests { extranonce2_size: usize, version_rolling_mask: Option, version_rolling_min_bit: Option, + version_rolling_grant: Option, } impl TestServer { @@ -747,6 +765,7 @@ mod tests { extranonce2_size, version_rolling_mask: None, version_rolling_min_bit: None, + version_rolling_grant: None, } } } @@ -759,7 +778,7 @@ mod tests { _client_id: Option, _request: &client_to_server::Configure, ) -> Result<(Option, Option), Error> { - Ok((None, None)) + Ok((self.version_rolling_grant.clone(), None)) } fn handle_subscribe( @@ -844,7 +863,7 @@ mod tests { &self, _client_id: Option, ) -> Result, Error> { - Ok(None) + Ok(self.version_rolling_mask.clone()) } fn set_version_rolling_mask( @@ -1056,4 +1075,121 @@ mod tests { let msg: Message = serde_json::from_value(raw).unwrap(); assert!(Method::try_from(msg).is_err()); } + + fn configure_request(params: serde_json::Value) -> Message { + serde_json::from_value(serde_json::json!({ + "id": 1, + "method": "mining.configure", + "params": params, + })) + .unwrap() + } + + fn version_rolling_request(mask: &str) -> Message { + configure_request(serde_json::json!([ + ["version-rolling"], + {"version-rolling.mask": mask}, + ])) + } + + /// A server whose `handle_configure` grants every version bit, reserved ones included. + fn server_granting_every_bit() -> TestServer { + let mut server = TestServer::new(vec![0; 4].try_into().unwrap(), 4); + server.version_rolling_grant = Some(server_to_client::VersionRollingParams { + version_rolling: true, + version_rolling_mask: HexU32Be(0xffffffff), + version_rolling_min_bit_count: HexU32Be(0), + }); + server.authorized_users.insert("worker".to_string()); + server + } + + fn submit(server: &mut TestServer, version_bits: Option) -> json_rpc::Response { + let request = client_to_server::Submit { + user_name: "worker".to_string(), + job_id: "job".to_string(), + extra_nonce2: vec![0; 4].try_into().unwrap(), + time: HexU32Be(0), + nonce: HexU32Be(0), + version_bits: version_bits.map(HexU32Be), + id: 2, + }; + server + .handle_message(Some(7), request.into()) + .unwrap() + .expect("mining.submit must receive a response") + } + + #[test] + fn configure_never_grants_reserved_version_bits() { + let mut server = server_granting_every_bit(); + + let response = server + .handle_message(Some(7), version_rolling_request("ffffffff")) + .unwrap() + .expect("mining.configure must receive a response"); + + assert_eq!(response.result["version-rolling.mask"], "1fffffe0"); + assert_eq!( + server.version_rolling_mask, + Some(HexU32Be(VERSION_ROLLING_MASK)) + ); + assert!(submit(&mut server, Some(0x1fffe000)).error.is_none()); + assert_eq!( + submit(&mut server, Some(0x20000000)).error.unwrap().code, + 20 + ); + } + + #[test] + fn configure_only_grants_requested_version_bits() { + let mut server = server_granting_every_bit(); + + let response = server + .handle_message(Some(7), version_rolling_request("00ff0000")) + .unwrap() + .expect("mining.configure must receive a response"); + + assert_eq!(response.result["version-rolling.mask"], "00ff0000"); + assert_eq!(server.version_rolling_mask, Some(HexU32Be(0x00ff0000))); + assert!(submit(&mut server, Some(0x00010000)).error.is_none()); + assert_eq!( + submit(&mut server, Some(0x01000000)).error.unwrap().code, + 20 + ); + } + + #[test] + fn configure_without_version_rolling_keeps_submits_without_version_bits() { + let mut server = server_granting_every_bit(); + + server + .handle_message(Some(7), configure_request(serde_json::json!([[], {}]))) + .unwrap(); + + assert_eq!(server.version_rolling_mask, None); + assert_eq!(server.version_rolling_min_bit, None); + assert!(submit(&mut server, None).error.is_none()); + assert_eq!( + submit(&mut server, Some(0x00002000)).error.unwrap().code, + 20 + ); + } + + #[test] + fn refused_version_rolling_is_not_stored() { + let mut server = server_granting_every_bit(); + server + .version_rolling_grant + .as_mut() + .unwrap() + .version_rolling = false; + + server + .handle_message(Some(7), version_rolling_request("1fffffe0")) + .unwrap(); + + assert_eq!(server.version_rolling_mask, None); + assert_eq!(server.version_rolling_min_bit, None); + } } From 9c27ff61b35be36c45600b55ca2652dbd9cdec09 Mon Sep 17 00:00:00 2001 From: Amartya Singh Date: Thu, 5 Nov 2026 17:06:42 +0530 Subject: [PATCH 3/4] fix(sv1_api): only roll the version bits the client requested The mining.configure response handler stored the pool's mask as is, so a pool could hand the client reserved bits or bits it never asked for. Narrow the grant to the requested mask and to VERSION_ROLLING_MASK, and keep no mask when version rolling was not requested. --- sv1/src/lib.rs | 253 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 251 insertions(+), 2 deletions(-) diff --git a/sv1/src/lib.rs b/sv1/src/lib.rs index 4985569ec3..437b0c5ffa 100644 --- a/sv1/src/lib.rs +++ b/sv1/src/lib.rs @@ -455,8 +455,24 @@ pub trait IsClient { match response { methods::Server2ClientResponse::Configure(mut configure) => { self.handle_configure(server_id, &mut configure)?; - self.set_version_rolling_mask(server_id, configure.version_rolling_mask())?; - self.set_version_rolling_min_bit(server_id, configure.version_rolling_min_bit())?; + // Rebuild the mask that `Self::configure` requested from the session state; only + // the part of it the pool granted may be rolled. + let requested_mask = match ( + self.version_rolling_mask(server_id)?, + self.version_rolling_min_bit(server_id)?, + ) { + (None, None) => None, + (mask, _) => Some(mask.unwrap_or(HexU32Be(VERSION_ROLLING_MASK))), + }; + let negotiated_mask = configure + .version_rolling + .as_ref() + .and_then(|params| params.negotiated_mask(requested_mask.as_ref())); + let min_bit = negotiated_mask + .as_ref() + .and(configure.version_rolling_min_bit()); + self.set_version_rolling_mask(server_id, negotiated_mask)?; + self.set_version_rolling_min_bit(server_id, min_bit)?; self.set_status(server_id, ClientStatus::Configured)?; //in sv1 the mining.configure message should be the first message to come in before @@ -1192,4 +1208,237 @@ mod tests { assert_eq!(server.version_rolling_mask, None); assert_eq!(server.version_rolling_min_bit, None); } + + // A minimal implementation of IsClient trait for testing + struct TestClient { + status: ClientStatus, + version_rolling_mask: Option, + version_rolling_min_bit: Option, + } + + impl TestClient { + fn requesting(mask: Option) -> Self { + Self { + status: ClientStatus::Init, + version_rolling_mask: mask.map(HexU32Be), + version_rolling_min_bit: None, + } + } + + /// Feeds the client the pool's answer to its `mining.configure`. + fn receive_configure_response(&mut self, result: serde_json::Value) { + let response = serde_json::from_value(serde_json::json!({ + "id": 1, + "error": null, + "result": result, + })) + .unwrap(); + self.handle_message(None, response).unwrap(); + } + } + + impl IsClient for TestClient { + type Error = Error; + + fn handle_error_message( + &mut self, + _server_id: Option, + _message: Message, + ) -> Result, Error> { + Ok(None) + } + + fn id_is_authorize( + &mut self, + _server_id: Option, + _id: &u64, + ) -> Result, Error> { + Ok(None) + } + + fn id_is_submit(&mut self, _server_id: Option, _id: &u64) -> Result { + Ok(false) + } + + fn handle_notify( + &mut self, + _server_id: Option, + _notify: server_to_client::Notify, + ) -> Result<(), Error> { + Ok(()) + } + + fn handle_configure( + &mut self, + _server_id: Option, + _conf: &mut server_to_client::Configure, + ) -> Result<(), Error> { + Ok(()) + } + + fn handle_set_difficulty( + &mut self, + _server_id: Option, + _m: &mut server_to_client::SetDifficulty, + ) -> Result<(), Error> { + Ok(()) + } + + fn handle_set_extranonce( + &mut self, + _server_id: Option, + _m: &mut server_to_client::SetExtranonce, + ) -> Result<(), Error> { + Ok(()) + } + + fn handle_set_version_mask( + &mut self, + _server_id: Option, + _m: &mut server_to_client::SetVersionMask, + ) -> Result<(), Error> { + Ok(()) + } + + fn handle_subscribe( + &mut self, + _server_id: Option, + _subscribe: &server_to_client::Subscribe, + ) -> Result<(), Error> { + Ok(()) + } + + fn set_extranonce1( + &mut self, + _server_id: Option, + _extranonce1: Extranonce, + ) -> Result<(), Error> { + Ok(()) + } + + fn extranonce1(&self, _server_id: Option) -> Result { + Ok(vec![0; 4].try_into().unwrap()) + } + + fn set_extranonce2_size( + &mut self, + _server_id: Option, + _extra_nonce2_size: usize, + ) -> Result<(), Error> { + Ok(()) + } + + fn extranonce2_size(&self, _server_id: Option) -> Result { + Ok(4) + } + + fn version_rolling_mask( + &self, + _server_id: Option, + ) -> Result, Error> { + Ok(self.version_rolling_mask.clone()) + } + + fn set_version_rolling_mask( + &mut self, + _server_id: Option, + mask: Option, + ) -> Result<(), Error> { + self.version_rolling_mask = mask; + Ok(()) + } + + fn set_version_rolling_min_bit( + &mut self, + _server_id: Option, + min: Option, + ) -> Result<(), Error> { + self.version_rolling_min_bit = min; + Ok(()) + } + + fn version_rolling_min_bit( + &mut self, + _server_id: Option, + ) -> Result, Error> { + Ok(self.version_rolling_min_bit.clone()) + } + + fn set_status( + &mut self, + _server_id: Option, + status: ClientStatus, + ) -> Result<(), Error> { + self.status = status; + Ok(()) + } + + fn signature(&self, _server_id: Option) -> Result { + Ok("test".to_string()) + } + + fn status(&self, _server_id: Option) -> Result { + Ok(self.status) + } + + fn last_notify( + &self, + _server_id: Option, + ) -> Result, Error> { + Ok(None) + } + + fn is_authorized(&self, _server_id: Option, _name: &String) -> Result { + Ok(false) + } + + fn authorize_user_name( + &mut self, + _server_id: Option, + _name: String, + ) -> Result<(), Error> { + Ok(()) + } + } + + #[test] + fn client_never_rolls_reserved_version_bits() { + let mut client = TestClient::requesting(Some(0xffffffff)); + + client.receive_configure_response(serde_json::json!({ + "version-rolling": true, + "version-rolling.mask": "ffffffff", + })); + + assert_eq!( + client.version_rolling_mask, + Some(HexU32Be(VERSION_ROLLING_MASK)) + ); + assert_eq!(client.status, ClientStatus::Configured); + } + + #[test] + fn client_only_rolls_requested_version_bits() { + let mut client = TestClient::requesting(Some(0x00ff0000)); + + client.receive_configure_response(serde_json::json!({ + "version-rolling": true, + "version-rolling.mask": "1fffffe0", + })); + + assert_eq!(client.version_rolling_mask, Some(HexU32Be(0x00ff0000))); + } + + #[test] + fn client_ignores_version_rolling_it_did_not_request() { + let mut client = TestClient::requesting(None); + + client.receive_configure_response(serde_json::json!({ + "version-rolling": true, + "version-rolling.mask": "1fffffe0", + })); + + assert_eq!(client.version_rolling_mask, None); + assert_eq!(client.version_rolling_min_bit, None); + } } From d6c0c53bf10dcf25045f30bcfed03b36e3c70058 Mon Sep 17 00:00:00 2001 From: Amartya Singh Date: Thu, 5 Nov 2026 17:07:39 +0530 Subject: [PATCH 4/4] chore: bump sv1_api to 7.1.0 sv1_api gains VersionRollingParams::negotiated_mask, so it takes a minor bump. No other crate calls it, so their requirements stay at ^7.0.0. --- Cargo.lock | 2 +- fuzz/Cargo.lock | 2 +- sv1/Cargo.toml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 58a34da8dd..889cdd7883 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1203,7 +1203,7 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" [[package]] name = "sv1_api" -version = "7.0.0" +version = "7.1.0" dependencies = [ "binary_sv2", "bitcoin", diff --git a/fuzz/Cargo.lock b/fuzz/Cargo.lock index 79d118bb53..a519d82878 100644 --- a/fuzz/Cargo.lock +++ b/fuzz/Cargo.lock @@ -559,7 +559,7 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" [[package]] name = "sv1_api" -version = "7.0.0" +version = "7.1.0" dependencies = [ "binary_sv2", "bitcoin", diff --git a/sv1/Cargo.toml b/sv1/Cargo.toml index 33b1b3233c..374f26b4f5 100644 --- a/sv1/Cargo.toml +++ b/sv1/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "sv1_api" -version = "7.0.0" +version = "7.1.0" authors = ["The Stratum V2 Developers"] edition = "2021" readme = "README.md"