feat: GET /extended/v1/burn_block (#1766)

zone117x · web-flow · commit cb38b6811c65 · 2023-12-12T17:12:28.000+01:00
* feat: new endpoint to get burn blocks `/extended/v1/burn_block`

* feat: return stacks block hashes in burn block results

* test: add tests for `/extended/v1/burn_block`

* ci: fix openapi lint
diff --git a/docs/api/blocks/get-burn-blocks.example.json b/docs/api/blocks/get-burn-blocks.example.json
@@ -0,0 +1,19 @@
+{
+  "limit": 1,
+  "offset": 0,
+  "total": 21707,
+  "results": [
+    {
+      "burn_block_time": 1626281749,
+      "burn_block_time_iso": "2021-07-14T16:55:49.000Z",
+      "burn_block_hash": "0x0000000000000000000ea16f8e906e85ee1cb4dff1e5424e93843b3cec8b0bcb",
+      "burn_block_height": 691014,
+      "stacks_blocks": [
+        "0x54647c277eefe60519b407f2c897749005fdb7f831034135063b2ee43fdacb04",
+        "0xdaf61d2b355f35c94cf019af99aeb73d8e7db7301c7cd693a464ebd1cfc2228c",
+        "0xb9e9b308cf9621ecbf66ca7b4689fe384b9b67c4588ec827d8163ab602fb935e",
+        "0x754562cba6ec243f90485e97778ab472f462fd123ef5b83cc79d8759ca8875f5"
+      ]
+    }
+  ]
+}
diff --git a/docs/api/blocks/get-burn-blocks.schema.json b/docs/api/blocks/get-burn-blocks.schema.json
@@ -0,0 +1,29 @@
+{
+  "description": "GET request that returns burn blocks",
+  "additionalProperties": false,
+  "title": "BurnBlockListResponse",
+  "type": "object",
+  "required": ["results", "limit", "offset", "total"],
+  "properties": {
+    "limit": {
+      "type": "integer",
+      "maximum": 30,
+      "description": "The number of burn blocks to return"
+    },
+    "offset": {
+      "type": "integer",
+      "description": "The number to burn blocks to skip (starting at `0`)",
+      "default": 0
+    },
+    "total": {
+      "type": "integer",
+      "description": "The number of burn blocks available (regardless of filter parameters)"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/blocks/burn-block.schema.json"
+      }
+    }
+  }
+}
diff --git a/docs/entities/blocks/burn-block.example.json b/docs/entities/blocks/burn-block.example.json
@@ -0,0 +1,12 @@
+{
+  "burn_block_time": 1594233639,
+  "burn_block_time_iso": "2020-08-27T16:41:26.000Z",
+  "burn_block_hash": "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2",
+  "burn_block_height": 654439,
+  "stacks_blocks": [
+    "0x54647c277eefe60519b407f2c897749005fdb7f831034135063b2ee43fdacb04",
+    "0xdaf61d2b355f35c94cf019af99aeb73d8e7db7301c7cd693a464ebd1cfc2228c",
+    "0xb9e9b308cf9621ecbf66ca7b4689fe384b9b67c4588ec827d8163ab602fb935e",
+    "0x754562cba6ec243f90485e97778ab472f462fd123ef5b83cc79d8759ca8875f5"
+  ]
+}
diff --git a/docs/entities/blocks/burn-block.schema.json b/docs/entities/blocks/burn-block.schema.json
@@ -0,0 +1,38 @@
+{
+  "title": "BurnBlock",
+  "description": "A burn block",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "burn_block_time",
+    "burn_block_time_iso",
+    "burn_block_hash",
+    "burn_block_height",
+    "stacks_blocks"
+  ],
+  "properties": {
+    "burn_block_time": {
+      "type": "number",
+      "description": "Unix timestamp (in seconds) indicating when this block was mined."
+    },
+    "burn_block_time_iso": {
+      "type": "string",
+      "description": "An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined."
+    },
+    "burn_block_hash": {
+      "type": "string",
+      "description": "Hash of the anchor chain block"
+    },
+    "burn_block_height": {
+      "type": "integer",
+      "description": "Height of the anchor chain block"
+    },
+    "stacks_blocks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Hashes of the Stacks blocks included in the burn block"
+    }
+  }
+}
diff --git a/docs/generated.d.ts b/docs/generated.d.ts
@@ -13,6 +13,7 @@ export type SchemaMergeRootStub =
   | AddressTransactionsWithTransfersListResponse
   | AddressTransactionsListResponse
   | BlockListResponse
+  | BurnBlockListResponse
   | BnsError
   | BnsFetchFileZoneResponse
   | BnsGetAllNamesResponse
@@ -114,6 +115,7 @@ export type SchemaMergeRootStub =
   | NftBalance
   | StxBalance
   | Block
+  | BurnBlock
   | BurnchainRewardSlotHolder
   | BurnchainReward
   | BurnchainRewardsTotal
@@ -1274,6 +1276,49 @@ export interface Block {
     [k: string]: number | undefined;
   };
 }
