refactor(ensnode-sdk): improve Indexing Status data model

.changeset/wet-pens-mate.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ensnode-sdk": minor
+---
+
+Introduced `validate*` functions for Indexing Status data model. These functions enable new use cases on consumers side.

apps/ensindexer/src/lib/indexing-status/ponder-metadata/validations.ts

@@ -1,13 +1,5 @@
-import { type ParsePayload, prettifyError } from "zod/v4/core";
+import { prettifyError } from "zod/v4/core";
 
-import {
-  checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotBackfill,
-  checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotCompleted,
-  checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotFollowing,
-  checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotUnstarted,
-  OmnichainIndexingStatusIds,
-  type SerializedOmnichainIndexingStatusSnapshot,
-} from "@ensnode/ensnode-sdk";
 import type { PrometheusMetrics } from "@ensnode/ponder-metadata";
 
 import { PonderAppSettingsSchema } from "./zod-schemas";
@@ -32,43 +24,3 @@ export function validatePonderMetrics(metrics: PrometheusMetrics) {
     );
   }
 }
-
-/**
- * Invariant: SerializedOmnichainSnapshot Has Valid Chains
- *
- * Validates that the `chains` property of a {@link SerializedOmnichainIndexingStatusSnapshot}
- * is consistent with the reported `omnichainStatus`.
- */
-export function invariant_serializedOmnichainSnapshotHasValidChains(
-  ctx: ParsePayload<SerializedOmnichainIndexingStatusSnapshot>,
-) {
-  const omnichainSnapshot = ctx.value;
-  const chains = Object.values(omnichainSnapshot.chains);
-  let hasValidChains = false;
-
-  switch (omnichainSnapshot.omnichainStatus) {
-    case OmnichainIndexingStatusIds.Unstarted:
-      hasValidChains = checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotUnstarted(chains);
-      break;
-
-    case OmnichainIndexingStatusIds.Backfill:
-      hasValidChains = checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotBackfill(chains);
-      break;
-
-    case OmnichainIndexingStatusIds.Completed:
-      hasValidChains = checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotCompleted(chains);
-      break;
-
-    case OmnichainIndexingStatusIds.Following:
-      hasValidChains = checkChainIndexingStatusSnapshotsForOmnichainStatusSnapshotFollowing(chains);
-      break;
-  }
-
-  if (!hasValidChains) {
-    ctx.issues.push({
-      code: "custom",
-      input: omnichainSnapshot,
-      message: `"chains" are not consistent with the reported '${omnichainSnapshot.omnichainStatus}' "omnichainStatus"`,
-    });
-  }
-}

packages/ensnode-sdk/src/api/indexing-status/deserialize.ts

@@ -1,16 +1,43 @@
-import { prettifyError } from "zod/v4";
+import { prettifyError, z } from "zod/v4";
 
-import type { IndexingStatusResponse } from "./response";
+import { buildUnvalidatedRealtimeIndexingStatusProjection } from "../../ensindexer/indexing-status/deserialize/realtime-indexing-status-projection";
+import { type IndexingStatusResponse, IndexingStatusResponseCodes } from "./response";
 import type { SerializedIndexingStatusResponse } from "./serialized-response";
