envio 3.9.0 → 3.10.0-subgraph

package/evm.schema.json

@@ -126,6 +126,17 @@
           "type": "null"
         }
       ]
+    },
+    "bytes_type": {
+      "description": "How the `Bytes` scalar in schema.graphql is represented. `hex` keeps 0x-prefixed hex strings stored as text, `uint8array` exposes `Uint8Array` values in handlers and stores raw bytes (BYTEA in Postgres, String in ClickHouse). (default: hex)",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BytesType"
+        },
+        {
+          "type": "null"
+        }
+      ]
     }
   },
   "additionalProperties": false,
@@ -758,6 +769,21 @@
         "checksum",
         "lowercase"
       ]
+    },
+    "BytesType": {
+      "description": "How the schema.graphql `Bytes` scalar reaches handlers and storage.",
+      "oneOf": [
+        {
+          "description": "`0x`-prefixed hex strings, stored as text.",
+          "type": "string",
+          "const": "hex"
+        },
+        {
+          "description": "`Uint8Array` values, stored as raw bytes (`BYTEA` in Postgres, `String` in ClickHouse).",
+          "type": "string",
+          "const": "uint8array"
+        }
+      ]
     }
   }
 }

package/fuel.schema.json

@@ -83,6 +83,17 @@
         "boolean",
         "null"
       ]
+    },
+    "bytes_type": {
+      "description": "How the `Bytes` scalar in schema.graphql is represented. `hex` keeps 0x-prefixed hex strings stored as text, `uint8array` exposes `Uint8Array` values in handlers and stores raw bytes (BYTEA in Postgres, String in ClickHouse). (default: hex)",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BytesType"
+        },
+        {
+          "type": "null"
+        }
+      ]
     }
   },
   "additionalProperties": false,
@@ -464,6 +475,21 @@
           }
         }
       ]
+    },
+    "BytesType": {
+      "description": "How the schema.graphql `Bytes` scalar reaches handlers and storage.",
+      "oneOf": [
+        {
+          "description": "`0x`-prefixed hex strings, stored as text.",
+          "type": "string",
+          "const": "hex"
+        },
+        {
+          "description": "`Uint8Array` values, stored as raw bytes (`BYTEA` in Postgres, `String` in ClickHouse).",
+          "type": "string",
+          "const": "uint8array"
+        }
+      ]
     }
   }
 }

package/index.d.ts

@@ -1423,7 +1423,7 @@ type SvmSelectedInstruction<Fields extends SvmFieldsSelection, ProgInstr> = {
   readonly instructionName: string;
   readonly discriminator: string;
   readonly programId: SvmInstrField<Fields, "programId", string>;
-  readonly data: SvmInstrField<Fields, "data", string>;
+  readonly data: SvmInstrField<Fields, "data", Uint8Array>;
   readonly path: SvmInstrField<Fields, "path", readonly number[]>;
   readonly isInner: SvmInstrField<Fields, "isInner", boolean>;
   readonly args: SvmInstrField<
@@ -1484,6 +1484,37 @@ export type SvmOnInstructionHandlerArgs<
   Instruction extends keyof SvmProgramsT[Program] & string = never,
 > = SvmOnInstructionArgsFor<SvmInstruction<Fields, Program, Instruction>, GlobalConfig>;
 
+/** The named accounts of a configured instruction. Falls back to an open
+ * record when the instruction carries no resolved schema, so its filter keys
+ * are unconstrained rather than unusable. */
+type SvmAccountsOf<Program extends string, Instruction extends string> =
+  SvmConfiguredInstruction<Program, Instruction>["accounts"];
+
+/** One AND-group of account narrowings: every named account must match one of
+ * its listed pubkeys. Names are the instruction's own account names. */
+export type SvmAccountsFilter<Accounts> = {
+  readonly [K in keyof Accounts]?: string | readonly string[];
+};
+
+/** The `where` option value of `indexer.onInstruction`.
+ *
+ * `accounts` accepts either a single AND-group of account narrowings, or an
+ * array of them (OR semantics). `block.slot._gte` promotes to the
+ * registration's startBlock and overrides the chain-level `start_block` — use
+ * it to restrict per-instruction processing without touching `config.yaml`.
+ * Only `_gte` is supported here; use `indexer.onSlot` for `_lte` / `_every`. */
+export type SvmOnInstructionWhere<Accounts> = {
+  /** Match only inner (CPI-invoked) or only outer instructions. Absent
+   * matches both. */
+  readonly isInner?: boolean;
+  readonly accounts?: SvmAccountsFilter<Accounts> | readonly SvmAccountsFilter<Accounts>[];
+  readonly block?: {
+    readonly slot?: {
+      readonly _gte?: number;
+    };
+  };
+};
+
 /** Options for an SVM `indexer.onInstruction` registration. */
 export type SvmOnInstructionOptions<
   P extends string = string,
@@ -1493,10 +1524,11 @@ export type SvmOnInstructionOptions<
   /** Program name as declared under `chains[].programs[].name` in
    * `config.yaml`. */
   readonly program: P;
-  /** Instruction name as declared under
-   * `chains[].programs[].instructions[].name` in `config.yaml`. */
+  /** Instruction name from the program's IDL, or from
+   * `chains[].programs[].instructions[].name` when the layout is inline. */
   readonly instruction: I;
   readonly fields?: Fields & SvmFieldsLiteralCheck<Fields>;
+  readonly where?: SvmOnInstructionWhere<SvmAccountsOf<P, I>>;
 };
 
 /** Handler function for an SVM `indexer.onInstruction` registration. Takes
@@ -1736,9 +1768,10 @@ type SvmEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
           }
             ? {
                 /**
-                 * Register an instruction handler. Dispatch matches on
-                 * `(programId, discriminator)` from the YAML config.
-                 * Handler `fields` is the only source of payload selection.
+                 * Register an instruction handler. `program` and `instruction`
+                 * name an entry from the IDL or YAML. Dispatch uses that
+                 * instruction's discriminator. Handler `fields` is the only
+                 * source of payload selection.
                  */
                 readonly onInstruction: <
                   P extends keyof Programs & string,
