envio 3.3.0-alpha.11 → 3.3.0-alpha.13

package/index.d.ts

@@ -48,6 +48,13 @@ export type EffectCaller = <I, O>(
   input: I extends undefined ? undefined : I
 ) => Promise<O>;
 
+/** The chain an Effect was called on. Available only on chain-scoped effects
+ * (`crossChain: false`). */
+export type EffectChain = {
+  /** The chain id the effect handler was called on. */
+  readonly id: number;
+};
+
 /** Context passed to an Effect's handler function. */
 export type EffectContext = {
   /** Access the logger instance with the event as context. */
@@ -57,6 +64,9 @@ export type EffectContext = {
   /** Whether to cache this call's result. Defaults to the effect's `cache`
    * option; set to `false` to skip caching for this specific invocation. */
   cache: boolean;
+  /** The chain the effect was called on. Only available on effects created with
+   * `crossChain: false`; accessing it on a cross-chain effect throws. */
+  readonly chain: EffectChain;
 };
 
 /** Rate-limit window for an {@link Effect}. Strings resolve to common
@@ -82,6 +92,11 @@ export type EffectOptions<Input, Output> = {
   readonly rateLimit: RateLimit;
   /** Whether the effect should be cached. */
   readonly cache?: boolean;
+  /** Whether the effect's cache is shared across all chains. Defaults to
+   * `true`. Set to `false` to isolate the cache and rate limiting per chain and
+   * enable `context.chain.id` inside the handler. Changing this changes the
+   * effect's cache identity. */
+  readonly crossChain?: boolean;
 };
 
 /** Arguments passed to the handler function of an {@link Effect}. */
@@ -209,6 +224,10 @@ export function createEffect<
     readonly rateLimit: RateLimit;
     /** Whether the effect should be cached. */
     readonly cache?: boolean;
+    /** Whether the effect's cache is shared across all chains. Defaults to
+     * `true`. Set to `false` to isolate the cache and rate limiting per chain
+     * and enable `context.chain.id` inside the handler. */
+    readonly crossChain?: boolean;
   },
   handler: (args: EffectArgs<I>) => Promise<R>
 ): Effect<I, O>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.3.0-alpha.11",
+  "version": "3.3.0-alpha.13",
   "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.3.0-alpha.11",
-    "envio-linux-x64-musl": "3.3.0-alpha.11",
-    "envio-linux-arm64": "3.3.0-alpha.11",
-    "envio-darwin-x64": "3.3.0-alpha.11",
-    "envio-darwin-arm64": "3.3.0-alpha.11"
+    "envio-linux-x64": "3.3.0-alpha.13",
+    "envio-linux-x64-musl": "3.3.0-alpha.13",
+    "envio-linux-arm64": "3.3.0-alpha.13",
+    "envio-darwin-x64": "3.3.0-alpha.13",
+    "envio-darwin-arm64": "3.3.0-alpha.13"
   }
 }

package/src/ChainFetching.res

@@ -149,19 +149,28 @@ let rec onQueryResponse = async (
 
     let numContractRegisterEvents = parsedQueueItems->Array.reduce(0, (count, item) => {
       let eventItem = item->Internal.castUnsafeEventItem
-      eventItem.onEventRegistration.contractRegister !== None
-        ? count + 1
-        : count
-    })
-    Logging.trace({
-      "msg": "Finished querying",
-      "chainId": chain->ChainMap.Chain.toChainId,
-      "partitionId": query.partitionId,
-      "fromBlock": fromBlockQueried,
-      "toBlock": latestFetchedBlockNumber,
-      "numEvents": parsedQueueItems->Array.length,
-      "numContractRegisterEvents": numContractRegisterEvents,
+      eventItem.onEventRegistration.contractRegister !== None ? count + 1 : count
     })
+    if numContractRegisterEvents === 0 {
+      Logging.trace({
+        "msg": "Finished querying",
+        "chainId": chain->ChainMap.Chain.toChainId,
+        "partitionId": query.partitionId,
+        "fromBlock": fromBlockQueried,
+        "toBlock": latestFetchedBlockNumber,
+        "numEvents": parsedQueueItems->Array.length,
+      })
+    } else {
+      Logging.trace({
+        "msg": "Finished querying",
+        "chainId": chain->ChainMap.Chain.toChainId,
+        "partitionId": query.partitionId,
+        "fromBlock": fromBlockQueried,
+        "toBlock": latestFetchedBlockNumber,
+        "numEvents": parsedQueueItems->Array.length,
+        "numContractRegisterEvents": numContractRegisterEvents,
+      })
+    }
 
     let reorgResult = chainState->ChainState.registerReorgGuard(~blockHashes, ~knownHeight)
 

package/src/ChainFetching.res.mjs

@@ -111,15 +111,26 @@ async function onQueryResponse(state, param, stateId, scheduleFetch, schedulePro
       return count;
     }
   });
