feat: separate /balances/ft endpoint

Author: zone117x

src/api/controllers/cache-controller.ts

@@ -15,7 +15,7 @@ import { BlockParams } from '../routes/v2/schemas';
  * state of the chain depending on the type of information being requested by the endpoint.
  * This entry will have an `ETag` string as the value.
  */
-enum ETagType {
+export enum ETagType {
   /** ETag based on the latest `index_block_hash` or `microblock_hash`. */
   chainTip = 'chain_tip',
   /** ETag based on a digest of all pending mempool `tx_id`s. */
@@ -149,7 +149,7 @@ async function calculateETag(
   }
 }
 
-async function handleCache(type: ETagType, request: FastifyRequest, reply: FastifyReply) {
+export async function handleCache(type: ETagType, request: FastifyRequest, reply: FastifyReply) {
   const metrics = getETagMetrics();
   const ifNoneMatch = parseIfNoneMatchHeader(request.headers['if-none-match']);
   const etag = await calculateETag(request.server.db, type, request);

src/api/pagination.ts

@@ -40,6 +40,7 @@ export enum ResourceType {
   PoxCycle,
   TokenHolders,
   BlockSignerSignature,
+  FtBalance,
 }
 
 export const pagingQueryLimits: Record<ResourceType, { defaultLimit: number; maxLimit: number }> = {
@@ -99,6 +100,10 @@ export const pagingQueryLimits: Record<ResourceType, { defaultLimit: number; max
     defaultLimit: 500,
     maxLimit: 1000,
   },
+  [ResourceType.FtBalance]: {
+    defaultLimit: 100,
+    maxLimit: 200,
+  },
 };
 
 export function getPagingQueryLimit(

src/api/routes/address.ts

@@ -91,9 +91,12 @@ export const AddressRoutes: FastifyPluginAsync<
     {
       preHandler: handlePrincipalMempoolCache,
       schema: {
+        deprecated: true,
         operationId: 'get_account_stx_balance',
         summary: 'Get account STX balance',
-        description: `Retrieves STX token balance for a given Address or Contract Identifier.`,
+        description: `**NOTE:** This endpoint is deprecated in favor of [Get address STX balance](/api/get-principal-stx-balance).
+        
+        Retrieves STX token balance for a given Address or Contract Identifier.`,
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -162,7 +165,7 @@ export const AddressRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_account_balance',
         summary: 'Get account balances',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get address transactions](/api/get-principal-balances).
+        description: `**NOTE:** This endpoint is deprecated in favor of [Get address FT balances](/api/get-principal-ft-balances).
         
         Retrieves total account balance information for a given Address or Contract Identifier. This includes the balances of STX Tokens, Fungible Tokens and Non-Fungible Tokens for the account.`,
         tags: ['Accounts'],

src/api/routes/v2/addresses.ts

@@ -1,4 +1,6 @@
 import {
+  ETagType,
+  handleCache,
   handlePrincipalCache,
   handlePrincipalMempoolCache,
   handleTransactionCache,
@@ -13,17 +15,15 @@ import { LimitParam, OffsetParam, PrincipalSchema } from '../../schemas/params';
 import { getPagingQueryLimit, ResourceType } from '../../pagination';
 import { PaginatedResponse } from '../../schemas/util';
 import {
-  AddressBalance,
-  AddressBalanceSchema,
-  AddressBalanceV2,
-  AddressBalanceV2Schema,
   AddressTransaction,
   AddressTransactionEvent,
   AddressTransactionEventSchema,
   AddressTransactionSchema,
+  PrincipalFtBalance,
+  PrincipalFtBalanceSchema,
 } from '../../schemas/entities/addresses';
-import { formatMapToObject } from '../../../helpers';
 import { validatePrincipal } from '../../query-helpers';
+import { StxBalance, StxBalanceSchema } from '../../schemas/entities/balances';
 
 export const AddressRoutesV2: FastifyPluginAsync<
   Record<never, never>,
@@ -125,21 +125,31 @@ export const AddressRoutesV2: FastifyPluginAsync<
     }
   );
 
-  // get balances for STX, FTs, and counts for NFTs
   fastify.get(
-    '/:principal/balances',
+    '/:principal/balances/stx',
     {
-      preHandler: handlePrincipalMempoolCache,
+      preHandler: (req, reply) => {
+        const etagType = req.query.include_mempool ? ETagType.principalMempool : ETagType.principal;
+        return handleCache(etagType, req, reply);
+      },
       schema: {
-        operationId: 'get_principal_balances',
-        summary: 'Get principal balances',
-        description: `Retrieves total account balance information for a given Address or Contract Identifier. This includes the balances of STX Tokens and Fungible Tokens for the account.`,
+        operationId: 'get_principal_stx_balance',
+        summary: 'Get principal STX balance',
+        description: `Retrieves STX account balance information for a given Address or Contract Identifier.`,
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
         }),
+        querystring: Type.Object({
+          include_mempool: Type.Optional(
+            Type.Boolean({
+              description: 'Include pending mempool transactions in the balance calculation',
+              default: false,
+            })
+          ),
+        }),
         response: {
-          200: AddressBalanceV2Schema,
+          200: StxBalanceSchema,
         },
       },
     },
@@ -150,21 +160,12 @@ export const AddressRoutesV2: FastifyPluginAsync<
       const result = await fastify.db.sqlTransaction(async sql => {
         const chainTip = await fastify.db.getChainTip(sql);
 
-        // Get balances for fungible tokens
-        const ftBalancesResult = await fastify.db.v2.getFungibleTokenHolderBalances({
+        // Get stx balance (sum of credits, debits, and fees) for address
+        const stxBalancesResult = await fastify.db.v2.getStxHolderBalance({
           sql,
           stxAddress,
         });
-        const ftBalances: Record<string, string> = {};
-        for (const { token, balance } of ftBalancesResult) {
-          if (token !== 'stx') {
-            ftBalances[token] = balance;
-          }
-        }
-
-        // Get stx balance (sum of credits, debits, and fees) for address
-        const stxBalanceResult = ftBalancesResult.find(entry => entry.token === 'stx');
-        let stxBalance = BigInt(stxBalanceResult?.balance ?? '0');
+        let stxBalance = stxBalancesResult.found ? stxBalancesResult.result.balance : 0n;
 
         // Get pox-locked info for STX token
         const stxPoxLockedResult = await fastify.db.v2.getStxPoxLockedAtBlock({
@@ -182,23 +183,78 @@ export const AddressRoutesV2: FastifyPluginAsync<
         });
         stxBalance += totalMinerRewardsReceived;
 
-        const mempoolResult = await fastify.db.getPrincipalMempoolStxBalanceDelta(sql, stxAddress);
-        const mempoolBalance: bigint = stxBalance + mempoolResult.delta;
+        const result: StxBalance = {
+          balance: stxBalance.toString(),
+          total_miner_rewards_received: totalMinerRewardsReceived.toString(),
+          lock_tx_id: stxPoxLockedResult.lockTxId,
+          locked: stxPoxLockedResult.locked.toString(),
+          lock_height: stxPoxLockedResult.lockHeight,
+          burnchain_lock_height: stxPoxLockedResult.burnchainLockHeight,
+          burnchain_unlock_height: stxPoxLockedResult.burnchainUnlockHeight,
+        };
+
+        if (req.query.include_mempool) {
+          const mempoolResult = await fastify.db.getPrincipalMempoolStxBalanceDelta(
+            sql,
+            stxAddress
+          );
+          const mempoolBalance = stxBalance + mempoolResult.delta;
+          result.estimated_balance = mempoolBalance.toString();
+          result.pending_balance_inbound = mempoolResult.inbound.toString();
+          result.pending_balance_outbound = mempoolResult.outbound.toString();
+        }
+
+        return result;
+      });
+      await reply.send(result);
+    }
+  );
 
-        const result: AddressBalanceV2 = {
-          stx: {
-            balance: stxBalance.toString(),
-            estimated_balance: mempoolBalance.toString(),
-            pending_balance_inbound: mempoolResult.inbound.toString(),
-            pending_balance_outbound: mempoolResult.outbound.toString(),
-            total_miner_rewards_received: totalMinerRewardsReceived.toString(),
-            lock_tx_id: stxPoxLockedResult.lockTxId,
-            locked: stxPoxLockedResult.locked.toString(),
-            lock_height: stxPoxLockedResult.lockHeight,
-            burnchain_lock_height: stxPoxLockedResult.burnchainLockHeight,
-            burnchain_unlock_height: stxPoxLockedResult.burnchainUnlockHeight,
-          },
-          fungible_tokens: ftBalances,
+  fastify.get(
+    '/:principal/balances/ft',
+    {
+      preHandler: handlePrincipalMempoolCache,
+      schema: {
+        operationId: 'get_principal_ft_balances',
+        summary: 'Get principal FT balances',
+        description: `Retrieves Fungible-token account balance information for a given Address or Contract Identifier.`,
+        tags: ['Accounts'],
+        params: Type.Object({
+          principal: PrincipalSchema,
+        }),
+        querystring: Type.Object({
+          limit: LimitParam(ResourceType.FtBalance),
+          offset: OffsetParam(),
+        }),
+        response: {
+          200: PaginatedResponse(PrincipalFtBalanceSchema),
+        },
+      },
+    },
+    async (req, reply) => {
+      const stxAddress = req.params.principal;
+      validatePrincipal(stxAddress);
+      const limit = getPagingQueryLimit(ResourceType.FtBalance, req.query.limit);
+      const offset = req.query.offset ?? 0;
+      const result = await fastify.db.sqlTransaction(async sql => {
+        // Get balances for fungible tokens
+        const ftBalancesResult = await fastify.db.v2.getFungibleTokenHolderBalances({
+          sql,
+          stxAddress,
+          limit,
+          offset,
+        });
+        const ftBalances: PrincipalFtBalance[] = ftBalancesResult.results.map(
+          ({ token, balance }) => ({
+            token,
+            balance,
+          })
+        );
+        const result = {
+          limit,
+          offset,
+          total: ftBalancesResult.total,
+          results: ftBalances,
         };
         return result;
       });

src/api/schemas/entities/addresses.ts

@@ -2,12 +2,7 @@ import { Static, Type } from '@sinclair/typebox';
 import { TransactionSchema } from './transactions';
 import { TransactionEventAssetTypeSchema } from './transaction-events';
 import { Nullable } from '../util';
-import {
-  FtBalanceSchema,
-  NftBalanceSchema,
-  StxBalanceSchema,
-  StxBalanceV2Schema,
-} from './balances';
+import { FtBalanceSchema, NftBalanceSchema, StxBalanceSchema } from './balances';
 
 export const AddressNoncesSchema = Type.Object(
   {
@@ -272,17 +267,11 @@ export const AddressBalanceSchema = Type.Object(
 );
 export type AddressBalance = Static<typeof AddressBalanceSchema>;
 
-export const AddressBalanceV2Schema = Type.Object(
-  {
-    stx: StxBalanceV2Schema,
-    fungible_tokens: Type.Record(
-      Type.String({ description: 'token' }),
-      Type.String({ description: 'balance' })
-    ),
-  },
-  { title: 'AddressBalanceResponseV2', description: 'GET request that returns address balances' }
-);
-export type AddressBalanceV2 = Static<typeof AddressBalanceV2Schema>;
+export const PrincipalFtBalanceSchema = Type.Object({
+  token: Type.String(),
+  balance: Type.String(),
+});
+export type PrincipalFtBalance = Static<typeof PrincipalFtBalanceSchema>;
 
 enum InboundStxTransferType {
   bulkSend = 'bulk-send',

src/api/schemas/entities/balances.ts

@@ -36,9 +36,9 @@ export const StxBalanceSchema = Type.Object(
         description: 'Outbound STX balance from pending mempool transactions',
       })
     ),
-    total_sent: Type.String(),
-    total_received: Type.String(),
-    total_fees_sent: Type.String(),
+    total_sent: Type.Optional(Type.String()),
+    total_received: Type.Optional(Type.String()),
+    total_fees_sent: Type.Optional(Type.String()),
     total_miner_rewards_received: Type.String(),
     lock_tx_id: Type.String({
       description: 'The transaction where the lock event occurred. Empty if no tokens are locked.',
@@ -62,39 +62,4 @@ export const StxBalanceSchema = Type.Object(
   },
   { title: 'StxBalance' }
 );
-
-export const StxBalanceV2Schema = Type.Object(
-  {
-    balance: Type.String(),
-    estimated_balance: Type.String({
-      description: 'Total STX balance considering pending mempool transactions',
-    }),
-    pending_balance_inbound: Type.String({
-      description: 'Inbound STX balance from pending mempool transactions',
-    }),
-    pending_balance_outbound: Type.String({
-      description: 'Outbound STX balance from pending mempool transactions',
-    }),
-    total_miner_rewards_received: Type.String(),
-    lock_tx_id: Type.String({
-      description: 'The transaction where the lock event occurred. Empty if no tokens are locked.',
-    }),
-    locked: Type.String({
-      description:
-        'The amount of locked STX, as string quoted micro-STX. Zero if no tokens are locked.',
-    }),
-    lock_height: Type.Integer({
-      description:
-        'The STX chain block height of when the lock event occurred. Zero if no tokens are locked.',
-    }),
-    burnchain_lock_height: Type.Integer({
-      description:
-        'The burnchain block height of when the lock event occurred. Zero if no tokens are locked.',
-    }),
-    burnchain_unlock_height: Type.Integer({
-      description:
-        'The burnchain block height of when the tokens unlock. Zero if no tokens are locked.',
-    }),
-  },
-  { title: 'StxBalanceV2' }
-);
+export type StxBalance = Static<typeof StxBalanceSchema>;