-import { makeIndexingStatusResponseSchema } from "./zod-schemas";
+import {
+  makeIndexingStatusResponseSchema,
+  makeSerializedIndexingStatusResponseSchema,
+} from "./zod-schemas";
+
+/**
+ * Build unvalidated indexing status response to be validated.
+ *
+ * Return type is intentionally "unknown" to enforce validation by
+ * {@link makeIndexingStatusResponseSchema} call.
+ */
+function buildUnvalidatedIndexingStatusResponse(
+  serializedResponse: SerializedIndexingStatusResponse,
+): unknown {
+  if (serializedResponse.responseCode === IndexingStatusResponseCodes.Error) {
+    return serializedResponse;
+  }
+
+  const { responseCode, realtimeProjection } = serializedResponse;
+
+  return {
+    responseCode,
+    realtimeProjection: buildUnvalidatedRealtimeIndexingStatusProjection(realtimeProjection),
+  };
+}
 
 /**
  * Deserialize a {@link IndexingStatusResponse} object.
  */
 export function deserializeIndexingStatusResponse(
   maybeResponse: SerializedIndexingStatusResponse,
 ): IndexingStatusResponse {
-  const parsed = makeIndexingStatusResponseSchema().safeParse(maybeResponse);
+  const parsed = makeSerializedIndexingStatusResponseSchema()
+    .pipe(z.preprocess(buildUnvalidatedIndexingStatusResponse, makeIndexingStatusResponseSchema()))
+    .safeParse(maybeResponse);
 
   if (parsed.error) {
     throw new Error(`Cannot deserialize IndexingStatusResponse:\n${prettifyError(parsed.error)}\n`);

packages/ensnode-sdk/src/api/indexing-status/zod-schemas.ts

@@ -1,12 +1,19 @@
 import { z } from "zod/v4";
 
-import { makeRealtimeIndexingStatusProjectionSchema } from "../../ensindexer/indexing-status/zod-schemas";
+import {
+  makeRealtimeIndexingStatusProjectionSchema,
+  makeSerializedRealtimeIndexingStatusProjectionSchema,
+} from "../../ensindexer/indexing-status/schema/realtime-indexing-status-projection";
 import {
   type IndexingStatusResponse,
   IndexingStatusResponseCodes,
   type IndexingStatusResponseError,
   type IndexingStatusResponseOk,
 } from "./response";
+import {
+  SerializedIndexingStatusResponse,
+  SerializedIndexingStatusResponseOk,
+} from "./serialized-response";
 
 /**
  * Schema for {@link IndexingStatusResponseOk}
@@ -19,6 +26,17 @@ export const makeIndexingStatusResponseOkSchema = (
     realtimeProjection: makeRealtimeIndexingStatusProjectionSchema(valueLabel),
   });
 
+/**
+ * Schema for {@link SerializedIndexingStatusResponseOk}
+ **/
+export const makeSerializedIndexingStatusResponseOkSchema = (
+  valueLabel: string = "Serialized Indexing Status Response OK",
+) =>
+  z.strictObject({
+    responseCode: z.literal(IndexingStatusResponseCodes.Ok),
+    realtimeProjection: makeSerializedRealtimeIndexingStatusProjectionSchema(valueLabel),
+  });
+
 /**
  * Schema for {@link IndexingStatusResponseError}
  **/
@@ -37,3 +55,14 @@ export const makeIndexingStatusResponseSchema = (valueLabel: string = "Indexing
     makeIndexingStatusResponseOkSchema(valueLabel),
     makeIndexingStatusResponseErrorSchema(valueLabel),
   ]);
+
+/**
+ * Schema for {@link SerializedIndexingStatusResponse}
+ **/
+export const makeSerializedIndexingStatusResponseSchema = (
+  valueLabel: string = "Serialized Indexing Status Response",
+) =>
+  z.discriminatedUnion("responseCode", [
+    makeSerializedIndexingStatusResponseOkSchema(valueLabel),
+    makeIndexingStatusResponseErrorSchema(valueLabel),
+  ]);

packages/ensnode-sdk/src/ensindexer/indexing-status/chain-indexing-status-snapshot.mocks.ts

@@ -0,0 +1,122 @@
+import {
+  earlierBlockRef,
+  earliestBlockRef,
+  laterBlockRef,
+  latestBlockRef,
+} from "./block-refs.mock";
+import {
+  ChainIndexingConfigTypeIds,
+  ChainIndexingStatusIds,
+  type ChainIndexingStatusSnapshot,
+  type ChainIndexingStatusSnapshotBackfill,
+  type ChainIndexingStatusSnapshotCompleted,
+  type ChainIndexingStatusSnapshotFollowing,
+  type ChainIndexingStatusSnapshotQueued,
+} from "./chain-indexing-status-snapshot";
+import type { ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill } from "./omnichain-indexing-status-snapshot";
+
+export const chainStatusesQueued = [
+  {
+    chainStatus: ChainIndexingStatusIds.Queued,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: latestBlockRef,
+    },
+  },
+  {
+    chainStatus: ChainIndexingStatusIds.Queued,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: laterBlockRef,
+    },
+  },
+] satisfies ChainIndexingStatusSnapshotQueued[];
+
+export const chainStatusesCompleted = [
+  {
+    chainStatus: ChainIndexingStatusIds.Completed,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earlierBlockRef,
+
+      endBlock: latestBlockRef,
+    },
+    latestIndexedBlock: latestBlockRef,
+  },
+
+  {
+    chainStatus: ChainIndexingStatusIds.Completed,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: laterBlockRef,
+    },
+    latestIndexedBlock: laterBlockRef,
+  },
+] satisfies ChainIndexingStatusSnapshotCompleted[];
+
+export const chainStatusesBackfillMixed = [
+  {
+    chainStatus: ChainIndexingStatusIds.Queued,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: latestBlockRef,
+    },
+  } satisfies ChainIndexingStatusSnapshotQueued,
+
+  {
+    chainStatus: ChainIndexingStatusIds.Backfill,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Indefinite,
+      startBlock: earliestBlockRef,
+    },
+    latestIndexedBlock: laterBlockRef,
+    backfillEndBlock: latestBlockRef,
+  } satisfies ChainIndexingStatusSnapshotBackfill,
+
+  {
+    chainStatus: ChainIndexingStatusIds.Completed,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: laterBlockRef,
+    },
+    latestIndexedBlock: laterBlockRef,
+  } satisfies ChainIndexingStatusSnapshotCompleted,
+] satisfies ChainIndexingStatusSnapshotForOmnichainIndexingStatusSnapshotBackfill[];
+
+export const chainStatusesFollowingMixed = [
+  {
+    chainStatus: ChainIndexingStatusIds.Following,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Indefinite,
+      startBlock: earlierBlockRef,
+    },
+    latestIndexedBlock: laterBlockRef,
+    latestKnownBlock: latestBlockRef,
+  } satisfies ChainIndexingStatusSnapshotFollowing,
+
+  {
+    chainStatus: ChainIndexingStatusIds.Backfill,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: latestBlockRef,
+    },
+    latestIndexedBlock: laterBlockRef,
+    backfillEndBlock: latestBlockRef,
+  } satisfies ChainIndexingStatusSnapshotBackfill,
+
+  {
+    chainStatus: ChainIndexingStatusIds.Completed,
+    config: {
+      configType: ChainIndexingConfigTypeIds.Definite,
+      startBlock: earliestBlockRef,
+      endBlock: laterBlockRef,
+    },
+    latestIndexedBlock: laterBlockRef,
+  } satisfies ChainIndexingStatusSnapshotCompleted,
+] satisfies ChainIndexingStatusSnapshot[];

