@ensnode/ponder-sdk 1.6.0 → 1.8.0

package/dist/index.d.cts

@@ -21,6 +21,10 @@ type BlockRef = z.infer<typeof schemaBlockRef>;
 /**
  * Compare two {@link BlockRef} objects to check
  * if blockA is before blockB.
+ *
+ * Ordering is determined by block number, which is the canonical
+ * ordering on a single chain. Timestamp is not used because EVM
+ * chains allow consecutive blocks to share the same timestamp.
  */
 declare function isBlockRefBefore(blockA: BlockRef, blockB: BlockRef): boolean;
 /**
@@ -114,8 +118,9 @@ declare function buildBlockNumberRange(startBlock?: BlockNumber, endBlock?: Bloc
  * Merge multiple block number ranges into a single range.
  *
  * The resulting range is a union that covers all input ranges:
- * - Uses the minimum defined start block (undefined if no ranges define a start block)
- * - Uses the maximum defined end block (undefined if no ranges define an end block)
+ * - Uses the minimum start block when every input range has a start block
+ * - Uses the maximum end block when every input range has an end block
+ * - Leaves a side unbounded when any input range is unbounded on that side
  *
  * Returns an unbounded range if no ranges are provided.
  *
@@ -205,7 +210,7 @@ type ChainId = z.infer<typeof schemaChainId>;
 type ChainIdString = string;
 
 /**
- * Ponder Application Commands
+ * Ponder app commands
  *
  * Represents the commands that can be used to start a Ponder app.
  */
@@ -214,6 +219,18 @@ declare const PonderAppCommands: {
     readonly Start: "start";
 };
 type PonderAppCommand = (typeof PonderAppCommands)[keyof typeof PonderAppCommands];
