envio 3.0.2-svm-alpha.1 → 3.0.2-svm-alpha.2

package/src/ChainManager.res

@@ -1,7 +1,6 @@
 type t = {
   committedCheckpointId: bigint,
   chainFetchers: ChainMap.t<ChainFetcher.t>,
-  multichain: Config.multichain,
   isInReorgThreshold: bool,
   // True once every chain has caught up to head/endBlock. Monotonic during a run.
   isRealtime: bool,
@@ -35,6 +34,7 @@ let makeFromDbState = (
   ~initialState: Persistence.initialState,
   ~config: Config.t,
   ~registrations,
+  ~reducedPollingInterval=?,
 ): t => {
   let isInReorgThreshold = if initialState.cleanRun {
     false
@@ -81,6 +81,7 @@ let makeFromDbState = (
           ~targetBufferSize,
           ~config,
           ~registrations,
+          ~reducedPollingInterval?,
         ),
       )
     })
@@ -106,7 +107,6 @@ let makeFromDbState = (
 
   {
     committedCheckpointId: initialState.checkpointId,
-    multichain: config.multichain,
     chainFetchers,
     isInReorgThreshold,
     isRealtime,
@@ -128,11 +128,10 @@ let setChainFetcher = (chainManager: t, chainFetcher: ChainFetcher.t) => {
 }
 
 let nextItemIsNone = (chainManager: t): bool => {
-  !Batch.hasMultichainReadyItem(
+  !Batch.hasReadyItem(
     chainManager.chainFetchers->ChainMap.map(cf => {
       cf.fetchState
     }),
-    ~multichain=chainManager.multichain,
   )
 }
 
@@ -152,7 +151,6 @@ let createBatch = (chainManager: t, ~batchSizeTarget: int, ~isRollback: bool): B
       reorgDetection: cf.reorgDetection,
       chainConfig: cf.chainConfig,
     }),
-    ~multichain=chainManager.multichain,
     ~batchSizeTarget,
   )
 }

package/src/ChainManager.res.mjs

@@ -38,7 +38,7 @@ function calculateTargetBufferSize(activeChainsCount) {
   }
 }
 
