feat: create /extended/v2/burn-blocks/:height_or_hash/blocks endpoint (#1782)

* chore: move to v2 pg submodule

* fix: move blocks per burn block endpoint

* docs: openapi

* docs: endpoint name

Author: rafaelcr

docs/openapi.yaml

@@ -21,6 +21,8 @@ tags:
       url: https://docs.stacks.co/understand-stacks/accounts
   - name: Blocks
     description: Read-only endpoints to obtain Stacks block details
+  - name: Burn Blocks
+    description: Read-only endpoints to obtain burn block details
   - name: Faucets
     description: Endpoints to request STX or BTC tokens (not possible on Mainnet)
   - name: Fees
@@ -613,7 +615,7 @@ paths:
       description: |
           Retrieves a list of recent burn blocks
       tags:
-        - Blocks
+        - Burn Blocks
       operationId: get_burn_blocks
       parameters:
         - name: limit
@@ -646,7 +648,7 @@ paths:
       summary: Get burn block
       description: Retrieves a single burn block
       tags:
-        - Blocks
+        - Burn Blocks
       operationId: get_burn_block
       parameters:
         - name: height_or_hash
@@ -668,16 +670,26 @@ paths:
                 $ref: ./entities/blocks/burn-block.schema.json
               example:
                 $ref: ./entities/blocks/burn-block.example.json
-
-  /extended/v2/blocks:
+  
+  /extended/v2/burn-blocks/{height_or_hash}/blocks:
     get:
-      summary: Get blocks
+      summary: Get blocks by burn block
       description: |
-        Retrieves a list of recently mined blocks
+        Retrieves a list of blocks confirmed by a specific burn block
       tags:
         - Blocks
-      operationId: get_blocks
+      operationId: get_blocks_by_burn_block
       parameters:
+        - name: height_or_hash
+          in: path
+          description: filter by burn block height, hash, or the constant `latest` to filter for the most recent burn block
+          required: true
+          schema:
+            oneOf:
+              - type: integer
+                example: 42000
+              - type: string
+                example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79"
         - name: limit
           in: query
           description: max number of blocks to fetch
@@ -692,20 +704,39 @@ paths:
           schema:
             type: integer
             example: 0
-        - name: burn_block_hash
+      responses:
+        200:
+          description: List of blocks
+          content:
+            application/json:
+              schema:
+                $ref: ./api/blocks/get-nakamoto-blocks.schema.json
+              example:
+                $ref: ./api/blocks/get-nakamoto-blocks.example.json
+
+  /extended/v2/blocks:
+    get:
+      summary: Get blocks
+      description: |
+        Retrieves a list of recently mined blocks
+      tags:
+        - Blocks
+      operationId: get_blocks
+      parameters:
+        - name: limit
           in: query
-          description: filter blocks by burn block hash
+          description: max number of blocks to fetch
           required: false
           schema:
-            type: string
-            example: "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2"
-        - name: burn_block_height
+            type: integer
+            example: 20
+        - name: offset
           in: query
-          description: filter blocks by burn block height
+          description: index of first burn block to fetch
           required: false
           schema:
             type: integer
-            example: 810344
+            example: 0
       responses:
         200:
           description: List of blocks
@@ -747,12 +778,12 @@ paths:
 
   /extended/v2/blocks/{height_or_hash}/transactions:
     get:
-      summary: Get block transactions
+      summary: Get transactions by block
       description: |
         Retrieves transactions confirmed in a single block
       tags:
-        - Blocks
-      operationId: get_block_transactions
+        - Transactions
+      operationId: get_transactions_by_block
       parameters:
         - name: height_or_hash
           in: path
@@ -2913,77 +2944,15 @@ paths:
               example:
                 $ref: ./api/bns/errors/bns-unsupported-blockchain.example.json
 
-#  /v1/subdomains:
-#    get:
-#      summary: Get All Subdomains
-#      description: Retrieves a list of all subdomains known to the node.
-#      tags:
-#        - Names
-#      operationId: get_all_subdomains
-#      parameters:
-#        - name: page
-#          in: query
-#          description: names are returned in pages of size 100, so specify the page number.
-#          required: true
-#          example: 3
-#          schema:
-#            type: integer
-#      responses:
-#        200:
-#          description: Success
-#          content:
-#            application/json:
-#              schema:
-#                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.schema.json
-#              example:
-#                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.example.json
-#        400:
-#          description: Error
-#          content:
-#            application/json:
-#              schema:
-#                $ref: ./api/bns/errors/bns-error.schema.json
-#              example:
-#                $ref: ./api/bns/errors/bns-invalid-page.example.json
-#
-#  /v1/subdomains/{txid}:
-#    get:
-#      summary: Get Subdomain at Transaction
-#      description: Retrieves the list of subdomain operations processed by a given transaction. The returned array includes subdomain operations that have not yet been accepted as part of any subdomain’s history (checkable via the accepted field). If the given transaction ID does not correspond to a Stacks transaction that introduced new subdomain operations, and empty array will be returned.
-#      tags:
-#        - Names
-#      operationId: get_subdomain_at_transaction
-#      parameters:
-#        - name: txid
-#          in: path
-#          description: transaction id
-#          required: true
-#          schema:
-#            type: string
-#            example: "d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe"
-#      responses:
-#        200:
-#          description: Success
-#          content:
-#            application/json:
-#              schema:
-#                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.schema.json
-#              example:
-#                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.example.json
-#        400:
-#          description: Error
-#          content:
-#            application/json:
-#              schema:
-#                $ref: ./api/bns/errors/bns-error.schema.json
-#              example:
-#                $ref: ./api/bns/errors/bns-invalid-tx-id.example.json
-
   /extended/v1/tx/block/{block_hash}:
     get:
+      deprecated: true
       operationId: get_transactions_by_block_hash
       summary: Transactions by block hash
-      description: Retrieves a list of all transactions within a block for a given block hash.
+      description: |
+        **NOTE:** This endpoint is deprecated in favor of [Get transactions by block](#operation/get_transactions_by_block).
+
+        Retrieves a list of all transactions within a block for a given block hash.
       tags:
         - Transactions
       parameters:
@@ -3020,9 +2989,13 @@ paths:
 
   /extended/v1/tx/block_height/{height}:
     get:
+      deprecated: true
       operationId: get_transactions_by_block_height
       summary: Transactions by block height
-      description: Retrieves all transactions within a block at a given height
+      description: |
+        **NOTE:** This endpoint is deprecated in favor of [Get transactions by block](#operation/get_transactions_by_block).
+
+        Retrieves all transactions within a block at a given height
       tags:
         - Transactions
       parameters:

src/api/controllers/db-controller.ts

@@ -68,7 +68,6 @@ import { getOperations, parseTransactionMemo } from '../../rosetta/rosetta-helpe
 import { PgStore } from '../../datastore/pg-store';
 import { SyntheticPoxEventName } from '../../pox-helpers';
 import { logger } from '../../logger';
-import { BlocksQueryParams } from '../routes/v2/schemas';
 
 export function parseTxTypeStrings(values: string[]): TransactionType[] {
   return values.map(v => {

src/api/routes/v2/blocks.ts

@@ -7,14 +7,14 @@ import {
 import { asyncHandler } from '../../async-handler';
 import { NakamotoBlockListResponse, TransactionResults } from 'docs/generated';
 import {
-  BlocksQueryParams,
   BlockParams,
-  CompiledBlocksQueryParams,
   CompiledBlockParams,
   CompiledTransactionPaginationQueryParams,
   TransactionPaginationQueryParams,
   validRequestQuery,
   validRequestParams,
+  CompiledBlockPaginationQueryParams,
+  BlockPaginationQueryParams,
 } from './schemas';
 import { parseDbNakamotoBlock } from './helpers';
 import { InvalidRequestError } from '../../../errors';
@@ -28,10 +28,10 @@ export function createV2BlocksRouter(db: PgStore): express.Router {
     '/',
     cacheHandler,
     asyncHandler(async (req, res) => {
-      if (!validRequestQuery(req, res, CompiledBlocksQueryParams)) return;
-      const query = req.query as BlocksQueryParams;
+      if (!validRequestQuery(req, res, CompiledBlockPaginationQueryParams)) return;
+      const query = req.query as BlockPaginationQueryParams;
 
-      const { limit, offset, results, total } = await db.getV2Blocks(query);
+      const { limit, offset, results, total } = await db.v2.getBlocks(query);
       const response: NakamotoBlockListResponse = {
         limit,
         offset,
@@ -50,7 +50,7 @@ export function createV2BlocksRouter(db: PgStore): express.Router {
       if (!validRequestParams(req, res, CompiledBlockParams)) return;
       const params = req.params as BlockParams;
 
-      const block = await db.getV2Block(params);
+      const block = await db.v2.getBlock(params);
       if (!block) {
         res.status(404).json({ errors: 'Not found' });
         return;
@@ -73,7 +73,7 @@ export function createV2BlocksRouter(db: PgStore): express.Router {
       const query = req.query as TransactionPaginationQueryParams;
 
       try {
-        const { limit, offset, results, total } = await db.getV2BlockTransactions({
+        const { limit, offset, results, total } = await db.v2.getBlockTransactions({
           ...params,
           ...query,
         });

src/api/routes/v2/burn-blocks.ts

@@ -1,9 +1,12 @@
 import * as express from 'express';
-import { BurnBlockListResponse } from '@stacks/stacks-blockchain-api-types';
+import {
+  BurnBlockListResponse,
+  NakamotoBlockListResponse,
+} from '@stacks/stacks-blockchain-api-types';
 import { getETagCacheHandler, setETagCacheHeaders } from '../../controllers/cache-controller';
 import { asyncHandler } from '../../async-handler';
 import { PgStore } from '../../../datastore/pg-store';
-import { parseDbBurnBlock } from './helpers';
+import { parseDbBurnBlock, parseDbNakamotoBlock } from './helpers';
 import {
   BlockPaginationQueryParams,
   BlockParams,
@@ -12,6 +15,7 @@ import {
   validRequestParams,
   validRequestQuery,
 } from './schemas';
+import { InvalidRequestError } from '../../../errors';
 
 export function createV2BurnBlocksRouter(db: PgStore): express.Router {
   const router = express.Router();
@@ -24,7 +28,7 @@ export function createV2BurnBlocksRouter(db: PgStore): express.Router {
       if (!validRequestQuery(req, res, CompiledBlockPaginationQueryParams)) return;
       const query = req.query as BlockPaginationQueryParams;
 
-      const { limit, offset, results, total } = await db.getBurnBlocks(query);
+      const { limit, offset, results, total } = await db.v2.getBurnBlocks(query);
       const response: BurnBlockListResponse = {
         limit,
         offset,
@@ -43,7 +47,7 @@ export function createV2BurnBlocksRouter(db: PgStore): express.Router {
       if (!validRequestParams(req, res, CompiledBlockParams)) return;
       const params = req.params as BlockParams;
 
-      const block = await db.getBurnBlock(params);
+      const block = await db.v2.getBurnBlock(params);
       if (!block) {
         res.status(404).json({ errors: 'Not found' });
         return;
@@ -53,5 +57,40 @@ export function createV2BurnBlocksRouter(db: PgStore): express.Router {
     })
   );
 
+  router.get(
+    '/:height_or_hash/blocks',
+    cacheHandler,
+    asyncHandler(async (req, res) => {
+      if (
+        !validRequestParams(req, res, CompiledBlockParams) ||
+        !validRequestQuery(req, res, CompiledBlockPaginationQueryParams)
+      )
+        return;
+      const params = req.params as BlockParams;
+      const query = req.query as BlockPaginationQueryParams;
+
+      try {
+        const { limit, offset, results, total } = await db.v2.getBlocksByBurnBlock({
+          ...params,
+          ...query,
+        });
+        const response: NakamotoBlockListResponse = {
+          limit,
+          offset,
+          total,
+          results: results.map(r => parseDbNakamotoBlock(r)),
+        };
+        setETagCacheHeaders(res);
+        res.json(response);
+      } catch (error) {
+        if (error instanceof InvalidRequestError) {
+          res.status(404).json({ errors: error.message });
+          return;
+        }
+        throw error;
+      }
+    })
+  );
+
   return router;
 }

src/api/routes/v2/schemas.ts

@@ -113,30 +113,6 @@ export const CompiledTransactionPaginationQueryParams = ajv.compile(
   TransactionPaginationQueryParamsSchema
 );
 
-const BlocksQueryParamsSchema = Type.Union([
-  BlockPaginationQueryParamsSchema,
-  Type.Composite(
-    [
-      Type.Object({
-        burn_block_hash: Type.Union([Type.Literal('latest'), BurnBlockHashParamSchema]),
-      }),
-      BlockPaginationQueryParamsSchema,
-    ],
-    { additionalProperties: false }
-  ),
-  Type.Composite(
-    [
-      Type.Object({
-        burn_block_height: Type.Union([Type.Literal('latest'), BurnBlockHeightParamSchema]),
-      }),
-      BlockPaginationQueryParamsSchema,
-    ],
-    { additionalProperties: false }
-  ),
-]);
-export type BlocksQueryParams = Static<typeof BlocksQueryParamsSchema>;
-export const CompiledBlocksQueryParams = ajv.compile(BlocksQueryParamsSchema);
-
 const BlockParamsSchema = Type.Object(
   {
     height_or_hash: Type.Union([