envio 3.6.0 → 3.6.1-subgraph

package/src/UserContext.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Utils from "./Utils.res.mjs";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as Internal from "./Internal.res.mjs";
 import * as Ecosystem from "./Ecosystem.res.mjs";
@@ -12,8 +13,70 @@ import * as InMemoryStore from "./InMemoryStore.res.mjs";
 import * as InMemoryTable from "./InMemoryTable.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+let Suspend = /* @__PURE__ */Primitive_exceptions.create("UserContext.Suspend");
+
+function isSuspend(exn) {
+  return exn.RE_EXN_ID === Suspend;
+}
+
+function makeSyncState() {
+  return {
+    status: "Active",
+    pending: undefined,
+    memo: undefined
+  };
+}
+
+function getPending(sync) {
+  let pending = sync.pending;
+  if (pending !== undefined) {
+    return pending;
+  }
+  let pending$1 = [];
+  sync.pending = pending$1;
+  return pending$1;
+}
+
+function getMemo(sync) {
+  let memo = sync.memo;
+  if (memo !== undefined) {
+    return memo;
+  }
+  let memo$1 = {};
+  sync.memo = memo$1;
+  return memo$1;
+}
+
+function checkStatusOrThrow(params, access) {
+  let exn = params.sync.status;
+  if (typeof exn !== "object") {
+    if (exn === "Active") {
+      return;
+    } else {
+      return ErrorHandling.mkLogAndRaise(Ecosystem.getItemLogger(params.item, params.config.ecosystem), undefined, new Error(`Impossible to access ` + access + ` after the handler is resolved. Make sure you didn't miss an await in the handler.`));
+    }
+  }
+  throw exn._0;
+}
+
+function scheduleAndSuspend(params, promise) {
+  getPending(params.sync).push(promise);
+  params.sync.status = {
+    TAG: "Aborted",
+    _0: {
+      RE_EXN_ID: Suspend
+    }
+  };
+  throw {
+    RE_EXN_ID: Suspend,
+    Error: new Error()
+  };
+}
 
 let paramsByThis = new WeakMap();
 
