envio 3.5.0-alpha.3 → 3.5.0-rc.0

package/src/ChainMap.res.mjs

@@ -1,78 +1,42 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Belt_Id from "@rescript/runtime/lib/es6/Belt_Id.js";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Belt_Map from "@rescript/runtime/lib/es6/Belt_Map.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 Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 
-function toString(chainId) {
-  return chainId.toString();
-}
-
-function makeUnsafe(chainId) {
-  return chainId;
-}
-
-let Chain = {
-  toString: toString,
-  makeUnsafe: makeUnsafe
-};
-
-function cmp(a, b) {
-  return Primitive_int.compare(a, b) | 0;
-}
-
 let ChainIdCmp = Belt_Id.MakeComparable({
-  cmp: cmp
+  cmp: ChainId.compare
 });
 
 function fromArrayUnsafe(arr) {
   return Belt_Map.fromArray(arr, ChainIdCmp);
 }
 
-function get(self, chain) {
-  let v = Belt_Map.get(self, chain);
+function get(self, chainId) {
+  let v = Belt_Map.get(self, chainId);
   if (v !== undefined) {
     return Primitive_option.valFromOption(v);
   } else {
-    return Stdlib_JsError.throwWithMessage("No chain with id " + chain.toString() + " found in chain map");
+    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainId.toString(chainId) + " found in chain map");
   }
 }
 
-let set = Belt_Map.set;
-
 let values = Belt_Map.valuesToArray;
 
 let keys = Belt_Map.keysToArray;
 
-let entries = Belt_Map.toArray;
-
 let has = Belt_Map.has;
 
-let map = Belt_Map.map;
-
 let mapWithKey = Belt_Map.mapWithKey;
 
-let size = Belt_Map.size;
-
-function update(map, chain, updateFn) {
-  return Belt_Map.update(map, chain, opt => Stdlib_Option.map(opt, updateFn));
-}
-
 export {
-  Chain,
   fromArrayUnsafe,
   get,
-  set,
   values,
   keys,
-  entries,
   has,
-  map,
   mapWithKey,
-  size,
-  update,
 }
 /* ChainIdCmp Not a pure module */

package/src/ChainMap.resi

@@ -1,22 +1,7 @@
-module Chain: {
-  type t
-
-  external toChainId: t => int = "%identity"
-
-  let toString: t => string
-
-  let makeUnsafe: (~chainId: int) => t
-}
-
 type t<'a>
