feat: average block times endpoint (#1962)

* feat: average block times endpoint

* test: add block times test

Author: zone117x

docs/api/blocks/get-average-times.example.json

@@ -0,0 +1,6 @@
+{
+  "last_1h": 846.75,
+  "last_24h": 635.2,
+  "last_7d": 731.26,
+  "last_30d": 738.67
+}

docs/api/blocks/get-average-times.schema.json

@@ -0,0 +1,30 @@
+{
+  "type": "object",
+  "title": "AverageBlockTimesResponse",
+  "description": "Request to fetch average block times (in seconds)",
+  "additionalProperties": false,
+  "required": [
+    "last_1h",
+    "last_24h",
+    "last_7d",
+    "last_30d"
+  ],
+  "properties": {
+    "last_1h": {
+      "type": "number",
+      "description": "Average block times over the last hour (in seconds)"
+    },
+    "last_24h": {
+      "type": "number",
+      "description": "Average block times over the last 24 hours (in seconds)"
+    },
+    "last_7d": {
+      "type": "number",
+      "description": "Average block times over the last 7 days (in seconds)"
+    },
+    "last_30d": {
+      "type": "number",
+      "description": "Average block times over the last 30 days (in seconds)"
+    }
+  }
+}

docs/generated.d.ts

@@ -13,6 +13,7 @@ export type SchemaMergeRootStub =
   | AddressTransactionsWithTransfersListResponse
   | AddressTransactionsListResponse
   | AddressTransactionsV2ListResponse
+  | AverageBlockTimesResponse
   | BlockListResponse
   | BurnBlockListResponse
   | NakamotoBlockListResponse
@@ -1285,6 +1286,27 @@ export interface AddressTransaction {
     [k: string]: unknown | undefined;
   };
 }
+/**
+ * Request to fetch average block times (in seconds)
+ */
+export interface AverageBlockTimesResponse {
+  /**
+   * Average block times over the last hour (in seconds)
+   */
+  last_1h: number;
+  /**
+   * Average block times over the last 24 hours (in seconds)
+   */
+  last_24h: number;
+  /**
+   * Average block times over the last 7 days (in seconds)
+   */
+  last_7d: number;
+  /**
+   * Average block times over the last 30 days (in seconds)
+   */
+  last_30d: number;
+}
 /**
  * GET request that returns blocks
  */

docs/openapi.yaml

@@ -779,7 +779,25 @@ paths:
                 $ref: ./api/blocks/get-nakamoto-blocks.schema.json
               example:
                 $ref: ./api/blocks/get-nakamoto-blocks.example.json
-  
+
+  /extended/v2/blocks/average-times:
+    get:
+      summary: Get average block times
+      description: |
+        Retrieves average block times (in seconds)
+      tags:
+        - Blocks
+      operationId: get_average_block_times
+      responses:
+        200:
+          description: Average block times (in seconds)
+          content:
+            application/json:
+              schema:
+                $ref: ./api/blocks/get-average-times.schema.json
+              example:
+                $ref: ./api/blocks/get-average-times.example.json
+
   /extended/v2/blocks/{height_or_hash}:
     get:
       summary: Get block

src/api/routes/v2/blocks.ts

@@ -43,6 +43,23 @@ export function createV2BlocksRouter(db: PgStore): express.Router {
     })
   );
 
+  router.get(
+    '/average-times',
+    cacheHandler,
+    asyncHandler(async (_req, res) => {
+      const query = await db.v2.getAverageBlockTimes();
+      // Round to 2 decimal places
+      const times = {
+        last_1h: parseFloat(query.last_1h.toFixed(2)),
+        last_24h: parseFloat(query.last_24h.toFixed(2)),
+        last_7d: parseFloat(query.last_7d.toFixed(2)),
+        last_30d: parseFloat(query.last_30d.toFixed(2)),
+      };
+      setETagCacheHeaders(res);
+      res.json(times);
+    })
+  );
+
   router.get(
     '/:height_or_hash',
     cacheHandler,

src/datastore/pg-store-v2.ts

@@ -163,6 +163,60 @@ export class PgStoreV2 extends BasePgStoreModule {
     });
   }
 