+/**
+ * GET request that returns burn blocks
+ */
+export interface BurnBlockListResponse {
+  /**
+   * The number of burn blocks to return
+   */
+  limit: number;
+  /**
+   * The number to burn blocks to skip (starting at `0`)
+   */
+  offset: number;
+  /**
+   * The number of burn blocks available (regardless of filter parameters)
+   */
+  total: number;
+  results: BurnBlock[];
+}
+/**
+ * A burn block
+ */
+export interface BurnBlock {
+  /**
+   * Unix timestamp (in seconds) indicating when this block was mined.
+   */
+  burn_block_time: number;
+  /**
+   * An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.
+   */
+  burn_block_time_iso: string;
+  /**
+   * Hash of the anchor chain block
+   */
+  burn_block_hash: string;
+  /**
+   * Height of the anchor chain block
+   */
+  burn_block_height: number;
+  /**
+   * Hashes of the Stacks blocks included in the burn block
+   */
+  stacks_blocks: string[];
+}
 /**
  * Error
  */
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
@@ -612,6 +612,54 @@ paths:
               schema:
                 $ref: ./api/microblocks/get-unanchored-txs.schema.json
 
+  /extended/v1/burn_block:
+    get:
+      summary: Get recent burn blocks
+      description: |
+          Retrieves a list of recent burn blocks
+      tags:
+        - Blocks
+      operationId: get_burn_block_list
+      parameters:
+        - name: limit
+          in: query
+          description: max number of burn blocks to fetch
+          required: false
+          schema:
+            type: integer
+            default: 20
+            maximum: 30
+        - name: offset
+          in: query
+          description: index of first burn block to fetch
+          required: false
+          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
+          content:
+            application/json:
+              schema:
+                $ref: ./api/blocks/get-burn-blocks.schema.json
+              example:
+                $ref: ./api/blocks/get-burn-blocks.example.json
+
   /extended/v1/block:
     get:
       summary: Get recent blocks
diff --git a/src/api/controllers/db-controller.ts b/src/api/controllers/db-controller.ts
@@ -16,6 +16,7 @@ import {
   AbstractTransaction,
   BaseTransaction,
   Block,
+  BurnBlock,
   CoinbaseTransactionMetadata,
   ContractCallTransactionMetadata,
   MempoolTransaction,
@@ -530,6 +531,35 @@ 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;
diff --git a/src/api/init.ts b/src/api/init.ts
@@ -45,6 +45,7 @@ import { createPox3EventsRouter } from './routes/pox3';
 import { createStackingRouter } from './routes/stacking';
 import { logger, loggerMiddleware } from '../logger';
 import { SERVER_VERSION, isPgConnectionError, isProdEnv, waiter } from '@hirosystems/api-toolkit';
+import { createBurnBlockRouter } from './routes/burn-block';
 
 export interface ApiServer {
   expressApp: express.Express;
@@ -184,6 +185,7 @@ export async function startApiServer(opts: {
       router.use('/tx', createTxRouter(datastore));
       router.use('/block', createBlockRouter(datastore));
       router.use('/microblock', createMicroblockRouter(datastore));
+      router.use('/burn_block', createBurnBlockRouter(datastore));
       router.use('/burnchain', createBurnchainRouter(datastore));
       router.use('/contract', createContractRouter(datastore));
       // same here, exclude account nonce route
diff --git a/src/api/pagination.ts b/src/api/pagination.ts
@@ -35,13 +35,18 @@ export enum ResourceType {
   Token,
   Pox2Event,
   Stacker,
+  BurnBlock,
 }
 
 const pagingQueryLimits: Record<ResourceType, { defaultLimit: number; maxLimit: number }> = {
   [ResourceType.Block]: {
     defaultLimit: 20,
     maxLimit: 30,
   },
+  [ResourceType.BurnBlock]: {
+    defaultLimit: 20,
+    maxLimit: 30,
+  },
   [ResourceType.Tx]: {
     defaultLimit: 20,
     maxLimit: 50,
diff --git a/src/api/query-helpers.ts b/src/api/query-helpers.ts
@@ -111,6 +111,53 @@ 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.
diff --git a/src/api/routes/burn-block.ts b/src/api/routes/burn-block.ts
@@ -0,0 +1,42 @@
+import * as express from 'express';
+import { BurnBlockListResponse } from '@stacks/stacks-blockchain-api-types';
+import { getBurnBlocksFromDataStore } from '../controllers/db-controller';
+import { getPagingQueryLimit, parsePagingQueryInput, ResourceType } from '../pagination';
+import { getBlockHashQueryParam, getBlockHeightQueryParam } from '../query-helpers';
+import { getETagCacheHandler, setETagCacheHeaders } from '../controllers/cache-controller';
+import { asyncHandler } from '../async-handler';
+import { PgStore } from '../../datastore/pg-store';
+
+export function createBurnBlockRouter(db: PgStore): express.Router {
+  const router = express.Router();
+  const cacheHandler = getETagCacheHandler(db);
+  router.get(
+    '/',
+    cacheHandler,
+    asyncHandler(async (req, res, next) => {
+      const limit = getPagingQueryLimit(ResourceType.BurnBlock, req.query.limit);
+      const offset = parsePagingQueryInput(req.query.offset ?? 0);
+      const height =
+        getBlockHeightQueryParam('height', false, req, res, next) ??
+        getBlockHeightQueryParam('block_height', false, req, res, next);
+
+      let hash = req.query.hash === 'latest' ? 'latest' : null;
+      if (!hash) {
+        hash = getBlockHashQueryParam('hash', false, req, res, next);
+      }
+
+      const { results, total } = await getBurnBlocksFromDataStore({
+        offset,
+        limit,
+        db,
+        height,
+        hash,
+      });
+      setETagCacheHeaders(res);
+      const response: BurnBlockListResponse = { limit, offset, total, results };
+      res.json(response);
+    })
+  );
+
+  return router;
+}
diff --git a/src/datastore/common.ts b/src/datastore/common.ts
diff --git a/src/datastore/pg-store.ts b/src/datastore/pg-store.ts
diff --git a/src/tests/block-tests.ts b/src/tests/block-tests.ts
