envio 3.3.0-alpha.9 → 3.3.0-rc.0

package/src/Core.res

@@ -10,9 +10,17 @@ type svmHypersyncClientCtor
 type hyperfuelClientCtor
 type transactionStoreCtor
 type blockStoreCtor
+type parseConfigYamlOptions = {
+  schema?: string,
+  env?: dict<string>,
+  files?: dict<string>,
+  isRescript?: bool,
+}
 
 type addon = {
   getConfigJson: (~configPath: Null.t<string>, ~directory: Null.t<string>) => string,
+  encodeIndexedTopic: (~abiType: string, ~value: unknown) => EvmTypes.Hex.t,
+  parseConfigYaml: (string, parseConfigYamlOptions) => string,
   runCli: (~args: array<string>, ~envioPackageDir: Null.t<string>) => promise<Null.t<string>>,
   @as("EvmHypersyncClient")
   evmHypersyncClient: evmHypersyncClientCtor,
@@ -197,6 +205,18 @@ let getConfigJson = (~configPath=?, ~directory=?) => {
   )
 }
 
+// Pure config entry point: no cwd, config file, schema file, .env, or process env lookup.
+// A supplied schema is authoritative; omitted or blank schema text means an empty schema.
+let parseConfigYaml = (~schema=?, ~env=?, ~files=?, ~isRescript=false, yaml) => {
+  let addon = getAddon()
+  addon.parseConfigYaml(yaml, {
+    ?schema,
+    ?env,
+    ?files,
+    isRescript,
+  })
+}
+
 let runCli = args => {
   let addon = getAddon()
   addon.runCli(~args, ~envioPackageDir=Null.make(envioPackageDir))

package/src/Core.res.mjs

@@ -180,6 +180,17 @@ function getConfigJson(configPath, directory) {
   return addon.getConfigJson(Stdlib_Null.fromOption(configPath), Stdlib_Null.fromOption(directory));
 }
 
+function parseConfigYaml(schema, env, files, isRescriptOpt, yaml) {
+  let isRescript = isRescriptOpt !== undefined ? isRescriptOpt : false;
+  let addon = getAddon();
+  return addon.parseConfigYaml(yaml, {
+    schema: schema,
+    env: env,
+    files: files,
+    isRescript: isRescript
+  });
+}
+
 function runCli(args) {
   let addon = getAddon();
   return addon.runCli(args, envioPackageDir);
@@ -196,6 +207,7 @@ export {
   addonRef,
   getAddon,
   getConfigJson,
+  parseConfigYaml,
   runCli,
 }
 /* envioPackageDir Not a pure module */

package/src/CrossChainState.res

@@ -19,7 +19,7 @@ type t = {
 let calculateTargetBufferSize = () =>
   switch Env.targetBufferSize {
   | Some(size) => size
-  | None => 50_000
+  | None => 100_000
   }
 
 let make = (
@@ -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
@@ -190,6 +195,22 @@ let totalReservedSize = (crossChainState: t) => {
   total.contents
 }
 
+// Action for a chain that was handed budget but emitted no query (its budget
+// went to more-behind chains, or the alignment clamp cut its range to
+// nothing). 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. Any other chain must keep polling for new blocks instead
+// of going silent: NothingToQuery isn't dispatched, and with the pool
+// unsaturated nothing else guarantees a tick that would revisit it, so its
+// head tracking would freeze.
+let idleOrWaitAction = (cs: ChainState.t) =>
+  cs->ChainState.isFetchingAtHead ||
+  cs->ChainState.pendingBudget > 0. ||
+  cs->ChainState.bufferReadyCount > 0
+    ? FetchState.NothingToQuery
+    : FetchState.WaitingForNewBlock
+
 // Dispatch a fetch tick across the whole indexer from one shared pool of
 // ~targetBufferSize ready events, as a waterfall: visit chains furthest-behind
 // first, hand each the budget remaining at that point (plus its own
@@ -198,57 +219,117 @@ 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. 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
+
+  // Server-cap floor for bounded queries: their block range is already the
+  // hard bound on the response, so a low density estimate shrinking the cap
+  // below this only buys self-truncated responses. Splitting the target pool
+  // across a chain's concurrency slots keeps the worst case — every in-flight
+  // bounded query returning a full floored response at once — at ~one buffer
+  // target.
+  let itemsTargetFloor = crossChainState.targetBufferSize / FetchState.maxChainConcurrency
+
+  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.
+      // No height yet — there's nothing to size a query against, only height
+      // tracking to start. Checked before the admission floor so a chain that
+      // hasn't found its first block yet keeps polling even while other chains
+      // hold the whole pool. (The general can't-fetch-yet rule, including
+      // blockLag, lives in FetchState.getNextQuery — this branch only
+      // short-circuits the unambiguous no-height case.)
       actionByChain->Utils.Dict.setByInt(chainId, FetchState.WaitingForNewBlock)
+    } else if remaining.contents < minimumAdmissionBudget {
+      // More than 90% of the target pool is ready or reserved. Don't admit new
+      // queries until a full admission unit becomes free. No wake-up poll is
+      // needed: a saturated pool means some chain holds ready items or
+      // in-flight reservations, so a batch completion or landing response is
+      // guaranteed to schedule another tick that revisits this chain.
+      actionByChain->Utils.Dict.setByInt(chainId, FetchState.NothingToQuery)
     } else {
-      let chainTargetItems = remaining.contents +. cs->ChainState.pendingBudget
-      let maxTargetBlock = switch maxProgress.contents {
-      | None =>
-        // The most-behind chain sets the alignment line for everyone after it.
-        maxProgress :=
-          Some(
-            cs->ChainState.progressAtBlock(
-              ~blockNumber=cs->ChainState.targetBlock(~chainTargetItems),
-            ),
-          )
-        None
-      | Some(progress) => Some(cs->ChainState.blockAtProgress(~progress))
+      let isCold = cs->ChainState.effectiveDensity === None
+      let chainTargetItems =
+        (isCold ? Pervasives.min(remaining.contents, coldChainBudget) : remaining.contents) +.
+        cs->ChainState.pendingBudget
+      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, ~maxTargetBlock?) {
-      | (WaitingForNewBlock | NothingToQuery) as action =>
-        actionByChain->Utils.Dict.setByInt(chainId, action)
+      switch cs->ChainState.getNextQuery(
+        ~chainTargetItems,
+        ~chunkItemsMultiplier,
+        ~itemsTargetFloor,
+        ~maxTargetBlock?,
+      ) {
+      | WaitingForNewBlock as action => actionByChain->Utils.Dict.setByInt(chainId, action)
+      | NothingToQuery =>
+        // A chain below its head can emit no query when its budget went to
+        // more-behind chains or the cross-chain alignment clamped its range to
+        // nothing — idleOrWaitAction keeps it polling for new blocks.
+        actionByChain->Utils.Dict.setByInt(chainId, idleOrWaitAction(cs))
       | Ready(queries) => {
           let consumed =
             queries->Array.reduce(0., (acc, query: FetchState.query) =>
-              acc +. query.itemsTarget->Int.toFloat
+              acc +. query.itemsEst->Int.toFloat
             )
 
           let partitions = Dict.make()

package/src/CrossChainState.res.mjs

@@ -6,8 +6,11 @@ import * as Utils from "./Utils.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
+import * as FetchState from "./FetchState.res.mjs";
 import * as Prometheus from "./Prometheus.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.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";
 
@@ -15,13 +18,13 @@ function calculateTargetBufferSize() {
   if (Env.targetBufferSize !== undefined) {
     return Env.targetBufferSize;
   } else {
-    return 50000;
+    return 100000;
   }
 }
 
 function make(chainStates, isInReorgThreshold, isRealtime, targetBufferSizeOpt) {
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : (
-      Env.targetBufferSize !== undefined ? Env.targetBufferSize : 50000
+      Env.targetBufferSize !== undefined ? Env.targetBufferSize : 100000
     );
   let crossChainState = {
     chainStates: chainStates,
@@ -121,7 +124,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) {
@@ -133,34 +136,54 @@ function totalReservedSize(crossChainState) {
   return total;
 }
 
+function idleOrWaitAction(cs) {
+  if (ChainState.isFetchingAtHead(cs) || ChainState.pendingBudget(cs) > 0 || ChainState.bufferReadyCount(cs) > 0) {
+    return "NothingToQuery";
+  } else {
+    return "WaitingForNewBlock";
+  }
+}
+
 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 minimumAdmissionBudget = targetBudget * 0.1;
+  let chunkItemsMultiplier = crossChainState.isRealtime ? 3 : 1.5;
+  let itemsTargetFloor = Primitive_int.div(crossChainState.targetBufferSize, FetchState.maxChainConcurrency);
+  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 (ChainState.knownHeight(cs) === 0) {
       actionByChain[chainId] = "WaitingForNewBlock";
       return;
     }
-    let chainTargetItems = remaining.contents + ChainState.pendingBudget(cs);
-    let progress = maxProgress.contents;
-    let maxTargetBlock = progress !== undefined ? ChainState.blockAtProgress(cs, progress) : (maxProgress.contents = ChainState.progressAtBlock(cs, ChainState.targetBlock(cs, chainTargetItems)), undefined);
-    let action = ChainState.getNextQuery(cs, chainTargetItems, maxTargetBlock);
+    if (remaining.contents < minimumAdmissionBudget) {
+      actionByChain[chainId] = "NothingToQuery";
+      return;
+    }
+    let isCold = ChainState.effectiveDensity(cs) === undefined;
+    let chainTargetItems = (
+      isCold ? Primitive_float.min(remaining.contents, minimumAdmissionBudget) : remaining.contents
+    ) + ChainState.pendingBudget(cs);
+    let maxTargetBlock = alignment !== undefined && alignment[0] !== chainId ? ChainState.blockAtProgress(cs, alignment[1] + 0.05) : undefined;
+    let action = ChainState.getNextQuery(cs, chainTargetItems, chunkItemsMultiplier, itemsTargetFloor, maxTargetBlock);
     if (typeof action !== "object") {
       if (action === "WaitingForNewBlock") {
         actionByChain[chainId] = action;
         return;
       }
-      actionByChain[chainId] = action;
+      actionByChain[chainId] = idleOrWaitAction(cs);
       return;
     } else {
       let queries = action._0;
-      let consumed = Stdlib_Array.reduce(queries, 0, (acc, query) => acc + query.itemsTarget);
+      let consumed = Stdlib_Array.reduce(queries, 0, (acc, query) => acc + query.itemsEst);
       let partitions = {};
       queries.forEach(query => {
         partitions[query.partitionId] = {

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()

package/src/EffectState.res.mjs

@@ -0,0 +1,74 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Utils from "./Utils.res.mjs";
+import * as Internal from "./Internal.res.mjs";
+
+function make() {
+  return {
+    tables: {},
+    rateLimits: {}
+  };
+}
+
+function getRateLimitState(self, tableName, effect) {
+  let match = effect.rateLimit;
+  if (match === undefined) {
+    return;
+  }
+  let callsPerDuration = match.callsPerDuration;
+  let existing = self.rateLimits[tableName];
+  let tmp;
+  if (existing !== undefined) {
+    tmp = existing;
+  } else {
+    let created = {
+      callsPerDuration: callsPerDuration,
+      durationMs: match.durationMs,
+      availableCalls: callsPerDuration,
+      windowStartTime: Date.now(),
+      queueCount: 0,
+      nextWindowPromise: undefined
+    };
+    self.rateLimits[tableName] = created;
+    tmp = created;
+  }
+  return tmp;
+}
+
+function getTable(self, effect, scope) {
+  let tableName = Internal.EffectCache.toTableName(effect.name, scope);
+  let inMemTable = self.tables[tableName];
+  if (inMemTable !== undefined) {
+    return inMemTable;
+  }
+  let inMemTable$1 = {
+    idsToStore: [],
+    invalidationsCount: 0,
+    dict: {},
+    changesCount: 0,
+    effect: effect,
+    scope: scope,
+    table: Internal.makeCacheTable(effect.name, scope),
+    rateLimitState: getRateLimitState(self, tableName, effect),
+    activeCallsCount: 0,
+    prevCallStartTimerRef: null
+  };
+  self.tables[tableName] = inMemTable$1;
+  return inMemTable$1;
+}
+
+function forEach(self, fn) {
+  Utils.Dict.forEach(self.tables, fn);
+}
+
+function resetForRollback(self) {
+  self.tables = {};
+}
+
+export {
+  make,
+  getTable,
+  forEach,
+  resetForRollback,
+}
+/* Utils Not a pure module */

package/src/EffectState.resi

@@ -0,0 +1,32 @@
+type effectRateLimitState = {
+  callsPerDuration: int,
+  durationMs: int,
+  mutable availableCalls: int,
+  mutable windowStartTime: float,
+  mutable queueCount: int,
+  mutable nextWindowPromise: option<promise<unit>>,
+}
+
+type effectCacheInMemTable = {
+  mutable idsToStore: array<string>,
+  mutable invalidationsCount: int,
+  mutable dict: dict<Change.t<Internal.effectOutput>>,
+  mutable changesCount: float,
+  effect: Internal.effect,
+  scope: Internal.chainScope,
+  table: Table.table,
+  rateLimitState: option<effectRateLimitState>,
+  mutable activeCallsCount: int,
+  mutable prevCallStartTimerRef: Performance.timeRef,
+}
+
+// Opaque store of all per-(effect, scope) runtime state.
+type t
+
+let make: unit => t
+// Get, or lazily create, the in-mem table for an (effect, scope). Reuses the
+// surviving rate-limit window when the table is recreated after a rollback.
+let getTable: (t, ~effect: Internal.effect, ~scope: Internal.chainScope) => effectCacheInMemTable
+let forEach: (t, effectCacheInMemTable => unit) => unit
+// Drop the cache tables but keep the rate-limit windows across a rollback.
+let resetForRollback: t => unit

package/src/Envio.res

@@ -186,11 +186,19 @@ and effectOptions<'input, 'output> = {
   rateLimit: rateLimit,
   /** Whether the effect should be cached. */
   cache?: bool,
+  /** 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. */
+  crossChain?: bool,
 }
+and effectChain = {id: int}
 and effectContext = {
   log: logger,
   effect: 'input 'output. (effect<'input, 'output>, 'input) => promise<'output>,
   mutable cache: bool,
+  /** The chain the effect was called on. Only available on effects created with
+   `crossChain: false`; accessing it on a cross-chain effect throws. */
+  chain: effectChain,
 }
 and effectArgs<'input> = {
   input: 'input,
@@ -205,10 +213,23 @@ let durationToMs = (duration: rateLimitDuration) =>
   | Milliseconds(ms) => ms
   }
 
+// The name becomes both a Postgres cache-table suffix and a .envio/cache file
+// path segment. Path separators are excluded from the charset and a leading dot
+// is disallowed, so a name can never be "." / ".." or otherwise traverse out of
+// the cache dir; dots elsewhere are fine and keep existing names like
+// "token.metadata" working, since the (name, scope) <-> table <-> path mapping
+// stays reversible.
+let effectNameRe = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/
+
 let createEffect = (
   options: effectOptions<'input, 'output>,
   handler: effectArgs<'input> => promise<'output>,
 ) => {
+  if !(effectNameRe->RegExp.test(options.name)) {
+    JsError.throwWithMessage(
+      `Invalid effect name "${options.name}". Effect names may contain letters, numbers, underscores, hyphens and dots (but must not start with a dot or contain a path separator), because the name is used as the cache table name and cache file path.`,
+    )
+  }
   let outputSchema =
     S.schema(_ => options.output)->(Utils.magic: S.t<S.t<'output>> => S.t<Internal.effectOutput>)
   let itemSchema = S.schema((s): Internal.effectCacheItem => {
@@ -222,8 +243,6 @@ let createEffect = (
         Internal.effectOutput,
       >
     ),
-    activeCallsCount: 0,
-    prevCallStartTimerRef: %raw(`null`),
     // This is the way to make the createEffect API
     // work without the need for users to call S.schema themselves,
     // but simply pass the desired object/tuple/etc.
@@ -233,7 +252,6 @@ let createEffect = (
     ),
     output: outputSchema,
     storageMeta: {
-      table: Internal.makeCacheTable(~effectName=options.name),
       outputSchema,
       itemSchema,
     },
@@ -241,16 +259,16 @@ let createEffect = (
     | Some(true) => true
     | _ => false
     },
+    crossChain: switch options.crossChain {
+    | Some(false) => false
+    | _ => true
+    },
     rateLimit: switch options.rateLimit {
     | Disable => None
     | Enable({calls, per}) =>
       Some({
         callsPerDuration: calls,
         durationMs: per->durationToMs,
-        availableCalls: calls,
-        windowStartTime: Date.now(),
-        queueCount: 0,
-        nextWindowPromise: None,
       })
     },
   }->(Utils.magic: Internal.effect => effect<'input, 'output>)