envio 3.15.0 → 3.16.0-subgraph

package/src/Internal.res

@@ -724,6 +724,12 @@ type onBlockArgs = {
   context: handlerContext,
 }
 
+type onBlockContractRegisterArgs = {
+  slot?: int,
+  block?: eventBlock,
+  context: contractRegisterContext,
+}
+
 type onBlockRegistration = {
   // When there are multiple onBlock handlers per chain,
   // we want to use the order they are defined for sorting
@@ -738,6 +744,14 @@ type onBlockRegistration = {
   // `None` when the handler reads only the block's key, which needs nothing
   // from a source: its items are generated locally, block by block.
   blockFieldMask: option<float>,
+  // Subgraph mode only: a `once` block handler, whose trigger graph-node runs
+  // ahead of everything else in its block (`EthereumBlockTriggerType::Start`).
+  runsFirst?: bool,
+  // Subgraph mode only: the register pass of a block handler that can create a
+  // data source. It runs for each of the handler's blocks at fetch time, and no
+  // block item is processed until every pass up to its block has run and what
+  // they registered is fetched, as an event's contractRegister.
+  contractRegister?: onBlockContractRegisterArgs => promise<unit>,
 }
 
 @tag("kind")
@@ -785,6 +799,53 @@ external getItemOrderPath: item => Nullable.t<array<int>> = "orderPath"
 // block ahead of that block's handlers without a `switch`.
 @get
 external getItemKind: item => int = "kind"
+// Set only in subgraph mode, on an event of an address registered in the very
+// block it was logged in: graph-node runs a new data source's creation-block
+// events after everything else in that block. The value is the round, as
+// graph-node counts them: 1 for a data source a block's own triggers created,
+// 2 for one that round-1 handlers created, and so on.
+@get
+external getItemCreationRound: item => option<int> = "runsAfterBlock"
+@set
+external markItemCreationRound: (item, int) => unit = "runsAfterBlock"
+
+let itemRunsFirst = (item: item) =>
+  switch item {
+  | Block({onBlockRegistration: {runsFirst: true}}) => true
+  | _ => false
+  }
+
+// Subgraph mode only. A call trigger travels through fetch and batching as an
+// event item (see `subgraph/calls-source.ts`), and graph-node orders it by its
+// transaction among the logs, so its item carries a rank: 1 for a call
+// handler's, 2 for the `filter: call` block handler's. Absent on every log.
+@get
+external getItemCallRank: item => option<int> = "callRank"
+@set
+external setItemCallRank: (item, int) => unit = "callRank"
+@get
+external getItemTransactionIndex: item => int = "transactionIndex"
+
+// Flips on when the first call item is built, so a run without call triggers
+// compares items exactly as before.
+let callOrderingActive = ref(false)
+
+// The call trigger an event of this name is, if it is one: the subgraph
+// translator names them `__envio_call_<selector>_<function>`, and the block
+// handler's `__envio_call_any`. No log carries either name.
+let callRankOfEventName = (name: string): option<int> =>
+  if name->String.startsWith("__envio_call_any") {
+    Some(2)
+  } else if name->String.startsWith("__envio_call_") {
+    Some(1)
+  } else {
+    None
+  }
+
+let markItemCall = (item, ~rank) => {
+  item->setItemCallRank(rank)
+  callOrderingActive := true
+}
 
 let getItemChainId = item =>
   switch item {
@@ -950,55 +1011,6 @@ module EffectCache = {
     | CrossChain => cacheTablePrefix ++ effectName
     | Chain(chainId) => `envio_${chainId->ChainId.toString}_effect_${effectName}`
     }
-
-  // Only accepts a canonical decimal chain id ("7", not "007" or "1foo") —
-  // the schema's parser follows parseFloat semantics and accepts both.
-  let parseChainId = str =>
-    switch try Some(str->ChainId.normalizeOrThrow) catch {
-    | _ => None
-    } {
-    | Some(chainId) if chainId->ChainId.toString === str => Some(chainId)
-    | _ => None
-    }
-
-  let chainScopedRe = /^envio_([0-9]+)_effect_(.+)$/
-  let crossChainRe = /^envio_effect_(.+)$/
-
-  // Inverse of toTableName. Returns None for any table name that isn't a cache
-  // table. Chain-scoped is tried first: the `_effect_` separator keeps effect
-  // names that themselves start with digits unambiguous.
-  let fromTableName = (tableName): option<(string, chainScope)> =>
-    switch RegExp.exec(chainScopedRe, tableName) {
-    | Some(result) =>
-      switch (
-        RegExp.Result.matches(result)->Array.get(0),
-        RegExp.Result.matches(result)->Array.get(1),
-      ) {
-      | (Some(Some(chainIdStr)), Some(Some(effectName))) =>
-        switch parseChainId(chainIdStr) {
-        | Some(chainId) => Some((effectName, Chain(chainId)))
-        | None => None
-        }
-      | _ => None
-      }
-    | None =>
-      switch RegExp.exec(crossChainRe, tableName) {
-      | Some(result) =>
-        switch RegExp.Result.matches(result)->Array.get(0) {
-        | Some(Some(effectName)) => Some((effectName, CrossChain))
-        | _ => None
-        }
-      | None => None
-      }
-    }
-
-  // Relative posix path within .envio/cache. Chain-scoped caches live one
-  // directory level deep, named by chain id.
-  let toCachePath = (~effectName, ~scope) =>
-    switch scope {
-    | CrossChain => effectName ++ ".tsv"
-    | Chain(chainId) => `${chainId->ChainId.toString}/${effectName}.tsv`
-    }
 }
 
 let cacheOutputSchema = S.json(~validate=false)->(Utils.magic: S.t<JSON.t> => S.t<effectOutput>)

package/src/Internal.res.mjs

@@ -188,6 +188,37 @@ function eventItemFieldsJson(eventItem, address) {
   return `{` + contractAndEventJson(eventItem.onEventRegistration.eventConfig) + `,"block":` + eventItem.blockNumber.toString() + `,"logIndex":` + eventItem.logIndex.toString() + `,"address":` + JSON.stringify(address) + `}`;
 }
 
+function itemRunsFirst(item) {
+  if (item.kind === 0) {
+    return false;
+  }
+  let match = item.onBlockRegistration.runsFirst;
+  if (match !== undefined) {
+    return match;
+  } else {
+    return false;
+  }
+}
+
+let callOrderingActive = {
+  contents: false
+};
+
+function callRankOfEventName(name) {
+  if (name.startsWith("__envio_call_any")) {
+    return 2;
+  } else if (name.startsWith("__envio_call_")) {
+    return 1;
+  } else {
+    return;
+  }
+}
+
+function markItemCall(item, rank) {
+  item.callRank = rank;
+  callOrderingActive.contents = true;
+}
+
 function getItemChainId(item) {
   if (item.kind === 0) {
     return item.chainId;
@@ -240,87 +271,8 @@ function toTableName(effectName, scope) {
   }
 }
 
-function parseChainId(str) {
-  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);
-  }
-}
-
-let chainScopedRe = /^envio_([0-9]+)_effect_(.+)$/;
-
-let crossChainRe = /^envio_effect_(.+)$/;
-
-function fromTableName(tableName) {
-  let result = chainScopedRe.exec(tableName);
-  if (result == null) {
-    let result$1 = crossChainRe.exec(tableName);
-    if (result$1 == null) {
-      return;
-    }
-    let match = result$1.slice(1)[0];
-    if (match === undefined) {
-      return;
-    }
-    let effectName = Primitive_option.valFromOption(match);
-    if (effectName !== undefined) {
-      return [
-        effectName,
-        "crossChain"
-      ];
-    } else {
-      return;
-    }
-  }
-  let match$1 = result.slice(1)[0];
-  let match$2 = result.slice(1)[1];
-  if (match$1 === undefined) {
-    return;
-  }
-  let chainIdStr = Primitive_option.valFromOption(match$1);
-  if (chainIdStr === undefined) {
-    return;
-  }
-  if (match$2 === undefined) {
-    return;
-  }
-  let effectName$1 = Primitive_option.valFromOption(match$2);
-  if (effectName$1 === undefined) {
-    return;
-  }
-  let chainId = parseChainId(chainIdStr);
-  if (chainId !== undefined) {
-    return [
-      effectName$1,
-      Primitive_option.valFromOption(chainId)
-    ];
-  }
-}
-
-function toCachePath(effectName, scope) {
-  if (scope === "crossChain") {
-    return effectName + ".tsv";
-  } else {
-    return ChainId.toString(scope) + `/` + effectName + `.tsv`;
-  }
-}
-
 let EffectCache = {
-  toTableName: toTableName,
-  parseChainId: parseChainId,
-  chainScopedRe: chainScopedRe,
-  crossChainRe: crossChainRe,
-  fromTableName: fromTableName,
-  toCachePath: toCachePath
+  toTableName: toTableName
 };
 
 let cacheOutputSchema = S$RescriptSchema.json(false);
