fix: move /extended/v1/burn_block to /extended/v2/burn-blocks (#1772)

* fix: move burn block to v2

* fix: new file

* fix: unused exports

Author: rafaelcr

docs/openapi.yaml

@@ -612,14 +612,14 @@ paths:
               schema:
                 $ref: ./api/microblocks/get-unanchored-txs.schema.json
 
-  /extended/v1/burn_block:
+  /extended/v2/burn-blocks:
     get:
-      summary: Get recent burn blocks
+      summary: Get burn blocks
       description: |
           Retrieves a list of recent burn blocks
       tags:
         - Blocks
-      operationId: get_burn_block_list
+      operationId: get_burn_blocks
       parameters:
         - name: limit
           in: query
@@ -636,20 +636,6 @@ paths:
           schema:
             type: integer
             example: 42000
-        - name: height
-          in: query
-          description: filter by burn block height
-          required: false
-          schema:
-            type: integer
-            example: 42000
-        - name: hash
-          in: query
-          description: filter by burn block hash or the constant 'latest' to filter for the most recent burn block
-          required: false
-          schema:
-            type: string
-            example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79"
       responses:
         200:
           description: List of burn blocks
@@ -660,6 +646,34 @@ paths:
               example:
                 $ref: ./api/blocks/get-burn-blocks.example.json
 
+  /extended/v2/burn-blocks/{height_or_hash}:
+    get:
+      summary: Get burn block
+      description: Retrieves a single burn block
+      tags:
+        - Blocks
+      operationId: get_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"
+      responses:
+        200:
+          description: Burn block
+          content:
+            application/json:
+              schema:
+                $ref: ./entities/blocks/burn-block.schema.json
+              example:
+                $ref: ./entities/blocks/burn-block.example.json
+
   /extended/v2/blocks:
     get:
       summary: Get blocks

src/api/controllers/db-controller.ts

@@ -538,35 +538,6 @@ export async function getMicroblockFromDataStore({
   };
 }
 
-export async function getBurnBlocksFromDataStore(args: {
-  db: PgStore;
-  limit: number;
-  offset: number;
-  height: number | null;
-  hash: 'latest' | string | null;
-}): Promise<{ total: number; results: BurnBlock[] }> {
-  const query = await args.db.getBurnBlocks({
-    limit: args.limit,
-    offset: args.offset,
-    height: args.height,
-    hash: args.hash,
-  });
-  const results = query.results.map(r => {
-    const burnBlock: BurnBlock = {
-      burn_block_time: r.burn_block_time,
-      burn_block_time_iso: unixEpochToIso(r.burn_block_time),
-      burn_block_hash: r.burn_block_hash,
-      burn_block_height: r.burn_block_height,
-      stacks_blocks: r.stacks_blocks,
-    };
-    return burnBlock;
-  });
-  return {
-    total: query.total,
-    results,
-  };
-}
-
 export async function getMicroblocksFromDataStore(args: {
   db: PgStore;
   limit: number;

src/api/init.ts

@@ -45,7 +45,7 @@ import { logger, loggerMiddleware } from '../logger';
 import { SERVER_VERSION, isPgConnectionError, isProdEnv, waiter } from '@hirosystems/api-toolkit';
 import { createV2BlocksRouter } from './routes/v2/blocks';
 import { getReqQuery } from './query-helpers';
-import { createBurnBlockRouter } from './routes/burn-block';
+import { createV2BurnBlocksRouter } from './routes/v2/burn-blocks';
 
 export interface ApiServer {
   expressApp: express.Express;
@@ -199,7 +199,6 @@ export async function startApiServer(opts: {
           v1.use('/status', createStatusRouter(datastore));
           v1.use('/fee_rate', createFeeRateRouter(datastore));
           v1.use('/tokens', createTokenRouter(datastore));
-          v1.use('/burn_block', createBurnBlockRouter(datastore));
 
           // These could be defined in one route but a url reporting library breaks with regex in middleware paths
           v1.use('/pox2', createPoxEventsRouter(datastore, 'pox2'));
@@ -227,6 +226,7 @@ export async function startApiServer(opts: {
         (() => {
           const v2 = express.Router();
           v2.use('/blocks', createV2BlocksRouter(datastore));
+          v2.use('/burn-blocks', createV2BurnBlocksRouter(datastore));
           return v2;
         })()
       );

src/api/query-helpers.ts

@@ -111,53 +111,6 @@ export function getBlockParams(
   }
 }
 
-/**
- * Parses a block hash value from a given request query param.
- * If an error is encountered while parsing the param then a 400 response with an error message is sent and the function throws.
- * @param queryParamName - name of the query param
- * @param paramRequired - if true then the function will throw and return a 400 if the param is missing, if false then the function will return null if the param is missing
- */
-export function getBlockHashQueryParam<TRequired extends boolean>(
-  queryParamName: string,
-  paramRequired: TRequired,
-  req: Request,
-  res: Response,
-  next: NextFunction
-): TRequired extends true ? string | never : string | null {
-  if (!(queryParamName in req.query)) {
-    if (paramRequired) {
-      handleBadRequest(
-        res,
-        next,
-        `Request is missing required "${queryParamName}" query parameter`
-      );
-    } else {
-      return null as TRequired extends true ? string : string | null;
-    }
-  }
-  const hashParamVal = req.query[queryParamName];
-  if (typeof hashParamVal !== 'string') {
-    handleBadRequest(
-      res,
-      next,
-      `Unexpected type for block hash query parameter: ${JSON.stringify(hashParamVal)}`
-    );
-  }
-
-  // Extract the hash part, ignoring '0x' if present
-  const match = hashParamVal.match(/^(0x)?([a-fA-F0-9]{64})$/i);
-  if (!match) {
-    handleBadRequest(
-      res,
-      next,
-      "Invalid hash string. Ensure it is 64 hexadecimal characters long, with an optional '0x' prefix"
-    );
-  }
-
-  // Normalize the string
-  return '0x' + match[2].toLowerCase();
-}
-
 /**
  * Parses a block height value from a given request query param.
  * If an error is encountered while parsing the param then a 400 response with an error message is sent and the function throws.

src/api/routes/burn-block.ts

@@ -6,7 +6,7 @@ import {
 } from '../../../api/controllers/cache-controller';
 import { asyncHandler } from '../../async-handler';
 import { NakamotoBlockListResponse } from 'docs/generated';
-import { BlockLimitParam, BlocksQueryParams, CompiledBlocksQueryParams } from './schemas';
+import { BlockLimitParamSchema, BlocksQueryParams, CompiledBlocksQueryParams } from './schemas';
 import { parseDbNakamotoBlock, validRequestQuery } from './helpers';
 
 export function createV2BlocksRouter(db: PgStore): express.Router {
@@ -20,10 +20,10 @@ export function createV2BlocksRouter(db: PgStore): express.Router {
       if (!validRequestQuery(req, res, CompiledBlocksQueryParams)) return;
       const query = req.query as BlocksQueryParams;
 
-      const { results, total } = await db.getV2Blocks(query);
+      const { limit, offset, results, total } = await db.getV2Blocks(query);
       const response: NakamotoBlockListResponse = {
-        limit: query.limit ?? BlockLimitParam.default,
-        offset: query.offset ?? 0,
+        limit,
+        offset,
         total,
         results: results.map(r => parseDbNakamotoBlock(r)),
       };

src/api/routes/v2/blocks.ts

@@ -0,0 +1,55 @@
+import * as express from 'express';
+import { BurnBlockListResponse } 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, validRequestParams, validRequestQuery } from './helpers';
+import {
+  BlockPaginationQueryParams,
+  BurnBlockParams,
+  CompiledBlockPaginationParams,
+  CompiledBurnBlockParams,
+} from './schemas';
+
+export function createV2BurnBlocksRouter(db: PgStore): express.Router {
+  const router = express.Router();
+  const cacheHandler = getETagCacheHandler(db);
+
+  router.get(
+    '/',
+    cacheHandler,
+    asyncHandler(async (req, res) => {
+      if (!validRequestQuery(req, res, CompiledBlockPaginationParams)) return;
+      const query = req.query as BlockPaginationQueryParams;
+
+      const { limit, offset, results, total } = await db.getBurnBlocks(query);
+      const response: BurnBlockListResponse = {
+        limit,
+        offset,
+        total,
+        results: results.map(r => parseDbBurnBlock(r)),
+      };
+      setETagCacheHeaders(res);
+      res.json(response);
+    })
+  );
+
+  router.get(
+    '/:height_or_hash',
+    cacheHandler,
+    asyncHandler(async (req, res) => {
+      if (!validRequestParams(req, res, CompiledBurnBlockParams)) return;
+      const params = req.params as BurnBlockParams;
+
+      const block = await db.getBurnBlock(params);
+      if (!block) {
+        res.status(404).json({ errors: 'Not found' });
+        return;
+      }
+      setETagCacheHeaders(res);
+      res.json(parseDbBurnBlock(block));
+    })
+  );
+
+  return router;
+}

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

@@ -1,5 +1,5 @@
-import { NakamotoBlock } from 'docs/generated';
-import { BlockWithTransactionIds } from '../../../datastore/common';
+import { BurnBlock, NakamotoBlock } from 'docs/generated';
+import { BlockWithTransactionIds, DbBurnBlock } from '../../../datastore/common';
 import { unixEpochToIso } from '../../../helpers';
 import { TypeCheck } from '@sinclair/typebox/compiler';
 import { Request, Response } from 'express';
@@ -25,6 +25,26 @@ export function validRequestQuery(
   return true;
 }
 
+/**
+ * Validate request path parameters with a TypeBox compiled schema
+ * @param req - Request
+ * @param res - Response
+ * @param compiledType - TypeBox compiled schema
+ * @returns boolean
+ */
+export function validRequestParams(
+  req: Request,
+  res: Response,
+  compiledType: TypeCheck<TSchema>
+): boolean {
+  if (!compiledType.Check(req.params)) {
+    // TODO: Return a more user-friendly error
+    res.status(400).json({ errors: [...compiledType.Errors(req.params)] });
+    return false;
+  }
+  return true;
+}
+
 export function parseDbNakamotoBlock(block: BlockWithTransactionIds): NakamotoBlock {
   const apiBlock: NakamotoBlock = {
     canonical: block.canonical,
@@ -47,3 +67,14 @@ export function parseDbNakamotoBlock(block: BlockWithTransactionIds): NakamotoBl
   };
   return apiBlock;
 }
+
+export function parseDbBurnBlock(block: DbBurnBlock): BurnBlock {
+  const burnBlock: BurnBlock = {
+    burn_block_time: block.burn_block_time,
+    burn_block_time_iso: unixEpochToIso(block.burn_block_time),
+    burn_block_hash: block.burn_block_hash,
+    burn_block_height: block.burn_block_height,
+    stacks_blocks: block.stacks_blocks,
+  };
+  return burnBlock;
+}