envio 3.2.0 → 3.3.0-alpha.0

package/src/Internal.res

@@ -269,12 +269,15 @@ type genericEvent<'params, 'block, 'transaction> = {
 // (blockNumber, timestamp, blockHash) live on the item instead.
 type event
 
-external fromGenericEvent: genericEvent<'a, 'b, 'c> => event = "%identity"
+// Opaque payload an item carries. A source builds an ecosystem-specific
+// concrete payload (see `Evm.payload` / `Fuel.payload`) and erases it to this
+// type; consumers never read it directly — the ecosystem converts it back to
+// its own payload to produce the user-facing `event`, a logger, or a raw
+// event. The concrete payload types deliberately live in the ecosystem
+// modules, not here, and are distinct per ecosystem.
+type eventPayload
 
-// Escape hatch for serialization boundaries (raw events, logging)
-// which genuinely need the runtime shape.
-external toGenericEvent: event => genericEvent<eventParams, eventBlock, eventTransaction> =
-  "%identity"
+external payloadToEvent: eventPayload => event = "%identity"
 
 type genericLoaderArgs<'event, 'context> = {
   event: 'event,
@@ -344,6 +347,16 @@ type rec paramMeta = {
   components?: array<paramMeta>,
 }
 
+// Fetch-state registry value for an indexed contract address.
+// `effectiveStartBlock` is derived from the registration block and the
+// contract's configured start block (see `FetchState.deriveEffectiveStartBlock`).
+type indexingContract = {
+  address: Address.t,
+  contractName: string,
+  registrationBlock: int,
+  effectiveStartBlock: int,
+}
+
 // This is private so it's not manually constructed internally
 // The idea is that it can only be coerced from fuel/evmEventConfig
 // and it can include their fields. We prevent manual creation,
@@ -358,6 +371,12 @@ type eventConfig = private {
   // Usually always false for wildcard events
   // But might be true for wildcard event with dynamic event filter by addresses
   dependsOnAddresses: bool,
+  // Precompiled predicate (EVM only) for events that filter an indexed address
+  // param by registered addresses. Given the decoded event and the log's block
+  // number, drops an event whose param-address isn't registered at/before that
+  // block — the param-level analogue of EventRouter's srcAddress
+  // `effectiveStartBlock` check. Absent otherwise.
+  clientAddressFilter?: (eventPayload, int, dict<indexingContract>) => bool,
   handler: option<handler>,
   contractRegister: option<contractRegister>,
   paramsRawEventSchema: S.schema<eventParams>,
@@ -483,7 +502,25 @@ type eventItem = private {
   blockNumber: int,
   blockHash: string,
   logIndex: int,
-  event: event,
+  payload: eventPayload,
+}
+
+// Row shape for the `raw_events` table. Defined here (rather than in
+// `InternalTable`) so the ecosystem's `toRawEvent` can reference it without
+// pulling in `InternalTable`'s dependency on `Config`.
+type rawEvent = {
+  chain_id: int,
+  event_id: bigint,
+  event_name: string,
+  contract_name: string,
+  block_number: int,
+  log_index: int,
+  src_address: Address.t,
+  block_hash: string,
+  block_timestamp: int,
+  block_fields: JSON.t,
+  transaction_fields: JSON.t,
+  params: JSON.t,
 }
 
 // Opaque type to support both EVM and other ecosystems
@@ -517,7 +554,7 @@ type item =
       blockNumber: int,
       blockHash: string,
       logIndex: int,
-      event: event,
+      payload: eventPayload,
     })
   | @as(1) Block({onBlockConfig: onBlockConfig, blockNumber: int, logIndex: int})
 

package/src/LoadLayer.res

