chore(api)!: use FeeRate instead of f64 for fee estimates

luisschwab · luisschwab · commit 8c52fba91277 · 2026-04-10T11:57:33.000-03:00
This commit:
  - Changes `get_fee_estimates` to return `HashMap&lt;u16, FeeRate&gt;` instead of `HashMap&lt;u16, f64&gt;`.
  - Changes `convert_fee_rate` to accept `HashMap&lt;u16, FeeRate&gt;` and return `Option&lt;FeeRate&gt;` instead of `Option&lt;f32&gt;`.
  - Adds `sat_per_vbyte_to_feerate` to `api.rs` to convert the raw `f64` sat/vbyte values returned by the Esplora API into `FeeRate`.
  - Updates the `feerate_parsing` test accordingly.
diff --git a/src/api.rs b/src/api.rs
@@ -470,6 +470,14 @@ pub struct MempoolFeesSubmitPackage {
     pub effective_includes: Option<Vec<Wtxid>>,
 }
 
+/// Converts a [`HashMap`] of fee estimates in sat/vbyte (`f64`) to [`FeeRate`].
+pub(crate) fn sat_per_vbyte_to_feerate(estimates: HashMap<u16, f64>) -> HashMap<u16, FeeRate> {
+    estimates
+        .into_iter()
+        .map(|(k, v)| (k, FeeRate::from_sat_per_kwu((v * 250_000.0) as u64)))
+        .collect()
+}
+
 /// Deserializes a witness from a list of hex-encoded strings.
 ///
 /// The Esplora API represents witness data as an array of hex strings,
diff --git a/src/async.rs b/src/async.rs
@@ -37,14 +37,14 @@ use bitcoin::consensus::encode::serialize_hex;
 use bitcoin::consensus::{deserialize, serialize, Decodable};
 use bitcoin::hashes::{sha256, Hash};
 use bitcoin::hex::{DisplayHex, FromHex};
