envio 3.5.0-alpha.2 → 3.5.0-rc.0

package/src/IndexerState.res

@@ -1,9 +1,8 @@
-type chain = ChainMap.Chain.t
 type rollbackState =
   | NoRollback
-  | ReorgDetected({chain: chain, blockNumber: int})
+  | ReorgDetected({chainId: ChainId.t, blockNumber: int})
   | FindingReorgDepth
-  | FoundReorgDepth({chain: chain, rollbackTargetBlockNumber: int})
+  | FoundReorgDepth({chainId: ChainId.t, rollbackTargetBlockNumber: int})
   | RollbackReady({eventsProcessedDiffByChain: dict<float>})
 
 module EntityTables = {
@@ -90,6 +89,10 @@ type t = {
   mutable processedBatchesCount: int,
   // The single in-flight write loop, None when idle.
   mutable writeFiber: option<promise<unit>>,
+  // The single in-flight finalization, None when none is running. Every path
+  // that reaches the FinalizingIndexes phase awaits this one instead of
+  // starting a second pass over the same indexes.
+  mutable finalizeFiber: option<promise<unit>>,
   // Set once a write throws, to stop the loop. The error itself goes to onError.
   mutable hasFailedWrite: bool,
   // Resolved after every commit so capacity/flush waiters can re-evaluate.
@@ -191,6 +194,7 @@ let make = (
     processedBatches: [],
     processedBatchesCount: 0,
     writeFiber: None,
+    finalizeFiber: None,
     hasFailedWrite: false,
     commitWaiters: [],
     chainMeta: Dict.make(),
@@ -256,27 +260,26 @@ let makeFromDbState = (
     false
   } else {
     // Check if any chain is in reorg threshold by comparing progress with sourceBlock - maxReorgDepth.
-    initialState.chains->Array.some(chain =>
+    initialState.chains->Array.some(resumedChainState =>
       isProgressInReorgThreshold(
-        ~progressBlockNumber=chain.progressBlockNumber,
-        ~sourceBlockNumber=chain.sourceBlockNumber,
-        ~maxReorgDepth=chain.maxReorgDepth,
+        ~progressBlockNumber=resumedChainState.progressBlockNumber,
+        ~sourceBlockNumber=resumedChainState.sourceBlockNumber,
+        ~maxReorgDepth=resumedChainState.maxReorgDepth,
       )
     )
   }
 
-  // updateSyncTimeOnRestart wipes the saved timestamp so a restart re-enters
-  // backfill mode for all chains.
+  // `ready_at` is durable: a chain that once caught up resumes realtime, and the
+  // deferred indexes committed alongside that stamp are not owed again.
   let isRealtime =
-    !Env.updateSyncTimeOnRestart &&
     initialState.chains->Array.length > 0 &&
-    initialState.chains->Array.every(c => c.timestampCaughtUpToHeadOrEndblock->Option.isSome)
+      initialState.chains->Array.every(c => c.timestampCaughtUpToHeadOrEndblock->Option.isSome)
 
   let chainStates = Dict.make()
   initialState.chains->Array.forEach((resumedChainState: Persistence.initialChainState) => {
-    let chain = Config.getChain(config, ~chainId=resumedChainState.id)
-    let chainConfig = config.chainMap->ChainMap.get(chain)
-    chainStates->Utils.Dict.setByInt(
+    let chainId = Config.getChain(config, ~chainId=resumedChainState.id)
+    let chainConfig = config.chainMap->ChainMap.get(chainId)
+    chainStates->ChainId.Dict.set(
       resumedChainState.id,
       chainConfig->ChainState.makeFromDbState(
         ~resumedChainState,
@@ -304,6 +307,7 @@ let makeFromDbState = (
     ~onError,
     ~onExit?,
   )
+  state.crossChainState->CrossChainState.markCaughtUpOnResume
   initialState.cache->Utils.Dict.forEach(({effectName, count, scope}) => {
     state.effectState->EffectState.setUnregisteredCacheCount(~effectName, ~scope, ~count)
   })
@@ -358,15 +362,15 @@ let stop = (state: t) => {
   state.isStopped = true
 }
 
-let getChainState = (state: t, ~chain: chain): ChainState.t =>
+let getChainState = (state: t, ~chainId: ChainId.t): ChainState.t =>
   switch state.crossChainState
   ->CrossChainState.chainStates
-  ->Utils.Dict.dangerouslyGetByIntNonOption(chain->ChainMap.Chain.toChainId) {
+  ->ChainId.Dict.dangerouslyGetNonOption(chainId) {
   | Some(cs) => cs
   | None =>
-    // Should be unreachable, since we validate on Chain.t creation
+    // Should be unreachable: every configured chain gets a state at startup
     JsError.throwWithMessage(
-      "No chain with id " ++ chain->ChainMap.Chain.toString ++ " found in chain states",
+      "No chain with id " ++ chainId->ChainId.toString ++ " found in chain states",
     )
   }
 
@@ -390,18 +394,18 @@ let enterReorgThreshold = (state: t) => state.crossChainState->CrossChainState.e
 // ReorgDetected state as one step, so the epoch bump can never be left out. The
 // caller has already mutated the chain states (restored counters, reset pending
 // queries). isResolvingReorg derives from rollbackState.
-let beginReorg = (state: t, ~chain, ~blockNumber) => {
+let beginReorg = (state: t, ~chainId, ~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})
+  state.rollbackState = ReorgDetected({chainId, blockNumber})
 }
 
 let enterFindingReorgDepth = (state: t) => state.rollbackState = FindingReorgDepth
 
-let foundReorgDepth = (state: t, ~chain, ~rollbackTargetBlockNumber) =>
-  state.rollbackState = FoundReorgDepth({chain, rollbackTargetBlockNumber})
+let foundReorgDepth = (state: t, ~chainId, ~rollbackTargetBlockNumber) =>
+  state.rollbackState = FoundReorgDepth({chainId, rollbackTargetBlockNumber})
 
 // Finish a rollback. The caller has already rolled the chain states back in
 // place; this leaves the diff ready for the next batch to consume.
@@ -414,7 +418,15 @@ let clearRollback = (state: t) => state.rollbackState = NoRollback
 
 // Invalidate in-flight fetches/waiters without starting a rollback, eg on the
 // realtime transition where the parked waiter is bound to the pre-realtime source.
-let invalidateInflight = (state: t) => state.epoch = state.epoch + 1
+// Drops the pending queries with it, the way the reorg path does: a response
+// carrying the old epoch is discarded before handleQueryResult can retire its
+// query, and a partition that still holds one never asks for another range.
+let invalidateInflight = (state: t) => {
+  state.epoch = state.epoch + 1
+  state.crossChainState
+  ->CrossChainState.chainStates
+  ->Utils.Dict.forEach(ChainState.resetPendingQueries)
+}
 
 let applyBatchProgress = (state: t, ~batch: Batch.t) =>
   state.crossChainState->CrossChainState.applyBatchProgress(
@@ -461,6 +473,7 @@ let processedCheckpointId = (state: t) => state.processedCheckpointId
 let processedBatches = (state: t) => state.processedBatches
 let processedBatchesCount = (state: t) => state.processedBatchesCount
 let writeFiber = (state: t) => state.writeFiber
+let finalizeFiber = (state: t) => state.finalizeFiber
 let hasFailedWrite = (state: t) => state.hasFailedWrite
 let chainMetaDirty = (state: t) => state.chainMetaDirty
 let chainMetaThrottler = (state: t) => state.chainMetaThrottler
@@ -468,6 +481,19 @@ 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 markCaughtUpIfSettled = (state: t) =>
+  state.crossChainState->CrossChainState.markCaughtUpIfSettled
+
+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
@@ -794,6 +820,9 @@ let recordWriteFailure = (state: t, exn) => {
 let beginWriteFiber = (state: t, fiber) => state.writeFiber = Some(fiber)
 let endWriteFiber = (state: t) => state.writeFiber = None
 
+let beginFinalizeFiber = (state: t, fiber) => state.finalizeFiber = Some(fiber)
+let endFinalizeFiber = (state: t) => state.finalizeFiber = None
+
 // Resolve and clear everyone waiting on a commit so they can re-evaluate.
 let wakeCommitWaiters = (state: t) => {
   let waiters = state.commitWaiters

package/src/IndexerState.res.mjs

@@ -3,6 +3,7 @@
 import * as Env from "./Env.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Config from "./Config.res.mjs";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as Internal from "./Internal.res.mjs";
@@ -67,6 +68,7 @@ function make$1(config, persistence, chainStates, isInReorgThreshold, isRealtime
     processedBatches: [],
     processedBatchesCount: 0,
     writeFiber: undefined,
+    finalizeFiber: undefined,
     hasFailedWrite: false,
     commitWaiters: [],
     chainMeta: {},
@@ -106,24 +108,25 @@ function makeFromDbState(config, persistence, initialState, registrationsByChain
   let shouldUseTui = shouldUseTuiOpt !== undefined ? shouldUseTuiOpt : false;
   let exitAfterFirstEventBlock = exitAfterFirstEventBlockOpt !== undefined ? exitAfterFirstEventBlockOpt : false;
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : CrossChainState.calculateTargetBufferSize();
-  let isInReorgThreshold = initialState.cleanRun ? false : initialState.chains.some(chain => {
-      let progressBlockNumber = chain.progressBlockNumber;
-      let sourceBlockNumber = chain.sourceBlockNumber;
-      let maxReorgDepth = chain.maxReorgDepth;
+  let isInReorgThreshold = initialState.cleanRun ? false : initialState.chains.some(resumedChainState => {
+      let progressBlockNumber = resumedChainState.progressBlockNumber;
+      let sourceBlockNumber = resumedChainState.sourceBlockNumber;
+      let maxReorgDepth = resumedChainState.maxReorgDepth;
       if (maxReorgDepth > 0 && sourceBlockNumber > 0) {
         return progressBlockNumber > (sourceBlockNumber - maxReorgDepth | 0);
       } else {
         return false;
       }
     });
-  let isRealtime = !Env.updateSyncTimeOnRestart && initialState.chains.length !== 0 && initialState.chains.every(c => Stdlib_Option.isSome(c.timestampCaughtUpToHeadOrEndblock));
+  let isRealtime = initialState.chains.length !== 0 && initialState.chains.every(c => Stdlib_Option.isSome(c.timestampCaughtUpToHeadOrEndblock));
   let chainStates = {};
   initialState.chains.forEach(resumedChainState => {
-    let chain = Config.getChain(config, resumedChainState.id);
-    let chainConfig = ChainMap.get(config.chainMap, chain);
+    let chainId = Config.getChain(config, resumedChainState.id);
+    let chainConfig = ChainMap.get(config.chainMap, chainId);
     chainStates[resumedChainState.id] = ChainState.makeFromDbState(chainConfig, resumedChainState, initialState.reorgCheckpoints, isInReorgThreshold, isRealtime, config, registrationsByChainId, reducedPollingInterval);
   });
   let state = make$1(config, persistence, chainStates, isInReorgThreshold, isRealtime, targetBufferSize, initialState.checkpointId, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError, onExit);
+  CrossChainState.markCaughtUpOnResume(state.crossChainState);
   Utils.Dict.forEach(initialState.cache, param => {
     let count = param.count;
     EffectState.setUnregisteredCacheCount(state.effectState, param.effectName, param.scope, count);
@@ -170,12 +173,12 @@ function stop(state) {
   state.isStopped = true;
 }
 
-function getChainState(state, chain) {
-  let cs = CrossChainState.chainStates(state.crossChainState)[chain];
+function getChainState(state, chainId) {
+  let cs = CrossChainState.chainStates(state.crossChainState)[chainId];
   if (cs !== undefined) {
     return Primitive_option.valFromOption(cs);
   } else {
-    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainMap.Chain.toString(chain) + " found in chain states");
+    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainId.toString(chainId) + " found in chain states");
   }
 }
 
@@ -191,7 +194,7 @@ function enterReorgThreshold(state) {
   CrossChainState.enterReorgThreshold(state.crossChainState);
 }
 
-function beginReorg(state, chain, blockNumber) {
+function beginReorg(state, chainId, blockNumber) {
   let since = state.processingStalledOnFetchSince;
   if (since !== undefined) {
     state.processingStalledOnFetchSeconds = state.processingStalledOnFetchSeconds + Performance.secondsSince(since);
@@ -200,7 +203,7 @@ function beginReorg(state, chain, blockNumber) {
   state.epoch = state.epoch + 1 | 0;
   state.rollbackState = {
     TAG: "ReorgDetected",
-    chain: chain,
+    chainId: chainId,
     blockNumber: blockNumber
   };
 }
@@ -209,10 +212,10 @@ function enterFindingReorgDepth(state) {
   state.rollbackState = "FindingReorgDepth";
 }
 
-function foundReorgDepth(state, chain, rollbackTargetBlockNumber) {
+function foundReorgDepth(state, chainId, rollbackTargetBlockNumber) {
   state.rollbackState = {
     TAG: "FoundReorgDepth",
-    chain: chain,
+    chainId: chainId,
     rollbackTargetBlockNumber: rollbackTargetBlockNumber
   };
 }
@@ -230,6 +233,7 @@ function clearRollback(state) {
 
 function invalidateInflight(state) {
   state.epoch = state.epoch + 1 | 0;
+  Utils.Dict.forEach(CrossChainState.chainStates(state.crossChainState), ChainState.resetPendingQueries);
 }
 
 function applyBatchProgress(state, batch) {
@@ -308,6 +312,10 @@ function writeFiber(state) {
   return state.writeFiber;
 }
 
+function finalizeFiber(state) {
+  return state.finalizeFiber;
+}
+
 function hasFailedWrite(state) {
   return state.hasFailedWrite;
 }
@@ -336,6 +344,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 markCaughtUpIfSettled(state) {
+  CrossChainState.markCaughtUpIfSettled(state.crossChainState);
+}
+
+function markReady(state, readyAt) {
+  CrossChainState.markReady(state.crossChainState, readyAt);
+}
+
 function rollbackState(state) {
   return state.rollbackState;
 }
@@ -676,6 +700,14 @@ function endWriteFiber(state) {
   state.writeFiber = undefined;
 }
 
+function beginFinalizeFiber(state, fiber) {
+  state.finalizeFiber = fiber;
+}
+
+function endFinalizeFiber(state) {
+  state.finalizeFiber = undefined;
+}
+
 function wakeCommitWaiters(state) {
   let waiters = state.commitWaiters;
   state.commitWaiters = [];
@@ -755,6 +787,7 @@ export {
   processedBatches,
   processedBatchesCount,
   writeFiber,
+  finalizeFiber,
   hasFailedWrite,
   chainMetaDirty,
   chainMetaThrottler,
@@ -762,6 +795,9 @@ export {
   chainStates,
   isInReorgThreshold,
   isRealtime,
+  isFinalizingIndexes,
+  markCaughtUpIfSettled,
+  markReady,
   rollbackState,
   indexerStartTime,
   loadManager,
@@ -791,6 +827,8 @@ export {
   recordWriteFailure,
   beginWriteFiber,
   endWriteFiber,
+  beginFinalizeFiber,
+  endFinalizeFiber,
   wakeCommitWaiters,
   addCommitWaiter,
   stageChainMeta,

package/src/IndexerState.resi

@@ -1,13 +1,12 @@
 // The indexer state. `t` is opaque: other modules read it through the accessors
 // and change it only through the transitions and setters exposed here.
 
-type chain = ChainMap.Chain.t
 
 type rollbackState =
   | NoRollback
-  | ReorgDetected({chain: chain, blockNumber: int})
+  | ReorgDetected({chainId: ChainId.t, blockNumber: int})
   | FindingReorgDepth
-  | FoundReorgDepth({chain: chain, rollbackTargetBlockNumber: int})
+  | FoundReorgDepth({chainId: ChainId.t, rollbackTargetBlockNumber: int})
   | RollbackReady({eventsProcessedDiffByChain: dict<float>})
 
 module EntityTables: {
@@ -54,11 +53,11 @@ let isStale: (t, ~stateId: int) => bool
 let isResolvingReorg: t => bool
 let errorExit: (t, ErrorHandling.t) => unit
 let stop: t => unit
-let getChainState: (t, ~chain: chain) => ChainState.t
+let getChainState: (t, ~chainId: ChainId.t) => ChainState.t
 let enterReorgThreshold: t => unit
-let beginReorg: (t, ~chain: chain, ~blockNumber: int) => unit
+let beginReorg: (t, ~chainId: ChainId.t, ~blockNumber: int) => unit
 let enterFindingReorgDepth: t => unit
-let foundReorgDepth: (t, ~chain: chain, ~rollbackTargetBlockNumber: int) => unit
+let foundReorgDepth: (t, ~chainId: ChainId.t, ~rollbackTargetBlockNumber: int) => unit
 let completeRollback: (t, ~eventsProcessedDiffByChain: dict<float>) => unit
 let clearRollback: t => unit
 let invalidateInflight: t => unit
@@ -87,6 +86,7 @@ let processedCheckpointId: t => Internal.checkpointId
 let processedBatches: t => array<Batch.t>
 let processedBatchesCount: t => int
 let writeFiber: t => option<promise<unit>>
+let finalizeFiber: t => option<promise<unit>>
 let hasFailedWrite: t => bool
 let chainMetaDirty: t => bool
 let chainMetaThrottler: t => Throttler.t
@@ -94,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 markCaughtUpIfSettled: t => unit
+let markReady: (t, ~readyAt: Date.t) => unit
 let rollbackState: t => rollbackState
 let indexerStartTime: t => Date.t
 let loadManager: t => LoadManager.t
@@ -142,6 +145,8 @@ let beginRollbackDiff: (
 let recordWriteFailure: (t, exn) => unit
 let beginWriteFiber: (t, promise<unit>) => unit
 let endWriteFiber: t => unit
+let beginFinalizeFiber: (t, promise<unit>) => unit
+let endFinalizeFiber: t => unit
 let wakeCommitWaiters: t => unit
 let addCommitWaiter: (t, unit => unit) => unit
 let stageChainMeta: (t, dict<InternalTable.Chains.metaFields>) => unit

package/src/Internal.res

@@ -301,7 +301,7 @@ type genericEvent<'params, 'block, 'transaction> = {
   contractName: string,
   eventName: string,
   params: 'params,
-  chainId: int,
+  chainId: ChainId.t,
   srcAddress: Address.t,
   logIndex: int,
   transaction: 'transaction,
@@ -369,7 +369,7 @@ type entityHandlerContext<'entity> = {
 }
 
 type chainInfo = {
-  id: int,
+  id: ChainId.t,
   // True once every chain has caught up to head/endBlock and entered real-time
   // indexing mode. False while any chain is still backfilling.
   isRealtime: bool,
@@ -624,7 +624,7 @@ type dcs = array<indexingAddress>
 type eventItem = private {
   kind: [#0],
   onEventRegistration: onEventRegistration,
-  chain: ChainMap.Chain.t,
+  chainId: ChainId.t,
   blockNumber: int,
   logIndex: int,
   // Within-block transaction index — the key into the per-chain transaction
@@ -637,7 +637,7 @@ type eventItem = private {
 // `InternalTable`) so the ecosystem's `toRawEvent` can reference it without
 // pulling in `InternalTable`'s dependency on `Config`.
 type rawEvent = {
-  chain_id: int,
+  chain_id: ChainId.t,
   event_id: bigint,
   event_name: string,
   contract_name: string,
@@ -665,7 +665,7 @@ type onBlockRegistration = {
   // we want to use the order they are defined for sorting
   index: int,
   name: string,
-  chainId: int,
+  chainId: ChainId.t,
   startBlock: option<int>,
   endBlock: option<int>,
   interval: int,
@@ -677,7 +677,7 @@ type item =
   | @as(0)
   Event({
       onEventRegistration: onEventRegistration,
-      chain: ChainMap.Chain.t,
+      chainId: ChainId.t,
       blockNumber: int,
       logIndex: int,
       transactionIndex: int,
@@ -694,7 +694,7 @@ external getItemLogIndex: item => int = "logIndex"
 
 let getItemChainId = item =>
   switch item {
-  | Event({chain}) => chain->ChainMap.Chain.toChainId
+  | Event({chainId})
   | Block({onBlockRegistration: {chainId}}) => chainId
   }
 
@@ -796,7 +796,7 @@ type effect = {
 @unboxed
 type chainScope =
   | @as("crossChain") CrossChain
-  | Chain(int)
+  | Chain(ChainId.t)
 
 let cacheTablePrefix = "envio_effect_"
 
@@ -804,27 +804,29 @@ let cacheTablePrefix = "envio_effect_"
 // canonical Postgres cache-table name and .envio/cache file path. Everything
 // that needs a cache address goes through here instead of slicing prefixes.
 //   CrossChain  ->  envio_effect_<name>        <name>.tsv
-//   Chain(1)    ->  envio_1_effect_<name>      1/<name>.tsv
-//   Chain(137)  ->  envio_137_effect_<name>    137/<name>.tsv
+//   Chain(1->ChainId.fromInt)    ->  envio_1_effect_<name>      1/<name>.tsv
+//   Chain(137->ChainId.fromInt)  ->  envio_137_effect_<name>    137/<name>.tsv
 module EffectCache = {
   let toTableName = (~effectName, ~scope) =>
     switch scope {
     | CrossChain => cacheTablePrefix ++ effectName
-    | Chain(chainId) => `envio_${chainId->Int.toString}_effect_${effectName}`
+    | Chain(chainId) => `envio_${chainId->ChainId.toString}_effect_${effectName}`
     }
 
   // "crossChain" or the decimal chain id. Used as the `scope` Prometheus label.
   let scopeToString = scope =>
     switch scope {
     | CrossChain => "crossChain"
-    | Chain(chainId) => chainId->Int.toString
+    | Chain(chainId) => chainId->ChainId.toString
     }
 
   // Only accepts a canonical decimal chain id ("7", not "007" or "1foo") —
-  // Int.fromString alone follows parseInt semantics and accepts both.
+  // the schema's parser follows parseFloat semantics and accepts both.
   let parseChainId = str =>
-    switch Int.fromString(str) {
-    | Some(chainId) if chainId >= 0 && chainId->Int.toString === str => Some(chainId)
+    switch try Some(str->ChainId.normalizeOrThrow) catch {
+    | _ => None
+    } {
+    | Some(chainId) if chainId->ChainId.toString === str => Some(chainId)
     | _ => None
     }
 
@@ -864,7 +866,7 @@ module EffectCache = {
   let toCachePath = (~effectName, ~scope) =>
     switch scope {
     | CrossChain => effectName ++ ".tsv"
-    | Chain(chainId) => `${chainId->Int.toString}/${effectName}.tsv`
+    | Chain(chainId) => `${chainId->ChainId.toString}/${effectName}.tsv`
     }
 }
 
@@ -893,7 +895,7 @@ type reorgCheckpoint = {
   @as("id")
   checkpointId: bigint,
   @as("chain_id")
-  chainId: int,
+  chainId: ChainId.t,
   @as("block_number")
   blockNumber: int,
   @as("block_hash")

package/src/Internal.res.mjs

@@ -3,7 +3,7 @@
 import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Address from "./Address.res.mjs";
-import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 
@@ -149,7 +149,7 @@ function dependsOnAddresses(isWildcard, filterByAddresses) {
 
 function getItemChainId(item) {
   if (item.kind === 0) {
-    return item.chain;
+    return item.chainId;
   } else {
     return item.onBlockRegistration.chainId;
   }
@@ -172,7 +172,7 @@ function toTableName(effectName, scope) {
   if (scope === "crossChain") {
     return cacheTablePrefix + effectName;
   } else {
-    return `envio_` + scope.toString() + `_effect_` + effectName;
+    return `envio_` + ChainId.toString(scope) + `_effect_` + effectName;
   }
 }
 
@@ -180,14 +180,23 @@ function scopeToString(scope) {
   if (scope === "crossChain") {
     return "crossChain";
   } else {
-    return scope.toString();
+    return ChainId.toString(scope);
   }
 }
 
 function parseChainId(str) {
-  let chainId = Stdlib_Int.fromString(str, undefined);
-  if (chainId !== undefined && chainId >= 0 && chainId.toString() === str) {
-    return chainId;
+  let chainId;
+  try {
+    chainId = Primitive_option.some(ChainId.normalizeOrThrow(str));
+  } catch (exn) {
+    chainId = undefined;
+  }
+  if (chainId === undefined) {
+    return;
+  }
+  let chainId$1 = Primitive_option.valFromOption(chainId);
+  if (ChainId.toString(chainId$1) === str) {
+    return Primitive_option.some(chainId$1);
   }
 }
 
@@ -236,7 +245,7 @@ function fromTableName(tableName) {
   if (chainId !== undefined) {
     return [
       effectName$1,
-      chainId
+      Primitive_option.valFromOption(chainId)
     ];
   }
 }
@@ -245,7 +254,7 @@ function toCachePath(effectName, scope) {
   if (scope === "crossChain") {
     return effectName + ".tsv";
   } else {
-    return scope.toString() + `/` + effectName + `.tsv`;
+    return ChainId.toString(scope) + `/` + effectName + `.tsv`;
   }
 }
 

package/src/LoadLayer.res

@@ -226,7 +226,7 @@ let loadEffect = (
   // the storage-load metric stays stable.
   let key = switch scope {
   | CrossChain => `${effectName}.effect`
-  | Chain(chainId) => `${effectName}.effect.${chainId->Int.toString}`
+  | Chain(chainId) => `${effectName}.effect.${chainId->ChainId.toString}`
   }
 
   let load = async (args, ~onError) => {
@@ -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

@@ -2,6 +2,7 @@
 
 import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as Ecosystem from "./Ecosystem.res.mjs";
 import * as EffectState from "./EffectState.res.mjs";
@@ -113,7 +114,7 @@ function loadEffect(loadManager, persistence, effect, effectArgs, scope, indexer
   let table = inMemTable.table;
   let tableName = table.tableName;
   let key;
-  key = scope === "crossChain" ? effectName + `.effect` : effectName + `.effect.` + scope.toString();
+  key = scope === "crossChain" ? effectName + `.effect` : effectName + `.effect.` + ChainId.toString(scope);
   let load = async (args, onError) => {
     let idsToLoad = args.map(arg => arg.cacheKey);
     let idsFromCache = new Set();
@@ -190,6 +191,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 {