Integration of Indexing Status Builder into ENSIndexer API

apps/ensapi/package.json

@@ -53,7 +53,7 @@
     "hono": "catalog:",
     "hono-openapi": "^1.1.2",
     "p-memoize": "^8.0.0",
-    "p-retry": "^7.1.0",
+    "p-retry": "catalog:",
     "pg-connection-string": "catalog:",
     "pino": "catalog:",
     "ponder-enrich-gql-docs-middleware": "^0.1.3",

apps/ensindexer/package.json

@@ -37,6 +37,7 @@
     "pg-connection-string": "catalog:",
     "hono": "catalog:",
     "ponder": "catalog:",
+    "p-retry": "catalog:",
     "viem": "catalog:",
     "zod": "catalog:"
   },

apps/ensindexer/ponder/src/api/handlers/ensnode-api.ts

@@ -1,6 +1,5 @@
 import config from "@/config";
 
-import { publicClients } from "ponder:api";
 import { getUnixTime } from "date-fns";
 import { Hono } from "hono";
 
@@ -15,13 +14,18 @@ import {
 } from "@ensnode/ensnode-sdk";
 
 import { buildENSIndexerPublicConfig } from "@/config/public";
-import {
-  buildOmnichainIndexingStatusSnapshot,
-  createCrossChainIndexingStatusSnapshotOmnichain,
-} from "@/lib/indexing-status/build-index-status";
+import { createCrossChainIndexingStatusSnapshotOmnichain } from "@/lib/indexing-status/build-index-status";
+import { buildOmnichainIndexingStatusSnapshot } from "@/lib/indexing-status-builder/omnichain-indexing-status-snapshot";
+import { getLocalPonderClient } from "@/lib/ponder-api-client";
 
 const app = new Hono();
 
