feat: add more recursion endpoints

src/api/init.ts

@@ -1,15 +1,16 @@
 import FastifyCors from '@fastify/cors';
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import { PINO_LOGGER_CONFIG } from '@hirosystems/api-toolkit';
 import Fastify, { FastifyPluginAsync } from 'fastify';
 import FastifyMetrics, { IFastifyMetrics } from 'fastify-metrics';
 import { Server } from 'http';
 import { PgStore } from '../pg/pg-store';
 import { InscriptionsRoutes } from './routes/inscriptions';
+import { RecursionRoutes } from './routes/recursion';
 import { SatRoutes } from './routes/sats';
 import { StatsRoutes } from './routes/stats';
 import { StatusRoutes } from './routes/status';
 import { isProdEnv } from './util/helpers';
-import { PINO_LOGGER_CONFIG } from '@hirosystems/api-toolkit';
 
 export const Api: FastifyPluginAsync<
   Record<never, never>,
@@ -20,6 +21,7 @@ export const Api: FastifyPluginAsync<
   await fastify.register(InscriptionsRoutes);
   await fastify.register(SatRoutes);
   await fastify.register(StatsRoutes);
+  await fastify.register(RecursionRoutes);
 };
 
 export async function buildApiServer(args: { db: PgStore }) {

src/api/routes/recursion.ts

@@ -0,0 +1,128 @@
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import { Type } from '@sinclair/typebox';
+import { FastifyPluginAsync, FastifyPluginCallback } from 'fastify';
+import { Server } from 'http';
+import {
+  BlockHashResponse,
+  BlockHeightParam,
+  BlockHeightResponse,
+  BlockTimestampResponse,
+  NotFoundResponse,
+} from '../schemas';
+import { handleBlockHashCache, handleBlockHeightCache } from '../util/cache';
+
+const IndexRoutes: FastifyPluginCallback<Record<never, never>, Server, TypeBoxTypeProvider> = (
+  fastify,
+  options,
+  done
+) => {
+  fastify.addHook('preHandler', handleBlockHashCache);
+
+  fastify.get(
+    '/blockheight',
+    {
+      schema: {
+        operationId: 'getBlockHeight',
+        summary: 'Recursion',
+        description: 'Retrieves the latest block height',
+        tags: ['Recursion'],
+        response: {
+          200: BlockHeightResponse,
+          404: NotFoundResponse,
+        },
+      },
+    },
+    async (request, reply) => {
+      const blockHeight = (await fastify.db.getChainTipBlockHeight()) ?? 'blockheight';
+      // Currently, the `chain_tip` materialized view should always  return a
+      // minimum of 767430 (inscription #0 genesis), but we'll keep the fallback
+      // to stay consistent with `ord`.
+
+      await reply.send(blockHeight.toString());
+    }
+  );
+
+  fastify.get(
+    '/blockhash',
+    {
+      schema: {
+        operationId: 'getBlockHash',
+        summary: 'Recursion',
+        description: 'Retrieves the latest block hash',
+        tags: ['Recursion'],
+        response: {
+          200: BlockHashResponse,
+          404: NotFoundResponse,
+        },
+      },
+    },
+    async (request, reply) => {
+      const blockHash = (await fastify.db.getBlockHash()) ?? 'blockhash';
+      await reply.send(blockHash);
+    }
+  );
+
+  fastify.get(
+    '/blocktime',
+    {
+      schema: {
+        operationId: 'getBlockTime',
+        summary: 'Recursion',
+        description: 'Retrieves the latest block time',
+        tags: ['Recursion'],
+        response: {
+          200: BlockTimestampResponse,
+          404: NotFoundResponse,
+        },
+      },
+    },
+    async (request, reply) => {
+      const blockTime = (await fastify.db.getBlockTimestamp()) ?? 'blocktime';
+      await reply.send(blockTime);
+    }
+  );
+
+  done();
+};
+
+const ShowRoutes: FastifyPluginCallback<Record<never, never>, Server, TypeBoxTypeProvider> = (
+  fastify,
+  options,
+  done
+) => {
+  fastify.addHook('preHandler', handleBlockHeightCache);
+
+  fastify.get(
+    '/blockhash/:block_height',
+    {
+      schema: {
+        operationId: 'getBlockHash',
+        summary: 'Recursion',
+        description: 'Retrieves the block hash for a given block height',
+        tags: ['Recursion'],
+        params: Type.Object({
+          block_height: BlockHeightParam,
+        }),
+        response: {
+          200: BlockHashResponse,
+          404: NotFoundResponse,
+        },
+      },
+    },
+    async (request, reply) => {
+      const blockHash = (await fastify.db.getBlockHash(request.params.block_height)) ?? 'blockhash';
+      await reply.send(blockHash);
+    }
+  );
+
+  done();
+};
+
+export const RecursionRoutes: FastifyPluginAsync<
+  Record<never, never>,
+  Server,
+  TypeBoxTypeProvider
+> = async fastify => {
+  await fastify.register(IndexRoutes);
+  await fastify.register(ShowRoutes);
+};

src/api/schemas.ts

@@ -351,3 +351,14 @@ export const InscriptionsPerBlockResponse = Type.Object({
   results: Type.Array(InscriptionsPerBlock),
 });
 export type InscriptionsPerBlockResponse = Static<typeof InscriptionsPerBlockResponse>;
+
+export const BlockHeightResponse = Type.String({ examples: ['778921'] });
+export type BlockHeightResponse = Static<typeof BlockHeightResponse>;
+
+export const BlockHashResponse = Type.String({
+  examples: ['0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133'],
+});
+export type BlockHashResponse = Static<typeof BlockHashResponse>;
+
+export const BlockTimestampResponse = Type.String({ examples: ['1677733170000'] });
+export type BlockTimestampResponse = Static<typeof BlockTimestampResponse>;

src/api/util/cache.ts

@@ -1,11 +1,17 @@
-import { FastifyReply, FastifyRequest } from 'fastify';
-import { InscriptionIdParamCType, InscriptionNumberParamCType } from '../schemas';
 import { logger } from '@hirosystems/api-toolkit';
+import { FastifyReply, FastifyRequest } from 'fastify';
+import {
+  BlockHeightParamCType,
+  InscriptionIdParamCType,
+  InscriptionNumberParamCType,
+} from '../schemas';
 
 export enum ETagType {
   inscriptionTransfers,
   inscription,
   inscriptionsPerBlock,
+  blockHash,
+  blockHeight,
 }
 
 /**
@@ -34,6 +40,14 @@ export async function handleInscriptionsPerBlockCache(
   return handleCache(ETagType.inscriptionsPerBlock, request, reply);
 }
 
+export async function handleBlockHashCache(request: FastifyRequest, reply: FastifyReply) {
+  return handleCache(ETagType.blockHash, request, reply);
+}
+
+export async function handleBlockHeightCache(request: FastifyRequest, reply: FastifyReply) {
+  return handleCache(ETagType.blockHeight, request, reply);
+}
+
 async function handleCache(type: ETagType, request: FastifyRequest, reply: FastifyReply) {
   const ifNoneMatch = parseIfNoneMatchHeader(request.headers['if-none-match']);
   let etag: string | undefined;
@@ -47,9 +61,15 @@ async function handleCache(type: ETagType, request: FastifyRequest, reply: Fasti
     case ETagType.inscriptionsPerBlock:
       etag = await request.server.db.getInscriptionsPerBlockETag();
       break;
+    case ETagType.blockHash:
+      etag = await request.server.db.getBlockHashETag();
+      break;
+    case ETagType.blockHeight:
+      etag = await getBlockHeightEtag(request);
+      break;
   }
   if (etag) {
-    if (ifNoneMatch && ifNoneMatch.includes(etag)) {
+    if (ifNoneMatch?.includes(etag)) {
       await reply.header('Cache-Control', CACHE_CONTROL_MUST_REVALIDATE).code(304).send();
     } else {
       void reply.headers({ 'Cache-Control': CACHE_CONTROL_MUST_REVALIDATE, ETag: `"${etag}"` });
@@ -62,6 +82,20 @@ export function setReplyNonCacheable(reply: FastifyReply) {
   reply.removeHeader('Etag');
 }
 
+/**
+ * Retrieve the blockheight's blockhash so we can use it as the response ETag.
+ * @param request - Fastify request
+ * @returns Etag string
+ */
+async function getBlockHeightEtag(request: FastifyRequest): Promise<string | undefined> {
+  const blockHeightParam = request.url.split('/').find(p => BlockHeightParamCType.Check(p));
+  return blockHeightParam
+    ? await request.server.db
+        .getBlockHeightETag({ block_height: blockHeightParam })
+        .catch(_ => undefined) // fallback
+    : undefined;
+}
+
 /**
  * Retrieve the inscriptions's location timestamp as a UNIX epoch so we can use it as the response
  * ETag.
@@ -73,7 +107,7 @@ async function getInscriptionLocationEtag(request: FastifyRequest): Promise<stri
     const components = request.url.split('/');
     do {
       const lastElement = components.pop();
-      if (lastElement && lastElement.length) {
+      if (lastElement?.length) {
         if (InscriptionIdParamCType.Check(lastElement)) {
           return await request.server.db.getInscriptionETag({ genesis_id: lastElement });
         } else if (InscriptionNumberParamCType.Check(parseInt(lastElement))) {

src/pg/pg-store.ts

@@ -1,4 +1,6 @@
+import { BasePgStore, connectPostgres, logger, runMigrations } from '@hirosystems/api-toolkit';
 import { BitcoinEvent, Payload } from '@hirosystems/chainhook-client';
+import * as path from 'path';
 import { Order, OrderBy } from '../api/schemas';
 import { isProdEnv, isTestEnv, normalizedHexString, parseSatPoint } from '../api/util/helpers';
 import { OrdinalSatoshi, SatoshiRarity } from '../api/util/ordinal-satoshi';
@@ -21,8 +23,6 @@ import {
   DbPaginatedResult,
   LOCATIONS_COLUMNS,
 } from './types';
-import { BasePgStore, connectPostgres, logger, runMigrations } from '@hirosystems/api-toolkit';
-import * as path from 'path';
 
 export const MIGRATIONS_DIR = path.join(__dirname, '../../migrations');
 
@@ -212,6 +212,36 @@ export class PgStore extends BasePgStore {
     return parseInt(result[0].block_height);
   }
 
+  /**
+   * Returns the block hash of the latest block, or the block hash of the block
+   * at the given height.
+   * @param blockHeight - optional block height (defaults to latest block)
+   */
+  async getBlockHash(blockHeight?: string): Promise<string> {
+    const clause = blockHeight
+      ? this.sql`WHERE block_height = ${blockHeight}`
+      : this.sql`
+        ORDER BY block_height DESC
+        LIMIT 1
+      `;
+
+    const result = await this.sql<{ block_hash: string }[]>`
+      SELECT block_hash FROM inscriptions_per_block
+      ${clause}
+    `;
+
+    return result[0]?.block_hash;
+  }
+
+  async getBlockTimestamp(): Promise<string> {
+    const result = await this.sql<{ timestamp: string }[]>`
+      SELECT ROUND(EXTRACT(EPOCH FROM timestamp)) as timestamp FROM inscriptions_per_block
+      ORDER BY block_height DESC
+      LIMIT 1
+    `;
+    return result[0]?.timestamp;
+  }
+
   async getChainTipInscriptionCount(): Promise<number> {
     const result = await this.sql<{ count: number }[]>`
       SELECT count FROM inscription_count
@@ -282,6 +312,25 @@ export class PgStore extends BasePgStore {
     return `${result[0].block_hash}:${result[0].inscription_count}`;
   }
 
+  async getBlockHashETag(): Promise<string> {
+    const result = await this.sql<{ block_hash: string }[]>`
+      SELECT block_hash
+      FROM inscriptions_per_block
+      ORDER BY block_height DESC
+      LIMIT 1
+    `;
+    return result[0].block_hash;
+  }
+
+  async getBlockHeightETag(args: { block_height: string }): Promise<string> {
+    const result = await this.sql<{ block_hash: string }[]>`
+      SELECT block_hash
+      FROM inscriptions_per_block
+      WHERE block_height = ${args.block_height}
+    `;
+    return result[0].block_hash;
+  }
+
   async getInscriptionContent(
     args: InscriptionIdentifier
   ): Promise<DbInscriptionContent | undefined> {