envio 3.5.0-alpha.1 → 3.5.0-alpha.3

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
 
@@ -419,6 +468,18 @@ let crossChainState = (state: t) => state.crossChainState
 let chainStates = (state: t) => state.crossChainState->CrossChainState.chainStates
 let isInReorgThreshold = (state: t) => state.crossChainState->CrossChainState.isInReorgThreshold
 let isRealtime = (state: t) => state.crossChainState->CrossChainState.isRealtime
+
+// The indexer runs Backfilling → FinalizingIndexes → Ready. This is true only
+// in the middle phase: every chain has caught up, but the deferred schema
+// indexes and `ready_at` haven't been committed yet.
+let isFinalizingIndexes = (state: t) =>
+  state.crossChainState->CrossChainState.isCaughtUp &&
+    !(state.crossChainState->CrossChainState.isRealtime)
+
+let markCaughtUp = (state: t) => state.crossChainState->CrossChainState.markCaughtUp
+
+let markReady = (state: t, ~readyAt) => state.crossChainState->CrossChainState.markReady(~readyAt)
+
 let rollbackState = (state: t) => state.rollbackState
 let indexerStartTime = (state: t) => state.indexerStartTime
 let loadManager = (state: t) => state.loadManager
@@ -469,12 +530,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;
 }
@@ -300,6 +336,22 @@ function isRealtime(state) {
   return CrossChainState.isRealtime(state.crossChainState);
 }
 
+function isFinalizingIndexes(state) {
+  if (CrossChainState.isCaughtUp(state.crossChainState)) {
+    return !CrossChainState.isRealtime(state.crossChainState);
+  } else {
+    return false;
+  }
+}
+
+function markCaughtUp(state) {
+  CrossChainState.markCaughtUp(state.crossChainState);
+}
+
+function markReady(state, readyAt) {
+  CrossChainState.markReady(state.crossChainState, readyAt);
+}
+
 function rollbackState(state) {
   return state.rollbackState;
 }
