feat: balances service

apps/mobile/src/queries/balance/bitcoin-balance.query.ts

@@ -1,15 +1,12 @@
-import { useCallback } from 'react';
-
 import { AccountId } from '@/models/domain.model';
 import { useBitcoinAccounts } from '@/store/keychains/bitcoin/bitcoin-keychains.read';
 import { useSettings } from '@/store/settings/settings';
-import { UseQueryResult, useQueries } from '@tanstack/react-query';
+import { QueryFunctionContext, useQueries, useQuery } from '@tanstack/react-query';
 
 import { inferPaymentTypeFromPath } from '@leather.io/bitcoin';
 import { Utxo, createUtxoQueryOptions } from '@leather.io/query';
-import { baseCurrencyAmountInQuote, createMoney, isDefined, sumNumbers } from '@leather.io/utils';
-
-import { useBtcMarketDataQuery } from '../market-data/btc-market-data.query';
+import { getBitcoinBalancesService } from '@leather.io/services';
+import { createMoney, isDefined } from '@leather.io/utils';
 
 function getDescriptorFromKeychain<T extends { keyOrigin: string; xpub: string }>(
   accountKeychain: T
@@ -57,32 +54,12 @@ export function useBitcoinAccountUtxos({ fingerprint, accountIndex }: AccountId)
   });
 }
 
