feat: add get block by burn block height and by burn block hash (#675)

fix: formatting

fix: extract BlockIdentifier type

fix: test

fix: test

fix: test

fix: test

fix: query

Author: friedger

docs/openapi.yaml

@@ -477,6 +477,65 @@ paths:
             application/json:
               example:
                 $ref: ./api/errors/block-not-found.json
+  /extended/v1/block/by_burn_block_hash/{burn_block_hash}:
+    parameters:
+      - name: burn_block_hash
+        in: path
+        description: Hash of the burnchain block
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get block
+      description: Get a specific block by burnchain block hash
+      tags:
+        - Blocks
+      operationId: get_block_by_burn_block_hash
+      responses:
+        200:
+          description: Block
+          content:
+            application/json:
+              schema:
+                $ref: ./entities/blocks/block.schema.json
+              example:
+                $ref: ./entities/blocks/block.example.json
+        404:
+          description: Cannot find block with given height
+          content:
+            application/json:
+              example:
+                $ref: ./api/errors/block-not-found.json
+
+  /extended/v1/block/by_burn_block_height/{burn_block_height}:
+    parameters:
+      - name: burn_block_height
+        in: path
+        description: Height of the burn chain block
+        required: true
+        schema:
+          type: number
+    get:
+      summary: Get block
+      description: Get a specific block by burn chain height
+      tags:
+        - Blocks
+      operationId: get_block_by_burn_block_height
+      responses:
+        200:
+          description: Block
+          content:
+            application/json:
+              schema:
+                $ref: ./entities/blocks/block.schema.json
+              example:
+                $ref: ./entities/blocks/block.example.json
+        404:
+          description: Cannot find block with given height
+          content:
+            application/json:
+              example:
+                $ref: ./api/errors/block-not-found.json
 
   /extended/v1/burnchain/reward_slot_holders:
     get:

src/api/controllers/db-controller.ts

@@ -44,6 +44,7 @@ import {
 } from '@stacks/stacks-blockchain-api-types';
 
 import {
+  BlockIdentifier,
   DataStore,
   DbAssetEventTypeId,
   DbBlock,
@@ -415,7 +416,7 @@ export async function getBlockFromDataStore({
   blockIdentifer,
   db,
 }: {
-  blockIdentifer: { hash: string } | { height: number };
+  blockIdentifer: BlockIdentifier;
   db: DataStore;
 }): Promise<FoundOrNot<Block>> {
   const blockQuery = await db.getBlockWithMetadata(blockIdentifer, {

src/api/routes/block.ts

@@ -52,6 +52,27 @@ export function createBlockRouter(db: DataStore): RouterWithAsync {
     res.json(block.result);
   });
 
+  router.getAsync('/by_burn_block_height/:burnBlockHeight', async (req, res) => {
+    const burnBlockHeight = parseInt(req.params['burnBlockHeight'], 10);
+    if (!Number.isInteger(burnBlockHeight)) {
+      return res.status(400).json({
+        error: `burnchain height is not a valid integer: ${req.params['burnBlockHeight']}`,
+      });
+    }
+    if (burnBlockHeight < 1) {
+      return res
+        .status(400)
+        .json({ error: `burnchain height is not a positive integer: ${burnBlockHeight}` });
+    }
+    const block = await getBlockFromDataStore({ blockIdentifer: { burnBlockHeight }, db });
+    if (!block.found) {
+      res.status(404).json({ error: `cannot find block by height ${burnBlockHeight}` });
+      return;
+    }
+    // TODO: block schema validation
+    res.json(block.result);
+  });
+
   router.getAsync('/:hash', async (req, res) => {
     const { hash } = req.params;
 
@@ -68,5 +89,21 @@ export function createBlockRouter(db: DataStore): RouterWithAsync {
     res.json(block.result);
   });
 
+  router.getAsync('/by_burn_block_hash/:burnBlockHash', async (req, res) => {
+    const { burnBlockHash } = req.params;
+
+    if (!has0xPrefix(burnBlockHash)) {
+      return res.redirect('/extended/v1/block/by_burn_block_hash/0x' + burnBlockHash);
+    }
+
+    const block = await getBlockFromDataStore({ blockIdentifer: { burnBlockHash }, db });
+    if (!block.found) {
+      res.status(404).json({ error: `cannot find block by burn block hash ${burnBlockHash}` });
+      return;
+    }
+    // TODO: block schema validation
+    res.json(block.result);
+  });
+
   return router;
 }

src/datastore/common.ts

@@ -492,13 +492,19 @@ export interface DbRawEventRequest {
   payload: string;
 }
 
+export type BlockIdentifier =
+  | { hash: string }
+  | { height: number }
+  | { burnBlockHash: string }
+  | { burnBlockHeight: number };
+
 export interface DataStore extends DataStoreEventEmitter {
   storeRawEventRequest(eventPath: string, payload: string): Promise<void>;
   getSubdomainResolver(name: { name: string }): Promise<FoundOrNot<string>>;
   getNameCanonical(txId: string, indexBlockHash: string): Promise<FoundOrNot<boolean>>;
-  getBlock(blockIdentifer: { hash: string } | { height: number }): Promise<FoundOrNot<DbBlock>>;
+  getBlock(blockIdentifer: BlockIdentifier): Promise<FoundOrNot<DbBlock>>;
   getBlockWithMetadata<TWithTxs extends boolean = false, TWithMicroblocks extends boolean = false>(
-    blockIdentifer: { hash: string } | { height: number },
+    blockIdentifer: BlockIdentifier,
     metadata?: DbGetBlockWithMetadataOpts<TWithTxs, TWithMicroblocks>
   ): Promise<FoundOrNot<DbGetBlockWithMetadataResponse<TWithTxs, TWithMicroblocks>>>;
 

src/datastore/memory-store.ts

@@ -33,6 +33,7 @@ import {
   DbMicroblock,
   DbGetBlockWithMetadataOpts,
   DbGetBlockWithMetadataResponse,
+  BlockIdentifier,
 } from './common';
 import { logger, FoundOrNot } from '../helpers';
 import { AddressTokenOfferingLocked, TransactionType } from '@stacks/stacks-blockchain-api-types';
@@ -173,27 +174,43 @@ export class MemoryDataStore
   }
 
   getBlockWithMetadata<TWithTxs extends boolean, TWithMicroblocks extends boolean>(
-    blockIdentifer: { hash: string } | { height: number },
+    blockIdentifer: BlockIdentifier,
     metadata?: DbGetBlockWithMetadataOpts<TWithTxs, TWithMicroblocks>
   ): Promise<FoundOrNot<DbGetBlockWithMetadataResponse<TWithTxs, TWithMicroblocks>>> {
     throw new Error('Method not implemented.');
   }
 
-  getBlock(blockIdentifer: { hash: string } | { height: number }): Promise<FoundOrNot<DbBlock>> {
+  getBlock(blockIdentifer: BlockIdentifier): Promise<FoundOrNot<DbBlock>> {
     if ('hash' in blockIdentifer) {
       const block = this.blocks.get(blockIdentifer.hash);
       if (!block) {
         return Promise.resolve({ found: false });
       }
       return Promise.resolve({ found: true, result: block.entry });
-    } else {
+    } else if ('height' in blockIdentifer) {
       const block = [...this.blocks.values()].find(
         b => b.entry.block_height === blockIdentifer.height
       );
       if (!block) {
         return Promise.resolve({ found: false });
       }
       return Promise.resolve({ found: true, result: block.entry });
+    } else if ('burnBlockHash' in blockIdentifer) {
+      const block = [...this.blocks.values()].find(
+        b => b.entry.burn_block_hash === blockIdentifer.burnBlockHash
+      );
+      if (!block) {
+        return Promise.resolve({ found: false });
+      }
+      return Promise.resolve({ found: true, result: block.entry });
+    } else {
+      const block = [...this.blocks.values()].find(
+        b => b.entry.burn_block_height === blockIdentifer.burnBlockHeight
+      );
+      if (!block) {
+        return Promise.resolve({ found: false });
+      }
+      return Promise.resolve({ found: true, result: block.entry });
     }
   }
 

src/datastore/postgres-store.ts

@@ -70,6 +70,7 @@ import {
   DbMicroblockPartial,
   DataStoreTxEventData,
   DbRawEventRequest,
+  BlockIdentifier,
 } from './common';
 import {
   AddressTokenOfferingLocked,
@@ -2202,7 +2203,7 @@ export class PgDataStore
   }
 
   async getBlockWithMetadata<TWithTxs extends boolean, TWithMicroblocks extends boolean>(
-    blockIdentifer: { hash: string } | { height: number },
+    blockIdentifer: BlockIdentifier,
     metadata?: DbGetBlockWithMetadataOpts<TWithTxs, TWithMicroblocks>
   ): Promise<FoundOrNot<DbGetBlockWithMetadataResponse<TWithTxs, TWithMicroblocks>>> {
     return await this.queryTx(async client => {
@@ -2265,13 +2266,13 @@ export class PgDataStore
     });
   }
 
-  getBlock(blockIdentifer: { hash: string } | { height: number }): Promise<FoundOrNot<DbBlock>> {
+  getBlock(blockIdentifer: BlockIdentifier): Promise<FoundOrNot<DbBlock>> {
     return this.query(client => this.getBlockInternal(client, blockIdentifer));
   }
 
   async getBlockInternal(
     client: ClientBase,
-    blockIdentifer: { hash: string } | { height: number }
+    blockIdentifer: BlockIdentifier
   ): Promise<FoundOrNot<DbBlock>> {
     let result: QueryResult<BlockQueryResult>;
     if ('hash' in blockIdentifer) {
@@ -2285,7 +2286,7 @@ export class PgDataStore
         `,
         [hexToBuffer(blockIdentifer.hash)]
       );
-    } else {
+    } else if ('height' in blockIdentifer) {
       result = await client.query<BlockQueryResult>(
         `
         SELECT ${BLOCK_COLUMNS}
@@ -2296,6 +2297,28 @@ export class PgDataStore
         `,
         [blockIdentifer.height]
       );
+    } else if ('burnBlockHash' in blockIdentifer) {
+      result = await client.query<BlockQueryResult>(
+        `
+        SELECT ${BLOCK_COLUMNS}
+        FROM blocks
+        WHERE burn_block_hash = $1 
+        ORDER BY canonical DESC, block_height DESC
+        LIMIT 1
+        `,
+        [hexToBuffer(blockIdentifer.burnBlockHash)]
+      );
+    } else {
+      result = await client.query<BlockQueryResult>(
+        `
+        SELECT ${BLOCK_COLUMNS}
+        FROM blocks
+        WHERE burn_block_height = $1 
+        ORDER BY canonical DESC, block_height DESC
+        LIMIT 1
+        `,
+        [blockIdentifer.burnBlockHeight]
+      );
     }
 
     if (result.rowCount === 0) {

src/tests/api-tests.ts

@@ -3120,6 +3120,60 @@ describe('api tests', () => {
     expect(fetchBlockByHeight.status).toBe(200);
     expect(fetchBlockByHeight.type).toBe('application/json');
     expect(JSON.parse(fetchBlockByHeight.text)).toEqual(expectedResp);
+
+    const fetchBlockByBurnBlockHeight = await supertest(api.server).get(
+      `/extended/v1/block/by_burn_block_height/${block.burn_block_height}`
+    );
+    expect(fetchBlockByBurnBlockHeight.status).toBe(200);
+    expect(fetchBlockByBurnBlockHeight.type).toBe('application/json');
+    expect(JSON.parse(fetchBlockByBurnBlockHeight.text)).toEqual(expectedResp);
+
+    const fetchBlockByInvalidBurnBlockHeight1 = await supertest(api.server).get(
+      `/extended/v1/block/by_burn_block_height/999`
+    );
+    expect(fetchBlockByInvalidBurnBlockHeight1.status).toBe(404);
+    expect(fetchBlockByInvalidBurnBlockHeight1.type).toBe('application/json');
+    const expectedResp1 = {
+      error: 'cannot find block by height 999',
+    };
+    expect(JSON.parse(fetchBlockByInvalidBurnBlockHeight1.text)).toEqual(expectedResp1);
+
+    const fetchBlockByInvalidBurnBlockHeight2 = await supertest(api.server).get(
+      `/extended/v1/block/by_burn_block_height/abc`
+    );
+    expect(fetchBlockByInvalidBurnBlockHeight2.status).toBe(400);
+    expect(fetchBlockByInvalidBurnBlockHeight2.type).toBe('application/json');
+    const expectedResp2 = {
+      error: 'burnchain height is not a valid integer: abc',
+    };
+    expect(JSON.parse(fetchBlockByInvalidBurnBlockHeight2.text)).toEqual(expectedResp2);
+
+    const fetchBlockByInvalidBurnBlockHeight3 = await supertest(api.server).get(
+      `/extended/v1/block/by_burn_block_height/0`
+    );
+    expect(fetchBlockByInvalidBurnBlockHeight3.status).toBe(400);
+    expect(fetchBlockByInvalidBurnBlockHeight3.type).toBe('application/json');
+    const expectedResp3 = {
+      error: 'burnchain height is not a positive integer: 0',
+    };
+    expect(JSON.parse(fetchBlockByInvalidBurnBlockHeight3.text)).toEqual(expectedResp3);
+
+    const fetchBlockByBurnBlockHash = await supertest(api.server).get(
+      `/extended/v1/block/by_burn_block_hash/${block.burn_block_hash}`
+    );
+    expect(fetchBlockByBurnBlockHash.status).toBe(200);
+    expect(fetchBlockByBurnBlockHash.type).toBe('application/json');
+    expect(JSON.parse(fetchBlockByBurnBlockHash.text)).toEqual(expectedResp);
+
+    const fetchBlockByInvalidBurnBlockHash = await supertest(api.server).get(
+      `/extended/v1/block/by_burn_block_hash/0x000000`
+    );
+    expect(fetchBlockByInvalidBurnBlockHash.status).toBe(404);
+    expect(fetchBlockByInvalidBurnBlockHash.type).toBe('application/json');
+    const expectedResp4 = {
+      error: 'cannot find block by burn block hash 0x000000',
+    };
+    expect(JSON.parse(fetchBlockByInvalidBurnBlockHash.text)).toEqual(expectedResp4);
   });
 
   test('tx - sponsored', async () => {