feat(client): add get_address_utxos()

`get_address_utxos` hits the `/address/{address}/utxo` endpoint
and returns a `Vec<Utxo>`

Author: luisschwab

src/async.rs

@@ -30,7 +30,7 @@ use reqwest::{header, Client, Response};
 
 use crate::api::AddressStats;
 use crate::{
-    BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus,
+    BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus, Utxo,
     BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
@@ -449,6 +449,12 @@ impl<S: Sleeper> AsyncClient<S> {
         Ok(blocks)
     }
 
+    /// Get all UTXOs locked to an address.
+    pub async fn get_address_utxos(&self, address: &Address) -> Result<Vec<Utxo>, Error> {
+        self.get_response_json(&format!("/address/{address}/utxo"))
+            .await
+    }
+
     /// Get the underlying base URL.
     pub fn url(&self) -> &str {
         &self.url

src/blocking.rs

@@ -31,7 +31,7 @@ use bitcoin::{
 
 use crate::api::AddressStats;
 use crate::{
-    BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus,
+    BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus, Utxo,
     BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
@@ -377,6 +377,11 @@ impl BlockingClient {
         Ok(blocks)
     }
 
+    /// Get all UTXOs locked to an address.
+    pub fn get_address_utxos(&self, address: &Address) -> Result<Vec<Utxo>, Error> {
+        self.get_response_json(&format!("/address/{address}/utxo"))
+    }
+
     /// Sends a GET request to the given `url`, retrying failed attempts
     /// for retryable error codes until max retries hit.
     fn get_with_retry(&self, url: &str) -> Result<Response, Error> {

src/lib.rs

@@ -1037,4 +1037,32 @@ mod test {
         assert_eq!(address_txs_blocking, address_txs_async);
         assert_eq!(address_txs_async[0].txid, txid);
     }
+
+    #[cfg(all(feature = "blocking", feature = "async"))]
+    #[tokio::test]
+    async fn test_get_address_utxos() {
+        let (blocking_client, async_client) = setup_clients().await;
+
+        let address = BITCOIND
+            .client
+            .new_address_with_type(AddressType::Legacy)
+            .unwrap();
+
+        let _txid = BITCOIND
+            .client
+            .send_to_address(&address, Amount::from_sat(21000))
+            .unwrap()
+            .txid()
+            .unwrap();
+
+        let _miner = MINER.lock().await;
+        generate_blocks_and_wait(1);
+
+        let address_utxos_blocking = blocking_client.get_address_utxos(&address).unwrap();
+        let address_utxos_async = async_client.get_address_utxos(&address).await.unwrap();
+
+        assert_ne!(address_utxos_blocking.len(), 0);
+        assert_ne!(address_utxos_async.len(), 0);
+        assert_eq!(address_utxos_blocking, address_utxos_async);
+    }
 }