@@ -47,28 +110,69 @@ var EffectContext = function(params, chainId, effectName, defaultShouldCache, ca
 EffectContext.prototype = effectContextPrototype;
 ;
 
-function initEffect(params) {
-  let handlerChainId = Internal.getItemChainId(params.item);
+function prepareEffectCall(params, effect, input, caller) {
   let isCrossChain = effect => Stdlib_Option.getOr(effect.crossChain, params.config.defaultCrossChain);
-  let makeCaller = caller => ((effect, input) => {
-    let scope = isCrossChain(effect) ? "crossChain" : handlerChainId;
-    if (caller !== undefined && isCrossChain(caller) && !isCrossChain(effect)) {
-      Stdlib_JsError.throwWithMessage(`The cross-chain effect "` + caller.name + `" cannot call the chain-scoped effect "` + effect.name + `", because a cross-chain effect isn't tied to a single chain. Make "` + effect.name + `" cross-chain (\`crossChain: true\`), or make "` + caller.name + `" chain-scoped (\`crossChain: false\`).`);
+  let scope = isCrossChain(effect) ? "crossChain" : Internal.getItemChainId(params.item);
+  if (caller !== undefined && isCrossChain(caller) && !isCrossChain(effect)) {
+    Stdlib_JsError.throwWithMessage(`The cross-chain effect "` + caller.name + `" cannot call the chain-scoped effect "` + effect.name + `", because a cross-chain effect isn't tied to a single chain. Make "` + effect.name + `" cross-chain (\`crossChain: true\`), or make "` + caller.name + `" chain-scoped (\`crossChain: false\`).`);
+  }
+  let tmp;
+  tmp = scope === "crossChain" ? undefined : Primitive_option.some(scope);
+  let effectContext = new EffectContext(params, tmp, effect.name, effect.defaultShouldCache, (nested, nestedInput) => callEffectAsync(params, nested, nestedInput, effect));
+  let effectArgs_cacheKey = Utils.Hash.makeOrThrow(S$RescriptSchema.reverseConvertOrThrow(input, effect.input));
+  let effectArgs_checkpointId = params.checkpointId;
+  let effectArgs = {
+    input: input,
+    context: effectContext,
+    cacheKey: effectArgs_cacheKey,
+    checkpointId: effectArgs_checkpointId
+  };
+  return [
+    scope,
+    effectArgs
+  ];
+}
+
+function callEffectAsync(params, effect, input, caller) {
+  let match = prepareEffectCall(params, effect, input, caller);
+  return LoadLayer.loadEffect(params.loadManager, params.persistence, effect, match[1], match[0], params.indexerState, params.isPreload, params.item, params.config.ecosystem);
+}
+
+function initEffect(params) {
+  return (effect, input) => {
+    checkStatusOrThrow(params, "context.effect");
+    return callEffectAsync(params, effect, input, undefined);
+  };
+}
+
+function effectMemoKey(effect, scope, cacheKey) {
+  if (scope === "crossChain") {
+    return effect.name + `.` + cacheKey;
+  } else {
+    return effect.name + `.` + ChainId.toString(scope) + `.` + cacheKey;
+  }
+}
+
+function initEffectSync(params) {
+  return (effect, input) => {
+    checkStatusOrThrow(params, "context.effectSync");
+    let match = prepareEffectCall(params, effect, input, undefined);
+    let effectArgs = match[1];
+    let scope = match[0];
+    let memo = getMemo(params.sync);
+    let memoKey = effectMemoKey(effect, scope, effectArgs.cacheKey);
+    let output = memo[memoKey];
+    if (output !== undefined) {
+      return Primitive_option.valFromOption(output);
     }
-    let tmp;
-    tmp = scope === "crossChain" ? undefined : Primitive_option.some(scope);
-    let effectContext = new EffectContext(params, tmp, effect.name, effect.defaultShouldCache, makeCaller(effect));
-    let effectArgs_cacheKey = Utils.Hash.makeOrThrow(S$RescriptSchema.reverseConvertOrThrow(input, effect.input));
-    let effectArgs_checkpointId = params.checkpointId;
-    let effectArgs = {
-      input: input,
-      context: effectContext,
-      cacheKey: effectArgs_cacheKey,
-      checkpointId: effectArgs_checkpointId
-    };
-    return LoadLayer.loadEffect(params.loadManager, params.persistence, effect, effectArgs, scope, params.indexerState, params.isPreload, params.item, params.config.ecosystem);
-  });
-  return makeCaller(undefined);
+    let inMemTable = InMemoryStore.getEffectInMemTable(params.indexerState, effect, scope);
+    if (!InMemoryStore.hasEffectOutput(inMemTable, effectArgs.cacheKey)) {
+      return scheduleAndSuspend(params, LoadLayer.loadEffect(params.loadManager, params.persistence, effect, effectArgs, scope, params.indexerState, params.isPreload, params.item, params.config.ecosystem));
+    }
+    let output$1 = InMemoryStore.getEffectOutputUnsafe(inMemTable, effectArgs.cacheKey);
+    memo[memoKey] = output$1;
+    return output$1;
+  };
 }
 
 function entityScope(params) {
@@ -97,24 +201,83 @@ function throwClickHouseReadOnly(entityConfig, op) {
   return Stdlib_JsError.throwWithMessage(`context.` + entityConfig.name + `.` + op + `() is unavailable: ClickHouse storage is currently write-only. Follow Envio releases to be notified when ClickHouse supports both reads and writes from handlers.`);
 }
 
+function getSyncHandler(params, entityId) {
+  let inMemTable = InMemoryStore.getInMemTable(params.indexerState, params.entityConfig, entityScope(params));
+  if (entityId in inMemTable.latestEntityChangeById) {
+    return InMemoryTable.Entity.getUnsafe(inMemTable)(entityId);
+  } else {
+    return scheduleAndSuspend(params, LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, entityScope(params), params.indexerState, params.isPreload, params.item, params.config.ecosystem, entityId));
+  }
+}
+
+function getWhereSyncHandler(params, filter) {
+  let entityConfig = params.entityConfig;
+  let inMemTable = InMemoryStore.getInMemTable(params.indexerState, entityConfig, entityScope(params));
+  let hasIndex = InMemoryTable.Entity.hasIndex(inMemTable);
+  let getOnIndex = InMemoryTable.Entity.getUnsafeOnIndex(inMemTable);
+  let filters = EntityFilter.parseGetWhereOrThrow(filter, entityConfig.name, entityConfig.table);
+  let missing = [];
+  let entities = [];
+  filters.forEach(filter => {
+    let filterKey = EntityFilter.toString(filter);
+    if (hasIndex(filterKey)) {
+      entities.push(...getOnIndex(filterKey));
+    } else {
+      missing.push(LoadLayer.loadByFilter(params.loadManager, params.persistence, entityConfig, entityScope(params), params.indexerState, params.isPreload, params.item, params.config.ecosystem, filter));
+    }
+  });
+  if (Utils.$$Array.notEmpty(missing)) {
+    let pending = getPending(params.sync);
+    missing.forEach(promise => {
+      pending.push(promise);
+    });
+    params.sync.status = {
+      TAG: "Aborted",
+      _0: {
+        RE_EXN_ID: Suspend
+      }
+    };
+    throw {
+      RE_EXN_ID: Suspend,
+      Error: new Error()
+    };
+  }
+  return entities;
+}
+
+function getInBlockSyncHandler(params, entityId) {
+  let inMemTable = InMemoryStore.getInMemTable(params.indexerState, params.entityConfig, entityScope(params));
+  let change = inMemTable.latestEntityChangeById[entityId];
+  if (change !== undefined && change.checkpointId === params.checkpointId) {
+    return InMemoryTable.Entity.mapChangeToEntity(change);
+  }
+}
+
 let entityTraps_get = (params, prop) => {
+  checkStatusOrThrow(params, `context.` + params.entityConfig.name + `.` + prop);
   let isClickHouseOnly = !params.entityConfig.storage.postgres;
-  let set = params.isPreload ? noopSet : entity => InMemoryTable.Entity.set(InMemoryStore.getInMemTable(params.indexerState, params.entityConfig, entityScope(params)), IndexerState.committedCheckpointId(params.indexerState), {
-      type: "SET",
-      entityId: entity.id,
-      entity: entity,
-      checkpointId: params.checkpointId
-    });
+  let set = params.isPreload ? noopSet : entity => {
+      checkStatusOrThrow(params, `context.` + params.entityConfig.name + `.set`);
+      InMemoryTable.Entity.set(InMemoryStore.getInMemTable(params.indexerState, params.entityConfig, entityScope(params)), IndexerState.committedCheckpointId(params.indexerState), {
+        type: "SET",
+        entityId: entity.id,
+        entity: entity,
+        checkpointId: params.checkpointId
+      });
+    };
   switch (prop) {
     case "deleteUnsafe" :
       if (params.isPreload) {
         return noopDeleteUnsafe;
       } else {
-        return entityId => InMemoryTable.Entity.set(InMemoryStore.getInMemTable(params.indexerState, params.entityConfig, entityScope(params)), IndexerState.committedCheckpointId(params.indexerState), {
-          type: "DELETE",
-          entityId: entityId,
-          checkpointId: params.checkpointId
-        });
+        return entityId => {
+          checkStatusOrThrow(params, `context.` + params.entityConfig.name + `.deleteUnsafe`);
+          InMemoryTable.Entity.set(InMemoryStore.getInMemTable(params.indexerState, params.entityConfig, entityScope(params)), IndexerState.committedCheckpointId(params.indexerState), {
+            type: "DELETE",
+            entityId: entityId,
+            checkpointId: params.checkpointId
+          });
+        };
       }
     case "get" :
       if (isClickHouseOnly) {
@@ -122,6 +285,8 @@ let entityTraps_get = (params, prop) => {
       } else {
         return entityId => LoadLayer.loadById(params.loadManager, params.persistence, params.entityConfig, entityScope(params), params.indexerState, params.isPreload, params.item, params.config.ecosystem, entityId);
       }
+    case "getInBlockSync" :
+      return entityId => getInBlockSyncHandler(params, entityId);
     case "getOrCreate" :
       if (isClickHouseOnly) {
         return _entity => throwClickHouseReadOnly(params.entityConfig, "getOrCreate");
@@ -147,12 +312,16 @@ let entityTraps_get = (params, prop) => {
           }
         });
       }
+    case "getSync" :
+      return entityId => getSyncHandler(params, entityId);
     case "getWhere" :
       if (isClickHouseOnly) {
         return _filter => throwClickHouseReadOnly(params.entityConfig, "getWhere");
       } else {
         return filter => getWhereHandler(params, filter);
       }
+    case "getWhereSync" :
+      return filter => getWhereSyncHandler(params, filter);
     case "set" :
       return set;
     default:
@@ -164,16 +333,63 @@ let entityTraps = {
   get: entityTraps_get
 };
 
-let handlerTraps_get = (params, prop) => {
-  if (params.isResolved) {
-    ErrorHandling.mkLogAndRaise(Ecosystem.getItemLogger(params.item, params.config.ecosystem), undefined, new Error(`Impossible to access context.` + prop + ` after the handler is resolved. Make sure you didn't miss an await in the handler.`));
+async function runSyncRound(params, fn, round) {
+  if (round > 10000) {
+    Stdlib_JsError.throwWithMessage(`The handler suspended on a synchronous read too many times: gave up after ` + (10000).toString() + ` rounds. This usually means the code isn't deterministic across reruns.`);
+  }
+  params.sync.status = "Active";
+  params.sync.pending = undefined;
+  let suspended;
+  try {
+    fn();
+    suspended = false;
+  } catch (raw_exn) {
+    let exn = Primitive_exceptions.internalToException(raw_exn);
+    if (exn.RE_EXN_ID === Suspend) {
+      suspended = true;
+    } else {
+      let pending = params.sync.pending;
+      if (pending !== undefined) {
+        params.sync.pending = undefined;
+        pending.forEach(promise => {
+          Utils.$$Promise.silentCatch(promise);
+        });
+      }
+      throw exn;
+    }
   }
+  let pending$1 = params.sync.pending;
+  if (pending$1 === undefined) {
+    return;
+  }
+  params.sync.pending = undefined;
+  if (suspended) {
+    let errors = [];
+    await Promise.all(pending$1.map(promise => Stdlib_Promise.$$catch(promise, exn => {
+      errors.push(exn);
+      return Promise.resolve();
+    })));
+    let exn$1 = errors[0];
+    if (exn$1 !== undefined) {
+      throw exn$1;
+    }
+    return await runSyncRound(params, fn, round + 1 | 0);
+  }
+  pending$1.forEach(promise => {
+    Utils.$$Promise.silentCatch(promise);
+  });
+}
+
+let handlerTraps_get = (params, prop) => {
+  checkStatusOrThrow(params, `context.` + prop);
   switch (prop) {
     case "chain" :
       let chainId = Internal.getItemChainId(params.item);
       return params.chains[chainId];
     case "effect" :
       return initEffect(params);
+    case "effectSync" :
+      return initEffectSync(params);
     case "isPreload" :
       return params.isPreload;
     case "log" :
@@ -182,6 +398,8 @@ let handlerTraps_get = (params, prop) => {
       } else {
         return Ecosystem.getItemUserLogger(params.item, params.config.ecosystem);
       }
+    case "runSync" :
+      return fn => runSyncRound(params, fn, 1);
     default:
       let entityConfig = params.config.userEntitiesByName[prop];
       if (entityConfig !== undefined) {
@@ -194,7 +412,7 @@ let handlerTraps_get = (params, prop) => {
           isPreload: params.isPreload,
           chains: params.chains,
           config: params.config,
-          isResolved: params.isResolved,
+          sync: params.sync,
           entityConfig: entityConfig
         }, entityTraps);
       } else {
@@ -211,16 +429,34 @@ function getHandlerContext(params) {
   return new Proxy(params, handlerTraps);
 }
 
+let maxSyncRounds = 10000;
+
 export {
+  Suspend,
+  isSuspend,
+  makeSyncState,
+  getPending,
+  getMemo,
+  checkStatusOrThrow,
+  scheduleAndSuspend,
   paramsByThis,
   effectContextPrototype,
+  prepareEffectCall,
+  callEffectAsync,
   initEffect,
+  effectMemoKey,
+  initEffectSync,
   entityScope,
   getWhereHandler,
   noopSet,
   noopDeleteUnsafe,
   throwClickHouseReadOnly,
+  getSyncHandler,
+  getWhereSyncHandler,
+  getInBlockSyncHandler,
   entityTraps,
+  maxSyncRounds,
+  runSyncRound,
   handlerTraps,
   getHandlerContext,
 }

package/src/sources/SourceManager.res

@@ -468,16 +468,16 @@ let getSourceNewHeight = async (
               // head on every (re)connect; waking the wait loop on a height we already
               // know spins it and leaks fallback pollers (#1270).
               if newHeight > sourceState.knownHeight {
+                sourceState->recordRequestStats([{Source.method: "heightPush", seconds: 0.}])
                 sourceState.knownHeight = newHeight
                 let resolvers = sourceState.pendingHeightResolvers
                 sourceState.pendingHeightResolvers = []
                 resolvers->Array.forEach(resolve => resolve(newHeight))
+              } else {
+                sourceState->recordRequestStats([{Source.method: "heightPushIgnored", seconds: 0.}])
               }
             })
             sourceState.unsubscribe = Some(unsubscribe)
-            // Count a subscription (re)start rather than every pushed height —
-            // there's no request/response to time here.
-            sourceState->recordRequestStats([{Source.method: "heightSubscription", seconds: 0.}])
           | _ =>
             // Slowdown polling when the chain isn't progressing
             let pollingInterval = if reducedPolling {
@@ -724,9 +724,7 @@ let executeQuery = async (
     ) {
     | Some(s) =>
       if s.source !== sourceManager.activeSource {
-        let logger = Logging.createChild(
-          ~params={"chainId": sourceManager.activeSource.chainId},
-        )
+        let logger = Logging.createChild(~params={"chainId": sourceManager.activeSource.chainId})
         logger->Logging.childInfo({
           "msg": "Switching data-source",
           "source": s.source.name,
@@ -736,9 +734,7 @@ let executeQuery = async (
       }
       s
     | None =>
-      let logger = Logging.createChild(
-        ~params={"chainId": sourceManager.activeSource.chainId},
-      )
+      let logger = Logging.createChild(~params={"chainId": sourceManager.activeSource.chainId})
       %raw(`null`)->ErrorHandling.mkLogAndRaise(~logger, ~msg=noSourcesError)
     }
     sourceManager.activeSource = sourceState.source
@@ -895,9 +891,7 @@ let getBlockHashes = async (sourceManager: t, ~blockNumbers: array<int>, ~isReal
     let sourceState = switch sourceManager->getNextSource(~isRealtime) {
     | Some(s) => s
     | None =>
-      let logger = Logging.createChild(
-        ~params={"chainId": sourceManager.activeSource.chainId},
-      )
+      let logger = Logging.createChild(~params={"chainId": sourceManager.activeSource.chainId})
       %raw(`null`)->ErrorHandling.mkLogAndRaise(
         ~logger,
         ~msg="No data-sources available for fetching block hashes.",

package/src/sources/SourceManager.res.mjs

@@ -388,18 +388,21 @@ async function getSourceNewHeight(sourceManager, sourceState, knownHeight, stall
           if (createSubscription !== undefined && isRealtime) {
             let unsubscribe = createSubscription(newHeight => {
               if (newHeight <= sourceState.knownHeight) {
-                return;
+                return recordRequestStats(sourceState, [{
+                    method: "heightPushIgnored",
+                    seconds: 0
+                  }]);
               }
+              recordRequestStats(sourceState, [{
+                  method: "heightPush",
+                  seconds: 0
+                }]);
               sourceState.knownHeight = newHeight;
               let resolvers = sourceState.pendingHeightResolvers;
               sourceState.pendingHeightResolvers = [];
               resolvers.forEach(resolve => resolve(newHeight));
             });
             sourceState.unsubscribe = unsubscribe;
-            recordRequestStats(sourceState, [{
-                method: "heightSubscription",
-                seconds: 0
-              }]);
           } else {
             exit = 1;
           }

package/src/subgraph/blocks.ts

@@ -0,0 +1,176 @@
+/**
+ * A block handler's `block.timestamp`.
+ *
+ * envio hands a block handler only the block number, so the timestamp has to be
+ * fetched. Every handler invocation in a batch asks within the same microtask,
+ * so the requests are collected and answered by a single HyperSync range query
+ * rather than one round trip per block. An RPC endpoint, if one is configured,
+ * is the fallback for whatever HyperSync couldn't answer.
+ */
+
+import { createPublicClient, fallback, http } from "viem";
+
+const API_TOKEN_ENV_VAR = "ENVIO_API_TOKEN";
+
+const hypersyncUrl = (chainId: number) => `https://${chainId}.hypersync.xyz/query`;
+
+type Waiter = {
+  resolve: (timestamp: bigint) => void;
+  reject: (error: unknown) => void;
+};
+
+/** Blocks asked for since the last flush, by chain then block number. */
+let pending = new Map<number, Map<number, Waiter[]>>();
+let flushScheduled = false;
+
+let rpcUrls: string[] = [];
+let client: ReturnType<typeof createPublicClient> | null = null;
+
+export function configureBlockTimestamps(urls: string[]) {
+  rpcUrls = urls;
+  client = null;
+  pending = new Map();
+  flushScheduled = false;
+}
+
+export function requestBlockTimestamp(chainId: number, blockNumber: number): Promise<bigint> {
+  return new Promise((resolve, reject) => {
+    let blocks = pending.get(chainId);
+    if (!blocks) {
+      blocks = new Map();
+      pending.set(chainId, blocks);
+    }
+    const waiters = blocks.get(blockNumber);
+    if (waiters) {
+      waiters.push({ resolve, reject });
+    } else {
+      blocks.set(blockNumber, [{ resolve, reject }]);
+    }
+
+    if (!flushScheduled) {
+      flushScheduled = true;
+      queueMicrotask(() => {
+        flushScheduled = false;
+        const collected = pending;
+        pending = new Map();
+        for (const [chain, blocksForChain] of collected) {
+          void answer(chain, blocksForChain);
+        }
+      });
+    }
+  });
+}
+
+async function answer(chainId: number, blocks: Map<number, Waiter[]>) {
+  let timestamps = new Map<number, bigint>();
+
+  // A batch can hold thousands of blocks, and one argument per block would
+  // overflow the call stack inside the try, where it would read as a HyperSync
+  // failure and fall back to one round trip per block.
+  let lowest = Infinity;
+  let highest = -Infinity;
+  for (const blockNumber of blocks.keys()) {
+    if (blockNumber < lowest) lowest = blockNumber;
+    if (blockNumber > highest) highest = blockNumber;
+  }
+
+  try {
+    timestamps = await fromHyperSync(chainId, lowest, highest);
+  } catch (error) {
+    if (rpcUrls.length === 0) {
+      const message = error instanceof Error ? error.message : String(error);
+      for (const waiters of blocks.values()) {
+        for (const waiter of waiters) {
+          waiter.reject(
+            new Error(
+              `Envio Subgraph couldn't read a block timestamp from HyperSync: ${message}\n` +
+                `Set ${API_TOKEN_ENV_VAR} in .env or the environment — create one at\n` +
+                `https://envio.dev/app/api-tokens — or set ENVIO_SUBGRAPH_RPC to fall back to RPC.`,
+            ),
+          );
+        }
+      }
+      return;
+    }
+  }
+
+  for (const [blockNumber, waiters] of blocks) {
+    const known = timestamps.get(blockNumber);
+    if (known !== undefined) {
+      for (const waiter of waiters) waiter.resolve(known);
+      continue;
+    }
+    try {
+      const timestamp = await fromRpc(blockNumber);
+      for (const waiter of waiters) waiter.resolve(timestamp);
+    } catch (error) {
+      for (const waiter of waiters) waiter.reject(error);
+    }
+  }
+}
+
+type HyperSyncResponse = {
+  data: { blocks?: { number: number; timestamp: string }[] }[];
+  next_block: number;
+};
+
+async function fromHyperSync(
+  chainId: number,
+  fromBlock: number,
+  toBlock: number,
+): Promise<Map<number, bigint>> {
+  const token = process.env[API_TOKEN_ENV_VAR];
+  const timestamps = new Map<number, bigint>();
+
+  let cursor = fromBlock;
+  // HyperSync answers as much of the range as one response holds and points at
+  // where to resume, so a wide range takes more than one round trip.
+  while (cursor <= toBlock) {
+    const response = await fetch(hypersyncUrl(chainId), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify({
+        from_block: cursor,
+        to_block: toBlock + 1,
+        include_all_blocks: true,
+        field_selection: { block: ["number", "timestamp"] },
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HyperSync returned ${response.status} ${await response.text()}`);
+    }
+
+    const body = (await response.json()) as HyperSyncResponse;
+    for (const page of body.data ?? []) {
+      for (const block of page.blocks ?? []) {
+        timestamps.set(block.number, BigInt(block.timestamp));
+      }
+    }
+
+    if (!body.next_block || body.next_block <= cursor) {
+      break;
+    }
+    cursor = body.next_block;
+  }
+
+  return timestamps;
+}
+
+async function fromRpc(blockNumber: number): Promise<bigint> {
+  if (rpcUrls.length === 0) {
+    throw new Error(
+      `Envio Subgraph couldn't read the timestamp of block ${blockNumber}: HyperSync didn't\n` +
+        `return it, and no RPC fallback is configured. Set ENVIO_SUBGRAPH_RPC in .env or the\n` +
+        `environment.`,
+    );
+  }
+  client ??= createPublicClient({
+    transport: fallback(rpcUrls.map((url) => http(url, { retryCount: 0 }))),
+  });
+  const block = await client.getBlock({ blockNumber: BigInt(blockNumber) });
+  return block.timestamp;
+}