-function makeFromDbState(initialState, config, registrations) {
+function makeFromDbState(initialState, config, registrations, reducedPollingInterval) {
   let isInReorgThreshold = initialState.cleanRun ? false : initialState.chains.some(chain => isProgressInReorgThreshold(chain.progressBlockNumber, chain.sourceBlockNumber, chain.maxReorgDepth));
   let targetBufferSize = calculateTargetBufferSize(initialState.chains.length);
   Prometheus.ProcessingMaxBatchSize.set(config.batchSize);
@@ -54,7 +54,7 @@ function makeFromDbState(initialState, config, registrations) {
     let chainConfig = ChainMap.get(config.chainMap, chain);
     return [
       chain,
-      ChainFetcher.makeFromDbState(chainConfig, resumedChainState, initialState.reorgCheckpoints, isInReorgThreshold, isRealtime, config, registrations, targetBufferSize)
+      ChainFetcher.makeFromDbState(chainConfig, resumedChainState, initialState.reorgCheckpoints, isInReorgThreshold, isRealtime, config, registrations, targetBufferSize, reducedPollingInterval)
     ];
   });
   let chainFetchers = ChainMap.fromArrayUnsafe(chainFetchersArr);
@@ -79,7 +79,6 @@ function makeFromDbState(initialState, config, registrations) {
   return {
     committedCheckpointId: initialState.checkpointId,
     chainFetchers: chainFetchers,
-    multichain: config.multichain,
     isInReorgThreshold: isInReorgThreshold,
     isRealtime: isRealtime
   };
@@ -93,14 +92,13 @@ function setChainFetcher(chainManager, chainFetcher) {
   return {
     committedCheckpointId: chainManager.committedCheckpointId,
     chainFetchers: ChainMap.set(chainManager.chainFetchers, ChainMap.Chain.makeUnsafe(chainFetcher.chainConfig.id), chainFetcher),
-    multichain: chainManager.multichain,
     isInReorgThreshold: chainManager.isInReorgThreshold,
     isRealtime: chainManager.isRealtime
   };
 }
 
 function nextItemIsNone(chainManager) {
-  return !Batch.hasMultichainReadyItem(ChainMap.map(chainManager.chainFetchers, cf => cf.fetchState), chainManager.multichain);
+  return !Batch.hasReadyItem(ChainMap.map(chainManager.chainFetchers, cf => cf.fetchState));
 }
 
 function createBatch(chainManager, batchSizeTarget, isRollback) {
@@ -113,7 +111,7 @@ function createBatch(chainManager, batchSizeTarget, isRollback) {
     sourceBlockNumber: cf.fetchState.knownHeight,
     totalEventsProcessed: cf.numEventsProcessed,
     chainConfig: cf.chainConfig
-  })), chainManager.multichain, batchSizeTarget);
+  })), batchSizeTarget);
 }
 
 function isProgressAtHead(chainManager) {

package/src/Config.res

@@ -15,8 +15,6 @@ type contract = {
   addresses: array<Address.t>,
   events: array<Internal.eventConfig>,
   startBlock: option<int>,
-  // EVM-specific: event sighashes for HyperSync queries
-  eventSignatures: array<string>,
 }
 
 // Sources are instantiated lazily in ChainFetcher from this config.
@@ -56,10 +54,6 @@ type sourceSync = {
   pollingInterval: int,
 }
 
-type multichain = Internal.multichain =
-  | @as("ordered") Ordered
-  | @as("unordered") Unordered
-
 type storage = {
   postgres: bool,
   clickhouse: bool,
@@ -78,7 +72,6 @@ type t = {
   shouldRollbackOnReorg: bool,
   shouldSaveFullHistory: bool,
   storage: storage,
-  multichain: multichain,
   chainMap: ChainMap.t<chain>,
   defaultChain: option<chain>,
   ecosystem: Ecosystem.t,
@@ -207,6 +200,7 @@ let svmEventDescriptorSchema = S.schema(s =>
     "discriminatorByteLen": s.matches(S.int),
     "includeTransaction": s.matches(S.bool),
     "includeLogs": s.matches(S.bool),
+    "includeTokenBalances": s.matches(S.bool),
     "accountFilters": s.matches(
       S.option(
         S.array(
@@ -235,10 +229,9 @@ let svmAbiSchema = S.schema(s =>
 
 let contractEventItemSchema = S.schema(s =>
   {
-    "event": s.matches(S.string),
     "name": s.matches(S.string),
     "sighash": s.matches(S.string),
-    "params": s.matches(S.option(S.array(EventConfigBuilder.eventParamSchema))),
+    "params": s.matches(S.option(S.array(EventConfigBuilder.paramMetaSchema))),
     "kind": s.matches(S.option(S.string)),
     "blockFields": s.matches(S.option(S.array(Internal.evmBlockFieldSchema))),
     "transactionFields": s.matches(S.option(S.array(Internal.evmTransactionFieldSchema))),
@@ -280,8 +273,6 @@ let publicConfigEvmSchema = S.schema(s =>
   }
 )
 
-let multichainSchema = S.enum([Ordered, Unordered])
-
 let compositeIndexFieldSchema = S.schema(s =>
   {
     "fieldName": s.matches(S.string),
@@ -294,6 +285,7 @@ let derivedFieldSchema = S.schema(s =>
     "fieldName": s.matches(S.string),
     "derivedFromEntity": s.matches(S.string),
     "derivedFromField": s.matches(S.string),
+    "description": s.matches(S.option(S.string)),
   }
 )
 
@@ -309,6 +301,7 @@ let propertySchema = S.schema(s =>
     "entity": s.matches(S.option(S.string)),
     "precision": s.matches(S.option(S.int)),
     "scale": s.matches(S.option(S.int)),
+    "description": s.matches(S.option(S.string)),
   }
 )
 
@@ -326,6 +319,7 @@ let entityJsonSchema = S.schema(s =>
     "properties": s.matches(S.array(propertySchema)),
     "derivedFields": s.matches(S.option(S.array(derivedFieldSchema))),
     "compositeIndices": s.matches(S.option(S.array(S.array(compositeIndexFieldSchema)))),
+    "description": s.matches(S.option(S.string)),
   }
 )
 
@@ -418,6 +412,7 @@ let parseEntitiesFromJson = (
         ~isArray,
         ~isIndex,
         ~linkedEntity=?prop["linkedEntity"],
+        ~description=?prop["description"],
       )
     })
 
@@ -429,6 +424,7 @@ let parseEntitiesFromJson = (
           df["fieldName"],
           ~derivedFromEntity=df["derivedFromEntity"],
           ~derivedFromField=df["derivedFromField"],
+          ~description=?df["description"],
         )
       )
 
@@ -448,6 +444,7 @@ let parseEntitiesFromJson = (
       entityName,
       ~fields=Array.concat(fields, derivedFields),
       ~compositeIndices,
+      ~description=?entityJson["description"],
     )
 
     // Build schema dynamically from properties
@@ -509,7 +506,6 @@ let publicConfigSchema = S.schema(s =>
     "description": s.matches(S.option(S.string)),
     "handlers": s.matches(S.option(S.string)),
     "isDev": s.matches(S.option(S.bool)),
-    "multichain": s.matches(S.option(multichainSchema)),
     "fullBatchSize": s.matches(S.option(S.int)),
     "rollbackOnReorg": s.matches(S.option(S.bool)),
     "saveFullHistory": s.matches(S.option(S.bool)),
@@ -592,7 +588,6 @@ let fromPublic = (publicConfigJson: JSON.t) => {
   | None => (Utils.Set.fromArray(EventConfigBuilder.alwaysIncludedBlockFields), Utils.Set.make())
   }
 
-  // Build contract data lookup: ABI, event signatures, event configs (keyed by capitalized name)
   let contractDataByName: dict<{
     "abi": EvmTypes.Abi.t,
     "eventSignatures": array<string>,
@@ -607,7 +602,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
       let capitalizedName = contractName->Utils.String.capitalize
       let abi = contractConfig["abi"]->(Utils.magic: JSON.t => EvmTypes.Abi.t)
       let eventSignatures = switch contractConfig["events"] {
-      | Some(events) => events->Array.map(eventItem => eventItem["event"])
+      | Some(events) => events->Array.map(eventItem => eventItem["sighash"])
       | None => []
       }
       let widened =
@@ -696,7 +691,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
                   "includeLogs": bool,
                   "includeTokenBalances": bool,
                   "accountFilters": option<
-                    array<{"position": int, "values": array<string>}>,
+                    array<array<{"position": int, "values": array<string>}>>,
                   >,
                   "isInner": option<bool>,
                   "accounts": option<array<string>>,
@@ -712,10 +707,12 @@ let fromPublic = (publicConfigJson: JSON.t) => {
             )
           }
           let accountFilters =
-            (svm["accountFilters"]->Option.getOr([]))->Array.map(af => {
-              Internal.position: af["position"],
-              values: af["values"]->SvmTypes.Pubkey.fromStringsUnsafe,
-            })
+            (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,
@@ -824,7 +821,6 @@ let fromPublic = (publicConfigJson: JSON.t) => {
             addresses,
             events,
             startBlock,
-            eventSignatures: contractData["eventSignatures"],
           }
         })
 
@@ -963,7 +959,6 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     shouldRollbackOnReorg: publicConfig["rollbackOnReorg"]->Option.getOr(true),
     shouldSaveFullHistory: publicConfig["saveFullHistory"]->Option.getOr(false),
     storage: globalStorage,
-    multichain: publicConfig["multichain"]->Option.getOr(Unordered),
     chainMap,
     defaultChain: chains->Array.get(0),
     enableRawEvents: publicConfig["rawEvents"]->Option.getOr(false),
@@ -1094,11 +1089,18 @@ let rec canonicalJson = (json: JSON.t): JSON.t =>
   }
 
 // Returns dotted leaf paths (`a.b[i].c`) where `stored` differs from
-// `current`. Skips subtrees whose canonical JSON matches.
+// `current`, restricted to the highest-priority top-level tier with any
+// diff. Tiers in order: version → name → storage → ecosystem
+// (evm/fuel/svm) → entities → other top-level keys. The first tier
+// containing a diff is the only one rendered; lower tiers are silenced
+// so a single noisy section doesn't bury the actionable change.
 let diffPaths = (~stored: JSON.t, ~current: JSON.t): array<string> => {
+  let canonEq = (a: JSON.t, b: JSON.t) =>
+    JSON.stringify(canonicalJson(a)) === JSON.stringify(canonicalJson(b))
+
   let acc = []
   let rec go = (s: JSON.t, c: JSON.t, prefix: string) => {
-    if JSON.stringify(canonicalJson(s)) === JSON.stringify(canonicalJson(c)) {
+    if canonEq(s, c) {
       ()
     } else {
       switch (s, c) {
@@ -1124,25 +1126,91 @@ let diffPaths = (~stored: JSON.t, ~current: JSON.t): array<string> => {
           | (Some(sv), Some(cv)) => go(sv, cv, p)
           }
         }
-      | _ =>
-        // Type mismatch or scalar diff
-        acc->Array.push(prefix === "" ? "<root>" : prefix)->ignore
+      | _ => acc->Array.push(prefix === "" ? "<root>" : prefix)->ignore
       }
     }
   }
-  go(stored, current, "")
+
+  let getTopKey = (j: JSON.t, k: string) =>
+    switch j {
+    | Object(d) => d->Dict.get(k)
+    | _ => None
+    }
+  let topKeyDiffers = (k: string) =>
+    switch (getTopKey(stored, k), getTopKey(current, k)) {
+    | (None, None) => false
+    | (None, _) | (_, None) => true
+    | (Some(s), Some(c)) => !canonEq(s, c)
+    }
+  let runTier = (keys: array<string>) =>
+    keys->Array.forEach(k =>
+      switch (getTopKey(stored, k), getTopKey(current, k)) {
+      | (None, None) => ()
+      | (None, _) | (_, None) => acc->Array.push(k)->ignore
+      | (Some(s), Some(c)) => go(s, c, k)
+      }
+    )
+
+  switch (stored, current) {
+  | (Object(sObj), Object(cObj)) =>
+    let tiers = [["version"], ["name"], ["storage"], ["evm", "fuel", "svm"], ["entities"]]
+    let firstHit = tiers->Array.reduce(None, (acc, tier) =>
+      switch acc {
+      | Some(_) => acc
+      | None =>
+        switch tier->Array.filter(topKeyDiffers) {
+        | [] => None
+        | hits => Some(hits)
+        }
+      }
+    )
+    switch firstHit {
+    | Some(hits) => runTier(hits)
+    | None =>
+      let knownSet = Utils.Set.fromArray(tiers->Belt.Array.concatMany)
+      let extras =
+        Utils.Set.fromArray(Array.concat(sObj->Dict.keysToArray, cObj->Dict.keysToArray))
+        ->Utils.Set.toArray
+        ->Array.filter(k => !(knownSet->Utils.Set.has(k)))
+        ->Array.toSorted(String.compare)
+        ->Array.filter(topKeyDiffers)
+      runTier(extras)
+    }
+  | _ => go(stored, current, "")
+  }
   acc
 }
 
 // Throws an `incompatible config` error listing each path in `changedPaths`,
-// plus the revert/reset remediation. `~resetCommand` lets each call site
-// (`envio dev -r` / `envio start -r` / `envio local db-migrate setup`)
-// surface the right wipe-and-restart command.
-let throwIfIncompatible = (changedPaths: array<string>, ~resetCommand: string) => {
+// plus the remediation options. `~resetCommand` is rendered as-is for
+// option 2 (the wipe-and-redo). `~runCommand` controls option 3 (parallel
+// indexer recipe): when `None`, option 3 is omitted — the migrate flow
+// uses this because running a second indexer doesn't apply.
+// `~hasClickhouse` adds the extra env line so users running both
+// Postgres and Clickhouse get a complete override.
+let throwIfIncompatible = (
+  changedPaths: array<string>,
+  ~resetCommand: string,
+  ~runCommand: option<string>,
+  ~hasClickhouse: bool,
+) => {
   if changedPaths->Array.length > 0 {
     let bullets = changedPaths->Array.map(p => `    - ${p}`)->Array.joinUnsafe("\n")
+    let option1 = "Revert the changes above"
+    let padTo = (s, col) => s ++ " "->String.repeat(Math.Int.max(col - String.length(s), 1))
+    let col = Math.Int.max(String.length(option1), String.length(resetCommand)) + 2
+    let option3 = switch runCommand {
+    | None => ""
+    | Some(cmd) =>
+      let clickhouseLine = hasClickhouse ? "       ENVIO_CLICKHOUSE_DATABASE=<new_db> \\\n" : ""
+      `\n  3. Run a second indexer alongside this one — keep both datasets:\n       ENVIO_PG_SCHEMA=<new_schema> \\\n${clickhouseLine}       ENVIO_INDEXER_PORT=<new_port> \\\n       ${cmd}`
+    }
     JsError.throwWithMessage(
-      `The following config changes are incompatible with the existing indexer data:\n\n${bullets}\n\nPick one:\n\n  1. Revert the changes above    # resume indexing where it left off\n  2. ${resetCommand}                # wipe the database and re-index from scratch`,
+      `The following config changes are incompatible with the existing indexer data:\n\n${bullets}\n\nPick one:\n  1. ${option1->padTo(
+          col,
+        )}# resume indexing where it left off\n  2. ${resetCommand->padTo(
+          col,
+        )}# delete all indexed data and start over${option3}`,
     )
   }
 }

package/src/Config.res.mjs

@@ -44,12 +44,12 @@ let schema = S$RescriptSchema.schema(s => ({
 let rowsSchema = S$RescriptSchema.array(schema);
 
 let table = Table.mkTable(name, undefined, [
-  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined),
-  Table.mkField("chain_id", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined)
-]);
+  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined),
+  Table.mkField("chain_id", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
+], undefined);
 
 let entityConfig_storage = {
   postgres: true,
@@ -118,6 +118,7 @@ let svmEventDescriptorSchema = S$RescriptSchema.schema(s => ({
   discriminatorByteLen: s.m(S$RescriptSchema.int),
   includeTransaction: s.m(S$RescriptSchema.bool),
   includeLogs: s.m(S$RescriptSchema.bool),
+  includeTokenBalances: s.m(S$RescriptSchema.bool),
   accountFilters: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.schema(s => ({
     position: s.m(S$RescriptSchema.int),
     values: s.m(S$RescriptSchema.array(S$RescriptSchema.string))
@@ -134,10 +135,9 @@ let svmAbiSchema = S$RescriptSchema.schema(s => ({
 }));
 
 let contractEventItemSchema = S$RescriptSchema.schema(s => ({
-  event: s.m(S$RescriptSchema.string),
   name: s.m(S$RescriptSchema.string),
   sighash: s.m(S$RescriptSchema.string),
-  params: s.m(S$RescriptSchema.option(S$RescriptSchema.array(EventConfigBuilder.eventParamSchema))),
+  params: s.m(S$RescriptSchema.option(S$RescriptSchema.array(EventConfigBuilder.paramMetaSchema))),
   kind: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   blockFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(Internal.evmBlockFieldSchema))),
   transactionFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(Internal.evmTransactionFieldSchema))),
@@ -168,11 +168,6 @@ let publicConfigEvmSchema = S$RescriptSchema.schema(s => ({
   globalTransactionFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(Internal.evmTransactionFieldSchema)))
 }));
 
-let multichainSchema = S$RescriptSchema.$$enum([
-  "ordered",
-  "unordered"
-]);
-
 let compositeIndexFieldSchema = S$RescriptSchema.schema(s => ({
   fieldName: s.m(S$RescriptSchema.string),
   direction: s.m(S$RescriptSchema.string)
@@ -181,7 +176,8 @@ let compositeIndexFieldSchema = S$RescriptSchema.schema(s => ({
 let derivedFieldSchema = S$RescriptSchema.schema(s => ({
   fieldName: s.m(S$RescriptSchema.string),
   derivedFromEntity: s.m(S$RescriptSchema.string),
-  derivedFromField: s.m(S$RescriptSchema.string)
+  derivedFromField: s.m(S$RescriptSchema.string),
+  description: s.m(S$RescriptSchema.option(S$RescriptSchema.string))
 }));
 
 let propertySchema = S$RescriptSchema.schema(s => ({
@@ -194,7 +190,8 @@ let propertySchema = S$RescriptSchema.schema(s => ({
   enum: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   entity: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   precision: s.m(S$RescriptSchema.option(S$RescriptSchema.int)),
-  scale: s.m(S$RescriptSchema.option(S$RescriptSchema.int))
+  scale: s.m(S$RescriptSchema.option(S$RescriptSchema.int)),
+  description: s.m(S$RescriptSchema.option(S$RescriptSchema.string))
 }));
 
 let entityStorageSchema = S$RescriptSchema.schema(s => ({
@@ -207,7 +204,8 @@ let entityJsonSchema = S$RescriptSchema.schema(s => ({
   storage: s.m(S$RescriptSchema.option(entityStorageSchema)),
   properties: s.m(S$RescriptSchema.array(propertySchema)),
   derivedFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(derivedFieldSchema))),
-  compositeIndices: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.array(compositeIndexFieldSchema))))
+  compositeIndices: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.array(compositeIndexFieldSchema)))),
+  description: s.m(S$RescriptSchema.option(S$RescriptSchema.string))
 }));
 
 function getFieldTypeAndSchema(prop, enumConfigsByName) {
@@ -325,14 +323,14 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
     let entityName = entityJson.name;
     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);
+      return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], prop.linkedEntity, prop.description);
     });
-    let derivedFields = Stdlib_Option.getOr(entityJson.derivedFields, []).map(df => Table.mkDerivedFromField(df.fieldName, df.derivedFromEntity, df.derivedFromField));
+    let derivedFields = Stdlib_Option.getOr(entityJson.derivedFields, []).map(df => Table.mkDerivedFromField(df.fieldName, df.derivedFromEntity, df.derivedFromField, df.description));
     let compositeIndices = Stdlib_Option.getOr(entityJson.compositeIndices, []).map(ci => ci.map(f => ({
       fieldName: f.fieldName,
       direction: f.direction === "Asc" ? "Asc" : "Desc"
     })));
-    let table = Table.mkTable(entityName, compositeIndices, fields.concat(derivedFields));
+    let table = Table.mkTable(entityName, compositeIndices, fields.concat(derivedFields), entityJson.description);
     let schema = S$RescriptSchema.schema(s => {
       let dict = {};
       entityJson.properties.forEach(prop => {
@@ -378,7 +376,6 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   description: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   handlers: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   isDev: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
-  multichain: s.m(S$RescriptSchema.option(multichainSchema)),
   fullBatchSize: s.m(S$RescriptSchema.option(S$RescriptSchema.int)),
   rollbackOnReorg: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   saveFullHistory: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
@@ -478,7 +475,7 @@ function fromPublic(publicConfigJson) {
       let capitalizedName = Utils.$$String.capitalize(param[0]);
       let abi = contractConfig.abi;
       let events = contractConfig.events;
-      let eventSignatures = events !== undefined ? events.map(eventItem => eventItem.event) : [];
+      let eventSignatures = events !== undefined ? events.map(eventItem => eventItem.sighash) : [];
       contractDataByName[capitalizedName] = {
         abi: abi,
         eventSignatures: eventSignatures,
@@ -511,10 +508,10 @@ function fromPublic(publicConfigJson) {
               ) : addresses[0];
             let s = eventItem.svm;
             let svm = s !== undefined ? Primitive_option.valFromOption(s) : Stdlib_JsError.throwWithMessage(`SVM instruction ` + contractName + `.` + eventName + ` is missing the "svm" descriptor in internal config`);
-            let accountFilters = Stdlib_Option.getOr(svm.accountFilters, []).map(af => ({
+            let accountFilters = Stdlib_Option.getOr(svm.accountFilters, []).map(group => group.map(af => ({
               position: af.position,
               values: af.values
-            }));
+            })));
             return EventConfigBuilder.buildSvmInstructionEventConfig(contractName, eventName, programId, svm.discriminator, svm.discriminatorByteLen, svm.includeTransaction, svm.includeLogs, svm.includeTokenBalances, accountFilters, svm.isInner, false, undefined, undefined, Stdlib_Option.getOr(svm.accounts, []), Stdlib_Option.getOr(svm.args, null), svmDefinedTypes, startBlock);
         }
       });
@@ -562,8 +559,7 @@ function fromPublic(publicConfigJson) {
         abi: contractData.abi,
         addresses: addresses,
         events: events,
-        startBlock: startBlock,
-        eventSignatures: contractData.eventSignatures
+        startBlock: startBlock
       };
     });
     let sourceConfig;
@@ -672,7 +668,6 @@ function fromPublic(publicConfigJson) {
     shouldRollbackOnReorg: Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true),
     shouldSaveFullHistory: Stdlib_Option.getOr(publicConfig.saveFullHistory, false),
     storage: globalStorage,
-    multichain: Stdlib_Option.getOr(publicConfig.multichain, "unordered"),
     chainMap: chainMap,
     defaultChain: chains[0],
     ecosystem: ecosystem,
@@ -818,9 +813,10 @@ function canonicalJson(json) {
 }
 
 function diffPaths(stored, current) {
+  let canonEq = (a, b) => JSON.stringify(canonicalJson(a)) === JSON.stringify(canonicalJson(b));
   let acc = [];
   let go = (s, c, prefix) => {
-    if (JSON.stringify(canonicalJson(s)) === JSON.stringify(canonicalJson(c))) {
+    if (canonEq(s, c)) {
       return;
     }
     if (Array.isArray(s)) {
@@ -868,16 +864,92 @@ function diffPaths(stored, current) {
     }
     acc.push(prefix === "" ? "<root>" : prefix);
   };
-  go(stored, current, "");
+  let getTopKey = (j, k) => {
+    if (typeof j === "object" && j !== null && !Array.isArray(j)) {
+      return j[k];
+    }
+  };
+  let topKeyDiffers = k => {
+    let match = getTopKey(stored, k);
+    let match$1 = getTopKey(current, k);
+    if (match !== undefined) {
+      if (match$1 !== undefined) {
+        return !canonEq(match, match$1);
+      } else {
+        return true;
+      }
+    } else {
+      return match$1 !== undefined;
+    }
+  };
+  let runTier = keys => {
+    keys.forEach(k => {
+      let match = getTopKey(stored, k);
+      let match$1 = getTopKey(current, k);
+      if (match !== undefined) {
+        if (match$1 !== undefined) {
+          return go(match, match$1, k);
+        } else {
+          acc.push(k);
+          return;
+        }
+      } else if (match$1 !== undefined) {
+        acc.push(k);
+        return;
+      } else {
+        return;
+      }
+    });
+  };
+  if (typeof stored === "object" && stored !== null && !Array.isArray(stored) && typeof current === "object" && current !== null && !Array.isArray(current)) {
+    let tiers = [
+      ["version"],
+      ["name"],
+      ["storage"],
+      [
+        "evm",
+        "fuel",
+        "svm"
+      ],
+      ["entities"]
+    ];
+    let firstHit = Stdlib_Array.reduce(tiers, undefined, (acc, tier) => {
+      if (acc !== undefined) {
+        return acc;
+      }
+      let hits = tier.filter(topKeyDiffers);
+      if (hits.length !== 0) {
+        return hits;
+      }
+    });
+    if (firstHit !== undefined) {
+      runTier(firstHit);
+    } else {
+      let knownSet = new Set(Belt_Array.concatMany(tiers));
+      runTier(Array.from(new Set(Object.keys(stored).concat(Object.keys(current)))).filter(k => !knownSet.has(k)).toSorted(Primitive_string.compare).filter(topKeyDiffers));
+    }
+  } else {
+    go(stored, current, "");
+  }
   return acc;
 }
 
-function throwIfIncompatible(changedPaths, resetCommand) {
+function throwIfIncompatible(changedPaths, resetCommand, runCommand, hasClickhouse) {
   if (changedPaths.length === 0) {
     return;
   }
   let bullets = changedPaths.map(p => `    - ` + p).join("\n");
-  Stdlib_JsError.throwWithMessage(`The following config changes are incompatible with the existing indexer data:\n\n` + bullets + `\n\nPick one:\n\n  1. Revert the changes above    # resume indexing where it left off\n  2. ` + resetCommand + `                # wipe the database and re-index from scratch`);
+  let option1 = "Revert the changes above";
+  let padTo = (s, col) => s + " ".repeat(Math.max(col - s.length | 0, 1));
+  let col = Math.max(option1.length, resetCommand.length) + 2 | 0;
+  let option3;
+  if (runCommand !== undefined) {
+    let clickhouseLine = hasClickhouse ? "       ENVIO_CLICKHOUSE_DATABASE=<new_db> \\\n" : "";
+    option3 = `\n  3. Run a second indexer alongside this one — keep both datasets:\n       ENVIO_PG_SCHEMA=<new_schema> \\\n` + clickhouseLine + `       ENVIO_INDEXER_PORT=<new_port> \\\n       ` + runCommand;
+  } else {
+    option3 = "";
+  }
+  Stdlib_JsError.throwWithMessage(`The following config changes are incompatible with the existing indexer data:\n\n` + bullets + `\n\nPick one:\n  1. ` + padTo(option1, col) + `# resume indexing where it left off\n  2. ` + padTo(resetCommand, col) + `# delete all indexed data and start over` + option3);
 }
 
 function loadWithoutRegistrations() {
@@ -906,7 +978,6 @@ export {
   contractConfigSchema,
   publicConfigEcosystemSchema,
   publicConfigEvmSchema,
-  multichainSchema,
   compositeIndexFieldSchema,
   derivedFieldSchema,
   propertySchema,

package/src/Core.res

@@ -1,13 +1,9 @@
 // Resolution order:
-//   1. Production: require("envio-{os}-{arch}") — platform-specific npm package
-//   2. Dev build:  find repo → cargo build --lib → load from target/debug/
+//   1. Production: require("envio-{os}-{arch}") - platform-specific npm package
+//   2. Dev build:  find repo -> cargo build --lib -> load from target/debug/
 
 // NAPI encodes Rust `Option<T>` as `null | T` (never `undefined`), so the
 // tighter `Null.t` captures the exact boundary shape.
-//
-// Opaque carriers for the NAPI class constructors. Static factories
-// (`newWithAgent`, `fromConfig`, `fromSignatures`) hang off these via `@send`
-// in `HyperSyncClient.res` / `HyperSyncSolanaClient.res`.
 type hypersyncClientCtor
 type hypersyncSolanaClientCtor
 type decoderCtor
@@ -147,8 +143,8 @@ let loadAddon = () => {
   }
 
   // Only swallow MODULE_NOT_FOUND (the optional package isn't installed on
-  // this host). Any other failure — corrupt .node, ABI mismatch, dlopen
-  // error — is a real load failure and must surface.
+  // this host). Any other failure - corrupt .node, ABI mismatch, dlopen
+  // error - is a real load failure and must surface.
   let rec tryRequire = i =>
     switch candidates[i] {
     | None => None