-type TotalBalanceCombineFn = UseQueryResult<Utxo[], Error>[];
-
 export function useTotalBitcoinBalanceOfDescriptors(descriptors: string[]) {
-  const queries = useCreateBitcoinAccountUtxoQueryOptions(descriptors);
-  const { data: btcMarketData } = useBtcMarketDataQuery();
-
-  const combine = useCallback(
-    (results: TotalBalanceCombineFn) => {
-      const amount = sumNumbers(
-        results
-          .map(data => data.data)
-          .filter(isDefined)
-          .map(data => sumNumbers(data.map(utxo => Number(utxo.value))).toNumber())
-      );
-
-      const availableBalance = createMoney(amount, 'BTC');
-      const fiatBalance = btcMarketData
-        ? baseCurrencyAmountInQuote(availableBalance, btcMarketData)
-        : createMoney(0, 'USD');
-
-      return { availableBalance, fiatBalance };
-    },
-    [btcMarketData]
-  );
-
-  return useQueries({ queries, combine });
+  const { isLoading, data } = useBtcBalanceQuery(descriptors);
+  return {
+    availableBalance: !isLoading && data ? data.balanceBtc.availableBalance : createMoney(0, 'BTC'),
+    fiatBalance: !isLoading && data ? data.balanceUsd.availableBalance : createMoney(0, 'USD'),
+  };
 }
 
 export function useWalletTotalBitcoinBalance() {
@@ -94,3 +71,17 @@ export function useBitcoinAccountTotalBitcoinBalance({ fingerprint, accountIndex
   const descriptors = useBitcoinDescriptorsByAcccount(fingerprint, accountIndex);
   return useTotalBitcoinBalanceOfDescriptors(descriptors);
 }
+
+export function useBtcBalanceQuery(descriptors: string[]) {
+  return useQuery({
+    queryKey: ['bitcoin-balance-service-get-btc-balance', descriptors],
+    queryFn: ({ signal }: QueryFunctionContext) =>
+      getBitcoinBalancesService().getBtcBalance(descriptors, signal),
+    refetchOnReconnect: false,
+    refetchOnWindowFocus: false,
+    refetchOnMount: true,
+    retryOnMount: false,
+    staleTime: 1 * 1000,
+    gcTime: 1 * 1000,
+  });
+}

apps/mobile/src/queries/balance/stacks-balance.query.ts

@@ -9,12 +9,13 @@ import {
   createGetStacksAccountBalanceQueryOptions,
   createStxCryptoAssetBalance,
   createStxMoney,
-  useCryptoCurrencyMarketDataMeanAverage,
   useCurrentNetworkState,
   useStacksClient,
 } from '@leather.io/query';
 import { baseCurrencyAmountInQuote, createMoney, sumMoney } from '@leather.io/utils';
 
+import { useStxMarketDataQuery } from '../market-data/stx-market-data.query';
+
 interface StxBalances {
   totalStxBalance: Money;
 }
@@ -68,7 +69,9 @@ function useStxBalancesQueries(addresses: string[]) {
 export function useStxBalance(addresses: string[]) {
   const { totalStxBalance } = useGetStxBalanceByAddresses(addresses);
 
-  const stxMarketData = useCryptoCurrencyMarketDataMeanAverage('STX');
-  const stxBalanceUsd = baseCurrencyAmountInQuote(totalStxBalance, stxMarketData);
+  const { data: stxMarketData } = useStxMarketDataQuery();
+  const stxBalanceUsd = stxMarketData
+    ? baseCurrencyAmountInQuote(totalStxBalance, stxMarketData)
+    : createMoney(0, 'USD');
   return { availableBalance: totalStxBalance, fiatBalance: stxBalanceUsd };
 }

packages/models/src/crypto-assets/crypto-asset-balance.model.ts

@@ -1,6 +1,22 @@
 import { Money } from '../money.model';
 
 export interface BaseCryptoAssetBalance {
+  /**
+   * Balance as confirmed on chain
+   */
+  readonly totalBalance: Money;
+  /**
+   * Balance of pending receipt into account given pending transactions
+   */
+  readonly inboundBalance: Money;
+  /**
+   * Balance of pending delivery from account given pending transactions
+   */
+  readonly outboundBalance: Money;
+  /**
+   * totalBalance plus inboundBalance minus outboundBalance
+   */
+  readonly pendingBalance: Money;
   /**
    * totalBalance after filtering out outboundBalance, protectedBalance, and uneconomicalBalance
    */
@@ -24,25 +40,9 @@ export interface StxCryptoAssetBalance extends BaseCryptoAssetBalance {
    */
   readonly availableUnlockedBalance: Money;
   /**
-   * Balance of pending receipt into account given pending transactions
-   */
-  readonly inboundBalance: Money;
-  /**
-   * totalBalance minus total amount locked by contracts
+   * total amount locked by contracts
    */
   readonly lockedBalance: Money;
-  /**
-   * Balance of pending delivery from account given pending transactions
-   */
-  readonly outboundBalance: Money;
-  /**
-   * totalBalance plus inboundBalance minus outboundBalance
-   */
-  readonly pendingBalance: Money;
-  /**
-   * Balance as confirmed on chain
-   */
-  readonly totalBalance: Money;
   /**
    * totalBalance minus lockedBalance
    */
@@ -53,7 +53,3 @@ export type CryptoAssetBalance =
   | BaseCryptoAssetBalance
   | BtcCryptoAssetBalance
   | StxCryptoAssetBalance;
-
-export function createCryptoAssetBalance(balance: Money): BaseCryptoAssetBalance {
-  return { availableBalance: balance };
-}

packages/query/src/bitcoin/runes/runes.utils.ts

@@ -1,11 +1,10 @@
 import {
   Money,
   type RuneCryptoAssetInfo,
-  createCryptoAssetBalance,
   createMarketData,
   createMarketPair,
 } from '@leather.io/models';
-import { createMoney } from '@leather.io/utils';
+import { createBaseCryptoAssetBalance, createMoney } from '@leather.io/utils';
 
 import { RuneBalance, RuneTickerInfo } from '../clients/best-in-slot';
 
@@ -30,7 +29,7 @@ export function createRuneCryptoAssetDetails(
   fiatPrice: Money
 ) {
   return {
-    balance: createCryptoAssetBalance(
+    balance: createBaseCryptoAssetBalance(
       createMoney(Number(runeBalance.total_balance), tickerInfo.rune_name, tickerInfo.decimals)
     ),
     info: createRuneCryptoAssetInfo(tickerInfo),

packages/query/src/bitcoin/stamps/stamps-by-address.hooks.ts

@@ -6,9 +6,8 @@ import {
   CryptoAssetChains,
   CryptoAssetProtocols,
   Src20CryptoAssetInfo,
-  createCryptoAssetBalance,
 } from '@leather.io/models';
-import { createMoney } from '@leather.io/utils';
+import { createBaseCryptoAssetBalance, createMoney } from '@leather.io/utils';
 
 import { Src20Token, createGetStampsByAddressQueryOptions } from './stamps-by-address.query';
 
@@ -36,7 +35,7 @@ export function useSrc20TokensByAddress(address: string) {
     ...createGetStampsByAddressQueryOptions(address),
     select: resp =>
       resp.data.src20.map(token => ({
-        balance: createCryptoAssetBalance(
+        balance: createBaseCryptoAssetBalance(
           createMoney(new BigNumber(token.amt ?? 0), token.tick, 0)
         ),
         info: createSrc20CryptoAssetInfo(token),

packages/query/src/stacks/stx20/stx20-tokens.hooks.ts

@@ -1,8 +1,8 @@
 import { useQuery } from '@tanstack/react-query';
 import BigNumber from 'bignumber.js';
 
-import { Stx20CryptoAssetInfo, createCryptoAssetBalance } from '@leather.io/models';
-import { createMoney } from '@leather.io/utils';
+import { Stx20CryptoAssetInfo } from '@leather.io/models';
+import { createBaseCryptoAssetBalance, createMoney } from '@leather.io/utils';
 
 import { useCurrentNetworkState } from '../../leather-query-provider';
 import { useStacksClient } from '../stacks-client';
@@ -30,7 +30,7 @@ export function useStx20Tokens(address: string) {
     }),
     select: resp =>
       resp.map(stx20Balance => ({
-        balance: createCryptoAssetBalance(
+        balance: createBaseCryptoAssetBalance(
           createMoney(new BigNumber(stx20Balance.balance), stx20Balance.ticker, 0)
         ),
         info: createStx20CryptoAssetInfo(stx20Balance),

packages/query/src/stacks/token-metadata/fungible-tokens/fungible-token-metadata.hooks.ts

@@ -1,8 +1,12 @@
 import { useQueries } from '@tanstack/react-query';
 import BigNumber from 'bignumber.js';
 
-import { createCryptoAssetBalance } from '@leather.io/models';
-import { createMoney, getPrincipalFromContractId, getTicker } from '@leather.io/utils';
+import {
+  createBaseCryptoAssetBalance,
+  createMoney,
+  getPrincipalFromContractId,
+  getTicker,
+} from '@leather.io/utils';
 
 import { useCurrentNetworkState } from '../../../leather-query-provider';
 import { AddressBalanceResponse } from '../../hiro-api-types';
@@ -34,7 +38,7 @@ export function useStacksFungibleTokensBalance(
           const symbol = resp.symbol || getTicker(name);
           return {
             contractId: key,
-            balance: createCryptoAssetBalance(
+            balance: createBaseCryptoAssetBalance(
               createMoney(new BigNumber(value.balance), symbol, resp.decimals ?? 0)
             ),
           };

packages/services/package.json

@@ -28,6 +28,7 @@
   "bugs": "https://github.com/leather-io/mono/issues",
   "dependencies": {
     "@leather.io/bitcoin": "workspace:*",
+    "@leather.io/constants": "workspace:*",
     "@leather.io/models": "workspace:*",
     "@leather.io/utils": "workspace:*",
     "alex-sdk": "2.1.4",
@@ -41,6 +42,7 @@
     "@leather.io/prettier-config": "workspace:*",
     "@leather.io/rpc": "workspace:*",
     "@leather.io/tsconfig-config": "workspace:*",
+    "@stacks/stacks-blockchain-api-types": "7.8.2",
     "eslint": "8.53.0",
     "prettier": "3.3.3",
     "tslib": "2.6.2",

packages/services/src/balances/bitcoin-balances.service.ts

@@ -0,0 +1,101 @@
+import { BtcCryptoAssetBalance } from '@leather.io/models';
+import {
+  baseCurrencyAmountInQuote,
+  createBtcCryptoAssetBalance,
+  createMoney,
+  isDefined,
+  sumNumbers,
+} from '@leather.io/utils';
+
+import { LeatherApiClient, LeatherApiUtxo } from '../infrastructure/api/leather/leather-api.client';
+import { MarketDataService } from '../market-data/market-data.service';
+import { hasUneconomicalBalance, removeExistingUtxos } from './bitcoin-balances.utils';
+
+export interface BtcBalance {
+  balanceBtc: BtcCryptoAssetBalance;
+  balanceUsd: BtcCryptoAssetBalance;
+}
+
+export interface BitcoinBalancesService {
+  getBtcBalance(descriptors: string[], signal?: AbortSignal): Promise<BtcBalance>;
+}
+
+export function createBitcoinBalancesService(
+  leatherApiClient: LeatherApiClient,
+  marketDataService: MarketDataService
+): BitcoinBalancesService {
+  /**
+   * Retrieves total BTC balance for listed descriptors. Includes all sub-balances (inbound, outbound, protected, uneconomical).
+   *
+   * @returns {BtcBalance} BTC balance denominanted in both in BTC and fiat (USD).
+   */
+  async function getBtcBalance(descriptors: string[], signal?: AbortSignal) {
+    const utxoPromises = descriptors.map(descriptor =>
+      leatherApiClient.fetchUtxos(descriptor, signal)
+    );
+    const totalUtxos = (await Promise.all(utxoPromises)).flat().filter(isDefined);
+    const totalBalanceBtc = createMoney(
+      sumNumbers(totalUtxos.map(utxo => Number(utxo.value))).toNumber(),
+      'BTC'
+    );
+    // TODO: fetch inbound utxos
+    const inboundUtxos = await getInboundUtxos(descriptors);
+    const inboundBalanceBtc = createMoney(
+      sumNumbers(inboundUtxos.map(utxo => Number(utxo.value))).toNumber(),
+      'BTC'
+    );
+    // TODO: fetch outbound utxos
+    const outboundUtxos = await getOutboundUtxos(descriptors);
+    const outboundBalanceBtc = createMoney(
+      sumNumbers(outboundUtxos.map(utxo => Number(utxo.value))).toNumber(),
+      'BTC'
+    );
+    // TODO: fetch protected utxos
+    const protectedUtxos = await getProtectedUtxos(descriptors);
+    const protectedBalanceBtc = createMoney(
+      sumNumbers(protectedUtxos.map(utxo => Number(utxo.value))).toNumber(),
+      'BTC'
+    );
+    const uneconomicalUtxos = removeExistingUtxos(totalUtxos, protectedUtxos).filter(
+      hasUneconomicalBalance
+    );
+    const uneconomicalBalanceBtc = createMoney(
+      sumNumbers(uneconomicalUtxos.map(utxo => Number(utxo.value))).toNumber(),
+      'BTC'
+    );
+
+    const btcMarketData = await marketDataService.getBtcMarketData(signal);
+    return {
+      balanceBtc: createBtcCryptoAssetBalance(
+        totalBalanceBtc,
+        inboundBalanceBtc,
+        outboundBalanceBtc,
+        protectedBalanceBtc,
+        uneconomicalBalanceBtc
+      ),
+      balanceUsd: createBtcCryptoAssetBalance(
+        baseCurrencyAmountInQuote(totalBalanceBtc, btcMarketData),
+        baseCurrencyAmountInQuote(inboundBalanceBtc, btcMarketData),
+        baseCurrencyAmountInQuote(outboundBalanceBtc, btcMarketData),
+        baseCurrencyAmountInQuote(protectedBalanceBtc, btcMarketData),
+        baseCurrencyAmountInQuote(uneconomicalBalanceBtc, btcMarketData)
+      ),
+    };
+  }
+
+  async function getInboundUtxos(_descriptors: string[]): Promise<LeatherApiUtxo[]> {
+    return [];
+  }
+
+  async function getOutboundUtxos(_descriptors: string[]): Promise<LeatherApiUtxo[]> {
+    return [];
+  }
+
+  async function getProtectedUtxos(_descriptors: string[]): Promise<LeatherApiUtxo[]> {
+    return [];
+  }
+
+  return {
+    getBtcBalance,
+  };
+}

packages/services/src/balances/bitcoin-balances.utils.ts

@@ -0,0 +1,16 @@
+import { LeatherApiUtxo } from '../infrastructure/api/leather/leather-api.client';
+
+export const uneconomicalSatThreshold = 10000;
+
+export function hasUneconomicalBalance(utxo: LeatherApiUtxo) {
+  return Number(utxo.value) < uneconomicalSatThreshold;
+}
+
+export function removeExistingUtxos(
+  candidateUtxos: LeatherApiUtxo[],
+  existingUtxos: LeatherApiUtxo[]
+) {
+  const existingUtxoIds = new Set(existingUtxos.map(utxo => `${utxo.txid}:${utxo.vout}`));
+
+  return candidateUtxos.filter(utxo => !existingUtxoIds.has(`${utxo.txid}:${utxo.vout}`));
+}

packages/services/src/index.ts

@@ -2,6 +2,7 @@ export * from './inversify.config';
 export * from './infrastructure/settings/network-settings.service';
 export * from './infrastructure/api/alex-sdk/alex-sdk.client';
 export * from './infrastructure/api/coingecko/coingecko-api.client';
-export * from './market-data/market-data.service';
 export * from './infrastructure/cache/http-cache.service';
 export * from './infrastructure/cache/http-cache.utils';
+export * from './market-data/market-data.service';
+export * from './balances/bitcoin-balances.service';