-use bitcoin::{Address, Block, BlockHash, MerkleBlock, Script, Transaction, Txid};
+use bitcoin::{Address, Block, BlockHash, FeeRate, MerkleBlock, Script, Transaction, Txid};
 
 use reqwest::{header, Body, Client, Response};
 
 use crate::{
-    AddressStats, BlockInfo, BlockStatus, Builder, Error, EsploraTx, MempoolRecentTx, MempoolStats,
-    MerkleProof, OutputStatus, ScriptHashStats, SubmitPackageResult, TxStatus, Utxo,
-    BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
+    sat_per_vbyte_to_feerate, AddressStats, BlockInfo, BlockStatus, Builder, Error, EsploraTx,
+    MempoolRecentTx, MempoolStats, MerkleProof, OutputStatus, ScriptHashStats, SubmitPackageResult,
+    TxStatus, Utxo, BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
 /// Returns `true` if the given HTTP status code should trigger a retry.
@@ -629,9 +629,12 @@ impl<S: Sleeper> AsyncClient<S> {
     /// Get fee estimates for a range of confirmation targets.
     ///
     /// Returns a [`HashMap`] where the key is the confirmation target in blocks
-    /// and the value is the estimated fee rate in sat/vB.
-    pub async fn get_fee_estimates(&self) -> Result<HashMap<u16, f64>, Error> {
-        self.get_response_json("/fee-estimates").await
+    /// and the value is the estimated [`FeeRate`].
+    pub async fn get_fee_estimates(&self) -> Result<HashMap<u16, FeeRate>, Error> {
+        let estimates_raw: HashMap<u16, f64> = self.get_response_json("/fee-estimates").await?;
+        let estimates = sat_per_vbyte_to_feerate(estimates_raw);
+
+        Ok(estimates)
     }
 
     // ----> ADDRESS
diff --git a/src/blocking.rs b/src/blocking.rs
@@ -36,12 +36,12 @@ use bitcoin::consensus::encode::serialize_hex;
 use bitcoin::consensus::{deserialize, serialize, Decodable};
 use bitcoin::hashes::{sha256, Hash};
 use bitcoin::hex::{DisplayHex, FromHex};
-use bitcoin::{Address, Block, BlockHash, MerkleBlock, Script, Transaction, Txid};
+use bitcoin::{Address, Block, BlockHash, FeeRate, MerkleBlock, Script, Transaction, Txid};
 
 use crate::{
-    AddressStats, BlockInfo, BlockStatus, Builder, Error, EsploraTx, MempoolRecentTx, MempoolStats,
-    MerkleProof, OutputStatus, ScriptHashStats, SubmitPackageResult, TxStatus, Utxo,
-    BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
+    sat_per_vbyte_to_feerate, AddressStats, BlockInfo, BlockStatus, Builder, Error, EsploraTx,
+    MempoolRecentTx, MempoolStats, MerkleProof, OutputStatus, ScriptHashStats, SubmitPackageResult,
+    TxStatus, Utxo, BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
 /// Returns `true` if the given HTTP status code indicates a successful response.
@@ -620,9 +620,12 @@ impl BlockingClient {
     /// Get fee estimates for a range of confirmation targets.
     ///
     /// Returns a [`HashMap`] where the key is the confirmation target in blocks
-    /// and the value is the estimated fee rate in sat/vB.
-    pub fn get_fee_estimates(&self) -> Result<HashMap<u16, f64>, Error> {
-        self.get_response_json("/fee-estimates")
+    /// and the value is the estimated [`FeeRate`].
+    pub fn get_fee_estimates(&self) -> Result<HashMap<u16, FeeRate>, Error> {
+        let estimates_raw: HashMap<u16, f64> = self.get_response_json("/fee-estimates")?;
+        let estimates = sat_per_vbyte_to_feerate(estimates_raw);
+
+        Ok(estimates)
     }
 
     // ----> ADDRESS
diff --git a/src/lib.rs b/src/lib.rs
@@ -103,17 +103,39 @@ const BASE_BACKOFF_MILLIS: Duration = Duration::from_millis(256);
 /// Default max retries.
 const DEFAULT_MAX_RETRIES: usize = 6;
 
-/// Get a fee value in sats/vbytes from the estimates
-/// that matches the confirmation target set as parameter.
+/// Returns the [`FeeRate`] for the given confirmation target in blocks.
 ///
-/// Returns `None` if no feerate estimate is found at or below `target`
-/// confirmations.
-pub fn convert_fee_rate(target: usize, estimates: HashMap<u16, f64>) -> Option<f32> {
+/// Selects the highest confirmation target from `estimates` that is at or
+/// below `target_blocks`, and returns its [`FeeRate`]. Returns `None` if no
+/// matching estimate is found.
+///
+/// # Example
+///
+/// ```rust
+/// use bitcoin::FeeRate;
+/// use esplora_client::convert_fee_rate;
+/// use std::collections::HashMap;
+///
+/// let mut estimates = HashMap::new();
+/// estimates.insert(1u16, FeeRate::from_sat_per_vb(10).unwrap());
+/// estimates.insert(6u16, FeeRate::from_sat_per_vb(5).unwrap());
+///
+/// assert_eq!(
+///     convert_fee_rate(6, estimates.clone()),
+///     Some(FeeRate::from_sat_per_vb(5).unwrap())
+/// );
+/// assert_eq!(
+///     convert_fee_rate(1, estimates.clone()),
+///     Some(FeeRate::from_sat_per_vb(10).unwrap())
+/// );
+/// assert_eq!(convert_fee_rate(0, estimates), None);
+/// ```
+pub fn convert_fee_rate(target_blocks: usize, estimates: HashMap<u16, FeeRate>) -> Option<FeeRate> {
     estimates
         .into_iter()
-        .filter(|(k, _)| *k as usize <= target)
+        .filter(|(k, _)| *k as usize <= target_blocks)
         .max_by_key(|(k, _)| *k)
-        .map(|(_, v)| v as f32)
+        .map(|(_, feerate)| feerate)
 }
 
 /// A builder for an [`AsyncClient`] or [`BlockingClient`].
@@ -473,8 +495,8 @@ mod test {
     }
 
     #[test]
-    fn feerate_parsing() {
-        let esplora_fees = serde_json::from_str::<HashMap<u16, f64>>(
+    fn test_feerate_parsing() {
+        let esplora_fees_raw = serde_json::from_str::<HashMap<u16, f64>>(
             r#"{
   "25": 1.015,
   "5": 2.3280000000000003,
@@ -508,11 +530,19 @@ mod test {
 "#,
         )
         .unwrap();
+
+        // Convert fees from sat/vB (`f64`) to `FeeRate`.
+        // Note that `get_fee_estimates` already returns `HashMap<u16, FeeRate>`.
+        let esplora_fees = sat_per_vbyte_to_feerate(esplora_fees_raw);
+
         assert!(convert_fee_rate(1, HashMap::new()).is_none());
-        assert_eq!(convert_fee_rate(6, esplora_fees.clone()).unwrap(), 2.236);
         assert_eq!(
-            convert_fee_rate(26, esplora_fees.clone()).unwrap(),
-            1.015,
+            convert_fee_rate(6, esplora_fees.clone()),
+            Some(FeeRate::from_sat_per_kwu((2.236_f64 * 250_000.0) as u64))
+        );
+        assert_eq!(
+            convert_fee_rate(26, esplora_fees.clone()),
+            Some(FeeRate::from_sat_per_kwu((1.015_f64 * 250_000.0) as u64)),
             "should inherit from value for 25"
         );
         assert!(
