envio 3.13.0 → 3.14.0

package/bin.mjs

@@ -1,3 +1,12 @@
 #!/usr/bin/env node
-import { run } from "./src/Bin.res.mjs";
+import { unsupportedNodeMessage } from "./src/NodeVersion.mjs";
+
+// Checked before the rest loads, which an older Node may not even parse.
+const unsupported = unsupportedNodeMessage();
+if (unsupported !== undefined) {
+  console.error(unsupported);
+  process.exit(1);
+}
+
+const { run } = await import("./src/Bin.res.mjs");
 await run(process.argv.slice(2));

package/index.d.ts

@@ -12,6 +12,17 @@ declare const bigintSchema: Sury.Schema<bigint>;
 /** Ethereum address — a 20-byte hex string prefixed with `0x`. */
 export type Address = `0x${string}`;
 
+/** A value a `Json` entity field can hold. A `bigint` isn't JSON — store its
+ * decimal string with `.toString()`. Shadows the global `JSON` interface only
+ * where imported; the `JSON` object itself is unaffected. */
+export type JSON =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JSON[]
+  | { readonly [key: string]: JSON };
+
 /** Structured logger bound to an event or handler context. Messages are
  * displayed in the console and the Envio Hosted Service. */
 export type Logger = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -27,7 +27,7 @@
     "dapp"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.15.0"
   },
   "files": [
     "bin.mjs",
@@ -42,11 +42,6 @@
   ],
   "dependencies": {
     "@elastic/ecs-pino-format": "1.4.0",
-    "@fuel-ts/crypto": "0.96.1",
-    "@fuel-ts/errors": "0.96.1",
-    "@fuel-ts/hasher": "0.96.1",
-    "@fuel-ts/math": "0.96.1",
-    "@fuel-ts/utils": "0.96.1",
     "bignumber.js": "9.3.1",
     "eventsource": "4.1.0",
     "express": "4.19.2",
@@ -56,20 +51,13 @@
     "rescript-schema": "9.5.1",
     "viem": "2.54.0",
     "dotenv": "16.4.5",
-    "date-fns": "3.3.1",
-    "@rescript/react": "0.14.1",
-    "react": "19.2.5",
-    "ink": "6.8.0",
-    "ink-big-text": "2.0.0",
-    "ink-spinner": "5.0.0",
-    "postgres": "3.4.8",
-    "tsx": "4.21.0"
+    "postgres": "3.4.8"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.13.0",
-    "envio-linux-x64-musl": "3.13.0",
-    "envio-linux-arm64": "3.13.0",
-    "envio-darwin-x64": "3.13.0",
-    "envio-darwin-arm64": "3.13.0"
+    "envio-linux-x64": "3.14.0",
+    "envio-linux-x64-musl": "3.14.0",
+    "envio-linux-arm64": "3.14.0",
+    "envio-darwin-x64": "3.14.0",
+    "envio-darwin-arm64": "3.14.0"
   }
 }

package/rescript.json

@@ -12,10 +12,7 @@
     "module": "esmodule",
     "in-source": true
   },