@@ -356,6 +308,10 @@ export {
   dependsOnAddresses,
   svmAccountSlotName,
   eventItemFieldsJson,
+  itemRunsFirst,
+  callOrderingActive,
+  callRankOfEventName,
+  markItemCall,
   getItemChainId,
   fuelSupplyParamsSchema,
   fuelTransferParamsSchema,

package/src/LoadLayer.res

@@ -16,7 +16,12 @@ let loadById = (
   ~entityId,
 ) => {
   let inMemTable = indexerState->InMemoryStore.getInMemTable(~entityConfig, ~scope)
-  switch inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(entityId) {
+  // The ids here are typed as strings but hold whatever scalar the id is.
+  let entityIdToKey =
+    inMemTable.entityIdToKey->(Utils.magic: (EntityId.t => string) => string => string)
+  switch inMemTable.latestEntityChangeById->Utils.Dict.dangerouslyGetNonOption(
+    entityIdToKey(entityId),
+  ) {
   // A row already in memory is final, so even a grouped call skips the load
   // manager: grouping it would only resolve it a tick later to the same value.
   | Some(change) => Promise.resolve(change->InMemoryTable.Entity.mapChangeToEntity)
@@ -53,14 +58,14 @@ let loadById = (
       //Set the entity in the in memory store
       for idx in 0 to dbEntities->Array.length - 1 {
         let entity = dbEntities->Array.getUnsafe(idx)
-        entitiesMap->Dict.set(entity.id, entity)
+        entitiesMap->Dict.set(entityIdToKey(entity.id), entity)
       }
       let committedCheckpointId = indexerState->IndexerState.committedCheckpointIdFor(~scope)
       idsToLoad->Array.forEach(entityId => {
         inMemTable->InMemoryTable.Entity.initValue(
           ~committedCheckpointId,
-          ~key=entityId,
-          ~entity=entitiesMap->Utils.Dict.dangerouslyGetNonOption(entityId),
+          ~entityId=entityId->EntityId.unsafeOfString,
+          ~entity=entitiesMap->Utils.Dict.dangerouslyGetNonOption(entityIdToKey(entityId)),
         )
       })
 
@@ -77,7 +82,7 @@ let loadById = (
       ~key,
       ~load,
       ~shouldGroup,
-      ~hasher=LoadManager.noopHasher,
+      ~hasher=entityIdToKey,
       ~getUnsafeInMemory=inMemTable->InMemoryTable.Entity.getUnsafe,
       ~hasInMemory=hash => inMemTable.latestEntityChangeById->Dict.has(hash),
       ~input=entityId,
@@ -140,7 +145,7 @@ let rec executeWithRateLimit = (
     }
 
   | Some(state) =>
-    let now = Date.now()
+    let now = state.clock.now()
 
     // Check if we need to reset the window
     if now >= state.windowStartTime +. state.durationMs->Int.toFloat {
@@ -188,7 +193,8 @@ let rec executeWithRateLimit = (
       | None =>
         millisUntilReset :=
           (state.windowStartTime +. state.durationMs->Int.toFloat -. now)->Float.toInt
-        let p = Utils.delay(millisUntilReset.contents)
+        let p =
+          state.clock->Clock.delay(~label="effect rate limit window", millisUntilReset.contents)
         state.nextWindowPromise = Some(p)
         p
       }
@@ -335,6 +341,45 @@ let loadEffect = (
   )
 }
 
+// Keying an _in walks every value, so it's computed once and handed on rather
+// than recomputed by each reader. Before answering "not in memory", the rows
+// already loaded for other filters are checked: they may cover this one.
+let indexFilter = (inMemTable, ~filter, ~table) => {
+  let filterKey = filter->EntityFilter.toString(~table)
+  if !(inMemTable->InMemoryTable.Entity.hasIndex)(filterKey) {
+    inMemTable->InMemoryTable.Entity.tryIndexFromLoadedValues(~filter, ~table)
+  }
+  filterKey
+}
+
+// A recorded absence is an answer too: `Some(None)` means the entity is known
+// not to exist, so no load is needed to say so.
+let getByIdInMemory = (
+  ~entityConfig: Internal.entityConfig,
+  ~scope,
+  ~indexerState,
+  ~entityId: string,
+) => {
+  let inMemTable = indexerState->InMemoryStore.getInMemTable(~entityConfig, ~scope)
+  let entityKey = inMemTable.entityIdToKey(entityId->EntityId.unsafeOfString)
+  inMemTable.latestEntityChangeById->Dict.has(entityKey)
+    ? Some((inMemTable->InMemoryTable.Entity.getUnsafe)(entityKey))
+    : None
+}
+
+let getByFilterInMemory = (
+  ~entityConfig: Internal.entityConfig,
+  ~scope,
+  ~indexerState,
+  ~filter: EntityFilter.t,
+) => {
+  let inMemTable = indexerState->InMemoryStore.getInMemTable(~entityConfig, ~scope)
+  let filterKey = inMemTable->indexFilter(~filter, ~table=entityConfig.table)
+  (inMemTable->InMemoryTable.Entity.hasIndex)(filterKey)
+    ? Some((inMemTable->InMemoryTable.Entity.getUnsafeOnIndex)(filterKey))
+    : None
+}
+
 let loadByParsedFilter = (
   ~loadManager,
   ~persistence: Persistence.t,
@@ -387,7 +432,7 @@ let loadByParsedFilter = (
         entities->Array.forEach(entity => {
           inMemTable->InMemoryTable.Entity.initValue(
             ~committedCheckpointId,
-            ~key=entity.id,
+            ~entityId=entity.id->EntityId.unsafeOfString,
             ~entity=Some(entity),
           )
         })
@@ -425,13 +470,7 @@ let loadByParsedFilter = (
     )
   }
 
-  // Keying an _in walks every value, so it's computed once here and handed to
-  // the load manager rather than recomputed by the hasher.
-  let filterKey = filter->EntityFilter.toString(~table=entityConfig.table)
-
-  if !(inMemTable->InMemoryTable.Entity.hasIndex)(filterKey) {
-    inMemTable->InMemoryTable.Entity.tryIndexFromLoadedValues(~filter, ~table=entityConfig.table)
-  }
+  let filterKey = inMemTable->indexFilter(~filter, ~table=entityConfig.table)
 
   loadManager->LoadManager.call(
     ~key,

package/src/LoadLayer.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Clock from "./Clock.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Logger from "./Logger.res.mjs";
 import * as ChainId from "./ChainId.res.mjs";
@@ -14,6 +15,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as ErrorHandling from "./ErrorHandling.res.mjs";
 import * as InMemoryStore from "./InMemoryStore.res.mjs";
 import * as InMemoryTable from "./InMemoryTable.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";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
@@ -27,7 +29,8 @@ function scopeKeySuffix(scope) {
 
 function loadById(loadManager, persistence, entityConfig, scope, indexerState, shouldGroup, entityId) {
   let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig, scope);
-  let change = inMemTable.latestEntityChangeById[entityId];
+  let entityIdToKey = inMemTable.entityIdToKey;
+  let change = inMemTable.latestEntityChangeById[entityIdToKey(entityId)];
   if (change !== undefined) {
     return Promise.resolve(InMemoryTable.Entity.mapChangeToEntity(change));
   }
@@ -50,13 +53,13 @@ function loadById(loadManager, persistence, entityConfig, scope, indexerState, s
     let entitiesMap = {};
     for (let idx = 0, idx_finish = dbEntities.length; idx < idx_finish; ++idx) {
       let entity = dbEntities[idx];
-      entitiesMap[entity.id] = entity;
+      entitiesMap[entityIdToKey(entity.id)] = entity;
     }
     let committedCheckpointId = IndexerState.committedCheckpointIdFor(indexerState, scope);
-    idsToLoad.forEach(entityId => InMemoryTable.Entity.initValue(inMemTable, committedCheckpointId, entityId, entitiesMap[entityId]));
+    idsToLoad.forEach(entityId => InMemoryTable.Entity.initValue(inMemTable, committedCheckpointId, entityId, entitiesMap[entityIdToKey(entityId)]));
     return IndexerState.endStorageLoad(indexerState, timerRef, storageName, key, idsToLoad.length, dbEntities.length);
   };
-  return LoadManager.call(loadManager, entityId, key, load, LoadManager.noopHasher, shouldGroup, hash => hash in inMemTable.latestEntityChangeById, InMemoryTable.Entity.getUnsafe(inMemTable));
+  return LoadManager.call(loadManager, entityId, key, load, entityIdToKey, shouldGroup, hash => hash in inMemTable.latestEntityChangeById, InMemoryTable.Entity.getUnsafe(inMemTable));
 }
 
 function callEffect(effect, arg, inMemTable, timerRef, onError) {
@@ -69,7 +72,7 @@ function executeWithRateLimit(effect, effectArgs, inMemTable, onError, isFromQue
   let promises = [];
   let state = inMemTable.rateLimitState;
   if (state !== undefined) {
-    let now = Date.now();
+    let now = state.clock.now();
     if (now >= state.windowStartTime + state.durationMs) {
       state.availableCalls = state.callsPerDuration;
       state.windowStartTime = now;
@@ -98,7 +101,7 @@ function executeWithRateLimit(effect, effectArgs, inMemTable, onError, isFromQue
         nextWindowPromise = p;
       } else {
         millisUntilReset.contents = state.windowStartTime + state.durationMs - now | 0;
-        let p$1 = Utils.delay(millisUntilReset.contents);
+        let p$1 = Clock.delay(state.clock, "effect rate limit window", millisUntilReset.contents);
         state.nextWindowPromise = p$1;
         nextWindowPromise = p$1;
       }
@@ -184,47 +187,71 @@ function loadEffect(loadManager, persistence, effect, effectArgs, scope, indexer
   return LoadManager.call(loadManager, effectArgs, key, load, args => args.cacheKey, shouldGroup, hash => InMemoryStore.hasEffectOutput(inMemTable, hash), hash => InMemoryStore.getEffectOutputUnsafe(inMemTable, hash));
 }
 
+function indexFilter(inMemTable, filter, table) {
+  let filterKey = EntityFilter.toString(filter, table);
+  if (!InMemoryTable.Entity.hasIndex(inMemTable)(filterKey)) {
+    InMemoryTable.Entity.tryIndexFromLoadedValues(inMemTable, filter, table);
+  }
+  return filterKey;
+}
+
+function getByIdInMemory(entityConfig, scope, indexerState, entityId) {
+  let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig, scope);
+  let entityKey = inMemTable.entityIdToKey(entityId);
+  if (entityKey in inMemTable.latestEntityChangeById) {
+    return Primitive_option.some(InMemoryTable.Entity.getUnsafe(inMemTable)(entityKey));
+  }
+}
+
+function getByFilterInMemory(entityConfig, scope, indexerState, filter) {
+  let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig, scope);
+  let filterKey = indexFilter(inMemTable, filter, entityConfig.table);
+  if (InMemoryTable.Entity.hasIndex(inMemTable)(filterKey)) {
+    return InMemoryTable.Entity.getUnsafeOnIndex(inMemTable)(filterKey);
+  }
+}
+
+function loadByParsedFilter(loadManager, persistence, entityConfig, scope, indexerState, shouldGroup, filter) {
+  let key = EntityFilter.toOperationKey(filter, entityConfig.name) + scopeKeySuffix(scope);
+  let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig, scope);
+  let load = async (filters, param) => {
+    let storage = Persistence.getInitializedStorageOrThrow(persistence);
+    let storageName = storage.entityStoreName(entityConfig);
+    let timerRef = IndexerState.startStorageLoad(indexerState, storageName, key);
+    let size = {
+      contents: 0
+    };
+    filters.forEach(filter => InMemoryTable.Entity.addEmptyIndex(inMemTable, filter, entityConfig.table));
+    await storage.ensureQueryIndexes(entityConfig, scope, filters);
+    let queries = EntityFilter.merge(filters);
+    await Promise.all(queries.map(async filter => {
+      try {
+        let entities = await storage.loadOrThrow(EntityFilter.scoped(filter, entityConfig.table, scope), entityConfig.table);
+        let committedCheckpointId = IndexerState.committedCheckpointIdFor(indexerState, scope);
+        entities.forEach(entity => InMemoryTable.Entity.initValue(inMemTable, committedCheckpointId, entity.id, entity));
+        InMemoryTable.Entity.recordLoadedValues(inMemTable, filter, entityConfig.table);
+        size.contents = size.contents + entities.length | 0;
+        return;
+      } catch (raw_exn) {
+        let exn = Primitive_exceptions.internalToException(raw_exn);
+        if (exn.RE_EXN_ID === Persistence.StorageError) {
+          return ErrorHandling.mkLogAndRaise(Logger.withFields(IndexerState.loggerForScope(indexerState, scope), {
+            operation: key,
+            params: EntityFilter.getParams(filter)
+          }), exn.message, exn.reason);
+        }
+        throw exn;
+      }
+    }));
+    return IndexerState.endStorageLoad(indexerState, timerRef, storageName, key, Stdlib_Array.reduce(queries, 0, (acc, query) => acc + EntityFilter.valuesCount(query) | 0), size.contents);
+  };
+  let filterKey = indexFilter(inMemTable, filter, entityConfig.table);
+  return LoadManager.call(loadManager, filter, key, load, param => filterKey, shouldGroup, InMemoryTable.Entity.hasIndex(inMemTable), InMemoryTable.Entity.getUnsafeOnIndex(inMemTable));
+}
+
 function loadByFilter(loadManager, persistence, entityConfig, scope, indexerState, shouldGroup, filter) {
   try {
-    let filter$1 = EntityFilter.parseOrThrow(filter, entityConfig.name, entityConfig.table);
-    let key = EntityFilter.toOperationKey(filter$1, entityConfig.name) + scopeKeySuffix(scope);
-    let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig, scope);
-    let load = async (filters, param) => {
-      let storage = Persistence.getInitializedStorageOrThrow(persistence);
-      let storageName = storage.entityStoreName(entityConfig);
-      let timerRef = IndexerState.startStorageLoad(indexerState, storageName, key);
-      let size = {
-        contents: 0
-      };
-      filters.forEach(filter => InMemoryTable.Entity.addEmptyIndex(inMemTable, filter, entityConfig.table));
-      await storage.ensureQueryIndexes(entityConfig, scope, filters);
-      let queries = EntityFilter.merge(filters);
-      await Promise.all(queries.map(async filter => {
-        try {
-          let entities = await storage.loadOrThrow(EntityFilter.scoped(filter, entityConfig.table, scope), entityConfig.table);
-          let committedCheckpointId = IndexerState.committedCheckpointIdFor(indexerState, scope);
-          entities.forEach(entity => InMemoryTable.Entity.initValue(inMemTable, committedCheckpointId, entity.id, entity));
-          InMemoryTable.Entity.recordLoadedValues(inMemTable, filter, entityConfig.table);
-          size.contents = size.contents + entities.length | 0;
-          return;
-        } catch (raw_exn) {
-          let exn = Primitive_exceptions.internalToException(raw_exn);
-          if (exn.RE_EXN_ID === Persistence.StorageError) {
-            return ErrorHandling.mkLogAndRaise(Logger.withFields(IndexerState.loggerForScope(indexerState, scope), {
-              operation: key,
-              params: EntityFilter.getParams(filter)
-            }), exn.message, exn.reason);
-          }
-          throw exn;
-        }
-      }));
-      return IndexerState.endStorageLoad(indexerState, timerRef, storageName, key, Stdlib_Array.reduce(queries, 0, (acc, query) => acc + EntityFilter.valuesCount(query) | 0), size.contents);
-    };
-    let filterKey = EntityFilter.toString(filter$1, entityConfig.table);
-    if (!InMemoryTable.Entity.hasIndex(inMemTable)(filterKey)) {
-      InMemoryTable.Entity.tryIndexFromLoadedValues(inMemTable, filter$1, entityConfig.table);
-    }
-    return LoadManager.call(loadManager, filter$1, key, load, param => filterKey, shouldGroup, InMemoryTable.Entity.hasIndex(inMemTable), InMemoryTable.Entity.getUnsafeOnIndex(inMemTable));
+    return loadByParsedFilter(loadManager, persistence, entityConfig, scope, indexerState, shouldGroup, EntityFilter.parseOrThrow(filter, entityConfig.name, entityConfig.table));
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
     return Promise.reject(Utils.prettifyExn(exn));
@@ -234,6 +261,9 @@ function loadByFilter(loadManager, persistence, entityConfig, scope, indexerStat
 export {
   loadById,
   loadByFilter,
+  loadByParsedFilter,
+  getByIdInMemory,
+  getByFilterInMemory,
   loadEffect,
 }
 /* Utils Not a pure module */

package/src/LoadLayer.resi

@@ -18,6 +18,32 @@ let loadByFilter: (
   ~filter: dict<dict<unknown>>,
 ) => promise<array<Internal.entity>>
 
+let loadByParsedFilter: (
+  ~loadManager: LoadManager.t,
+  ~persistence: Persistence.t,
+  ~entityConfig: Internal.entityConfig,
+  ~scope: Internal.chainScope,
+  ~indexerState: IndexerState.t,
+  ~shouldGroup: bool,
+  ~filter: EntityFilter.t,
+) => promise<array<Internal.entity>>
+
+// What a get or getWhere answers without a load, or None when it would need
+// one. The sync context reads through these and suspends on None.
+let getByIdInMemory: (
+  ~entityConfig: Internal.entityConfig,
+  ~scope: Internal.chainScope,
+  ~indexerState: IndexerState.t,
+  ~entityId: string,
+) => option<option<Internal.entity>>
+
+let getByFilterInMemory: (
+  ~entityConfig: Internal.entityConfig,
+  ~scope: Internal.chainScope,
+  ~indexerState: IndexerState.t,
+  ~filter: EntityFilter.t,
+) => option<array<Internal.entity>>
+
 let loadEffect: (
   ~loadManager: LoadManager.t,
   ~persistence: Persistence.t,

package/src/Main.res

@@ -303,12 +303,25 @@ let getGlobalIndexer = (): 'indexer => {
 
   let onBlockFn = (rawOptions: 'a, handler: 'b) => {
     HandlerRegister.throwIfFinishedRegistration(~methodName="onBlock")
-    let raw = rawOptions->(Utils.magic: 'a => {"name": string, "where": unknown, "fields": unknown})
+    let raw =
+      rawOptions->(
+        Utils.magic: 'a => {
+          "name": string,
+          "where": unknown,
+          "fields": unknown,
+          "runsFirst": option<bool>,
+          "contractRegister": option<Internal.onBlockContractRegisterArgs => promise<unit>>,
+        }
+      )
     HandlerRegister.registerOnBlock(
       ~name=raw["name"],
       ~where=raw["where"],
       ~fields=raw["fields"],
       ~handler=handler->(Utils.magic: 'b => Internal.onBlockArgs => promise<unit>),
+      // Not part of the public API: the subgraph runtime's `once` handlers, and
+      // the register passes of block handlers that create data sources.
+      ~runsFirst=Env.subgraphMode.contents && raw["runsFirst"] === Some(true),
+      ~contractRegister=?Env.subgraphMode.contents ? raw["contractRegister"] : None,
       ~getChainsObject=config => {
         let (chains, _) = buildChainsObject(~config)
         chains->(Utils.magic: {..} => dict<unknown>)

package/src/Main.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Env from "./Env.res.mjs";
 import * as Tui from "./tui/Tui.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Config from "./Config.res.mjs";
@@ -255,7 +256,7 @@ function getGlobalIndexer() {
   };
   let onBlockFn = (rawOptions, handler) => {
     HandlerRegister.throwIfFinishedRegistration("onBlock");
-    HandlerRegister.registerOnBlock(rawOptions.name, rawOptions.where, rawOptions.fields, handler, config => buildChainsObject(config)[0]);
+    HandlerRegister.registerOnBlock(rawOptions.name, rawOptions.where, rawOptions.fields, handler, Env.subgraphMode.contents && rawOptions.runsFirst === true, Env.subgraphMode.contents ? rawOptions.contractRegister : undefined, config => buildChainsObject(config)[0]);
   };
   let keysMemo = {
     contents: undefined
@@ -413,7 +414,7 @@ async function startIndexer(config, logger, persistence, resetOpt, isTestOpt, ex
     Metrics.startRuntimeCollectors();
     Server.startServer(logger, getMetrics, envioVersion, () => Persistence.getInitializedStorageOrThrow(persistence$1).dumpEffectCache().then(prim => {}), Metrics.collectRuntime, isDevelopmentMode);
   }
-  let state = IndexerState.makeFromDbState(config$2, logger, persistence$1, Persistence.getInitializedState(persistence$1), registrationsByChainId, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, undefined, undefined, Stdlib_Option.mapOr(Worker.config, false, worker => worker.holdRealtime), onError, undefined);
+  let state = IndexerState.makeFromDbState(config$2, logger, persistence$1, Persistence.getInitializedState(persistence$1), registrationsByChainId, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, undefined, undefined, Stdlib_Option.mapOr(Worker.config, false, worker => worker.holdRealtime), onError, undefined, undefined);
   if (shouldUseTui) {
     Tui.start(config$2, logger, () => IndexerState.toMetrics(state));
   }
@@ -454,4 +455,4 @@ export {
   FatalError,
   start,
 }
-/* Tui Not a pure module */
+/* Env Not a pure module */