-  Logging.trace({
-    msg: "Finished querying",
-    chainId: chain,
-    partitionId: query.partitionId,
-    fromBlock: fromBlockQueried,
-    toBlock: latestFetchedBlockNumber,
-    numEvents: parsedQueueItems.length,
-    numContractRegisterEvents: numContractRegisterEvents
-  });
+  if (numContractRegisterEvents === 0) {
+    Logging.trace({
+      msg: "Finished querying",
+      chainId: chain,
+      partitionId: query.partitionId,
+      fromBlock: fromBlockQueried,
+      toBlock: latestFetchedBlockNumber,
+      numEvents: parsedQueueItems.length
+    });
+  } else {
+    Logging.trace({
+      msg: "Finished querying",
+      chainId: chain,
+      partitionId: query.partitionId,
+      fromBlock: fromBlockQueried,
+      toBlock: latestFetchedBlockNumber,
+      numEvents: parsedQueueItems.length,
+      numContractRegisterEvents: numContractRegisterEvents
+    });
+  }
   let reorgResult = ChainState.registerReorgGuard(chainState, response.blockHashes, knownHeight);
   let rollbackWithReorgDetectedBlockNumber;
   if (typeof reorgResult !== "object") {

package/src/ChainState.res

@@ -410,13 +410,17 @@ let isReady = (cs: t) => cs.timestampCaughtUpToHeadOrEndblock !== None
 // nudge it.
 let densityBlendWindow = 100.
 
-// The last block this chain can fetch right now: the head, or endBlock when
-// it's below the head.
+// The last block this chain can fetch right now: the lagged head
+// (knownHeight - blockLag, the frontier when a reorg-threshold blockLag holds
+// back the tip), or endBlock when it's below that head. Matching isFetchingAtHead's
+// definition of the head is what lets a chain parked at its lagged head read
+// 100% progress instead of looking behind against blocks it can't fetch.
 let fetchCeiling = (cs: t) => {
   let fetchState = cs.fetchState
+  let head = Pervasives.max(0, fetchState.knownHeight - fetchState.blockLag)
   switch fetchState.endBlock {
-  | Some(endBlock) => Pervasives.min(endBlock, fetchState.knownHeight)
-  | None => fetchState.knownHeight
+  | Some(endBlock) => Pervasives.min(endBlock, head)
+  | None => head
   }
 }
 
@@ -466,12 +470,14 @@ let targetBlock = (cs: t, ~chainTargetItems: float) => {
 }
 
 // Block range that cross-chain progress alignment maps fractions over: from
-// the first block that can hold this chain's events to the last block it can
-// fetch right now.
+// the chain's startBlock to the last block it can fetch right now. The lower
+// bound is deliberately static — anchoring it at firstEventBlock would make
+// two chains sitting at the same block read different progress fractions
+// depending on whether each has discovered its first event yet, so the
+// anchor's line could map below a follower's own frontier and stall it.
 let progressRange = (cs: t) => {
   let fetchState = cs.fetchState
-  let lower = fetchState.firstEventBlock->Option.getOr(fetchState.startBlock)
-  (lower, cs->fetchCeiling)
+  (fetchState.startBlock, cs->fetchCeiling)
 }
 
 // A degenerate range (chain already at or past its last block) maps to 1 so it
@@ -492,6 +498,12 @@ let blockAtProgress = (cs: t, ~progress) => {
   lower + Math.ceil(progress *. (upper - lower)->Int.toFloat)->Float.toInt
 }
 
+// The fetch frontier as a fraction of the alignable range — what the
+// cross-chain waterfall aligns other chains against. Based on blocks actually
+// fetched, so it holds up even while this chain's queries are in flight.
+let frontierProgress = (cs: t) =>
+  cs->progressAtBlock(~blockNumber=cs.fetchState->FetchState.bufferBlockNumber)
+
 // Propose queries sized against this chain's target block. Called by
 // CrossChainState's waterfall, furthest-behind chain first, with
 // chainTargetItems set to whatever budget remains at that point and

package/src/ChainState.res.mjs

@@ -254,11 +254,12 @@ function isReady(cs) {
 
 function fetchCeiling(cs) {
   let fetchState = cs.fetchState;
+  let head = Primitive_int.max(0, fetchState.knownHeight - fetchState.blockLag | 0);
   let endBlock = fetchState.endBlock;
   if (endBlock !== undefined) {
-    return Primitive_int.min(endBlock, fetchState.knownHeight);
+    return Primitive_int.min(endBlock, head);
   } else {
-    return fetchState.knownHeight;
+    return head;
   }
 }
 
@@ -300,14 +301,20 @@ function targetBlock(cs, chainTargetItems) {
 
 function progressRange(cs) {
   let fetchState = cs.fetchState;
-  let lower = Stdlib_Option.getOr(fetchState.firstEventBlock, fetchState.startBlock);
   return [
-    lower,
+    fetchState.startBlock,
     fetchCeiling(cs)
   ];
 }
 
-function progressAtBlock(cs, blockNumber) {
+function blockAtProgress(cs, progress) {
+  let match = progressRange(cs);
+  let lower = match[0];
+  return lower + (Math.ceil(progress * (match[1] - lower | 0)) | 0) | 0;
+}
+
+function frontierProgress(cs) {
+  let blockNumber = FetchState.bufferBlockNumber(cs.fetchState);
   let match = progressRange(cs);
   let upper = match[1];
   let lower = match[0];
@@ -318,12 +325,6 @@ function progressAtBlock(cs, blockNumber) {
   }
 }
 
-function blockAtProgress(cs, progress) {
-  let match = progressRange(cs);
-  let lower = match[0];
-  return lower + (Math.ceil(progress * (match[1] - lower | 0)) | 0) | 0;
-}
-
 function getNextQuery(cs, chainTargetItems, chunkItemsMultiplierOpt, maxTargetBlock) {
   let chunkItemsMultiplier = chunkItemsMultiplierOpt !== undefined ? chunkItemsMultiplierOpt : 1;
   let chainTargetBlock = targetBlock(cs, chainTargetItems);
@@ -782,8 +783,8 @@ export {
   hasReadyItem,
   isReadyToEnterReorgThreshold,
   targetBlock,
-  progressAtBlock,
   blockAtProgress,
+  frontierProgress,
   getNextQuery,
   dispatch,
   toChainData,

package/src/ChainState.resi

@@ -67,8 +67,8 @@ let isReadyToEnterReorgThreshold: t => bool
 
 // Fetch control.
 let targetBlock: (t, ~chainTargetItems: float) => int
-let progressAtBlock: (t, ~blockNumber: int) => float
 let blockAtProgress: (t, ~progress: float) => int
+let frontierProgress: t => float
 let getNextQuery: (
   t,
   ~chainTargetItems: float,

package/src/CrossChainState.res

@@ -169,13 +169,18 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
 
 // --- Fetch control. ---
 
-// Chains ordered furthest-behind first, so the shared buffer pool goes to the
-// chains with the most backfill work before the rest.
+// Chains ordered furthest-behind first by fetch-frontier progress, so the
+// shared buffer pool goes to the chains with the most fetchable backfill work
+// before the rest — and the same metric that sets the alignment line also
+// decides who draws budget first, so the anchor is served before any chain it
+// clamps. (Batch ordering keeps its own getProgressPercentage measure.) A chain
+// with no known height reads 100% here and sorts last, which is fine: it can't
+// fetch until its first block lands regardless of when it's visited.
 let priorityOrder = (crossChainState: t) =>
   crossChainState.chainStates
   ->Dict.valuesToArray
   ->Array.toSorted((a, b) =>
-    Float.compare(a->ChainState.getProgressPercentage, b->ChainState.getProgressPercentage)
+    Float.compare(a->ChainState.frontierProgress, b->ChainState.frontierProgress)
   )
 
 // In-flight estimated items across every chain — the live draw against
@@ -198,69 +203,88 @@ let totalReservedSize = (crossChainState: t) => {
 // chain-density-derived target block, then subtract what it actually used
 // before moving to the next chain. So a chain that can only use a little
 // (density too low, or already caught up) leaves the rest for the others
-// automatically. A chain visited after the budget ran out simply doesn't
-// query this round — the leader's reservations release as its responses land,
-// so the next tick redistributes. Chains that do get budget are additionally
-// capped at the most-behind chain's target progress mapped onto their own
-// range, so no chain runs further ahead than the chain the pool is
-// prioritizing.
+// automatically. Starting a new query requires at least 10% of the target pool
+// to be free. A chain visited after the budget falls below that admission unit
+// doesn't query this round — reservations release as responses land, so the
+// next tick redistributes. Every other chain is additionally capped at the
+// lowest-frontier-progress chain's progress mapped onto its own range, so no
+// chain runs ahead of the chain the pool is prioritizing — including on ticks
+// where that chain is mid-fetch and emits no new query. A chain with no known
+// height can't anchor this line (there's no range to measure against), a chain
+// caught up to its fetchable head reads 100% and so never anchors while another
+// is behind, and once the whole indexer has caught up (isRealtime) the clamp is
+// dropped — chains at head only trail each other by real-time block production.
 let checkAndFetch = async (
   crossChainState: t,
   ~dispatchChain: (~chain: ChainMap.Chain.t, ~action: FetchState.nextQuery) => promise<unit>,
 ) => {
+  let targetBudget = crossChainState.targetBufferSize->Int.toFloat
   let remaining = ref(
     Pervasives.max(
       0.,
-      crossChainState.targetBufferSize->Int.toFloat -.
+      targetBudget -.
       crossChainState->totalReadyCount->Int.toFloat -.
       crossChainState->totalReservedSize,
     ),
   )
 
+  // New fetch work is admitted in units of 10% of the target pool. Waiting
+  // below this floor avoids spending the last few free items on undersized
+  // queries; response and batch completion schedule another tick after they
+  // release enough budget.
+  let minimumAdmissionBudget = targetBudget *. 0.1
+
   // A chain with no density signal probes blind, so it only gets a bounded
   // slice of the pool — one unknown chain shouldn't hold the whole budget
-  // while it takes its first measurements.
-  let coldChainBudget = Pervasives.min(5_000., crossChainState.targetBufferSize->Int.toFloat)
+  // while it takes its first measurements. Its probe is one admission unit.
+  let coldChainBudget = minimumAdmissionBudget
 
   // Chunk reservations get headroom over the density estimate so a
   // denser-than-expected range doesn't truncate at the server cap; realtime
   // gets more since a forced catch-up query there costs a head-poll roundtrip.
   let chunkItemsMultiplier = crossChainState.isRealtime ? 3. : 1.5
 
+  let prioritizedChainStates = crossChainState->priorityOrder
+
+  // Alignment anchor: the first known-height chain in priority order — which,
+  // since that order sorts by frontier progress, is the chain furthest behind
+  // by the very metric the clamp maps other chains against. Anchoring on the
+  // frontier (not on the target of whichever chain happens to query this tick)
+  // keeps the line in place while the anchor's queries are still in flight. A
+  // chain caught up to its fetchable head reads 100% and sorts past any behind
+  // chain, so it never anchors while another chain is behind.
+  let alignment = crossChainState.isRealtime
+    ? None
+    : prioritizedChainStates
+      ->Array.find(cs => cs->ChainState.knownHeight != 0)
+      ->Option.map(cs => ((cs->ChainState.chainConfig).id, cs->ChainState.frontierProgress))
+
   let actionByChain = Dict.make()
-  let maxProgress = ref(None)
-  crossChainState
-  ->priorityOrder
-  ->Array.forEach(cs => {
+  prioritizedChainStates->Array.forEach(cs => {
     let chainId = (cs->ChainState.chainConfig).id
-    if cs->ChainState.knownHeight == 0 {
-      // No height yet — nothing to size a budget or an alignment line
-      // against. Skip without consuming budget or claiming leadership, so a
-      // chain whose source hasn't reported doesn't unconstrain everyone else.
-      actionByChain->Utils.Dict.setByInt(chainId, FetchState.WaitingForNewBlock)
+    if remaining.contents < minimumAdmissionBudget {
+      // More than 90% of the target pool is ready or reserved. Do not attempt
+      // any chain action until a full admission unit becomes free.
+      actionByChain->Utils.Dict.setByInt(chainId, FetchState.NothingToQuery)
+    } else if cs->ChainState.knownHeight == 0 {
+      // Let getNextQuery own the waiting decision without trying to size work
+      // against an unknown height.
+      actionByChain->Utils.Dict.setByInt(
+        chainId,
+        cs->ChainState.getNextQuery(~chainTargetItems=0., ~chunkItemsMultiplier),
+      )
     } else {
       let isCold = cs->ChainState.effectiveDensity === None
       let chainTargetItems =
         (isCold ? Pervasives.min(remaining.contents, coldChainBudget) : remaining.contents) +.
         cs->ChainState.pendingBudget
-      let maxTargetBlock = switch maxProgress.contents {
-      | None if isCold =>
-        // A cold chain's target is a guess — it doesn't set the alignment
-        // line; the first density-bearing chain after it does.
-        None
-      | None =>
-        // The most-behind chain sets the alignment line for everyone after it.
-        maxProgress :=
-          Some(
-            cs->ChainState.progressAtBlock(
-              ~blockNumber=cs->ChainState.targetBlock(~chainTargetItems),
-            ),
-          )
-        None
-      // 5% margin past the leader's line: chains whose progress tracks the
-      // leader closely would otherwise flap in and out of the clamp as
-      // leadership alternates, stalling their pipeline every other tick.
-      | Some(progress) => Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.05))
+      let maxTargetBlock = switch alignment {
+      // 5% margin past the anchor's line: chains whose progress tracks the
+      // anchor closely would otherwise flap in and out of the clamp on every
+      // small frontier move, stalling their pipeline every other tick.
+      | Some((anchorChainId, progress)) if anchorChainId !== chainId =>
+        Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.05))
+      | _ => None
       }
       switch cs->ChainState.getNextQuery(
         ~chainTargetItems,
@@ -274,8 +298,7 @@ let checkAndFetch = async (
         // range to nothing — and has nothing else to wake it must keep polling
         // for new blocks instead of going silent. NothingToQuery isn't
         // dispatched, so such a chain would never be re-scheduled and its head
-        // tracking would freeze (the knownHeight == 0 branch above forces a poll
-        // for the same reason). A chain is genuinely idle — and correctly left
+        // tracking would freeze. A chain is genuinely idle — and correctly left
         // undispatched — when it is caught up to its head/endblock, still
         // draining in-flight queries, or holding ready items that batch
         // processing will drain and re-schedule from.

package/src/CrossChainState.res.mjs

@@ -8,6 +8,7 @@ import * as ChainMap from "./ChainMap.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
 import * as Prometheus from "./Prometheus.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_float from "@rescript/runtime/lib/es6/Primitive_float.js";
 import * as SafeCheckpointTracking from "./SafeCheckpointTracking.res.mjs";
 
@@ -121,7 +122,7 @@ function applyBatchProgress(crossChainState, batch, blockTimestampName) {
 }
 
 function priorityOrder(crossChainState) {
-  return Object.values(crossChainState.chainStates).toSorted((a, b) => Primitive_float.compare(ChainState.getProgressPercentage(a), ChainState.getProgressPercentage(b)));
+  return Object.values(crossChainState.chainStates).toSorted((a, b) => Primitive_float.compare(ChainState.frontierProgress(a), ChainState.frontierProgress(b)));
 }
 
 function totalReservedSize(crossChainState) {
@@ -134,29 +135,33 @@ function totalReservedSize(crossChainState) {
 }
 
 async function checkAndFetch(crossChainState, dispatchChain) {
+  let targetBudget = crossChainState.targetBufferSize;
   let remaining = {
-    contents: Primitive_float.max(0, crossChainState.targetBufferSize - totalReadyCount(crossChainState) - totalReservedSize(crossChainState))
+    contents: Primitive_float.max(0, targetBudget - totalReadyCount(crossChainState) - totalReservedSize(crossChainState))
   };
-  let coldChainBudget = Primitive_float.min(5000, crossChainState.targetBufferSize);
+  let minimumAdmissionBudget = targetBudget * 0.1;
   let chunkItemsMultiplier = crossChainState.isRealtime ? 3 : 1.5;
+  let prioritizedChainStates = priorityOrder(crossChainState);
+  let alignment = crossChainState.isRealtime ? undefined : Stdlib_Option.map(prioritizedChainStates.find(cs => ChainState.knownHeight(cs) !== 0), cs => [
+      ChainState.chainConfig(cs).id,
+      ChainState.frontierProgress(cs)
+    ]);
   let actionByChain = {};
-  let maxProgress = {
-    contents: undefined
-  };
-  priorityOrder(crossChainState).forEach(cs => {
+  prioritizedChainStates.forEach(cs => {
     let chainId = ChainState.chainConfig(cs).id;
+    if (remaining.contents < minimumAdmissionBudget) {
+      actionByChain[chainId] = "NothingToQuery";
+      return;
+    }
     if (ChainState.knownHeight(cs) === 0) {
-      actionByChain[chainId] = "WaitingForNewBlock";
+      actionByChain[chainId] = ChainState.getNextQuery(cs, 0, chunkItemsMultiplier, undefined);
       return;
     }
     let isCold = ChainState.effectiveDensity(cs) === undefined;
     let chainTargetItems = (
-      isCold ? Primitive_float.min(remaining.contents, coldChainBudget) : remaining.contents
+      isCold ? Primitive_float.min(remaining.contents, minimumAdmissionBudget) : remaining.contents
     ) + ChainState.pendingBudget(cs);
-    let progress = maxProgress.contents;
-    let maxTargetBlock = progress !== undefined ? ChainState.blockAtProgress(cs, progress + 0.05) : (
-        isCold ? undefined : (maxProgress.contents = ChainState.progressAtBlock(cs, ChainState.targetBlock(cs, chainTargetItems)), undefined)
-      );
+    let maxTargetBlock = alignment !== undefined && alignment[0] !== chainId ? ChainState.blockAtProgress(cs, alignment[1] + 0.05) : undefined;
     let action = ChainState.getNextQuery(cs, chainTargetItems, chunkItemsMultiplier, maxTargetBlock);
     if (typeof action !== "object") {
       if (action === "WaitingForNewBlock") {

package/src/EffectState.res

@@ -0,0 +1,100 @@
+// Owns all per-(effect, scope) runtime state and its lifecycle. The two maps
+// have different rollback semantics, so keeping them together behind an explicit
+// `resetForRollback` makes the invariant enforced rather than remembered.
+
+// Per-scope rate-limit window and queue. A chain-scoped effect gets one of
+// these per chain, so each chain's throughput is independent.
+type effectRateLimitState = {
+  callsPerDuration: int,
+  durationMs: int,
+  mutable availableCalls: int,
+  mutable windowStartTime: float,
+  mutable queueCount: int,
+  mutable nextWindowPromise: option<promise<unit>>,
+}
+
+type effectCacheInMemTable = {
+  // Cache keys whose handler output is persisted on the next write. Drained
+  // each write; eviction is driven by the per-entry checkpointId instead.
+  mutable idsToStore: array<string>,
+  mutable invalidationsCount: int,
+  // Each entry is stamped with the checkpoint that referenced it (or
+  // loadedFromDbCheckpointId for db reads), so committed entries can be
+  // dropped once persisted/re-derivable, mirroring entity changes.
+  mutable dict: dict<Change.t<Internal.effectOutput>>,
+  mutable changesCount: float,
+  effect: Internal.effect,
+  // The scope this cache is for and its resolved db table (the address). The
+  // in-mem table is keyed by `table.tableName`, so a cross-chain and a
+  // chain-scoped cache for the same effect stay isolated.
+  scope: Internal.chainScope,
+  table: Table.table,
+  rateLimitState: option<effectRateLimitState>,
+  // Per-scope active-call bookkeeping, surfaced through the Effect metrics.
+  mutable activeCallsCount: int,
+  mutable prevCallStartTimerRef: Performance.timeRef,
+}
+
+type t = {
+  // Cache tables keyed by cache table name. Dropped on rollback — the cache
+  // is re-derivable from the db.
+  mutable tables: dict<effectCacheInMemTable>,
+  // Rate-limit windows keyed by the same name. Survive rollback: rate limiting
+  // reflects real API throughput, not indexing progress, so a reorg must not
+  // refill an effect's budget.
+  rateLimits: dict<effectRateLimitState>,
+}
+
+let make = (): t => {tables: Dict.make(), rateLimits: Dict.make()}
+
+let getRateLimitState = (self: t, ~tableName, ~effect: Internal.effect) =>
+  switch effect.rateLimit {
+  | None => None
+  | Some({callsPerDuration, durationMs}) =>
+    Some(
+      switch self.rateLimits->Utils.Dict.dangerouslyGetNonOption(tableName) {
+      | Some(existing) => existing
+      | None =>
+        let created: effectRateLimitState = {
+          callsPerDuration,
+          durationMs,
+          availableCalls: callsPerDuration,
+          windowStartTime: Date.now(),
+          queueCount: 0,
+          nextWindowPromise: None,
+        }
+        self.rateLimits->Dict.set(tableName, created)
+        created
+      },
+    )
+  }
+
+// Get, or lazily create, the in-mem table for an (effect, scope). A recreated
+// table (e.g. after a rollback) reuses the surviving rate-limit window.
+let getTable = (self: t, ~effect: Internal.effect, ~scope: Internal.chainScope) => {
+  let tableName = Internal.EffectCache.toTableName(~effectName=effect.name, ~scope)
+  switch self.tables->Utils.Dict.dangerouslyGetNonOption(tableName) {
+  | Some(inMemTable) => inMemTable
+  | None =>
+    let inMemTable: effectCacheInMemTable = {
+      idsToStore: [],
+      dict: Dict.make(),
+      changesCount: 0.,
+      invalidationsCount: 0,
+      effect,
+      scope,
+      table: Internal.makeCacheTable(~effectName=effect.name, ~scope),
+      rateLimitState: self->getRateLimitState(~tableName, ~effect),
+      activeCallsCount: 0,
+      prevCallStartTimerRef: %raw(`null`),
+    }
+    self.tables->Dict.set(tableName, inMemTable)
+    inMemTable
+  }
+}
+
+let forEach = (self: t, fn) => self.tables->Utils.Dict.forEach(fn)
+
+// Drop the cache tables (re-derivable from the db) but keep the rate-limit
+// windows so a reorg doesn't hand an effect a fresh budget.
+let resetForRollback = (self: t) => self.tables = Dict.make()