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

package/src/FetchState.res

@@ -9,18 +9,27 @@ type blockNumberAndLogIndex = {blockNumber: int, logIndex: int}
 
 type selection = {
   onEventRegistrations: array<Internal.onEventRegistration>,
+  // Whether the partition's queries are built from its own address list
+  // (server-side address filtering). This is the *partition* property; not to
+  // be confused with the per-registration `Internal.onEventRegistration.dependsOnAddresses`.
   dependsOnAddresses: bool,
+  // Contract names this query fetches address-free even though their
+  // registrations depend on addresses. The source passes these to the client so
+  // their log selections carry no server-side address filter; the client then
+  // gates each item against the chain's address store instead of the
+  // partition's set. Absent for normal partitions.
+  clientFilteredContracts?: array<string>,
 }
 
 type pendingQuery = {
   fromBlock: int,
   toBlock: option<int>,
   isChunk: bool,
-  // Items this in-flight query is targeting (server maxNumLogs-style cap).
-  itemsTarget: int,
-  // Estimated items this in-flight query will actually return (no headroom),
-  // carried from the query so the shared buffer budget can account for what's
-  // already being fetched without the cap's safety margin inflating it.
+  // Server maxNumLogs-style cap for this in-flight query. None for bounded
+  // chunk/gap-fill queries, which send no cap (their toBlock is the bound).
+  itemsTarget: option<int>,
+  // Estimated items this in-flight query will return, carried from the query so
+  // the shared buffer budget can account for what's already being fetched.
   itemsEst: int,
   // Stores latestFetchedBlock when query completes. Only needed to persist
   // timestamp while earlier queries are still pending before updating
@@ -40,10 +49,13 @@ type partition = {
   // which added all its events to the queue
   latestFetchedBlock: blockNumberAndTimestamp,
   selection: selection,
-  addressesByContractName: dict<array<Address.t>>,
+  // The partition's slice of the chain's address index. Ordered by
+  // (effectiveStartBlock, address) inside Rust, so a partition layout is a pure
+  // function of which addresses it holds — not of the order they arrived in.
+  addresses: AddressSet.t,
   mergeBlock: option<int>,
   // When set, partition indexes a single dynamic contract type.
-  // The addressesByContractName must contain only addresses for this contract.
+  // `addresses` must then contain only addresses for this contract.
   dynamicContract: option<string>,
   // Mutated in place and shared across fetchState versions (updateInternal
   // copies the record, not this array): startFetchingQueries inserts,
@@ -72,44 +84,29 @@ type query = {
   fromBlock: int,
   toBlock: option<int>,
   isChunk: bool,
-  // Items this query targets: the server-side maxNumLogs-style cap, sized
-  // with headroom (chunkItemsMultiplier) so a denser-than-expected range
-  // doesn't truncate the response.
-  itemsTarget: int,
-  // Expected items without headroom: density × the query's block range for a
-  // known-density partition, the query's budget share otherwise. This is the
-  // unit the chain's per-tick budget is reserved/consumed in — reserving the
-  // headroomed cap instead would throttle the pipeline by the safety margin.
+  // Server-side maxNumLogs-style cap. Some only for open-ended probes, whose
+  // range isn't otherwise bounded; None for bounded chunk/gap-fill queries,
+  // whose toBlock already bounds the response so a cap would only self-truncate
+  // (worse under client-side address filtering, which counts filtered-out items
+  // toward the cap).
+  itemsTarget: option<int>,
+  // Density × the query's block range for a known-density partition, the
+  // query's budget share otherwise. This is the unit the chain's per-tick
+  // budget is reserved/consumed in and that sizes every query.
   itemsEst: int,
   selection: selection,
-  addressesByContractName: dict<array<Address.t>>,
+  addresses: AddressSet.t,
 }
 
-// Invert addressesByContractName into address→contractName for log-ownership
-// routing. 1:1 today (each address belongs to one contract), so no key
-// collisions. Memoized on the addressesByContractName object so a partition's
-// many responses share one derivation and a large factory never rebuilds the
-// whole index; sound because the dict is immutable after construction (every
-// mutation produces a new dict).
-let deriveContractNameByAddress: dict<array<Address.t>> => dict<
-  string,
-> = Utils.WeakMap.memoize(addressesByContractName => {
-  let result = Dict.make()
-  addressesByContractName->Utils.Dict.forEachWithKey((addresses, contractName) => {
-    for i in 0 to addresses->Array.length - 1 {
-      result->Dict.set(addresses->Array.getUnsafe(i)->Address.toString, contractName)
-    }
-  })
-  result
-})
+let withAddresses = (p: partition, addresses: AddressSet.t) => {...p, addresses}
 
-// itemsTarget for a query over [fromBlock, toBlock] at the given event density
+// itemsEst for a query over [fromBlock, toBlock] at the given event density
 // (items/block). toBlock None is the open-ended tail, capped at
 // chainTargetBlock — the soft per-tick horizon the owning chain wants to reach
 // (see getNextQuery).
 let densityItemsTarget = (~density, ~fromBlock, ~toBlock, ~chainTargetBlock) => {
-  // Floor at 1: the reservation must equal the server-side cap SourceManager
-  // sends, and a 0 cap would ask the backend for nothing.
+  // Floor at 1: this is the budget reservation, and for a probe also its server
+  // cap — a 0 cap would ask the backend for nothing.
   Pervasives.max(
     1,
     ((toBlock->Option.getOr(chainTargetBlock) - fromBlock + 1)->Int.toFloat *. density)
@@ -159,6 +156,12 @@ module OptimizedPartitions = {
     // Tracks all contract names that have been dynamically added.
     // Never reset - used to determine when to split existing partitions.
     dynamicContracts: Utils.Set.t<string>,
+    // Contract names switched to client-side address filtering once their
+    // registered address count crossed the server-side threshold. Sticky for
+    // the run: their addresses live only in the index, their events are fetched
+    // by the single address-free partition, and new dynamic addresses get a
+    // bounded backfill up to its frontier instead of a standing partition.
+    clientFilteredContracts: Utils.Set.t<string>,
   }
 
   @inline
@@ -184,10 +187,7 @@ module OptimizedPartitions = {
     ~maxAddrInPartition: int,
     ~nextPartitionIndexRef: ref<int>,
   ) => {
-    let combinedAddresses =
-      p1.addressesByContractName
-      ->Dict.getUnsafe(contractName)
-      ->Array.concat(p2.addressesByContractName->Dict.getUnsafe(contractName))
+    let combinedAddresses = p1.addresses->AddressSet.merge(p2.addresses)
 
     let p1Below = p1.latestFetchedBlock.blockNumber < potentialMergeBlock
     let p2Below = p2.latestFetchedBlock.blockNumber < potentialMergeBlock
@@ -224,7 +224,7 @@ module OptimizedPartitions = {
         selection: p1.selection,
         latestFetchedBlock: {blockNumber: potentialMergeBlock, blockTimestamp: 0},
         mergeBlock: None,
-        addressesByContractName: Dict.make(), // set below
+        addresses: p1.addresses, // replaced below
         mutPendingQueries: [],
         sourceRangeCapacity: minRange,
         prevSourceRangeCapacity: minRange,
@@ -234,29 +234,28 @@ module OptimizedPartitions = {
     }
 
     // Apply address split on the continuing partition
-    if combinedAddresses->Array.length > maxAddrInPartition {
-      let addressesFull = combinedAddresses->Array.slice(~start=0, ~end=maxAddrInPartition)
-      let addressesRest = combinedAddresses->Array.slice(~start=maxAddrInPartition)
-      let abcFull = Dict.make()
-      abcFull->Dict.set(contractName, addressesFull)
-      let abcRest = Dict.make()
-      abcRest->Dict.set(contractName, addressesRest)
-      completed->Array.push({...continuingBase, addressesByContractName: abcFull})->ignore
+    if combinedAddresses->AddressSet.size > maxAddrInPartition {
+      completed
+      ->Array.push(
+        continuingBase->withAddresses(
+          combinedAddresses->AddressSet.slice(~offset=0, ~limit=Some(maxAddrInPartition)),
+        ),
+      )
+      ->ignore
       let restId = nextPartitionIndexRef.contents->Int.toString
       nextPartitionIndexRef := nextPartitionIndexRef.contents + 1
       completed
       ->Array.push({
-        ...continuingBase,
+        ...continuingBase->withAddresses(
+          combinedAddresses->AddressSet.slice(~offset=maxAddrInPartition, ~limit=None),
+        ),
         id: restId,
-        addressesByContractName: abcRest,
         mutPendingQueries: [],
       })
       ->ignore
       completed
     } else {
-      let abc = Dict.make()
-      abc->Dict.set(contractName, combinedAddresses)
-      completed->Array.push({...continuingBase, addressesByContractName: abc})->ignore
+      completed->Array.push(continuingBase->withAddresses(combinedAddresses))->ignore
       completed
     }
   }
@@ -283,6 +282,7 @@ module OptimizedPartitions = {
     ~maxAddrInPartition,
     ~nextPartitionIndex: int,
     ~dynamicContracts: Utils.Set.t<string>,
+    ~clientFilteredContracts: Utils.Set.t<string>,
   ) => {
     let newPartitions = []
     let mergingPartitions = Dict.make()
@@ -303,7 +303,7 @@ module OptimizedPartitions = {
       {mergeBlock: Some(_)} =>
         newPartitions->Array.push(p)->ignore
       | {dynamicContract: Some(contractName)} =>
-        let pAddressesCount = p.addressesByContractName->Dict.getUnsafe(contractName)->Array.length
+        let pAddressesCount = p.addresses->AddressSet.countFor(contractName)
         // Compute merge block: last pending query's toBlock, or lfb if idle
         let potentialMergeBlock = switch p.mutPendingQueries->Utils.Array.last {
         | Some({isChunk: true, toBlock: Some(toBlock)}) => Some(toBlock)
@@ -416,6 +416,7 @@ module OptimizedPartitions = {
       maxAddrInPartition,
       nextPartitionIndex: nextPartitionIndexRef.contents,
       dynamicContracts,
+      clientFilteredContracts,
     }
   }
 
@@ -467,14 +468,37 @@ module OptimizedPartitions = {
     }
   }
 
-  let handleQueryResponse = (
+  let rec handleQueryResponse = (
+    optimizedPartitions: t,
+    ~query,
+    ~knownHeight,
+    ~itemsCount,
+    ~latestFetchedBlock: blockNumberAndTimestamp,
+  ) =>
+    switch optimizedPartitions.entities->Utils.Dict.dangerouslyGetNonOption(query.partitionId) {
+    // The partition was absorbed into the address-free client-filtered partition
+    // while this query was in flight. Its items are still merged into the buffer
+    // by the caller (and deduped); there's no partition bookkeeping left to do,
+    // and its reservation is released by ChainState regardless.
+    | None => optimizedPartitions
+    | Some(p) =>
+      optimizedPartitions->handleQueryResponseForPartition(
+        ~p,
+        ~query,
+        ~knownHeight,
+        ~itemsCount,
+        ~latestFetchedBlock,
+      )
+    }
+
+  and handleQueryResponseForPartition = (
     optimizedPartitions: t,
+    ~p: partition,
     ~query,
     ~knownHeight,
     ~itemsCount,
     ~latestFetchedBlock: blockNumberAndTimestamp,
   ) => {
-    let p = optimizedPartitions->getOrThrow(~partitionId=query.partitionId)
     let mutEntities = optimizedPartitions.entities->Utils.Dict.shallowCopy
 
     // Mark query as fetched
@@ -508,8 +532,12 @@ module OptimizedPartitions = {
           if latestFetchedBlock.blockNumber < queryToBlock {
             // Partial response is direct capacity evidence — unless it was
             // truncated by our own itemsTarget cap: that reflects the
-            // reservation we asked for, not what the server could return.
-            itemsCount < query.itemsTarget
+            // reservation we asked for, not what the server could return. A
+            // capless bounded query can only have been truncated by the source.
+            switch query.itemsTarget {
+            | None => true
+            | Some(itemsTarget) => itemsCount < itemsTarget
+            }
           } else {
             // A full response updates only when the query's intended range
             // covers at least the partition's current chunk range — meaning it
@@ -549,6 +577,7 @@ module OptimizedPartitions = {
         ~maxAddrInPartition=optimizedPartitions.maxAddrInPartition,
         ~nextPartitionIndex=optimizedPartitions.nextPartitionIndex,
         ~dynamicContracts=optimizedPartitions.dynamicContracts,
+        ~clientFilteredContracts=optimizedPartitions.clientFilteredContracts,
       )
     } else {
       let updatedMainPartition = {
@@ -598,6 +627,7 @@ module OptimizedPartitions = {
           ~maxAddrInPartition=optimizedPartitions.maxAddrInPartition,
           ~nextPartitionIndex=optimizedPartitions.nextPartitionIndex,
           ~dynamicContracts=optimizedPartitions.dynamicContracts,
+          ~clientFilteredContracts=optimizedPartitions.clientFilteredContracts,
         )
       }
     }
@@ -617,8 +647,6 @@ type t = {
   startBlock: int,
   endBlock: option<int>,
   normalSelection: selection,
-  // By contract name
-  contractConfigs: dict<IndexingAddresses.contractConfig>,
   // Not used for logic - only metadata
   chainId: int,
   // The block number of the latest block which was added to the queue
@@ -638,6 +666,10 @@ type t = {
   onBlockRegistrations: array<Internal.onBlockRegistration>,
   knownHeight: int,
   firstEventBlock: option<int>,
+  // Per-contract registered-address count past which a dynamic contract is
+  // switched to client-side filtering. None disables the switch, leaving every
+  // contract filtered server-side.
+  clientFilterAddressThreshold: option<int>,
 }
 
 @inline
@@ -892,7 +924,6 @@ let updateInternal = (
   let updatedFetchState = {
     startBlock: fetchState.startBlock,
     endBlock: fetchState.endBlock,
-    contractConfigs: fetchState.contractConfigs,
     normalSelection: fetchState.normalSelection,
     chainId: fetchState.chainId,
     onBlockRegistrations: fetchState.onBlockRegistrations,
@@ -907,43 +938,238 @@ let updateInternal = (
     | blockItems => base->mergeIntoBuffer(blockItems)
     },
     firstEventBlock: fetchState.firstEventBlock,
+    clientFilterAddressThreshold: fetchState.clientFilterAddressThreshold,
   }
 
   updatedFetchState
 }
 
-let warnDifferentContractType = (
-  fetchState,
-  ~existingContract: indexingAddress,
-  ~dc: indexingAddress,
+// Move a contract to client-side address filtering, recording why.
+let addClientFilteredContract = (
+  clientFilteredContracts: Utils.Set.t<string>,
+  ~contractName,
+  ~chainId,
+  ~addressCount,
+  ~threshold,
 ) => {
-  let logger = Logging.createChild(
+  clientFilteredContracts->Utils.Set.add(contractName)->ignore
+  Logging.createChild(
     ~params={
-      "chainId": fetchState.chainId,
-      "contractAddress": dc.address->Address.toString,
-      "existingContractType": existingContract.contractName,
-      "newContractType": dc.contractName,
+      "chainId": chainId,
+      "contractName": contractName,
+      "addressCount": addressCount,
+      "threshold": threshold,
     },
+  )->Logging.childTrace(
+    "Switching contract to client-side address filtering: registered address count crossed the server-side threshold.",
   )
-  logger->Logging.childWarn(`Skipping contract registration: Contract address is already registered for one contract and cannot be registered for another contract.`)
 }
 
-let addressesByContractNameCount = (addressesByContractName: dict<array<Address.t>>) => {
-  let numAddresses = ref(0)
-  addressesByContractName->Utils.Dict.forEach(addresses => {
-    numAddresses := numAddresses.contents + addresses->Array.length
-  })
-  numAddresses.contents
-}
+// The block a partition will have fetched to once everything on its pending
+// queue lands — not the block it has fetched to now. A backfill has to reach it
+// rather than the frontier: a query that was routed before this batch's
+// addresses reached the address store carries no events for them, yet it still
+// advances the frontier over its range on arrival, and nothing else would ever
+// refetch it. An in-flight open-ended query has no toBlock of its own; it can't
+// return past the chain's known height, so that bounds it.
+let claimedFetchedBlock = (p: partition, ~knownHeight) =>
+  p.mutPendingQueries->Array.reduce(p.latestFetchedBlock.blockNumber, (max, q) =>
+    Pervasives.max(
+      max,
+      switch q.fetchedBlock {
+      | Some({blockNumber}) => blockNumber
+      | None => q.toBlock->Option.getOr(knownHeight)
+      },
+    )
+  )
+
+// Fold every client-filtered contract's server-side partitions into client-side
+// fetching without tearing down established state:
+// - The standing address-free partition (no mergeBlock) keeps its id, frontier,
+//   in-flight queries and learned density. Only when a newly-switched contract
+//   must be added does its selection change — under a fresh id, so in-flight
+//   responses built from the old selection are orphaned instead of advancing
+//   the frontier past ranges the new contract wasn't fetched for.
+// - Partitions absorbed below the standing partition's claimed block
+//   (single-contract dynamic partitions and config partitions all of whose
+//   contracts are client-filtered, plus any prior backfill) become one bounded
+//   backfill partition covering [their min frontier, that claimed block]:
+//   getNextQuery caps its queries at mergeBlock and handleQueryResponse deletes
+//   it on arrival. The overlap it re-delivers is deduped by mergeIntoBuffer, and
+//   the re-fetch doubles as history for freshly registered addresses: events
+//   dropped before the address was registered now pass the address gate.
+// - A partition mixing client-filtered and server-side contracts stays,
+//   stripped of the client-filtered contracts' addresses — the address-free
+//   partition covers those logs, so fetching them server-side too would only
+//   produce duplicates. Its frontier bounds the backfill from below so the
+//   stripped contracts lose no range.
+//
+// Registrations come from the address-free partitions plus `normalSelection`
+// filtered to client-filtered contracts, so coverage never depends on which
+// partitions happened to be absorbed (a stripped contract may have no
+// absorbable partition at all).
+let collapseClientFilteredContracts = (
+  partitions: array<partition>,
+  ~clientFilteredContracts: Utils.Set.t<string>,
+  ~normalSelection: selection,
+  ~nextPartitionIndexRef: ref<int>,
+  ~addressStore: AddressStore.t,
+  ~knownHeight: int,
+) => {
+  if clientFilteredContracts->Utils.Set.size === 0 {
+    partitions
+  } else {
+    let kept = []
+    let standingRef = ref(None)
+    let backfills = []
+    let absorbedPartitions = []
+    let strippedFrontiers = []
+
+    partitions->Array.forEach(p =>
+      switch p {
+      | {selection: {dependsOnAddresses: false}, mergeBlock: None}
+        if standingRef.contents->Option.isNone =>
+        standingRef := Some(p)
+      | {selection: {dependsOnAddresses: false}, mergeBlock: Some(_)} =>
+        backfills->Array.push(p)->ignore
+      | {selection: {dependsOnAddresses: false}} => absorbedPartitions->Array.push(p)->ignore
+      | _ =>
+        let contractNames = p.addresses->AddressSet.contractNames
+        let serverSideNames =
+          contractNames->Array.filter(c => !(clientFilteredContracts->Utils.Set.has(c)))
+        if serverSideNames->Array.length === contractNames->Array.length {
+          kept->Array.push(p)->ignore
+        } else if serverSideNames->Utils.Array.isEmpty {
+          absorbedPartitions->Array.push(p)->ignore
+        } else {
+          strippedFrontiers->Array.push(p.latestFetchedBlock)->ignore
+          kept
+          ->Array.push(p->withAddresses(p.addresses->AddressSet.filterByContracts(serverSideNames)))
+          ->ignore
+        }
+      }
+    )
 
-let addressesByContractNameGetAll = (addressesByContractName: dict<array<Address.t>>) => {
-  let all = []
-  addressesByContractName->Utils.Dict.forEach(addresses => {
-    for idx in 0 to addresses->Array.length - 1 {
-      all->Array.push(addresses->Array.getUnsafe(idx))->ignore
+    let selectionChanged = switch standingRef.contents {
+    | Some(standing) =>
+      standing.selection.clientFilteredContracts->Option.mapOr(0, Array.length) !==
+        clientFilteredContracts->Utils.Set.size
+    | None => true
     }
-  })
-  all
+
+    if (
+      absorbedPartitions->Utils.Array.isEmpty &&
+      strippedFrontiers->Utils.Array.isEmpty &&
+      !selectionChanged
+    ) {
+      // Nothing to fold in and no newly-switched contract: leave the standing
+      // partition (and any in-progress backfill) untouched.
+      partitions
+    } else {
+      let minFrontierRef: ref<option<blockNumberAndTimestamp>> = ref(None)
+      let considerFrontier = (b: blockNumberAndTimestamp) =>
+        switch minFrontierRef.contents {
+        | Some(m) if m.blockNumber <= b.blockNumber => ()
+        | _ => minFrontierRef := Some(b)
+        }
+      absorbedPartitions->Array.forEach(p => considerFrontier(p.latestFetchedBlock))
+      backfills->Array.forEach(p => considerFrontier(p.latestFetchedBlock))
+      strippedFrontiers->Array.forEach(considerFrontier)
+
+      let regByIndex = Dict.make()
+      let addRegs = (regs: array<Internal.onEventRegistration>) =>
+        regs->Array.forEach(reg => regByIndex->Dict.set(reg.index->Int.toString, reg))
+      switch standingRef.contents {
+      | Some(standing) => addRegs(standing.selection.onEventRegistrations)
+      | None => ()
+      }
+      absorbedPartitions->Array.forEach(p =>
+        if !p.selection.dependsOnAddresses {
+          addRegs(p.selection.onEventRegistrations)
+        }
+      )
+      addRegs(
+        normalSelection.onEventRegistrations->Array.filter(reg =>
+          clientFilteredContracts->Utils.Set.has(reg.eventConfig.contractName)
+        ),
+      )
+      let newSelection = {
+        dependsOnAddresses: false,
+        onEventRegistrations: regByIndex->Dict.valuesToArray,
+        clientFilteredContracts: clientFilteredContracts->Utils.Set.toArray,
+      }
+
+      switch standingRef.contents {
+      | None =>
+        // First switch: no standing partition to preserve, so create it at the
+        // min frontier directly — the whole range above is unfetched for the
+        // client-filtered side anyway.
+        switch minFrontierRef.contents {
+        | None => kept
+        | Some(minFrontier) =>
+          let minRange = getMinQueryRange(absorbedPartitions)
+          let id = nextPartitionIndexRef.contents->Int.toString
+          nextPartitionIndexRef := nextPartitionIndexRef.contents + 1
+          kept
+          ->Array.push({
+            id,
+            latestFetchedBlock: minFrontier,
+            selection: newSelection,
+            addresses: addressStore->AddressStore.emptySet,
+            mergeBlock: None,
+            dynamicContract: None,
+            mutPendingQueries: [],
+            sourceRangeCapacity: minRange,
+            prevSourceRangeCapacity: minRange,
+            eventDensity: None,
+            latestSourceRangeCapacityUpdateBlock: 0,
+          })
+          ->ignore
+          kept
+        }
+      | Some(standing) =>
+        let standingOut = if selectionChanged {
+          let id = nextPartitionIndexRef.contents->Int.toString
+          nextPartitionIndexRef := nextPartitionIndexRef.contents + 1
+          {...standing, id, selection: newSelection, mutPendingQueries: []}
+        } else {
+          standing
+        }
+        kept->Array.push(standingOut)->ignore
+        // Read off standingOut, not standing: a selection change orphans the
+        // in-flight queries (fresh id, empty queue), so there the frontier is
+        // all the partition will ever claim.
+        let catchUpToBlock = standingOut->claimedFetchedBlock(~knownHeight)
+        switch minFrontierRef.contents {
+        | Some(minFrontier) if minFrontier.blockNumber < catchUpToBlock =>
+          let id = nextPartitionIndexRef.contents->Int.toString
+          nextPartitionIndexRef := nextPartitionIndexRef.contents + 1
+          kept
+          ->Array.push({
+            id,
+            latestFetchedBlock: minFrontier,
+            selection: newSelection,
+            addresses: addressStore->AddressStore.emptySet,
+            mergeBlock: Some(catchUpToBlock),
+            dynamicContract: None,
+            mutPendingQueries: [],
+            // Same query shape as the standing partition, so inherit its
+            // learned range and density instead of probing from scratch.
+            sourceRangeCapacity: standing.sourceRangeCapacity,
+            prevSourceRangeCapacity: standing.prevSourceRangeCapacity,
+            eventDensity: standing.eventDensity,
+            latestSourceRangeCapacityUpdateBlock: 0,
+          })
+          ->ignore
+        // An absorbed frontier at/above the claimed block needs no backfill:
+        // nothing has fetched past there yet, so the standing partition still
+        // covers it going forward.
+        | _ => ()
+        }
+        kept
+      }
+    }
+  }
 }
 
 /**
@@ -953,14 +1179,19 @@ Phase 2: Merge non-dynamic partitions together to reduce unnecessary concurrency
 Returns OptimizedPartitions.t directly.
 (Dynamic partitions are merged by OptimizedPartitions.make automatically)
 */
-let createPartitionsFromIndexingAddresses = (
-  ~registeringContractsByContract: dict<dict<indexingAddress>>,
+let createPartitions = (
+  // One set per contract, holding the addresses that still need a partition:
+  // a batch's fresh registrations, or the survivors of a rolled-back partition.
+  ~registeringSetsByContract: dict<AddressSet.t>,
+  ~addressStore: AddressStore.t,
   ~dynamicContracts: Utils.Set.t<string>,
+  ~clientFilteredContracts: Utils.Set.t<string>,
   ~normalSelection: selection,
   ~maxAddrInPartition: int,
   ~nextPartitionIndex: int,
   ~existingPartitions: array<partition>,
   ~progressBlockNumber: int,
+  ~knownHeight: int,
 ): // Floor for latestFetchedBlock (use progressBlockNumber from make, or 0 for registerDynamicContracts)
 OptimizedPartitions.t => {
   let nextPartitionIndexRef = ref(nextPartitionIndex)
@@ -969,90 +1200,67 @@ OptimizedPartitions.t => {
   let dynamicPartitions = []
   let nonDynamicPartitions = []
 
-  let contractNames = registeringContractsByContract->Dict.keysToArray
+  let contractNames = registeringSetsByContract->Dict.keysToArray
   for cIdx in 0 to contractNames->Array.length - 1 {
     let contractName = contractNames->Array.getUnsafe(cIdx)
-    let registeringContracts = registeringContractsByContract->Dict.getUnsafe(contractName)
-    let addresses =
-      registeringContracts->Dict.keysToArray->(Utils.magic: array<string> => array<Address.t>)
+    let contractSet = registeringSetsByContract->Dict.getUnsafe(contractName)
 
     let isDynamic = dynamicContracts->Utils.Set.has(contractName)
     let partitions = isDynamic ? dynamicPartitions : nonDynamicPartitions
 
-    let byStartBlock = Dict.make()
-    for jdx in 0 to addresses->Array.length - 1 {
-      let address = addresses->Array.getUnsafe(jdx)
-      let indexingContract = registeringContracts->Dict.getUnsafe(address->Address.toString)
-      byStartBlock->Utils.Dict.push(indexingContract.effectiveStartBlock->Int.toString, address)
-    }
-
-    // Will be in ASC order by JS spec
-    let ascKeys = byStartBlock->Dict.keysToArray
-    let initialKey = ascKeys->Utils.Array.firstUnsafe
-
-    let startBlockRef = ref(initialKey->Int.fromString->Option.getUnsafe)
-    let addressesRef = ref(byStartBlock->Dict.getUnsafe(initialKey))
-
-    for idx in 0 to ascKeys->Array.length - 1 {
-      let maybeNextStartBlockKey =
-        ascKeys->Array.getUnsafe(idx + 1)->(Utils.magic: string => option<string>)
-
-      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 (the event's clientAddressFilter for address-valued
-          // params).
-          if shouldJoinCurrentStartBlock {
-            addressesRef :=
-              addressesRef.contents->Array.concat(byStartBlock->Dict.getUnsafe(nextStartBlockKey))
-            false
-          } else {
-            true
-          }
+    // A set is ordered by effectiveStartBlock, so its start-block groups are
+    // ascending and each group's addresses are a contiguous slice.
+    let groups = contractSet->AddressSet.startBlockGroups
+    let offsetRef = ref(0)
+    let groupIdx = ref(0)
+    while groupIdx.contents < groups->Array.length {
+      let startBlock = (groups->Array.getUnsafe(groupIdx.contents)).startBlock
+      // Addresses with different start blocks within range share a partition;
+      // events before each address's effectiveStartBlock are dropped by the
+      // source's address gate.
+      let countRef = ref(0)
+      let nextIdx = ref(groupIdx.contents)
+      let joining = ref(true)
+      while joining.contents && nextIdx.contents < groups->Array.length {
+        let group = groups->Array.getUnsafe(nextIdx.contents)
+        if group.startBlock - startBlock < OptimizedPartitions.tooFarBlockRange {
+          countRef := countRef.contents + group.count
+          nextIdx := nextIdx.contents + 1
+        } else {
+          joining := false
         }
       }
 
-      if shouldAllocateNewPartition {
-        let latestFetchedBlock = {
-          blockNumber: Pervasives.max(startBlockRef.contents - 1, progressBlockNumber),
-          blockTimestamp: 0,
-        }
-        while addressesRef.contents->Array.length > 0 {
-          let pAddresses = addressesRef.contents->Array.slice(~start=0, ~end=maxAddrInPartition)
-          addressesRef.contents = addressesRef.contents->Array.slice(~start=maxAddrInPartition)
-
-          let addressesByContractName = Dict.make()
-          addressesByContractName->Dict.set(contractName, pAddresses)
-          partitions->Array.push({
-            id: nextPartitionIndexRef.contents->Int.toString,
-            latestFetchedBlock,
-            selection: normalSelection,
-            dynamicContract: isDynamic ? Some(contractName) : None,
-            addressesByContractName,
-            mergeBlock: None,
-            mutPendingQueries: [],
-            sourceRangeCapacity: 0,
-            prevSourceRangeCapacity: 0,
-            eventDensity: None,
-            latestSourceRangeCapacityUpdateBlock: 0,
-          })
-          nextPartitionIndexRef := nextPartitionIndexRef.contents + 1
-        }
-
-        switch maybeNextStartBlockKey {
-        | None => ()
-        | Some(nextStartBlockKey) => {
-            startBlockRef := nextStartBlockKey->Int.fromString->Option.getUnsafe
-            addressesRef := byStartBlock->Dict.getUnsafe(nextStartBlockKey)
-          }
-        }
+      let latestFetchedBlock = {
+        blockNumber: Pervasives.max(startBlock - 1, progressBlockNumber),
+        blockTimestamp: 0,
+      }
+      let remainingRef = ref(countRef.contents)
+      let chunkOffsetRef = ref(offsetRef.contents)
+      while remainingRef.contents > 0 {
+        let take = Pervasives.min(remainingRef.contents, maxAddrInPartition)
+        let pAddresses =
+          contractSet->AddressSet.slice(~offset=chunkOffsetRef.contents, ~limit=Some(take))
+        partitions->Array.push({
+          id: nextPartitionIndexRef.contents->Int.toString,
+          latestFetchedBlock,
+          selection: normalSelection,
+          dynamicContract: isDynamic ? Some(contractName) : None,
+          addresses: pAddresses,
+          mergeBlock: None,
+          mutPendingQueries: [],
+          sourceRangeCapacity: 0,
+          prevSourceRangeCapacity: 0,
+          eventDensity: None,
+          latestSourceRangeCapacityUpdateBlock: 0,
+        })
+        nextPartitionIndexRef := nextPartitionIndexRef.contents + 1
+        chunkOffsetRef := chunkOffsetRef.contents + take
+        remainingRef := remainingRef.contents - take
       }
+
+      offsetRef := offsetRef.contents + countRef.contents
+      groupIdx := nextIdx.contents
     }
   }
 
@@ -1072,29 +1280,14 @@ OptimizedPartitions.t => {
       let currentPBlock = currentP.latestFetchedBlock.blockNumber
       let nextPBlock = nextP.latestFetchedBlock.blockNumber
 
-      // Compute total count WITHOUT mutating any arrays
-      let totalCount =
-        currentP.addressesByContractName->addressesByContractNameCount +
-          nextP.addressesByContractName->addressesByContractNameCount
+      let totalCount = currentP.addresses->AddressSet.size + nextP.addresses->AddressSet.size
 
       if totalCount > maxAddrInPartition {
         // Exceeds address limit - don't merge, keep partitions separate
         mergedNonDynamic->Array.push(currentP)->ignore
         currentPRef := nextP
       } else {
-        // Build merged addresses using Array.concat (non-mutating)
-        let mergedAddresses = nextP.addressesByContractName->Utils.Dict.shallowCopy
-        let currentContractNames = currentP.addressesByContractName->Dict.keysToArray
-        for jdx in 0 to currentContractNames->Array.length - 1 {
-          let cn = currentContractNames->Array.getUnsafe(jdx)
-          let currentAddrs = currentP.addressesByContractName->Dict.getUnsafe(cn)
-          switch mergedAddresses->Utils.Dict.dangerouslyGetNonOption(cn) {
-          | Some(existingAddrs) =>
-            // Use concat (non-mutating) to avoid corrupting nextP's arrays
-            mergedAddresses->Dict.set(cn, existingAddrs->Array.concat(currentAddrs))
-          | None => mergedAddresses->Dict.set(cn, currentAddrs)
-          }
-        }
+        let mergedAddresses = nextP.addresses->AddressSet.merge(currentP.addresses)
 
         let isTooFar = currentPBlock + OptimizedPartitions.tooFarBlockRange < nextPBlock
 
@@ -1106,16 +1299,10 @@ OptimizedPartitions.t => {
             mergeBlock: currentPBlock < nextPBlock ? Some(nextPBlock) : None,
           })
           ->ignore
-          currentPRef := {
-              ...nextP,
-              addressesByContractName: mergedAddresses,
-            }
+          currentPRef := nextP->withAddresses(mergedAddresses)
         } else {
           // Close: push next's addresses into current
-          currentPRef := {
-              ...currentP,
-              addressesByContractName: mergedAddresses,
-            }
+          currentPRef := currentP->withAddresses(mergedAddresses)
         }
       }
 
@@ -1127,18 +1314,37 @@ OptimizedPartitions.t => {
 
   let mergedPartitions = mergedNonDynamic->Array.concat(dynamicPartitions)
 
-  // Final step: concat existing partitions with phase 1+2 result and call OptimizedPartitions.make
+  // Final step: concat existing partitions with phase 1+2 result, collapse any
+  // client-filtered contracts into the single address-free partition, and optimize.
+  let allPartitions =
+    existingPartitions
+    ->Array.concat(mergedPartitions)
+    ->collapseClientFilteredContracts(
+      ~clientFilteredContracts,
+      ~normalSelection,
+      ~nextPartitionIndexRef,
+      ~addressStore,
+      ~knownHeight,
+    )
   OptimizedPartitions.make(
-    ~partitions=existingPartitions->Array.concat(mergedPartitions),
+    ~partitions=allPartitions,
     ~maxAddrInPartition,
     ~nextPartitionIndex=nextPartitionIndexRef.contents,
     ~dynamicContracts,
+    ~clientFilteredContracts,
   )
 }
 
 let registerDynamicContracts = (
   fetchState: t,
-  ~indexingAddresses: IndexingAddresses.t,
+  ~addressStore: AddressStore.t,
+  // How far an in-flight open-ended query may end up claiming. These
+  // registrations usually come out of a response that is applied right after
+  // this call, and an unbounded query can reach past the height known when it
+  // was dispatched — so the caller folds that response's own frontier and
+  // height in here. Defaults to what the fetch state knows, which is all
+  // there is to go on when no response is being applied.
+  ~claimCeiling=fetchState.knownHeight,
   // These are raw items which might have dynamic contracts received from contractRegister call.
   // Might contain duplicates which we should filter out
   items: array<Internal.item>,
@@ -1150,167 +1356,130 @@ let registerDynamicContracts = (
     )
   }
 
-  let registeringContractsByContract: dict<dict<indexingAddress>> = Dict.make()
-  let earliestRegisteringEventBlockNumber = ref(%raw(`Infinity`))
-  // Addresses registered for contracts without matching events. These are not
-  // added to partitions, but they are tracked on indexingAddresses
-  // so that later conflicting registrations are detected, and are persisted
-  // to envio_addresses so they can be picked up on restart with updated config.
-  let noEventsAddresses: dict<indexingAddress> = Dict.make()
-  // Batch-level view of all addresses registered so far (across contracts,
-  // including no-events ones), so two contracts registering the same address
-  // within one batch conflict the same way as against indexingAddresses.
-  let registeringAddresses: dict<indexingAddress> = Dict.make()
-
+  // Flatten every item's dcs into one batch, remembering where each came from
+  // so the rejected ones can be spliced back out of their item (which is what
+  // keeps them from being persisted twice).
+  let registrations: array<AddressStore.registration> = []
+  let sourceDcs: array<Internal.dcs> = []
+  let sourceIndexes: array<int> = []
   for itemIdx in 0 to items->Array.length - 1 {
-    let item = items->Array.getUnsafe(itemIdx)
-    switch item->Internal.getItemDcs {
+    switch items->Array.getUnsafe(itemIdx)->Internal.getItemDcs {
     | None => ()
     | Some(dcs) =>
-      let idx = ref(0)
-      while idx.contents < dcs->Array.length {
-        let dc = dcs->Array.getUnsafe(idx.contents)
-
-        let shouldRemove = ref(false)
-
-        switch fetchState.contractConfigs->Utils.Dict.dangerouslyGetNonOption(dc.contractName) {
-        | Some({startBlock: contractStartBlock}) =>
-          let dcWithStartBlock: indexingAddress = {
-            address: dc.address,
-            contractName: dc.contractName,
-            registrationBlock: dc.registrationBlock,
-            effectiveStartBlock: IndexingAddresses.deriveEffectiveStartBlock(
-              ~registrationBlock=dc.registrationBlock,
-              ~contractStartBlock,
-            ),
-          }
-          // Prevent registering already indexing contracts
-          switch indexingAddresses->IndexingAddresses.get(dc.address->Address.toString) {
-          | Some(existingContract) =>
-            // FIXME: Instead of filtering out duplicates,
-            // we should check the block number first.
-            // If new registration with earlier block number
-            // we should register it for the missing block range
-            if existingContract.contractName != dc.contractName {
-              fetchState->warnDifferentContractType(~existingContract, ~dc=dcWithStartBlock)
-            } else if existingContract.effectiveStartBlock > dcWithStartBlock.effectiveStartBlock {
-              let logger = Logging.createChild(
-                ~params={
-                  "chainId": fetchState.chainId,
-                  "contractAddress": dc.address->Address.toString,
-                  "existingBlockNumber": existingContract.effectiveStartBlock,
-                  "newBlockNumber": dcWithStartBlock.effectiveStartBlock,
-                },
-              )
-              logger->Logging.childWarn(`Skipping contract registration: Contract address is already registered at a later block number. Currently registration of the same contract address is not supported by Envio. Reach out to us if it's a problem for you.`)
-            }
-            shouldRemove := true
-          | None =>
-            let shouldUpdate = switch registeringAddresses->Utils.Dict.dangerouslyGetNonOption(
-              dc.address->Address.toString,
-            ) {
-            | Some(registeringContract) if registeringContract.contractName != dc.contractName =>
-              fetchState->warnDifferentContractType(
-                ~existingContract=registeringContract,
-                ~dc=dcWithStartBlock,
-              )
-              false
-            | Some(_) => // Since the DC is registered by an earlier item in the query
-              // 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 => true
-            }
-            if shouldUpdate {
-              earliestRegisteringEventBlockNumber :=
-                Pervasives.min(
-                  earliestRegisteringEventBlockNumber.contents,
-                  dcWithStartBlock.effectiveStartBlock,
-                )
-              registeringContractsByContract
-              ->Utils.Dict.getOrInsertEmptyDict(dc.contractName)
-              ->Dict.set(dc.address->Address.toString, dcWithStartBlock)
-              registeringAddresses->Dict.set(dc.address->Address.toString, dcWithStartBlock)
-            } else {
-              shouldRemove := true
-            }
-          }
-        | None =>
-          let dcAsIndexingAddress: indexingAddress = {
-            address: dc.address,
-            contractName: dc.contractName,
-            registrationBlock: dc.registrationBlock,
-            effectiveStartBlock: IndexingAddresses.deriveEffectiveStartBlock(
-              ~registrationBlock=dc.registrationBlock,
-              ~contractStartBlock=None,
-            ),
-          }
-          // Prevent duplicate logging/persistence when the same address is
-          // already tracked on fetchState, either from the db on startup or
-          // from an earlier registration in this batch.
-          switch indexingAddresses->IndexingAddresses.get(dc.address->Address.toString) {
-          | Some(existingContract) =>
-            if existingContract.contractName != dc.contractName {
-              fetchState->warnDifferentContractType(~existingContract, ~dc=dcAsIndexingAddress)
-            }
-            shouldRemove := true
-          | None =>
-            switch registeringAddresses->Utils.Dict.dangerouslyGetNonOption(
-              dc.address->Address.toString,
-            ) {
-            | Some(existingContract) =>
-              if existingContract.contractName != dc.contractName {
-                fetchState->warnDifferentContractType(~existingContract, ~dc=dcAsIndexingAddress)
-              }
-              // Otherwise already queued for persistence by an earlier item in this batch.
-              shouldRemove := true
-            | None =>
-              let logger = Logging.createChild(
-                ~params={
-                  "chainId": fetchState.chainId,
-                  "contractAddress": dc.address->Address.toString,
-                  "contractName": dc.contractName,
-                },
-              )
-              // Persist the address to the db so a future config change that
-              // adds events for this contract can pick it up on restart, but
-              // skip partition registration since there's nothing to fetch.
-              logger->Logging.childWarn(`Persisting contract registration without fetching: Contract doesn't have any events to fetch. It'll be picked up on restart if you add events for the contract.`)
-              noEventsAddresses->Dict.set(dc.address->Address.toString, dcAsIndexingAddress)
-              registeringAddresses->Dict.set(dc.address->Address.toString, dcAsIndexingAddress)
-            }
-          }
-        }
+      for dcIdx in 0 to dcs->Array.length - 1 {
+        let dc = dcs->Array.getUnsafe(dcIdx)
+        registrations
+        ->Array.push({
+          address: dc.address,
+          contractName: dc.contractName,
+          registrationBlock: dc.registrationBlock,
+        })
+        ->ignore
+        sourceDcs->Array.push(dcs)->ignore
+        sourceIndexes->Array.push(dcIdx)->ignore
+      }
+    }
+  }
 
-        if shouldRemove.contents {
-          // Remove the DC from item to prevent it from saving to the db
-          let _ = dcs->Array.splice(~start=idx.contents, ~remove=1, ~insert=[])
-          // Don't increment idx - next element shifted into current position
-        } else {
-          idx := idx.contents + 1
-        }
+  // Ids are handed out in registration order, so a cursor taken now selects
+  // exactly what this batch adds.
+  let idCursor = addressStore->AddressStore.nextId
+  // The store resolves each address against both what it already holds and the
+  // batch's own earlier entries, so two contracts claiming one address inside a
+  // single batch conflict the same way as across batches.
+  let verdicts = addressStore->AddressStore.registerBatch(registrations)
+
+  let warn = (~contractAddress, ~params, message) =>
+    Logging.createChild(
+      ~params={
+        "chainId": fetchState.chainId,
+        "contractAddress": contractAddress,
+        "details": params,
+      },
+    )->Logging.childWarn(message)
+
+  let registeringContractNames = []
+  let hasNoEventsUpdatesRef = ref(false)
+  for idx in 0 to verdicts->Array.length - 1 {
+    let registration = registrations->Array.getUnsafe(idx)
+    let contractAddress = registration.address->Address.toString
+    let keep = switch verdicts->Array.getUnsafe(idx) {
+    | Added(_) =>
+      if !(registeringContractNames->Array.includes(registration.contractName)) {
+        registeringContractNames->Array.push(registration.contractName)->ignore
+      }
+      true
+    | NoEvents(_) =>
+      hasNoEventsUpdatesRef := true
+      // Persist the address to the db so a future config change that adds
+      // events for this contract can pick it up on restart, but skip partition
+      // registration since there's nothing to fetch.
+      warn(
+        ~contractAddress,
+        ~params={"contractName": registration.contractName},
+        `Persisting contract registration without fetching: Contract doesn't have any events to fetch. It'll be picked up on restart if you add events for the contract.`,
+      )
+      true
+    | Conflict({existingContractName}) =>
+      warn(
+        ~contractAddress,
+        ~params={
+          "existingContractType": existingContractName,
+          "newContractType": registration.contractName,
+        },
+        `Skipping contract registration: Contract address is already registered for one contract and cannot be registered for another contract.`,
+      )
+      false
+    | Duplicate({effectiveStartBlock, existingEffectiveStartBlock}) =>
+      // FIXME: Instead of filtering out duplicates, we should check the block
+      // number first. If a new registration has an earlier block number we
+      // should register it for the missing block range.
+      if existingEffectiveStartBlock > effectiveStartBlock {
+        warn(
+          ~contractAddress,
+          ~params={
+            "existingBlockNumber": existingEffectiveStartBlock,
+            "newBlockNumber": effectiveStartBlock,
+          },
+          `Skipping contract registration: Contract address is already registered at a later block number. Currently registration of the same contract address is not supported by Envio. Reach out to us if it's a problem for you.`,
+        )
       }
+      false
+    | Invalid =>
+      warn(
+        ~contractAddress,
+        ~params={"contractName": registration.contractName},
+        `Skipping contract registration: Not a valid address for this chain's ecosystem.`,
+      )
+      false
+    }
+    if !keep {
+      // Mark for removal; the splice happens below, back to front, so earlier
+      // indexes stay valid.
+      sourceIndexes->Array.setUnsafe(idx, -1 - sourceIndexes->Array.getUnsafe(idx))
+    }
+  }
+  for idx in verdicts->Array.length - 1 downto 0 {
+    let marked = sourceIndexes->Array.getUnsafe(idx)
+    if marked < 0 {
+      let _ =
+        sourceDcs->Array.getUnsafe(idx)->Array.splice(~start=-1 - marked, ~remove=1, ~insert=[])
     }
   }
 
-  let dcContractNamesToStore = registeringContractsByContract->Dict.keysToArray
-  let hasNoEventsUpdates = !(noEventsAddresses->Utils.Dict.isEmpty)
-  switch (dcContractNamesToStore, hasNoEventsUpdates) {
-  // Dont update anything when everything was filter out
+  switch (registeringContractNames, hasNoEventsUpdatesRef.contents) {
+  // Dont update anything when everything was filtered out
   | ([], false) => fetchState
-  | ([], true) =>
-    // Only dcs for contracts without events. Track them on
-    // indexingAddresses so subsequent registrations see them, but don't touch
-    // partitions since there's nothing to fetch for them.
-    indexingAddresses->IndexingAddresses.register(noEventsAddresses)
-    fetchState
+  // Only dcs for contracts without events. The store already tracks them so
+  // subsequent registrations see them, but there are no partitions to touch.
+  | ([], true) => fetchState
   | (_, _) => {
       let newPartitions = []
       let dynamicContractsRef = ref(fetchState.optimizedPartitions.dynamicContracts)
       let mutExistingPartitions = fetchState.optimizedPartitions.entities->Dict.valuesToArray
 
-      for idx in 0 to dcContractNamesToStore->Array.length - 1 {
-        let contractName = dcContractNamesToStore->Array.getUnsafe(idx)
+      for idx in 0 to registeringContractNames->Array.length - 1 {
+        let contractName = registeringContractNames->Array.getUnsafe(idx)
 
         // When a new contract name is added as a dynamic contract for the first time (not in dynamicContracts set):
         // Walks through existing partitions that have addresses for this contract name
@@ -1323,12 +1492,12 @@ let registerDynamicContracts = (
 
           for idx in 0 to mutExistingPartitions->Array.length - 1 {
             let p = mutExistingPartitions->Array.getUnsafe(idx)
-            switch p.addressesByContractName->Utils.Dict.dangerouslyGetNonOption(contractName) {
-            | None => () // Skip partitions which don't have our contract
-            | Some(addresses) =>
+            switch p.addresses->AddressSet.countFor(contractName) {
+            | 0 => () // Skip partitions which don't have our contract
+            | _ =>
               // Also filter out partitions which are 100% not mergable
               if p.selection.dependsOnAddresses && p.mergeBlock === None {
-                let allPartitionContractNames = p.addressesByContractName->Dict.keysToArray
+                let allPartitionContractNames = p.addresses->AddressSet.contractNames
                 switch allPartitionContractNames {
                 | [_] =>
                   mutExistingPartitions->Array.setUnsafe(
@@ -1351,26 +1520,20 @@ let registerDynamicContracts = (
                         (fetchState.optimizedPartitions.nextPartitionIndex +
                         newPartitions->Array.length)->Int.toString
 
-                      let restAddressesByContractName =
-                        p.addressesByContractName->Utils.Dict.shallowCopy
-                      restAddressesByContractName->Utils.Dict.deleteInPlace(contractName)
-
+                      let restNames =
+                        allPartitionContractNames->Array.filter(name => name !== contractName)
                       mutExistingPartitions->Array.setUnsafe(
                         idx,
-                        {
-                          ...p,
-                          addressesByContractName: restAddressesByContractName,
-                        },
+                        p->withAddresses(p.addresses->AddressSet.filterByContracts(restNames)),
                       )
 
-                      let addressesByContractName = Dict.make()
-                      addressesByContractName->Dict.set(contractName, addresses)
+                      let splitAddresses = p.addresses->AddressSet.filterByContracts([contractName])
                       newPartitions->Array.push({
                         id: newPartitionId,
                         latestFetchedBlock: p.latestFetchedBlock,
                         selection: fetchState.normalSelection,
                         dynamicContract: Some(contractName),
-                        addressesByContractName,
+                        addresses: splitAddresses,
                         mergeBlock: None,
                         mutPendingQueries: p.mutPendingQueries,
                         sourceRangeCapacity: p.sourceRangeCapacity,
@@ -1385,22 +1548,59 @@ let registerDynamicContracts = (
             }
           }
         }
+      }
 
-        let registeringContracts = registeringContractsByContract->Dict.getUnsafe(contractName)
-        indexingAddresses->IndexingAddresses.register(registeringContracts)
+      // Switch any dynamic contract that has just crossed the server-side
+      // address threshold to client-side filtering. Sticky: the set only grows, and
+      // collapse in createPartitions folds the contract's
+      // partitions into the single address-free partition.
+      // Clone the sticky set before mutating so this update owns its copy and
+      // older fetchState snapshots keep theirs (Utils.Set.add mutates in place).
+      let clientFilteredContracts = switch fetchState.clientFilterAddressThreshold {
+      | Some(threshold) =>
+        let clientFilteredContracts =
+          fetchState.optimizedPartitions.clientFilteredContracts
+          ->Utils.Set.toArray
+          ->Utils.Set.fromArray
+        dynamicContractsRef.contents
+        ->Utils.Set.toArray
+        ->Array.forEach(contractName => {
+          let addressCount = addressStore->AddressStore.contractCount(contractName)
+          if !(clientFilteredContracts->Utils.Set.has(contractName)) && addressCount > threshold {
+            clientFilteredContracts->addClientFilteredContract(
+              ~contractName,
+              ~chainId=fetchState.chainId,
+              ~addressCount,
+              ~threshold,
+            )
+          }
+        })
+        clientFilteredContracts
+      | None => fetchState.optimizedPartitions.clientFilteredContracts
       }
-      // Include no-events dcs so later batches detect conflicts against them.
-      indexingAddresses->IndexingAddresses.register(noEventsAddresses)
 
-      let optimizedPartitions = createPartitionsFromIndexingAddresses(
-        ~registeringContractsByContract,
+      // Only this batch's additions need partitions; everything already
+      // registered has one.
+      let registeringSetsByContract = Dict.make()
+      registeringContractNames->Array.forEach(contractName => {
+        registeringSetsByContract->Dict.set(
+          contractName,
+          addressStore->AddressStore.makeSet(~contractName, ~options={minId: idCursor}),
+        )
+      })
+
+      let optimizedPartitions = createPartitions(
+        ~registeringSetsByContract,
+        ~addressStore,
         ~dynamicContracts=dynamicContractsRef.contents,
+        ~clientFilteredContracts,
         ~normalSelection=fetchState.normalSelection,
         ~maxAddrInPartition=fetchState.optimizedPartitions.maxAddrInPartition,
         ~nextPartitionIndex=fetchState.optimizedPartitions.nextPartitionIndex +
         newPartitions->Array.length,
         ~existingPartitions=mutExistingPartitions->Array.concat(newPartitions),
         ~progressBlockNumber=0,
+        ~knownHeight=Pervasives.max(claimCeiling, fetchState.knownHeight),
       )
 
       fetchState->updateInternal(~optimizedPartitions)
@@ -1408,26 +1608,6 @@ let registerDynamicContracts = (
   }
 }
 
-// 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 the srcAddress effectiveStartBlock check.
-let filterByClientAddress = (
-  items: array<Internal.item>,
-  ~indexingAddresses: IndexingAddresses.t,
-): array<Internal.item> =>
-  items->Array.filter(item =>
-    switch item {
-    | Internal.Event({payload, blockNumber}) as item =>
-      switch (item->Internal.castUnsafeEventItem).onEventRegistration.clientAddressFilter {
-      | Some(filter) =>
-        filter(payload, blockNumber, indexingAddresses->IndexingAddresses.rawForFilter)
-      | None => true
-      }
-    | _ => true
-    }
-  )
-
 /*
 Updates fetchState with a response for a given query.
 Returns Error if the partition with given query cannot be found (unexpected)
@@ -1505,26 +1685,19 @@ let maxInFlightChunksPerPartition = 12
 // Most parallel in-flight queries a single chain may have at once, across all
 // its partitions. Bounds source load on chains with many partitions, where the
 // per-partition cap alone would admit thousands of concurrent queries.
-let maxChainConcurrency = 100
+let maxChainConcurrency = Env.maxChainConcurrency
 
 // Chunk spans grow by this factor over the smallest recently observed source
 // range, so the pipeline keeps probing for more capacity instead of locking in
 // the first measurement.
 let chunkRangeGrowthFactor = 1.8
 
-// Push one density-priced query and return its itemsEst. itemsEst is the honest
-// density estimate the chain's budget is reserved in; itemsTarget is the
-// server-side cap with chunkItemsMultiplier headroom so a denser-than-expected
-// range doesn't truncate the response.
-//
-// A bounded query (toBlock set) additionally floors its cap at
-// itemsTargetFloor: its range is already the hard bound on the response, so a
-// low density estimate shrinking the cap only buys self-truncated responses —
-// each one a wasted roundtrip that opens a gap and pollutes nothing but our
-// own pipeline. The floor is the indexer target split across the chain's
-// concurrency slots, so even every in-flight bounded query hitting its floored
-// cap at once overshoots the pool by at most ~one buffer target. Open-ended
-// queries keep the pure density cap — there it's the only bound at all.
+// Push one density-priced query and return its itemsEst, the density estimate
+// that sizes the query and the chain's budget reservation. These queries are
+// chunks and gap-fills: their toBlock is a tight bound sized to the source's
+// range capacity, so they send no server cap (itemsTarget None) — a cap would
+// only self-truncate the bounded range, worse under client-side address
+// filtering. A rare unbounded call caps at the estimate as its only bound.
 let pushDensityPricedQuery = (
   queries: array<query>,
   ~partitionId,
@@ -1532,19 +1705,11 @@ let pushDensityPricedQuery = (
   ~toBlock,
   ~isChunk,
   ~density,
-  ~chunkItemsMultiplier,
   ~chainTargetBlock,
-  ~itemsTargetFloor,
   ~selection,
-  ~addressesByContractName,
+  ~addresses,
 ) => {
   let itemsEst = densityItemsTarget(~density, ~fromBlock, ~toBlock, ~chainTargetBlock)
-  let itemsTarget = densityItemsTarget(
-    ~density=density *. chunkItemsMultiplier,
-    ~fromBlock,
-    ~toBlock,
-    ~chainTargetBlock,
-  )
   queries
   ->Array.push({
     partitionId,
@@ -1553,11 +1718,11 @@ let pushDensityPricedQuery = (
     selection,
     isChunk,
     itemsTarget: switch toBlock {
-    | Some(_) => Pervasives.max(itemsTarget, itemsTargetFloor)
-    | None => itemsTarget
+    | Some(_) => None
+    | None => Some(itemsEst)
     },
     itemsEst,
-    addressesByContractName,
+    addresses,
   })
   ->ignore
   itemsEst
@@ -1585,10 +1750,8 @@ let pushGapFillQueries = (
   ~maxChunks: int,
   ~partition: partition,
   ~partitionBudget: float,
-  ~chunkItemsMultiplier: float,
-  ~itemsTargetFloor: int,
   ~selection: selection,
-  ~addressesByContractName: dict<array<Address.t>>,
+  ~addresses: AddressSet.t,
 ) => {
   // Gaps past the chain's target block wait: they regenerate from the
   // pending-walk each tick and fill once the target reaches them. The lagged
@@ -1610,11 +1773,9 @@ let pushGapFillQueries = (
           ~toBlock=rangeEndBlock,
           ~isChunk,
           ~density,
-          ~chunkItemsMultiplier,
           ~chainTargetBlock,
-          ~itemsTargetFloor,
           ~selection,
-          ~addressesByContractName,
+          ~addresses,
         )
         ->ignore
       switch (partition->getTrustedDensity, maybeChunkRange) {
@@ -1634,11 +1795,9 @@ let pushGapFillQueries = (
               ~toBlock=Some(chunkToBlock),
               ~isChunk=true,
               ~density,
-              ~chunkItemsMultiplier,
               ~chainTargetBlock,
-              ~itemsTargetFloor,
               ~selection,
-              ~addressesByContractName,
+              ~addresses,
             )
             ->ignore
             chunkFromBlock := chunkToBlock + 1
@@ -1684,8 +1843,6 @@ let walkPartitionPending = (
   ~candidates: array<query>,
   ~headBlockNumber: int,
   ~chainTargetBlock: int,
-  ~chunkItemsMultiplier: float,
-  ~itemsTargetFloor: int,
   ~partitionBudget: float,
   ~queryEndBlock: option<int>,
 ): option<partitionFillState> => {
@@ -1712,10 +1869,8 @@ let walkPartitionPending = (
         ~maxChunks=maxInFlightChunksPerPartition - inFlightCount - chunksUsedThisCall.contents,
         ~partition=p,
         ~partitionBudget,
-        ~chunkItemsMultiplier,
-        ~itemsTargetFloor,
         ~selection=p.selection,
-        ~addressesByContractName=p.addressesByContractName,
+        ~addresses=p.addresses,
       )
       chunksUsedThisCall := chunksUsedThisCall.contents + (candidates->Array.length - beforeLen)
     }
@@ -1757,14 +1912,12 @@ let pushForwardCandidates = (
   // bound, see getNextQuery.
   ~inRangeStates: array<partitionFillState>,
   // The full in-range partition count, pre-truncation. Probe sizing divides by
-  // this so each probe's itemsEst/itemsTarget stays the honest per-partition
-  // share for budget control — sizing by the (fewer) admittable queries would
-  // let every accepted probe over-fetch its share.
+  // this so each probe's itemsEst stays the honest per-partition share for
+  // budget control — sizing by the (fewer) admittable queries would let every
+  // accepted probe over-fetch its share.
   ~inRangeCount: int,
   ~chainTargetBlock: int,
   ~freshBudget: float,
-  ~chunkItemsMultiplier: float,
-  ~itemsTargetFloor: int,
 ) => {
   // Even share of the fresh budget across the partitions actually fetching
   // this tick (not every partition — so budget isn't stranded on ones below
@@ -1818,11 +1971,9 @@ let pushForwardCandidates = (
             ~toBlock=Some(chunkToBlock),
             ~isChunk=true,
             ~density,
-            ~chunkItemsMultiplier,
             ~chainTargetBlock,
-            ~itemsTargetFloor,
             ~selection=p.selection,
-            ~addressesByContractName=p.addressesByContractName,
+            ~addresses=p.addresses,
           )
         generatedItems := generatedItems.contents +. itemsEst->Int.toFloat
         chunkFromBlock := chunkToBlock + 1
@@ -1834,7 +1985,7 @@ let pushForwardCandidates = (
       // across the partitions fetching this tick. With no range to the target
       // fall back to an even share of the fresh budget, so cold chains and
       // caught-up partitions still probe.
-      let itemsTarget = if rangeToTarget > 0 {
+      let itemsEst = if rangeToTarget > 0 {
         Pervasives.max(
           1,
           Math.round(
@@ -1853,9 +2004,11 @@ let pushForwardCandidates = (
         toBlock: fs.queryEndBlock,
         isChunk: false,
         selection: p.selection,
-        itemsTarget,
-        itemsEst: itemsTarget,
-        addressesByContractName: p.addressesByContractName,
+        // An open-ended probe's range isn't bounded to source capacity, so it
+        // keeps a server cap at its estimate to protect the shared buffer.
+        itemsTarget: Some(itemsEst),
+        itemsEst,
+        addresses: p.addresses,
       })
       ->ignore
     }
@@ -1958,10 +2111,6 @@ let getNextQuery = (
   {optimizedPartitions, blockLag, latestOnBlockBlockNumber, knownHeight, endBlock}: t,
   ~chainTargetBlock: int,
   ~chainTargetItems: float,
-  ~chunkItemsMultiplier: float=1.,
-  // Floor for bounded queries' server cap (see pushDensityPricedQuery) —
-  // targetBufferSize / maxChainConcurrency from the cross-chain scheduler.
-  ~itemsTargetFloor: int=0,
 ) => {
   let headBlockNumber = knownHeight - blockLag
   if headBlockNumber <= 0 {
@@ -2079,8 +2228,6 @@ let getNextQuery = (
         ~candidates,
         ~headBlockNumber,
         ~chainTargetBlock,
-        ~chunkItemsMultiplier,
-        ~itemsTargetFloor,
         ~partitionBudget,
         ~queryEndBlock=computeQueryEndBlock(p),
       ) {
@@ -2124,8 +2271,6 @@ let getNextQuery = (
       ~inRangeCount,
       ~chainTargetBlock,
       ~freshBudget,
-      ~chunkItemsMultiplier,
-      ~itemsTargetFloor,
     )
 
     acceptCandidates(
@@ -2187,7 +2332,7 @@ let make = (
   ~startBlock,
   ~endBlock,
   ~onEventRegistrations: array<Internal.onEventRegistration>,
-  ~contractConfigs: dict<IndexingAddresses.contractConfig>,
+  ~addressStore: AddressStore.t,
   ~addresses: array<Internal.indexingAddress>,
   ~maxAddrInPartition,
   ~chainId,
@@ -2197,6 +2342,7 @@ let make = (
   ~onBlockRegistrations=[],
   ~blockLag=0,
   ~firstEventBlock=None,
+  ~clientFilterAddressThreshold=None,
 ): t => {
   let latestFetchedBlock = {
     blockTimestamp: 0,
@@ -2226,7 +2372,7 @@ let make = (
         dependsOnAddresses: false,
         onEventRegistrations: notDependingOnAddresses,
       },
-      addressesByContractName: Dict.make(),
+      addresses: addressStore->AddressStore.emptySet,
       mergeBlock: None,
       dynamicContract: None,
       mutPendingQueries: [],
@@ -2242,8 +2388,22 @@ let make = (
     onEventRegistrations: normalRegistrations,
   }
 
-  let registeringContractsByContract: dict<dict<indexingAddress>> = Dict.make()
+  // Every address the chain indexes goes into the store — including ones whose
+  // contract has no address-dependent events, so a later registration of the
+  // same address still conflicts and the address is still persisted.
+  addressStore
+  ->AddressStore.registerBatch(
+    addresses->Array.map((contract): AddressStore.registration => {
+      address: contract.address,
+      contractName: contract.contractName,
+      registrationBlock: contract.registrationBlock,
+    }),
+  )
+  ->ignore
+
   let dynamicContracts = Utils.Set.make()
+  let clientFilteredContracts = Utils.Set.make()
+  let registeringSetsByContract = Dict.make()
 
   addresses->Array.forEach(contract => {
     let contractName = contract.contractName
@@ -2251,12 +2411,12 @@ let make = (
     // Only addresses whose contract has events that depend on addresses get
     // registered for active fetching via partitions.
     if contractNamesWithNormalEvents->Utils.Set.has(contractName) {
-      registeringContractsByContract
-      ->Utils.Dict.getOrInsertEmptyDict(contractName)
-      ->Dict.set(
-        contract.address->Address.toString,
-        IndexingAddresses.makeIndexingAddress(~contract, ~contractConfigs),
-      )
+      if !(registeringSetsByContract->Dict.has(contractName)) {
+        registeringSetsByContract->Dict.set(
+          contractName,
+          addressStore->AddressStore.makeSet(~contractName),
+        )
+      }
 
       // Detect dynamic contracts by registrationBlock
       if contract.registrationBlock !== -1 {
@@ -2265,14 +2425,36 @@ let make = (
     }
   })
 
-  let optimizedPartitions = createPartitionsFromIndexingAddresses(
-    ~registeringContractsByContract,
+  // Switch any contract already over the server-side address threshold to
+  // client-side filtering at creation — a config contract with a large static
+  // address list, or a dynamic contract restored from a large persisted set.
+  switch clientFilterAddressThreshold {
+  | Some(threshold) =>
+    registeringSetsByContract->Utils.Dict.forEachWithKey((set, contractName) => {
+      let addressCount = set->AddressSet.size
+      if addressCount > threshold {
+        clientFilteredContracts->addClientFilteredContract(
+          ~contractName,
+          ~chainId,
+          ~addressCount,
+          ~threshold,
+        )
+      }
+    })
+  | None => ()
+  }
+
+  let optimizedPartitions = createPartitions(
+    ~registeringSetsByContract,
+    ~addressStore,
     ~dynamicContracts,
+    ~clientFilteredContracts,
     ~normalSelection,
     ~maxAddrInPartition,
     ~nextPartitionIndex=partitions->Array.length,
     ~existingPartitions=partitions, // wildcard partition(s) if any
     ~progressBlockNumber,
+    ~knownHeight,
   )
 
   if (
@@ -2313,7 +2495,6 @@ let make = (
 
   let fetchState = {
     optimizedPartitions,
-    contractConfigs,
     chainId,
     startBlock,
     endBlock,
@@ -2325,6 +2506,7 @@ let make = (
     knownHeight,
     buffer,
     firstEventBlock,
+    clientFilterAddressThreshold,
   }
 
   fetchState
@@ -2365,16 +2547,29 @@ Always recreates optimized partitions to avoid duplicate addresses:
 - Non-wildcard with lfb <= target: keep, adjust pending queries and mergeBlock
 - Non-wildcard with lfb > target: delete, track addresses for recreation
 */
-let rollback = (fetchState: t, ~indexingAddresses: IndexingAddresses.t, ~targetBlockNumber) => {
-  // Step 1: Prune addresses registered after the target block. The pruned index is
-  // then the source of truth for partition cleanup below — an address survives iff
-  // it's still in the index.
-  indexingAddresses->IndexingAddresses.rollbackInPlace(~targetBlockNumber)
+let rollback = (fetchState: t, ~addressStore: AddressStore.t, ~targetBlockNumber) => {
+  // Step 1: Prune addresses registered after the target block. The pruned store
+  // is then the source of truth for partition cleanup below — an address
+  // survives iff `filterByRegistrationBlock` keeps it.
+  addressStore->AddressStore.rollback(targetBlockNumber)->ignore
 
   // Step 2: Categorize partitions
   let keptPartitions = []
   let nextKeptIdRef = ref(0)
-  let registeringContractsByContract: dict<dict<indexingAddress>> = Dict.make()
+  let registeringSetsByContract: dict<AddressSet.t> = Dict.make()
+  let collectForRecreation = (set: AddressSet.t) =>
+    set
+    ->AddressSet.contractNames
+    ->Array.forEach(contractName => {
+      let contractSet = set->AddressSet.filterByContracts([contractName])
+      registeringSetsByContract->Dict.set(
+        contractName,
+        switch registeringSetsByContract->Utils.Dict.dangerouslyGetNonOption(contractName) {
+        | Some(existing) => existing->AddressSet.merge(contractSet)
+        | None => contractSet
+        },
+      )
+    })
 
   let partitions = fetchState.optimizedPartitions.entities->Dict.valuesToArray
   for idx in 0 to partitions->Array.length - 1 {
@@ -2397,46 +2592,27 @@ let rollback = (fetchState: t, ~indexingAddresses: IndexingAddresses.t, ~targetB
 
     // Non-wildcard with lfb > target: delete, collect addresses for recreation
     | _ if p.latestFetchedBlock.blockNumber > targetBlockNumber =>
-      p.addressesByContractName->Utils.Dict.forEachWithKey((addresses, contractName) => {
-        addresses->Array.forEach(address => {
-          switch indexingAddresses->IndexingAddresses.get(address->Address.toString) {
-          | Some(indexingContract) =>
-            let registeringContracts =
-              registeringContractsByContract->Utils.Dict.getOrInsertEmptyDict(contractName)
-            registeringContracts->Dict.set(address->Address.toString, indexingContract)
-          | None => ()
-          }
-        })
-      })
+      collectForRecreation(p.addresses->AddressSet.filterByRegistrationBlock(targetBlockNumber))
 
     // Non-wildcard with lfb <= target: keep, adjust pending queries and mergeBlock
-    | {addressesByContractName} => {
+    | _ => {
         // Cap mergeBlock at target
         let mergeBlock = switch p.mergeBlock {
         | Some(mergeBlock) if mergeBlock > targetBlockNumber => Some(targetBlockNumber)
         | other => other
         }
 
-        // Drop addresses pruned from the index
-        let rollbackedAddressesByContractName = Dict.make()
-        addressesByContractName->Utils.Dict.forEachWithKey((addresses, contractName) => {
-          let keptAddresses =
-            addresses->Array.filter(address =>
-              indexingAddresses->IndexingAddresses.get(address->Address.toString)->Option.isSome
-            )
-          if keptAddresses->Array.length > 0 {
-            rollbackedAddressesByContractName->Dict.set(contractName, keptAddresses)
-          }
-        })
+        // Drop addresses pruned from the store
+        let rollbackedAddresses =
+          p.addresses->AddressSet.filterByRegistrationBlock(targetBlockNumber)
 
-        if !(rollbackedAddressesByContractName->Utils.Dict.isEmpty) {
+        if !(rollbackedAddresses->AddressSet.isEmpty) {
           let id = nextKeptIdRef.contents->Int.toString
           nextKeptIdRef := nextKeptIdRef.contents + 1
           keptPartitions
           ->Array.push({
-            ...p,
+            ...p->withAddresses(rollbackedAddresses),
             id,
-            addressesByContractName: rollbackedAddressesByContractName,
             mutPendingQueries: rollbackPendingQueries(p.mutPendingQueries, ~targetBlockNumber),
             mergeBlock,
           })
@@ -2447,14 +2623,17 @@ let rollback = (fetchState: t, ~indexingAddresses: IndexingAddresses.t, ~targetB
   }
 
   // Step 3: Recreate partitions from deleted partition addresses
-  let optimizedPartitions = createPartitionsFromIndexingAddresses(
-    ~registeringContractsByContract,
+  let optimizedPartitions = createPartitions(
+    ~registeringSetsByContract,
+    ~addressStore,
     ~dynamicContracts=fetchState.optimizedPartitions.dynamicContracts,
+    ~clientFilteredContracts=fetchState.optimizedPartitions.clientFilteredContracts,
     ~normalSelection=fetchState.normalSelection,
     ~maxAddrInPartition=fetchState.optimizedPartitions.maxAddrInPartition,
     ~nextPartitionIndex=nextKeptIdRef.contents,
     ~existingPartitions=keptPartitions,
     ~progressBlockNumber=targetBlockNumber,
+    ~knownHeight=fetchState.knownHeight,
   )
 
   // Step 4: Update state