envio 3.2.0 → 3.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -70,10 +70,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.2.0",
-    "envio-linux-x64-musl": "3.2.0",
-    "envio-linux-arm64": "3.2.0",
-    "envio-darwin-x64": "3.2.0",
-    "envio-darwin-arm64": "3.2.0"
+    "envio-linux-x64": "3.2.1",
+    "envio-linux-x64-musl": "3.2.1",
+    "envio-linux-arm64": "3.2.1",
+    "envio-darwin-x64": "3.2.1",
+    "envio-darwin-arm64": "3.2.1"
   }
 }

package/src/EventConfigBuilder.res

@@ -309,6 +309,39 @@ let resolveFieldSelection = (
   (selectedBlockFields, selectedTransactionFields)
 }
 
+// ============== Client-side address filter ==============
+
+let compileAddressFilter: string => (
+  Internal.event,
+  int,
+  dict<Internal.indexingContract>,
+) => bool = %raw(`function (body) {
+  return new Function("event", "blockNumber", "indexingAddresses", body);
+}`)
+
+// Body of the client-side address filter for a DNF of address-filtered param
+// names (OR of AND-groups): keep the event only if some group's params are all
+// registered at or before the log's block. The DNF is fixed here, so it's
+// unrolled into one boolean expression — no per-event closure, loop, or array.
+// `None` when there's no address-param filter. Exposed for snapshotting.
+let buildAddressFilterBody = (groups: array<array<string>>): option<string> => {
+  switch groups {
+  | [] => None
+  | _ =>
+    let leaf = name =>
+      `(ic = indexingAddresses[p[${JSON.stringify(
+          JSON.String(name),
+        )}]]) !== undefined && ic.effectiveStartBlock <= blockNumber`
+    let groupExprs =
+      groups->Array.map(group => "(" ++ group->Array.map(leaf)->Array.join(" && ") ++ ")")
+    Some("var p = event.params, ic; return " ++ groupExprs->Array.join(" || ") ++ ";")
+  }
+}
+
+let buildAddressFilter = (groups: array<array<string>>): option<
+  (Internal.event, int, dict<Internal.indexingContract>) => bool,
+> => buildAddressFilterBody(groups)->Option.map(compileAddressFilter)
+
 // ============== Build complete EVM event config ==============
 
 let buildEvmEventConfig = (
@@ -334,6 +367,7 @@ let buildEvmEventConfig = (
   let {
     getEventFiltersOrThrow,
     filterByAddresses,
+    addressFilterParamGroups,
     startBlock: whereStartBlock,
   } = LogSelection.parseEventFiltersOrThrow(
     ~eventFilters,
@@ -374,6 +408,7 @@ let buildEvmEventConfig = (
     simulateParamsSchema: buildSimulateParamsSchema(params),
     getEventFiltersOrThrow,
     filterByAddresses,
+    clientAddressFilter: ?buildAddressFilter(addressFilterParamGroups),
     dependsOnAddresses: !isWildcard || filterByAddresses,
     startBlock: resolvedStartBlock,
     selectedBlockFields,

package/src/EventConfigBuilder.res.mjs

@@ -251,6 +251,23 @@ function resolveFieldSelection(blockFields, transactionFields, globalBlockFields
   ];
 }
 
+let compileAddressFilter = (function (body) {
+  return new Function("event", "blockNumber", "indexingAddresses", body);
+});
+
+function buildAddressFilterBody(groups) {
+  if (groups.length === 0) {
+    return;
+  }
+  let leaf = name => `(ic = indexingAddresses[p[` + JSON.stringify(name) + `]]) !== undefined && ic.effectiveStartBlock <= blockNumber`;
+  let groupExprs = groups.map(group => "(" + group.map(leaf).join(" && ") + ")");
+  return "var p = event.params, ic; return " + groupExprs.join(" || ") + ";";
+}
+
+function buildAddressFilter(groups) {
+  return Stdlib_Option.map(buildAddressFilterBody(groups), compileAddressFilter);
+}
+
 function buildEvmEventConfig(contractName, eventName, sighash, params, isWildcard, handler, contractRegister, eventFilters, probeChainId, onEventBlockFilterSchema, blockFields, transactionFields, startBlock, globalBlockFieldsSetOpt, globalTransactionFieldsSetOpt) {
   let globalBlockFieldsSet = globalBlockFieldsSetOpt !== undefined ? Primitive_option.valFromOption(globalBlockFieldsSetOpt) : new Set();
   let globalTransactionFieldsSet = globalTransactionFieldsSetOpt !== undefined ? Primitive_option.valFromOption(globalTransactionFieldsSetOpt) : new Set();
@@ -274,6 +291,7 @@ function buildEvmEventConfig(contractName, eventName, sighash, params, isWildcar
     isWildcard: isWildcard,
     filterByAddresses: filterByAddresses,
     dependsOnAddresses: !isWildcard || filterByAddresses,
+    clientAddressFilter: Stdlib_Option.map(buildAddressFilterBody(match.addressFilterParamGroups), compileAddressFilter),
     handler: handler,
     contractRegister: contractRegister,
     paramsRawEventSchema: buildParamsSchema(params),
@@ -393,6 +411,9 @@ export {
   buildTopicGetter,
   alwaysIncludedBlockFields,
   resolveFieldSelection,
+  compileAddressFilter,
+  buildAddressFilterBody,
+  buildAddressFilter,
   buildEvmEventConfig,
   buildSvmInstructionEventConfig,
   buildFuelEventConfig,

package/src/FetchState.res

@@ -1,9 +1,6 @@
-type contractConfig = {filterByAddresses: bool, startBlock: option<int>}
+type contractConfig = {startBlock: option<int>}
 
-type indexingAddress = {
-  ...Internal.indexingAddress,
-  effectiveStartBlock: int,
-}
+type indexingAddress = Internal.indexingContract
 
 let deriveEffectiveStartBlock = (~registrationBlock: int, ~contractStartBlock: option<int>) => {
   Pervasives.max(Pervasives.max(registrationBlock, 0), contractStartBlock->Option.getOr(0))
@@ -756,7 +753,6 @@ Returns OptimizedPartitions.t directly.
 */
 let createPartitionsFromIndexingAddresses = (
   ~registeringContractsByContract: dict<dict<indexingAddress>>,
-  ~contractConfigs: dict<contractConfig>,
   ~dynamicContracts: Utils.Set.t<string>,
   ~normalSelection: selection,
   ~maxAddrInPartition: int,
@@ -778,9 +774,6 @@ OptimizedPartitions.t => {
     let addresses =
       registeringContracts->Dict.keysToArray->(Utils.magic: array<string> => array<Address.t>)
 
-    // Can unsafely get it, because we already filtered out the contracts
-    // that don't have any events to fetch
-    let contractConfig = contractConfigs->Dict.getUnsafe(contractName)
     let isDynamic = dynamicContracts->Utils.Set.has(contractName)
     let partitions = isDynamic ? dynamicPartitions : nonDynamicPartitions
 
@@ -802,30 +795,23 @@ OptimizedPartitions.t => {
       let maybeNextStartBlockKey =
         ascKeys->Array.getUnsafe(idx + 1)->(Utils.magic: string => option<string>)
 
-      // For this case we can't filter out events earlier than contract registration
-      // on the client side, so we need to keep the old logic of creating
-      // a partition for every block range, so there are no irrelevant events
-      let shouldAllocateNewPartition = if contractConfig.filterByAddresses {
-        true
-      } else {
-        switch maybeNextStartBlockKey {
-        | None => true
-        | Some(nextStartBlockKey) => {
-            let nextStartBlock = nextStartBlockKey->Int.fromString->Option.getUnsafe
-            let shouldJoinCurrentStartBlock =
-              nextStartBlock - startBlockRef.contents < OptimizedPartitions.tooFarBlockRange
-
-            // If dynamic contract registration are close to eachother
-            // and it's possible to use dc.effectiveStartBlock to filter out events on client side
-            // then we can optimize the number of partitions,
-            // by putting dcs with different startBlocks in the same partition
-            if shouldJoinCurrentStartBlock {
-              addressesRef :=
-                addressesRef.contents->Array.concat(byStartBlock->Dict.getUnsafe(nextStartBlockKey))
-              false
-            } else {
-              true
-            }
+      let shouldAllocateNewPartition = switch maybeNextStartBlockKey {
+      | None => true
+      | Some(nextStartBlockKey) => {
+          let nextStartBlock = nextStartBlockKey->Int.fromString->Option.getUnsafe
+          let shouldJoinCurrentStartBlock =
+            nextStartBlock - startBlockRef.contents < OptimizedPartitions.tooFarBlockRange
+
+          // Addresses with different start blocks within range share a partition;
+          // events before each address's effectiveStartBlock are dropped on the
+          // client side (EventRouter for the srcAddress, the event's
+          // clientAddressFilter for address-valued params).
+          if shouldJoinCurrentStartBlock {
+            addressesRef :=
+              addressesRef.contents->Array.concat(byStartBlock->Dict.getUnsafe(nextStartBlockKey))
+            false
+          } else {
+            true
           }
         }
       }
@@ -907,15 +893,10 @@ OptimizedPartitions.t => {
           }
         }
 
-        let nextContractName =
-          nextP.addressesByContractName->Dict.keysToArray->Utils.Array.firstUnsafe
-        let hasFilterByAddresses = (
-          contractConfigs->Dict.getUnsafe(nextContractName)
-        ).filterByAddresses
         let isTooFar = currentPBlock + OptimizedPartitions.tooFarBlockRange < nextPBlock
 
-        if isTooFar || hasFilterByAddresses {
-          // Too far or address-filtered: mergeBlock on current, merge addresses into next
+        if isTooFar {
+          // Too far: mergeBlock on current, merge addresses into next
           mergedNonDynamic
           ->Array.push({
             ...currentP,
@@ -927,7 +908,7 @@ OptimizedPartitions.t => {
               addressesByContractName: mergedAddresses,
             }
         } else {
-          // Close and not address-filtered: push next's addresses into current
+          // Close: push next's addresses into current
           currentPRef := {
               ...currentP,
               addressesByContractName: mergedAddresses,
@@ -968,7 +949,6 @@ let registerDynamicContracts = (
   let indexingAddresses = fetchState.indexingAddresses
   let registeringContractsByContract: dict<dict<indexingAddress>> = Dict.make()
   let earliestRegisteringEventBlockNumber = ref(%raw(`Infinity`))
-  let hasDCWithFilterByAddresses = ref(false)
   // Addresses registered for contracts without matching events. These are not
   // added to partitions, but they are tracked on fetchState.indexingAddresses
   // so that later conflicting registrations are detected, and are persisted
@@ -991,7 +971,7 @@ let registerDynamicContracts = (
         let shouldRemove = ref(false)
 
         switch fetchState.contractConfigs->Utils.Dict.dangerouslyGetNonOption(dc.contractName) {
-        | Some({filterByAddresses, startBlock: contractStartBlock}) =>
+        | Some({startBlock: contractStartBlock}) =>
           let dcWithStartBlock: indexingAddress = {
             address: dc.address,
             contractName: dc.contractName,
@@ -1038,9 +1018,7 @@ let registerDynamicContracts = (
               // FIXME: This unsafely relies on the asc order of the items
               // which is 99% true, but there were cases when the source ordering was wrong
               false
-            | None =>
-              hasDCWithFilterByAddresses := hasDCWithFilterByAddresses.contents || filterByAddresses
-              true
+            | None => true
             }
             if shouldUpdate {
               earliestRegisteringEventBlockNumber :=
@@ -1218,7 +1196,6 @@ let registerDynamicContracts = (
 
       let optimizedPartitions = createPartitionsFromIndexingAddresses(
         ~registeringContractsByContract,
-        ~contractConfigs=fetchState.contractConfigs,
         ~dynamicContracts=dynamicContractsRef.contents,
         ~normalSelection=fetchState.normalSelection,
         ~maxAddrInPartition=fetchState.optimizedPartitions.maxAddrInPartition,
@@ -1245,6 +1222,20 @@ let handleQueryResult = (
   ~latestFetchedBlock: blockNumberAndTimestamp,
   ~newItems,
 ): t => {
+  // Drop events an address-param filter rejects. A merged partition may
+  // over-fetch a wildcard event whose indexed address param references an
+  // address registered after the log's block; `clientAddressFilter` is the
+  // param-level analogue of EventRouter's srcAddress effectiveStartBlock check.
+  let newItems = newItems->Array.filter(item =>
+    switch item {
+    | Internal.Event({eventConfig, event, blockNumber}) =>
+      switch eventConfig.clientAddressFilter {
+      | Some(filter) => filter(event, blockNumber, fetchState.indexingAddresses)
+      | None => true
+      }
+    | _ => true
+    }
+  )
   fetchState->updateInternal(
     ~optimizedPartitions=fetchState.optimizedPartitions->OptimizedPartitions.handleQueryResponse(
       ~query,
@@ -1572,15 +1563,14 @@ let make = (
   let normalEventConfigs = []
   let contractNamesWithNormalEvents = Utils.Set.make()
   let indexingAddresses = Dict.make()
-  let contractConfigs = Dict.make()
+  let contractConfigs: dict<contractConfig> = Dict.make()
 
   eventConfigs->Array.forEach(ec => {
     switch contractConfigs->Utils.Dict.dangerouslyGetNonOption(ec.contractName) {
-    | Some({filterByAddresses, startBlock}) =>
+    | Some({startBlock}) =>
       contractConfigs->Dict.set(
         ec.contractName,
         {
-          filterByAddresses: filterByAddresses || ec.filterByAddresses,
           startBlock: switch (startBlock, ec.startBlock) {
           | (Some(a), Some(b)) => Some(Pervasives.min(a, b))
           | (Some(_) as s, None) | (None, Some(_) as s) => s
@@ -1592,7 +1582,6 @@ let make = (
       contractConfigs->Dict.set(
         ec.contractName,
         {
-          filterByAddresses: ec.filterByAddresses,
           startBlock: ec.startBlock,
         },
       )
@@ -1672,7 +1661,6 @@ let make = (
 
   let optimizedPartitions = createPartitionsFromIndexingAddresses(
     ~registeringContractsByContract,
-    ~contractConfigs,
     ~dynamicContracts,
     ~normalSelection,
     ~maxAddrInPartition,
@@ -1875,7 +1863,6 @@ let rollback = (fetchState: t, ~targetBlockNumber) => {
   // Step 3: Recreate partitions from deleted partition addresses
   let optimizedPartitions = createPartitionsFromIndexingAddresses(
     ~registeringContractsByContract,
-    ~contractConfigs=fetchState.contractConfigs,
     ~dynamicContracts=fetchState.optimizedPartitions.dynamicContracts,
     ~normalSelection=fetchState.normalSelection,
     ~maxAddrInPartition=fetchState.optimizedPartitions.maxAddrInPartition,

package/src/FetchState.res.mjs

@@ -571,7 +571,7 @@ function addressesByContractNameGetAll(addressesByContractName) {
   return all;
 }
 
-function createPartitionsFromIndexingAddresses(registeringContractsByContract, contractConfigs, dynamicContracts, normalSelection, maxAddrInPartition, nextPartitionIndex, existingPartitions, progressBlockNumber) {
+function createPartitionsFromIndexingAddresses(registeringContractsByContract, dynamicContracts, normalSelection, maxAddrInPartition, nextPartitionIndex, existingPartitions, progressBlockNumber) {
   let nextPartitionIndexRef = nextPartitionIndex;
   let dynamicPartitions = [];
   let nonDynamicPartitions = [];
@@ -580,7 +580,6 @@ function createPartitionsFromIndexingAddresses(registeringContractsByContract, c
     let contractName = contractNames[cIdx];
     let registeringContracts = registeringContractsByContract[contractName];
     let addresses = Object.keys(registeringContracts);
-    let contractConfig = contractConfigs[contractName];
     let isDynamic = dynamicContracts.has(contractName);
     let partitions = isDynamic ? dynamicPartitions : nonDynamicPartitions;
     let byStartBlock = {};
@@ -596,9 +595,7 @@ function createPartitionsFromIndexingAddresses(registeringContractsByContract, c
     for (let idx = 0, idx_finish = ascKeys.length; idx < idx_finish; ++idx) {
       let maybeNextStartBlockKey = ascKeys[idx + 1 | 0];
       let shouldAllocateNewPartition;
-      if (contractConfig.filterByAddresses || maybeNextStartBlockKey === undefined) {
-        shouldAllocateNewPartition = true;
-      } else {
+      if (maybeNextStartBlockKey !== undefined) {
         let nextStartBlock = Stdlib_Int.fromString(maybeNextStartBlockKey, undefined);
         let shouldJoinCurrentStartBlock = (nextStartBlock - startBlockRef | 0) < 20000;
         if (shouldJoinCurrentStartBlock) {
@@ -607,6 +604,8 @@ function createPartitionsFromIndexingAddresses(registeringContractsByContract, c
         } else {
           shouldAllocateNewPartition = true;
         }
+      } else {
+        shouldAllocateNewPartition = true;
       }
       if (shouldAllocateNewPartition) {
         let latestFetchedBlock_blockNumber = Primitive_int.max(startBlockRef - 1 | 0, progressBlockNumber);
@@ -667,10 +666,8 @@ function createPartitionsFromIndexingAddresses(registeringContractsByContract, c
             mergedAddresses[cn] = currentAddrs;
           }
         }
-        let nextContractName = Utils.$$Array.firstUnsafe(Object.keys(nextP.addressesByContractName));
-        let hasFilterByAddresses = contractConfigs[nextContractName].filterByAddresses;
         let isTooFar = (currentPBlock + 20000 | 0) < nextPBlock;
-        if (isTooFar || hasFilterByAddresses) {
+        if (isTooFar) {
           mergedNonDynamic.push({
             id: currentP.id,
             latestFetchedBlock: currentP.latestFetchedBlock,
@@ -725,7 +722,6 @@ function registerDynamicContracts(fetchState, items) {
   let indexingAddresses = fetchState.indexingAddresses;
   let registeringContractsByContract = {};
   let earliestRegisteringEventBlockNumber = Infinity;
-  let hasDCWithFilterByAddresses = false;
   let noEventsAddresses = {};
   let registeringAddresses = {};
   for (let itemIdx = 0, itemIdx_finish = items.length; itemIdx < itemIdx_finish; ++itemIdx) {
@@ -764,18 +760,9 @@ function registerDynamicContracts(fetchState, items) {
             shouldRemove = true;
           } else {
             let registeringContract = registeringAddresses[dc.address];
-            let shouldUpdate;
-            if (registeringContract !== undefined) {
-              if (registeringContract.contractName !== dc.contractName) {
-                warnDifferentContractType(fetchState, registeringContract, dcWithStartBlock);
-                shouldUpdate = false;
-              } else {
-                shouldUpdate = false;
-              }
-            } else {
-              hasDCWithFilterByAddresses = hasDCWithFilterByAddresses || match.filterByAddresses;
-              shouldUpdate = true;
-            }
+            let shouldUpdate = registeringContract !== undefined ? (
+                registeringContract.contractName !== dc.contractName ? (warnDifferentContractType(fetchState, registeringContract, dcWithStartBlock), false) : false
+              ) : true;
             if (shouldUpdate) {
               earliestRegisteringEventBlockNumber = Primitive_int.min(earliestRegisteringEventBlockNumber, dcWithStartBlock_effectiveStartBlock);
               Utils.Dict.getOrInsertEmptyDict(registeringContractsByContract, dc.contractName)[dc.address] = dcWithStartBlock;
@@ -898,7 +885,7 @@ function registerDynamicContracts(fetchState, items) {
       Object.assign(newIndexingAddresses, registeringContracts);
     }
     Object.assign(newIndexingAddresses, noEventsAddresses);
-    let optimizedPartitions = createPartitionsFromIndexingAddresses(registeringContractsByContract, fetchState.contractConfigs, dynamicContractsRef, fetchState.normalSelection, fetchState.optimizedPartitions.maxAddrInPartition, fetchState.optimizedPartitions.nextPartitionIndex + newPartitions.length | 0, mutExistingPartitions.concat(newPartitions), 0);
+    let optimizedPartitions = createPartitionsFromIndexingAddresses(registeringContractsByContract, dynamicContractsRef, fetchState.normalSelection, fetchState.optimizedPartitions.maxAddrInPartition, fetchState.optimizedPartitions.nextPartitionIndex + newPartitions.length | 0, mutExistingPartitions.concat(newPartitions), 0);
     return updateInternal(fetchState, optimizedPartitions, newIndexingAddresses, undefined, undefined, undefined);
   }
   if (!hasNoEventsUpdates) {
@@ -910,7 +897,18 @@ function registerDynamicContracts(fetchState, items) {
 }
 
 function handleQueryResult(fetchState, query, latestFetchedBlock, newItems) {
-  return updateInternal(fetchState, handleQueryResponse(fetchState.optimizedPartitions, query, fetchState.knownHeight, latestFetchedBlock), undefined, newItems.length !== 0 ? fetchState.buffer.concat(newItems) : undefined, undefined, undefined);
+  let newItems$1 = newItems.filter(item => {
+    if (item.kind !== 0) {
+      return true;
+    }
+    let filter = item.eventConfig.clientAddressFilter;
+    if (filter !== undefined) {
+      return filter(item.event, item.blockNumber, fetchState.indexingAddresses);
+    } else {
+      return true;
+    }
+  });
+  return updateInternal(fetchState, handleQueryResponse(fetchState.optimizedPartitions, query, fetchState.knownHeight, latestFetchedBlock), undefined, newItems$1.length !== 0 ? fetchState.buffer.concat(newItems$1) : undefined, undefined, undefined);
 }
 
 function startFetchingQueries(param, queries) {
@@ -1236,7 +1234,6 @@ function make$1(startBlock, endBlock, eventConfigs, addresses, maxAddrInPartitio
       let startBlock = match.startBlock;
       let match$1 = ec.startBlock;
       contractConfigs[ec.contractName] = {
-        filterByAddresses: match.filterByAddresses || ec.filterByAddresses,
         startBlock: startBlock !== undefined ? (
             match$1 !== undefined ? Primitive_int.min(startBlock, match$1) : startBlock
           ) : (
@@ -1245,7 +1242,6 @@ function make$1(startBlock, endBlock, eventConfigs, addresses, maxAddrInPartitio
       };
     } else {
       contractConfigs[ec.contractName] = {
-        filterByAddresses: ec.filterByAddresses,
         startBlock: ec.startBlock
       };
     }
@@ -1305,7 +1301,7 @@ function make$1(startBlock, endBlock, eventConfigs, addresses, maxAddrInPartitio
       return;
     }
   });
-  let optimizedPartitions = createPartitionsFromIndexingAddresses(registeringContractsByContract, contractConfigs, dynamicContracts, normalSelection, maxAddrInPartition, partitions.length, partitions, progressBlockNumber);
+  let optimizedPartitions = createPartitionsFromIndexingAddresses(registeringContractsByContract, dynamicContracts, normalSelection, maxAddrInPartition, partitions.length, partitions, progressBlockNumber);
   if (optimizedPartitions.idsInAscOrder.length === 0 && Utils.$$Array.isEmpty(onBlockConfigs)) {
     Stdlib_JsError.throwWithMessage(`Invalid configuration: Nothing to fetch on chain ` + chainId.toString() + `. ` + (`addresses=` + addresses.length.toString() + `, `) + (`eventConfigs=` + eventConfigs.length.toString() + `, `) + (`normalEventConfigs=` + normalEventConfigs.length.toString() + `. `) + `Make sure that you provided at least one contract address to index, or have events with Wildcard mode enabled, or have onBlock handlers.`);
   }
@@ -1453,7 +1449,7 @@ function rollback(fetchState, targetBlockNumber) {
       });
     }
   }
-  let optimizedPartitions = createPartitionsFromIndexingAddresses(registeringContractsByContract, fetchState.contractConfigs, fetchState.optimizedPartitions.dynamicContracts, fetchState.normalSelection, fetchState.optimizedPartitions.maxAddrInPartition, nextKeptIdRef, keptPartitions, targetBlockNumber);
+  let optimizedPartitions = createPartitionsFromIndexingAddresses(registeringContractsByContract, fetchState.optimizedPartitions.dynamicContracts, fetchState.normalSelection, fetchState.optimizedPartitions.maxAddrInPartition, nextKeptIdRef, keptPartitions, targetBlockNumber);
   return updateInternal({
     optimizedPartitions: fetchState.optimizedPartitions,
     startBlock: fetchState.startBlock,

package/src/HandlerLoader.res

@@ -115,7 +115,11 @@ let applyRegistrations = (~config: Config.t): Config.t => {
               ~eventName=ev.name,
             )
             let indexedParams = evmEv.paramsMetadata->Array.filter(p => p.indexed)
-            let {getEventFiltersOrThrow, filterByAddresses} = LogSelection.parseEventFiltersOrThrow(
+            let {
+              getEventFiltersOrThrow,
+              filterByAddresses,
+              addressFilterParamGroups,
+            } = LogSelection.parseEventFiltersOrThrow(
               ~eventFilters,
               ~sighash=evmEv.sighash,
               ~params=indexedParams->Array.map(p => p.name),
@@ -140,6 +144,7 @@ let applyRegistrations = (~config: Config.t): Config.t => {
               contractRegister,
               getEventFiltersOrThrow,
               filterByAddresses,
+              clientAddressFilter: ?EventConfigBuilder.buildAddressFilter(addressFilterParamGroups),
               dependsOnAddresses: Internal.dependsOnAddresses(~isWildcard, ~filterByAddresses),
             } :> Internal.eventConfig)
           | Svm =>

package/src/HandlerLoader.res.mjs

@@ -75,48 +75,25 @@ function applyRegistrations(config) {
             let indexedParams = ev.paramsMetadata.filter(p => p.indexed);
             let match$1 = LogSelection.parseEventFiltersOrThrow(eventFilters, ev.sighash, indexedParams.map(p => p.name), ev.contractName, chain.id, config.ecosystem.onEventBlockFilterSchema, Stdlib_Option.map(indexedParams[0], EventConfigBuilder.buildTopicGetter), Stdlib_Option.map(indexedParams[1], EventConfigBuilder.buildTopicGetter), Stdlib_Option.map(indexedParams[2], EventConfigBuilder.buildTopicGetter));
             let filterByAddresses = match$1.filterByAddresses;
-            return {
-              id: ev.id,
-              name: ev.name,
-              contractName: ev.contractName,
-              isWildcard: isWildcard,
-              filterByAddresses: filterByAddresses,
-              dependsOnAddresses: Internal.dependsOnAddresses(isWildcard, filterByAddresses),
-              handler: handler,
-              contractRegister: contractRegister,
-              paramsRawEventSchema: ev.paramsRawEventSchema,
-              simulateParamsSchema: ev.simulateParamsSchema,
-              startBlock: ev.startBlock,
-              getEventFiltersOrThrow: match$1.getEventFiltersOrThrow,
-              selectedBlockFields: ev.selectedBlockFields,
-              selectedTransactionFields: ev.selectedTransactionFields,
-              sighash: ev.sighash,
-              topicCount: ev.topicCount,
-              paramsMetadata: ev.paramsMetadata
-            };
-          case "fuel" :
-            return {
-              id: ev.id,
-              name: ev.name,
-              contractName: ev.contractName,
-              isWildcard: isWildcard,
-              filterByAddresses: ev.filterByAddresses,
-              dependsOnAddresses: Internal.dependsOnAddresses(isWildcard, false),
-              handler: handler,
-              contractRegister: contractRegister,
-              paramsRawEventSchema: ev.paramsRawEventSchema,
-              simulateParamsSchema: ev.simulateParamsSchema,
-              startBlock: ev.startBlock,
-              kind: ev.kind
-            };
-          case "svm" :
             let newrecord = {...ev};
+            newrecord.getEventFiltersOrThrow = match$1.getEventFiltersOrThrow;
             newrecord.contractRegister = contractRegister;
             newrecord.handler = handler;
-            newrecord.dependsOnAddresses = Internal.dependsOnAddresses(isWildcard, false);
+            newrecord.clientAddressFilter = EventConfigBuilder.buildAddressFilter(match$1.addressFilterParamGroups);
+            newrecord.dependsOnAddresses = Internal.dependsOnAddresses(isWildcard, filterByAddresses);
+            newrecord.filterByAddresses = filterByAddresses;
             newrecord.isWildcard = isWildcard;
             return newrecord;
+          case "fuel" :
+          case "svm" :
+            break;
         }
+        let newrecord$1 = {...ev};
+        newrecord$1.contractRegister = contractRegister;
+        newrecord$1.handler = handler;
+        newrecord$1.dependsOnAddresses = Internal.dependsOnAddresses(isWildcard, false);
+        newrecord$1.isWildcard = isWildcard;
+        return newrecord$1;
       });
       return {
         name: contract.name,

package/src/Internal.res

@@ -344,6 +344,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 +368,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?: (event, int, dict<indexingContract>) => bool,
   handler: option<handler>,
   contractRegister: option<contractRegister>,
   paramsRawEventSchema: S.schema<eventParams>,

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/TestIndexer.res

@@ -44,35 +44,42 @@ let toIndexingAddress = (dc: InternalTable.EnvioAddresses.t): Internal.indexingA
 }
 
 let handleLoad = (state: testIndexerState, ~tableName: string, ~filter: EntityFilter.t): JSON.t => {
-  let entityDict = state.entities->Dict.get(tableName)->Option.getOr(Dict.make())
-  let entityConfig = state.entityConfigs->Dict.getUnsafe(tableName)
-  let results = []
-
-  // Field values arrive as JSON from the worker boundary, so parse them
-  // with the field's schema before comparing. This properly handles
-  // bigint and BigDecimal comparisons
-  let parseLeaf = (~fieldName, ~fieldValue: unknown, ~isArray): unknown => {
-    let queryField = switch entityConfig.table->Table.queryFields->Dict.get(fieldName) {
-    | Some(queryField) => queryField
-    | None => JsError.throwWithMessage(`Field ${fieldName} not found in entity ${tableName}`)
-    }
-    fieldValue->S.convertOrThrow(isArray ? queryField.arrayFieldSchema : queryField.fieldSchema)
-  }
-  let filter = filter->EntityFilter.mapValues(~mapValue=parseLeaf)
-
-  entityDict
-  ->Dict.valuesToArray
-  ->Array.forEach(entity => {
-    // Cast entity to dict of field values (same approach as InMemoryTable)
-    let entityAsDict = entity->(Utils.magic: Internal.entity => dict<EntityFilter.FieldValue.t>)
-    if filter->EntityFilter.matches(~entity=entityAsDict) {
-      // Serialize entity back to JSON for worker thread
-      let jsonEntity = entity->S.reverseConvertToJsonOrThrow(entityConfig.schema)
-      results->Array.push(jsonEntity)->ignore
+  // Loads for non-entity tables (e.g. effect caches `envio_effect_<name>`) reach
+  // here too. TestIndexer never persists those, so there's nothing to return —
+  // an empty result makes the effect recompute instead of crashing on a missing
+  // entityConfig.
+  switch state.entityConfigs->Dict.get(tableName) {
+  | None => []->JSON.Encode.array
+  | Some(entityConfig) =>
+    let entityDict = state.entities->Dict.get(tableName)->Option.getOr(Dict.make())
+    let results = []
+
+    // Field values arrive as JSON from the worker boundary, so parse them
+    // with the field's schema before comparing. This properly handles
+    // bigint and BigDecimal comparisons
+    let parseLeaf = (~fieldName, ~fieldValue: unknown, ~isArray): unknown => {
+      let queryField = switch entityConfig.table->Table.queryFields->Dict.get(fieldName) {
+      | Some(queryField) => queryField
+      | None => JsError.throwWithMessage(`Field ${fieldName} not found in entity ${tableName}`)
+      }
+      fieldValue->S.convertOrThrow(isArray ? queryField.arrayFieldSchema : queryField.fieldSchema)
     }
-  })
+    let filter = filter->EntityFilter.mapValues(~mapValue=parseLeaf)
+
+    entityDict
+    ->Dict.valuesToArray
+    ->Array.forEach(entity => {
+      // Cast entity to dict of field values (same approach as InMemoryTable)
+      let entityAsDict = entity->(Utils.magic: Internal.entity => dict<EntityFilter.FieldValue.t>)
+      if filter->EntityFilter.matches(~entity=entityAsDict) {
+        // Serialize entity back to JSON for worker thread
+        let jsonEntity = entity->S.reverseConvertToJsonOrThrow(entityConfig.schema)
+        results->Array.push(jsonEntity)->ignore
+      }
+    })
 
-  results->JSON.Encode.array
+    results->JSON.Encode.array
+  }
 }
 
 let handleWriteBatch = (

package/src/TestIndexer.res.mjs

@@ -33,8 +33,11 @@ function toIndexingAddress(dc) {
 }
 
 function handleLoad(state, tableName, filter) {
-  let entityDict = Stdlib_Option.getOr(state.entities[tableName], {});
   let entityConfig = state.entityConfigs[tableName];
+  if (entityConfig === undefined) {
+    return [];
+  }
+  let entityDict = Stdlib_Option.getOr(state.entities[tableName], {});
   let results = [];
   let parseLeaf = (fieldName, fieldValue, isArray) => {
     let queryField = Table.queryFields(entityConfig.table)[fieldName];

package/src/sources/HyperSyncSource.res

@@ -167,9 +167,9 @@ let make = (
   let apiToken = switch apiToken {
   | Some(token) => token
   | None =>
-    JsError.throwWithMessage(`An API token is required for using HyperSync as a data-source.
+    JsError.throwWithMessage(`An Envio API token is required for using HyperSync as a data-source.
 Set the ENVIO_API_TOKEN environment variable in your .env file.
-Learn more or get a free API token at: https://envio.dev/app/api-tokens`)
+Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`)
   }
 
   let client = switch HyperSyncClient.make(

package/src/sources/HyperSyncSource.res.mjs

@@ -113,9 +113,9 @@ function make(param) {
   let chain = param.chain;
   let name = "HyperSync";
   let getSelectionConfig = memoGetSelectionConfig(chain);
-  let apiToken$1 = apiToken !== undefined ? apiToken : Stdlib_JsError.throwWithMessage(`An API token is required for using HyperSync as a data-source.
+  let apiToken$1 = apiToken !== undefined ? apiToken : Stdlib_JsError.throwWithMessage(`An Envio API token is required for using HyperSync as a data-source.
 Set the ENVIO_API_TOKEN environment variable in your .env file.
-Learn more or get a free API token at: https://envio.dev/app/api-tokens`);
+Learn more or get a free Envio API token at: https://envio.dev/app/api-tokens`);
   let client;
   try {
     client = HyperSyncClient.make(endpointUrl, apiToken$1, param.clientTimeoutMillis, param.allEventParams, !param.lowercaseAddresses, param.serializationFormat, param.enableQueryCaching, undefined, undefined, undefined, param.logLevel);