feat: Add optional EstimationMode parameter to estimate_fee

Add support for the optional `mode` argument to `blockchain.estimatefee`
which was added in protocol v1.6. The mode is passed to bitcoind's
`estimatesmartfee` RPC as the `estimate_mode` parameter.

- Add `EstimationMode` enum with `Conservative` and `Economical` variants
- Update `estimate_fee` to take `Option<EstimationMode>` as second parameter
- Update `Batch::estimate_fee` to support the mode parameter
- `batch_estimate_fee` currently always uses `None` for mode

This is a breaking change as the `estimate_fee` signature has changed.

Co-Authored-By: Claude Code AI

Author: tnull

src/api.rs

@@ -42,8 +42,8 @@ where
         (**self).block_headers(start_height, count)
     }
 
-    fn estimate_fee(&self, number: usize) -> Result<f64, Error> {
-        (**self).estimate_fee(number)
+    fn estimate_fee(&self, number: usize, mode: Option<EstimationMode>) -> Result<f64, Error> {
+        (**self).estimate_fee(number, mode)
     }
 
     fn relay_fee(&self) -> Result<f64, Error> {
@@ -272,7 +272,10 @@ pub trait ElectrumApi {
     fn block_headers(&self, start_height: usize, count: usize) -> Result<GetHeadersRes, Error>;
 
     /// Estimates the fee required in **Bitcoin per kilobyte** to confirm a transaction in `number` blocks.
-    fn estimate_fee(&self, number: usize) -> Result<f64, Error>;
+    ///
+    /// Optionally takes an [`EstimationMode`] parameter to specify the fee estimation mode.
+    /// This parameter was added in protocol v1.6.
+    fn estimate_fee(&self, number: usize, mode: Option<EstimationMode>) -> Result<f64, Error>;
 
     /// Returns the minimum accepted fee by the server's node in **Bitcoin, not Satoshi**.
     fn relay_fee(&self) -> Result<f64, Error>;
@@ -459,7 +462,11 @@ mod test {
             unreachable!()
         }
 
-        fn estimate_fee(&self, _: usize) -> Result<f64, super::Error> {
+        fn estimate_fee(
+            &self,
+            _: usize,
+            _: Option<super::EstimationMode>,
+        ) -> Result<f64, super::Error> {
             unreachable!()
         }
 

src/batch.rs

@@ -4,7 +4,7 @@
 
 use bitcoin::{Script, Txid};
 
-use crate::types::{Call, Param, ToElectrumScriptHash};
+use crate::types::{Call, EstimationMode, Param, ToElectrumScriptHash};
 
 /// Helper structure that caches all the requests before they are actually sent to the server.
 ///
@@ -74,8 +74,11 @@ impl Batch {
     }
 
     /// Add one `blockchain.estimatefee` request to the batch queue
-    pub fn estimate_fee(&mut self, number: usize) {
-        let params = vec![Param::Usize(number)];
+    pub fn estimate_fee(&mut self, number: usize, mode: Option<EstimationMode>) {
+        let mut params = vec![Param::Usize(number)];
+        if let Some(mode) = mode {
+            params.push(Param::String(mode.to_string()));
+        }
         self.calls
             .push((String::from("blockchain.estimatefee"), params));
     }

src/client.rs

@@ -207,8 +207,8 @@ impl ElectrumApi for Client {
     }
 
     #[inline]
-    fn estimate_fee(&self, number: usize) -> Result<f64, Error> {
-        impl_inner_call!(self, estimate_fee, number)
+    fn estimate_fee(&self, number: usize, mode: Option<EstimationMode>) -> Result<f64, Error> {
+        impl_inner_call!(self, estimate_fee, number, mode)
     }
 
     #[inline]

src/raw_client.rs

@@ -938,11 +938,15 @@ impl<T: Read + Write> ElectrumApi for RawClient<T> {
         Ok(deserialized)
     }
 
-    fn estimate_fee(&self, number: usize) -> Result<f64, Error> {
+    fn estimate_fee(&self, number: usize, mode: Option<EstimationMode>) -> Result<f64, Error> {
+        let mut params = vec![Param::Usize(number)];
+        if let Some(mode) = mode {
+            params.push(Param::String(mode.to_string()));
+        }
         let req = Request::new_id(
             self.last_id.fetch_add(1, Ordering::SeqCst),
             "blockchain.estimatefee",
-            vec![Param::Usize(number)],
+            params,
         );
         let result = self.call(req)?;
 
@@ -1147,7 +1151,19 @@ impl<T: Read + Write> ElectrumApi for RawClient<T> {
         I: IntoIterator + Clone,
         I::Item: Borrow<usize>,
     {
-        impl_batch_call!(self, numbers, estimate_fee, apply_deref)
+        let mut batch = Batch::default();
+        for i in numbers {
+            batch.estimate_fee(*i.borrow(), None);
+        }
+
+        let resp = self.batch_call(&batch)?;
+        let mut answer = Vec::new();
+
+        for x in resp {
+            answer.push(serde_json::from_value(x)?);
+        }
+
+        Ok(answer)
     }
 
     fn transaction_broadcast_raw(&self, raw_tx: &[u8]) -> Result<Txid, Error> {
@@ -1328,7 +1344,7 @@ mod test {
     fn test_estimate_fee() {
         let client = get_test_client();
 
-        let resp = client.estimate_fee(10).unwrap();
+        let resp = client.estimate_fee(10, None).unwrap();
         assert!(resp > 0.0);
     }
 

src/types.rs

@@ -37,6 +37,29 @@ pub enum Param {
     StringVec(Vec<String>),
 }
 
+/// Fee estimation mode for [`estimate_fee`](../api/trait.ElectrumApi.html#method.estimate_fee).
+///
+/// This parameter was added in protocol v1.6 and is passed to bitcoind's
+/// `estimatesmartfee` RPC as the `estimate_mode` parameter.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EstimationMode {
+    /// A conservative estimate potentially returns a higher feerate and is more likely to be
+    /// sufficient for the desired target, but is not as responsive to short term drops in the
+    /// prevailing fee market.
+    Conservative,
+    /// Economical fee estimate - potentially lower fees but may take longer to confirm.
+    Economical,
+}
+
+impl Display for EstimationMode {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            EstimationMode::Conservative => write!(f, "CONSERVATIVE"),
+            EstimationMode::Economical => write!(f, "ECONOMICAL"),
+        }
+    }
+}
+
 #[derive(Serialize, Clone)]
 /// A request that can be sent to the server
 pub struct Request<'a> {