envio 3.3.0-alpha.12 → 3.3.0-alpha.13

package/src/Envio.res.mjs

@@ -2,8 +2,8 @@
 
 import * as Address from "./Address.res.mjs";
 import * as Process from "process";
-import * as Internal from "./Internal.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 
 function durationToMs(duration) {
@@ -18,41 +18,36 @@ function durationToMs(duration) {
   }
 }
 
+let effectNameRe = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/;
+
 function createEffect(options, handler) {
+  if (!effectNameRe.test(options.name)) {
+    Stdlib_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$RescriptSchema.schema(param => options.output);
   let itemSchema = S$RescriptSchema.schema(s => ({
     id: s.m(S$RescriptSchema.string),
     output: s.m(outputSchema)
   }));
   let match = options.cache;
-  let match$1 = options.rateLimit;
+  let match$1 = options.crossChain;
+  let match$2 = options.rateLimit;
   let tmp;
-  if (match$1 === false) {
-    tmp = undefined;
-  } else {
-    let calls = match$1.calls;
-    tmp = {
-      callsPerDuration: calls,
-      durationMs: durationToMs(match$1.per),
-      availableCalls: calls,
-      windowStartTime: Date.now(),
-      queueCount: 0,
-      nextWindowPromise: undefined
-    };
-  }
+  tmp = match$2 === false ? undefined : ({
+      callsPerDuration: match$2.calls,
+      durationMs: durationToMs(match$2.per)
+    });
   return {
     name: options.name,
     handler: handler,
     storageMeta: {
       itemSchema: itemSchema,
-      outputSchema: outputSchema,
-      table: Internal.makeCacheTable(options.name)
+      outputSchema: outputSchema
     },
     defaultShouldCache: match !== undefined ? match : false,
+    crossChain: match$1 !== undefined ? match$1 : true,
     output: outputSchema,
     input: S$RescriptSchema.schema(param => options.input),
-    activeCallsCount: 0,
-    prevCallStartTimerRef: null,
     rateLimit: tmp
   };
 }
@@ -102,6 +97,7 @@ let TestHelpers = {
 
 export {
   durationToMs,
+  effectNameRe,
   createEffect,
   isNonInteractive,
   TestHelpers,

package/src/FetchState.res

@@ -1465,6 +1465,11 @@ let startFetchingQueries = ({optimizedPartitions}: t, ~queries: array<query>) =>
 // Most parallel in-flight chunk queries a single partition may have at once.
 let maxPendingChunksPerPartition = 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
+
 // Generates candidate queries for a gap range (a hole left between
 // completed/pending chunks, e.g. from an out-of-order partial response). Gaps
 // carry the range's low fromBlock, so the acceptance pass takes them before
@@ -1939,12 +1944,21 @@ let getNextQuery = (
     let streamCount = acceptanceStream->Array.length
     let remainingBudget = ref(chainTargetItems)
     let acceptIdx = ref(0)
-    while remainingBudget.contents > 0. && acceptIdx.contents < streamCount {
+    // In-flight queries count against the chain's concurrency cap alongside the
+    // ones accepted this tick; once the cap is reached no later candidate can be
+    // accepted (they're only later in fromBlock order), so the walk stops.
+    let usedConcurrency = ref(reservations->Array.length)
+    while (
+      remainingBudget.contents > 0. &&
+      acceptIdx.contents < streamCount &&
+      usedConcurrency.contents < maxChainConcurrency
+    ) {
       let (_, itemsEst, maybeQuery) = acceptanceStream->Array.getUnsafe(acceptIdx.contents)
       switch maybeQuery {
       | Some(query) =>
         let partitionIdx = partitionIndexById->Dict.getUnsafe(query.partitionId)
         queriesByPartitionIndex->Array.getUnsafe(partitionIdx)->Array.push(query)->ignore
+        usedConcurrency := usedConcurrency.contents + 1
       | None => ()
       }
       remainingBudget := remainingBudget.contents -. itemsEst->Int.toFloat

package/src/FetchState.res.mjs

@@ -1331,12 +1331,14 @@ function getNextQuery(param, chainTargetBlock, chainTargetItems, $staropt$star)
   let streamCount = acceptanceStream.length;
   let remainingBudget = chainTargetItems;
   let acceptIdx = 0;
-  while (remainingBudget > 0 && acceptIdx < streamCount) {
+  let usedConcurrency = reservations.length;
+  while (remainingBudget > 0 && acceptIdx < streamCount && usedConcurrency < 100) {
     let match$1 = acceptanceStream[acceptIdx];
     let maybeQuery = match$1[2];
     if (maybeQuery !== undefined) {
       let partitionIdx = partitionIndexById[maybeQuery.partitionId];
       queriesByPartitionIndex[partitionIdx].push(maybeQuery);
+      usedConcurrency = usedConcurrency + 1 | 0;
     }
     remainingBudget = remainingBudget - match$1[1];
     acceptIdx = acceptIdx + 1 | 0;
@@ -1769,6 +1771,8 @@ let blockItemLogIndex = 16777216;
 
 let maxPendingChunksPerPartition = 12;
 
+let maxChainConcurrency = 100;
+
 export {
   deriveContractNameByAddress,
   densityItemsTarget,
@@ -1794,6 +1798,7 @@ export {
   handleQueryResult,
   startFetchingQueries,
   maxPendingChunksPerPartition,
+  maxChainConcurrency,
   pushGapFillQueries,
   getNextQuery,
   hasReadyItem,

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

@@ -45,26 +45,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,
@@ -143,7 +130,7 @@ let make = (
     persistence,
     allEntities: persistence.allEntities,
     entities: EntityTables.make(persistence.allEntities),
-    effects: Dict.make(),
+    effectState: EffectState.make(),
     rollback: None,
     committedCheckpointId,
     processedCheckpointId: committedCheckpointId,
@@ -211,8 +198,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 +376,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
@@ -485,7 +476,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";
@@ -70,7 +71,7 @@ function make$2(config, persistence, chainStates, isInReorgThreshold, isRealtime
     persistence: persistence,
     allEntities: persistence.allEntities,
     entities: make$1(persistence.allEntities),
-    effects: {},
+    effectState: EffectState.make(),
     rollback: undefined,
     committedCheckpointId: committedCheckpointId,
     processedCheckpointId: committedCheckpointId,
@@ -116,7 +117,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 = {};
@@ -266,8 +267,8 @@ function entities(state) {
   return state.entities;
 }
 
-function effects(state) {
-  return state.effects;
+function effectState(state) {
+  return state.effectState;
 }
 
 function committedCheckpointId(state) {
@@ -419,7 +420,7 @@ function markCommitted(state, upToCheckpointId) {
 
 function beginRollbackDiff(state, targetCheckpointId, diffCheckpointId, progressBlockNumberByChainId) {
   state.entities = make$1(state.allEntities);
-  state.effects = {};
+  EffectState.resetForRollback(state.effectState);
   state.rollback = {
     targetCheckpointId: targetCheckpointId,
     diffCheckpointId: diffCheckpointId,
@@ -512,7 +513,7 @@ export {
   persistence,
   allEntities,
   entities,
-  effects,
+  effectState,
   committedCheckpointId,
   processedCheckpointId,
   processedBatches,

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>

package/src/Internal.res

@@ -752,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),

package/src/Internal.res.mjs

@@ -3,6 +3,8 @@
 import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Address from "./Address.res.mjs";
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 
 let allEvmBlockFields = [
@@ -166,10 +168,101 @@ let fuelTransferParamsSchema = S$RescriptSchema.schema(s => ({
 
 let cacheTablePrefix = "envio_effect_";
 
+function toTableName(effectName, scope) {
+  if (scope === "crossChain") {
+    return cacheTablePrefix + effectName;
+  } else {
+    return `envio_` + scope.toString() + `_effect_` + effectName;
+  }
+}
+
+function scopeToString(scope) {
+  if (scope === "crossChain") {
+    return "crossChain";
+  } else {
+    return scope.toString();
+  }
+}
+
+function parseChainId(str) {
+  let chainId = Stdlib_Int.fromString(str, undefined);
+  if (chainId !== undefined && chainId >= 0 && chainId.toString() === str) {
+    return chainId;
+  }
+}
+
+let chainScopedRe = /^envio_([0-9]+)_effect_(.+)$/;
+
+let crossChainRe = /^envio_effect_(.+)$/;
+
+function fromTableName(tableName) {
+  let result = chainScopedRe.exec(tableName);
+  if (result == null) {
+    let result$1 = crossChainRe.exec(tableName);
+    if (result$1 == null) {
+      return;
+    }
+    let match = result$1.slice(1)[0];
+    if (match === undefined) {
+      return;
+    }
+    let effectName = Primitive_option.valFromOption(match);
+    if (effectName !== undefined) {
+      return [
+        effectName,
+        "crossChain"
+      ];
+    } else {
+      return;
+    }
+  }
+  let match$1 = result.slice(1)[0];
+  let match$2 = result.slice(1)[1];
+  if (match$1 === undefined) {
+    return;
+  }
+  let chainIdStr = Primitive_option.valFromOption(match$1);
+  if (chainIdStr === undefined) {
+    return;
+  }
+  if (match$2 === undefined) {
+    return;
+  }
+  let effectName$1 = Primitive_option.valFromOption(match$2);
+  if (effectName$1 === undefined) {
+    return;
+  }
+  let chainId = parseChainId(chainIdStr);
+  if (chainId !== undefined) {
+    return [
+      effectName$1,
+      chainId
+    ];
+  }
+}
+
+function toCachePath(effectName, scope) {
+  if (scope === "crossChain") {
+    return effectName + ".tsv";
+  } else {
+    return scope.toString() + `/` + effectName + `.tsv`;
+  }
+}
+
+let EffectCache = {
+  toTableName: toTableName,
+  scopeToString: scopeToString,
+  parseChainId: parseChainId,
+  chainScopedRe: chainScopedRe,
+  crossChainRe: crossChainRe,
+  fromTableName: fromTableName,
+  toCachePath: toCachePath
+};
+
 let cacheOutputSchema = S$RescriptSchema.json(false);
 
-function makeCacheTable(effectName) {
-  return Table.mkTable(cacheTablePrefix + effectName, undefined, [
+function makeCacheTable(effectName, scope) {
+  return Table.mkTable(toTableName(effectName, scope), undefined, [
     Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined),
     Table.mkField("output", "Json", cacheOutputSchema, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined, undefined)
   ], undefined);
@@ -195,6 +288,7 @@ export {
   fuelSupplyParamsSchema,
   fuelTransferParamsSchema,
   cacheTablePrefix,
+  EffectCache,
   cacheOutputSchema,
   makeCacheTable,
   loadedFromDbCheckpointId,