chore: deprecate replaced v1 address endpoints

src/api/routes/address.ts

@@ -95,9 +95,8 @@ export const AddressRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_account_stx_balance',
         summary: 'Get account STX balance',
-        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.`,
+        description:
+          'Retrieves STX token balance for a given Address or Contract Identifier. **This endpoint is deprecated in favor of `get_principal_stx_balance`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -166,9 +165,8 @@ 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 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.`,
+        description:
+          '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. **This endpoint is deprecated in favor of `get_principal_ft_balances`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -274,11 +272,8 @@ export const AddressRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_account_transactions',
         summary: 'Get account transactions',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get address transactions](/api/get-address-transactions).
-
-        Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/transactions/how-transactions-work#types).
-
-        If you need to actively monitor new transactions for an address or contract id, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.`,
+        description:
+          'Retrieves a list of all Transactions for a given Address or Contract Identifier. **This endpoint is deprecated in favor of `get_address_transactions`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -349,9 +344,8 @@ export const AddressRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_single_transaction_with_transfers',
         summary: 'Get account transaction information for specific transaction',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get events for an address transaction](/api/get-address-transaction-events).
-
-        Retrieves transaction details for a given Transaction Id \`tx_id\`, for a given account or contract Identifier.`,
+        description:
+          'Retrieves transaction details for a given Transaction Id, for a given account or contract Identifier. **This endpoint is deprecated in favor of `get_address_transaction_events`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -416,7 +410,8 @@ export const AddressRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_account_transactions_with_transfers',
         summary: 'Get account transactions including STX transfers for each transaction.',