-  "jsx": {
-    "version": 4
-  },
-  "dependencies": ["rescript-schema", "@rescript/react"],
+  "dependencies": ["rescript-schema"],
   "compiler-flags": ["-open RescriptSchema"],
   "warnings": {
     "error": "+a"

package/src/Config.res

@@ -136,6 +136,9 @@ type t = {
   reorgThresholdReadyTolerance: int,
   lowercaseAddresses: bool,
   isDev: bool,
+  // The operator's `-d` / `--config` flags, repeated in every command printed
+  // for them to run next. Empty when they gave neither.
+  projectFlags: string,
   // An `envio start --chain` process: drives a subset of the schema's chains
   // while sibling processes drive the rest, so it only touches what its own
   // chains own — their partitions' indexes, their `ready_at`, their resume.
@@ -147,6 +150,7 @@ type t = {
   // the schema alone: a cross-chain entity has rows any chain's reorg can
   // reach, so its checkpoints have to be comparable across chains.
   checkpointSequence: CheckpointSequence.t,
+  envioInfo: JSON.t,
 }
 
 type rpcSourceFor = | @as("sync") Sync | @as("fallback") Fallback | @as("realtime") Realtime
@@ -595,6 +599,7 @@ let publicConfigSchema = S.schema(s =>
     "handlers": s.matches(S.option(S.string)),
     "isDev": s.matches(S.option(S.bool)),
     "isolatedChains": s.matches(S.option(S.array(ChainId.schema))),
+    "projectFlags": s.matches(S.option(S.string)),
     "fullBatchSize": s.matches(S.option(S.int)),
     "rollbackOnReorg": s.matches(S.option(S.bool)),
     "saveFullHistory": s.matches(S.option(S.bool)),
@@ -666,6 +671,41 @@ let isolate = (config: t, ~chainIds: array<ChainId.t>) => {
   }
 }
 
+// What the command decided rather than the project's files: `envio dev` vs
+// `envio start`, which chains this process drives, and how it found the
+// project.
+let commandFields = ["isDev", "isolatedChains", "projectFlags"]
+
+let withProjectFlags = (command, ~config: t) =>
+  switch config.projectFlags {
+  | "" => command
+  | flags => `${command} ${flags}`
+  }
+
+let ecosystemFields = ["evm", "fuel", "svm"]
+
+// What `envio_info` records: the public config without the command's fields
+// or its chains. A chain is recorded by its own `envio_chains` row and its
+// config's `envio_addresses` rows instead, so adding one never rewrites this
+// record. The rest of a chain's config — its sources, its block lag, a
+// contract's start block — is read from config.yaml on every start.
+let toEnvioInfo = (publicConfigJson: JSON.t): JSON.t => {
+  let envioInfo = publicConfigJson->JSON.stringify->JSON.parseOrThrow
+  switch envioInfo {
+  | Object(obj) => {
+      commandFields->Array.forEach(field => obj->Utils.Dict.deleteInPlace(field))
+      ecosystemFields->Array.forEach(ecosystem =>
+        switch obj->Dict.get(ecosystem) {
+        | Some(Object(ecosystemDict)) => ecosystemDict->Utils.Dict.deleteInPlace("chains")
+        | _ => ()
+        }
+      )
+    }
+  | _ => ()
+  }
+  envioInfo
+}
+
 let fromPublic = (publicConfigJson: JSON.t) => {
   let maxAddrInPartition = Env.maxAddrInPartition
   // Parse public config
@@ -1136,11 +1176,13 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     reorgThresholdReadyTolerance: 100,
     lowercaseAddresses,
     isDev: publicConfig["isDev"]->Option.getOr(false),
+    projectFlags: publicConfig["projectFlags"]->Option.getOr(""),
     isolated: false,
     userEntitiesByName,
     userEntities,
     allEnums,
     checkpointSequence: CheckpointSequence.fromEntities(userEntities),
+    envioInfo: publicConfigJson->toEnvioInfo,
   }
 
   switch publicConfig["isolatedChains"] {
@@ -1255,49 +1297,6 @@ let getPublicConfigJson = () =>
   | None => Core.getConfigJson()->JSON.parseOrThrow
   }
 
-// Drops source URLs from each chain so RPC/hypersync edits don't trigger
-// the resume-time compat check (and don't end up in `envio_info`). Also
-// drops `isDev`, which toggles between `envio dev` and `envio start` and
-// has no bearing on schema/indexing compatibility.
-let stripSensitiveData = (json: JSON.t): JSON.t => {
-  let cloned = json->JSON.stringify->JSON.parseOrThrow
-  let stripChains = (ecosystem: option<JSON.t>) =>
-    switch ecosystem {
-    | Some(Object(ecosystemDict)) =>
-      switch ecosystemDict->Dict.get("chains") {
-      | Some(Object(chains)) =>
-        chains
-        ->Dict.valuesToArray
-        ->Array.forEach(chainJson =>
-          switch chainJson {
-          | Object(chain) => {
-              chain->Utils.Dict.deleteInPlace("rpcs")
-              chain->Utils.Dict.deleteInPlace("hypersync")
-            }
-          | _ => ()
-          }
-        )
-      | _ => ()
-      }
-    | _ => ()
-    }
-  switch cloned {
-  | Object(obj) => {
-      obj->Utils.Dict.deleteInPlace("isDev")
-      obj->Utils.Dict.deleteInPlace("isolatedChains")
-      stripChains(obj->Dict.get("evm"))
-      stripChains(obj->Dict.get("fuel"))
-      stripChains(obj->Dict.get("svm"))
-    }
-  | _ => ()
-  }
-  cloned
-}
-
-// What the storage layer records as the config this schema was built from,
-// and checks a resuming run against.
-let envioInfo = () => getPublicConfigJson()->stripSensitiveData
-
 // Postgres jsonb doesn't preserve key order, so canonicalize with sorted
 // keys before string-comparing.
 let rec canonicalJson = (json: JSON.t): JSON.t =>
@@ -1317,9 +1316,10 @@ let rec canonicalJson = (json: JSON.t): JSON.t =>
 // Returns dotted leaf paths (`a.b[i].c`) where `stored` differs from
 // `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.
+// (evm/fuel/svm, and the chains a resume puts beside them) → 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))
@@ -1387,7 +1387,7 @@ let diffPaths = (~stored: JSON.t, ~current: JSON.t): array<string> => {
       ["chainIdMode"],
       ["name"],
       ["storage"],
-      ["evm", "fuel", "svm"],
+      ["evm", "fuel", "svm", "chains"],
       ["entities"],
     ]
     let firstHit = tiers->Array.reduce(None, (acc, tier) =>
@@ -1417,65 +1417,34 @@ let diffPaths = (~stored: JSON.t, ~current: JSON.t): array<string> => {
   acc
 }
 
-// Throws an `incompatible config` error listing each path in `changedPaths`,
-// 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 = (
+// The `incompatible config` error listing each path in `changedPaths`, 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 incompatibleMessage = (
   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  1. ${option1->padTo(
-          col,
-        )}# resume indexing where it left off\n  2. ${resetCommand->padTo(
-          col,
-        )}# delete all indexed data and start over${option3}`,
-    )
-  }
-}
-
-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
+  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}`
   }
-  throwIfIncompatible(changedPaths, ~resetCommand, ~runCommand, ~hasClickhouse)
+  `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}`
 }
 
 // The returned value is a pure function of the JSON: it holds only event

package/src/Config.res.mjs

@@ -18,7 +18,6 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.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 ContractMapping from "./ContractMapping.res.mjs";
-import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
@@ -439,6 +438,7 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   handlers: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   isDev: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   isolatedChains: s.m(S$RescriptSchema.option(S$RescriptSchema.array(ChainId.schema))),
+  projectFlags: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   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)),
@@ -495,6 +495,41 @@ function isolate(config, chainIds) {
   return newrecord;
 }
 
+let commandFields = [
+  "isDev",
+  "isolatedChains",
+  "projectFlags"
+];
+
+function withProjectFlags(command, config) {
+  let flags = config.projectFlags;
+  if (flags === "") {
+    return command;
+  } else {
+    return command + ` ` + flags;
+  }
+}
+
+let ecosystemFields = [
+  "evm",
+  "fuel",
+  "svm"
+];
+
+function toEnvioInfo(publicConfigJson) {
+  let envioInfo = JSON.parse(JSON.stringify(publicConfigJson));
+  if (typeof envioInfo === "object" && envioInfo !== null && !Array.isArray(envioInfo)) {
+    commandFields.forEach(field => Utils.Dict.deleteInPlace(envioInfo, field));
+    ecosystemFields.forEach(ecosystem => {
+      let match = envioInfo[ecosystem];
+      if (typeof match === "object" && match !== null && !Array.isArray(match)) {
+        return Utils.Dict.deleteInPlace(match, "chains");
+      }
+    });
+  }
+  return envioInfo;
+}
+
 function fromPublic(publicConfigJson) {
   let publicConfig;
   try {
@@ -801,7 +836,9 @@ function fromPublic(publicConfigJson) {
   let config_enableRawEvents = Stdlib_Option.getOr(publicConfig.rawEvents, false);
   let config_batchSize = Stdlib_Option.getOr(publicConfig.fullBatchSize, 5000);
   let config_isDev = Stdlib_Option.getOr(publicConfig.isDev, false);
+  let config_projectFlags = Stdlib_Option.getOr(publicConfig.projectFlags, "");
   let config_checkpointSequence = CheckpointSequence.fromEntities(userEntities);
+  let config_envioInfo = toEnvioInfo(publicConfigJson);
   let config = {
     name: config_name,
     description: config_description,
@@ -823,11 +860,13 @@ function fromPublic(publicConfigJson) {
     reorgThresholdReadyTolerance: 100,
     lowercaseAddresses: lowercaseAddresses,
     isDev: config_isDev,
+    projectFlags: config_projectFlags,
     isolated: false,
     userEntitiesByName: userEntitiesByName,
     userEntities: userEntities,
     allEnums: allEnums,
-    checkpointSequence: config_checkpointSequence
+    checkpointSequence: config_checkpointSequence,
+    envioInfo: config_envioInfo
   };
   let chainIds = publicConfig.isolatedChains;
   if (chainIds !== undefined) {
@@ -933,44 +972,6 @@ function getPublicConfigJson() {
   }
 }
 
-function stripSensitiveData(json) {
-  let cloned = JSON.parse(JSON.stringify(json));
-  let stripChains = ecosystem => {
-    if (ecosystem === undefined) {
-      return;
-    }
-    if (typeof ecosystem !== "object" || ecosystem === null || Array.isArray(ecosystem)) {
-      return;
-    }
-    let match = ecosystem["chains"];
-    if (match === undefined) {
-      return;
-    }
-    if (typeof match !== "object" || match === null || Array.isArray(match)) {
-      return;
-    }
-    Object.values(match).forEach(chainJson => {
-      if (typeof chainJson !== "object" || chainJson === null || Array.isArray(chainJson)) {
-        return;
-      }
-      Utils.Dict.deleteInPlace(chainJson, "rpcs");
-      Utils.Dict.deleteInPlace(chainJson, "hypersync");
-    });
-  };
-  if (typeof cloned === "object" && cloned !== null && !Array.isArray(cloned)) {
-    Utils.Dict.deleteInPlace(cloned, "isDev");
-    Utils.Dict.deleteInPlace(cloned, "isolatedChains");
-    stripChains(cloned["evm"]);
-    stripChains(cloned["fuel"]);
-    stripChains(cloned["svm"]);
-  }
-  return cloned;
-}
-
-function envioInfo() {
-  return stripSensitiveData(getPublicConfigJson());
-}
-
 function canonicalJson(json) {
   if (Array.isArray(json)) {
     return json.map(canonicalJson);
@@ -1088,7 +1089,8 @@ function diffPaths(stored, current) {
       [
         "evm",
         "fuel",
-        "svm"
+        "svm",
+        "chains"
       ],
       ["entities"]
     ];
@@ -1113,10 +1115,7 @@ function diffPaths(stored, current) {
   return acc;
 }
 
-function throwIfIncompatible(changedPaths, resetCommand, runCommand, hasClickhouse) {
-  if (changedPaths.length === 0) {
-    return;
-  }
+function incompatibleMessage(changedPaths, resetCommand, runCommand, hasClickhouse) {
   let bullets = changedPaths.map(p => `    - ` + p).join("\n");
   let option1 = "Revert the changes above";
   let padTo = (s, col) => s + " ".repeat(Math.max(col - s.length | 0, 1));
@@ -1128,20 +1127,7 @@ function throwIfIncompatible(changedPaths, resetCommand, runCommand, hasClickhou
   } 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 throwIfResumeIncompatible(storedEnvioInfo, storedContractMapping, envioInfo, contractMapping, resetCommand, runCommand) {
-  let changedPaths = storedEnvioInfo !== undefined ? diffPaths(storedEnvioInfo, envioInfo) : ["storage was initialized by an older envio version"];
-  let changedPaths$1 = ContractMapping.isEqual(storedContractMapping, contractMapping) ? changedPaths : changedPaths.concat(["contracts"]);
-  let hasClickhouse;
-  if (typeof envioInfo === "object" && envioInfo !== null && !Array.isArray(envioInfo)) {
-    let match = envioInfo["storage"];
-    hasClickhouse = typeof match === "object" && match !== null && !Array.isArray(match) ? Primitive_object.equal(match["clickhouse"], true) : false;
-  } else {
-    hasClickhouse = false;
-  }
-  throwIfIncompatible(changedPaths$1, resetCommand, runCommand, hasClickhouse);
+  return `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 load() {
@@ -1195,6 +1181,10 @@ export {
   getChain,
   isPerChain,
   isolate,
+  commandFields,
+  withProjectFlags,
+  ecosystemFields,
+  toEnvioInfo,
   fromPublic,
   normalizeUserAddress,
   normalizeSimulateAddress,
@@ -1202,12 +1192,9 @@ export {
   prime,
   withCommandFields,
   getPublicConfigJson,
-  stripSensitiveData,
-  envioInfo,
   canonicalJson,
   diffPaths,
-  throwIfIncompatible,
-  throwIfResumeIncompatible,
+  incompatibleMessage,
   load,
   getPgUserEntities,
 }

package/src/Core.res

@@ -12,6 +12,7 @@ type transactionStoreCtor
 type blockStoreCtor
 type clickHouseSinkCtor
 type addressStoreCtor
+type tuiCtor
 // Test-only: a local HyperSync server, bound by MockHyperSyncServer in envio-tests.
 type mockHyperSyncServerCtor
 type fromUserApiOptions = {
@@ -33,6 +34,10 @@ type addon = {
   isSvmPubkey: (~value: string) => bool,
   fromUserApi: (string, fromUserApiOptions) => fromUserApiResult,
   runCli: (~args: array<string>, ~envioPackageDir: Null.t<string>) => promise<Null.t<string>>,
+  loadTs: string => string,
+  tsCheckHandlerFormat: string => unit,
+  tsResolveCandidates: (string, Null.t<string>) => array<string>,
+  tsNotFoundCandidates: (string, Null.t<string>, string) => array<string>,
   @as("EvmHyperSyncClient")
   evmHyperSyncClient: evmHyperSyncClientCtor,
   @as("EvmRpcClient")
@@ -49,6 +54,8 @@ type addon = {
   addressStore: addressStoreCtor,
   @as("ClickHouseSink")
   clickHouseSink: clickHouseSinkCtor,
+  @as("Tui")
+  tui: tuiCtor,
   @as("MockHyperSyncServer")
   mockHyperSyncServer: mockHyperSyncServerCtor,
   encodeAddresses: (~ecosystem: string, ~addresses: array<Address.t>) => array<NodeJs.Buffer.t>,
@@ -99,7 +106,7 @@ let callRequire: ({..}, string) => addon = %raw(`(req, id) => req(id)`)
 let envioPackageDir = pathDirname(pathDirname(fileURLToPath(importMetaUrl)))
 
 // Runs `cargo build` on every invocation (like `cargo run`).
-let loadDevAddon: ({..}, string) => addon = %raw(`function(req, envioDir) {
+let loadDevAddon: ({..}, string) => Null.t<addon> = %raw(`function(req, envioDir) {
   var cp = Nodechild_process;
   var path = Nodepath;
   var fs = Nodefs;
@@ -177,6 +184,22 @@ let loadDevAddon: ({..}, string) => addon = %raw(`function(req, envioDir) {
 // `code`, and any other fields a diagnostic might rely on.
 let rethrow: JsExn.t => 'a = %raw(`function(e) { throw e }`)
 
+type packageJson = {version: string}
+let requirePackageJson: ({..}, string) => packageJson = %raw(`(req, p) => req(p)`)
+let devVersion = "0.0.1-dev"
+
+let isGlibc: unit => bool = %raw(`() => Boolean(process.report?.getReport().header.glibcVersionRuntime)`)
+
+@val external npmUserAgent: option<string> = "process.env.npm_config_user_agent"
+
+let addCommand = () =>
+  switch npmUserAgent {
+  | Some(ua) if ua->String.startsWith("pnpm/") => "pnpm add"
+  | Some(ua) if ua->String.startsWith("yarn/") => "yarn add"
+  | Some(ua) if ua->String.startsWith("bun/") => "bun add"
+  | _ => "npm install"
+  }
+
 let loadAddon = () => {
   let req = createRequire(importMetaUrl)
 
@@ -212,15 +235,32 @@ let loadAddon = () => {
   switch tryRequire(0) {
   | Some(addon) => addon
   | None =>
-    // Dev build fallback (cargo build on every run)
-    switch loadDevAddon(req, envioPackageDir)->(Utils.magic: addon => option<addon>) {
+    let version = requirePackageJson(req, "../package.json").version
+    // Publishing stamps the real version, so only a monorepo checkout (or a
+    // `file:` link to one) can have a dev build to fall back to. Skipping it
+    // spares published installs a `pnpm list` spawn before the error below.
+    let devAddon = if version === devVersion {
+      loadDevAddon(req, envioPackageDir)->Null.toOption
+    } else {
+      None
+    }
+    switch devAddon {
     | Some(addon) => addon
     | None =>
       let host = `${processPlatform}-${processArch}`
-      let msg = if candidates->Array.length === 0 {
+      let msg = switch candidates {
+      | []
+        if processPlatform === "win32" => `envio doesn't run natively on Windows. Use WSL 2 instead: https://learn.microsoft.com/windows/wsl/install`
+      | [] =>
         `envio doesn't support ${host}. Supported: linux-x64 (glibc/musl), linux-arm64, darwin-x64, darwin-arm64.`
-      } else {
-        `Couldn't load the envio native addon for ${host}. Reinstall envio (ensure optional dependencies aren't skipped).`
+      | _ =>
+        let pkg = if processPlatform === "linux" && processArch === "x64" && !isGlibc() {
+          `envio-linux-x64-musl`
+        } else {
+          candidates->Array.getUnsafe(0)
+        }
+        `envio's native binary for ${host} isn't installed (package "${pkg}"). This happens when optional dependencies are skipped (--omit=optional, --no-optional) or the lockfile was generated on another platform.
+Reinstall dependencies, or add the package explicitly: ${addCommand()} ${pkg}@${version}`
       }
       JsError.throwWithMessage(msg)
     }