envio 3.15.0 → 3.16.0-subgraph

package/src/FinalizeBackfill.res.mjs

@@ -27,7 +27,7 @@ async function runOnce(state) {
   let persistence = IndexerState.persistence(state);
   let storage = Persistence.getInitializedStorageOrThrow(persistence);
   let readyAt = new Date();
-  await storage.finalizeBackfill(persistence.allEntities, chainIds, readyAt);
+  await storage.finalizeBackfill(chainIds, readyAt);
   return IndexerState.markReady(state, readyAt);
 }
 
@@ -42,9 +42,8 @@ function run(state) {
 }
 
 function repairSchemaIndexes(state) {
-  let persistence = IndexerState.persistence(state);
-  let storage = Persistence.getInitializedStorageOrThrow(persistence);
-  return storage.ensureSchemaIndexes(persistence.allEntities, CrossChainState.chainIds(IndexerState.crossChainState(state)));
+  let storage = Persistence.getInitializedStorageOrThrow(IndexerState.persistence(state));
+  return storage.ensureSchemaIndexes(CrossChainState.chainIds(IndexerState.crossChainState(state)));
 }
 
 export {

package/src/HandlerLoader.res

@@ -54,8 +54,8 @@ let registerContractHandlers = async (~logger, ~contractName, ~handler: option<s
   }
 }
 