packages/ensnode-sdk/src/ensindexer/indexing-status/chain-indexing-status-snapshot.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import { earlierBlockRef, laterBlockRef } from "./block-refs.mock";
+import {
+  type ChainIndexingConfigDefinite,
+  type ChainIndexingConfigIndefinite,
+  ChainIndexingConfigTypeIds,
+  createIndexingConfig,
+} from "./chain-indexing-status-snapshot";
+
+describe("Chain Indexing Status Snapshot", () => {
+  describe("createIndexingConfig", () => {
+    it("returns 'definite' indexer config if the endBlock exists", () => {
+      // arrange
+      const startBlock = earlierBlockRef;
+      const endBlock = laterBlockRef;
+
+      // act
+      const indexingConfig = createIndexingConfig(startBlock, endBlock);
+
+      // assert
+      expect(indexingConfig).toStrictEqual({
+        configType: ChainIndexingConfigTypeIds.Definite,
+        startBlock: earlierBlockRef,
+        endBlock: laterBlockRef,
+      } satisfies ChainIndexingConfigDefinite);
+    });
+
+    it("returns 'indefinite' indexer config if the endBlock does not exist", () => {
+      // arrange
+      const startBlock = earlierBlockRef;
+      const endBlock = null;
+
+      // act
+      const indexingConfig = createIndexingConfig(startBlock, endBlock);
+
+      // assert
+      expect(indexingConfig).toStrictEqual({
+        configType: ChainIndexingConfigTypeIds.Indefinite,
+        startBlock: earlierBlockRef,
+      } satisfies ChainIndexingConfigIndefinite);
+    });
+  });
+});