From 8f4e17f7a724c69dd45ce0ba28a2aef07128a638 Mon Sep 17 00:00:00 2001
From: Gregory Hill <gregorydhill@outlook.com>
Date: Thu, 5 Sep 2024 11:44:57 +0100
Subject: [PATCH] feat: add esplora get balance

Signed-off-by: Gregory Hill <gregorydhill@outlook.com>
---
 sdk/package-lock.json    |  4 ++--
 sdk/package.json         |  2 +-
 sdk/src/esplora.ts       | 34 ++++++++++++++++++++++++++++++++++
 sdk/src/wallet/utxo.ts   |  2 --
 sdk/test/esplora.test.ts |  6 +++++-
 5 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/sdk/package-lock.json b/sdk/package-lock.json
index 990cb940..5498778a 100644
--- a/sdk/package-lock.json
+++ b/sdk/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@gobob/bob-sdk",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gobob/bob-sdk",
-      "version": "2.2.4",
+      "version": "2.2.5",
       "dependencies": {
         "@scure/base": "^1.1.7",
         "@scure/btc-signer": "^1.3.2",
diff --git a/sdk/package.json b/sdk/package.json
index 77623bdc..cde93e02 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@gobob/bob-sdk",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
diff --git a/sdk/src/esplora.ts b/sdk/src/esplora.ts
index 05a2793e..44f54eaa 100644
--- a/sdk/src/esplora.ts
+++ b/sdk/src/esplora.ts
@@ -330,10 +330,14 @@ export class EsploraClient {
     /**
      * Get the Unspent Transaction Outputs (UTXOs) for an address.
      *
+     * @dev Should return up to 500 UTXOs - depending on the configured limit.
      * @param {string} address - The Bitcoin address to check.
      * @returns {Promise<Array<UTXO>>} A promise that resolves to an array of UTXOs.
      */
     async getAddressUtxos(address: string, confirmed?: boolean): Promise<Array<UTXO>> {
+        // https://github.com/Blockstream/electrs/blob/306f66acf2ab10bcd99b8012e95a0de30b2cc012/src/rest.rs#L860
+        // https://github.com/Blockstream/electrs/blob/306f66acf2ab10bcd99b8012e95a0de30b2cc012/src/new_index/query.rs#L82
+        // https://github.com/Blockstream/electrs/blob/306f66acf2ab10bcd99b8012e95a0de30b2cc012/src/config.rs#L177
         const response = await this.getJson<Array<{
             txid: string,
             vout: number,
@@ -372,6 +376,36 @@ export class EsploraClient {
         return await res.text();
     }
 
+    /**
+     * Get the balance for an account / address.
+     *
+     * @param {string} address - The Bitcoin address to check.
+     * @returns {Promise<number>} A promise that resolves to the balance.
+     */
+    async getBalance(address: string): Promise<number> {
+        const response = await this.getJson<{
+            address: string,
+            chain_stats: {
+                funded_txo_count: number,
+                funded_txo_sum: number,
+                spent_txo_count: number,
+                spent_txo_sum: number,
+                tx_count: number
+            },
+            mempool_stats: {
+                funded_txo_count: number,
+                funded_txo_sum: number,
+                spent_txo_count: number,
+                spent_txo_sum: number,
+                tx_count: number
+            }
+        }>(`${this.basePath}/address/${address}`);
+
+        const chainBalance = response.chain_stats.funded_txo_sum - response.chain_stats.spent_txo_sum;
+        const mempoolBalance = response.mempool_stats.funded_txo_sum - response.mempool_stats.spent_txo_sum;
+        return chainBalance + mempoolBalance;
+    }
+
     /**
      * @ignore
      */
diff --git a/sdk/src/wallet/utxo.ts b/sdk/src/wallet/utxo.ts
index c119d443..16ed12ef 100644
--- a/sdk/src/wallet/utxo.ts
+++ b/sdk/src/wallet/utxo.ts
@@ -64,8 +64,6 @@ export async function createBitcoinPsbt(
 
     const esploraClient = new EsploraClient(addressInfo.network);
 
-    // NOTE: esplora only returns the 25 most recent UTXOs
-    // TODO: change this to use the pagination API and return all UTXOs
     const [confirmedUtxos, feeRate] = await Promise.all([
         esploraClient.getAddressUtxos(fromAddress),
         esploraClient.getFeeEstimate(confirmationTarget),
diff --git a/sdk/test/esplora.test.ts b/sdk/test/esplora.test.ts
index d4693390..e5bc51fd 100644
--- a/sdk/test/esplora.test.ts
+++ b/sdk/test/esplora.test.ts
@@ -116,5 +116,9 @@ describe("Esplora Tests", () => {
         assert.isAtLeast(feeRate, 1);
     });
 
-
+    it("should get balance", async () => {
+        const client = new EsploraClient("testnet");
+        const balance = await client.getBalance("tb1qjhekcm565spvr0epqu5nvd9mhgwaafg6d0n2yw");
+        assert.equal(balance, 727499862);
+    });
 });