@@ -1905,8 +1938,8 @@ type SvmSimulateItem<Config extends IndexerConfigTypes = GlobalConfig> =
             path?: readonly number[];
             /** Override the program id. Defaults to the configured `program_id`. */
             programId?: string;
-            /** Raw instruction data, `0x`-prefixed hex. */
-            data?: string;
+            /** Raw instruction data. Defaults to the configured discriminator bytes. */
+            data?: Uint8Array;
             /** Whether this is a CPI-invoked inner instruction. */
             isInner?: boolean;
             /** Decoded args. Keys match the instruction's arg names. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.9.0",
+  "version": "3.10.0-subgraph",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -41,7 +41,6 @@
     "licenses"
   ],
   "dependencies": {
-    "@clickhouse/client": "1.17.0",
     "@elastic/ecs-pino-format": "1.4.0",
     "@fuel-ts/crypto": "0.96.1",
     "@fuel-ts/errors": "0.96.1",
@@ -69,10 +68,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.9.0",
-    "envio-linux-x64-musl": "3.9.0",
-    "envio-linux-arm64": "3.9.0",
-    "envio-darwin-x64": "3.9.0",
-    "envio-darwin-arm64": "3.9.0"
+    "envio-linux-x64": "3.10.0-subgraph",
+    "envio-linux-x64-musl": "3.10.0-subgraph",
+    "envio-linux-arm64": "3.10.0-subgraph",
+    "envio-darwin-x64": "3.10.0-subgraph",
+    "envio-darwin-arm64": "3.10.0-subgraph"
   }
 }

package/src/Batch.res

@@ -189,6 +189,15 @@ let addReorgCheckpoints = (
   }
 }
 
+// Checkpoint ids are handed out in ascending order as each chain's items are
+// walked in block order, so within a chain a higher id always means a later
+// block. Rollback preserves that: it deletes the chain's ids above its target
+// before any higher one is allocated, so the ids the re-indexed blocks get are
+// above everything the chain still holds. An isolated rollback leans on the
+// invariant — it deletes by `chain_id = c AND id > target`, which is only the
+// chain's stale suffix if ids and blocks agree on order within the chain. Ids
+// interleave freely *across* chains, which is exactly why that predicate can't
+// be the id bound alone.
 let prepareBatch = (
   ~checkpointIdBeforeBatch,
   ~chainsBeforeBatch: dict<chainBeforeBatch>,

package/src/ChainState.res

@@ -310,7 +310,11 @@ let makeInternal = (
           chainId,
           endpointUrl: hypersyncUrl,
           apiToken,
-          onEventRegistrations,
+          onEventRegistrations: onEventRegistrations->(
+            Utils.magic: array<Internal.onEventRegistration> => array<
+              Internal.svmOnEventRegistration,
+            >
+          ),
           clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis,
           addressStore,
         }),
@@ -1205,21 +1209,17 @@ let markReady = (cs: t, ~readyAt) =>
     cs.timestampCaughtUpToHeadOrEndblock = Some(readyAt)
   }
 
-// Roll a chain back to a reorg target. With a progress diff, restore fetch/
-// safe-checkpoint/progress state to `newProgressBlockNumber`. A reorg chain
-// with no diff entry still rewinds fetch state + stores to the target -
-// otherwise the stale block hash stays in the store and re-triggers the same
-// reorg.
-// Returns the address registrations the storage has to delete along with it —
-// the store is what decides which ones died, so the two halves of a rollback
-// can't disagree.
-let rollback = (
-  cs: t,
-  ~newProgressBlockNumber,
-  ~eventsProcessedDiff,
-  ~rollbackTargetBlockNumber,
-  ~isReorgChain,
-): array<AddressRows.key> => {
+type progressDiff = {blockNumber: int, eventsProcessed: float}
+
+type rolledBackTo =
+  | RecomputedProgress(progressDiff)
+  | ForkBlock(int)
+  | Untouched
+
+// Returns the address registrations the storage has to delete along with the
+// chain — the store is what decides which ones died, so the two halves of a
+// rollback can't disagree.
+let rollback = (cs: t, ~rolledBackTo: rolledBackTo): array<AddressRows.key> => {
   let rollbackTo = targetBlockNumber => {
     let {fetchState, rolledBackAddresses} =
       cs.fetchState->FetchState.rollback(
@@ -1234,15 +1234,15 @@ let rollback = (
     })
   }
 
-  switch newProgressBlockNumber {
-  | Some(newProgressBlockNumber) =>
-    let newTotalEventsProcessed =
-      cs.numEventsProcessed -.
-      // Both dicts are populated together per progress-diff row, so a chain with
-      // a progress diff always has an events-processed diff too.
-      eventsProcessedDiff->Option.getOrThrow(
-        ~message="Missing events-processed diff for rolled-back chain",
-      )
+  switch rolledBackTo {
+  | RecomputedProgress({blockNumber, eventsProcessed}) =>
+    // A rollback only ever takes a chain back. The diff recomputes progress from
+    // the checkpoints still in the database, so a chain that an unwritten
+    // rollback already took below them — to a fork block only that rollback
+    // knew — would be handed their MIN back and moved forward onto blocks it
+    // never re-indexed.
+    let newProgressBlockNumber = Pervasives.min(blockNumber, cs.committedProgressBlockNumber)
+    let newTotalEventsProcessed = cs.numEventsProcessed -. eventsProcessed
 
     switch cs.safeCheckpointTracking {
     | Some(safeCheckpointTracking) =>
@@ -1260,19 +1260,15 @@ let rollback = (
     cs.processingBlockNumber = newProgressBlockNumber
     cs.numEventsProcessed = newTotalEventsProcessed
     rolledBackAddresses
-  | None =>
-    if isReorgChain {
-      let rolledBackAddresses = rollbackTo(rollbackTargetBlockNumber)
-      cs.transactionStore->TransactionStore.rollback(rollbackTargetBlockNumber)
-      cs.blockStore->BlockStore.rollback(rollbackTargetBlockNumber)
-      cs.committedProgressBlockNumber = Pervasives.min(
-        cs.committedProgressBlockNumber,
-        rollbackTargetBlockNumber,
-      )
-      cs.processingBlockNumber = Pervasives.min(cs.processingBlockNumber, rollbackTargetBlockNumber)
-      rolledBackAddresses
-    } else {
-      []
-    }
+  | ForkBlock(forkBlock) =>
+    // Rewinds the stores too, not just progress: otherwise the stale block hash
+    // survives and re-triggers the same reorg.
+    let rolledBackAddresses = rollbackTo(forkBlock)
+    cs.transactionStore->TransactionStore.rollback(forkBlock)
+    cs.blockStore->BlockStore.rollback(forkBlock)
+    cs.committedProgressBlockNumber = Pervasives.min(cs.committedProgressBlockNumber, forkBlock)
+    cs.processingBlockNumber = Pervasives.min(cs.processingBlockNumber, forkBlock)
+    rolledBackAddresses
+  | Untouched => []
   }
 }

package/src/ChainState.res.mjs

@@ -857,7 +857,7 @@ function markReady(cs, readyAt) {
   }
 }
 
-function rollback(cs, newProgressBlockNumber, eventsProcessedDiff, rollbackTargetBlockNumber, isReorgChain) {
+function rollback(cs, rolledBackTo) {
   let rollbackTo = targetBlockNumber => {
     let match = FetchState.rollback(cs.fetchState, cs.addressStore, targetBlockNumber);
     cs.fetchState = match.fetchState;
@@ -867,8 +867,13 @@ function rollback(cs, newProgressBlockNumber, eventsProcessedDiff, rollbackTarge
       contractId: param.contractId
     }));
   };
-  if (newProgressBlockNumber !== undefined) {
-    let newTotalEventsProcessed = cs.numEventsProcessed - Stdlib_Option.getOrThrow(eventsProcessedDiff, "Missing events-processed diff for rolled-back chain");
+  if (typeof rolledBackTo !== "object") {
+    return [];
+  }
+  if (rolledBackTo.TAG === "RecomputedProgress") {
+    let match = rolledBackTo._0;
+    let newProgressBlockNumber = Primitive_int.min(match.blockNumber, cs.committedProgressBlockNumber);
+    let newTotalEventsProcessed = cs.numEventsProcessed - match.eventsProcessed;
     let safeCheckpointTracking = cs.safeCheckpointTracking;
     if (safeCheckpointTracking !== undefined) {
       cs.safeCheckpointTracking = SafeCheckpointTracking.rollback(safeCheckpointTracking, newProgressBlockNumber);
@@ -881,14 +886,12 @@ function rollback(cs, newProgressBlockNumber, eventsProcessedDiff, rollbackTarge
     cs.numEventsProcessed = newTotalEventsProcessed;
     return rolledBackAddresses;
   }
-  if (!isReorgChain) {
-    return [];
-  }
-  let rolledBackAddresses$1 = rollbackTo(rollbackTargetBlockNumber);
-  cs.transactionStore.rollback(rollbackTargetBlockNumber);
-  cs.blockStore.rollback(rollbackTargetBlockNumber);
-  cs.committedProgressBlockNumber = Primitive_int.min(cs.committedProgressBlockNumber, rollbackTargetBlockNumber);
-  cs.processingBlockNumber = Primitive_int.min(cs.processingBlockNumber, rollbackTargetBlockNumber);
+  let forkBlock = rolledBackTo._0;
+  let rolledBackAddresses$1 = rollbackTo(forkBlock);
+  cs.transactionStore.rollback(forkBlock);
+  cs.blockStore.rollback(forkBlock);
+  cs.committedProgressBlockNumber = Primitive_int.min(cs.committedProgressBlockNumber, forkBlock);
+  cs.processingBlockNumber = Primitive_int.min(cs.processingBlockNumber, forkBlock);
   return rolledBackAddresses$1;
 }
 

package/src/ChainState.resi

@@ -157,10 +157,18 @@ let enterReorgThreshold: t => unit
 let advanceAfterBatch: (t, ~batch: Batch.t, ~enteringReorgThreshold: bool) => unit
 let applyBatchProgress: (t, ~batch: Batch.t, ~blockTimestampName: string) => unit
 let markReady: (t, ~readyAt: Date.t) => unit
-let rollback: (
-  t,
-  ~newProgressBlockNumber: option<int>,
-  ~eventsProcessedDiff: option<float>,
-  ~rollbackTargetBlockNumber: int,
-  ~isReorgChain: bool,
-) => array<AddressRows.key>
+// What a rollback's progress diff says about one chain: the block its surviving
+// checkpoints put it back to, and the events the deleted ones carried away. One
+// record because one diff row yields both — they are never known separately.
+type progressDiff = {blockNumber: int, eventsProcessed: float}
+
+// Where a rollback leaves one chain.
+type rolledBackTo =
+  | RecomputedProgress(progressDiff)
+  // The reorg chain with no checkpoint left at or below the target, so only the
+  // fork block says where it goes.
+  | ForkBlock(int)
+  // A chain this rollback doesn't reach.
+  | Untouched
+
+let rollback: (t, ~rolledBackTo: rolledBackTo) => array<AddressRows.key>

package/src/Config.res

@@ -127,6 +127,9 @@ type t = {
   userEntitiesByName: dict<Internal.entityConfig>,
   userEntities: array<Internal.entityConfig>,
   allEnums: array<Table.enumConfig<Table.enum>>,
+  // Set only in subgraph mode: the translated manifest, which is what makes
+  // the subgraph runtime take over handler registration.
+  subgraph: option<JSON.t>,
 }
 
 type rpcSourceFor = | @as("sync") Sync | @as("fallback") Fallback | @as("realtime") Realtime
@@ -177,24 +180,6 @@ let publicConfigChainSchema = S.schema(s =>
 let svmEventDescriptorSchema = S.schema(s =>
   {
     "discriminator": s.matches(S.option(S.string)),
-    "discriminatorByteLen": s.matches(S.int),
-    // An array of AND-groups OR-ed together: the CLI normalizes both the flat
-    // and `any_of` YAML shapes to `Vec<Vec<SvmAccountFilterJson>>`.
-    "accountFilters": s.matches(
-      S.option(
-        S.array(
-          S.array(
-            S.schema(s =>
-              {
-                "position": s.matches(S.int),
-                "values": s.matches(S.array(S.string)),
-              }
-            ),
-          ),
-        ),
-      ),
-    ),
-    "isInner": s.matches(S.option(S.bool)),
     "accounts": s.matches(S.option(S.array(S.string))),
     "args": s.matches(S.option(S.json(~validate=false))),
   }
@@ -341,6 +326,7 @@ let getFieldTypeAndSchema = (prop, ~enumConfigsByName: dict<Table.enumConfig<Tab
 
   let (fieldType, baseSchema) = switch typ {
   | "string" => (Table.String, S.string->S.toUnknown)
+  | "bytes" => (Table.Bytea, Utils.Schema.bytes->S.toUnknown)
   | "boolean" => (Table.Boolean, S.bool->S.toUnknown)
   | "int" => (Table.Int32, S.int->S.toUnknown)
   | "bigint" => (Table.BigInt({precision: ?prop["precision"]}), Utils.BigInt.schema->S.toUnknown)
@@ -374,13 +360,13 @@ let getFieldTypeAndSchema = (prop, ~enumConfigsByName: dict<Table.enumConfig<Tab
   | other => JsError.throwWithMessage("Unknown field type in entity config: " ++ other)
   }
 
-  let fieldSchema = if isArray {
-    S.array(baseSchema)->S.toUnknown
-  } else {
-    baseSchema
+  let fieldSchema = switch (fieldType, isArray) {
+  | (Table.Bytea, true) => Utils.Schema.bytesArray->S.toUnknown
+  | (_, true) => S.array(baseSchema)->S.toUnknown
+  | (_, false) => baseSchema
   }
   let fieldSchema = if isNullable {
-    S.null(fieldSchema)->S.toUnknown
+    Utils.Schema.nullTolerant(fieldSchema)->S.toUnknown
   } else {
     fieldSchema
   }
@@ -563,6 +549,7 @@ let publicConfigSchema = S.schema(s =>
     "svm": s.matches(S.option(publicConfigEcosystemSchema)),
     "enums": s.matches(S.option(S.dict(S.array(S.string)))),
     "entities": s.matches(S.option(S.array(entityJsonSchema))),
+    "subgraph": s.matches(S.option(S.json(~validate=false))),
   }
 )
 
@@ -753,11 +740,6 @@ let fromPublic = (publicConfigJson: JSON.t) => {
               Utils.magic: _ => {
                 "svm": option<{
                   "discriminator": option<string>,
-                  "discriminatorByteLen": int,
-                  "accountFilters": option<
-                    array<array<{"position": int, "values": array<string>}>>,
-                  >,
-                  "isInner": option<bool>,
                   "accounts": option<array<string>>,
                   "args": option<JSON.t>,
                 }>,
@@ -770,25 +752,11 @@ let fromPublic = (publicConfigJson: JSON.t) => {
               `SVM instruction ${contractName}.${eventName} is missing the "svm" descriptor in internal config`,
             )
           }
-          let accountFilters =
-            svm["accountFilters"]
-            ->Option.getOr([])
-            ->Array.map(group =>
-              group->Array.map(
-                af => {
-                  Internal.position: af["position"],
-                  values: af["values"]->SvmTypes.Pubkey.fromStringsUnsafe,
-                },
-              )
-            )
           (EventConfigBuilder.buildSvmInstructionEventConfig(
             ~contractName,
             ~instructionName=eventName,
             ~programId,
             ~discriminator=svm["discriminator"],
-            ~discriminatorByteLen=svm["discriminatorByteLen"],
-            ~accountFilters,
-            ~isInner=svm["isInner"],
             ~accounts=svm["accounts"]->Option.getOr([]),
             ~args=svm["args"]->Option.getOr(JSON.Null),
             ~definedTypes=svmDefinedTypes,
@@ -1067,9 +1035,18 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     userEntitiesByName,
     userEntities,
     allEnums,
+    subgraph: publicConfig["subgraph"],
   }
 }
 
+// With no cross-chain entity, a reorg on one chain can never have changed a row
+// another chain owns, so its rollback stays isolated to that chain instead of
+// dragging every sibling back with it. A single chain has no sibling to spare,
+// and narrowing its rollback would only buy it a predicate that always holds.
+let isIsolatedMultichain = (config: t) =>
+  config.chainMap->ChainMap.keys->Array.length > 1 &&
+    config.userEntities->Array.every(entityConfig => !entityConfig.crossChain)
+
 // Canonicalize a user-provided address to the configured casing so it matches
 // addresses parsed from config.yaml during routing. HyperSync/RPC data arrives
 // already canonical; only user-land input (simulate srcAddress, contractRegister
@@ -1141,8 +1118,17 @@ let getEventConfig = (config: t, ~contractName, ~eventName, ~chainId: option<Cha
   })
 }
 
-let shouldSaveHistory = (config, ~isInReorgThreshold) =>
-  config.shouldSaveFullHistory || (config.shouldRollbackOnReorg && isInReorgThreshold)
+// A chain that can't be rolled back (maxReorgDepth = 0) has no history to keep,
+// unless a cross-chain entity lets another chain's rollback reach its rows.
+let shouldSaveHistory = (config, ~isInReorgThreshold, ~chainId: option<ChainId.t>=?) =>
+  config.shouldSaveFullHistory ||
+  (config.shouldRollbackOnReorg &&
+  isInReorgThreshold &&
+  switch chainId {
+  | Some(chainId) if config->isIsolatedMultichain =>
+    (config.chainMap->ChainMap.get(chainId)).maxReorgDepth > 0
+  | _ => true
+  })
 
 let shouldPruneHistory = (config, ~isInReorgThreshold) =>
   !config.shouldSaveFullHistory && (config.shouldRollbackOnReorg && isInReorgThreshold)
@@ -1203,6 +1189,10 @@ let stripSensitiveData = (json: JSON.t): JSON.t => {
       stripChains(obj->Dict.get("evm"))
       stripChains(obj->Dict.get("fuel"))
       stripChains(obj->Dict.get("svm"))
+      // The subgraph blob is how the runtime finds mappings. None of it
+      // describes stored data — that's already in `evm` / `entities` — so a
+      // specVersion bump or a mapping-path edit must not force a reset.
+      obj->Utils.Dict.deleteInPlace("subgraph")
     }
   | _ => ()
   }
@@ -1362,6 +1352,33 @@ let throwIfIncompatible = (
   }
 }
 
+let throwIfResumeIncompatible = (
+  ~storedEnvioInfo: option<JSON.t>,
+  ~storedContractMapping: ContractMapping.t,
+  ~envioInfo: JSON.t,
+  ~contractMapping: ContractMapping.t,
+  ~resetCommand: string,
+  ~runCommand: option<string>,
+) => {
+  let changedPaths = switch storedEnvioInfo {
+  | None => ["storage was initialized by an older envio version"]
+  | Some(stored) => diffPaths(~stored, ~current=envioInfo)
+  }
+  let changedPaths =
+    storedContractMapping->ContractMapping.isEqual(contractMapping)
+      ? changedPaths
+      : changedPaths->Array.concat(["contracts"])
+  let hasClickhouse = switch envioInfo {
+  | Object(d) =>
+    switch d->Dict.get("storage") {
+    | Some(Object(s)) => s->Dict.get("clickhouse") == Some(Boolean(true))
+    | _ => false
+    }
+  | _ => false
+  }
+  throwIfIncompatible(changedPaths, ~resetCommand, ~runCommand, ~hasClickhouse)
+}
+
 // The returned value is a pure function of the JSON: it holds only event
 // definitions, never handler/contractRegister/where state (that's layered on
 // separately as `HandlerRegister.registrationsByChainId`). That purity is