+// Calling `getLocalPonderClient` at the top level to initialize
+// the singleton client instance on app startup.
+// This ensures that the client is ready to use when handling requests,
+// and allows us to catch initialization errors early.
+getLocalPonderClient();
+
 // include ENSIndexer Public Config endpoint
 app.get("/config", async (c) => {
   // prepare the public config object, including dependency info
@@ -38,23 +42,26 @@ app.get("/indexing-status", async (c) => {
   let omnichainSnapshot: OmnichainIndexingStatusSnapshot | undefined;
 
   try {
-    omnichainSnapshot = await buildOmnichainIndexingStatusSnapshot(publicClients);
+    const localPonderClient = await getLocalPonderClient();
+    const chainsIndexingMetadata = await localPonderClient.chainsIndexingMetadata();
+
+    omnichainSnapshot = buildOmnichainIndexingStatusSnapshot(chainsIndexingMetadata);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : "Unknown error";
-    console.error(`Omnichain snapshot is currently not available: ${errorMessage}`);
+    console.error(
+      `Indexing Status is currently not available. Failed to fetch Omnichain Indexing Status snapshot: ${errorMessage}`,
+    );
   }
 
   // return IndexingStatusResponseError
-  if (typeof omnichainSnapshot === "undefined") {
+  if (!omnichainSnapshot) {
     return c.json(
       serializeIndexingStatusResponse({
         responseCode: IndexingStatusResponseCodes.Error,
       } satisfies IndexingStatusResponseError),
       500,
     );
   }
-
-  // otherwise, proceed with creating IndexingStatusResponseOk
   const crossChainSnapshot = createCrossChainIndexingStatusSnapshotOmnichain(
     omnichainSnapshot,
     snapshotTime,

apps/ensindexer/ponder/src/api/lib/chains-config-blockrange.ts

@@ -0,0 +1,185 @@
+/**
+ * This file is about parsing the object that is exported by `ponder.config.ts`.
+ *
+ * Each Ponder datasource defined in the aforementioned Ponder Config object
+ * can include information about startBlock and endBlock. This is to let
+ * Ponder know which blockrange to index for a particular Ponder Datasource.
+ *
+ * ENSIndexer, however, needs a blockrange for each indexed chain. This is why
+ * we examine Ponder Config object, looking for the "lowest" startBlock, and
+ * the "highest" endBlock defined for each of the indexed chains.
+ */
+
+import type { AddressConfig, ChainConfig, CreateConfigReturnType } from "ponder";
+
+import {
+  deserializeBlockNumber,
+  deserializeBlockrange,
+  deserializeChainId,
+} from "@ensnode/ensnode-sdk";
+import type {
+  BlockNumber,
+  Blockrange,
+  BlockrangeWithStartBlock,
+  ChainId,
+  ChainIdString,
+} from "@ensnode/ponder-sdk";
+
+/**
+ * Ponder config datasource with a flat `chain` value.
+ */
+export type PonderConfigDatasourceFlat = {
+  chain: ChainIdString;
+} & AddressConfig &
+  Blockrange;
+
+/**
+ * Ponder config datasource with a nested `chain` value.
+ */
+export type PonderConfigDatasourceNested = {
+  chain: Record<ChainIdString, AddressConfig & Blockrange>;
+};
+
+/**
+ * Ponder config datasource
+ */
+export type PonderConfigDatasource = PonderConfigDatasourceFlat | PonderConfigDatasourceNested;
+
+/**
+ * Ponder config datasource
+ */
+type PonderConfigDatasources = {
+  [datasourceId: string]: PonderConfigDatasource;
+};
+
+/**
+ * Ponder chains config
+ *
+ * Chain config for each indexed chain.
+ */
+type PonderConfigChains = {
+  [chainId: ChainIdString]: ChainConfig;
+};
+
+/**
+ * Ponder Config
+ *
+ * A utility type describing Ponder Config.
+ */
+export type PonderConfigType = CreateConfigReturnType<
+  PonderConfigChains,
+  PonderConfigDatasources,
+  PonderConfigDatasources,
+  PonderConfigDatasources
+>;
+
+/**
+ * Ensure the `ponderDatasource` is {@link PonderConfigDatasourceFlat}.
+ */
+function isPonderDatasourceFlat(
+  ponderDatasource: PonderConfigDatasource,
+): ponderDatasource is PonderConfigDatasourceFlat {
+  return typeof ponderDatasource.chain === "string";
+}
+
+/**
+ * Ensure the `ponderDatasource` is {@link PonderConfigDatasourceNested}.
+ */
+function isPonderDatasourceNested(
+  ponderDatasource: PonderConfigDatasource,
+): ponderDatasource is PonderConfigDatasourceNested {
+  return typeof ponderDatasource.chain === "object";
+}
+
+/**
+ * Build {@link Blockrange} for each indexed chain.
+ *
+ * Invariants:
+ * - every chain include a startBlock,
+ * - some chains may include an endBlock,
+ * - all present startBlock and endBlock values are valid {@link BlockNumber} values.
+ *
+ * @throws Error if any of the above invariants are violated.
+ */
+export function buildChainsBlockrange(
+  ponderConfig: PonderConfigType,
+): Map<ChainId, BlockrangeWithStartBlock> {
+  const chainsBlockrange = new Map<ChainId, BlockrangeWithStartBlock>();
+
+  // 0. Get all ponder sources (includes chain + startBlock & endBlock)
+  const ponderSources = [
+    ...Object.values(ponderConfig.accounts ?? {}),
+    ...Object.values(ponderConfig.blocks ?? {}),
+    ...Object.values(ponderConfig.contracts ?? {}),
+  ] as PonderConfigDatasource[];
+
+  // 1. For every indexed chain
+  for (const serializedChainId of Object.keys(ponderConfig.chains)) {
+    const chainStartBlocks: BlockNumber[] = [];
+    const chainEndBlocks: BlockNumber[] = [];
+
+    // 1.1. For every Ponder source (accounts, blocks, contracts),
+    //      extract startBlock number (required) and endBlock number (optional).
+    for (const ponderSource of ponderSources) {
+      let startBlock: Blockrange["startBlock"];
+      let endBlock: Blockrange["endBlock"];
+
+      if (isPonderDatasourceFlat(ponderSource) && ponderSource.chain === serializedChainId) {
+        startBlock = ponderSource.startBlock;
+        endBlock = ponderSource.endBlock;
+      } else if (isPonderDatasourceNested(ponderSource) && ponderSource.chain[serializedChainId]) {
+        startBlock = ponderSource.chain[serializedChainId].startBlock;
+        endBlock = ponderSource.chain[serializedChainId].endBlock;
+      }
+
+      if (typeof startBlock === "number") {
+        chainStartBlocks.push(deserializeBlockNumber(startBlock));
+      }
+
+      if (typeof endBlock === "number") {
+        chainEndBlocks.push(deserializeBlockNumber(endBlock));
+      }
+    }
+
+    // 2. Get the lowest startBlock for the chain.
+    const chainLowestStartBlock =
+      chainStartBlocks.length > 0 ? Math.min(...chainStartBlocks) : undefined;
+
+    // 3.a) The endBlock can only be set for a chain if and only if every
+    //      ponderSource for that chain has its respective `endBlock` defined.
+    const isEndBlockForChainAllowed = chainEndBlocks.length === chainStartBlocks.length;
+
+    // 3.b) Get the highest endBLock for the chain.
+    const chainHighestEndBlock =
+      isEndBlockForChainAllowed && chainEndBlocks.length > 0
+        ? Math.max(...chainEndBlocks)
+        : undefined;
+
+    // 4. Enforce invariants
+
+    // Invariant: the indexed chain must have its startBlock defined as number.
+    if (typeof chainLowestStartBlock === "undefined") {
+      throw new Error(
+        `No minimum start block found for chain '${serializedChainId}'. Either all contracts, accounts, and block intervals use "latest" (unsupported) or the chain is misconfigured.`,
+      );
+    }
+
+    // 5. Assign a valid blockrange to the chain
+    const chainId = deserializeChainId(serializedChainId);
+    const blockrange = deserializeBlockrange({
+      startBlock: chainLowestStartBlock,
+      endBlock: chainHighestEndBlock,
+    });
+
+    // Invariant: the blockrange must include a valid startBlock number.
+    if (typeof blockrange.startBlock === "undefined") {
+      throw new Error(
+        `Invalid blockrange for chain '${serializedChainId}'. The blockrange must include a valid startBlock number.`,
+      );
+    }
+
+    chainsBlockrange.set(chainId, blockrange as BlockrangeWithStartBlock);
+  }
+
+  return chainsBlockrange;
+}

apps/ensindexer/ponder/src/api/lib/fetch-block-ref.ts

@@ -0,0 +1,39 @@
+import type { PublicClient } from "viem";
+
+import { bigIntToNumber, deserializeBlockRef } from "@ensnode/ensnode-sdk";
+import type { BlockNumber, BlockRef } from "@ensnode/ponder-sdk";
+
+/**
+ * Fetch block reference (number and timestamp) for a given block number on
+ * a given chain, using the provided public client.
+ *
+ * @returns Requested block reference
+ * @throws Error if the block cannot be fetched or if the block data is invalid.
+ */
+export async function fetchBlockRef(
+  publicClient: PublicClient,
+  blockNumber: BlockNumber,
+): Promise<BlockRef> {
+  const chainId = publicClient.chain?.id;
+
+  if (!chainId) {
+    throw new Error(
+      `Public client is missing chain ID, cannot fetch block ref for block number ${blockNumber}`,
+    );
+  }
+
+  try {
+    const block = await publicClient.getBlock({ blockNumber: BigInt(blockNumber) });
+
+    return deserializeBlockRef({
+      timestamp: bigIntToNumber(block.timestamp),
+      number: bigIntToNumber(block.number),
+    });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+
+    throw new Error(
+      `Error fetching block for chain ID ${chainId} at block number ${blockNumber}: ${errorMessage}`,
+    );
+  }
+}