@ensnode/ensnode-sdk 1.13.1 → 1.15.0

package/dist/index.cjs

@@ -162,9 +162,11 @@ __export(index_exports, {
   getTimestampForLowestOmnichainStartBlock: () => getTimestampForLowestOmnichainStartBlock,
   hasNullByte: () => hasNullByte,
   hasOmnigraphApiConfigSupport: () => hasOmnigraphApiConfigSupport,
+  hasOmnigraphApiIndexingStatusSupport: () => hasOmnigraphApiIndexingStatusSupport,
   hasRegistrarActionsConfigSupport: () => hasRegistrarActionsConfigSupport,
   hasRegistrarActionsIndexingStatusSupport: () => hasRegistrarActionsIndexingStatusSupport,
   hasSubgraphApiConfigSupport: () => hasSubgraphApiConfigSupport,
+  hasSubgraphApiIndexingStatusSupport: () => hasSubgraphApiIndexingStatusSupport,
   interpretAddress: () => interpretAddress,
   interpretAddressRecordValue: () => interpretAddressRecordValue,
   interpretContenthashValue: () => interpretContenthashValue,
@@ -636,6 +638,7 @@ var PluginName = /* @__PURE__ */ ((PluginName2) => {
   PluginName2["Registrars"] = "registrars";
   PluginName2["TokenScope"] = "tokenscope";
   PluginName2["ENSv2"] = "ensv2";
+  PluginName2["Unigraph"] = "unigraph";
   return PluginName2;
 })(PluginName || {});
 
@@ -1764,14 +1767,26 @@ function invariant_realtimeIndexingStatusProjectionWorstCaseDistanceIsCorrect(ct
   }
 }
 var makeRealtimeIndexingStatusProjectionSchema = (valueLabel = "Realtime Indexing Status Projection") => import_v413.z.object({
-  projectedAt: makeUnixTimestampSchema(valueLabel),
-  worstCaseDistance: makeDurationSchema(valueLabel),
-  snapshot: makeCrossChainIndexingStatusSnapshotSchema(valueLabel)
+  projectedAt: makeUnixTimestampSchema(valueLabel).describe(
+    "The timestamp representing 'now' as of the time this projection was generated."
+  ),
+  worstCaseDistance: makeDurationSchema(valueLabel).describe(
+    "The distance between `projectedAt` and `snapshot.slowestChainIndexingCursor` in seconds. This is a worst-case distance because it assumes no indexing progress has been made since `snapshot.snapshotTime` and that each indexed chain has added a new block as of `projectedAt`."
+  ),
+  snapshot: makeCrossChainIndexingStatusSnapshotSchema(valueLabel).describe(
+    "The cross-chain indexing status snapshot that this projection is based on."
+  )
 }).check(invariant_realtimeIndexingStatusProjectionProjectedAtIsAfterOrEqualToSnapshotTime).check(invariant_realtimeIndexingStatusProjectionWorstCaseDistanceIsCorrect);
 var makeSerializedRealtimeIndexingStatusProjectionSchema = (valueLabel = "Value") => import_v413.z.object({
-  snapshot: makeSerializedCrossChainIndexingStatusSnapshotSchema(valueLabel),
-  projectedAt: makeUnixTimestampSchema(valueLabel),
-  worstCaseDistance: makeDurationSchema(valueLabel)
+  snapshot: makeSerializedCrossChainIndexingStatusSnapshotSchema(valueLabel).describe(
+    "The cross-chain indexing status snapshot that this projection is based on."
+  ),
+  projectedAt: makeUnixTimestampSchema(valueLabel).describe(
+    "The timestamp representing 'now' as of the time this projection was generated."
+  ),
+  worstCaseDistance: makeDurationSchema(valueLabel).describe(
+    "The distance between `projectedAt` and `snapshot.slowestChainIndexingCursor` in seconds. This is a worst-case distance because it assumes no indexing progress has been made since `snapshot.snapshotTime` and that each indexed chain has added a new block as of `projectedAt`."
+  )
 });
 
 // src/indexing-status/deserialize/cross-chain-indexing-status-snapshot.ts
@@ -2953,8 +2968,8 @@ function getNameTokenOwnership(namespaceId, name, owner) {
 // src/ensnode/api/shared/errors/zod-schemas.ts
 var import_v431 = require("zod/v4");
 var makeErrorResponseSchema = () => import_v431.z.object({
-  message: import_v431.z.string(),
-  details: import_v431.z.optional(import_v431.z.unknown())
+  message: import_v431.z.string().describe("A description of the error that occurred."),
+  details: import_v431.z.optional(import_v431.z.unknown()).describe("Additional details about the error.")
 });
 
 // src/ensnode/api/name-tokens/response.ts
@@ -4395,15 +4410,28 @@ function isResolvedIdentity(identity) {
   return identity.resolutionStatus !== ResolutionStatusIds.Unresolved;
 }
 
+// src/ensnode/api/prerequisites.ts
+function hasBackfillCompleted(indexingStatus) {
+  const supported = indexingStatus === OmnichainIndexingStatusIds.Completed || indexingStatus === OmnichainIndexingStatusIds.Following;
+  if (supported) return { supported };
+  return {
+    supported: false,
+    reason: `The connected ENSNode's Indexing Status must be "${OmnichainIndexingStatusIds.Completed}" or "${OmnichainIndexingStatusIds.Following}". Currently, it is "${indexingStatus}".`
+  };
+}
+
 // src/omnigraph-api/prerequisites.ts
 function hasOmnigraphApiConfigSupport(config) {
-  const supported = config.plugins.includes("ensv2" /* ENSv2 */);
+  const supported = config.plugins.includes("unigraph" /* Unigraph */) || config.plugins.includes("ensv2" /* ENSv2 */);
   if (supported) return { supported };
   return {
     supported: false,
-    reason: `The connected ENSNode's Config must have the '${"ensv2" /* ENSv2 */}' plugin enabled.`
+    reason: `The connected ENSNode's Config must have the '${"unigraph" /* Unigraph */}' plugin enabled.`
   };
 }
+function hasOmnigraphApiIndexingStatusSupport(indexingStatus) {
+  return hasBackfillCompleted(indexingStatus);
+}
 
 // src/registrars/registration-expiration.ts
 function isRegistrationExpired(info, now) {
@@ -4683,6 +4711,30 @@ var SWRCache = class {
     }
     return this.cache.result;
   }
+  /**
+   * Synchronously returns the most recently cached result without triggering revalidation.
+   *
+   * Unlike {@link read}, this method is synchronous and never causes any I/O — it simply
+   * returns whatever value is already in memory. Use this when you need a best-effort
+   * snapshot of the cached value and can tolerate stale data.
+   *
+   * @returns the most recently cached `ValueType`, or an `Error` if the last fetch failed.
+   * @throws if the cache has not been initialized yet (i.e. {@link read} has never been awaited
+   * and `proactivelyInitialize` was not set to `true`).
+   *
+   * @example
+   * ```ts
+   * // Ensure cache is initialized first
+   * await cache.read();
+   *
+   * // Later, peek synchronously without triggering revalidation
+   * const result = cache.peek();
+   * ```
+   */
+  peek() {
+    if (!this.cache) throw new Error("Cache is not initialized yet");
+    return this.cache.result;
+  }
   /**
    * Destroys the background revalidation interval, if exists.
    */
@@ -4761,7 +4813,7 @@ var TtlCache = class {
 
 // src/shared/config/indexed-blockranges.ts
 var import_datasources8 = require("@ensnode/datasources");
-function buildIndexedBlockranges(namespace, pluginsDatasourceNames) {
+function buildIndexedBlockranges(namespace, globalBlockrangeEndBlock, pluginsDatasourceNames) {
   const indexedBlockranges = /* @__PURE__ */ new Map();
   for (const [, datasourceNames] of pluginsDatasourceNames) {
     for (const datasourceName of datasourceNames) {
@@ -4771,9 +4823,12 @@ function buildIndexedBlockranges(namespace, pluginsDatasourceNames) {
       const datasourceContracts = Object.values(datasource.contracts);
       for (const datasourceContract of datasourceContracts) {
         const currentChainIndexedBlockrange = indexedBlockranges.get(datasourceChainId);
+        if (typeof globalBlockrangeEndBlock === "number" && datasourceContract.startBlock > globalBlockrangeEndBlock) {
+          continue;
+        }
         const contractIndexedBlockrange = buildBlockNumberRange(
           datasourceContract.startBlock,
-          datasourceContract.endBlock
+          datasourceContract.endBlock ?? globalBlockrangeEndBlock
         );
         const indexedBlockrange = currentChainIndexedBlockrange ? mergeBlockNumberRanges(currentChainIndexedBlockrange, contractIndexedBlockrange) : contractIndexedBlockrange;
         if (indexedBlockrange.rangeType !== RangeTypeIds.LeftBounded && indexedBlockrange.rangeType !== RangeTypeIds.Bounded) {
@@ -5044,6 +5099,9 @@ function hasSubgraphApiConfigSupport(config) {
     reason: `The connected ENSNode's Config must have the '${"subgraph" /* Subgraph */}' plugin enabled.`
   };
 }
+function hasSubgraphApiIndexingStatusSupport(indexingStatus) {
+  return hasBackfillCompleted(indexingStatus);
+}
 
 // src/tracing/ens-protocol-tracing.ts
 var PROTOCOL_ATTRIBUTE_PREFIX = "ens";