@@ -371,14 +423,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 +757,7 @@ export {
   isProcessing,
   beginProcessing,
   endProcessing,
+  markProcessingStalledOnFetch,
   recordProcessedBatch,
   createBatch,
   getSafeCheckpointId,
@@ -718,6 +778,9 @@ export {
   chainStates,
   isInReorgThreshold,
   isRealtime,
+  isFinalizingIndexes,
+  markCaughtUp,
+  markReady,
   rollbackState,
   indexerStartTime,
   loadManager,
@@ -730,6 +793,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,
@@ -93,6 +94,9 @@ let crossChainState: t => CrossChainState.t
 let chainStates: t => dict<ChainState.t>
 let isInReorgThreshold: t => bool
 let isRealtime: t => bool
+let isFinalizingIndexes: t => bool
+let markCaughtUp: t => unit
+let markReady: (t, ~readyAt: Date.t) => unit
 let rollbackState: t => rollbackState
 let indexerStartTime: t => Date.t
 let loadManager: t => LoadManager.t
@@ -110,6 +114,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/LoadLayer.res

@@ -338,6 +338,7 @@ let loadByFilter = (
 
   let load = async (filters: array<EntityFilter.t>, ~onError as _) => {
     let storage = persistence->Persistence.getInitializedStorageOrThrow
+
     let timerRef =
       indexerState->IndexerState.startStorageLoad(~storage=storage.name, ~operation=key)
 
@@ -345,8 +346,15 @@ let loadByFilter = (
 
     filters->Array.forEach(filter => inMemTable->InMemoryTable.Entity.addEmptyIndex(~filter))
 
+    // Any non-derived field can be filtered on, so the columns this query reads
+    // are indexed on demand before it runs rather than promised by the schema.
+    // Inside the load timing: waiting on the build is time the handler spends
+    // waiting for this operation, and it's the only thing that explains an
+    // occasional very slow getWhere.
+    await storage.ensureQueryIndexes(~table=entityConfig.table, ~filters)
+
     // Loading a superset of rows via a merged query is safe: every loaded
-    // entity is matched against all registered indices, not only the
+    // entity is matched against all registered indexes, not only the
     // query's own filter.
     let queries = filters->EntityFilter.merge
 

package/src/LoadLayer.res.mjs

@@ -190,6 +190,7 @@ function loadByFilter(loadManager, persistence, entityConfig, indexerState, shou
       contents: 0
     };
     filters.forEach(filter => InMemoryTable.Entity.addEmptyIndex(inMemTable, filter));
+    await storage.ensureQueryIndexes(entityConfig.table, filters);
     let queries = EntityFilter.merge(filters);
     await Promise.all(queries.map(async filter => {
       try {

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>>,
 }
 

package/src/Metrics.res

@@ -98,12 +98,19 @@ type sourceHeightMetrics = {
 
 type t = {
   startTime: Date.t,
+  // Wall clock when this snapshot was built, so a scrape can be dated.
+  metricTime: Date.t,
+  // Measured monotonically, not as metricTime - startTime: a wall-clock
+  // correction would otherwise skew the counter shares derived from it.
+  elapsedSeconds: float,
   targetBufferSize: int,
   isInReorgThreshold: bool,
   rollbackEnabled: bool,
   maxBatchSize: int,
   preloadSeconds: float,
   processingSeconds: float,
+  processingStalledOnFetchSeconds: float,
+  processingStalledOnStorageWriteSeconds: float,
   rollbackSeconds: float,
   rollbackCount: int,
   rollbackEventsCount: float,
@@ -241,6 +248,24 @@ let renderMetrics = (b: builder, metrics: t) => {
     byLabels->Dict.toArray
   }
 
+  b->single(
+    ~name="envio_process_start_time_seconds",
+    ~help="Start time of the process since unix epoch in seconds.",
+    ~kind="gauge",
+    ~value=metrics.startTime->Date.getTime /. 1000.,
+  )
+  b->single(
+    ~name="envio_process_metric_time_seconds",
+    ~help="The time these metrics were collected. Use it to tell how fresh a snapshot is, or to measure rates between two snapshots.",
+    ~kind="gauge",
+    ~value=metrics.metricTime->Date.getTime /. 1000.,
+  )
+  b->single(
+    ~name="envio_process_elapsed_seconds",
+    ~help="How long the indexer has been running. Divide a cumulative seconds metric by this to get the share of the run it took, eg envio_processing_seconds for time spent in event handlers.",
+    ~kind="gauge",
+    ~value=metrics.elapsedSeconds,
+  )
   b->single(
     ~name="envio_preload_seconds",
     ~help="Cumulative time spent on preloading entities during batch processing.",
@@ -253,6 +278,18 @@ let renderMetrics = (b: builder, metrics: t) => {
     ~kind="counter",
     ~value=metrics.processingSeconds,
   )
+  b->single(
+    ~name="envio_processing_stalled_on_fetch_seconds",
+    ~help="Time the indexer had nothing to process while waiting for events to be fetched. A high rate means fetching is the bottleneck: check the data-source latency and whether it can be queried with more concurrency. Waiting at the chain head for new blocks is not counted.",
+    ~kind="counter",
+    ~value=metrics.processingStalledOnFetchSeconds,
+  )
+  b->single(
+    ~name="envio_processing_stalled_on_storage_write_seconds",
+    ~help="Time the indexer paused processing because too many changes were still waiting to be written. A high rate means storage writes are the bottleneck: check envio_storage_write_seconds and the database performance.",
+    ~kind="counter",
+    ~value=metrics.processingStalledOnStorageWriteSeconds,
+  )
   b->series(
     ~name="envio_progress_ready",
     ~help="Whether the chain is fully synced to the head.",
@@ -346,12 +383,6 @@ let renderMetrics = (b: builder, metrics: t) => {
     ~entries=chains,
     ~value=m => m.sourceBlockNumber->Int.toFloat,
   )
-  b->single(
-    ~name="envio_process_start_time_seconds",
-    ~help="Start time of the process since unix epoch in seconds.",
-    ~kind="gauge",
-    ~value=metrics.startTime->Date.getTime /. 1000.,
-  )
   b->series(
     ~name="envio_indexing_concurrency",
     ~help="The number of executing concurrent queries to the chain data-source.",

package/src/Metrics.res.mjs

@@ -108,8 +108,13 @@ function renderMetrics(b, metrics) {
     }
   });
   let sources = Object.entries(byLabels$1);
+  single(b, "envio_process_start_time_seconds", "Start time of the process since unix epoch in seconds.", "gauge", metrics.startTime.getTime() / 1000);
+  single(b, "envio_process_metric_time_seconds", "The time these metrics were collected. Use it to tell how fresh a snapshot is, or to measure rates between two snapshots.", "gauge", metrics.metricTime.getTime() / 1000);
+  single(b, "envio_process_elapsed_seconds", "How long the indexer has been running. Divide a cumulative seconds metric by this to get the share of the run it took, eg envio_processing_seconds for time spent in event handlers.", "gauge", metrics.elapsedSeconds);
   single(b, "envio_preload_seconds", "Cumulative time spent on preloading entities during batch processing.", "counter", metrics.preloadSeconds);
   single(b, "envio_processing_seconds", "Cumulative time spent executing event handlers during batch processing.", "counter", metrics.processingSeconds);
+  single(b, "envio_processing_stalled_on_fetch_seconds", "Time the indexer had nothing to process while waiting for events to be fetched. A high rate means fetching is the bottleneck: check the data-source latency and whether it can be queried with more concurrency. Waiting at the chain head for new blocks is not counted.", "counter", metrics.processingStalledOnFetchSeconds);
+  single(b, "envio_processing_stalled_on_storage_write_seconds", "Time the indexer paused processing because too many changes were still waiting to be written. A high rate means storage writes are the bottleneck: check envio_storage_write_seconds and the database performance.", "counter", metrics.processingStalledOnStorageWriteSeconds);
   series(b, "envio_progress_ready", "Whether the chain is fully synced to the head.", "gauge", chains, m => {
     if (m.isReady) {
       return 1;
@@ -129,7 +134,6 @@ function renderMetrics(b, metrics) {
   series(b, "envio_fetching_block_range_events_total", "Cumulative number of events fetched across all block range operations.", "counter", chains, m => m.blockRangeFetchedEvents);
   series(b, "envio_fetching_block_range_size", "Cumulative number of blocks covered across all block range fetch operations.", "counter", chains, m => m.blockRangeFetchedBlocks);
   series(b, "envio_indexing_known_height", "The latest known block number reported by the active indexing source. This value may lag behind the actual chain height, as it is updated only when needed.", "gauge", chains, m => m.sourceBlockNumber);
-  single(b, "envio_process_start_time_seconds", "Start time of the process since unix epoch in seconds.", "gauge", metrics.startTime.getTime() / 1000);
   series(b, "envio_indexing_concurrency", "The number of executing concurrent queries to the chain data-source.", "gauge", chains, m => m.concurrency);
   series(b, "envio_indexing_partitions", "The number of partitions used to split fetching logic by addresses and block ranges.", "gauge", chains, m => m.partitionsCount);
   series(b, "envio_indexing_idle_seconds", "The time the indexer source syncing has been idle. A high value may indicate the source sync is a bottleneck.", "counter", chains, m => m.idleSeconds);

package/src/Persistence.res

@@ -89,6 +89,17 @@ type storage = {
   // Field values are serialized and rows parsed with the table's field schemas.
   @raises("StorageError")
   loadOrThrow: (~filter: EntityFilter.t, ~table: Table.table) => promise<array<unknown>>,
+  // Creates whatever indexes the filters need and aren't there yet, resolving
+  // once they're queryable. Best-effort: it resolves even when a build fails,
+  // leaving the query to run unindexed rather than failing the handler.
+  ensureQueryIndexes: (~table: Table.table, ~filters: array<EntityFilter.t>) => promise<unit>,
+  // Creates every schema-defined index still missing and stamps `ready_at` on
+  // the given chains, atomically. Called once, when backfill completes.
+  finalizeBackfill: (
+    ~entities: array<Internal.entityConfig>,
+    ~chainIds: array<int>,
+    ~readyAt: Date.t,
+  ) => promise<unit>,
   // This is to download cache from the database to .envio/cache
   dumpEffectCache: unit => promise<unit>,
   reset: unit => promise<unit>,
@@ -121,7 +132,7 @@ type storage = {
   getRollbackData: (
     ~entityConfig: Internal.entityConfig,
     ~rollbackTargetCheckpointId: Internal.checkpointId,
-  ) => promise<(array<string>, array<unknown>)>,
+  ) => promise<(array<EntityId.t>, array<unknown>)>,
   // Write batch to storage
   writeBatch: (
     ~batch: Batch.t,