+/**
+ * Ponder app context
+ *
+ * Represents the internal context of a local Ponder app.
+ */
+interface PonderAppContext {
+    /**
+     * Command used to start the Ponder app.
+     */
+    command: PonderAppCommand;
+}
+
 /**
  * Ponder Indexing Orderings
  *
@@ -409,6 +426,101 @@ declare class PonderClient {
     status(): Promise<PonderIndexingStatus>;
 }
 
+/**
+ * A utility type that makes all properties of a type optional recursively,
+ * including nested objects and arrays.
+ *
+ * @example
+ * ```typescript
+ * type Config = {
+ *   a: string;
+ *   b: {
+ *     x: number;
+ *     y: { z: boolean };
+ *   };
+ *   c: { id: string }[];
+ * }
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // Results in:
+ * // {
+ * //   a?: string;
+ * //   b?: {
+ * //     x?: number;
+ * //     y?: { z?: boolean };
+ * //   };
+ * //   c?: { id?: string }[];
+ * // }
+ *
+ * // Usage:
+ * const update: PartialConfig = { b: { y: { z: true } } };
+ * ```
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Helper type to represent an unvalidated version of a business layer type `T`,
+ * where all properties are optional.
+ *
+ * This is useful for building a validated object `T` from partial input,
+ * where the input may be missing required fields or have fields that
+ * are not yet validated.
+ *
+ * For example, transforming serialized representation of type `T` into
+ * an unvalidated version of `T` that can be later validated against
+ * defined business rules and constraints.
+ *
+ * ```ts
+ * function buildUnvalidatedValue(serialized: SerializedChainId): Unvalidated<ChainId> {
+ *  // transform serialized chainId into unvalidated number (e.g. parseInt)
+ *  return parseInt(serialized, 10);
+ * }
+ *
+ * // Later, we can validate the unvalidated value against our business rules
+ * function validateChainId(unvalidatedChainId: Unvalidated<ChainId>): ChainId {
+ *   if (typeof unvalidatedChainId !== "number" || unvalidatedChainId <= 0) {
+ *     throw new Error("Invalid ChainId");
+ *   }
+ *
+ *   return unvalidatedChainId as ChainId;
+ * }
+ *
+ * ```
+ */
+type Unvalidated<T> = DeepPartial<T>;
+
+/**
+ * This module provides functionality to deserialize the "raw" context of
+ * a local Ponder app into a validated Ponder App Context.
+ *
+ * The "raw" context is injected by Ponder at runtime as
+ * the `PONDER_COMMON` global variable.
+ *
+ * @see https://github.com/ponder-sh/ponder/blob/6fcc15d4234e43862cb6e21c05f3c57f4c2f7464/packages/core/src/internal/common.ts#L7-L15
+ */
+
+/**
+ * Type representing the "raw" context of a local Ponder app.
+ */
+declare const schemaRawPonderAppContext: z.ZodObject<{
+    options: z.ZodObject<{
+        command: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Type representing the "raw" context of a local Ponder app.
+ */
+type RawPonderAppContext = z.infer<typeof schemaRawPonderAppContext>;
+/**
+ * Deserialize and validate a Raw Ponder App Context.
+ *
+ * @param unvalidatedRawPonderAppContext Raw Ponder App Context to be validated.
+ * @returns Deserialized and validated Ponder App Context.
+ * @throws Error if data cannot be deserialized into a valid Ponder App Context.
+ */
+declare function deserializePonderAppContext(unvalidatedRawPonderAppContext: Unvalidated<RawPonderAppContext>): PonderAppContext;
+
 /**
  * Chain indexing config
  *
@@ -526,14 +638,21 @@ declare class LocalPonderClient extends PonderClient {
      * - Does not include entries for non-indexed chains.
      */
     private cachedPublicClients;
+    /**
+     * Ponder App Context
+     *
+     * The internal context of the local Ponder app.
+     */
+    private ponderAppContext;
     /**
      * @param localPonderAppUrl URL of the local Ponder app to connect to.
      * @param indexedChainIds Configured indexed chain IDs which are used to validate and filter the Ponder app metadata to only include entries for indexed chains.
      * @param indexedBlockranges Configured indexing blockrange for each indexed chain.
      * @param ponderPublicClients All cached public clients provided by the local Ponder app
      *                            (may include non-indexed chains).
+     * @param ponderAppContext The internal context of the local Ponder app.
      */
-    constructor(localPonderAppUrl: URL, indexedChainIds: Set<ChainId>, indexedBlockranges: Map<ChainId, BlockNumberRangeWithStartBlock>, ponderPublicClients: Record<ChainIdString, CachedPublicClient>);
+    constructor(localPonderAppUrl: URL, indexedChainIds: Set<ChainId>, indexedBlockranges: Map<ChainId, BlockNumberRangeWithStartBlock>, ponderPublicClients: Record<ChainIdString, CachedPublicClient>, ponderAppContext: PonderAppContext);
     /**
      * Get the blockrange that is configured to be indexed for a specific chain ID.
      *
@@ -558,6 +677,10 @@ declare class LocalPonderClient extends PonderClient {
      * @throws Error if the response could not be fetched or was invalid.
      */
     metrics(): Promise<LocalPonderIndexingMetrics>;
+    /**
+     * Indicates whether the local Ponder app is running in dev mode.
+     */
+    get isInDevMode(): boolean;
     /**
      * Builds a map of cached public clients based on the Ponder cached public clients.
      *
@@ -636,4 +759,4 @@ declare const schemaUnixTimestamp: z.ZodNumber;
  */
 type UnixTimestamp = z.infer<typeof schemaUnixTimestamp>;
 
-export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };
+export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderAppContext, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type RawPonderAppContext, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, deserializePonderAppContext, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };

package/dist/index.d.ts

@@ -21,6 +21,10 @@ type BlockRef = z.infer<typeof schemaBlockRef>;
 /**
  * Compare two {@link BlockRef} objects to check
  * if blockA is before blockB.
+ *
+ * Ordering is determined by block number, which is the canonical
+ * ordering on a single chain. Timestamp is not used because EVM
+ * chains allow consecutive blocks to share the same timestamp.
  */
 declare function isBlockRefBefore(blockA: BlockRef, blockB: BlockRef): boolean;
 /**
@@ -114,8 +118,9 @@ declare function buildBlockNumberRange(startBlock?: BlockNumber, endBlock?: Bloc
  * Merge multiple block number ranges into a single range.
  *
  * The resulting range is a union that covers all input ranges:
- * - Uses the minimum defined start block (undefined if no ranges define a start block)
- * - Uses the maximum defined end block (undefined if no ranges define an end block)
+ * - Uses the minimum start block when every input range has a start block
+ * - Uses the maximum end block when every input range has an end block
+ * - Leaves a side unbounded when any input range is unbounded on that side
  *
  * Returns an unbounded range if no ranges are provided.
  *
@@ -205,7 +210,7 @@ type ChainId = z.infer<typeof schemaChainId>;
 type ChainIdString = string;
 
 /**
- * Ponder Application Commands
+ * Ponder app commands
  *
  * Represents the commands that can be used to start a Ponder app.
  */
@@ -214,6 +219,18 @@ declare const PonderAppCommands: {
     readonly Start: "start";
 };
 type PonderAppCommand = (typeof PonderAppCommands)[keyof typeof PonderAppCommands];
