envio 3.3.0-alpha.9 → 3.3.0

package/src/HandlerRegister.res

@@ -679,7 +679,9 @@ let finishRegistration = (~config: Config.t): registrationsByChainId => {
                   config.ecosystem.name === Evm &&
                     (registration->getResolvedWhere).topicSelections->Utils.Array.isEmpty
                 if !isDroppedByWhere {
-                  onEventRegistrations->Array.push(registration)
+                  onEventRegistrations
+                  ->Array.push({...registration, index: onEventRegistrations->Array.length})
+                  ->ignore
                 }
               | None => ()
               }

package/src/HandlerRegister.res.mjs

@@ -388,10 +388,11 @@ function finishRegistration(config) {
           return;
         }
         let isDroppedByWhere = config.ecosystem.name === "evm" && Utils.$$Array.isEmpty(registration$1.resolvedWhere.topicSelections);
-        if (!isDroppedByWhere) {
-          onEventRegistrations.push(registration$1);
+        if (isDroppedByWhere) {
           return;
         }
+        let newrecord = {...registration$1};
+        onEventRegistrations.push((newrecord.index = onEventRegistrations.length, newrecord));
       });
     });
     registrationsByChainId[key] = {

package/src/InMemoryStore.res

@@ -8,25 +8,13 @@ let getInMemTable = (
 ): InMemoryTable.Entity.t =>
   state->IndexerState.entities->IndexerState.EntityTables.get(~entityName=entityConfig.name)
 
-let getEffectInMemTable = (state: IndexerState.t, ~effect: Internal.effect) => {
-  let key = effect.name
-  let effects = state->IndexerState.effects
-  switch effects->Utils.Dict.dangerouslyGetNonOption(key) {
-  | Some(table) => table
-  | None =>
-    let table: IndexerState.effectCacheInMemTable = {
-      idsToStore: [],
-      dict: Dict.make(),
-      changesCount: 0.,
-      invalidationsCount: 0,
-      effect,
-    }
-    effects->Dict.set(key, table)
-    table
-  }
-}
+let getEffectInMemTable = (
+  state: IndexerState.t,
+  ~effect: Internal.effect,
+  ~scope: Internal.chainScope,
+) => state->IndexerState.effectState->EffectState.getTable(~effect, ~scope)
 
-let hasEffectOutput = (inMemTable: IndexerState.effectCacheInMemTable, key) =>
+let hasEffectOutput = (inMemTable: EffectState.effectCacheInMemTable, key) =>
   switch inMemTable.dict->Utils.Dict.dangerouslyGetNonOption(key) {
   | Some(Set(_)) => true
   | Some(Delete(_)) | None => false
@@ -36,7 +24,7 @@ let hasEffectOutput = (inMemTable: IndexerState.effectCacheInMemTable, key) =>
 // optional output, so it must never be wrapped in another option here: Some(None)
 // is encoded as the nested-option sentinel and would leak to the handler.
 let getEffectOutputUnsafe = (
-  inMemTable: IndexerState.effectCacheInMemTable,
+  inMemTable: EffectState.effectCacheInMemTable,
   key,
 ): Internal.effectOutput =>
   switch inMemTable.dict->Utils.Dict.dangerouslyGetNonOption(key) {
@@ -47,7 +35,7 @@ let getEffectOutputUnsafe = (
 // Records a handler output. Persisted on the next write only when shouldCache;
 // otherwise kept in memory (re-run on a later miss) but never written to the db.
 let setEffectOutput = (
-  inMemTable: IndexerState.effectCacheInMemTable,
+  inMemTable: EffectState.effectCacheInMemTable,
   ~checkpointId,
   ~cacheKey,
   ~output,
@@ -65,7 +53,7 @@ let setEffectOutput = (
 
 // Seeds an entry from a db read. Stamped with loadedFromDbCheckpointId so it's
 // always droppable (re-readable from the db) and never re-persisted.
-let initEffectOutputFromDb = (inMemTable: IndexerState.effectCacheInMemTable, ~cacheKey, ~output) =>
+let initEffectOutputFromDb = (inMemTable: EffectState.effectCacheInMemTable, ~cacheKey, ~output) =>
   if inMemTable.dict->Utils.Dict.dangerouslyGetNonOption(cacheKey)->Option.isNone {
     inMemTable.changesCount = inMemTable.changesCount +. 1.
     inMemTable.dict->Dict.set(
@@ -78,7 +66,7 @@ let initEffectOutputFromDb = (inMemTable: IndexerState.effectCacheInMemTable, ~c
 // cache:false). Uncommitted entries stay warm. With keepLoadedFromDb, entries
 // seeded from a db read are spared. Mirrors entity dropCommittedChanges.
 let dropCommittedEffects = (
-  inMemTable: IndexerState.effectCacheInMemTable,
+  inMemTable: EffectState.effectCacheInMemTable,
   ~committedCheckpointId,
   ~keepLoadedFromDb,
 ) => {
@@ -117,17 +105,17 @@ let prepareRollbackDiff = async (
   ->Array.map(async entityConfig => {
     let entityTable = state->getInMemTable(~entityConfig)
 
-    let (removedIdsResult, restoredEntitiesResult) = await persistence.storage.getRollbackData(
+    let (removedIds, restoredEntitiesResult) = await persistence.storage.getRollbackData(
       ~entityConfig,
       ~rollbackTargetCheckpointId,
     )
 
-    removedIdsResult->Array.forEach(data => {
-      deletedEntities->Utils.Dict.push(entityConfig.name, data["id"])
+    removedIds->Array.forEach(entityId => {
+      deletedEntities->Utils.Dict.push(entityConfig.name, entityId)
       entityTable->InMemoryTable.Entity.set(
         ~committedCheckpointId,
         Delete({
-          entityId: data["id"],
+          entityId,
           checkpointId: rollbackDiffCheckpointId,
         }),
       )

package/src/InMemoryStore.res.mjs

@@ -4,6 +4,7 @@ import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Config from "./Config.res.mjs";
 import * as Internal from "./Internal.res.mjs";
+import * as EffectState from "./EffectState.res.mjs";
 import * as IndexerState from "./IndexerState.res.mjs";
 import * as InMemoryTable from "./InMemoryTable.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
@@ -13,22 +14,8 @@ function getInMemTable(state, entityConfig) {
   return IndexerState.EntityTables.get(IndexerState.entities(state), entityConfig.name);
 }
 
-function getEffectInMemTable(state, effect) {
-  let key = effect.name;
-  let effects = IndexerState.effects(state);
-  let table = effects[key];
-  if (table !== undefined) {
-    return table;
-  }
-  let table$1 = {
-    idsToStore: [],
-    invalidationsCount: 0,
-    dict: {},
-    changesCount: 0,
-    effect: effect
-  };
-  effects[key] = table$1;
-  return table$1;
+function getEffectInMemTable(state, effect, scope) {
+  return EffectState.getTable(IndexerState.effectState(state), effect, scope);
 }
 
 function hasEffectOutput(inMemTable, key) {
@@ -102,11 +89,11 @@ async function prepareRollbackDiff(state, rollbackTargetCheckpointId, rollbackDi
   await Promise.all(persistence.allEntities.map(async entityConfig => {
     let entityTable = getInMemTable(state, entityConfig);
     let match = await persistence.storage.getRollbackData(entityConfig, rollbackTargetCheckpointId);
-    match[0].forEach(data => {
-      Utils.Dict.push(deletedEntities, entityConfig.name, data.id);
+    match[0].forEach(entityId => {
+      Utils.Dict.push(deletedEntities, entityConfig.name, entityId);
       InMemoryTable.Entity.set(entityTable, committedCheckpointId, {
         type: "DELETE",
-        entityId: data.id,
+        entityId: entityId,
         checkpointId: rollbackDiffCheckpointId
       });
     });

package/src/IndexerState.res

@@ -6,23 +6,6 @@ type rollbackState =
   | FoundReorgDepth({chain: chain, rollbackTargetBlockNumber: int})
   | RollbackReady({eventsProcessedDiffByChain: dict<float>})
 
-module WriteThrottlers = {
-  type t = {pruneStaleEntityHistory: Throttler.t}
-  let make = (): t => {
-    let pruneStaleEntityHistory = {
-      let intervalMillis = Env.ThrottleWrites.pruneStaleDataIntervalMillis
-      let logger = Logging.createChild(
-        ~params={
-          "context": "Throttler for pruning stale entity history data",
-          "intervalMillis": intervalMillis,
-        },
-      )
-      Throttler.make(~intervalMillis, ~logger)
-    }
-    {pruneStaleEntityHistory: pruneStaleEntityHistory}
-  }
-}
-
 module EntityTables = {
   type t = dict<InMemoryTable.Entity.t>
   exception UndefinedEntity({entityName: string})
@@ -45,26 +28,13 @@ module EntityTables = {
   }
 }
 
-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,
-}
-
 type t = {
   config: Config.t,
   persistence: Persistence.t,
   // --- In-memory store: entity/effect tables and the pending-write queue. ---
   allEntities: array<Internal.entityConfig>,
   mutable entities: EntityTables.t,
-  mutable effects: dict<effectCacheInMemTable>,
+  effectState: EffectState.t,
   mutable rollback: option<Persistence.rollback>,
   // Last checkpoint persisted to the db.
   mutable committedCheckpointId: Internal.checkpointId,
@@ -94,7 +64,9 @@ type t = {
   crossChainState: CrossChainState.t,
   mutable rollbackState: rollbackState,
   indexerStartTime: Date.t,
-  writeThrottlers: WriteThrottlers.t,
+  // When an entity's history was last pruned. No key = never pruned yet,
+  // which counts as overdue.
+  lastPrunedAtMillis: dict<float>,
   loadManager: LoadManager.t,
   keepProcessAlive: bool,
   exitAfterFirstEventBlock: bool,
@@ -143,7 +115,7 @@ let make = (
     persistence,
     allEntities: persistence.allEntities,
     entities: EntityTables.make(persistence.allEntities),
-    effects: Dict.make(),
+    effectState: EffectState.make(),
     rollback: None,
     committedCheckpointId,
     processedCheckpointId: committedCheckpointId,
@@ -164,7 +136,7 @@ let make = (
     ),
     indexerStartTime: Date.make(),
     rollbackState: NoRollback,
-    writeThrottlers: WriteThrottlers.make(),
+    lastPrunedAtMillis: Dict.make(),
     loadManager: LoadManager.make(),
     keepProcessAlive: isDevelopmentMode || shouldUseTui,
     exitAfterFirstEventBlock,
@@ -211,8 +183,12 @@ let makeFromDbState = (
 
   Prometheus.ProcessingMaxBatchSize.set(~maxBatchSize=config.batchSize)
   Prometheus.ReorgThreshold.set(~isInReorgThreshold)
-  initialState.cache->Utils.Dict.forEach(({effectName, count}) => {
-    Prometheus.EffectCacheCount.set(~count, ~effectName)
+  initialState.cache->Utils.Dict.forEach(({effectName, count, scope}) => {
+    Prometheus.EffectCacheCount.set(
+      ~count,
+      ~effectName,
+      ~scope=scope->Internal.EffectCache.scopeToString,
+    )
   })
 
   // updateSyncTimeOnRestart wipes the saved timestamp so a restart re-enters
@@ -385,7 +361,7 @@ let config = (state: t) => state.config
 let persistence = (state: t) => state.persistence
 let allEntities = (state: t) => state.allEntities
 let entities = (state: t) => state.entities
-let effects = (state: t) => state.effects
+let effectState = (state: t) => state.effectState
 let committedCheckpointId = (state: t) => state.committedCheckpointId
 let processedCheckpointId = (state: t) => state.processedCheckpointId
 let processedBatches = (state: t) => state.processedBatches
@@ -405,7 +381,7 @@ let keepProcessAlive = (state: t) => state.keepProcessAlive
 let exitAfterFirstEventBlock = (state: t) => state.exitAfterFirstEventBlock
 let isStopped = (state: t) => state.isStopped
 let epoch = (state: t) => state.epoch
-let pruneStaleEntityHistoryThrottler = (state: t) => state.writeThrottlers.pruneStaleEntityHistory
+let lastPrunedAtMillis = (state: t) => state.lastPrunedAtMillis
 let simulateDeadInputTracker = (state: t) => state.simulateDeadInputTracker
 
 // --- Store domain operations. ---
@@ -485,7 +461,7 @@ let beginRollbackDiff = (
   ~progressBlockNumberByChainId,
 ) => {
   state.entities = EntityTables.make(state.allEntities)
-  state.effects = Dict.make()
+  state.effectState->EffectState.resetForRollback
   state.rollback = Some({
     targetCheckpointId,
     diffCheckpointId,

package/src/IndexerState.res.mjs

@@ -9,6 +9,7 @@ import * as Internal from "./Internal.res.mjs";
 import * as Throttler from "./Throttler.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
 import * as Prometheus from "./Prometheus.res.mjs";
+import * as EffectState from "./EffectState.res.mjs";
 import * as LoadManager from "./LoadManager.res.mjs";
 import * as ErrorHandling from "./ErrorHandling.res.mjs";
 import * as InMemoryTable from "./InMemoryTable.res.mjs";
@@ -20,21 +21,9 @@ import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as SimulateDeadInputTracker from "./SimulateDeadInputTracker.res.mjs";
 
-function make() {
-  let intervalMillis = Env.ThrottleWrites.pruneStaleDataIntervalMillis;
-  let logger = Logging.createChild({
-    context: "Throttler for pruning stale entity history data",
-    intervalMillis: intervalMillis
-  });
-  let pruneStaleEntityHistory = Throttler.make(intervalMillis, logger);
-  return {
-    pruneStaleEntityHistory: pruneStaleEntityHistory
-  };
-}
-
 let UndefinedEntity = /* @__PURE__ */Primitive_exceptions.create("IndexerState.EntityTables.UndefinedEntity");
 
-function make$1(entities) {
+function make(entities) {
   let init = {};
   entities.forEach(entityConfig => {
     init[entityConfig.name] = InMemoryTable.Entity.make();
@@ -54,7 +43,7 @@ function get(self, entityName) {
   }
 }
 
-function make$2(config, persistence, chainStates, isInReorgThreshold, isRealtime, targetBufferSizeOpt, committedCheckpointIdOpt, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, onError) {
+function make$1(config, persistence, chainStates, isInReorgThreshold, isRealtime, targetBufferSizeOpt, committedCheckpointIdOpt, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, onError) {
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : CrossChainState.calculateTargetBufferSize();
   let committedCheckpointId = committedCheckpointIdOpt !== undefined ? committedCheckpointIdOpt : Internal.initialCheckpointId;
   let isDevelopmentMode = isDevelopmentModeOpt !== undefined ? isDevelopmentModeOpt : false;
@@ -69,8 +58,8 @@ function make$2(config, persistence, chainStates, isInReorgThreshold, isRealtime
     config: config,
     persistence: persistence,
     allEntities: persistence.allEntities,
-    entities: make$1(persistence.allEntities),
-    effects: {},
+    entities: make(persistence.allEntities),
+    effectState: EffectState.make(),
     rollback: undefined,
     committedCheckpointId: committedCheckpointId,
     processedCheckpointId: committedCheckpointId,
@@ -86,7 +75,7 @@ function make$2(config, persistence, chainStates, isInReorgThreshold, isRealtime
     crossChainState: CrossChainState.make(chainStates, isInReorgThreshold, isRealtime, targetBufferSize),
     rollbackState: "NoRollback",
     indexerStartTime: new Date(),
-    writeThrottlers: make(),
+    lastPrunedAtMillis: {},
     loadManager: LoadManager.make(),
     keepProcessAlive: isDevelopmentMode || shouldUseTui,
     exitAfterFirstEventBlock: exitAfterFirstEventBlock,
@@ -116,7 +105,7 @@ function makeFromDbState(config, persistence, initialState, registrationsByChain
   Prometheus.ReorgThreshold.set(isInReorgThreshold);
   Utils.Dict.forEach(initialState.cache, param => {
     let count = param.count;
-    Prometheus.EffectCacheCount.set(count, param.effectName);
+    Prometheus.EffectCacheCount.set(count, param.effectName, Internal.EffectCache.scopeToString(param.scope));
   });
   let isRealtime = !Env.updateSyncTimeOnRestart && initialState.chains.length !== 0 && initialState.chains.every(c => Stdlib_Option.isSome(c.timestampCaughtUpToHeadOrEndblock));
   let chainStates = {};
@@ -142,7 +131,7 @@ function makeFromDbState(config, persistence, initialState, registrationsByChain
   if (allChainsReady.contents) {
     Prometheus.ProgressReady.setAllReady();
   }
-  return make$2(config, persistence, chainStates, isInReorgThreshold, isRealtime, targetBufferSize, initialState.checkpointId, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError);
+  return make$1(config, persistence, chainStates, isInReorgThreshold, isRealtime, targetBufferSize, initialState.checkpointId, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError);
 }
 
 function isStale(state, stateId) {
@@ -266,8 +255,8 @@ function entities(state) {
   return state.entities;
 }
 
-function effects(state) {
-  return state.effects;
+function effectState(state) {
+  return state.effectState;
 }
 
 function committedCheckpointId(state) {
@@ -346,8 +335,8 @@ function epoch(state) {
   return state.epoch;
 }
 
-function pruneStaleEntityHistoryThrottler(state) {
-  return state.writeThrottlers.pruneStaleEntityHistory;
+function lastPrunedAtMillis(state) {
+  return state.lastPrunedAtMillis;
 }
 
 function simulateDeadInputTracker(state) {
@@ -418,8 +407,8 @@ function markCommitted(state, upToCheckpointId) {
 }
 
 function beginRollbackDiff(state, targetCheckpointId, diffCheckpointId, progressBlockNumberByChainId) {
-  state.entities = make$1(state.allEntities);
-  state.effects = {};
+  state.entities = make(state.allEntities);
+  EffectState.resetForRollback(state.effectState);
   state.rollback = {
     targetCheckpointId: targetCheckpointId,
     diffCheckpointId: diffCheckpointId,
@@ -478,7 +467,7 @@ function takeChainMetaSnapshot(state) {
 }
 
 let EntityTables = {
-  make: make$1,
+  make: make,
   get: get
 };
 
@@ -486,7 +475,7 @@ let unexpectedErrorMsg = "Indexer has failed with an unexpected error";
 
 export {
   EntityTables,
-  make$2 as make,
+  make$1 as make,
   makeFromDbState,
   unexpectedErrorMsg,
   isStale,
@@ -512,7 +501,7 @@ export {
   persistence,
   allEntities,
   entities,
-  effects,
+  effectState,
   committedCheckpointId,
   processedCheckpointId,
   processedBatches,
@@ -532,7 +521,7 @@ export {
   exitAfterFirstEventBlock,
   isStopped,
   epoch,
-  pruneStaleEntityHistoryThrottler,
+  lastPrunedAtMillis,
   simulateDeadInputTracker,
   queueProcessedBatch,
   drainBatchRun,

package/src/IndexerState.resi

@@ -16,14 +16,6 @@ module EntityTables: {
   let get: (t, ~entityName: string) => InMemoryTable.Entity.t
 }
 
-type effectCacheInMemTable = {
-  mutable idsToStore: array<string>,
-  mutable invalidationsCount: int,
-  mutable dict: dict<Change.t<Internal.effectOutput>>,
-  mutable changesCount: float,
-  effect: Internal.effect,
-}
-
 type t
 
 let make: (
@@ -86,7 +78,7 @@ let config: t => Config.t
 let persistence: t => Persistence.t
 let allEntities: t => array<Internal.entityConfig>
 let entities: t => EntityTables.t
-let effects: t => dict<effectCacheInMemTable>
+let effectState: t => EffectState.t
 let committedCheckpointId: t => Internal.checkpointId
 let processedCheckpointId: t => Internal.checkpointId
 let processedBatches: t => array<Batch.t>
@@ -106,7 +98,7 @@ let keepProcessAlive: t => bool
 let exitAfterFirstEventBlock: t => bool
 let isStopped: t => bool
 let epoch: t => int
-let pruneStaleEntityHistoryThrottler: t => Throttler.t
+let lastPrunedAtMillis: t => dict<float>
 let simulateDeadInputTracker: t => option<SimulateDeadInputTracker.t>
 
 // Store domain operations.

package/src/Internal.res

@@ -330,6 +330,9 @@ type eventPayload
 @get external getPayloadBlock: eventPayload => Nullable.t<eventBlock> = "block"
 @set external setPayloadBlock: (eventPayload, eventBlock) => unit = "block"
 
+// The log's emitting address (EVM/Fuel; the program id carries it for SVM).
+@get external getPayloadSrcAddress: eventPayload => Address.t = "srcAddress"
+
 type genericLoaderArgs<'event, 'context> = {
   event: 'event,
   context: 'context,
@@ -555,6 +558,11 @@ type svmInstructionEventConfig = {
 // must stay directly constructable), and the evm→base cast in sources is sound
 // by ecosystem homogeneity — an EVM chain only ever holds `evmOnEventRegistration`s.
 type onEventRegistration = {
+  // Chain-scoped sequential index — the registration's position in the
+  // chain's onEventRegistrations array, assigned when registration finishes
+  // (-1 until then). Native-routed items reference their registration by this
+  // index across the napi boundary; sources resolve it before creating an item.
+  index: int,
   eventConfig: eventConfig,
   handler: option<handler>,
   contractRegister: option<contractRegister>,
@@ -601,8 +609,9 @@ type indexingAddress = {
 
 type dcs = array<indexingAddress>
 
-// Duplicate the type from item
-// to make item properly unboxed
+// Duplicate the type from item to keep item properly unboxed. Runtime event
+// items carry the registration their source already resolved from the
+// ChainState-owned registration array.
 type eventItem = private {
   kind: [#0],
   onEventRegistration: onEventRegistration,
@@ -743,33 +752,108 @@ type effectCacheItem = {id: string, output: effectOutput}
 type effectCacheStorageMeta = {
   itemSchema: S.t<effectCacheItem>,
   outputSchema: S.t<effectOutput>,
-  table: Table.table,
 }
-type rateLimitState = {
+type rateLimitOptions = {
   callsPerDuration: int,
   durationMs: int,
-  mutable availableCalls: int,
-  mutable windowStartTime: float,
-  mutable queueCount: int,
-  mutable nextWindowPromise: option<promise<unit>>,
 }
 type effect = {
   name: string,
   handler: effectArgs => promise<effectOutput>,
   storageMeta: effectCacheStorageMeta,
   defaultShouldCache: bool,
+  // When true (the default) a single cache is shared across every chain and the
+  // handler must not read context.chain. When false the cache is isolated per
+  // chain and context.chain.id is available.
+  crossChain: bool,
   output: S.t<effectOutput>,
   input: S.t<effectInput>,
-  // The number of functions that are currently running.
-  mutable activeCallsCount: int,
-  mutable prevCallStartTimerRef: Performance.timeRef,
-  rateLimit: option<rateLimitState>,
+  rateLimit: option<rateLimitOptions>,
 }
+
+// Whether some piece of data (currently an effect cache; entities in a future
+// version) is shared across every chain or isolated to a single chain. Unboxed:
+// `CrossChain` is the string "crossChain" and `Chain(id)` is the raw chain id,
+// discriminated by runtime type.
+@unboxed
+type chainScope =
+  | @as("crossChain") CrossChain
+  | Chain(int)
+
 let cacheTablePrefix = "envio_effect_"
+
+// The single reversible mapping between an effect's (name, scope) and its
+// canonical Postgres cache-table name and .envio/cache file path. Everything
+// that needs a cache address goes through here instead of slicing prefixes.
+//   CrossChain  ->  envio_effect_<name>        <name>.tsv
+//   Chain(1)    ->  envio_1_effect_<name>      1/<name>.tsv
+//   Chain(137)  ->  envio_137_effect_<name>    137/<name>.tsv
+module EffectCache = {
+  let toTableName = (~effectName, ~scope) =>
+    switch scope {
+    | CrossChain => cacheTablePrefix ++ effectName
+    | Chain(chainId) => `envio_${chainId->Int.toString}_effect_${effectName}`
+    }
+
+  // "crossChain" or the decimal chain id. Used as the `scope` Prometheus label.
+  let scopeToString = scope =>
+    switch scope {
+    | CrossChain => "crossChain"
+    | Chain(chainId) => chainId->Int.toString
+    }
+
+  // Only accepts a canonical decimal chain id ("7", not "007" or "1foo") —
+  // Int.fromString alone follows parseInt semantics and accepts both.
+  let parseChainId = str =>
+    switch Int.fromString(str) {
+    | Some(chainId) if chainId >= 0 && chainId->Int.toString === str => Some(chainId)
+    | _ => None
+    }
+
+  let chainScopedRe = /^envio_([0-9]+)_effect_(.+)$/
+  let crossChainRe = /^envio_effect_(.+)$/
+
+  // Inverse of toTableName. Returns None for any table name that isn't a cache
+  // table. Chain-scoped is tried first: the `_effect_` separator keeps effect
+  // names that themselves start with digits unambiguous.
+  let fromTableName = (tableName): option<(string, chainScope)> =>
+    switch RegExp.exec(chainScopedRe, tableName) {
+    | Some(result) =>
+      switch (
+        RegExp.Result.matches(result)->Array.get(0),
+        RegExp.Result.matches(result)->Array.get(1),
+      ) {
+      | (Some(Some(chainIdStr)), Some(Some(effectName))) =>
+        switch parseChainId(chainIdStr) {
+        | Some(chainId) => Some((effectName, Chain(chainId)))
+        | None => None
+        }
+      | _ => None
+      }
+    | None =>
+      switch RegExp.exec(crossChainRe, tableName) {
+      | Some(result) =>
+        switch RegExp.Result.matches(result)->Array.get(0) {
+        | Some(Some(effectName)) => Some((effectName, CrossChain))
+        | _ => None
+        }
+      | None => None
+      }
+    }
+
+  // Relative posix path within .envio/cache. Chain-scoped caches live one
+  // directory level deep, named by chain id.
+  let toCachePath = (~effectName, ~scope) =>
+    switch scope {
+    | CrossChain => effectName ++ ".tsv"
+    | Chain(chainId) => `${chainId->Int.toString}/${effectName}.tsv`
+    }
+}
+
 let cacheOutputSchema = S.json(~validate=false)->(Utils.magic: S.t<JSON.t> => S.t<effectOutput>)
-let makeCacheTable = (~effectName) => {
+let makeCacheTable = (~effectName, ~scope) => {
   Table.mkTable(
-    cacheTablePrefix ++ effectName,
+    EffectCache.toTableName(~effectName, ~scope),
     ~fields=[
       Table.mkField("id", String, ~fieldSchema=S.string, ~isPrimaryKey=true),
       Table.mkField("output", Json, ~fieldSchema=cacheOutputSchema, ~isNullable=true),