@@ -2,19 +2,20 @@ let loadById = (
   ~loadManager,
   ~persistence: Persistence.t,
   ~entityConfig: Internal.entityConfig,
-  ~inMemoryStore,
+  ~indexerState,
   ~shouldGroup,
   ~item,
+  ~ecosystem,
   ~entityId,
 ) => {
   let key = `${entityConfig.name}.get`
-  let inMemTable = inMemoryStore->InMemoryStore.getInMemTable(~entityConfig)
+  let inMemTable = indexerState->InMemoryStore.getInMemTable(~entityConfig)
 
   let load = async (idsToLoad, ~onError as _) => {
     let storage = persistence->Persistence.getInitializedStorageOrThrow
     let timerRef = Prometheus.StorageLoad.startOperation(~storage=storage.name, ~operation=key)
 
-    // Since LoadManager.call prevents registerign entities already existing in the inMemoryStore,
+    // Since LoadManager.call prevents registering entities already in the in-memory store,
     // we can be sure that we load only the new ones.
     let dbEntities = try {
       (
@@ -28,7 +29,10 @@ let loadById = (
       )->(Utils.magic: array<unknown> => array<Internal.entity>)
     } catch {
     | Persistence.StorageError({message, reason}) =>
-      reason->ErrorHandling.mkLogAndRaise(~logger=item->Logging.getItemLogger, ~msg=message)
+      reason->ErrorHandling.mkLogAndRaise(
+        ~logger=Ecosystem.getItemLogger(item, ~ecosystem),
+        ~msg=message,
+      )
     }
 
     let entitiesMap = Dict.make()
@@ -40,7 +44,7 @@ let loadById = (
     }
     idsToLoad->Array.forEach(entityId => {
       inMemTable->InMemoryTable.Entity.initValue(
-        ~committedCheckpointId=inMemoryStore.committedCheckpointId,
+        ~committedCheckpointId=indexerState->IndexerState.committedCheckpointId,
         ~key=entityId,
         ~entity=entitiesMap->Utils.Dict.dangerouslyGetNonOption(entityId),
       )
@@ -68,7 +72,7 @@ let loadById = (
 let callEffect = (
   ~effect: Internal.effect,
   ~arg: Internal.effectArgs,
-  ~inMemTable: InMemoryStore.effectCacheInMemTable,
+  ~inMemTable: IndexerState.effectCacheInMemTable,
   ~timerRef,
   ~onError,
 ) => {
@@ -245,13 +249,14 @@ let loadEffect = (
   ~persistence: Persistence.t,
   ~effect: Internal.effect,
   ~effectArgs,
-  ~inMemoryStore,
+  ~indexerState,
   ~shouldGroup,
   ~item,
+  ~ecosystem,
 ) => {
   let effectName = effect.name
   let key = `${effectName}.effect`
-  let inMemTable = inMemoryStore->InMemoryStore.getEffectInMemTable(~effect)
+  let inMemTable = indexerState->InMemoryStore.getEffectInMemTable(~effect)
 
   let load = async (args, ~onError) => {
     let idsToLoad = args->Array.map((arg: Internal.effectArgs) => arg.cacheKey)
@@ -279,9 +284,7 @@ let loadEffect = (
         )->(Utils.magic: array<unknown> => array<Internal.effectCacheItem>)
       } catch {
       | exn =>
-        item
-        ->Logging.getItemLogger
-        ->Logging.childWarn({
+        Ecosystem.getItemLogger(item, ~ecosystem)->Logging.childWarn({
           "msg": `Failed to load cache effect cache. The indexer will continue working, but the effect will not be able to use the cache.`,
           "err": exn->Utils.prettifyExn,
           "effect": effectName,
@@ -298,9 +301,7 @@ let loadEffect = (
         | S.Raised(error) =>
           inMemTable.invalidationsCount = inMemTable.invalidationsCount + 1
           Prometheus.EffectCacheInvalidationsCount.increment(~effectName)
-          item
-          ->Logging.getItemLogger
-          ->Logging.childTrace({
+          Ecosystem.getItemLogger(item, ~ecosystem)->Logging.childTrace({
             "msg": "Invalidated effect cache",
             "input": dbEntity.id,
             "effect": effectName,
@@ -354,13 +355,14 @@ let loadByFilter = (
   ~loadManager,
   ~persistence: Persistence.t,
   ~entityConfig: Internal.entityConfig,
-  ~inMemoryStore,
+  ~indexerState,
   ~shouldGroup,
   ~item,
+  ~ecosystem,
   ~filter: EntityFilter.t,
 ) => {
   let key = filter->EntityFilter.toOperationKey(~entityName=entityConfig.name)
-  let inMemTable = inMemoryStore->InMemoryStore.getInMemTable(~entityConfig)
+  let inMemTable = indexerState->InMemoryStore.getInMemTable(~entityConfig)
 
   let load = async (filters: array<EntityFilter.t>, ~onError as _) => {
     let storage = persistence->Persistence.getInitializedStorageOrThrow
@@ -385,7 +387,7 @@ let loadByFilter = (
 
         entities->Array.forEach(entity => {
           inMemTable->InMemoryTable.Entity.initValue(
-            ~committedCheckpointId=inMemoryStore.committedCheckpointId,
+            ~committedCheckpointId=indexerState->IndexerState.committedCheckpointId,
             ~key=entity.id,
             ~entity=Some(entity),
           )
@@ -396,7 +398,7 @@ let loadByFilter = (
       | Persistence.StorageError({message, reason}) =>
         reason->ErrorHandling.mkLogAndRaise(
           ~logger=Logging.createChildFrom(
-            ~logger=item->Logging.getItemLogger,
+            ~logger=Ecosystem.getItemLogger(item, ~ecosystem),
             // The executed query might be merged from multiple getWhere
             // calls, so report it as the operation users write with the
             // values bound to its placeholders, instead of an internal

package/src/LoadLayer.res.mjs

@@ -4,10 +4,12 @@ import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Hrtime from "./bindings/Hrtime.res.mjs";
 import * as Logging from "./Logging.res.mjs";
+import * as Ecosystem from "./Ecosystem.res.mjs";
 import * as Prometheus from "./Prometheus.res.mjs";
 import * as LoadManager from "./LoadManager.res.mjs";
 import * as Persistence from "./Persistence.res.mjs";
 import * as EntityFilter from "./db/EntityFilter.res.mjs";
+import * as IndexerState from "./IndexerState.res.mjs";
 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";
@@ -15,9 +17,9 @@ import * as InMemoryTable from "./InMemoryTable.res.mjs";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
-function loadById(loadManager, persistence, entityConfig, inMemoryStore, shouldGroup, item, entityId) {
+function loadById(loadManager, persistence, entityConfig, indexerState, shouldGroup, item, ecosystem, entityId) {
   let key = entityConfig.name + `.get`;
-  let inMemTable = InMemoryStore.getInMemTable(inMemoryStore, entityConfig);
+  let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig);
   let load = async (idsToLoad, param) => {
     let storage = Persistence.getInitializedStorageOrThrow(persistence);
     let timerRef = Prometheus.StorageLoad.startOperation(storage.name, key);
@@ -31,7 +33,7 @@ function loadById(loadManager, persistence, entityConfig, inMemoryStore, shouldG
     } catch (raw_exn) {
       let exn = Primitive_exceptions.internalToException(raw_exn);
       if (exn.RE_EXN_ID === Persistence.StorageError) {
-        dbEntities = ErrorHandling.mkLogAndRaise(Logging.getItemLogger(item), exn.message, exn.reason);
+        dbEntities = ErrorHandling.mkLogAndRaise(Ecosystem.getItemLogger(item, ecosystem), exn.message, exn.reason);
       } else {
         throw exn;
       }
@@ -41,7 +43,7 @@ function loadById(loadManager, persistence, entityConfig, inMemoryStore, shouldG
       let entity = dbEntities[idx];
       entitiesMap[entity.id] = entity;
     }
-    idsToLoad.forEach(entityId => InMemoryTable.Entity.initValue(inMemTable, inMemoryStore.committedCheckpointId, entityId, entitiesMap[entityId]));
+    idsToLoad.forEach(entityId => InMemoryTable.Entity.initValue(inMemTable, IndexerState.committedCheckpointId(indexerState), entityId, entitiesMap[entityId]));
     return Prometheus.StorageLoad.endOperation(timerRef, storage.name, key, idsToLoad.length, dbEntities.length);
   };
   return LoadManager.call(loadManager, entityId, key, load, LoadManager.noopHasher, shouldGroup, hash => hash in inMemTable.latestEntityChangeById, InMemoryTable.Entity.getUnsafe(inMemTable));
@@ -126,10 +128,10 @@ function executeWithRateLimit(effect, effectArgs, inMemTable, onError, isFromQue
   return Promise.all(promises);
 }
 
-function loadEffect(loadManager, persistence, effect, effectArgs, inMemoryStore, shouldGroup, item) {
+function loadEffect(loadManager, persistence, effect, effectArgs, indexerState, shouldGroup, item, ecosystem) {
   let effectName = effect.name;
   let key = effectName + `.effect`;
-  let inMemTable = InMemoryStore.getEffectInMemTable(inMemoryStore, effect);
+  let inMemTable = InMemoryStore.getEffectInMemTable(indexerState, effect);
   let load = async (args, onError) => {
     let idsToLoad = args.map(arg => arg.cacheKey);
     let idsFromCache = new Set();
@@ -150,7 +152,7 @@ function loadEffect(loadManager, persistence, effect, effectArgs, inMemoryStore,
         }, match$1.table);
       } catch (raw_exn) {
         let exn = Primitive_exceptions.internalToException(raw_exn);
-        Logging.childWarn(Logging.getItemLogger(item), {
+        Logging.childWarn(Ecosystem.getItemLogger(item, ecosystem), {
           msg: `Failed to load cache effect cache. The indexer will continue working, but the effect will not be able to use the cache.`,
           err: Utils.prettifyExn(exn),
           effect: effectName
@@ -167,7 +169,7 @@ function loadEffect(loadManager, persistence, effect, effectArgs, inMemoryStore,
           if (error.RE_EXN_ID === S$RescriptSchema.Raised) {
             inMemTable.invalidationsCount = inMemTable.invalidationsCount + 1 | 0;
             Prometheus.EffectCacheInvalidationsCount.increment(effectName);
-            return Logging.childTrace(Logging.getItemLogger(item), {
+            return Logging.childTrace(Ecosystem.getItemLogger(item, ecosystem), {
               msg: "Invalidated effect cache",
               input: dbEntity.id,
               effect: effectName,
@@ -197,9 +199,9 @@ function loadEffect(loadManager, persistence, effect, effectArgs, inMemoryStore,
   return LoadManager.call(loadManager, effectArgs, key, load, args => args.cacheKey, shouldGroup, hash => InMemoryStore.hasEffectOutput(inMemTable, hash), hash => InMemoryStore.getEffectOutputUnsafe(inMemTable, hash));
 }
 
-function loadByFilter(loadManager, persistence, entityConfig, inMemoryStore, shouldGroup, item, filter) {
+function loadByFilter(loadManager, persistence, entityConfig, indexerState, shouldGroup, item, ecosystem, filter) {
   let key = EntityFilter.toOperationKey(filter, entityConfig.name);
-  let inMemTable = InMemoryStore.getInMemTable(inMemoryStore, entityConfig);
+  let inMemTable = InMemoryStore.getInMemTable(indexerState, entityConfig);
   let load = async (filters, param) => {
     let storage = Persistence.getInitializedStorageOrThrow(persistence);
     let timerRef = Prometheus.StorageLoad.startOperation(storage.name, key);
@@ -211,13 +213,13 @@ function loadByFilter(loadManager, persistence, entityConfig, inMemoryStore, sho
     await Promise.all(queries.map(async filter => {
       try {
         let entities = await storage.loadOrThrow(filter, entityConfig.table);
-        entities.forEach(entity => InMemoryTable.Entity.initValue(inMemTable, inMemoryStore.committedCheckpointId, entity.id, entity));
+        entities.forEach(entity => InMemoryTable.Entity.initValue(inMemTable, IndexerState.committedCheckpointId(indexerState), entity.id, entity));
         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(Logging.createChildFrom(Logging.getItemLogger(item), {
+          return ErrorHandling.mkLogAndRaise(Logging.createChildFrom(Ecosystem.getItemLogger(item, ecosystem), {
             operation: key,
             params: EntityFilter.getParams(filter)
           }), exn.message, exn.reason);

package/src/LoadLayer.resi

@@ -2,9 +2,10 @@ let loadById: (
   ~loadManager: LoadManager.t,
   ~persistence: Persistence.t,
   ~entityConfig: Internal.entityConfig,
-  ~inMemoryStore: InMemoryStore.t,
+  ~indexerState: IndexerState.t,
   ~shouldGroup: bool,
   ~item: Internal.item,
+  ~ecosystem: Ecosystem.t,
   ~entityId: string,
 ) => promise<option<Internal.entity>>
 
@@ -12,9 +13,10 @@ let loadByFilter: (
   ~loadManager: LoadManager.t,
   ~persistence: Persistence.t,
   ~entityConfig: Internal.entityConfig,
-  ~inMemoryStore: InMemoryStore.t,
+  ~indexerState: IndexerState.t,
   ~shouldGroup: bool,
   ~item: Internal.item,
+  ~ecosystem: Ecosystem.t,
   ~filter: EntityFilter.t,
 ) => promise<array<Internal.entity>>
 
@@ -23,7 +25,8 @@ let loadEffect: (
   ~persistence: Persistence.t,
   ~effect: Internal.effect,
   ~effectArgs: Internal.effectArgs,
-  ~inMemoryStore: InMemoryStore.t,
+  ~indexerState: IndexerState.t,
   ~shouldGroup: bool,
   ~item: Internal.item,
+  ~ecosystem: Ecosystem.t,
 ) => promise<Internal.effectOutput>

package/src/LogSelection.res

@@ -60,6 +60,10 @@ let make = (~addresses, ~topicSelections) => {
 type parsedEventFilters = {
   getEventFiltersOrThrow: ChainMap.Chain.t => Internal.eventFilters,
   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`.
+  addressFilterParamGroups: array<array<string>>,
   // `_gte` from the top-level `block` filter of the user's `where`,
   // resolved at build time (per-chain via the `probeChainId`). The
   // caller uses this to override the per-event `startBlock` — a
@@ -151,6 +155,70 @@ let makeDetectionChainArg = (
   chainObj
 }
 
+// Sentinel returned by `chain.<Contract>.addresses` during detection. A Proxy
+// whose traps throw on any access, so the only non-throwing use is passing it
+// straight through as a param filter value — which `extractAddressFilterGroups`
+// then finds by identity. Misuse (spread/map/index/...) fails loud at the site.
+let makeAddressesProbe: (
+  ~contractName: string,
+) => array<Address.t> = %raw(`function (contractName) {
+  var trap = function () {
+    throw new Error(
+      'Invalid where configuration for "' + contractName +
+      '": chain.' + contractName + '.addresses must be passed directly as an indexed-param ' +
+      'filter value (e.g. { params: { to: chain.' + contractName + '.addresses } }). ' +
+      'It cannot be spread, mapped, indexed, or otherwise transformed.'
+    );
+  };
+  return new Proxy([], {get: trap});
+}`)
+
+// Find which indexed params the probed `where` result assigned the Proxy to
+// (DNF: object => one AND-group, array => OR of groups), neutralizing each match
+// to `[]` so later passes can't touch the throwing Proxy. Throws when the
+// callback read the addresses but didn't use them as a param filter value, since
+// the caller only invokes this once it knows the addresses were read.
+let extractAddressFilterGroupsOrThrow = (
+  result: JSON.t,
+  ~probe: array<Address.t>,
+  ~contractName: string,
+): array<array<string>> => {
+  let groups = []
+  let scanGroup = (paramsObj: dict<JSON.t>) => {
+    let names = []
+    paramsObj->Utils.Dict.forEachWithKey((value, key) => {
+      if value === probe->(Utils.magic: array<Address.t> => JSON.t) {
+        names->Array.push(key)->ignore
+        paramsObj->Dict.set(key, []->(Utils.magic: array<unknown> => JSON.t))
+      }
+    })
+    if names->Utils.Array.isEmpty->not {
+      groups->Array.push(names)->ignore
+    }
+  }
+  switch result {
+  | Object(obj) =>
+    switch obj->Dict.get("params") {
+    | Some(Object(p)) => scanGroup(p)
+    | Some(Array(arr)) =>
+      arr->Array.forEach(item =>
+        switch item {
+        | Object(p) => scanGroup(p)
+        | _ => ()
+        }
+      )
+    | _ => ()
+    }
+  | _ => ()
+  }
+  if groups->Utils.Array.isEmpty {
+    JsError.throwWithMessage(
+      `Invalid where configuration for ${contractName}. The callback reads \`chain.${contractName}.addresses\` but doesn't use it as an indexed-param filter value. Use it directly, e.g. { params: { to: chain.${contractName}.addresses } }.`,
+    )
+  }
+  groups
+}
+
 let parseEventFiltersOrThrow = {
   let emptyTopics = []
   let noopGetter = _ => emptyTopics
@@ -167,6 +235,7 @@ let parseEventFiltersOrThrow = {
     ~topic3=noopGetter,
   ): parsedEventFilters => {
     let filterByAddresses = ref(false)
+    let addressFilterParamGroups = ref([])
     let startBlock = ref(None)
     let topic0 = [sighash->EvmTypes.Hex.fromStringUnsafe]
     let default = {
@@ -286,24 +355,23 @@ let parseEventFiltersOrThrow = {
         // `startBlock` (from `where.block`) for this chain — a second
         // invocation would risk observing different state for callbacks
         // that close over mutable references.
-        let probedResult = try {
-          let chain = makeDetectionChainArg(
-            ~contractName,
-            ~chainId=probeChainId,
-            ~getAddresses=() => {
-              filterByAddresses := true
-              []
-            },
-          )
-          Some(fn({chain: chain->Obj.magic}))
-        } catch {
-        | _ => None
-        }
-        switch probedResult {
-        | Some(result) =>
-          startBlock := extractStartBlock(~onEventBlockFilterSchema, ~contractName, result)
-        | None => ()
+        // A misused Proxy (or any throw from the callback) propagates as-is —
+        // the Proxy's guidance message surfaces without wrapping.
+        let addressesProbe = makeAddressesProbe(~contractName)
+        let chain = makeDetectionChainArg(
+          ~contractName,
+          ~chainId=probeChainId,
+          ~getAddresses=() => {
+            filterByAddresses := true
+            addressesProbe
+          },
+        )
+        let probedResult = fn({chain: chain->Obj.magic})
+        if filterByAddresses.contents {
+          addressFilterParamGroups :=
+            extractAddressFilterGroupsOrThrow(probedResult, ~probe=addressesProbe, ~contractName)
         }
+        startBlock := extractStartBlock(~onEventBlockFilterSchema, ~contractName, probedResult)
         if filterByAddresses.contents {
           chain => Internal.Dynamic(
             addresses => {
@@ -343,6 +411,7 @@ let parseEventFiltersOrThrow = {
     {
       getEventFiltersOrThrow,
       filterByAddresses: filterByAddresses.contents,
+      addressFilterParamGroups: addressFilterParamGroups.contents,
       startBlock: startBlock.contents,
     }
   }

package/src/LogSelection.res.mjs

@@ -121,6 +121,58 @@ function makeDetectionChainArg(contractName, chainId, getAddresses) {
   return chainObj;
 }
 
+let makeAddressesProbe = (function (contractName) {
+  var trap = function () {
+    throw new Error(
+      'Invalid where configuration for "' + contractName +
+      '": chain.' + contractName + '.addresses must be passed directly as an indexed-param ' +
+      'filter value (e.g. { params: { to: chain.' + contractName + '.addresses } }). ' +
+      'It cannot be spread, mapped, indexed, or otherwise transformed.'
+    );
+  };
+  return new Proxy([], {get: trap});
+});
+
+function extractAddressFilterGroupsOrThrow(result, probe, contractName) {
+  let groups = [];
+  let scanGroup = paramsObj => {
+    let names = [];
+    Utils.Dict.forEachWithKey(paramsObj, (value, key) => {
+      if (value === probe) {
+        names.push(key);
+        paramsObj[key] = [];
+        return;
+      }
+    });
+    if (!Utils.$$Array.isEmpty(names)) {
+      groups.push(names);
+      return;
+    }
+  };
+  if (typeof result === "object" && result !== null && !Array.isArray(result)) {
+    let match = result["params"];
+    if (match !== undefined) {
+      if (Array.isArray(match)) {
+        match.forEach(item => {
+          if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+            return scanGroup(item);
+          }
+        });
+      } else {
+        switch (typeof match) {
+          case "object" :
+            scanGroup(match);
+            break;
+        }
+      }
+    }
+  }
+  if (Utils.$$Array.isEmpty(groups)) {
+    Stdlib_JsError.throwWithMessage(`Invalid where configuration for ` + contractName + `. The callback reads \`chain.` + contractName + `.addresses\` but doesn't use it as an indexed-param filter value. Use it directly, e.g. { params: { to: chain.` + contractName + `.addresses } }.`);
+  }
+  return groups;
+}
+
 let emptyTopics = [];
 
 function noopGetter(param) {
@@ -134,6 +186,7 @@ function parseEventFiltersOrThrow(eventFilters, sighash, params, contractName, p
   let filterByAddresses = {
     contents: false
   };
+  let addressFilterParamGroups = [];
   let startBlock;
   let topic0 = [sighash];
   let $$default = {
@@ -208,21 +261,18 @@ function parseEventFiltersOrThrow(eventFilters, sighash, params, contractName, p
   let getEventFiltersOrThrow;
   if (eventFilters !== undefined) {
     if (typeof eventFilters === "function") {
-      let probedResult;
-      try {
-        let chain = makeDetectionChainArg(contractName, probeChainId, () => {
-          filterByAddresses.contents = true;
-          return [];
-        });
-        probedResult = eventFilters({
-          chain: chain
-        });
-      } catch (exn) {
-        probedResult = undefined;
-      }
-      if (probedResult !== undefined) {
-        startBlock = extractStartBlock(probedResult, onEventBlockFilterSchema, contractName);
+      let addressesProbe = makeAddressesProbe(contractName);
+      let chain = makeDetectionChainArg(contractName, probeChainId, () => {
+        filterByAddresses.contents = true;
+        return addressesProbe;
+      });
+      let probedResult = eventFilters({
+        chain: chain
+      });
+      if (filterByAddresses.contents) {
+        addressFilterParamGroups = extractAddressFilterGroupsOrThrow(probedResult, addressesProbe, contractName);
       }
+      startBlock = extractStartBlock(probedResult, onEventBlockFilterSchema, contractName);
       getEventFiltersOrThrow = filterByAddresses.contents ? chain => ({
           TAG: "Dynamic",
           _0: addresses => {
@@ -258,6 +308,7 @@ function parseEventFiltersOrThrow(eventFilters, sighash, params, contractName, p
   return {
     getEventFiltersOrThrow: getEventFiltersOrThrow,
     filterByAddresses: filterByAddresses.contents,
+    addressFilterParamGroups: addressFilterParamGroups,
     startBlock: startBlock
   };
 }
@@ -272,6 +323,8 @@ export {
   extractStartBlock,
   makeChainArg,
   makeDetectionChainArg,
+  makeAddressesProbe,
+  extractAddressFilterGroupsOrThrow,
   parseEventFiltersOrThrow,
 }
 /* eventBlockRangeSchema Not a pure module */

package/src/Logging.res

@@ -155,46 +155,11 @@ let createChildFrom = (~logger: t, ~params: 'a) => {
   logger->child(params->createChildParams)
 }
 
-let getItemLogger = {
-  let cacheKey = "_logger"
-  (item: Internal.item) => {
-    switch item
-    ->(Utils.magic: Internal.item => dict<Pino.t>)
-    ->Utils.Dict.dangerouslyGetNonOption(cacheKey) {
-    | Some(l) => l
-    | None => {
-        let l = getLogger()->child(
-          switch item {
-          | Event({eventConfig, chain, blockNumber, logIndex, event}) =>
-            {
-              "contractName": eventConfig.contractName,
-              "eventName": eventConfig.name,
-              "chainId": chain->ChainMap.Chain.toChainId,
-              "block": blockNumber,
-              "logIndex": logIndex,
-              "address": (event->Internal.toGenericEvent).srcAddress,
-            }->createChildParams
-          | Block({blockNumber, onBlockConfig}) =>
-            {
-              "onBlock": onBlockConfig.name,
-              "chainId": onBlockConfig.chainId,
-              "block": blockNumber,
-            }->createChildParams
-          },
-        )
-        item->(Utils.magic: Internal.item => dict<Pino.t>)->Dict.set(cacheKey, l)
-        l
-      }
-    }
-  }
-}
-
 @inline
-let logForItem = (item, level: Pino.logLevel, message: string, ~params=?) => {
+let logAtLevel = (logger: t, level: Pino.logLevel, message: string, ~params=?) => {
   (
-    item
-    ->getItemLogger
-    ->(Utils.magic: Pino.t => dict<(option<'a>, string) => unit>)
+    logger
+    ->(Utils.magic: t => dict<(option<'a>, string) => unit>)
     ->Dict.getUnsafe((level :> string))
   )(params, message)
 }
@@ -207,11 +172,13 @@ let noopLogger: Envio.logger = {
   errorWithExn: (_message: string, _exn) => (),
 }
 
-let getUserLogger = (item): Envio.logger => {
-  info: (message: string, ~params=?) => item->logForItem(#uinfo, message, ~params?),
-  debug: (message: string, ~params=?) => item->logForItem(#udebug, message, ~params?),
-  warn: (message: string, ~params=?) => item->logForItem(#uwarn, message, ~params?),
-  error: (message: string, ~params=?) => item->logForItem(#uerror, message, ~params?),
+// Wrap a (child) logger as the user-facing `context.log`, routing through the
+// custom `u*` levels. The caller builds the per-item logger via the ecosystem.
+let userLogger = (logger: t): Envio.logger => {
+  info: (message: string, ~params=?) => logger->logAtLevel(#uinfo, message, ~params?),
+  debug: (message: string, ~params=?) => logger->logAtLevel(#udebug, message, ~params?),
+  warn: (message: string, ~params=?) => logger->logAtLevel(#uwarn, message, ~params?),
+  error: (message: string, ~params=?) => logger->logAtLevel(#uerror, message, ~params?),
   errorWithExn: (message: string, exn) =>
-    item->logForItem(#uerror, message, ~params={"err": exn->Utils.prettifyExn}),
+    logger->logAtLevel(#uerror, message, ~params={"err": exn->Utils.prettifyExn}),
 }