-        description: `Retrieve all transactions for an account or contract identifier including STX transfers for each transaction.`,
+        description:
+          'Retrieve all transactions for an account or contract identifier including STX transfers for each transaction. **This endpoint is deprecated in favor of `get_address_transactions`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -526,9 +521,11 @@ export const AddressRoutes: FastifyPluginAsync<
     {
       preHandler: handlePrincipalCache,
       schema: {
+        deprecated: true,
         operationId: 'get_account_assets',
         summary: 'Get account assets',
-        description: `Retrieves a list of all assets events associated with an account or a Contract Identifier. This includes Transfers, Mints.`,
+        description:
+          'Retrieves a list of all assets events associated with an account or a Contract Identifier. This includes Transfers, Mints. **This endpoint is deprecated in favor of `get_address_transaction_events`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,
@@ -574,10 +571,11 @@ export const AddressRoutes: FastifyPluginAsync<
     {
       preHandler: handlePrincipalCache,
       schema: {
+        deprecated: true,
         operationId: 'get_account_inbound',
         summary: 'Get inbound STX transfers',
-        description: `Retrieves a list of STX transfers with memos to the given principal. This includes regular transfers from a stx-transfer transaction type,
-        and transfers from contract-call transactions a the \`send-many-memo\` bulk sending contract.`,
+        description:
+          'Retrieves a list of STX transfers with memos to the given principal. This includes regular transfers from a stx-transfer transaction type, and transfers from contract-call transactions a the `send-many-memo` bulk sending contract. **This endpoint is deprecated in favor of `get_address_transactions`.**',
         tags: ['Accounts'],
         params: Type.Object({
           principal: PrincipalSchema,

src/api/routes/block.ts

@@ -25,11 +25,8 @@ export const BlockRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_block_list',
         summary: 'Get recent blocks',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks).
-
-          Retrieves a list of recently mined blocks
-
-          If you need to actively monitor new blocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.`,
+        description:
+          'Retrieves a list of recently mined blocks. **This endpoint is deprecated in favor of `get_blocks`.**',
         tags: ['Blocks'],
         querystring: Type.Object({
           limit: LimitParam(ResourceType.Block, 'Limit', 'max number of blocks to fetch'),
@@ -61,9 +58,8 @@ export const BlockRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_block_by_height',
         summary: 'Get block by height',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get block](/api/get-block).
-
-        Retrieves block details of a specific block at a given block height`,
+        description:
+          'Retrieves block details of a specific block at a given block height. **This endpoint is deprecated in favor of `get_block`.**',
         tags: ['Blocks'],
         params: Type.Object({
           height: Type.Integer({
@@ -95,9 +91,8 @@ export const BlockRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_block_by_burn_block_height',
         summary: 'Get block by burnchain height',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks).
-
-        Retrieves block details of a specific block for a given burn chain height`,
+        description:
+          'Retrieves block details of a specific block for a given burn chain height. **This endpoint is deprecated in favor of `get_blocks_by_burn_block`.**',
         tags: ['Blocks'],
         params: Type.Object({
           burn_block_height: Type.Integer({
@@ -132,9 +127,8 @@ export const BlockRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_block_by_hash',
         summary: 'Get block by hash',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get block](/api/get-block).
-
-        Retrieves block details of a specific block for a given chain height. You can use the hash from your latest block ('get_block_list' API) to get your block details.`,
+        description:
+          'Retrieves block details of a specific block for a given chain height. **This endpoint is deprecated in favor of `get_block`.**',
         tags: ['Blocks'],
         params: Type.Object({
           hash: Type.String({
@@ -172,9 +166,8 @@ export const BlockRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_block_by_burn_block_hash',
         summary: 'Get block by burnchain block hash',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks).
-
-        Retrieves block details of a specific block for a given burnchain block hash`,
+        description:
+          'Retrieves block details of a specific block for a given burnchain block hash. **This endpoint is deprecated in favor of `get_blocks_by_burn_block`.**',
         tags: ['Blocks'],
         params: Type.Object({
           burn_block_hash: Type.String({

src/api/routes/stx-supply.ts

@@ -122,7 +122,8 @@ export const StxSupplyRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_stx_supply_total_supply_plain',
         summary: 'Get total STX supply in plain text format',
-        description: `Retrieves the total circulating STX token supply as plain text.`,
+        description:
+          'Retrieves the total circulating STX token supply as plain text. **This endpoint is deprecated in favor of `get_stx_supply`.**',
         tags: ['Info'],
         response: {
           200: {
@@ -149,7 +150,8 @@ export const StxSupplyRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_stx_supply_circulating_plain',
         summary: 'Get circulating STX supply in plain text format',
-        description: `Retrieves the STX tokens currently in circulation that have been unlocked as plain text.`,
+        description:
+          'Retrieves the STX tokens currently in circulation that have been unlocked as plain text. **This endpoint is deprecated in favor of `get_stx_supply`.**',
         tags: ['Info'],
         response: {
           200: {
@@ -177,7 +179,8 @@ export const StxSupplyRoutes: FastifyPluginAsync<
         operationId: 'get_total_stx_supply_legacy_format',
         summary:
           'Get total and unlocked STX supply (results formatted the same as the legacy 1.0 API)',
-        description: `Retrieves total supply of STX tokens including those currently in circulation that have been unlocked.`,
+        description:
+          'Retrieves total supply of STX tokens including those currently in circulation that have been unlocked. **This endpoint is deprecated in favor of `get_stx_supply`.**',
         tags: ['Info'],
         querystring: Type.Object({
           height: Type.Optional(

src/api/routes/tx.ts

@@ -579,9 +579,8 @@ export const TxRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_transactions_by_block_hash',
         summary: 'Transactions by block hash',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get transactions by block](/api/get-transactions-by-block).
-
-        Retrieves a list of all transactions within a block for a given block hash.`,
+        description:
+          'Retrieves a list of all transactions within a block for a given block hash. **This endpoint is deprecated in favor of `get_transactions_by_block`.**',
         tags: ['Transactions'],
         params: Type.Object({
           block_hash: Type.String(),
@@ -627,9 +626,8 @@ export const TxRoutes: FastifyPluginAsync<
         deprecated: true,
         operationId: 'get_transactions_by_block_height',
         summary: 'Transactions by block height',
-        description: `**NOTE:** This endpoint is deprecated in favor of [Get transactions by block](/api/get-transactions-by-block).
-
-        Retrieves all transactions within a block at a given height`,
+        description:
+          'Retrieves all transactions within a block at a given height. **This endpoint is deprecated in favor of `get_transactions_by_block`.**',
         tags: ['Transactions'],
         params: Type.Object({
           height: BlockHeightSchema,

src/api/routes/v2/addresses.ts

@@ -148,8 +148,7 @@ export const AddressRoutesV2: FastifyPluginAsync<
     '/:principal/balances/stx',
     {
       preHandler: (req, reply) => {
-        // TODO: use `ETagType.principal` instead of chaintip cache type when it's optimized
-        const etagType = req.query.include_mempool ? ETagType.principalMempool : ETagType.chainTip;
+        const etagType = req.query.include_mempool ? ETagType.principalMempool : ETagType.principal;
         return handleCache(etagType, req, reply);
       },
       schema: {
@@ -232,7 +231,7 @@ export const AddressRoutesV2: FastifyPluginAsync<
   fastify.get(
     '/:principal/balances/ft',
     {
-      preHandler: handleChainTipCache, // TODO: use handlePrincipalCache once it's optimized
+      preHandler: handlePrincipalCache,
       schema: {
         operationId: 'get_principal_ft_balances',
         summary: 'Get principal FT balances',
@@ -284,7 +283,7 @@ export const AddressRoutesV2: FastifyPluginAsync<
   fastify.get(
     '/:principal/balances/ft/:token',
     {
-      preHandler: handleChainTipCache, // TODO: use handlePrincipalCache once it's optimized
+      preHandler: handlePrincipalCache,
       schema: {
         operationId: 'get_principal_ft_balance',
         summary: 'Get principal FT balance',

src/api/schemas/openapi.ts

@@ -5,9 +5,7 @@ export const OpenApiSchemaOptions: SwaggerOptions = {
   openapi: {
     info: {
       title: 'Stacks Blockchain API',
-      description: `Welcome to the API reference overview for the [Stacks Blockchain API](https://docs.hiro.so/stacks-blockchain-api).
-
-      [Download Postman collection](https://hirosystems.github.io/stacks-blockchain-api/collection.json)`,
+      description: `Welcome to the API reference overview for the [Stacks Blockchain API](https://docs.hiro.so/stacks-blockchain-api). [Download Postman collection](https://hirosystems.github.io/stacks-blockchain-api/collection.json).`,
       version: SERVER_VERSION.tag,
     },
     externalDocs: {