diff --git a/sdk/package.json b/sdk/package.json index ea6368a1..8dc2c5b0 100644 --- a/sdk/package.json +++ b/sdk/package.json @@ -1,6 +1,6 @@ { "name": "@gobob/bob-sdk", - "version": "2.3.8", + "version": "3.0.0", "main": "dist/index.js", "types": "dist/index.d.ts", "scripts": { diff --git a/sdk/src/esplora.ts b/sdk/src/esplora.ts index f7c3650c..ea4ab8fe 100644 --- a/sdk/src/esplora.ts +++ b/sdk/src/esplora.ts @@ -341,6 +341,7 @@ export class EsploraClient { * * @dev Should return up to 500 UTXOs - depending on the configured limit. * @param {string} address - The Bitcoin address to check. + * @param {string} [confirmed] - Whether to return only confirmed UTXOs. If omitted, defaults to false. * @returns {Promise>} A promise that resolves to an array of UTXOs. */ async getAddressUtxos(address: string, confirmed?: boolean): Promise> { @@ -388,12 +389,19 @@ export class EsploraClient { } /** - * Get the balance for an account / address. + * Get the Bitcoin balance for an address, returning both confirmed (on-chain) and unconfirmed (mempool) balances. + * + * @dev This method returns an object containing the confirmed balance, unconfirmed balance, and the total balance. + * The confirmed balance represents the amount that is on-chain, while the mempool balance includes transactions + * that are pending (unconfirmed). The total is the sum of both confirmed and unconfirmed balances. * * @param {string} address - The Bitcoin address to check. - * @returns {Promise} A promise that resolves to the balance. + * @returns {Promise<{ confirmed: number, unconfirmed: number, total: number }>} A promise that resolves to an object containing: + * - `confirmed`: The confirmed on-chain balance in satoshis. + * - `unconfirmed`: The unconfirmed balance (in mempool) in satoshis. + * - `total`: The total balance, which is the sum of the confirmed and unconfirmed balances. */ - async getBalance(address: string): Promise { + async getBalance(address: string): Promise<{ confirmed: number; unconfirmed: number; total: number }> { const response = await this.getJson<{ address: string; chain_stats: { @@ -412,9 +420,14 @@ export class EsploraClient { }; }>(`${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; + const confirmedBalance = response.chain_stats.funded_txo_sum - response.chain_stats.spent_txo_sum; + const unconfirmedBalance = response.mempool_stats.funded_txo_sum - response.mempool_stats.spent_txo_sum; + + return { + confirmed: confirmedBalance, + unconfirmed: unconfirmedBalance, + total: confirmedBalance + unconfirmedBalance, + }; } /** diff --git a/sdk/test/esplora.test.ts b/sdk/test/esplora.test.ts index 58cc813f..a163a371 100644 --- a/sdk/test/esplora.test.ts +++ b/sdk/test/esplora.test.ts @@ -138,6 +138,10 @@ describe('Esplora Tests', () => { it('should get balance', async () => { const client = new EsploraClient('testnet'); const balance = await client.getBalance('tb1qjhekcm565spvr0epqu5nvd9mhgwaafg6d0n2yw'); - assert.equal(balance, 727499862); + assert.deepEqual(balance, { + confirmed: 727499862, + unconfirmed: 0, + total: 727499862, + }); }); });