+  async getAverageBlockTimes(): Promise<{
+    last_1h: number;
+    last_24h: number;
+    last_7d: number;
+    last_30d: number;
+  }> {
+    return await this.sqlTransaction(async sql => {
+      // Query against block_time but fallback to burn_block_time if block_time is 0 (work around for recent bug).
+      // TODO: remove the burn_block_time fallback once all blocks for last N time have block_time set.
+      const avgBlockTimeQuery = await sql<
+        {
+          last_1h: string | null;
+          last_24h: string | null;
+          last_7d: string | null;
+          last_30d: string | null;
+        }[]
+      >`
+        WITH TimeThresholds AS (
+          SELECT
+            FLOOR(EXTRACT(EPOCH FROM NOW() - INTERVAL '1 HOUR'))::INT AS h1,
+            FLOOR(EXTRACT(EPOCH FROM NOW() - INTERVAL '24 HOURS'))::INT AS h24,
+            FLOOR(EXTRACT(EPOCH FROM NOW() - INTERVAL '7 DAYS'))::INT AS d7,
+            FLOOR(EXTRACT(EPOCH FROM NOW() - INTERVAL '30 DAYS'))::INT AS d30
+        ),
+        OrderedCanonicalBlocks AS (
+          SELECT
+            CASE WHEN block_time = 0 THEN burn_block_time ELSE block_time END AS effective_time,
+            LAG(CASE WHEN block_time = 0 THEN burn_block_time ELSE block_time END) OVER (ORDER BY block_height) AS prev_time
+          FROM
+            blocks
+          WHERE
+            canonical = true AND
+            (CASE WHEN block_time = 0 THEN burn_block_time ELSE block_time END) >= (SELECT d30 FROM TimeThresholds)
+        )
+        SELECT
+          AVG(CASE WHEN effective_time >= (SELECT h1 FROM TimeThresholds) THEN effective_time - prev_time ELSE NULL END) AS last_1h,
+          AVG(CASE WHEN effective_time >= (SELECT h24 FROM TimeThresholds) THEN effective_time - prev_time ELSE NULL END) AS last_24h,
+          AVG(CASE WHEN effective_time >= (SELECT d7 FROM TimeThresholds) THEN effective_time - prev_time ELSE NULL END) AS last_7d,
+          AVG(effective_time - prev_time) AS last_30d
+        FROM
+          OrderedCanonicalBlocks
+        WHERE
+          prev_time IS NOT NULL
+      `;
+      const times = {
+        last_1h: Number.parseFloat(avgBlockTimeQuery[0]?.last_1h ?? '0'),
+        last_24h: Number.parseFloat(avgBlockTimeQuery[0]?.last_24h ?? '0'),
+        last_7d: Number.parseFloat(avgBlockTimeQuery[0]?.last_7d ?? '0'),
+        last_30d: Number.parseFloat(avgBlockTimeQuery[0]?.last_30d ?? '0'),
+      };
+      return times;
+    });
+  }
+
   async getBlockTransactions(
     args: BlockParams & TransactionPaginationQueryParams
   ): Promise<DbPaginatedResult<DbTx>> {

src/tests/block-tests.ts

@@ -14,6 +14,7 @@ import { TestBlockBuilder, TestMicroblockStreamBuilder } from '../test-utils/tes
 import { PgWriteStore } from '../datastore/pg-write-store';
 import { PgSqlClient, bufferToHex } from '@hirosystems/api-toolkit';
 import { migrate } from '../test-utils/test-helpers';
+import { AverageBlockTimesResponse } from '@stacks/stacks-blockchain-api-types';
 
 describe('block tests', () => {
   let db: PgWriteStore;
@@ -809,4 +810,42 @@ describe('block tests', () => {
     expect(fetch.status).toBe(200);
     expect(json).toStrictEqual(block5);
   });
+
+  test('blocks average time', async () => {
+    const blockCount = 50;
+    const now = Math.round(Date.now() / 1000);
+    const thirtyMinutes = 30 * 60;
+    // Return timestamp in seconds for block, latest block will be now(), and previous blocks will be 30 minutes apart
+    const timeForBlock = (blockHeight: number) => {
+      const blockDistance = blockCount - blockHeight;
+      return now - thirtyMinutes * blockDistance;
+    };
+    for (let i = 1; i <= blockCount; i++) {
+      const block = new TestBlockBuilder({
+        block_height: i,
+        block_time: timeForBlock(i),
+        block_hash: `0x${i.toString().padStart(64, '0')}`,
+        index_block_hash: `0x11${i.toString().padStart(62, '0')}`,
+        parent_index_block_hash: `0x11${(i - 1).toString().padStart(62, '0')}`,
+        parent_block_hash: `0x${(i - 1).toString().padStart(64, '0')}`,
+        burn_block_height: 700000,
+        burn_block_hash: '0x00000000000000000001e2ee7f0c6bd5361b5e7afd76156ca7d6f524ee5ca3d8',
+      })
+        .addTx({ tx_id: `0x${i.toString().padStart(64, '0')}` })
+        .build();
+      await db.update(block);
+    }
+
+    const fetch = await supertest(api.server).get(`/extended/v2/blocks/average-times`);
+    const response: AverageBlockTimesResponse = fetch.body;
+    expect(fetch.status).toBe(200);
+
+    // All block time averages should be about 30 minutes
+    const getRatio = (time: number) =>
+      Math.min(thirtyMinutes, time) / Math.max(thirtyMinutes, time);
+    expect(getRatio(response.last_1h)).toBeGreaterThanOrEqual(0.9);
+    expect(getRatio(response.last_24h)).toBeGreaterThanOrEqual(0.9);
+    expect(getRatio(response.last_7d)).toBeGreaterThanOrEqual(0.9);
+    expect(getRatio(response.last_30d)).toBeGreaterThanOrEqual(0.9);
+  });
 });