-let getAutoLoadFiles = async (~config: Config.t) => {
-  let srcPattern = `./${config.handlers}/**/*.{js,mjs,ts}`
+let globAutoLoadFiles = async (~handlers) => {
+  let srcPattern = `./${handlers}/**/*.{js,mjs,ts}`
   try {
     let iterator = globIterator(srcPattern)
     let files = await iterator->Utils.Array.fromAsyncIterator
@@ -77,6 +77,14 @@ let getAutoLoadFiles = async (~config: Config.t) => {
   }
 }
 
+let getAutoLoadFiles = async (~config: Config.t) =>
+  switch config.subgraph {
+  // A subgraph project's `src/` holds AssemblyScript mappings, not envio
+  // handlers: auto-loading or type-checking them as TypeScript would fail.
+  | Some(_) => []
+  | None => await globAutoLoadFiles(~handlers=config.handlers)
+  }
+
 let typeCheck = async (~config: Config.t, ~logger, ~autoLoadFiles) => {
   // A contract's `handler:` may also be an auto-loaded file.
   let files =
@@ -103,6 +111,16 @@ let typeCheck = async (~config: Config.t, ~logger, ~autoLoadFiles) => {
 // `HandlerRegister.finishRegistration`. This loads the user handler files
 // (populating the global `HandlerRegister` registry as a side effect) and
 // returns the resulting per-chain registrations.
+// The subgraph runtime lives in this package but is never exported: it's
+// reached only from here, when the resolved config carries a translated
+// manifest.
+let registerSubgraph: (
+  JSON.t,
+  ~isDev: bool,
+  ~logger: Logger.t,
+) => promise<unit> = %raw(`(subgraph, isDev, logger) =>
+  import("./subgraph/runtime.ts").then((m) => m.registerSubgraph({ ...subgraph, isDev }, logger))`)
+
 let registerAllHandlers = async (
   ~config: Config.t,
   ~logger,
@@ -111,21 +129,27 @@ let registerAllHandlers = async (
   HandlerRegister.startRegistration(~config, ~logger)
   registerTsHooks()
 
-  let _ = await autoLoadFiles
-  ->Array.map(file => {
-    importHandler(file)->Promise.catch(exn => {
-      let cause = exn->Utils.prettifyExn->Obj.magic
-      logger->Logger.errorWithExn(`Failed to auto-load handler file: ${file}`, exn)
-      JsError.throwWithMessage(`Failed to auto-load handler file: ${file}. Cause: ${cause}`)
+  switch config.subgraph {
+  // Registered after the TypeScript hooks, so the subgraph runtime's own hooks
+  // see a mapping first.
+  | Some(subgraph) => await registerSubgraph(subgraph, ~isDev=config.isDev, ~logger)
+  | None =>
+    let _ = await autoLoadFiles
+    ->Array.map(file => {
+      importHandler(file)->Promise.catch(exn => {
+        let cause = exn->Utils.prettifyExn->Obj.magic
+        logger->Logger.errorWithExn(`Failed to auto-load handler file: ${file}`, exn)
+        JsError.throwWithMessage(`Failed to auto-load handler file: ${file}. Cause: ${cause}`)
+      })
     })
-  })
-  ->Promise.all
+    ->Promise.all
 
-  let _ = await config.contractHandlers
-  ->Array.map(({name, handler}) => {
-    registerContractHandlers(~logger, ~contractName=name, ~handler)
-  })
-  ->Promise.all
+    let _ = await config.contractHandlers
+    ->Array.map(({name, handler}) => {
+      registerContractHandlers(~logger, ~contractName=name, ~handler)
+    })
+    ->Promise.all
+  }
 
   HandlerRegister.finishRegistration(~config)
 }

package/src/HandlerLoader.res.mjs

@@ -58,8 +58,8 @@ async function registerContractHandlers(logger, contractName, handler) {
   }
 }
 
-async function getAutoLoadFiles(config) {
-  let srcPattern = `./` + config.handlers + `/**/*.{js,mjs,ts}`;
+async function globAutoLoadFiles(handlers) {
+  let srcPattern = `./` + handlers + `/**/*.{js,mjs,ts}`;
   try {
     let iterator = Promises.glob(srcPattern);
     let files = await Utils.$$Array.fromAsyncIterator(iterator);
@@ -70,6 +70,15 @@ async function getAutoLoadFiles(config) {
   }
 }
 
+async function getAutoLoadFiles(config) {
+  let match = config.subgraph;
+  if (match !== undefined) {
+    return [];
+  } else {
+    return await globAutoLoadFiles(config.handlers);
+  }
+}
+
 async function typeCheck(config, logger, autoLoadFiles) {
   let files = Array.from(new Set(autoLoadFiles.concat(Stdlib_Array.filterMap(config.contractHandlers, param => param.handler)).filter(isTypeScript).map(toAbsolutePath)));
   if (files.length === 0) {
@@ -85,15 +94,23 @@ async function typeCheck(config, logger, autoLoadFiles) {
   }
 }
 
+let registerSubgraph = ((subgraph, isDev, logger) =>
+  import("./subgraph/runtime.ts").then((m) => m.registerSubgraph({ ...subgraph, isDev }, logger)));
+
 async function registerAllHandlers(config, logger, autoLoadFiles) {
   HandlerRegister.startRegistration(config, logger);
   registerTsHooks();
-  await Promise.all(autoLoadFiles.map(file => Stdlib_Promise.$$catch(importHandler(file), exn => {
-    let cause = Utils.prettifyExn(exn);
-    Logger.errorWithExn(logger, `Failed to auto-load handler file: ` + file, exn);
-    return Stdlib_JsError.throwWithMessage(`Failed to auto-load handler file: ` + file + `. Cause: ` + cause);
-  })));
-  await Promise.all(config.contractHandlers.map(param => registerContractHandlers(logger, param.name, param.handler)));
+  let subgraph = config.subgraph;
+  if (subgraph !== undefined) {
+    await registerSubgraph(subgraph, config.isDev, logger);
+  } else {
+    await Promise.all(autoLoadFiles.map(file => Stdlib_Promise.$$catch(importHandler(file), exn => {
+      let cause = Utils.prettifyExn(exn);
+      Logger.errorWithExn(logger, `Failed to auto-load handler file: ` + file, exn);
+      return Stdlib_JsError.throwWithMessage(`Failed to auto-load handler file: ` + file + `. Cause: ` + cause);
+    })));
+    await Promise.all(config.contractHandlers.map(param => registerContractHandlers(logger, param.name, param.handler)));
+  }
   return HandlerRegister.finishRegistration(config);
 }
 
@@ -104,8 +121,10 @@ export {
   toAbsolutePath,
   importHandler,
   registerContractHandlers,
+  globAutoLoadFiles,
   getAutoLoadFiles,
   typeCheck,
+  registerSubgraph,
   registerAllHandlers,
 }
 /* url Not a pure module */

package/src/HandlerRegister.res

@@ -699,6 +699,8 @@ let registerOnBlock = (
   ~where: unknown,
   ~fields: unknown,
   ~handler: Internal.onBlockArgs => promise<unit>,
+  ~runsFirst=false,
+  ~contractRegister=?,
   ~getChainsObject: Config.t => dict<unknown>,
 ) => {
   withRegistration(registration => {
@@ -792,6 +794,8 @@ let registerOnBlock = (
               interval: range._every,
               chainId,
               handler,
+              runsFirst,
+              ?contractRegister,
               blockFieldMask,
             }: Internal.onBlockRegistration
           ),

package/src/HandlerRegister.res.mjs

@@ -440,7 +440,8 @@ function extractRange(filter, name, ecosystem) {
   }
 }
 
-function registerOnBlock(name, where, fields, handler, getChainsObject) {
+function registerOnBlock(name, where, fields, handler, runsFirstOpt, contractRegister, getChainsObject) {
+  let runsFirst = runsFirstOpt !== undefined ? runsFirstOpt : false;
   withRegistration(registration => {
     let config = registration.config;
     let ecosystem = config.ecosystem;
@@ -497,7 +498,9 @@ function registerOnBlock(name, where, fields, handler, getChainsObject) {
         endBlock: range._lte,
         interval: range._every,
         handler: handler,
-        blockFieldMask: blockFieldMask
+        blockFieldMask: blockFieldMask,
+        runsFirst: runsFirst,
+        contractRegister: contractRegister
       });
     });
     if (!matchedAny.contents) {

package/src/HandlerRegister.resi

@@ -46,5 +46,7 @@ let registerOnBlock: (
   ~where: unknown,
   ~fields: unknown,
   ~handler: Internal.onBlockArgs => promise<unit>,
+  ~runsFirst: bool=?,
+  ~contractRegister: Internal.onBlockContractRegisterArgs => promise<unit>=?,
   ~getChainsObject: Config.t => dict<unknown>,
 ) => unit

package/src/InMemoryTable.res

@@ -22,6 +22,8 @@ module Entity = {
   }
 
   type t = {
+    // Keys every id dict and Set below; see Table.table.
+    entityIdToKey: EntityId.t => string,
     latestEntityChangeById: dict<Change.t<Internal.entity>>,
     // Recorded changes (new latest ids + prevEntityChanges pushes), tracked
     // manually so InMemoryStore can gauge size without scanning every dict.
@@ -45,12 +47,9 @@ module Entity = {
     mutable hasIndexes: bool,
   }
 
-  // Helper to extract an entity's id as a dict key. The raw id may be a
-  // string/int/bigint, so it's stringified to a stable key for in-memory
-  // indexing.
-  let getEntityIdUnsafe = (entity: Internal.entity): string =>
+  let getEntityKeyUnsafe = (self: t, entity: Internal.entity): string =>
     switch (entity->(Utils.magic: Internal.entity => {"id": option<EntityId.t>}))["id"] {
-    | Some(id) => id->EntityId.toKey
+    | Some(id) => self.entityIdToKey(id)
     | None => JsError.throwWithMessage("Property 'id' does not exist on expected entity object")
     }
 
@@ -62,7 +61,8 @@ module Entity = {
     }
   }
 
-  let make = (): t => {
+  let make = (~entityIdToKey): t => {
+    entityIdToKey,
     latestEntityChangeById: Dict.make(),
     changesCount: 0.,
     dirtyIds: Utils.Set.make(),
@@ -141,10 +141,8 @@ module Entity = {
     self.hasIndexes = false
   }
 
-  let updateIndexes = (self: t, ~entity: Internal.entity) =>
+  let updateIndexes = (self: t, ~entityId: string, ~entity: Internal.entity) =>
     if self.hasIndexes {
-      let entityId = entity->getEntityIdUnsafe
-
       switch self.indexesByEntityId->Utils.Dict.dangerouslyGetNonOption(entityId) {
       | None => ()
       | Some(indexes) =>
@@ -185,7 +183,7 @@ module Entity = {
     }
 
   let set = (inMemTable: t, ~committedCheckpointId, change: Change.t<Internal.entity>) => {
-    let entityKey = change->Change.getEntityId->EntityId.toKey
+    let entityKey = inMemTable.entityIdToKey(change->Change.getEntityId)
     switch inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(entityKey) {
     | Some(prev) =>
       let prevCheckpointId = prev->Change.getCheckpointId
@@ -200,8 +198,8 @@ module Entity = {
     }
 
     switch change {
-    | Set({entity}) => inMemTable->updateIndexes(~entity)
-    | Delete({entityId}) => inMemTable->deleteEntityFromIndexes(~entityId=entityId->EntityId.toKey)
+    | Set({entity}) => inMemTable->updateIndexes(~entityId=entityKey, ~entity)
+    | Delete(_) => inMemTable->deleteEntityFromIndexes(~entityId=entityKey)
     }
     inMemTable.latestEntityChangeById->Dict.set(entityKey, change)
     if change->Change.getCheckpointId > committedCheckpointId {
@@ -214,11 +212,14 @@ module Entity = {
   let initValue = (
     inMemTable: t,
     ~committedCheckpointId,
-    ~key: string,
+    ~entityId: EntityId.t,
     ~entity: option<Internal.entity>,
   ) =>
-    if inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(key)->Option.isNone {
-      let entityId = key->EntityId.unsafeOfString
+    if (
+      inMemTable.latestEntityChangeById
+      ->Utils.Dict.dangerouslyGetNonOption(inMemTable.entityIdToKey(entityId))
+      ->Option.isNone
+    ) {
       let change: Change.t<Internal.entity> = switch entity {
       | Some(entity) => Set({entityId, entity, checkpointId: Internal.loadedFromDbCheckpointId})
       | None => Delete({entityId, checkpointId: Internal.loadedFromDbCheckpointId})
@@ -312,7 +313,7 @@ module Entity = {
         switch change->mapChangeToEntity {
         | Some(entity) =>
           if index.matcher(entity) {
-            inMemTable->addToIndex(~index, ~entityId=entity->getEntityIdUnsafe)
+            inMemTable->addToIndex(~index, ~entityId=inMemTable->getEntityKeyUnsafe(entity))
           }
         | None => ()
         }

package/src/InMemoryTable.res.mjs

@@ -1,7 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Utils from "./Utils.res.mjs";
-import * as EntityId from "./EntityId.res.mjs";
 import * as Internal from "./Internal.res.mjs";
 import * as EntityFilter from "./db/EntityFilter.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
@@ -9,10 +8,10 @@ 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 Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 
-function getEntityIdUnsafe(entity) {
+function getEntityKeyUnsafe(self, entity) {
   let id = entity.id;
   if (id !== undefined) {
-    return EntityId.toKey(Primitive_option.valFromOption(id));
+    return self.entityIdToKey(Primitive_option.valFromOption(id));
   } else {
     return Stdlib_JsError.throwWithMessage("Property 'id' does not exist on expected entity object");
   }
@@ -28,8 +27,9 @@ function addToIndex(self, index, entityId) {
   }
 }
 
-function make() {
+function make(entityIdToKey) {
   return {
+    entityIdToKey: entityIdToKey,
     latestEntityChangeById: {},
     changesCount: 0,
     dirtyIds: new Set(),
@@ -99,11 +99,10 @@ function dropCommittedChanges(self, committedCheckpointId, keepLoadedFromDb) {
   self.hasIndexes = false;
 }
 
-function updateIndexes(self, entity) {
+function updateIndexes(self, entityId, entity) {
   if (!self.hasIndexes) {
     return;
   }
-  let entityId = getEntityIdUnsafe(entity);
   let indexes = self.indexesByEntityId[entityId];
   if (indexes !== undefined) {
     let indexes$1 = Primitive_option.valFromOption(indexes);
@@ -144,7 +143,7 @@ function deleteEntityFromIndexes(self, entityId) {
 }
 
 function set(inMemTable, committedCheckpointId, change) {
-  let entityKey = EntityId.toKey(change.entityId);
+  let entityKey = inMemTable.entityIdToKey(change.entityId);
   let prev = inMemTable.latestEntityChangeById[entityKey];
   if (prev !== undefined) {
     let prevCheckpointId = prev.checkpointId;
@@ -156,9 +155,9 @@ function set(inMemTable, committedCheckpointId, change) {
     inMemTable.changesCount = inMemTable.changesCount + 1;
   }
   if (change.type === "SET") {
-    updateIndexes(inMemTable, change.entity);
+    updateIndexes(inMemTable, entityKey, change.entity);
   } else {
-    deleteEntityFromIndexes(inMemTable, EntityId.toKey(change.entityId));
+    deleteEntityFromIndexes(inMemTable, entityKey);
   }
   inMemTable.latestEntityChangeById[entityKey] = change;
   if (change.checkpointId > committedCheckpointId) {
@@ -167,18 +166,18 @@ function set(inMemTable, committedCheckpointId, change) {
   }
 }
 
-function initValue(inMemTable, committedCheckpointId, key, entity) {
-  if (!Stdlib_Option.isNone(inMemTable.latestEntityChangeById[key])) {
+function initValue(inMemTable, committedCheckpointId, entityId, entity) {
+  if (!Stdlib_Option.isNone(inMemTable.latestEntityChangeById[inMemTable.entityIdToKey(entityId)])) {
     return;
   }
   let change = entity !== undefined ? ({
       type: "SET",
-      entityId: key,
+      entityId: entityId,
       entity: entity,
       checkpointId: Internal.loadedFromDbCheckpointId
     }) : ({
       type: "DELETE",
-      entityId: key,
+      entityId: entityId,
       checkpointId: Internal.loadedFromDbCheckpointId
     });
   set(inMemTable, committedCheckpointId, change);
@@ -285,7 +284,7 @@ function addEmptyIndex(inMemTable, filter, table) {
   Utils.Dict.forEach(inMemTable.latestEntityChangeById, change => {
     let entity = mapChangeToEntity(change);
     if (entity !== undefined && index_matcher(entity)) {
-      return addToIndex(inMemTable, index, getEntityIdUnsafe(entity));
+      return addToIndex(inMemTable, index, getEntityKeyUnsafe(inMemTable, entity));
     }
   });
 }
@@ -321,7 +320,7 @@ function tryIndexFromLoadedValues(inMemTable, filter, table) {
 }
 
 let Entity = {
-  getEntityIdUnsafe: getEntityIdUnsafe,
+  getEntityKeyUnsafe: getEntityKeyUnsafe,
   addToIndex: addToIndex,
   make: make,
   snapshotChanges: snapshotChanges,

package/src/IndexerState.res

@@ -108,6 +108,12 @@ type t = {
   // in-process test runner injects a callback that resolves its run promise
   // instead, so a caught-up run doesn't kill the test process.
   onExit: option<unit => unit>,
+  // Told, in the processing pass that gets it there, that a run holding its
+  // realtime transitions has gone as far as it can on its own. The test
+  // runner's stand-in supervisor releases from it, so the release lands at a
+  // point in the indexer's own progress rather than on a timer.
+  onArrivedAtHead: option<unit => unit>,
+  mutable reportedArrivalAtHead: bool,
   // Set once on any fatal error. Every loop checks it to stop iterating and
   // every launch skips when it's set, so a single failure quiesces the indexer.
   mutable isStopped: bool,
@@ -157,10 +163,13 @@ let make = (
   ~exitAfterFirstEventBlock=false,
   ~onError: ErrorHandling.t => unit,
   ~onExit=?,
+  ~onArrivedAtHead=?,
+  ~clock=Clock.real,
 ) => {
   let chainMetaThrottler = {
     let intervalMillis = Env.ThrottleWrites.chainMetadataIntervalMillis
     Throttler.make(
+      ~clock,
       ~intervalMillis,
       ~logger=logger->Logger.withFields({
         "context": "Throttler for chain metadata writes",
@@ -175,7 +184,7 @@ let make = (
     persistence,
     allEntities: persistence.allEntities,
     entities: EntityTables.make(persistence.allEntities->EntityTables.crossChain),
-    effectState: EffectState.make(),
+    effectState: EffectState.make(~clock, ()),
     rollback: None,
     committedFrontier,
     processedFrontier: committedFrontier->Frontier.copy,
@@ -205,6 +214,8 @@ let make = (
     exitAfterFirstEventBlock,
     onError,
     onExit,
+    onArrivedAtHead,
+    reportedArrivalAtHead: false,
     isStopped: false,
     epoch: 0,
     simulateDeadInputTracker: SimulateDeadInputTracker.makeFromConfig(config),
@@ -225,12 +236,13 @@ let make = (
 }
 
 // Check if progress is past the reorg threshold (safe block).
-// A chain is in reorg threshold when progressBlockNumber > sourceBlockNumber - maxReorgDepth.
-// This matches the logic in InternalTable.Checkpoints.makeGetReorgCheckpointsQuery.
+// A chain is in reorg threshold once its progress passes the safe block,
+// sourceBlockNumber - maxReorgDepth - 1. This matches the reorg checkpoints
+// query in packages/cli/src/postgres/internal.rs.
 let isProgressInReorgThreshold = (~progressBlockNumber, ~sourceBlockNumber, ~maxReorgDepth) => {
   maxReorgDepth > 0 &&
   sourceBlockNumber > 0 &&
-  progressBlockNumber > sourceBlockNumber - maxReorgDepth
+  progressBlockNumber > sourceBlockNumber - maxReorgDepth - 1
 }
 
 let makeFromDbState = (
@@ -249,6 +261,7 @@ let makeFromDbState = (
   ~holdRealtime=false,
   ~onError,
   ~onExit=?,
+  ~onArrivedAtHead=?,
 ) => {
   let isInReorgThreshold = if initialState.cleanRun {
     false
@@ -303,6 +316,8 @@ let makeFromDbState = (
     ~exitAfterFirstEventBlock,
     ~onError,
     ~onExit?,
+    ~onArrivedAtHead?,
+    ~clock=?sourceTiming->Option.flatMap(timing => timing.clock),
   )
   state.crossChainState->CrossChainState.markCaughtUpOnResume
   initialState.cache->Utils.Dict.forEach(({effectName, count, scope}) => {
@@ -559,6 +574,15 @@ let isHoldingRealtime = (state: t) => state.crossChainState->CrossChainState.isH
 
 let hasArrivedAtHead = (state: t) => state.crossChainState->CrossChainState.hasArrivedAtHead
 
+let reportArrivalAtHead = (state: t) =>
+  switch state.onArrivedAtHead {
+  | Some(onArrivedAtHead)
+    if !state.reportedArrivalAtHead && state->isHoldingRealtime && state->hasArrivedAtHead =>
+    state.reportedArrivalAtHead = true
+    onArrivedAtHead()
+  | _ => ()
+  }
+
 let releaseRealtime = (state: t) => {
   state.crossChainState->CrossChainState.releaseRealtime
   // Every chain is parked at the head with no batch coming, so nothing would

package/src/IndexerState.res.mjs

@@ -2,6 +2,7 @@
 
 import * as Env from "./Env.res.mjs";
 import * as Batch from "./Batch.res.mjs";
+import * as Clock from "./Clock.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Config from "./Config.res.mjs";
 import * as Logger from "./Logger.res.mjs";
@@ -26,25 +27,26 @@ import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js
 import * as CheckpointSequence from "./db/CheckpointSequence.res.mjs";
 import * as SimulateDeadInputTracker from "./SimulateDeadInputTracker.res.mjs";
 
-function make(config, logger, persistence, chainStates, isRealtime, targetBufferSizeOpt, holdRealtimeOpt, committedFrontierOpt, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, onError, onExit) {
+function make(config, logger, persistence, chainStates, isRealtime, targetBufferSizeOpt, holdRealtimeOpt, committedFrontierOpt, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, onError, onExit, onArrivedAtHead, clockOpt) {
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : CrossChainState.calculateTargetBufferSize();
   let holdRealtime = holdRealtimeOpt !== undefined ? holdRealtimeOpt : false;
   let committedFrontier = committedFrontierOpt !== undefined ? committedFrontierOpt : Frontier.empty();
   let isDevelopmentMode = isDevelopmentModeOpt !== undefined ? isDevelopmentModeOpt : false;
   let shouldUseTui = shouldUseTuiOpt !== undefined ? shouldUseTuiOpt : false;
   let exitAfterFirstEventBlock = exitAfterFirstEventBlockOpt !== undefined ? exitAfterFirstEventBlockOpt : false;
+  let clock = clockOpt !== undefined ? clockOpt : Clock.real;
   let intervalMillis = Env.ThrottleWrites.chainMetadataIntervalMillis;
   let chainMetaThrottler = Throttler.make(intervalMillis, Logger.withFields(logger, {
     context: "Throttler for chain metadata writes",
     intervalMillis: intervalMillis
-  }));
+  }), clock);
   return {
     config: config,
     logger: logger,
     persistence: persistence,
     allEntities: persistence.allEntities,
     entities: EntityTables.make(EntityTables.crossChain(persistence.allEntities)),
-    effectState: EffectState.make(),
+    effectState: EffectState.make(clock, undefined),
     rollback: undefined,
     committedFrontier: committedFrontier,
     processedFrontier: Frontier.copy(committedFrontier),
@@ -68,6 +70,8 @@ function make(config, logger, persistence, chainStates, isRealtime, targetBuffer
     exitAfterFirstEventBlock: exitAfterFirstEventBlock,
     onError: onError,
     onExit: onExit,
+    onArrivedAtHead: onArrivedAtHead,
+    reportedArrivalAtHead: false,
     isStopped: false,
     epoch: 0,
     scheduleProcessing: () => {},
@@ -88,7 +92,7 @@ function make(config, logger, persistence, chainStates, isRealtime, targetBuffer
   };
 }
 
-function makeFromDbState(config, logger, persistence, initialState, registrationsByChainId, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, sourceTiming, targetBufferSizeOpt, holdRealtimeOpt, onError, onExit) {
+function makeFromDbState(config, logger, persistence, initialState, registrationsByChainId, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, sourceTiming, targetBufferSizeOpt, holdRealtimeOpt, onError, onExit, onArrivedAtHead) {
   let isDevelopmentMode = isDevelopmentModeOpt !== undefined ? isDevelopmentModeOpt : false;
   let shouldUseTui = shouldUseTuiOpt !== undefined ? shouldUseTuiOpt : false;
   let exitAfterFirstEventBlock = exitAfterFirstEventBlockOpt !== undefined ? exitAfterFirstEventBlockOpt : false;
@@ -99,7 +103,7 @@ function makeFromDbState(config, logger, persistence, initialState, registration
       let sourceBlockNumber = resumedChainState.sourceBlockNumber;
       let maxReorgDepth = resumedChainState.maxReorgDepth;
       if (maxReorgDepth > 0 && sourceBlockNumber > 0) {
-        return progressBlockNumber > (sourceBlockNumber - maxReorgDepth | 0);
+        return progressBlockNumber > ((sourceBlockNumber - maxReorgDepth | 0) - 1 | 0);
       } else {
         return false;
       }
@@ -111,7 +115,7 @@ function makeFromDbState(config, logger, persistence, initialState, registration
     let chainConfig = ChainMap.get(config.chainMap, chainId);
     chainStates[resumedChainState.id] = ChainState.makeFromDbState(chainConfig, resumedChainState, initialState.reorgCheckpoints, isInReorgThreshold, isRealtime, config, initialState.contractMapping, registrationsByChainId, logger, sourceTiming);
   });
-  let state = make(config, logger, persistence, chainStates, isRealtime, targetBufferSize, holdRealtime, initialState.checkpointFrontier, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError, onExit);
+  let state = make(config, logger, persistence, chainStates, isRealtime, targetBufferSize, holdRealtime, initialState.checkpointFrontier, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError, onExit, onArrivedAtHead, Stdlib_Option.flatMap(sourceTiming, timing => timing.clock));
   CrossChainState.markCaughtUpOnResume(state.crossChainState);
   Utils.Dict.forEach(initialState.cache, param => {
     let count = param.count;
@@ -401,6 +405,14 @@ function hasArrivedAtHead(state) {
   return CrossChainState.hasArrivedAtHead(state.crossChainState);
 }
 
+function reportArrivalAtHead(state) {
+  let onArrivedAtHead = state.onArrivedAtHead;
+  if (onArrivedAtHead !== undefined && !state.reportedArrivalAtHead && CrossChainState.isHoldingRealtime(state.crossChainState) && CrossChainState.hasArrivedAtHead(state.crossChainState)) {
+    state.reportedArrivalAtHead = true;
+    return onArrivedAtHead();
+  }
+}
+
 function releaseRealtime(state) {
   CrossChainState.releaseRealtime(state.crossChainState);
   state.scheduleProcessing();
@@ -917,6 +929,7 @@ export {
   bindScheduleProcessing,
   isHoldingRealtime,
   hasArrivedAtHead,
+  reportArrivalAtHead,
   releaseRealtime,
   markReady,
   reportFinished,

package/src/IndexerState.resi

@@ -24,6 +24,8 @@ let make: (
   ~exitAfterFirstEventBlock: bool=?,
   ~onError: ErrorHandling.t => unit,
   ~onExit: unit => unit=?,
+  ~onArrivedAtHead: unit => unit=?,
+  ~clock: Clock.t=?,
 ) => t
 
 let makeFromDbState: (
@@ -40,6 +42,7 @@ let makeFromDbState: (
   ~holdRealtime: bool=?,
   ~onError: ErrorHandling.t => unit,
   ~onExit: unit => unit=?,
+  ~onArrivedAtHead: unit => unit=?,
 ) => t
 
 let unexpectedErrorMsg: string
@@ -106,6 +109,7 @@ let shouldFinalizeIndexes: t => bool
 let bindScheduleProcessing: (t, unit => unit) => unit
 let isHoldingRealtime: t => bool
 let hasArrivedAtHead: t => bool
+let reportArrivalAtHead: t => unit
 // The supervisor's go-ahead for a process driving part of a split run.
 let releaseRealtime: t => unit
 let markReady: (t, ~readyAt: Date.t) => unit