Merge bitcoindevkit#134: feat: add get_address_utxos method

86d3d44 feat(client): add `get_address_utxos()` (Luis Schwab)
3c8b6e3 feat(api): create `UtxoStatus` and `Utxo` structs (Luis Schwab)

Pull request description:

  Closes bitcoindevkit#133.

  This PR adds the `get_address_utxos` method, which hits the `/address/{addr}/utxo` endpoint, returning a `Vec<Utxo>`.

  # Changelog
  - Create `UtxoStatus`.
  - Create `Utxo`.
  - Create `get_address_utxos` for both blocking and async clients.
  - Add a functional test for it.

ACKs for top commit:
  oleonardolima:
    ACK 86d3d44

Tree-SHA512: 9fa3e210be06d47e350d1afe01ab6b5c9173a2504ae769c6af364a1badbeb93034e3d053ebc95a8605030ba87dac264772c0c1a277561671a7a84b9d6a3f628d

Author: oleonardolima

src/api.rs

@@ -123,6 +123,33 @@ pub struct AddressTxsSummary {
     pub tx_count: u32,
 }
 
+/// Information about an UTXO's status: confirmation status,
+/// confirmation height, confirmation block hash and confirmation block time.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
+pub struct UtxoStatus {
+    /// Whether or not the UTXO is confirmed.
+    pub confirmed: bool,
+    /// The block height in which the UTXO was confirmed.
+    pub block_height: Option<u32>,
+    /// The block hash in which the UTXO was confirmed.
+    pub block_hash: Option<BlockHash>,
+    /// The UNIX timestamp in which the UTXO was confirmed.
+    pub block_time: Option<u64>,
+}
+
+/// Information about an UTXO's outpoint, confirmation status and value.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
+pub struct Utxo {
+    /// The [`Txid`] of the transaction that created the UTXO.
+    pub txid: Txid,
+    /// The output index of the UTXO on the transaction that created the it.
+    pub vout: u32,
+    /// The confirmation status of the UTXO.
+    pub status: UtxoStatus,
+    /// The value of the UTXO as an [`Amount`].
+    pub value: Amount,
+}
+
 impl Tx {
     pub fn to_tx(&self) -> Transaction {
         Transaction {

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);
+    }
 }