envio 3.5.0-alpha.1 → 3.5.0-alpha.2

package/src/HandlerRegister.res

@@ -215,6 +215,25 @@ let mergeRegistrations = (resolved: array<Internal.onEventRegistration>, ~config
 let isDroppedByWhere = (~config: Config.t, reg: Internal.onEventRegistration) =>
   config.ecosystem.name === Evm && (reg->getResolvedWhere).topicSelections->Utils.Array.isEmpty
 
+// Names configured across every chain, used to explain a registration that
+// matched nothing. Only built on the failure path.
+let describeConfigured = (registration: activeRegistration, ~contractName) => {
+  let contractNames = Utils.Set.make()
+  let eventNames = Utils.Set.make()
+  registration.config.chainMap
+  ->ChainMap.values
+  ->Array.forEach(chainConfig =>
+    chainConfig.contracts->Array.forEach(contract => {
+      contractNames->Utils.Set.add(contract.name)->ignore
+      if contract.name === contractName {
+        contract.events->Array.forEach(e => eventNames->Utils.Set.add(e.name)->ignore)
+      }
+    })
+  )
+  let sorted = set => set->Utils.Set.toArray->Array.toSorted(String.compare)
+  (sorted(contractNames), sorted(eventNames))
+}
+
 // Resolve one `onEvent`/`contractRegister` call into a registration for every
 // chain in the config (the full chain set) and store it in registration order.
 // Building runs the user's `where` callback here — once per chain — so a broken
@@ -230,6 +249,7 @@ let addOnEventRegistration = (
 ) => {
   let isWildcard = eventOptions->Option.flatMap(v => v.wildcard)->Option.getOr(false)
   let where = eventOptions->Option.flatMap(v => v.where)
+  let matched = ref(false)
   registration.config.chainMap
   ->ChainMap.values
   ->Array.forEach(chainConfig =>
@@ -239,6 +259,7 @@ let addOnEventRegistration = (
       switch contract.events->Array.find(e => e.name === eventName) {
       | None => ()
       | Some(eventConfig) =>
+        matched := true
         let reg = buildOnEventRegistrationWith(
           ~config=registration.config,
           ~chainId=chainConfig.id,
@@ -255,6 +276,30 @@ let addOnEventRegistration = (
       }
     }
   )
+
+  // Nothing matched on any chain, so the callback could never be dispatched.
+  // Reported at the registration call site, where the stack still points at the
+  // offending `onEvent`/`contractRegister`.
+  if !matched.contents {
+    let (contractNames, eventNames) = registration->describeConfigured(~contractName)
+    let listOr = (names, empty) =>
+      names->Utils.Array.isEmpty ? empty : names->Array.joinUnsafe(", ")
+    if eventNames->Utils.Array.isEmpty {
+      JsError.throwWithMessage(
+        `Contract "${contractName}" is not configured on any chain, so its handler for "${eventName}" would never run. Add it to your config, or remove the registration. Configured contracts: ${listOr(
+            contractNames,
+            "none",
+          )}.`,
+      )
+    } else {
+      JsError.throwWithMessage(
+        `Event "${eventName}" is not configured on contract "${contractName}", so its handler would never run. Add it to your config, or remove the registration. Configured events on "${contractName}": ${listOr(
+            eventNames,
+            "none",
+          )}.`,
+      )
+    }
+  }
 }
 
 let setHandler = (~contractName, ~eventName, handler, ~eventOptions) => {

package/src/HandlerRegister.res.mjs

@@ -8,6 +8,7 @@ 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_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 import * as EventConfigBuilder from "./EventConfigBuilder.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
@@ -145,9 +146,33 @@ function isDroppedByWhere(config, reg) {
   }
 }
 
+function describeConfigured(registration, contractName) {
+  let contractNames = new Set();
+  let eventNames = new Set();
+  ChainMap.values(registration.config.chainMap).forEach(chainConfig => {
+    chainConfig.contracts.forEach(contract => {
+      contractNames.add(contract.name);
+      if (contract.name === contractName) {
+        contract.events.forEach(e => {
+          eventNames.add(e.name);
+        });
+        return;
+      }
+    });
+  });
+  let sorted = set => Array.from(set).toSorted(Primitive_string.compare);
+  return [
+    sorted(contractNames),
+    sorted(eventNames)
+  ];
+}
+
 function addOnEventRegistration(registration, contractName, eventName, handler, contractRegister, eventOptions) {
   let isWildcard = Stdlib_Option.getOr(Stdlib_Option.flatMap(eventOptions, v => v.wildcard), false);
   let where = Stdlib_Option.flatMap(eventOptions, v => v.where);
+  let matched = {
+    contents: false
+  };
   ChainMap.values(registration.config.chainMap).forEach(chainConfig => {
     let contract = chainConfig.contracts.find(c => c.name === contractName);
     if (contract === undefined) {
@@ -157,9 +182,27 @@ function addOnEventRegistration(registration, contractName, eventName, handler,
     if (eventConfig === undefined) {
       return;
     }
+    matched.contents = true;
     let reg = buildOnEventRegistrationWith(registration.config, chainConfig.id, eventConfig, isWildcard, handler, contractRegister, where, contract.startBlock);
     getChainRegistrations(registration, chainConfig.id).onEventRegistrations.push(reg);
   });
+  if (matched.contents) {
+    return;
+  }
+  let match = describeConfigured(registration, contractName);
+  let eventNames = match[1];
+  let listOr = (names, empty) => {
+    if (Utils.$$Array.isEmpty(names)) {
+      return empty;
+    } else {
+      return names.join(", ");
+    }
+  };
+  if (Utils.$$Array.isEmpty(eventNames)) {
+    return Stdlib_JsError.throwWithMessage(`Contract "` + contractName + `" is not configured on any chain, so its handler for "` + eventName + `" would never run. Add it to your config, or remove the registration. Configured contracts: ` + listOr(match[0], "none") + `.`);
+  } else {
+    return Stdlib_JsError.throwWithMessage(`Event "` + eventName + `" is not configured on contract "` + contractName + `", so its handler would never run. Add it to your config, or remove the registration. Configured events on "` + contractName + `": ` + listOr(eventNames, "none") + `.`);
+  }
 }
 
 function setHandler(contractName, eventName, handler, eventOptions) {

package/src/InMemoryStore.res

@@ -45,7 +45,10 @@ let setEffectOutput = (
   | Some(_) => ()
   | None => inMemTable.changesCount = inMemTable.changesCount +. 1.
   }
-  inMemTable.dict->Dict.set(cacheKey, Set({entityId: cacheKey, entity: output, checkpointId}))
+  inMemTable.dict->Dict.set(
+    cacheKey,
+    Set({entityId: cacheKey->EntityId.unsafeOfString, entity: output, checkpointId}),
+  )
   if shouldCache {
     inMemTable.idsToStore->Array.push(cacheKey)->ignore
   }
@@ -58,7 +61,11 @@ let initEffectOutputFromDb = (inMemTable: EffectState.effectCacheInMemTable, ~ca
     inMemTable.changesCount = inMemTable.changesCount +. 1.
     inMemTable.dict->Dict.set(
       cacheKey,
-      Set({entityId: cacheKey, entity: output, checkpointId: Internal.loadedFromDbCheckpointId}),
+      Set({
+        entityId: cacheKey->EntityId.unsafeOfString,
+        entity: output,
+        checkpointId: Internal.loadedFromDbCheckpointId,
+      }),
     )
   }
 
@@ -131,7 +138,7 @@ let prepareRollbackDiff = async (
       entityTable->InMemoryTable.Entity.set(
         ~committedCheckpointId,
         Set({
-          entityId: entity.id,
+          entityId: entity.id->EntityId.unsafeOfString,
           checkpointId: rollbackDiffCheckpointId,
           entity,
         }),
@@ -177,7 +184,7 @@ let setBatchDcs = (state: IndexerState.t, ~batch: Batch.t) => {
           inMemTable->InMemoryTable.Entity.set(
             ~committedCheckpointId,
             Set({
-              entityId: entity.id,
+              entityId: entity.id->EntityId.unsafeOfString,
               checkpointId,
               entity: entity->InternalTable.EnvioAddresses.castToInternal,
             }),

package/src/InMemoryTable.res

@@ -17,11 +17,13 @@ module Entity = {
     mutable filterIndices: filterIndices,
   }
 
-  // Helper to extract entity ID from any entity
+  // 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.
   exception UnexpectedIdNotDefinedOnEntity
   let getEntityIdUnsafe = (entity: Internal.entity): string =>
-    switch (entity->(Utils.magic: Internal.entity => {"id": option<string>}))["id"] {
-    | Some(id) => id
+    switch (entity->(Utils.magic: Internal.entity => {"id": option<EntityId.t>}))["id"] {
+    | Some(id) => id->EntityId.toKey
     | None =>
       UnexpectedIdNotDefinedOnEntity->ErrorHandling.mkLogAndRaise(
         ~msg="Property 'id' does not exist on expected entity object",
@@ -142,8 +144,8 @@ module Entity = {
     }
 
   let set = (inMemTable: t, ~committedCheckpointId, change: Change.t<Internal.entity>) => {
-    let entityId = change->Change.getEntityId
-    switch inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(entityId) {
+    let entityKey = change->Change.getEntityId->EntityId.toKey
+    switch inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(entityKey) {
     | Some(prev) =>
       let prevCheckpointId = prev->Change.getCheckpointId
       if (
@@ -158,9 +160,9 @@ module Entity = {
 
     switch change {
     | Set({entity}) => inMemTable->updateIndices(~entity)
-    | Delete({entityId}) => inMemTable->deleteEntityFromIndices(~entityId)
+    | Delete({entityId}) => inMemTable->deleteEntityFromIndices(~entityId=entityId->EntityId.toKey)
     }
-    inMemTable.latestEntityChangeById->Dict.set(entityId, change)
+    inMemTable.latestEntityChangeById->Dict.set(entityKey, change)
   }
 
   // Only writes when the id isn't already present, so set always takes its
@@ -172,10 +174,10 @@ module Entity = {
     ~entity: option<Internal.entity>,
   ) =>
     if inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(key)->Option.isNone {
+      let entityId = key->EntityId.unsafeOfString
       let change: Change.t<Internal.entity> = switch entity {
-      | Some(entity) =>
-        Set({entityId: key, entity, checkpointId: Internal.loadedFromDbCheckpointId})
-      | None => Delete({entityId: key, checkpointId: Internal.loadedFromDbCheckpointId})
+      | Some(entity) => Set({entityId, entity, checkpointId: Internal.loadedFromDbCheckpointId})
+      | None => Delete({entityId, checkpointId: Internal.loadedFromDbCheckpointId})
       }
       inMemTable->set(~committedCheckpointId, change)
     }

package/src/InMemoryTable.res.mjs

@@ -1,6 +1,7 @@
 // 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";
@@ -15,7 +16,7 @@ let UnexpectedIdNotDefinedOnEntity = /* @__PURE__ */Primitive_exceptions.create(
 function getEntityIdUnsafe(entity) {
   let id = entity.id;
   if (id !== undefined) {
-    return id;
+    return EntityId.toKey(Primitive_option.valFromOption(id));
   } else {
     return ErrorHandling.mkLogAndRaise(undefined, "Property 'id' does not exist on expected entity object", {
       RE_EXN_ID: UnexpectedIdNotDefinedOnEntity
@@ -126,8 +127,8 @@ function deleteEntityFromIndices(self, entityId) {
 }
 
 function set(inMemTable, committedCheckpointId, change) {
-  let entityId = change.entityId;
-  let prev = inMemTable.latestEntityChangeById[entityId];
+  let entityKey = EntityId.toKey(change.entityId);
+  let prev = inMemTable.latestEntityChangeById[entityKey];
   if (prev !== undefined) {
     let prevCheckpointId = prev.checkpointId;
     if (prevCheckpointId > committedCheckpointId && prevCheckpointId < change.checkpointId) {
@@ -140,9 +141,9 @@ function set(inMemTable, committedCheckpointId, change) {
   if (change.type === "SET") {
     updateIndices(inMemTable, change.entity);
   } else {
-    deleteEntityFromIndices(inMemTable, change.entityId);
+    deleteEntityFromIndices(inMemTable, EntityId.toKey(change.entityId));
   }
-  inMemTable.latestEntityChangeById[entityId] = change;
+  inMemTable.latestEntityChangeById[entityKey] = change;
 }
 
 function initValue(inMemTable, committedCheckpointId, key, entity) {

package/src/IndexerState.res

@@ -107,6 +107,10 @@ type t = {
   crossChainState: CrossChainState.t,
   mutable rollbackState: rollbackState,
   indexerStartTime: Date.t,
+  // Monotonic peer of indexerStartTime. Elapsed run time is derived from this so
+  // an NTP correction can't move it out of step with the Performance-based
+  // counters that get divided by it.
+  indexerStartTimeRef: Performance.timeRef,
   // When an entity's history was last pruned. No key = never pruned yet,
   // which counts as overdue.
   lastPrunedAtMillis: dict<float>,
@@ -133,6 +137,12 @@ type t = {
   // --- Metric counters, rendered by Metrics at scrape time. ---
   mutable preloadSeconds: float,
   mutable processingSeconds: float,
+  mutable processingStalledOnFetchSeconds: float,
+  // Set while the processing loop is idle after starving on an empty buffer;
+  // None while processing or when the loop stopped for a reorg/shutdown. The
+  // getter folds the in-progress interval in so a scrape mid-stall isn't stale.
+  mutable processingStalledOnFetchSince: option<Performance.timeRef>,
+  mutable processingStalledOnStorageWriteSeconds: float,
   handlerStats: dict<handlerStat>,
   storageLoadStats: dict<storageLoadStat>,
   storageWriteStats: dict<storageWriteStat>,
@@ -194,6 +204,7 @@ let make = (
       ~targetBufferSize,
     ),
     indexerStartTime: Date.make(),
+    indexerStartTimeRef: Performance.now(),
     rollbackState: NoRollback,
     lastPrunedAtMillis: Dict.make(),
     loadManager: LoadManager.make(),
@@ -206,6 +217,9 @@ let make = (
     simulateDeadInputTracker: SimulateDeadInputTracker.makeFromConfig(config),
     preloadSeconds: 0.,
     processingSeconds: 0.,
+    processingStalledOnFetchSeconds: 0.,
+    processingStalledOnFetchSince: None,
+    processingStalledOnStorageWriteSeconds: 0.,
     handlerStats: Dict.make(),
     storageLoadStats: Dict.make(),
     storageWriteStats: Dict.make(),
@@ -315,8 +329,22 @@ let isResolvingReorg = (state: t) =>
 // reports the first error so redundant handlers (eg an error caught in two
 // nested scopes) don't double-report.
 @inline
+let // Close an open fetch-stall interval, accruing it into the counter. Called
+// whenever the reason for the idle changes, so the interval never spans into
+// time another counter owns — or, at shutdown, past the point where the loops
+// stop and nothing would ever close it.
+settleStalledOnFetch = (state: t) =>
+  switch state.processingStalledOnFetchSince {
+  | Some(since) =>
+    state.processingStalledOnFetchSeconds =
+      state.processingStalledOnFetchSeconds +. since->Performance.secondsSince
+    state.processingStalledOnFetchSince = None
+  | None => ()
+  }
+
 let errorExit = (state: t, errHandler) =>
   if !state.isStopped {
+    state->settleStalledOnFetch
     state.isStopped = true
     state.onError(errHandler)
   }
@@ -325,7 +353,10 @@ let unexpectedErrorMsg = "Indexer has failed with an unexpected error"
 
 // Halt the loops without reporting an error, eg to hand the shared db over to a
 // resumed indexer in tests.
-let stop = (state: t) => state.isStopped = true
+let stop = (state: t) => {
+  state->settleStalledOnFetch
+  state.isStopped = true
+}
 
 let getChainState = (state: t, ~chain: chain): ChainState.t =>
   switch state.crossChainState
@@ -360,6 +391,9 @@ let enterReorgThreshold = (state: t) => state.crossChainState->CrossChainState.e
 // caller has already mutated the chain states (restored counters, reset pending
 // queries). isResolvingReorg derives from rollbackState.
 let beginReorg = (state: t, ~chain, ~blockNumber) => {
+  // Settle here, or the rollback that follows would be folded into the stall on
+  // the next beginProcessing — time envio_rollback_seconds already counts.
+  state->settleStalledOnFetch
   state.epoch = state.epoch + 1
   state.rollbackState = ReorgDetected({chain, blockNumber})
 }
@@ -391,9 +425,24 @@ let applyBatchProgress = (state: t, ~batch: Batch.t) =>
 // Processing-loop mutex. Guards ProcessEventBatch re-entry so only one
 // processing loop runs at a time.
 let isProcessing = (state: t) => state.isProcessing
-let beginProcessing = (state: t) => state.isProcessing = true
+let beginProcessing = (state: t) => {
+  state->settleStalledOnFetch
+  state.isProcessing = true
+}
 let endProcessing = (state: t) => state.isProcessing = false
 
+// Start attributing idle time to fetch starvation. Called when the processing
+// loop exits with no work left; skipped when it exits for a reorg or shutdown,
+// so only genuine buffer starvation is counted.
+let markProcessingStalledOnFetch = (state: t) =>
+  if state.processingStalledOnFetchSince->Option.isNone {
+    state.processingStalledOnFetchSince = Some(Performance.now())
+  }
+
+let recordStalledOnStorageWrite = (state: t, ~seconds) =>
+  state.processingStalledOnStorageWriteSeconds =
+    state.processingStalledOnStorageWriteSeconds +. seconds
+
 let recordProcessedBatch = (state: t) =>
   state.processedBatchesCount = state.processedBatchesCount + 1
 
@@ -469,12 +518,20 @@ let toMetrics = (state: t): Metrics.t => {
   )
   {
     startTime: state.indexerStartTime,
+    metricTime: Date.make(),
+    elapsedSeconds: state.indexerStartTimeRef->Performance.secondsSince,
     targetBufferSize: state.crossChainState->CrossChainState.targetBufferSize,
     isInReorgThreshold: state.crossChainState->CrossChainState.isInReorgThreshold,
     rollbackEnabled: state.config.shouldRollbackOnReorg,
     maxBatchSize: state.config.batchSize,
     preloadSeconds: state.preloadSeconds,
     processingSeconds: state.processingSeconds,
+    processingStalledOnFetchSeconds: state.processingStalledOnFetchSeconds +.
+    switch state.processingStalledOnFetchSince {
+    | Some(since) => since->Performance.secondsSince
+    | None => 0.
+    },
+    processingStalledOnStorageWriteSeconds: state.processingStalledOnStorageWriteSeconds,
     rollbackSeconds: state.rollbackSeconds,
     rollbackCount: state.rollbackCount,
     rollbackEventsCount: state.rollbackEventsCount,

package/src/IndexerState.res.mjs

@@ -76,6 +76,7 @@ function make$1(config, persistence, chainStates, isInReorgThreshold, isRealtime
     crossChainState: CrossChainState.make(chainStates, isInReorgThreshold, isRealtime, targetBufferSize),
     rollbackState: "NoRollback",
     indexerStartTime: new Date(),
+    indexerStartTimeRef: Performance.now(),
     lastPrunedAtMillis: {},
     loadManager: LoadManager.make(),
     keepProcessAlive: isDevelopmentMode || shouldUseTui,
@@ -87,6 +88,9 @@ function make$1(config, persistence, chainStates, isInReorgThreshold, isRealtime
     simulateDeadInputTracker: SimulateDeadInputTracker.makeFromConfig(config),
     preloadSeconds: 0,
     processingSeconds: 0,
+    processingStalledOnFetchSeconds: 0,
+    processingStalledOnFetchSince: undefined,
+    processingStalledOnStorageWriteSeconds: 0,
     handlerStats: {},
     storageLoadStats: {},
     storageWriteStats: {},
@@ -145,13 +149,24 @@ function isResolvingReorg(state) {
 }
 
 function errorExit(state, errHandler) {
-  if (!state.isStopped) {
-    state.isStopped = true;
-    return state.onError(errHandler);
+  if (state.isStopped) {
+    return;
   }
+  let since = state.processingStalledOnFetchSince;
+  if (since !== undefined) {
+    state.processingStalledOnFetchSeconds = state.processingStalledOnFetchSeconds + Performance.secondsSince(since);
+    state.processingStalledOnFetchSince = undefined;
+  }
+  state.isStopped = true;
+  state.onError(errHandler);
 }
 
 function stop(state) {
+  let since = state.processingStalledOnFetchSince;
+  if (since !== undefined) {
+    state.processingStalledOnFetchSeconds = state.processingStalledOnFetchSeconds + Performance.secondsSince(since);
+    state.processingStalledOnFetchSince = undefined;
+  }
   state.isStopped = true;
 }
 
@@ -177,6 +192,11 @@ function enterReorgThreshold(state) {
 }
 
 function beginReorg(state, chain, blockNumber) {
+  let since = state.processingStalledOnFetchSince;
+  if (since !== undefined) {
+    state.processingStalledOnFetchSeconds = state.processingStalledOnFetchSeconds + Performance.secondsSince(since);
+    state.processingStalledOnFetchSince = undefined;
+  }
   state.epoch = state.epoch + 1 | 0;
   state.rollbackState = {
     TAG: "ReorgDetected",
@@ -221,6 +241,11 @@ function isProcessing(state) {
 }
 
 function beginProcessing(state) {
+  let since = state.processingStalledOnFetchSince;
+  if (since !== undefined) {
+    state.processingStalledOnFetchSeconds = state.processingStalledOnFetchSeconds + Performance.secondsSince(since);
+    state.processingStalledOnFetchSince = undefined;
+  }
   state.isProcessing = true;
 }
 
@@ -228,6 +253,17 @@ function endProcessing(state) {
   state.isProcessing = false;
 }
 
+function markProcessingStalledOnFetch(state) {
+  if (Stdlib_Option.isNone(state.processingStalledOnFetchSince)) {
+    state.processingStalledOnFetchSince = Performance.now();
+    return;
+  }
+}
+
+function recordStalledOnStorageWrite(state, seconds) {
+  state.processingStalledOnStorageWriteSeconds = state.processingStalledOnStorageWriteSeconds + seconds;
+}
+
 function recordProcessedBatch(state) {
   state.processedBatchesCount = state.processedBatchesCount + 1 | 0;
 }
@@ -371,14 +407,21 @@ function toMetrics(state) {
       count: s.count
     });
   });
+  let since = state.processingStalledOnFetchSince;
   return {
     startTime: state.indexerStartTime,
+    metricTime: new Date(),
+    elapsedSeconds: Performance.secondsSince(state.indexerStartTimeRef),
     targetBufferSize: CrossChainState.targetBufferSize(state.crossChainState),
     isInReorgThreshold: CrossChainState.isInReorgThreshold(state.crossChainState),
     rollbackEnabled: state.config.shouldRollbackOnReorg,
     maxBatchSize: state.config.batchSize,
     preloadSeconds: state.preloadSeconds,
     processingSeconds: state.processingSeconds,
+    processingStalledOnFetchSeconds: state.processingStalledOnFetchSeconds + (
+      since !== undefined ? Performance.secondsSince(since) : 0
+    ),
+    processingStalledOnStorageWriteSeconds: state.processingStalledOnStorageWriteSeconds,
     rollbackSeconds: state.rollbackSeconds,
     rollbackCount: state.rollbackCount,
     rollbackEventsCount: state.rollbackEventsCount,
@@ -698,6 +741,7 @@ export {
   isProcessing,
   beginProcessing,
   endProcessing,
+  markProcessingStalledOnFetch,
   recordProcessedBatch,
   createBatch,
   getSafeCheckpointId,
@@ -730,6 +774,7 @@ export {
   simulateDeadInputTracker,
   toMetrics,
   recordBatchDurations,
+  recordStalledOnStorageWrite,
   recordHandlerDuration,
   startPreloadHandler,
   endPreloadHandler,

package/src/IndexerState.resi

@@ -66,6 +66,7 @@ let applyBatchProgress: (t, ~batch: Batch.t) => unit
 let isProcessing: t => bool
 let beginProcessing: t => unit
 let endProcessing: t => unit
+let markProcessingStalledOnFetch: t => unit
 let recordProcessedBatch: t => unit
 let createBatch: (
   t,
@@ -110,6 +111,7 @@ let toMetrics: t => Metrics.t
 
 // Metric counters.
 let recordBatchDurations: (t, ~loadDuration: float, ~handlerDuration: float) => unit
+let recordStalledOnStorageWrite: (t, ~seconds: float) => unit
 let recordHandlerDuration: (t, ~contract: string, ~event: string, ~duration: float) => unit
 let startPreloadHandler: (t, ~contract: string, ~event: string) => Performance.timeRef
 let endPreloadHandler: (t, Performance.timeRef, ~contract: string, ~event: string) => unit

package/src/Internal.res

@@ -333,6 +333,11 @@ type eventPayload
 // The log's emitting address (EVM/Fuel; the program id carries it for SVM).
 @get external getPayloadSrcAddress: eventPayload => Address.t = "srcAddress"
 
+// The decoded params, read by name for the address-valued ones a `where`
+// filters on. Only those names are ever looked up, so the address type is
+// accurate at every use site.
+@get external getPayloadAddressParams: eventPayload => dict<Address.t> = "params"
+
 type genericLoaderArgs<'event, 'context> = {
   event: 'event,
   context: 'context,
@@ -356,11 +361,11 @@ type genericHandlerArgs<'event, 'context> = {
 type genericHandler<'args> = 'args => promise<unit>
 
 type entityHandlerContext<'entity> = {
-  get: string => promise<option<'entity>>,
-  getOrThrow: (string, ~message: string=?) => promise<'entity>,
+  get: EntityId.t => promise<option<'entity>>,
+  getOrThrow: (EntityId.t, ~message: string=?) => promise<'entity>,
   getOrCreate: 'entity => promise<'entity>,
   set: 'entity => unit,
-  deleteUnsafe: string => unit,
+  deleteUnsafe: EntityId.t => unit,
 }
 
 type chainInfo = {
@@ -572,11 +577,15 @@ type onEventRegistration = {
   // Usually always false for wildcard events, but might be true for a wildcard
   // event with a dynamic event filter by addresses.
   dependsOnAddresses: bool,
-  // Precompiled predicate for events that filter an indexed address param by
-  // registered addresses (see `EventConfigBuilder.buildAddressFilter`); drops a
-  // decoded event whose param-address isn't registered at/before the log's
-  // block. Absent otherwise.
-  clientAddressFilter?: (eventPayload, int, dict<indexingContract>) => bool,
+  // Indexed address params this event filters on, in disjunctive normal form
+  // (OR of AND-groups), from `where: {params: {to: chain.C.addresses}}`. Every
+  // source applies this natively while routing; it's carried here for the
+  // simulate source, which has no native query boundary. Absent otherwise.
+  //
+  // Keep it optional: with every field required, ReScript compiles a
+  // `{...registration, ...}` spread into an explicit field-by-field copy, which
+  // drops the ecosystem-only fields an `evmOnEventRegistration` carries.
+  addressFilterParamGroups?: array<array<string>>,
   // Final start block: the contract/chain config value, overridden by a
   // `where.block.number._gte` when the registered `where` supplies one.
   startBlock: option<int>,

package/src/LogSelection.res

@@ -23,7 +23,8 @@ type parsedWhere = {
   filterByAddresses: bool,
   // Indexed params filtered by `chain.<Contract>.addresses`, in disjunctive
   // normal form (outer array OR of AND-groups). Empty unless `filterByAddresses`.
-  // Consumed by the codegen of the event's `clientAddressFilter`.
+  // Applied natively by every source while routing; carried on the registration
+  // for the simulate source, which has no native query boundary.
   addressFilterParamGroups: array<array<string>>,
 }