-let fromArrayUnsafe: array<(Chain.t, 'a)> => t<'a>
-let get: (t<'a>, Chain.t) => 'a
-let set: (t<'a>, Chain.t, 'a) => t<'a>
+let fromArrayUnsafe: array<(ChainId.t, 'a)> => t<'a>
+let get: (t<'a>, ChainId.t) => 'a
 let values: t<'a> => array<'a>
-let keys: t<'a> => array<Chain.t>
-let entries: t<'a> => array<(Chain.t, 'a)>
-let has: (t<'a>, Chain.t) => bool
-let map: (t<'a>, 'a => 'b) => t<'b>
-let mapWithKey: (t<'a>, (Chain.t, 'a) => 'b) => t<'b>
-let size: t<'a> => int
-let update: (t<'a>, Chain.t, 'a => 'a) => t<'a>
+let keys: t<'a> => array<ChainId.t>
+let has: (t<'a>, ChainId.t) => bool
+let mapWithKey: (t<'a>, (ChainId.t, 'a) => 'b) => t<'b>

package/src/ChainMetadata.res

@@ -8,7 +8,7 @@ let stage = (state: IndexerState.t) => {
   ->Dict.valuesToArray
   ->Array.forEach(cs => {
     chainsData->Dict.set(
-      (cs->ChainState.chainConfig).id->Int.toString,
+      (cs->ChainState.chainConfig).id->ChainId.toString,
       cs->ChainState.toChainMetadata,
     )
   })

package/src/ChainMetadata.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as ChainId from "./ChainId.res.mjs";
 import * as Writing from "./Writing.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
 import * as IndexerState from "./IndexerState.res.mjs";
@@ -7,7 +8,7 @@ import * as IndexerState from "./IndexerState.res.mjs";
 function stage(state) {
   let chainsData = {};
   Object.values(IndexerState.chainStates(state)).forEach(cs => {
-    chainsData[ChainState.chainConfig(cs).id.toString()] = ChainState.toChainMetadata(cs);
+    chainsData[ChainId.toString(ChainState.chainConfig(cs).id)] = ChainState.toChainMetadata(cs);
   });
   Writing.setChainMeta(state, chainsData);
 }
@@ -15,4 +16,4 @@ function stage(state) {
 export {
   stage,
 }
-/* Writing Not a pure module */
+/* ChainId Not a pure module */

package/src/ChainState.res

@@ -69,13 +69,13 @@ let configAddresses = (chainConfig: Config.chain): array<Internal.indexingAddres
 }
 
 let validateOnEventRegistrations = (
-  ~chainId: int,
+  ~chainId: ChainId.t,
   registrations: array<Internal.onEventRegistration>,
 ) =>
   registrations->Array.forEachWithIndex((registration, expectedIndex) => {
     if registration.index !== expectedIndex {
       JsError.throwWithMessage(
-        `Invalid onEvent registration index for chain ${chainId->Int.toString}: ${registration.eventConfig.contractName}.${registration.eventConfig.name} has index ${registration.index->Int.toString}, but its ChainState position is ${expectedIndex->Int.toString}.`,
+        `Invalid onEvent registration index for chain ${chainId->ChainId.toString}: ${registration.eventConfig.contractName}.${registration.eventConfig.name} has index ${registration.index->Int.toString}, but its ChainState position is ${expectedIndex->Int.toString}.`,
       )
     }
   })
@@ -155,7 +155,7 @@ let makeInternal = (
   // chain - this just looks up this chain's slice.
   let {onEventRegistrations, onBlockRegistrations} =
     registrationsByChainId
-    ->Utils.Dict.dangerouslyGetNonOption(chainConfig.id->Int.toString)
+    ->Utils.Dict.dangerouslyGetNonOption(chainConfig.id->ChainId.toString)
     ->Option.getOr({onEventRegistrations: [], onBlockRegistrations: []})
 
   chainConfig.contracts->Array.forEach(contract => {
@@ -216,7 +216,7 @@ let makeInternal = (
   })
 
   // Create sources lazily here - this is where API token validation happens
-  let chain = ChainMap.Chain.makeUnsafe(~chainId=chainConfig.id)
+  let chainId = chainConfig.id
   let sources = switch chainConfig.sourceConfig {
   | Config.EvmSourceConfig({hypersync, rpcs}) =>
     let evmRpcs: array<EvmChain.rpc> = rpcs->Array.map((rpc): EvmChain.rpc => {
@@ -232,7 +232,7 @@ let makeInternal = (
       }
     })
     EvmChain.makeSources(
-      ~chain,
+      ~chainId,
       ~onEventRegistrations=onEventRegistrations->(
         Utils.magic: array<Internal.onEventRegistration> => array<Internal.evmOnEventRegistration>
       ),
@@ -243,7 +243,7 @@ let makeInternal = (
     )
   | Config.FuelSourceConfig({hypersync}) => [
       FuelHyperSyncSource.make({
-        chain,
+        chainId,
         endpointUrl: hypersync,
         apiToken: Env.envioApiToken,
         onEventRegistrations,
@@ -253,17 +253,15 @@ let makeInternal = (
   | Config.SvmSourceConfig({hypersync, rpc}) =>
     switch (hypersync, rpc) {
     | (None, None) =>
-      JsError.throwWithMessage(
-        `Chain ${chain->ChainMap.Chain.toChainId->Int.toString} has no SVM data source`,
-      )
-    | (None, Some(rpc)) => [Svm.makeRPCSource(~chain, ~rpc)]
+      JsError.throwWithMessage(`Chain ${chainId->ChainId.toString} has no SVM data source`)
+    | (None, Some(rpc)) => [Svm.makeRPCSource(~chainId, ~rpc)]
     | (Some(hypersyncUrl), _) =>
       // HyperSync drives instruction sync. A configured RPC is ignored for now
       // (RPC fallback isn't wired up yet).
       let apiToken = Env.envioApiToken
       [
         SvmHyperSyncSource.make({
-          chain,
+          chainId,
           endpointUrl: hypersyncUrl,
           apiToken,
           onEventRegistrations,
@@ -272,6 +270,9 @@ let makeInternal = (
         }),
       ]
     }
+  | Config.SimulateSourceConfig({items, endBlock}) => [
+      SimulateSource.make(~items, ~endBlock, ~chainId, ~addressStore),
+    ]
   // For tests: use ready-to-use sources directly
   | Config.CustomSources(sources) => sources
   }
@@ -377,9 +378,7 @@ let makeFromDbState = (
     ~maxReorgDepth=resumedChainState.maxReorgDepth,
     ~firstEventBlock=resumedChainState.firstEventBlockNumber,
     ~progressBlockNumber,
-    ~timestampCaughtUpToHeadOrEndblock=Env.updateSyncTimeOnRestart
-      ? None
-      : resumedChainState.timestampCaughtUpToHeadOrEndblock,
+    ~timestampCaughtUpToHeadOrEndblock=resumedChainState.timestampCaughtUpToHeadOrEndblock,
     ~numEventsProcessed=resumedChainState.numEventsProcessed,
     ~logger,
     ~isInReorgThreshold,
@@ -615,6 +614,24 @@ let hasProcessedToEndblock = (cs: t) => {
   }
 }
 
+// Caught up as judged by persisted values alone: progress reached the endBlock,
+// or the head the previous run had already observed (less the lag that holds the
+// tip back). Unlike `isFetchingAtHead` this doesn't move when a fresh height
+// lands, so a run resumed at the head still knows it was caught up even once the
+// head has run away from it while the indexer was down.
+let isDurablyCaughtUp = (cs: t) => {
+  let {committedProgressBlockNumber, fetchState} = cs
+  switch fetchState.endBlock {
+  | Some(endBlock) => committedProgressBlockNumber >= endBlock
+  | None =>
+    // The configured lag, not the fetch state's: pre-threshold that one also
+    // carries maxReorgDepth, which would read a chain a whole reorg depth behind
+    // the head as caught up.
+    fetchState.knownHeight > 0 &&
+      committedProgressBlockNumber >= fetchState.knownHeight - cs.chainConfig.blockLag
+  }
+}
+
 let getHighestBlockBelowThreshold = (cs: t): int => {
   let highestBlockBelowThreshold = cs.fetchState.knownHeight - cs.chainConfig.maxReorgDepth
   highestBlockBelowThreshold < 0 ? 0 : highestBlockBelowThreshold
@@ -911,7 +928,7 @@ let toChainMetadata = (cs: t): InternalTable.Chains.metaFields => {
 }
 
 let toMetrics = (cs: t): Metrics.chainMetrics => {
-  chainId: cs.chainConfig.id->Int.toFloat,
+  chainId: cs.chainConfig.id,
   poweredByHyperSync: (cs.sourceManager->SourceManager.getActiveSource).poweredByHyperSync,
   firstEventBlockNumber: cs.fetchState.firstEventBlock,
   latestProcessedBlock: cs.committedProgressBlockNumber === -1
@@ -961,7 +978,7 @@ let toChainBeforeBatch = (cs: t): Batch.chainBeforeBatch => {
 // Whether the chain's post-batch fetch frontier is ready to cross into the reorg
 // threshold, using the batch's progressed frontier when this chain advanced.
 let isReadyToEnterReorgThresholdAfterBatch = (cs: t, ~batch: Batch.t) => {
-  let fetchState = switch batch.progressedChainsById->Utils.Dict.dangerouslyGetByIntNonOption(
+  let fetchState = switch batch.progressedChainsById->ChainId.Dict.dangerouslyGetNonOption(
     cs.fetchState.chainId,
   ) {
   | Some(chainAfterBatch) => chainAfterBatch.fetchState
@@ -973,9 +990,7 @@ let isReadyToEnterReorgThresholdAfterBatch = (cs: t, ~batch: Batch.t) => {
 // Commit the post-batch fetch frontier for a chain that progressed in the batch,
 // applying blockLag when this batch also crosses into the reorg threshold.
 let advanceAfterBatch = (cs: t, ~batch: Batch.t, ~enteringReorgThreshold) =>
-  switch batch.progressedChainsById->Utils.Dict.dangerouslyGetByIntNonOption(
-    cs.fetchState.chainId,
-  ) {
+  switch batch.progressedChainsById->ChainId.Dict.dangerouslyGetNonOption(cs.fetchState.chainId) {
   | Some(chainAfterBatch) =>
     cs.fetchState = enteringReorgThreshold
       ? chainAfterBatch.fetchState->FetchState.updateInternal(~blockLag=cs.chainConfig.blockLag)
@@ -995,7 +1010,7 @@ let advanceAfterBatch = (cs: t, ~batch: Batch.t, ~enteringReorgThreshold) =>
 let applyBatchProgress = (cs: t, ~batch: Batch.t, ~blockTimestampName: string) => {
   let chainId = cs.chainConfig.id
 
-  switch batch.progressedChainsById->Utils.Dict.dangerouslyGetByIntNonOption(chainId) {
+  switch batch.progressedChainsById->ChainId.Dict.dangerouslyGetNonOption(chainId) {
   | Some(chainAfterBatch) => {
       // Calculate and set latency metrics. The payload block is materialised or
       // inline by processing time; its timestamp may still be absent (e.g. an

package/src/ChainState.res.mjs

@@ -4,8 +4,8 @@ import * as Env from "./Env.res.mjs";
 import * as Svm from "./sources/Svm.res.mjs";
 import * as Batch from "./Batch.res.mjs";
 import * as Utils from "./Utils.res.mjs";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
-import * as ChainMap from "./ChainMap.res.mjs";
 import * as EvmChain from "./sources/EvmChain.res.mjs";
 import * as FieldMask from "./sources/FieldMask.res.mjs";
 import * as BlockStore from "./sources/BlockStore.res.mjs";
@@ -17,6 +17,7 @@ import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as SourceManager from "./sources/SourceManager.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as ReorgDetection from "./ReorgDetection.res.mjs";
+import * as SimulateSource from "./sources/SimulateSource.res.mjs";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_float from "@rescript/runtime/lib/es6/Primitive_float.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
@@ -42,7 +43,7 @@ function configAddresses(chainConfig) {
 function validateOnEventRegistrations(chainId, registrations) {
   registrations.forEach((registration, expectedIndex) => {
     if (registration.index !== expectedIndex) {
-      return Stdlib_JsError.throwWithMessage(`Invalid onEvent registration index for chain ` + chainId.toString() + `: ` + registration.eventConfig.contractName + `.` + registration.eventConfig.name + ` has index ` + registration.index.toString() + `, but its ChainState position is ` + expectedIndex.toString() + `.`);
+      return Stdlib_JsError.throwWithMessage(`Invalid onEvent registration index for chain ` + ChainId.toString(chainId) + `: ` + registration.eventConfig.contractName + `.` + registration.eventConfig.name + ` has index ` + registration.index.toString() + `, but its ChainState position is ` + expectedIndex.toString() + `.`);
     }
   });
 }
@@ -93,7 +94,7 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
   let firstEventBlock = firstEventBlockOpt !== undefined ? Primitive_option.valFromOption(firstEventBlockOpt) : undefined;
   let knownHeight = knownHeightOpt !== undefined ? knownHeightOpt : 0;
   let isResumed = isResumedOpt !== undefined ? isResumedOpt : false;
-  let match = Stdlib_Option.getOr(registrationsByChainId[chainConfig.id.toString()], {
+  let match = Stdlib_Option.getOr(registrationsByChainId[ChainId.toString(chainConfig.id)], {
     onEventRegistrations: [],
     onBlockRegistrations: []
   });
@@ -123,7 +124,7 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
       return reorgCheckpoint;
     }
   });
-  let chain = ChainMap.Chain.makeUnsafe(chainConfig.id);
+  let chainId = chainConfig.id;
   let sources = chainConfig.sourceConfig;
   let sources$1;
   switch (sources.TAG) {
@@ -140,11 +141,11 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
           headers: headers
         };
       });
-      sources$1 = EvmChain.makeSources(chain, onEventRegistrations, sources.hypersync, evmRpcs, lowercaseAddresses, addressStore);
+      sources$1 = EvmChain.makeSources(chainId, onEventRegistrations, sources.hypersync, evmRpcs, lowercaseAddresses, addressStore);
       break;
     case "FuelSourceConfig" :
       sources$1 = [FuelHyperSyncSource.make({
-          chain: chain,
+          chainId: chainId,
           endpointUrl: sources.hypersync,
           apiToken: Env.envioApiToken,
           onEventRegistrations: onEventRegistrations,
@@ -155,16 +156,19 @@ function makeInternal(chainConfig, indexingAddresses, startBlock, endBlock, firs
       let rpc = sources.rpc;
       let hypersync = sources.hypersync;
       sources$1 = hypersync !== undefined ? [SvmHyperSyncSource.make({
-            chain: chain,
+            chainId: chainId,
             endpointUrl: hypersync,
             apiToken: Env.envioApiToken,
             onEventRegistrations: onEventRegistrations,
             clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis,
             addressStore: addressStore
           })] : (
-          rpc !== undefined ? [Svm.makeRPCSource(chain, rpc, undefined)] : Stdlib_JsError.throwWithMessage(`Chain ` + chain.toString() + ` has no SVM data source`)
+          rpc !== undefined ? [Svm.makeRPCSource(chainId, rpc, undefined)] : Stdlib_JsError.throwWithMessage(`Chain ` + ChainId.toString(chainId) + ` has no SVM data source`)
         );
       break;
+    case "SimulateSourceConfig" :
+      sources$1 = [SimulateSource.make(sources.items, sources.endBlock, chainId, addressStore)];
+      break;
     case "CustomSources" :
       sources$1 = sources._0;
       break;
@@ -187,7 +191,7 @@ function makeFromDbState(chainConfig, resumedChainState, reorgCheckpoints, isInR
     chainId: chainId
   });
   let progressBlockNumber = resumedChainState.progressBlockNumber >= 0 ? resumedChainState.progressBlockNumber : resumedChainState.startBlock - 1 | 0;
-  return makeInternal(chainConfig, resumedChainState.indexingAddresses, resumedChainState.startBlock, resumedChainState.endBlock, Primitive_option.some(resumedChainState.firstEventBlockNumber), progressBlockNumber, config, registrationsByChainId, logger, Env.updateSyncTimeOnRestart ? undefined : resumedChainState.timestampCaughtUpToHeadOrEndblock, resumedChainState.numEventsProcessed, isInReorgThreshold, isRealtime, reorgCheckpoints, resumedChainState.maxReorgDepth, resumedChainState.sourceBlockNumber, true, reducedPollingInterval);
+  return makeInternal(chainConfig, resumedChainState.indexingAddresses, resumedChainState.startBlock, resumedChainState.endBlock, Primitive_option.some(resumedChainState.firstEventBlockNumber), progressBlockNumber, config, registrationsByChainId, logger, resumedChainState.timestampCaughtUpToHeadOrEndblock, resumedChainState.numEventsProcessed, isInReorgThreshold, isRealtime, reorgCheckpoints, resumedChainState.maxReorgDepth, resumedChainState.sourceBlockNumber, true, reducedPollingInterval);
 }
 
 function logger(cs) {
@@ -284,6 +288,11 @@ function startFetchingQueries(cs, queries) {
   cs.pendingBudget = cs.pendingBudget + Stdlib_Array.reduce(queries, 0, (acc, query) => acc + query.itemsEst);
 }
 
+function resetPendingQueries(cs) {
+  cs.fetchState = FetchState.resetPendingQueries(cs.fetchState);
+  cs.pendingBudget = 0;
+}
+
 function isReady(cs) {
   return cs.timestampCaughtUpToHeadOrEndblock !== undefined;
 }
@@ -390,6 +399,19 @@ function hasProcessedToEndblock(cs) {
   }
 }
 
+function isDurablyCaughtUp(cs) {
+  let fetchState = cs.fetchState;
+  let committedProgressBlockNumber = cs.committedProgressBlockNumber;
+  let endBlock = fetchState.endBlock;
+  if (endBlock !== undefined) {
+    return committedProgressBlockNumber >= endBlock;
+  } else if (fetchState.knownHeight > 0) {
+    return committedProgressBlockNumber >= (fetchState.knownHeight - cs.chainConfig.blockLag | 0);
+  } else {
+    return false;
+  }
+}
+
 function getHighestBlockBelowThreshold(cs) {
   let highestBlockBelowThreshold = cs.fetchState.knownHeight - cs.chainConfig.maxReorgDepth | 0;
   if (highestBlockBelowThreshold < 0) {
@@ -565,8 +587,7 @@ function prepareReorg(cs, eventsProcessedDiff) {
   if (eventsProcessedDiff !== undefined) {
     cs.numEventsProcessed = cs.numEventsProcessed + eventsProcessedDiff;
   }
-  cs.fetchState = FetchState.resetPendingQueries(cs.fetchState);
-  cs.pendingBudget = 0;
+  resetPendingQueries(cs);
 }
 
 function updateKnownHeight(cs, knownHeight) {
@@ -832,6 +853,7 @@ export {
   toChainBeforeBatch,
   isReadyToEnterReorgThresholdAfterBatch,
   hasProcessedToEndblock,
+  isDurablyCaughtUp,
   getHighestBlockBelowThreshold,
   isActivelyIndexing,
   isReady,
@@ -842,6 +864,7 @@ export {
   materializePageItems,
   registerReorgGuard,
   prepareReorg,
+  resetPendingQueries,
   updateKnownHeight,
   setEndBlockToFirstEvent,
   enterReorgThreshold,

package/src/ChainState.resi

@@ -98,6 +98,7 @@ let isReadyToEnterReorgThresholdAfterBatch: (t, ~batch: Batch.t) => bool
 
 // Derived (pure).
 let hasProcessedToEndblock: t => bool
+let isDurablyCaughtUp: t => bool
 let getHighestBlockBelowThreshold: t => int
 let isActivelyIndexing: t => bool
 let isReady: t => bool
@@ -132,6 +133,7 @@ let registerReorgGuard: (
   ~knownHeight: int,
 ) => ReorgDetection.reorgResult
 let prepareReorg: (t, ~eventsProcessedDiff: option<float>) => unit
+let resetPendingQueries: t => unit
 let updateKnownHeight: (t, ~knownHeight: int) => unit
 let setEndBlockToFirstEvent: (t, ~blockNumber: int) => unit
 let enterReorgThreshold: t => unit

package/src/Config.res

@@ -30,12 +30,16 @@ type sourceConfig =
   | EvmSourceConfig({hypersync: option<string>, rpcs: array<evmRpcConfig>})
   | FuelSourceConfig({hypersync: string})
   | SvmSourceConfig({hypersync: option<string>, rpc: option<string>})
+  // A `simulate` run: the items the test fed in, parsed against the chain's
+  // registrations. The source itself is built with the chain's address store,
+  // like every other source, so it can apply the same gates.
+  | SimulateSourceConfig({items: array<Internal.item>, endBlock: int})
   // For tests: pass custom sources directly
   | CustomSources(array<Source.t>)
 
 type chain = {
   name: string,
-  id: int,
+  id: ChainId.t,
   startBlock: int,
   endBlock?: int,
   maxReorgDepth: int,
@@ -73,6 +77,10 @@ type t = {
   shouldRollbackOnReorg: bool,
   shouldSaveFullHistory: 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
+  // they can express fits an INTEGER.
+  chainIdMode: ChainId.mode,
   chainMap: ChainMap.t<chain>,
   defaultChain: option<chain>,
   ecosystem: Ecosystem.t,
@@ -98,13 +106,13 @@ module EnvioAddresses = {
   let name = "envio_addresses"
   let index = -1
 
-  let makeId = (~chainId, ~address) => {
-    chainId->Int.toString ++ "-" ++ address->Address.toString
+  let makeId = (~chainId: ChainId.t, ~address) => {
+    chainId->ChainId.toString ++ "-" ++ address->Address.toString
   }
 
   type t = {
     id: string,
-    @as("chain_id") chainId: int,
+    @as("chain_id") chainId: ChainId.t,
     @as("registration_block") registrationBlock: int,
     // -1 when the address was registered from a block handler (no log index)
     @as("registration_log_index") registrationLogIndex: int,
@@ -123,7 +131,7 @@ module EnvioAddresses = {
 
   let schema = S.schema(s => {
     id: s.matches(S.string),
-    chainId: s.matches(S.int),
+    chainId: s.matches(ChainId.schema),
     registrationBlock: s.matches(S.int),
     registrationLogIndex: s.matches(S.int),
     contractName: s.matches(S.string),
@@ -133,7 +141,7 @@ module EnvioAddresses = {
     name,
     ~fields=[
       Table.mkField("id", String, ~isPrimaryKey=true, ~fieldSchema=S.string),
-      Table.mkField("chain_id", Int32, ~fieldSchema=S.int),
+      Table.mkField("chain_id", ChainId, ~fieldSchema=ChainId.schema),
       Table.mkField("registration_block", Int32, ~fieldSchema=S.int),
       // -1 sentinel when registered from a block handler (no log index)
       Table.mkField("registration_log_index", Int32, ~fieldSchema=S.int),
@@ -185,7 +193,7 @@ let chainContractSchema = S.schema(s =>
 
 let publicConfigChainSchema = S.schema(s =>
   {
-    "id": s.matches(S.int),
+    "id": s.matches(ChainId.schema),
     "startBlock": s.matches(S.int),
     "endBlock": s.matches(S.option(S.int)),
     "maxReorgDepth": s.matches(S.option(S.int)),
@@ -548,6 +556,7 @@ let publicConfigSchema = S.schema(s =>
     "rollbackOnReorg": s.matches(S.option(S.bool)),
     "saveFullHistory": s.matches(S.option(S.bool)),
     "rawEvents": s.matches(S.option(S.bool)),
+    "chainIdMode": s.matches(S.option(ChainId.modeSchema)),
     "storage": s.matches(publicConfigStorageSchema),
     "evm": s.matches(S.option(publicConfigEvmSchema)),
     "fuel": s.matches(S.option(publicConfigEcosystemSchema)),
@@ -690,7 +699,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     ~contractName,
     ~events: option<array<_>>,
     ~abi,
-    ~chainId: int,
+    ~chainId: ChainId.t,
     ~addresses: array<string>,
     ~svmDefinedTypes: JSON.t=JSON.Null,
   ) => {
@@ -724,11 +733,11 @@ let fromPublic = (publicConfigJson: JSON.t) => {
           | [pid] => pid->SvmTypes.Pubkey.fromStringUnsafe
           | [] =>
             JsError.throwWithMessage(
-              `SVM program ${contractName} on chain ${chainId->Int.toString} is missing a program_id`,
+              `SVM program ${contractName} on chain ${chainId->ChainId.toString} is missing a program_id`,
             )
           | _ =>
             JsError.throwWithMessage(
-              `SVM program ${contractName} on chain ${chainId->Int.toString} has multiple addresses; a program is uniquely identified by a single program_id`,
+              `SVM program ${contractName} on chain ${chainId->ChainId.toString} has multiple addresses; a program is uniquely identified by a single program_id`,
             )
           }
           let widenedEventItem =
@@ -878,8 +887,8 @@ let fromPublic = (publicConfigJson: JSON.t) => {
             | Some(existingContractName) =>
               JsError.throwWithMessage(
                 existingContractName === contract.name
-                  ? `Address ${addressString} is listed multiple times for the contract ${contract.name} on chain ${chainId->Int.toString}. Please remove the duplicate from your config.`
-                  : `Address ${addressString} on chain ${chainId->Int.toString} is configured for multiple contracts: ${existingContractName} and ${contract.name}. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`,
+                  ? `Address ${addressString} is listed multiple times for the contract ${contract.name} on chain ${chainId->ChainId.toString}. Please remove the duplicate from your config.`
+                  : `Address ${addressString} on chain ${chainId->ChainId.toString} is configured for multiple contracts: ${existingContractName} and ${contract.name}. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`,
               )
             | None => contractNameByAddress->Dict.set(addressString, contract.name)
             }
@@ -969,7 +978,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
   let chainMap =
     chains
     ->Array.map(chain => {
-      (ChainMap.Chain.makeUnsafe(~chainId=chain.id), chain)
+      (chain.id, chain)
     })
     ->ChainMap.fromArrayUnsafe
 
@@ -1027,6 +1036,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     shouldRollbackOnReorg: publicConfig["rollbackOnReorg"]->Option.getOr(true),
     shouldSaveFullHistory: publicConfig["saveFullHistory"]->Option.getOr(false),
     storage: globalStorage,
+    chainIdMode: publicConfig["chainIdMode"]->Option.getOr(Int32),
     chainMap,
     defaultChain: chains->Array.get(0),
     enableRawEvents: publicConfig["rawEvents"]->Option.getOr(false),
@@ -1092,15 +1102,14 @@ let normalizeSimulateAddress = (config: t, address: Address.t): Address.t =>
 // returns that chain's per-chain event config (matters for where-callback
 // probe detection, which runs with the chain's real id). Without `chainId`,
 // falls back to the first chain that declares this event.
-let getEventConfig = (config: t, ~contractName, ~eventName, ~chainId: option<int>=?) => {
+let getEventConfig = (config: t, ~contractName, ~eventName, ~chainId: option<ChainId.t>=?) => {
   let chains = switch chainId {
   | Some(chainId) =>
-    let chain = ChainMap.Chain.makeUnsafe(~chainId)
-    switch config.chainMap->ChainMap.get(chain) {
+    switch config.chainMap->ChainMap.get(chainId) {
     | chainConfig => [chainConfig]
     | exception _ =>
       JsError.throwWithMessage(
-        `Chain ${chainId->Int.toString} is not configured. Add it to config.yaml or pass a configured chain.`,
+        `Chain ${chainId->ChainId.toString} is not configured. Add it to config.yaml or pass a configured chain.`,
       )
     }
   | None => config.chainMap->ChainMap.values
@@ -1122,14 +1131,12 @@ let shouldSaveHistory = (config, ~isInReorgThreshold) =>
 let shouldPruneHistory = (config, ~isInReorgThreshold) =>
   !config.shouldSaveFullHistory && (config.shouldRollbackOnReorg && isInReorgThreshold)
 
-let getChain = (config, ~chainId) => {
-  let chain = ChainMap.Chain.makeUnsafe(~chainId)
-  config.chainMap->ChainMap.has(chain)
-    ? chain
+let getChain = (config, ~chainId) =>
+  config.chainMap->ChainMap.has(chainId)
+    ? chainId
     : JsError.throwWithMessage(
-        "No chain with id " ++ chain->ChainMap.Chain.toString ++ " found in config.yaml",
+        "No chain with id " ++ chainId->ChainId.toString ++ " found in config.yaml",
       )
-}
 
 // A CLI command payload already contains the resolved JSON; priming lets
 // downstream callers skip the NAPI `getConfigJson` round-trip. Calling
@@ -1267,7 +1274,17 @@ let diffPaths = (~stored: JSON.t, ~current: JSON.t): array<string> => {
 
   switch (stored, current) {
   | (Object(sObj), Object(cObj)) =>
-    let tiers = [["version"], ["name"], ["storage"], ["evm", "fuel", "svm"], ["entities"]]
+    // chainIdMode sits right after version: it decides the physical type of
+    // every chain-id column, so a change to it is reported on its own rather
+    // than buried under the chain diffs that always accompany it.
+    let tiers = [
+      ["version"],
+      ["chainIdMode"],
+      ["name"],
+      ["storage"],
+      ["evm", "fuel", "svm"],
+      ["entities"],
+    ]
     let firstHit = tiers->Array.reduce(None, (acc, tier) =>
       switch acc {
       | Some(_) => acc