+/**
+ * Ponder app context
+ *
+ * Represents the internal context of a local Ponder app.
+ */
+interface PonderAppContext {
+    /**
+     * Command used to start the Ponder app.
+     */
+    command: PonderAppCommand;
+}
+
 /**
  * Ponder Indexing Orderings
  *
@@ -409,6 +426,101 @@ declare class PonderClient {
     status(): Promise<PonderIndexingStatus>;
 }
 
+/**
+ * A utility type that makes all properties of a type optional recursively,
+ * including nested objects and arrays.
+ *
+ * @example
+ * ```typescript
+ * type Config = {
+ *   a: string;
+ *   b: {
+ *     x: number;
+ *     y: { z: boolean };
+ *   };
+ *   c: { id: string }[];
+ * }
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // Results in:
+ * // {
+ * //   a?: string;
+ * //   b?: {
+ * //     x?: number;
+ * //     y?: { z?: boolean };
+ * //   };
+ * //   c?: { id?: string }[];
+ * // }
+ *
+ * // Usage:
+ * const update: PartialConfig = { b: { y: { z: true } } };
+ * ```
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Helper type to represent an unvalidated version of a business layer type `T`,
+ * where all properties are optional.
+ *
+ * This is useful for building a validated object `T` from partial input,
+ * where the input may be missing required fields or have fields that
+ * are not yet validated.
+ *
+ * For example, transforming serialized representation of type `T` into
+ * an unvalidated version of `T` that can be later validated against
+ * defined business rules and constraints.
+ *
+ * ```ts
+ * function buildUnvalidatedValue(serialized: SerializedChainId): Unvalidated<ChainId> {
+ *  // transform serialized chainId into unvalidated number (e.g. parseInt)
+ *  return parseInt(serialized, 10);
+ * }
+ *
+ * // Later, we can validate the unvalidated value against our business rules
+ * function validateChainId(unvalidatedChainId: Unvalidated<ChainId>): ChainId {
+ *   if (typeof unvalidatedChainId !== "number" || unvalidatedChainId <= 0) {
+ *     throw new Error("Invalid ChainId");
+ *   }
+ *
+ *   return unvalidatedChainId as ChainId;
+ * }
+ *
+ * ```
+ */
+type Unvalidated<T> = DeepPartial<T>;
+
+/**
+ * This module provides functionality to deserialize the "raw" context of
+ * a local Ponder app into a validated Ponder App Context.
+ *
+ * The "raw" context is injected by Ponder at runtime as
+ * the `PONDER_COMMON` global variable.
+ *
+ * @see https://github.com/ponder-sh/ponder/blob/6fcc15d4234e43862cb6e21c05f3c57f4c2f7464/packages/core/src/internal/common.ts#L7-L15
+ */
+
+/**
+ * Type representing the "raw" context of a local Ponder app.
+ */
+declare const schemaRawPonderAppContext: z.ZodObject<{
+    options: z.ZodObject<{
+        command: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Type representing the "raw" context of a local Ponder app.
+ */
+type RawPonderAppContext = z.infer<typeof schemaRawPonderAppContext>;
+/**
+ * Deserialize and validate a Raw Ponder App Context.
+ *
+ * @param unvalidatedRawPonderAppContext Raw Ponder App Context to be validated.
+ * @returns Deserialized and validated Ponder App Context.
+ * @throws Error if data cannot be deserialized into a valid Ponder App Context.
+ */
+declare function deserializePonderAppContext(unvalidatedRawPonderAppContext: Unvalidated<RawPonderAppContext>): PonderAppContext;
+
 /**
  * Chain indexing config
  *
@@ -526,14 +638,21 @@ declare class LocalPonderClient extends PonderClient {
      * - Does not include entries for non-indexed chains.
      */
     private cachedPublicClients;
+    /**
+     * Ponder App Context
+     *
+     * The internal context of the local Ponder app.
+     */
+    private ponderAppContext;
     /**
      * @param localPonderAppUrl URL of the local Ponder app to connect to.
      * @param indexedChainIds Configured indexed chain IDs which are used to validate and filter the Ponder app metadata to only include entries for indexed chains.
      * @param indexedBlockranges Configured indexing blockrange for each indexed chain.
      * @param ponderPublicClients All cached public clients provided by the local Ponder app
      *                            (may include non-indexed chains).
+     * @param ponderAppContext The internal context of the local Ponder app.
      */
-    constructor(localPonderAppUrl: URL, indexedChainIds: Set<ChainId>, indexedBlockranges: Map<ChainId, BlockNumberRangeWithStartBlock>, ponderPublicClients: Record<ChainIdString, CachedPublicClient>);
+    constructor(localPonderAppUrl: URL, indexedChainIds: Set<ChainId>, indexedBlockranges: Map<ChainId, BlockNumberRangeWithStartBlock>, ponderPublicClients: Record<ChainIdString, CachedPublicClient>, ponderAppContext: PonderAppContext);
     /**
      * Get the blockrange that is configured to be indexed for a specific chain ID.
      *
@@ -558,6 +677,10 @@ declare class LocalPonderClient extends PonderClient {
      * @throws Error if the response could not be fetched or was invalid.
      */
     metrics(): Promise<LocalPonderIndexingMetrics>;
+    /**
+     * Indicates whether the local Ponder app is running in dev mode.
+     */
+    get isInDevMode(): boolean;
     /**
      * Builds a map of cached public clients based on the Ponder cached public clients.
      *
@@ -636,4 +759,4 @@ declare const schemaUnixTimestamp: z.ZodNumber;
  */
 type UnixTimestamp = z.infer<typeof schemaUnixTimestamp>;
 
-export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };
+export { type BlockNumber, type BlockNumberRange, type BlockNumberRangeBounded, type BlockNumberRangeLeftBounded, type BlockNumberRangeRightBounded, type BlockNumberRangeUnbounded, type BlockNumberRangeWithStartBlock, type BlockRef, type BlockRefRange, type BlockRefRangeBounded, type BlockRefRangeLeftBounded, type BlockRefRangeRightBounded, type BlockRefRangeUnbounded, type BlockRefRangeWithStartBlock, type ChainId, type ChainIdString, type ChainIndexingConfig, type ChainIndexingMetrics, type ChainIndexingMetricsCompleted, type ChainIndexingMetricsHistorical, type ChainIndexingMetricsRealtime, type ChainIndexingState, ChainIndexingStates, type ChainIndexingStatus, type LocalChainIndexingMetrics, type LocalChainIndexingMetricsHistorical, LocalPonderClient, type LocalPonderIndexingMetrics, type PonderAppCommand, PonderAppCommands, type PonderAppContext, type PonderApplicationSettings, type PonderBlockNumberRange, PonderClient, type PonderIndexingMetrics, type PonderIndexingOrdering, PonderIndexingOrderings, type PonderIndexingStatus, type RangeType, RangeTypeIds, type RawPonderAppContext, type UnixTimestamp, buildBlockNumberRange, buildBlockRefRange, deserializePonderAppContext, isBlockRefBefore, isBlockRefBeforeOrEqualTo, isBlockRefEqualTo, mergeBlockNumberRanges, schemaBlockNumber, schemaBlockRef, schemaChainId, schemaInteger, schemaNonnegativeInteger, schemaNonnegativeNumber, schemaNumber, schemaPositiveInteger, schemaPositiveNumber, schemaUnixTimestamp };

package/dist/index.js

@@ -498,7 +498,7 @@ var schemaBlockRef = z2.object({
   timestamp: schemaUnixTimestamp
 });
 function isBlockRefBefore(blockA, blockB) {
-  return blockA.number < blockB.number && blockA.timestamp < blockB.timestamp;
+  return blockA.number < blockB.number;
 }
 function isBlockRefEqualTo(blockA, blockB) {
   return blockA.number === blockB.number && blockA.timestamp === blockB.timestamp;
@@ -552,17 +552,28 @@ function mergeBlockNumberRanges(...ranges) {
   }
   let minStartBlock;
   let maxEndBlock;
+  let hasUnboundedStart = false;
+  let hasUnboundedEnd = false;
   for (const range of ranges) {
-    if (range.startBlock !== void 0) {
-      if (minStartBlock === void 0 || range.startBlock < minStartBlock) {
-        minStartBlock = range.startBlock;
-      }
+    if (range.startBlock === void 0) {
+      hasUnboundedStart = true;
+    } else if (minStartBlock === void 0 || range.startBlock < minStartBlock) {
+      minStartBlock = range.startBlock;
     }
-    if (range.endBlock !== void 0) {
-      if (maxEndBlock === void 0 || range.endBlock > maxEndBlock) {
-        maxEndBlock = range.endBlock;
-      }
+    if (range.endBlock === void 0) {
+      hasUnboundedEnd = true;
+    } else if (maxEndBlock === void 0 || range.endBlock > maxEndBlock) {
+      maxEndBlock = range.endBlock;
     }
+    if (hasUnboundedStart && hasUnboundedEnd) {
+      return buildBlockNumberRange(void 0, void 0);
+    }
+  }
+  if (hasUnboundedStart) {
+    minStartBlock = void 0;
+  }
+  if (hasUnboundedEnd) {
+    maxEndBlock = void 0;
   }
   return buildBlockNumberRange(minStartBlock, maxEndBlock);
 }
@@ -604,10 +615,6 @@ var schemaChainId = schemaPositiveInteger;
 import { prettifyError, z as z4 } from "zod/v4";
 
 // src/indexing-metrics.ts
-var PonderAppCommands = {
-  Dev: "dev",
-  Start: "start"
-};
 var PonderIndexingOrderings = {
   Omnichain: "omnichain"
 };
@@ -617,6 +624,12 @@ var ChainIndexingStates = {
   Realtime: "realtime"
 };
 
+// src/ponder-app-context.ts
+var PonderAppCommands = {
+  Dev: "dev",
+  Start: "start"
+};
+
 // src/deserialize/chains.ts
 import { z as z3 } from "zod/v4";
 import { formatError } from "zod/v4/core";
@@ -1059,6 +1072,29 @@ var PonderClient = class {
   }
 };
 
+// src/deserialize/ponder-app-context.ts
+import { prettifyError as prettifyError3, z as z6 } from "zod/v4";
+var schemaRawPonderAppContext = z6.object({
+  options: z6.object({
+    command: z6.string()
+  })
+});
+var schemaPonderAppContext = z6.object({
+  command: z6.enum(PonderAppCommands)
+});
+function buildUnvalidatedPonderAppContext(rawPonderAppContext) {
+  return {
+    command: rawPonderAppContext.options.command
+  };
+}
+function deserializePonderAppContext(unvalidatedRawPonderAppContext) {
+  const validation = schemaRawPonderAppContext.transform(buildUnvalidatedPonderAppContext).pipe(schemaPonderAppContext).safeParse(unvalidatedRawPonderAppContext);
+  if (!validation.success) {
+    throw new Error(`Invalid raw Ponder App Context: ${prettifyError3(validation.error)}`);
+  }
+  return validation.data;
+}
+
 // src/local-ponder-client.ts
 var LocalPonderClient = class _LocalPonderClient extends PonderClient {
   /**
@@ -1090,14 +1126,21 @@ var LocalPonderClient = class _LocalPonderClient extends PonderClient {
    * - Does not include entries for non-indexed chains.
    */
   cachedPublicClients;
+  /**
+   * Ponder App Context
+   *
+   * The internal context of the local Ponder app.
+   */
+  ponderAppContext;
   /**
    * @param localPonderAppUrl URL of the local Ponder app to connect to.
    * @param indexedChainIds Configured indexed chain IDs which are used to validate and filter the Ponder app metadata to only include entries for indexed chains.
    * @param indexedBlockranges Configured indexing blockrange for each indexed chain.
    * @param ponderPublicClients All cached public clients provided by the local Ponder app
    *                            (may include non-indexed chains).
+   * @param ponderAppContext The internal context of the local Ponder app.
    */
-  constructor(localPonderAppUrl, indexedChainIds, indexedBlockranges, ponderPublicClients) {
+  constructor(localPonderAppUrl, indexedChainIds, indexedBlockranges, ponderPublicClients, ponderAppContext) {
     super(localPonderAppUrl);
     this.indexedChainIds = indexedChainIds;
     const cachedPublicClients = _LocalPonderClient.buildCachedPublicClients(ponderPublicClients);
@@ -1111,6 +1154,7 @@ var LocalPonderClient = class _LocalPonderClient extends PonderClient {
       cachedPublicClients,
       "Cached Public Clients"
     );
+    this.ponderAppContext = ponderAppContext;
   }
   /**
    * Get the blockrange that is configured to be indexed for a specific chain ID.
@@ -1164,6 +1208,12 @@ var LocalPonderClient = class _LocalPonderClient extends PonderClient {
     });
     return localMetrics;
   }
+  /**
+   * Indicates whether the local Ponder app is running in dev mode.
+   */
+  get isInDevMode() {
+    return this.ponderAppContext.command === PonderAppCommands.Dev;
+  }
   /**
    * Builds a map of cached public clients based on the Ponder cached public clients.
    *
@@ -1277,6 +1327,7 @@ export {
   RangeTypeIds,
   buildBlockNumberRange,
   buildBlockRefRange,
+  deserializePonderAppContext,
   isBlockRefBefore,
   isBlockRefBeforeOrEqualTo,
   isBlockRefEqualTo,