feat: Automatically negotiate protocol version on connect

Send `server.version` as the first message after establishing a
connection, as required by Electrum protocol v1.6. The negotiated
protocol version is stored in `RawClient` and can be retrieved via
the new `protocol_version()` method.

- Add `CLIENT_NAME`, `PROTOCOL_VERSION_MIN`, `PROTOCOL_VERSION_MAX` constants
- Add `protocol_version` field to `RawClient` to store negotiated version
- All constructors (`new`, `new_ssl`, `new_ssl_from_stream`, `new_proxy`)
  now automatically call `server.version` after connecting
- The `server_version()` method also updates the stored version when called

This is a breaking change as the constructors now return errors if
protocol negotiation fails.

Co-Authored-By: Claude Code AI
Signed-off-by: Elias Rohrer <dev@tnull.de>

Author: tnull

src/raw_client.rs

@@ -45,6 +45,15 @@ use crate::api::ElectrumApi;
 use crate::batch::Batch;
 use crate::types::*;
 
+/// Client name sent to the server during protocol version negotiation.
+pub const CLIENT_NAME: &str = "rust-electrum-client";
+
+/// Minimum protocol version supported by this client.
+pub const PROTOCOL_VERSION_MIN: &str = "1.4";
+
+/// Maximum protocol version supported by this client.
+pub const PROTOCOL_VERSION_MAX: &str = "1.6";
+
 macro_rules! impl_batch_call {
     ( $self:expr, $data:expr, $call:ident ) => {{
         impl_batch_call!($self, $data, $call, )
@@ -142,6 +151,9 @@ where
     headers: Mutex<VecDeque<RawHeaderNotification>>,
     script_notifications: Mutex<HashMap<ScriptHash, VecDeque<ScriptStatus>>>,
 
+    /// The protocol version negotiated with the server via `server.version`.
+    protocol_version: Mutex<Option<String>>,
+
     #[cfg(feature = "debug-calls")]
     calls: AtomicUsize,
 }
@@ -163,6 +175,8 @@ where
             headers: Mutex::new(VecDeque::new()),
             script_notifications: Mutex::new(HashMap::new()),
 
+            protocol_version: Mutex::new(None),
+
             #[cfg(feature = "debug-calls")]
             calls: AtomicUsize::new(0),
         }
@@ -173,6 +187,9 @@ where
 pub type ElectrumPlaintextStream = TcpStream;
 impl RawClient<ElectrumPlaintextStream> {
     /// Creates a new plaintext client and tries to connect to `socket_addr`.
+    ///
+    /// Automatically negotiates the protocol version with the server using
+    /// `server.version` as required by the Electrum protocol.
     pub fn new<A: ToSocketAddrs>(
         socket_addrs: A,
         timeout: Option<Duration>,
@@ -187,7 +204,9 @@ impl RawClient<ElectrumPlaintextStream> {
             None => TcpStream::connect(socket_addrs)?,
         };
 
-        Ok(stream.into())
+        let client: Self = stream.into();
+        client.negotiate_protocol_version()?;
+        Ok(client)
     }
 }
 
@@ -285,7 +304,9 @@ impl RawClient<ElectrumSslStream> {
             .connect(&domain, stream)
             .map_err(Error::SslHandshakeError)?;
 
-        Ok(stream.into())
+        let client: Self = stream.into();
+        client.negotiate_protocol_version()?;
+        Ok(client)
     }
 }
 
@@ -466,7 +487,9 @@ impl RawClient<ElectrumSslStream> {
         .map_err(Error::CouldNotCreateConnection)?;
         let stream = StreamOwned::new(session, tcp_stream);
 
-        Ok(stream.into())
+        let client: Self = stream.into();
+        client.negotiate_protocol_version()?;
+        Ok(client)
     }
 }
 
@@ -496,7 +519,9 @@ impl RawClient<ElectrumProxyStream> {
         stream.get_mut().set_read_timeout(timeout)?;
         stream.get_mut().set_write_timeout(timeout)?;
 
-        Ok(stream.into())
+        let client: Self = stream.into();
+        client.negotiate_protocol_version()?;
+        Ok(client)
     }
 
     #[cfg(any(
@@ -551,6 +576,30 @@ impl<S: Read + Write> RawClient<S> {
     //     self._reader_thread(None).map(|_| ())
     // }
 
+    /// Negotiates the protocol version with the server.
+    ///
+    /// This sends `server.version` as the first message and stores the negotiated
+    /// protocol version. Called automatically by constructors.
+    fn negotiate_protocol_version(&self) -> Result<(), Error> {
+        let version_range = vec![
+            PROTOCOL_VERSION_MIN.to_string(),
+            PROTOCOL_VERSION_MAX.to_string(),
+        ];
+        let req = Request::new_id(
+            self.last_id.fetch_add(1, Ordering::SeqCst),
+            "server.version",
+            vec![
+                Param::String(CLIENT_NAME.to_string()),
+                Param::StringVec(version_range),
+            ],
+        );
+        let result = self.call(req)?;
+        let response: ServerVersionRes = serde_json::from_value(result)?;
+
+        *self.protocol_version.lock()? = Some(response.protocol_version);
+        Ok(())
+    }
+
     fn _reader_thread(&self, until_message: Option<usize>) -> Result<serde_json::Value, Error> {
         let mut raw_resp = String::new();
         let resp = match self.buf_reader.try_lock() {

src/types.rs

@@ -33,6 +33,8 @@ pub enum Param {
     Bool(bool),
     /// Bytes array parameter
     Bytes(Vec<u8>),
+    /// String array parameter
+    StringVec(Vec<String>),
 }
 
 #[derive(Serialize, Clone)]
@@ -202,7 +204,38 @@ pub struct ServerFeaturesRes {
     pub pruning: Option<i64>,
 }
 
-/// Response to a [`server_features`](../client/struct.Client.html#method.server_features) request.
+/// Response to a [`server_version`](../client/struct.Client.html#method.server_version) request.
+///
+/// This is returned as an array of two strings: `[server_software_version, protocol_version]`.
+#[derive(Clone, Debug)]
+pub struct ServerVersionRes {
+    /// Server software version string (e.g., "ElectrumX 1.18.0").
+    pub server_software_version: String,
+    /// Negotiated protocol version (e.g., "1.6").
+    pub protocol_version: String,
+}
+
+impl<'de> Deserialize<'de> for ServerVersionRes {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: de::Deserializer<'de>,
+    {
+        let arr: Vec<String> = Vec::deserialize(deserializer)?;
+        let mut iter = arr.into_iter();
+        let server_software_version = iter.next().ok_or_else(|| {
+            de::Error::custom("expected server_software_version as first element")
+        })?;
+        let protocol_version = iter
+            .next()
+            .ok_or_else(|| de::Error::custom("expected protocol_version as second element"))?;
+        Ok(ServerVersionRes {
+            server_software_version,
+            protocol_version,
+        })
+    }
+}
+
+/// Response to a [`block_headers`](../client/struct.Client.html#method.block_headers) request.
 #[derive(Clone, Debug, Deserialize)]
 pub struct GetHeadersRes {
     /// Maximum number of headers returned in a single response.