envio 3.5.1 → 3.6.1

package/evm.schema.json

@@ -49,6 +49,13 @@
         }
       ]
     },
+    "disable_default_cross_chain": {
+      "description": "Make entities and effect caches per-chain instead of shared across every chain (recommended). Sharing then becomes explicit — add `@crossChain` to an entity in schema.graphql or `crossChain: true` to an effect. (default: false)",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
     "ecosystem": {
       "description": "Ecosystem of the project.",
       "anyOf": [

package/fuel.schema.json

@@ -49,6 +49,13 @@
         }
       ]
     },
+    "disable_default_cross_chain": {
+      "description": "Make entities and effect caches per-chain instead of shared across every chain (recommended). Sharing then becomes explicit — add `@crossChain` to an entity in schema.graphql or `crossChain: true` to an effect. (default: false)",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
     "ecosystem": {
       "description": "Ecosystem of the project.",
       "$ref": "#/$defs/EcosystemTag"

package/index.d.ts

@@ -48,8 +48,7 @@ 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`). */
+/** The chain an Effect was called on. Available only on chain-scoped effects. */
 export type EffectChain = {
   /** The chain id the effect handler was called on. */
   readonly id: number;
@@ -64,8 +63,8 @@ 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. */
+  /** The chain the effect was called on. Only available on chain-scoped
+   * effects; accessing it on a cross-chain effect throws. */
   readonly chain: EffectChain;
 };
 
@@ -93,9 +92,10 @@ export type EffectOptions<Input, Output> = {
   /** 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. */
+   * `true`, or to `false` when config.yaml sets
+   * `disable_default_cross_chain: 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;
 };
 
@@ -225,8 +225,10 @@ export function createEffect<
     /** 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. */
+     * `true`, or to `false` when config.yaml sets
+     * `disable_default_cross_chain: 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>
@@ -502,6 +504,8 @@ type IndexerConfigTypes = {
   };
   svm?: { chains: Record<string, { id: number }> };
   entities?: Record<string, object>;
+  // Union of the entity names whose rows belong to a single chain, or `never`.
+  perChainEntities?: string;
   enums?: Record<string, string>;
 };
 
@@ -1529,6 +1533,21 @@ type AddressRegistration = {
 type ConfigEntities<Config extends IndexerConfigTypes = GlobalConfig> =
   Config["entities"] extends Record<string, object> ? Config["entities"] : {};
 
+/** Entity names whose rows belong to a single chain. */
+type PerChainEntityNames<Config extends IndexerConfigTypes = GlobalConfig> =
+  Config extends { perChainEntities: infer Names extends string } ? Names : never;
+
+/** The row shape the chain-agnostic test-indexer operations exchange. A
+ * per-chain entity's row is only identified together with its chain, so the
+ * chain id travels alongside the entity fields. */
+type TestIndexerEntityRow<
+  Config extends IndexerConfigTypes,
+  Name,
+  Entity
+> = Name extends PerChainEntityNames<Config>
+  ? Entity & { readonly chainId: number }
+  : Entity;
+
 /** Entity operations available on test indexer for direct entity manipulation. */
 type TestIndexerEntityOperations<Entity> = {
   /** Get an entity by ID. Returns undefined if not found. */
@@ -1537,6 +1556,10 @@ type TestIndexerEntityOperations<Entity> = {
   readonly getOrThrow: (id: EntityId<Entity>, message?: string) => Promise<Entity>;
   /** Get all entities. */
   readonly getAll: () => Promise<Entity[]>;
+  /** Get the entities matching a filter. For a per-chain entity the filter
+   * accepts `chainId`, which is how an id present on several chains is
+   * narrowed to one. */
+  readonly getWhere: (filter: GetWhereFilter<Entity>) => Promise<Entity[]>;
   /** Set (create or update) an entity. */
   readonly set: (entity: Entity) => void;
 };
@@ -1711,7 +1734,7 @@ export type TestIndexerFromConfig<Config extends IndexerConfigTypes = GlobalConf
 } & SingleEcosystemTestChains<Config> & {
   /** Entity operations for direct manipulation outside of handlers. */
   readonly [K in keyof ConfigEntities<Config>]: TestIndexerEntityOperations<
-    ConfigEntities<Config>[K]
+    TestIndexerEntityRow<Config, K, ConfigEntities<Config>[K]>
   >;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.5.1",
+  "version": "3.6.1",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -69,10 +69,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.5.1",
-    "envio-linux-x64-musl": "3.5.1",
-    "envio-linux-arm64": "3.5.1",
-    "envio-darwin-x64": "3.5.1",
-    "envio-darwin-arm64": "3.5.1"
+    "envio-linux-x64": "3.6.1",
+    "envio-linux-x64-musl": "3.6.1",
+    "envio-linux-arm64": "3.6.1",
+    "envio-darwin-x64": "3.6.1",
+    "envio-darwin-arm64": "3.6.1"
   }
 }

package/src/ChainState.res

@@ -31,6 +31,10 @@ type t = {
   // then smoothed with an EMA on every batch (see applyBatchProgress). None
   // until the chain has processed at least one event.
   mutable chainDensity: option<float>,
+  // In-memory tables for the entities whose rows belong to a single chain.
+  // Empty in the default cross-chain mode, where every entity's table lives on
+  // the indexer instead.
+  mutable entities: EntityTables.t,
   mutable reorgDetection: ReorgDetection.t,
   mutable safeCheckpointTracking: option<SafeCheckpointTracking.t>,
   // Holds this chain's transactions (kept in Rust) keyed by (blockNumber,
@@ -96,11 +100,13 @@ let make = (
   ~chainDensity=None,
   ~blockStore=BlockStore.make(~ecosystem=Ecosystem.Evm, ~shouldChecksum=false),
   ~reorgThresholdReadyTolerance=100,
+  ~perChainEntities: array<Internal.entityConfig>=[],
   ~logger: Pino.t,
 ): t => {
   validateOnEventRegistrations(~chainId=chainConfig.id, onEventRegistrations)
   {
     logger,
+    entities: EntityTables.make(perChainEntities),
     onEventRegistrations,
     fetchState,
     addressStore,
@@ -318,6 +324,7 @@ let makeInternal = (
       ~chainReorgCheckpoints,
     ),
     ~committedProgressBlockNumber=progressBlockNumber,
+    ~perChainEntities=config.allEntities->EntityTables.perChain,
     ~timestampCaughtUpToHeadOrEndblock,
     ~numEventsProcessed,
     ~transactionStore=TransactionStore.make(
@@ -408,6 +415,11 @@ let makeFromDbState = (
 // --- Read accessors. ---
 
 let logger = (cs: t) => cs.logger
+let entities = (cs: t) => cs.entities
+
+// Rollback discards every uncommitted change, so this chain's partition is
+// rebuilt from scratch alongside the indexer's cross-chain one.
+let resetEntities = (cs: t, ~perChainEntities) => cs.entities = EntityTables.make(perChainEntities)
 let sourceManager = (cs: t) => cs.sourceManager
 let chainConfig = (cs: t) => cs.chainConfig
 let reorgDetection = (cs: t) => cs.reorgDetection
@@ -537,10 +549,16 @@ let targetBlock = (cs: t, ~chainTargetItems: float) => {
   let bufferBlockNumber = fetchState->FetchState.bufferBlockNumber
   switch cs->effectiveDensity {
   | Some(density) if density > 0. =>
-    Pervasives.min(
-      fetchCeiling,
-      bufferBlockNumber + Math.ceil(chainTargetItems /. density)->Float.toInt,
-    )
+    // Decided by comparison so no unbounded value is ever converted to int:
+    // at low densities chainTargetItems /. density exceeds the int range, and
+    // truncating it wraps negative — the target collapses below the frontier
+    // and the chain stops querying. The division only runs when its result is
+    // provably below the ceiling-bounded range.
+    if density *. (fetchCeiling - bufferBlockNumber)->Int.toFloat <= chainTargetItems {
+      fetchCeiling
+    } else {
+      bufferBlockNumber + Math.ceil(chainTargetItems /. density)->Float.toInt
+    }
   | _ => Pervasives.min(bufferBlockNumber + coldTargetRange, fetchCeiling)
   }
 }

package/src/ChainState.res.mjs

@@ -13,6 +13,7 @@ import * as BlockStore from "./sources/BlockStore.res.mjs";
 import * as FetchState from "./FetchState.res.mjs";
 import * as Stdlib_Null from "@rescript/runtime/lib/es6/Stdlib_Null.js";
 import * as AddressStore from "./sources/AddressStore.res.mjs";
+import * as EntityTables from "./EntityTables.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 SourceManager from "./sources/SourceManager.res.mjs";
@@ -49,7 +50,7 @@ function validateOnEventRegistrations(chainId, registrations) {
   });
 }
 
-function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, sourceManager, reorgDetection, committedProgressBlockNumber, safeCheckpointTrackingOpt, numEventsProcessedOpt, timestampCaughtUpToHeadOrEndblockOpt, isProgressAtHeadOpt, transactionStoreOpt, chainDensityOpt, blockStoreOpt, reorgThresholdReadyToleranceOpt, logger) {
+function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, sourceManager, reorgDetection, committedProgressBlockNumber, safeCheckpointTrackingOpt, numEventsProcessedOpt, timestampCaughtUpToHeadOrEndblockOpt, isProgressAtHeadOpt, transactionStoreOpt, chainDensityOpt, blockStoreOpt, reorgThresholdReadyToleranceOpt, perChainEntitiesOpt, logger) {
   let onEventRegistrations = onEventRegistrationsOpt !== undefined ? onEventRegistrationsOpt : [];
   let safeCheckpointTracking = safeCheckpointTrackingOpt !== undefined ? Primitive_option.valFromOption(safeCheckpointTrackingOpt) : undefined;
   let numEventsProcessed = numEventsProcessedOpt !== undefined ? numEventsProcessedOpt : 0;
@@ -59,6 +60,7 @@ function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, so
   let chainDensity = chainDensityOpt !== undefined ? Primitive_option.valFromOption(chainDensityOpt) : undefined;
   let blockStore = blockStoreOpt !== undefined ? Primitive_option.valFromOption(blockStoreOpt) : BlockStore.make("evm", false);
   let reorgThresholdReadyTolerance = reorgThresholdReadyToleranceOpt !== undefined ? reorgThresholdReadyToleranceOpt : 100;
+  let perChainEntities = perChainEntitiesOpt !== undefined ? perChainEntitiesOpt : [];
   validateOnEventRegistrations(chainConfig.id, onEventRegistrations);
   return {
     logger: logger,
@@ -74,6 +76,7 @@ function make(chainConfig, fetchState, onEventRegistrationsOpt, addressStore, so
     numEventsProcessed: numEventsProcessed,
     pendingBudget: 0,
     chainDensity: chainDensity,
+    entities: EntityTables.make(perChainEntities),
     reorgDetection: reorgDetection,
     safeCheckpointTracking: safeCheckpointTracking,
     transactionStore: transactionStore,
@@ -186,7 +189,7 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
   }
   let firstEventBlock$1 = fetchState.firstEventBlock;
   let chainDensity = firstEventBlock$1 !== undefined && progressBlockNumber > firstEventBlock$1 && numEventsProcessed > 0 ? numEventsProcessed / (progressBlockNumber - firstEventBlock$1 | 0) : undefined;
-  return make(chainConfig, fetchState, onEventRegistrations, addressStore, SourceManager.make(sources$1, isRealtime, undefined, undefined, undefined, reducedPollingInterval, undefined, undefined), ReorgDetection.make(chainReorgCheckpoints, maxReorgDepth, config.shouldRollbackOnReorg), progressBlockNumber, Primitive_option.some(SafeCheckpointTracking.make(maxReorgDepth, config.shouldRollbackOnReorg, chainReorgCheckpoints)), numEventsProcessed, Primitive_option.some(timestampCaughtUpToHeadOrEndblock), undefined, Primitive_option.some(TransactionStore.make(config.ecosystem.name, !lowercaseAddresses)), Primitive_option.some(chainDensity), Primitive_option.some(BlockStore.make(config.ecosystem.name, !lowercaseAddresses)), config.reorgThresholdReadyTolerance, logger);
+  return make(chainConfig, fetchState, onEventRegistrations, addressStore, SourceManager.make(sources$1, isRealtime, undefined, undefined, undefined, reducedPollingInterval, undefined, undefined), ReorgDetection.make(chainReorgCheckpoints, maxReorgDepth, config.shouldRollbackOnReorg), progressBlockNumber, Primitive_option.some(SafeCheckpointTracking.make(maxReorgDepth, config.shouldRollbackOnReorg, chainReorgCheckpoints)), numEventsProcessed, Primitive_option.some(timestampCaughtUpToHeadOrEndblock), undefined, Primitive_option.some(TransactionStore.make(config.ecosystem.name, !lowercaseAddresses)), Primitive_option.some(chainDensity), Primitive_option.some(BlockStore.make(config.ecosystem.name, !lowercaseAddresses)), config.reorgThresholdReadyTolerance, EntityTables.perChain(config.allEntities), logger);
 }
 
 function makeFromConfig(chainConfig, config, registrationsByChainId, knownHeight) {
@@ -209,6 +212,14 @@ function logger(cs) {
   return cs.logger;
 }
 
+function entities(cs) {
+  return cs.entities;
+}
+
+function resetEntities(cs, perChainEntities) {
+  cs.entities = EntityTables.make(perChainEntities);
+}
+
 function sourceManager(cs) {
   return cs.sourceManager;
 }
@@ -357,7 +368,11 @@ function targetBlock(cs, chainTargetItems) {
   let bufferBlockNumber = FetchState.bufferBlockNumber(fetchState);
   let density = effectiveDensity(cs);
   if (density !== undefined && density > 0) {
-    return Primitive_int.min(fetchCeiling$1, bufferBlockNumber + (Math.ceil(chainTargetItems / density) | 0) | 0);
+    if (density * (fetchCeiling$1 - bufferBlockNumber | 0) <= chainTargetItems) {
+      return fetchCeiling$1;
+    } else {
+      return bufferBlockNumber + (Math.ceil(chainTargetItems / density) | 0) | 0;
+    }
   } else {
     return Primitive_int.min(bufferBlockNumber + 20000 | 0, fetchCeiling$1);
   }
@@ -841,6 +856,8 @@ export {
   makeFromConfig,
   makeFromDbState,
   logger,
+  entities,
+  resetEntities,
   sourceManager,
   chainConfig,
   reorgDetection,

package/src/ChainState.resi

@@ -21,6 +21,7 @@ let make: (
   ~chainDensity: option<float>=?,
   ~blockStore: BlockStore.t=?,
   ~reorgThresholdReadyTolerance: int=?,
+  ~perChainEntities: array<Internal.entityConfig>=?,
   ~logger: Pino.t,
 ) => t
 
@@ -44,6 +45,8 @@ let makeFromDbState: (
 
 // Accessors.
 let logger: t => Pino.t
+let entities: t => EntityTables.t
+let resetEntities: (t, ~perChainEntities: array<Internal.entityConfig>) => unit
 let sourceManager: t => SourceManager.t
 let chainConfig: t => Config.chain
 let reorgDetection: t => ReorgDetection.t

package/src/Config.res

@@ -59,11 +59,26 @@ type sourceSync = {
   pollingInterval: int,
 }
 
+// How a backend spells column names, mirroring `column_name_format` in
+// config.yaml. Only the internal columns the runtime appends need it — user
+// field names arrive pre-resolved from the CLI.
+type columnNameFormat = | @as("original") Original | @as("snake_case") SnakeCase
+
 type storage = {
   postgres: bool,
   clickhouse: bool,
+  postgresColumnNameFormat: columnNameFormat,
+  clickhouseColumnNameFormat: columnNameFormat,
 }
 
+let chainIdFieldName = "chainId"
+
+let chainIdColumnName = format =>
+  switch format {
+  | Original => chainIdFieldName
+  | SnakeCase => "chain_id"
+  }
+
 type contractHandler = {
   name: string,
   handler: option<string>,
@@ -76,6 +91,10 @@ type t = {
   contractHandlers: array<contractHandler>,
   shouldRollbackOnReorg: bool,
   shouldSaveFullHistory: bool,
+  // False when `disable_default_cross_chain: true` in config.yaml. Entities
+  // carry their own resolved `crossChain`; this only decides the default for
+  // effects that don't state one.
+  defaultCrossChain: bool,
   storage: storage,
   // Widest scalar the internal chain-id columns need, resolved by the CLI from
   // the maximum active chain id. Older configs predate the field, and every id
@@ -161,6 +180,9 @@ module EnvioAddresses = {
     // always required to have Postgres enabled (Storage::resolve forbids
     // a Postgres-disabled global), so this is safe regardless of mode.
     storage: {postgres: true, clickhouse: false},
+    // The table already keys rows by chain through the composite `id`, so the
+    // per-chain mode must not append a second chain-id column to it.
+    crossChain: true,
   }->Internal.fromGenericEntityConfig
 }
 
@@ -353,6 +375,7 @@ let entityStorageSchema = S.schema(s =>
 let entityJsonSchema = S.schema(s =>
   {
     "name": s.matches(S.string),
+    "crossChain": s.matches(S.option(S.bool)),
     "storage": s.matches(S.option(entityStorageSchema)),
     "properties": s.matches(S.array(propertySchema)),
     "derivedFields": s.matches(S.option(S.array(derivedFieldSchema))),
@@ -424,13 +447,30 @@ let parseEnumsFromJson = (enumsJson: dict<array<string>>): array<Table.enumConfi
   )
 }
 
+// The chain-id column appended to a per-chain entity's table. It completes the
+// primary key so the same id can exist independently on every chain, and it's
+// spelled per backend because the two can be configured with different
+// `column_name_format`s.
+let makeChainIdField = (~globalStorage: storage) =>
+  Table.mkField(
+    chainIdFieldName,
+    ChainId,
+    ~fieldSchema=ChainId.schema,
+    ~isPrimaryKey=true,
+    ~isChainId=true,
+    ~postgresDbName=globalStorage.postgresColumnNameFormat->chainIdColumnName,
+    ~clickhouseDbName=globalStorage.clickhouseColumnNameFormat->chainIdColumnName,
+  )
+
 let parseEntitiesFromJson = (
   entitiesJson: array<'entityJson>,
   ~enumConfigsByName: dict<Table.enumConfig<Table.enum>>,
   ~globalStorage: storage,
+  ~defaultCrossChain: bool,
 ): array<Internal.entityConfig> => {
   entitiesJson->Array.mapWithIndex((entityJson, index) => {
     let entityName = entityJson["name"]
+    let crossChain = entityJson["crossChain"]->Option.getOr(defaultCrossChain)
 
     let fields: array<Table.fieldOrDerived> = entityJson["properties"]->Array.map(prop => {
       let (fieldType, fieldSchema, isNullable, isArray, isIndex) = getFieldTypeAndSchema(
@@ -478,7 +518,10 @@ let parseEntitiesFromJson = (
 
     let table = Table.mkTable(
       entityName,
-      ~fields=Array.concat(fields, derivedFields),
+      ~fields=Array.concatMany(
+        fields,
+        [crossChain ? [] : [makeChainIdField(~globalStorage)], derivedFields],
+      ),
       ~compositeIndexes,
       ~description=?entityJson["description"],
     )
@@ -536,14 +579,19 @@ let parseEntitiesFromJson = (
       schema: schema->(Utils.magic: S.t<dict<unknown>> => S.t<Internal.entity>),
       table,
       storage,
+      crossChain,
     }->Internal.fromGenericEntityConfig
   })
 }
 
+let columnNameFormatSchema = S.enum([Original, SnakeCase])
+
 let publicConfigStorageSchema = S.schema(s =>
   {
     "postgres": s.matches(S.bool),
     "clickhouse": s.matches(S.option(S.bool)),
+    "postgresColumnNameFormat": s.matches(S.option(columnNameFormatSchema)),
+    "clickhouseColumnNameFormat": s.matches(S.option(columnNameFormatSchema)),
   }
 )
 
@@ -558,6 +606,7 @@ let publicConfigSchema = S.schema(s =>
     "saveFullHistory": s.matches(S.option(S.bool)),
     "rawEvents": s.matches(S.option(S.bool)),
     "chainIdMode": s.matches(S.option(ChainId.modeSchema)),
+    "defaultCrossChain": s.matches(S.option(S.bool)),
     "storage": s.matches(publicConfigStorageSchema),
     "evm": s.matches(S.option(publicConfigEvmSchema)),
     "fuel": s.matches(S.option(publicConfigEcosystemSchema)),
@@ -995,12 +1044,20 @@ let fromPublic = (publicConfigJson: JSON.t) => {
   let globalStorage: storage = {
     postgres: publicConfig["storage"]["postgres"],
     clickhouse: publicConfig["storage"]["clickhouse"]->Option.getOr(false),
+    postgresColumnNameFormat: publicConfig["storage"]["postgresColumnNameFormat"]->Option.getOr(
+      Original,
+    ),
+    clickhouseColumnNameFormat: publicConfig["storage"]["clickhouseColumnNameFormat"]->Option.getOr(
+      Original,
+    ),
   }
 
+  let defaultCrossChain = publicConfig["defaultCrossChain"]->Option.getOr(true)
+
   let userEntities =
     publicConfig["entities"]
     ->Option.getOr([])
-    ->parseEntitiesFromJson(~enumConfigsByName, ~globalStorage)
+    ->parseEntitiesFromJson(~enumConfigsByName, ~globalStorage, ~defaultCrossChain)
 
   let allEntities = userEntities->Array.concat([EnvioAddresses.entityConfig])
 
@@ -1036,6 +1093,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     contractHandlers,
     shouldRollbackOnReorg: publicConfig["rollbackOnReorg"]->Option.getOr(true),
     shouldSaveFullHistory: publicConfig["saveFullHistory"]->Option.getOr(false),
+    defaultCrossChain,
     storage: globalStorage,
     chainIdMode: publicConfig["chainIdMode"]->Option.getOr(Int32),
     chainMap,

package/src/Config.res.mjs

@@ -22,6 +22,16 @@ import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 import * as EventConfigBuilder from "./EventConfigBuilder.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
+let chainIdFieldName = "chainId";
+
+function chainIdColumnName(format) {
+  if (format === "original") {
+    return chainIdFieldName;
+  } else {
+    return "chain_id";
+  }
+}
+
 let name = "envio_addresses";
 
 function makeId(chainId, address) {
@@ -42,11 +52,11 @@ let schema = S$RescriptSchema.schema(s => ({
 }));
 
 let table = Table.mkTable(name, undefined, [
-  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("chain_id", "ChainId", ChainId.schema, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
+  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("chain_id", "ChainId", ChainId.schema, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
 ], undefined);
 
 let entityConfig_storage = {
@@ -59,7 +69,8 @@ let entityConfig = {
   index: -1,
   schema: schema,
   table: table,
-  storage: entityConfig_storage
+  storage: entityConfig_storage,
+  crossChain: true
 };
 
 let EnvioAddresses = {
@@ -217,6 +228,7 @@ let entityStorageSchema = S$RescriptSchema.schema(s => ({
 
 let entityJsonSchema = S$RescriptSchema.schema(s => ({
   name: s.m(S$RescriptSchema.string),
+  crossChain: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   storage: s.m(S$RescriptSchema.option(entityStorageSchema)),
   properties: s.m(S$RescriptSchema.array(propertySchema)),
   derivedFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(derivedFieldSchema))),
@@ -324,19 +336,24 @@ function parseEnumsFromJson(enumsJson) {
   return Object.entries(enumsJson).map(param => Table.makeEnumConfig(param[0], param[1]));
 }
 
-function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
+function makeChainIdField(globalStorage) {
+  return Table.mkField(chainIdFieldName, "ChainId", ChainId.schema, undefined, undefined, undefined, true, undefined, true, undefined, undefined, chainIdColumnName(globalStorage.postgresColumnNameFormat), chainIdColumnName(globalStorage.clickhouseColumnNameFormat));
+}
+
+function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage, defaultCrossChain) {
   return entitiesJson.map((entityJson, index) => {
     let entityName = entityJson.name;
+    let crossChain = Stdlib_Option.getOr(entityJson.crossChain, defaultCrossChain);
     let fields = entityJson.properties.map(prop => {
       let match = getFieldTypeAndSchema(prop, enumConfigsByName);
-      return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], prop.linkedEntity, prop.description, prop.postgresDbName, prop.clickhouseDbName);
+      return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], undefined, prop.linkedEntity, prop.description, prop.postgresDbName, prop.clickhouseDbName);
     });
     let derivedFields = Stdlib_Option.getOr(entityJson.derivedFields, []).map(df => Table.mkDerivedFromField(df.fieldName, df.derivedFromEntity, df.derivedFromField, df.description));
     let compositeIndexes = Stdlib_Option.getOr(entityJson.compositeIndices, []).map(ci => ci.map(f => ({
       fieldName: f.fieldName,
       direction: f.direction === "Asc" ? "Asc" : "Desc"
     })));
-    let table = Table.mkTable(entityName, compositeIndexes, fields.concat(derivedFields), entityJson.description);
+    let table = Table.mkTable(entityName, compositeIndexes, fields.concat(crossChain ? [] : [makeChainIdField(globalStorage)], derivedFields), entityJson.description);
     let getApiFieldName = prop => {
       let match = prop.linkedEntity;
       if (match !== undefined) {
@@ -382,14 +399,22 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
       index: index,
       schema: schema,
       table: table,
-      storage: storage
+      storage: storage,
+      crossChain: crossChain
     };
   });
 }
 
+let columnNameFormatSchema = S$RescriptSchema.$$enum([
+  "original",
+  "snake_case"
+]);
+
 let publicConfigStorageSchema = S$RescriptSchema.schema(s => ({
   postgres: s.m(S$RescriptSchema.bool),
-  clickhouse: s.m(S$RescriptSchema.option(S$RescriptSchema.bool))
+  clickhouse: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
+  postgresColumnNameFormat: s.m(S$RescriptSchema.option(columnNameFormatSchema)),
+  clickhouseColumnNameFormat: s.m(S$RescriptSchema.option(columnNameFormatSchema))
 }));
 
 let publicConfigSchema = S$RescriptSchema.schema(s => ({
@@ -402,6 +427,7 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   saveFullHistory: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   rawEvents: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   chainIdMode: s.m(S$RescriptSchema.option(ChainId.modeSchema)),
+  defaultCrossChain: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   storage: s.m(publicConfigStorageSchema),
   evm: s.m(S$RescriptSchema.option(publicConfigEvmSchema)),
   fuel: s.m(S$RescriptSchema.option(publicConfigEcosystemSchema)),
@@ -689,11 +715,16 @@ function fromPublic(publicConfigJson) {
   ]));
   let globalStorage_postgres = publicConfig.storage.postgres;
   let globalStorage_clickhouse = Stdlib_Option.getOr(publicConfig.storage.clickhouse, false);
+  let globalStorage_postgresColumnNameFormat = Stdlib_Option.getOr(publicConfig.storage.postgresColumnNameFormat, "original");
+  let globalStorage_clickhouseColumnNameFormat = Stdlib_Option.getOr(publicConfig.storage.clickhouseColumnNameFormat, "original");
   let globalStorage = {
     postgres: globalStorage_postgres,
-    clickhouse: globalStorage_clickhouse
+    clickhouse: globalStorage_clickhouse,
+    postgresColumnNameFormat: globalStorage_postgresColumnNameFormat,
+    clickhouseColumnNameFormat: globalStorage_clickhouseColumnNameFormat
   };
-  let userEntities = parseEntitiesFromJson(Stdlib_Option.getOr(publicConfig.entities, []), enumConfigsByName, globalStorage);
+  let defaultCrossChain = Stdlib_Option.getOr(publicConfig.defaultCrossChain, true);
+  let userEntities = parseEntitiesFromJson(Stdlib_Option.getOr(publicConfig.entities, []), enumConfigsByName, globalStorage, defaultCrossChain);
   let allEntities = userEntities.concat([entityConfig]);
   let userEntitiesByName = Object.fromEntries(userEntities.map(entityConfig => [
     Utils.$$String.capitalize(entityConfig.name),
@@ -710,6 +741,7 @@ function fromPublic(publicConfigJson) {
     contractHandlers: contractHandlers,
     shouldRollbackOnReorg: Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true),
     shouldSaveFullHistory: Stdlib_Option.getOr(publicConfig.saveFullHistory, false),
+    defaultCrossChain: defaultCrossChain,
     storage: globalStorage,
     chainIdMode: Stdlib_Option.getOr(publicConfig.chainIdMode, "int32"),
     chainMap: chainMap,
@@ -1049,6 +1081,8 @@ function getPgUserEntities(config) {
 }
 
 export {
+  chainIdFieldName,
+  chainIdColumnName,
   EnvioAddresses,
   rpcSourceForSchema,
   rpcConfigSchema,
@@ -1069,7 +1103,9 @@ export {
   entityJsonSchema,
   getFieldTypeAndSchema,
   parseEnumsFromJson,
+  makeChainIdField,
   parseEntitiesFromJson,
+  columnNameFormatSchema,
   publicConfigStorageSchema,
   publicConfigSchema,
   fromPublic,

package/src/EffectState.res

@@ -131,7 +131,7 @@ let commitCacheCount = (inMemTable: effectCacheInMemTable, ~count) => {
 
 let statsToMetrics = (stats: effectStats): Metrics.effectMetrics => {
   Metrics.effect: stats.effectName,
-  scope: stats.scope->Internal.EffectCache.scopeToString,
+  scope: stats.scope->Internal.chainScopeToString,
   callSeconds: stats.callSeconds,
   callSecondsTotal: stats.callSecondsTotal,
   callCount: stats.callCount,
@@ -152,7 +152,7 @@ let toMetrics = (self: t): array<Metrics.effectMetrics> => {
     metrics
     ->Array.push({
       Metrics.effect: effectName,
-      scope: scope->Internal.EffectCache.scopeToString,
+      scope: scope->Internal.chainScopeToString,
       callSeconds: 0.,
       callSecondsTotal: 0.,
       callCount: 0.,

package/src/EffectState.res.mjs

@@ -68,7 +68,7 @@ function toMetrics(self) {
     let stats = t.stats;
     return {
       effect: stats.effectName,
-      scope: Internal.EffectCache.scopeToString(stats.scope),
+      scope: Internal.chainScopeToString(stats.scope),
       callSeconds: stats.callSeconds,
       callSecondsTotal: stats.callSecondsTotal,
       callCount: stats.callCount,
@@ -82,7 +82,7 @@ function toMetrics(self) {
   Utils.Dict.forEach(self.unregisteredCacheCounts, param => {
     metrics.push({
       effect: param.effectName,
-      scope: Internal.EffectCache.scopeToString(param.scope),
+      scope: Internal.chainScopeToString(param.scope),
       callSeconds: 0,
       callSecondsTotal: 0,
       callCount: 0,